euthyna 0.1.1 → 0.3.0

package/src/gate.js

@@ -25,6 +25,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { safeTextLines } from './contract.js';
+import { T, DEFAULT_LANG } from './lang.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -40,6 +41,30 @@ export const GATE_NAMES = Object.freeze({
   6: '环境'
 });
 
+/** The gate statuses as written in a report, in either language. */
+const GATE_STATUSES = Object.freeze({
+  PASS: 'PASS',
+  FAIL: 'FAIL',
+  PASS_ZH: '通过',
+  NOT_EVALUATED_ZH: '未评估',
+  NOT_EVALUATED_EN: 'NOT EVALUATED'
+});
+
+/** True when a parsed status means "the gate passed". */
+export function isPassStatus(status) {
+  return status === GATE_STATUSES.PASS || status === GATE_STATUSES.PASS_ZH;
+}
+
+/** True when a parsed status means "the gate failed". */
+export function isFailStatus(status) {
+  return status === GATE_STATUSES.FAIL;
+}
+
+/** True when a parsed status means "the gate could not be evaluated". */
+export function isNotEvaluatedStatus(status) {
+  return status === GATE_STATUSES.NOT_EVALUATED_ZH || /^not evaluated$/i.test(status);
+}
+
 /**
  * A finding header: `BUG #N <VERDICT> — <claim>`. The em dash is the skill's
  * form, a hyphen is tolerated, and the claim may be empty (that is itself a
@@ -50,16 +75,23 @@ const HEADER = /^BUG\s+#?(\d+)\s+(TRUE POSITIVE|FALSE POSITIVE|INCONCLUSIVE)\s*(
 /** A line that starts like a finding but does not parse - reported, not dropped. */
 const BUGLIKE = /^BUG\b/i;
 
+/**
+ * Field markers, accepted in either language. The parser is bilingual on
+ * purpose and independent of the output language: a report is data, and a
+ * Chinese-written report must validate under an English session and vice
+ * versa. The English keywords are case-insensitive; the Chinese ones are
+ * unaffected by the flag.
+ */
 const FIELDS = {
-  evidence: /^证据\s*[:：]\s*(.+)$/,
-  reproduce: /^复现\s*[:：]\s*(.+)$/,
-  impact: /^影响\s*[:：]\s*(.+)$/,
-  exploitability: /^可利用性\s*[:：]\s*(.+)$/,
-  gate: /^门禁\s*(\d+)\s*(?:[（(]([^）)]*)[）)])?\s*(PASS|通过|FAIL|未评估)\s*[:：]?\s*(.*)$/
+  evidence: /^(?:证据|Evidence)\s*[:：]\s*(.+)$/i,
+  reproduce: /^(?:复现|Reproduce)\s*[:：]\s*(.+)$/i,
+  impact: /^(?:影响|Impact)\s*[:：]\s*(.+)$/i,
+  exploitability: /^(?:可利用性|Exploitability)\s*[:：]\s*(.+)$/i,
+  gate: /^(?:门禁|Gate)\s*(\d+)\s*(?:[（(]([^）)]*)[）)])?\s*(PASS|通过|FAIL|未评估|NOT EVALUATED|Not evaluated)\s*[:：]?\s*(.*)$/i
 };
 
-/** `门禁全部通过。` may share its line with the evidence that follows it. */
-const ALL_PASS = /^门禁全部通过[。.]?/;
+/** `门禁全部通过。` / `All gates passed.` may share its line with the evidence that follows it. */
+const ALL_PASS = /^(?:门禁全部通过|All gates passed)[。.]?\s*/i;
 
 /**
  * Extract {file, line, commit} from an evidence string. Both `src/a.js:123`
@@ -178,43 +210,113 @@ export function parseGateReport(text) {
  * `violations` names every way it fails, `downgraded` is true when any fail.
  * Unparseable BUG-like lines are returned separately as downgrade candidates.
  */
