logdigest

logdigest

将日志文件浓缩为失败证据。

CI 或测试日志可能长达一万行，但人们真正会阅读的部分只有少数几个失败片段：失败的测试、错误行、堆栈、非零退出。logdigest 会读取日志文件，找出这些行，按片段分组并保留原始行号，然后打印一份一屏即可读完的摘要。找到任何失败片段时，它会报告判定结果 FAILURES-FOUND；未找到时则报告 NO-FAILURES。

安装

npx @reneturcios/logdigest digest build.log

也可以全局安装：

npm install -g @reneturcios/logdigest

需要 Node 20 或更高版本。

CLI

logdigest digest [file] [--json]
logdigest mcp
logdigest --version

• logdigest digest <file> 打印易读的摘要。
• logdigest digest <file> --json 以 JSON 格式打印完整报告。
• logdigest mcp 通过 stdio 运行 MCP 服务（见下文）。
• logdigest --version 打印版本。

退出代码：判定结果为 NO-FAILURES 时返回 0，判定结果为 FAILURES-FOUND 时返回 1，发生用法错误或读取错误时返回 2（例如， 目标是目录或无法读取），读取器提前关闭输出管道时返回 141。

摘要示例：

logdigest digest test.log: FAILURES-FOUND
  2 failure section(s) found in 28 line(s): 9 matched line(s).
  [HIGH] TEST-FAIL lines 5-16
FAIL src/math.test.ts
    AssertionError: expected 3 to be 4
        at Object.<anonymous> (src/math.test.ts:10:11)
  totals: total lines 28, matched lines 9, sections 2, overflow sections 0
  by rule: TEST-FAIL 8, ERROR-LINE 1, EXIT-NONZERO 0

（以上示例经过了缩短；实际摘要会打印每个片段中捕获的所有 行。）

MCP

同一个二进制文件也是一个 MCP 服务：

npx @reneturcios/logdigest mcp

它提供一个工具：

• digest_log，带有一个 path 参数（要检查的日志文件）。它 返回与 CLI --json 输出相同的报告。

检测内容

检测基于模式。每个匹配行只会分配给一条规则；当一行匹配多种模式时，优先采用最具体的规则（TEST-FAIL 优先于 EXIT-NONZERO，EXIT-NONZERO 优先于 ERROR-LINE）。

规则	模式	说明
TEST-FAIL	FAIL 、单词 failing（例如运行器摘要中的 2 failing）、✕、× 、not ok （TAP）、AssertionError，以及 expected ... to ... 这种形式	测试运行器失败和断言失败
ERROR-LINE	单词 error（任意大小写）、Error:、ERR!、fatal:、panic、Traceback、Exception	通用错误证据，包括 Python 回溯和 npm ERR! 行
EXIT-NONZERO	后接非零数字的 exit code 或 exited with code，以及短语 command failed	退出代码为 0 不算匹配

片段和判定结果的工作方式

• 相距不超过 3 行的匹配行会组成一个片段。 间隔更大时会开始一个新片段。
• 在堆栈头之后（Traceback 行、一次运行中的第一条 at 堆栈行，或直接 后接堆栈行的匹配行），最多会额外捕获 5 行作为上下文，确保堆栈顶部 保留在摘要中。捕获内容不会跨越到下一个片段。
• 每个片段会成为一条发现项。其 line 是片段的首行行号，evidence 是第一条匹配行；发现项还包含 endLine 和捕获的 sectionLines。
• 对于包含堆栈头或断言的 TEST-FAIL 或 ERROR-LINE 片段，严重性为 high；其他情况为 medium。空日志会生成一条规则为 EMPTY-LOG、严重性为 info 的发现项。
• 报告会统计 totalLines、matchedLines、sections（实际输出的片段数）、sectionsTotal、overflowSections，以及每条规则的计数。
• 判定结果：至少有一个片段时为 FAILURES-FOUND，否则为 NO-FAILURES。空日志的判定结果为 NO-FAILURES，并包含上述 EMPTY-LOG 发现项。
• 发现项最多包含 200 个片段。超出上限的片段不会输出，但会计入 overflowSections，因此报告不会悄然截断。
• 在易读摘要中，每个片段会先打印其行号范围，再逐字打印捕获的行（每行截断至 200 个字符），最后打印总计。输出是确定性的：它完全由文件内容决定，不包含时间戳。

限制

• 检测基于模式，因此，如果日志以新颖的方式描述失败，且不符合上表中的任何形式，就可能无法检测到。 NO-FAILURES 判定的含义是“未发现已知的失败形式”， 并不能证明运行成功。
• logdigest 负责精简，不负责诊断。它会显示失败行及其紧邻上下文，但超出所显示行范围的根因分析需要读者自行完成。
• 只会输出前 200 个区段（其余区段只计数），渲染后的行会截断至 200 个字符，因此摘要只是阅读原始日志的起点，并非原文副本。原始行号始终会保留，以便在源日志中找到任何区段。

开发

npm install
npm run build
npm test

核心代码位于 src/core.ts，仅使用 Node 标准库。