@boyingliu01/xp-gate 0.31.1 → 0.31.3

package/lib/arch.js

@@ -21,9 +21,51 @@ const BASELINE_FILE = '.architecture-baseline.json';
 // (`archlint diff .architecture-baseline.json --fail-on high`).
 const FAIL_ON = 'high';
 const BLOCKING_SEVERITIES = new Set(['high', 'critical']);
-const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+/**
+ * Cap on captured archlint output.
+ *
+ * Written as a megabyte multiplier so the unit is in the name AND the literal is a
+ * named constant — a bare 64 next to 1024 reads as an arbitrary product.
+ */
+const MEBIBYTE = 1024 * 1024;
+const MAX_OUTPUT_MIB = 64;
+const MAX_OUTPUT_BYTES = MAX_OUTPUT_MIB * MEBIBYTE;
 const BLOCKING_PREVIEW_LIMIT = 10;
 
+/**
+ * Source extensions counted when measuring how much of a project a scan covered.
+ *
+ * Deliberately the same extension set archlint's detectors understand, plus the
+ * mainstream statically-typed ones it does not — the point of the census is to notice
+ * a project whose bulk is in a language no detector covers (#590's Java case), and
+ * that only works if those files are counted.
+ */
+const LANGUAGE_BY_EXTENSION = new Map([
+  ['.ts', 'typescript'],
+  ['.tsx', 'typescript'],
+  ['.js', 'javascript'],
+  ['.jsx', 'javascript'],
+  ['.mjs', 'javascript'],
+  ['.cjs', 'javascript'],
+  ['.java', 'java'],
+  ['.kt', 'kotlin'],
+  ['.kts', 'kotlin'],
+  ['.py', 'python'],
+  ['.go', 'go'],
+  ['.rs', 'rust'],
+  ['.cs', 'csharp'],
+  ['.rb', 'ruby'],
+  ['.php', 'php'],
+  ['.swift', 'swift'],
+  ['.dart', 'dart'],
+  ['.scala', 'scala'],
+  ['.c', 'c'],
+  ['.cc', 'cpp'],
+  ['.cpp', 'cpp'],
+  ['.h', 'c'],
+  ['.hpp', 'cpp'],
+]);
+
 /**
  * Windows extended-length prefixes (`\\?\C:\...`, `\\?\UNC\server\share\...`) —
  * strip for readable output. UNC first: its prefix also starts with `\\?\`.
@@ -84,10 +126,18 @@ function ownDependencyEntry() {
 
 /** First match of `name` on PATH, or null. */
 function findOnPath(name) {
-  const lookup = spawnSync(process.platform === 'win32' ? 'where' : 'which', [name], {
-    encoding: 'utf8',
-  });
-  if (lookup.status !== 0 || !lookup.stdout) return null;
+  let lookup;
+  try {
+    lookup = spawnSync(process.platform === 'win32' ? 'where' : 'which', [name], {
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    // A throw here means the lookup binary itself is unavailable. That is "not found on
+    // PATH", which is exactly what this function reports, not a reason to crash.
+    console.error(`[xp-gate arch] PATH lookup for ${name} could not run: ${err.message}`);
+    return null;
+  }
+  if (lookup.error || lookup.status !== 0 || !lookup.stdout) return null;
   const first = lookup.stdout.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
   return first && fs.existsSync(first) ? first : null;
 }
@@ -132,7 +182,18 @@ function quoteForShell(arg) {
  * otherwise output is inherited so the user sees archlint's own report.
  * Returns { ok, status, stdout, stderr }; ok:false means the tool never ran.
  */
-function runArchlint(resolved, args, { cwd, capture = false } = {}) {
+/**
+ * Work out the executable + argument list for a resolved archlint.
+ *
+ * Split from `runArchlint` to keep that function inside the long-function limit, and
+ * because the tier→invocation mapping is the part worth reading on its own: only the
+ * `node-script` tier avoids a shell, which is why it is the pinned default.
+ *
+ * @param {{kind: string, script?: string, bin?: string}} resolved
+ * @param {string[]} args arguments to the archlint CLI
+ * @returns {{command: string, commandArgs: string[], useShell: boolean}}
+ */
+function archlintInvocation(resolved, args) {
   let command;
   let commandArgs;
   let useShell = false;
@@ -153,21 +214,45 @@ function runArchlint(resolved, args, { cwd, capture = false } = {}) {
     command = quoteForShell(command);
     commandArgs = commandArgs.map(quoteForShell);
   }
-  const result = spawnSync(command, commandArgs, {
-    cwd,
-    encoding: 'utf8',
-    stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-    shell: useShell,
-    maxBuffer: MAX_OUTPUT_BYTES,
-  });
+  return { command, commandArgs, useShell };
+}
+
+/**
+ * Report why archlint could not be launched, in terms the reader can act on.
+ *
+ * @param {{source: string}} resolved
+ * @param {Error} error spawnSync's error, or a caught throw
+ */
+function reportLaunchFailure(resolved, error) {
+  if (error.code === 'ENOENT') {
+    console.error(`[xp-gate arch] ERROR: archlint not found (${resolved.source}).`);
+    console.error(`  Fix: npm install --save-dev ${ARCHLINT_PACKAGE} in your project,`);
+    console.error('  or reinstall xp-gate when its own pinned copy is the missing one.');
+    return;
+  }
+  console.error(`[xp-gate arch] ERROR: failed to run archlint (${resolved.source}): ${error.message}`);
+}
+
+function runArchlint(resolved, args, { cwd, capture = false } = {}) {
+  const { command, commandArgs, useShell } = archlintInvocation(resolved, args);
+  let result;
+  try {
+    result = spawnSync(command, commandArgs, {
+      cwd,
+      encoding: 'utf8',
+      stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      shell: useShell,
+      maxBuffer: MAX_OUTPUT_BYTES,
+    });
+  } catch (err) {
+    // spawnSync normally reports launch failures via `result.error`; a throw means the
+    // call itself was malformed. Both are "the tool never ran", which must never read as
+    // a clean scan.
+    console.error(`[xp-gate arch] ERROR: could not invoke archlint (${resolved.source}): ${err.message}`);
+    return { ok: false, status: 1, stdout: '', stderr: '' };
+  }
   if (result.error) {
-    if (result.error.code === 'ENOENT') {
-      console.error(`[xp-gate arch] ERROR: archlint not found (${resolved.source}).`);
-      console.error(`  Fix: npm install --save-dev ${ARCHLINT_PACKAGE} in your project,`);
-      console.error('  or reinstall xp-gate when its own pinned copy is the missing one.');
-    } else {
-      console.error(`[xp-gate arch] ERROR: failed to run archlint (${resolved.source}): ${result.error.message}`);
-    }
+    reportLaunchFailure(resolved, result.error);
     return { ok: false, status: 1, stdout: '', stderr: '' };
   }
   return {
@@ -182,7 +267,106 @@ function runArchlint(resolved, args, { cwd, capture = false } = {}) {
  * Parse `archlint scan --format json` output into a verdict.
  * Fail-closed: unparseable output is reported as an error, never as "clean".
  */
-function verdictFromScanJson(jsonText) {
+/**
+ * Below this fraction of the project's source files, a scan is treated as not having
+ * covered the project.
+ *
+ * Not zero, because archlint legitimately analyses only the files its detectors
+ * understand, and a polyglot repo will always have some files outside its extensions.
+ * A quarter is deliberately generous: the case this exists for is 1-of-140, where any
+ * threshold catches it, and a real JS/TS project sits far above 0.25.
+ */
+const MIN_ANALYSIS_COVERAGE = 0.25;
+
+/**
+ * Source-file census for the project, used to judge whether a scan covered it.
+ *
+ * Walks the tree once, skipping the usual vendored directories. Cheap enough to run
+ * before a scan that takes seconds, and it is the ONLY way to know that
+ * `files_analyzed: 1` is a fifth of a percent rather than "this project is tiny".
+ *
+ * A failure to count returns `{}` rather than a guess: an unknown project size must
+ * leave the grade alone (see the `no project size known` case in the tests), never
+ * produce a spurious "not covered" verdict.
+ *
+ * @param {string} projectRoot repository root
+ * @returns {{projectFileCount?: number, dominantLanguage?: string}}
+ */
+function projectScanContext(projectRoot) {
+  const counts = new Map();
+  let total = 0;
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'target', 'coverage', 'vendor']);
+  const walk = (dir, depth) => {
+    // Depth bound: a symlink cycle would otherwise walk forever.
+    if (depth > 24) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIP.has(entry.name)) continue;
+        walk(path.join(dir, entry.name), depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!LANGUAGE_BY_EXTENSION.has(ext)) continue;
+      total += 1;
+      const lang = LANGUAGE_BY_EXTENSION.get(ext);
+      counts.set(lang, (counts.get(lang) || 0) + 1);
+    }
+  };
+  walk(projectRoot, 0);
+  if (total === 0) return {};
+  let dominantLanguage;
+  let best = -1;
+  // Deterministic tie-break: candidates in sorted order, strict `>` keeps the first.
+  for (const [lang, n] of [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    if (n > best) {
+      best = n;
+      dominantLanguage = lang;
+    }
+  }
+  return { projectFileCount: total, dominantLanguage };
+}
+
+/**
+ * Decide whether a scan covered enough of the project for its grade to mean anything.
+ *
+ * #590: a Java project with 140 `.java` files and no JS/TS got
+ * `files_analyzed: 1`, `total_smells: 0`, and therefore `10.0 / Excellent`. archlint's
+ * detectors are import-graph based over JS/TS extensions, so on that project every
+ * architecture check Gate 6 exists for — cycles, god modules, dead code, shotgun
+ * surgery — was silently skipped, while the report said the architecture was excellent.
+ *
+ * "Did not look" and "looked and found nothing" must be distinguishable. This is the
+ * same shape as #589 (Gate 3 permanently SKIP) and #594 (NaN coverage as PASS): the
+ * third instance today, which is why the check lives here rather than in the printer.
+ *
+ * @param {object|null} summary archlint's summary object
+ * @param {{projectFileCount?: number, dominantLanguage?: string}} [context]
+ * @returns {string|null} why the grade is untrustworthy, or null when it is fine
+ */
+function analysisCoverageGap(summary, context) {
+  if (!summary) return null; // no grade at all: nothing to withhold
+  const analyzed = Number(summary.files_analyzed);
+  const total = Number(context && context.projectFileCount);
+  // Without both numbers there is nothing to compare. Reporting a gap on a guess would
+  // withhold grades from every caller that has not supplied a count — a worse outcome
+  // than the defect, and the reason the existing arch tests keep working unchanged.
+  if (!Number.isFinite(analyzed) || !Number.isFinite(total) || total <= 0) return null;
+  if (analyzed >= total * MIN_ANALYSIS_COVERAGE) return null;
+
+  const lang = (context && context.dominantLanguage) || 'the project';
+  // The numbers are in the message on purpose: an operator who sees "1 of 140" believes
+  // it, where "low coverage" reads as a threshold opinion.
+  return `archlint analysed ${analyzed} of ${total} source file(s), so it did not cover ${lang}. Its grade is withheld.`;
+}
+
+function verdictFromScanJson(jsonText, context) {
   let parsed;
   try {
     parsed = JSON.parse(jsonText);
@@ -207,16 +391,29 @@ function verdictFromScanJson(jsonText) {
       if (blockingDetails.length < BLOCKING_PREVIEW_LIMIT) blockingDetails.push(smell);
     }
   }
+  const summary = (parsed && parsed.summary) || null;
+  // #590: withhold an untrustworthy grade. The findings themselves are still reported —
+  // they are real regardless of how much was covered — but a 10.0 is a claim about a
+  // project, and this is the check that stops the claim being made about a project that
+  // was not read.
+  const coverageGap = analysisCoverageGap(summary, context);
   return {
     parseError: null,
     total: smells.length,
     blocking,
     blockingDetails,
-    summary: (parsed && parsed.summary) || null,
+    summary: coverageGap ? null : summary,
+    coverageGap,
   };
 }
 
 function printScanSummary(verdict) {
+  if (verdict.coverageGap) {
+    // Say it before the findings line: an operator reading top-down must know the grade
+    // is missing and why, or the absence looks like a formatting quirk.
+    console.log(`[xp-gate arch] Grade withheld: ${verdict.coverageGap}`);
+    console.log('  Architecture was NOT measured for the languages archlint has no detector for.');
+  }
   const grade = verdict.summary && verdict.summary.architecture_grade;
   if (grade && grade.score !== undefined) {
     console.log(`[xp-gate arch] Architecture quality: ${grade.score}/10 (${grade.level})`);
@@ -237,30 +434,44 @@ function printScanSummary(verdict) {
  * Tool failures (spawn error, non-zero scan exit, unparseable JSON) always
  * exit non-zero — a broken scan must never read as a clean one.
  */
+/**
+ * Baseline-ratchet mode: only NEW high/critical findings block.
+ *
+ * Split out of `runBuiltinScan` to keep that function inside the long-function limit
+ * (the #590 census pushed it over), and because this mode's contract — the exit code
+ * itself IS the verdict — deserves to be readable in one place.
+ *
+ * @param {string} projectRoot repository root
+ * @param {{kind: string}} resolved resolved archlint
+ * @param {string} baselinePath path to the baseline file
+ * @returns {number} exit code
+ */
+function runBaselineRatchet(projectRoot, resolved, baselinePath) {
+  console.log(`[xp-gate arch] Baseline ratchet mode — ${BASELINE_FILE} present; blocking new ${FAIL_ON}+ findings only`);
+  const diff = runArchlint(resolved, ['diff', baselinePath, '--fail-on', FAIL_ON], { cwd: projectRoot });
+  if (!diff.ok) return 1;
+  // `--fail-on high` makes the exit code itself the verdict contract: 0 = no new high+
+  // findings, 1 = at least one. This is the exact mechanism Gate 6's pre-commit has used
+  // since before #447, so parity here is the point, not a shortcut. Anything other than
+  // 0/1 is a tool failure and blocks.
+  if (diff.status === 0) {
+    console.log(`✅ arch: no new ${FAIL_ON}+ architecture findings (baseline ratchet)`);
+    return 0;
+  }
+  if (diff.status === 1) {
+    console.error(`❌ BLOCKED - new ${FAIL_ON}+ architecture findings (baseline ratchet mode)`);
+    console.error('  Fix the findings above, or refresh the baseline with:');
+    console.error(`    npx ${ARCHLINT_PACKAGE} snapshot -o ${BASELINE_FILE}`);
+    return 1;
+  }
+  console.error(`❌ ERROR - archlint diff exited ${diff.status}; tool failure is treated as blocking (never a silent pass)`);
+  return 1;
+}
+
 function runBuiltinScan(projectRoot, resolved) {
   const baselinePath = path.join(projectRoot, BASELINE_FILE);
   if (fs.existsSync(baselinePath)) {
-    console.log(`[xp-gate arch] Baseline ratchet mode — ${BASELINE_FILE} present; blocking new ${FAIL_ON}+ findings only`);
-    const diff = runArchlint(resolved, ['diff', baselinePath, '--fail-on', FAIL_ON], { cwd: projectRoot });
-    if (!diff.ok) return 1;
-    // `--fail-on high` makes the exit code itself the verdict contract: 0 = no
-    // new high+ findings, 1 = at least one. This is the exact mechanism Gate
-    // 6's pre-commit has used since before #447 (issue evidence: "Gate 6
-    // actually uses: archlint diff .architecture-baseline.json --fail-on high
-    // ✅ normal"), so parity here is the point, not a shortcut. Anything other
-    // than 0/1 is a tool failure and blocks.
-    if (diff.status === 0) {
-      console.log(`✅ arch: no new ${FAIL_ON}+ architecture findings (baseline ratchet)`);
-      return 0;
-    }
-    if (diff.status === 1) {
-      console.error(`❌ BLOCKED - new ${FAIL_ON}+ architecture findings (baseline ratchet mode)`);
-      console.error('  Fix the findings above, or refresh the baseline with:');
-      console.error(`    npx ${ARCHLINT_PACKAGE} snapshot -o ${BASELINE_FILE}`);
-      return 1;
-    }
-    console.error(`❌ ERROR - archlint diff exited ${diff.status}; tool failure is treated as blocking (never a silent pass)`);
-    return 1;
+    return runBaselineRatchet(projectRoot, resolved, baselinePath);
   }
 
   console.log('[xp-gate arch] Zero-tolerance mode — no .architecture-baseline.json; blocking any high/critical finding');
@@ -281,7 +492,11 @@ function runBuiltinScan(projectRoot, resolved) {
     if (scan.stderr) process.stderr.write(scan.stderr);
     return 1;
   }
-  const verdict = verdictFromScanJson(scan.stdout);
+  // #590: give the verdict the two facts it needs to judge its own grade — how many
+  // source files the project has, and which language dominates it. Without them a scan
+  // of 1-of-140 files still reports 10.0/Excellent, which is the vacuous pass this
+  // issue is about.
+  const verdict = verdictFromScanJson(scan.stdout, projectScanContext(projectRoot));
   if (verdict.parseError) {
     console.error(`❌ ERROR - ${verdict.parseError}; tool failure is treated as blocking (never a silent pass)`);
     return 1;
@@ -360,6 +575,8 @@ module.exports = {
     binEntryFromPackageDir,
     resolveArchlint,
     verdictFromScanJson,
+    analysisCoverageGap,
+    projectScanContext,
     quoteForShell,
     stripExtendedPrefix,
     BLOCKING_SEVERITIES,

package/lib/check-alignment-runner.cjs

@@ -68,6 +68,29 @@ if (jsonMode) {
   console.log('Status:', report.alignment_status);
   console.log('Score:', report.score);
   console.log('Misaligned:', report.misaligned_tests.length);
+
+  // #573 (recurrence of #57): a non-PASS verdict used to print only the status
+  // and counters. On a real run that read:
+  //     Status: BLOCKED
+  //     Score: 0
+  //     Misaligned: 0
+  // which contradicts itself — zero misaligned tests, yet blocked — while the
+  // actual reason sat in report.errors that nothing ever printed. A gate that
+  // blocks without saying why is not actionable, and the usual response to an
+  // unactionable red is to bypass it, which is how dead gates are made.
+  if (report.alignment_status !== 'PASS') {
+    const reasons = Array.isArray(report.errors) ? report.errors : [];
+    if (reasons.length > 0) {
+      console.error('Reasons:');
+      for (const reason of reasons) console.error('  -', reason);
+    } else {
+      // Saying so is the point: a blocked verdict with no recorded reason is a
+      // defect in whoever produced the report, not something the reader can fix
+      // by editing their own files.
+      console.error('Reasons: (none recorded) — this is a bug in the report producer:');
+      console.error('  a non-PASS alignment verdict must carry at least one entry in report.errors.');
+    }
+  }
 }
 // Set exitCode instead of process.exit() so buffered stdout (notably the
 // --json document) flushes fully before the process terminates (#392 review).

package/lib/check.js

@@ -147,7 +147,10 @@ async function checkAllGates(target) {
   }
 
   for (const gate of invokableGates) {
-    const code = await runGate(gate.id, target);
+    // #589: `--all` means the whole tree. Passing the scope keeps the gates that
+    // read CHANGED_FILES from scanning an empty diff and reporting SKIP — which
+    // read like a pass while checking LESS than an ordinary commit.
+    const code = await runGate(gate.id, target, { scope: 'all' });
     if (code === 0) tally.passed += 1;
     else tally.failed += 1;
     console.log('');