-export function validateFindings(findings) {
+export function validateFindings(findings, { lang = DEFAULT_LANG } = {}) {
+  const t = T(lang);
   return findings.map((finding) => {
     const violations = [];
-    const fails = finding.gates.filter((g) => g.status === 'FAIL');
-    const notEval = finding.gates.filter((g) => g.status === '未评估');
-    const passes = finding.gates.filter((g) => g.status === 'PASS' || g.status === '通过');
+    const fails = finding.gates.filter((g) => isFailStatus(g.status));
+    const notEval = finding.gates.filter((g) => isNotEvaluatedStatus(g.status));
+    const passes = finding.gates.filter((g) => isPassStatus(g.status));
 
     for (const gate of finding.gates) {
       if (!(gate.number in GATE_NAMES)) {
-        violations.push(`门禁编号 ${gate.number} 不在 1..6 内`);
+        violations.push(
+          t(`门禁编号 ${gate.number} 不在 1..6 内`, `gate number ${gate.number} is not in 1..6`)
+        );
       }
-      if ((gate.status === 'FAIL' || gate.status === '未评估') && !gate.reason.trim()) {
-        violations.push(`门禁 ${gate.number} ${gate.status} 缺少理由`);
+      if ((isFailStatus(gate.status) || isNotEvaluatedStatus(gate.status)) && !gate.reason.trim()) {
+        violations.push(
+          t(`门禁 ${gate.number} ${gate.status} 缺少理由`, `gate ${gate.number} ${gate.status} lacks a reason`)
+        );
       }
     }
 
-    if (!finding.claim.trim()) violations.push('缺少结论描述（BUG 标题后的说明）');
+    if (!finding.claim.trim()) {
+      violations.push(
+        t('缺少结论描述（BUG 标题后的说明）', 'missing claim description (the note after the BUG header)')
+      );
+    }
 
     if (finding.verdict === 'TRUE POSITIVE') {
       if (!finding.evidence) {
-        violations.push('缺少证据（TRUE POSITIVE 必须带 证据：path:L123）');
+        violations.push(
+          t(
+            '缺少证据（TRUE POSITIVE 必须带 证据：path:L123）',
+            'missing evidence (a TRUE POSITIVE must carry Evidence: path:L123)'
+          )
+        );
       } else if (finding.evidence.line === null) {
-        violations.push('证据缺少行号（需要 path:L123 形式，禁止只写文件名）');
+        violations.push(
+          t(
+            '证据缺少行号（需要 path:L123 形式，禁止只写文件名）',
+            'evidence lacks a line number (path:L123 form required; a bare file name is not allowed)'
+          )
+        );
       }
       if (!finding.reproduce) {
-        violations.push('缺少复现命令（TRUE POSITIVE 必须带 复现：<命令> 或 PoC）');
+        violations.push(
+          t(
+            '缺少复现命令（TRUE POSITIVE 必须带 复现：<命令> 或 PoC）',
+            'missing reproduce command (a TRUE POSITIVE must carry Reproduce: <command> or a PoC)'
+          )
+        );
+      }
+      if (!finding.impact) {
+        violations.push(
+          t('缺少影响说明（门禁 3 的证据）', 'missing impact statement (the evidence for gate 3)')
+        );
       }
-      if (!finding.impact) violations.push('缺少影响说明（门禁 3 的证据）');
       const allPassed = finding.allPass || passes.length === 6;
-      if (!allPassed) violations.push('门禁未全部通过（需要 门禁全部通过。 或六条 PASS）');
-      if (fails.length) violations.push(`TRUE POSITIVE 含 FAIL 门禁（${fails.map((g) => g.number).join(', ')}）——应裁定为 FALSE POSITIVE`);
-      if (notEval.length) violations.push(`TRUE POSITIVE 含未评估门禁（${notEval.map((g) => g.number).join(', ')}）——应裁定为 INCONCLUSIVE`);
+      if (!allPassed) {
+        violations.push(
+          t(
+            '门禁未全部通过（需要 门禁全部通过。 或六条 PASS）',
+            'not all gates pass (requires "All gates passed." or six PASS lines)'
+          )
+        );
+      }
+      if (fails.length) {
+        violations.push(
+          t(
+            `TRUE POSITIVE 含 FAIL 门禁（${fails.map((g) => g.number).join(', ')}）——应裁定为 FALSE POSITIVE`,
+            `TRUE POSITIVE contains FAIL gates (${fails.map((g) => g.number).join(', ')}) — should be ruled FALSE POSITIVE`
+          )
+        );
+      }
+      if (notEval.length) {
+        violations.push(
+          t(
+            `TRUE POSITIVE 含未评估门禁（${notEval.map((g) => g.number).join(', ')}）——应裁定为 INCONCLUSIVE`,
+            `TRUE POSITIVE contains not-evaluated gates (${notEval.map((g) => g.number).join(', ')}) — should be ruled INCONCLUSIVE`
+          )
+        );
+      }
     } else if (finding.verdict === 'FALSE POSITIVE') {
-      if (fails.length === 0) violations.push('FALSE POSITIVE 必须至少有一条 门禁 N FAIL：<具体证据>');
+      if (fails.length === 0) {
+        violations.push(
+          t(
+            'FALSE POSITIVE 必须至少有一条 门禁 N FAIL：<具体证据>',
+            'a FALSE POSITIVE must have at least one Gate N FAIL: <specific evidence>'
+          )
+        );
+      }
     } else {
-      if (notEval.length === 0) violations.push('INCONCLUSIVE 必须至少有一条 门禁 N 未评估：<为什么>');
-      if (fails.length) violations.push('INCONCLUSIVE 含 FAIL 门禁——应裁定为 FALSE POSITIVE');
+      if (notEval.length === 0) {
+        violations.push(
+          t(
+            'INCONCLUSIVE 必须至少有一条 门禁 N 未评估：<为什么>',
+            'an INCONCLUSIVE must have at least one Gate N NOT EVALUATED: <why>'
+          )
+        );
+      }
+      if (fails.length) {
+        violations.push(
+          t(
+            'INCONCLUSIVE 含 FAIL 门禁——应裁定为 FALSE POSITIVE',
+            'INCONCLUSIVE contains FAIL gates — should be ruled FALSE POSITIVE'
+          )
+        );
+      }
     }
 
     return { finding, violations, downgraded: violations.length > 0 };
@@ -321,27 +423,48 @@ export async function verifyFinding(
  * Render the gate result for a terminal reader. Report-derived text passes the
  * render boundary here exactly once, like the fact report channel.
  */
-export function renderGateReport(result, { write: rawWrite = console.log } = {}) {
+export function renderGateReport(result, { write: rawWrite = console.log, lang = DEFAULT_LANG } = {}) {
+  const t = T(lang);
   const write = (line) => rawWrite(safeTextLines(line));
   const { file, findings, unparseable, downgraded, verify } = result;
 
   write('');
-  write('euthyna gate — 6 门禁契约校验（不测量，只核对报告的自我声明）');
-  write(`报告: ${file}`);
+  write(
+    t(
+      'euthyna gate — 6 门禁契约校验（不测量，只核对报告的自我声明）',
+      'euthyna gate — six-gate contract check (no measurement; only the report\'s own claims are checked)'
+    )
+  );
+  write(`${t('报告: ', 'Report: ')}${file}`);
   if (verify) {
-    write('⚠ --verify 以当前用户权限执行报告中的复现命令（按 argv 执行，不经过 shell）。');
-    write('  默认只执行 git 命令；解释器命令（node/npm/python）需要显式 --allow-exec。');
-    write('  它不是一个安全沙箱：只对你自己信任的报告使用。');
+    write(
+      t(
+        '⚠ --verify 以当前用户权限执行报告中的复现命令（按 argv 执行，不经过 shell）。',
+        '⚠ --verify runs the report\'s reproduce commands with your privileges (as argv, no shell).'
+      )
+    );
+    write(
+      t(
+        '  默认只执行 git 命令；解释器命令（node/npm/python）需要显式 --allow-exec。',
+        '  Only git commands run by default; interpreter commands (node/npm/python) need explicit --allow-exec.'
+      )
+    );
+    write(
+      t(
+        '  它不是一个安全沙箱：只对你自己信任的报告使用。',
+        '  It is not a sandbox: use it only on reports you trust.'
+      )
+    );
   }
   write('');
 
   for (const entry of findings) {
     const f = entry.finding;
-    const head = `  BUG #${f.number} ${f.verdict} — ${f.claim || '(无结论描述)'}`;
+    const head = `  BUG #${f.number} ${f.verdict} — ${f.claim || t('(无结论描述)', '(no claim)')}`;
     if (entry.downgraded) {
-      write(`${head} — ✗ 降级为「观察」`);
+      write(`${head} — ✗ ${t('降级为「观察」', 'downgraded to "observation"')}`);
     } else {
-      write(`${head} — ✓ 通过`);
+      write(`${head} — ✓ ${t('通过', 'passed')}`);
     }
     if (entry.verification && f.verdict === 'TRUE POSITIVE') {
       const v = entry.verification;
@@ -352,30 +475,35 @@ export function renderGateReport(result, { write: rawWrite = console.log } = {})
           : v.status === 'failed'
             ? `(exit ${v.exitCode ?? '?'}${v.detail ? `: ${v.detail}` : ''})`
             : v.status === 'refused'
-              ? `(拒绝运行 ${v.tool} —— 不在白名单)`
+              ? t(`(拒绝运行 ${v.tool} —— 不在白名单)`, `(refused to run ${v.tool} — not on the allowlist)`)
               : v.status === 'needs-consent'
-                ? `(未执行 ${v.tool} 解释器命令 —— 需要 --allow-exec)`
+                ? t(`(未执行 ${v.tool} 解释器命令 —— 需要 --allow-exec)`, `(interpreter command ${v.tool} not run — needs --allow-exec)`)
                 : v.status === 'unparseable'
-                  ? '(命令无法拆分为 argv)'
-                  : '(无复现命令)';
-      write(`     复现核验 ${mark} ${how}`);
+                  ? t('(命令无法拆分为 argv)', '(command could not be split into argv)')
+                  : t('(无复现命令)', '(no reproduce command)');
+      write(`${t('     复现核验 ', '     Reproduce check ')}${mark} ${how}`);
     }
     for (const violation of entry.violations) {
-      write(`     缺: ${violation}`);
+      write(`${t('     缺: ', '     missing: ')}${violation}`);
     }
   }
 
   if (unparseable.length) {
     write('');
-    write('⚠ 无法解析的 BUG 行（计入降级）：');
+    write(t('⚠ 无法解析的 BUG 行（计入降级）：', '⚠ Unparseable BUG lines (counted as downgrades):'));
     for (const line of unparseable) write(`  • ${line}`);
   }
 
   write('');
   if (downgraded === 0) {
-    write('全部 finding 通过门禁契约。');
+    write(t('全部 finding 通过门禁契约。', 'All findings pass the gate contract.'));
   } else {
-    write(`⚠ ${downgraded} 个 finding 被降级为「观察」——缺证据、缺复现或门禁不一致，不得当作已确证的结论。`);
+    write(
+      t(
+        `⚠ ${downgraded} 个 finding 被降级为「观察」——缺证据、缺复现或门禁不一致，不得当作已确证的结论。`,
+        `⚠ ${downgraded} finding${downgraded === 1 ? '' : 's'} downgraded to "observation" — missing evidence, missing reproduction, or inconsistent gates; must not be read as established findings.`
+      )
+    );
   }
   write('');
 }

package/src/lang.js

@@ -0,0 +1,55 @@
+/**
+ * Language selection for the CLI (i18n).
+ *
+ * Zero-dependency on purpose, like everything else in this project: no i18n
+ * framework is pulled in. The CLI currently ships two languages, chosen by an
+ * explicit switch rather than by locale sniffing, because a locale-derived
+ * answer can surprise ("I asked for English and got Chinese") and is hard to
+ * reproduce in CI.
+ *
+ * Precedence: an explicit `--lang` flag beats the EUTHYNA_LANG environment
+ * variable, which beats the default (Chinese). The default stays Chinese so a
+ * user who never asks for English sees exactly the output they saw before.
+ */
+
+export const LANGS = Object.freeze(['zh', 'en']);
+export const DEFAULT_LANG = 'zh';
+
+/** True for a value the CLI accepts as a language. */
+export function isLang(value) {
+  return value === 'zh' || value === 'en';
+}
+
+/**
+ * Resolve the effective language.
+ *
+ * Precedence: an explicit flag wins, then the environment variable, then the
+ * default. cli.js validates the flag value before calling this, so a non-zh/en
+ * flag never reaches here.
+ *
+ * @param {object} [options]
+ * @param {string|boolean} [options.flag]  the value of --lang (true when the
+ *                                         flag was passed without a value)
+ * @param {object} [options.env]  defaults to process.env
+ * @returns {'zh'|'en'}
+ */
+export function resolveLang({ flag, env = process.env } = {}) {
+  if (flag === 'en' || flag === 'zh') return flag;
+  if (env.EUTHYNA_LANG === 'en') return 'en';
+  return DEFAULT_LANG;
+}
+
+/**
+ * The translation helper. Call it once per scope with the active language:
+ *
+ *   const t = T(lang);
+ *   write(t('已确证', 'Established'));
+ *
+ * The Chinese text is always the first argument and stays the canonical form;
+ * the English is the second. Each call site keeps both strings next to the
+ * interpolation that builds them, so a translation cannot drift from the
+ * message it translates.
+ */
+export function T(lang) {
+  return (zh, en) => (lang === 'en' ? en : zh);
+}