输出格式

codescan 支持三种输出格式，根据 stdout 是否为终端自动选择。

Pretty（交互模式默认）

受 Cargo 启发的人类可读输出，带颜色和源码上下文：

error[SECRET001]: Hardcoded password
  --> src/config.py:14:12
   |
14 |   password = "hunter2"
   |              ^^^^^^^^^
   = help: Use environment variables or a secrets manager instead

warning[CRYPTO001]: Weak hashing algorithm
  --> src/auth.py:8:5
   |
 8 |   hashlib.md5(data).hexdigest()
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   = help: Use SHA-256 or better

found 1 error, 1 warning, 0 notes

颜色编码：

• error[...] — 红色加粗
• warning[...] — 黄色加粗
• info[...] — 青色加粗
• 位置箭头（-->、|）— 蓝色加粗
• 插入符号下划线 — 红色
• = suppressed:（使用 --show-suppressed 时）— 变暗

强制在管道中使用 pretty 输出：

codescan --format pretty --interactive true . | less -R

Text（非交互模式默认）

冒号分隔的纯文本，每行一个发现。易于 grep、awk 或在 CI 脚本中解析：

src/config.py:14:12:error:SECRET001:Hardcoded password
src/auth.py:8:5:warning:CRYPTO001:Weak hashing algorithm
# errors=1 warnings=1 infos=0

格式：路径:行:列:严重性:规则ID:消息

使用 --quiet 时省略汇总行（以 # 开头）。

# 仅提取错误行
codescan --format text . | grep '^[^#].*:error:'

# 按规则统计发现数量
codescan --format text -q . | awk -F: '{print $5}' | sort | uniq -c | sort -rn

JSON

换行分隔的 JSON（NDJSON），每行一个发现对象。适合下游处理、仪表盘和工具集成：

{"path":"src/config.py","line":14,"col":12,"end_col":21,"severity":"error","rule_id":"SECRET001","category":"SECRET","message":"Hardcoded password","snippet":"  password = \"hunter2\"","help":"Use environment variables or a secrets manager instead","suppressed_by":null}
{"path":"src/auth.py","line":8,"col":5,"end_col":36,"severity":"warning","rule_id":"CRYPTO001","category":"CRYPTO","message":"Weak hashing algorithm","snippet":"  hashlib.md5(data).hexdigest()","help":"Use SHA-256 or better","suppressed_by":null}

汇总对象写入 stderr：

{"summary":{"errors":1,"warnings":1,"infos":0}}

JSON 字段说明

字段	类型	描述
path	string	相对文件路径
line	number	1-based 行号
col	number	1-based 列号
end_col	number	结束列（不含）
severity	"error" | "warning" | "info"	严重性级别
rule_id	string	规则标识符
category	string	规则类别
message	string	发现描述
snippet	string	源代码行文本
help	string | null	修复建议
suppressed_by	string | null	抑制原因（活跃时为 null）

处理 JSON 输出

# 仅过滤错误
codescan --format json . | jq 'select(.severity == "error")'

# 按规则分组
codescan --format json -q . | jq -s 'group_by(.rule_id) | map({rule: .[0].rule_id, count: length})'

# 导出为 CSV
codescan --format json -q . | jq -r '[.path, .line, .severity, .rule_id, .message] | @csv'

写入文件

codescan --output findings.txt --format text .
codescan --output findings.jsonl --format json .

静默模式

抑制汇总行：

codescan --quiet .
codescan -q --format json .  # 同时抑制 stderr 汇总

显示被抑制的发现

被抑制的发现默认隐藏。使用以下命令显示：

codescan --show-suppressed .

在 pretty 格式中，被抑制的发现会显示额外一行：

  = suppressed: inline codescan:ignore