@ecoma-io/archkeep 0.21.0 → 0.22.1

package/src/report/json.mjs

@@ -94,12 +94,39 @@ export function jsonEnvelope({ command, context, status, exitCode, coverage, res
         `them disagree would make one of them a lie.`,
     );
   }
-  if (coverage.complete !== (coverage.notAnalyzed.length === 0)) {
+  // Completeness law, one-directional (#595, #599): `complete: true`
+  // claims the run judged everything its coverage block describes, and a
+  // whole-file failure or an unresolvable import site is exactly the kind
+  // of thing it did not judge — so the claim is refused over either. The
+  // reverse is deliberately allowed: `complete: false` with both lists
+  // empty is the zero-analysis state (a scope that selected no owned file,
+  // in-scope files no analyzer claims), which names its reason in the
+  // envelope's status and decision rather than in these lists, and refusing
+  // it would leave a run that judged nothing unable to say so. blindSpots
+  // is optional because not every command's coverage carries it; where it
+  // is present, the law is enforced.
+  //
+  // Within blindSpots only the unresolvable-LITERAL class counts as unjudged
+  // work (#595, narrowed): a row carrying `dynamic: true` is the declared
+  // non-literal-import limit — the language itself saying the target is
+  // computed at runtime, unknowable to static analysis in principle — and a
+  // declared limit is disclosed, not withheld over. The classifier lives once
+  // in `analysis/source-util.mjs`; this guard reads the row field the same
+  // helper that built the rows set, so the two can never disagree.
+  const blindSpotList = Array.isArray(coverage.blindSpots) ? coverage.blindSpots : [];
+  const unjudgedBlindSpots = blindSpotList.filter(
+    (row) => row.dynamic !== true && row.external !== true,
+  );
+  if (
+    coverage.complete === true &&
+    (coverage.notAnalyzed.length > 0 || unjudgedBlindSpots.length > 0)
+  ) {
     throw new Error(
-      `archkeep: refusing to build a JSON envelope where coverage.complete (${coverage.complete}) ` +
-        `disagrees with coverage.notAnalyzed (${coverage.notAnalyzed.length} entr${coverage.notAnalyzed.length === 1 ? "y" : "ies"}) ` +
-        `— the two must always agree, or a reader checking only one of them could mistake a partial ` +
-        `run for a complete one.`,
+      `archkeep: refusing to build a JSON envelope claiming coverage.complete (${coverage.complete}) ` +
+        `over unjudged work (notAnalyzed: ${coverage.notAnalyzed.length} entr${coverage.notAnalyzed.length === 1 ? "y" : "ies"}, ` +
+        `blindSpots: ${unjudgedBlindSpots.length}) — a run ` +
+        `that could not read everything cannot claim to have. This is a bug in the command that built ` +
+        `this envelope, not a fact about the workspace being judged.`,
     );
   }
   // A bare `null` decision is the same programming error as a hand-built

package/src/report/text.mjs

@@ -21,7 +21,11 @@
  * wearing a formatter's name, and it would disagree with the engine the first
  * time either changed (`README.md` beside this file).
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  isDynamicSiteFailure,
+  isExternalSiteFailure,
+  isWholeFileFailure,
+} from "../analysis/source-util.mjs";
 
 /** Two spaces of indent for a violation's detail lines, four for wrapped text. */
 const DETAIL = "  ";
@@ -128,12 +132,19 @@ const formatFailure = (failure) =>
  * consequences and one heading for both hid that for as long as it existed.
  *
  * A SITE failure is a blind spot: the file was analyzed, and one specifier in
- * it is not statically knowable — `import(url)` with a computed argument is
- * the honest example, and so is a literal package import that names no
- * declared project and cannot resolve (an uninstalled third-party dependency:
- * a workspace with packages is a normal state, and failing the run on it would
- * block merges over dependencies nobody crossed). Both are legitimately
- * permanent, and the rest of the file still got a verdict.
+ * it is not statically knowable. Three classes, and the section says which
+ * class did what instead of leaving the exit code to be discovered. An
+ * unresolvable literal referencing the workspace's own surface — path-like,
+ * `#` subpath, `paths` alias — is a concrete question the resolver was asked
+ * about the governed graph and could not answer: it WITHHELD the verdict
+ * (exit 3 on a findings-free run, #595). An unresolvable bare-package
+ * specifier names no project the workspace declares — `external: true`, the
+ * resolvability question an installed dependency tree answers, which a
+ * workspace legitimately may not have (the native self-check's `git archive`
+ * copy is the measured case: 284 rows) — disclosed without withholding. A
+ * non-literal `import()`/`require()` argument is the language declaring the
+ * target computed at runtime — a declared limit, `dynamic: true`, disclosed
+ * without withholding.
  *
  * A WHOLE-FILE failure is a hole: nothing was read, parsed, or analyzed — or a
  * literal import that names a DECLARED project could not be resolved, so the
@@ -165,12 +176,42 @@ export function formatFailures(failures) {
   }
 
   if (blind.length > 0) {
+    const dyn = blind.filter(isDynamicSiteFailure).length;
+    const ext = blind.filter(isExternalSiteFailure).length;
+    const literal = blind.length - dyn - ext;
     sections.push(
       [
-        `${blind.length} import${blind.length === 1 ? "" : "s"} could not be resolved. ` +
-          `These are blind spots inside files that were analyzed, not verdicts — the run does not fail on them:`,
-        ...blind.map(formatFailure),
-      ].join("\n"),
+        `${blind.length} import${blind.length === 1 ? "" : "s"} could not be resolved — ` +
+          `blind spots inside files that were analyzed:`,
+        // All permanent classes are disclosed; the verdict treats them
+        // differently, and the report says which class did what instead of
+        // leaving the exit code to be discovered (the same posture the
+        // whole-file section's heading holds).
+        ...(literal > 0
+          ? [
+              `${literal} unresolvable literal import${literal === 1 ? "" : "s"} withheld the run's verdict (#595):`,
+            ]
+          : []),
+        ...blind
+          .filter((failure) => !isDynamicSiteFailure(failure) && !isExternalSiteFailure(failure))
+          .map(formatFailure),
+        ...(ext > 0
+          ? [
+              `${ext} unresolvable package import${ext === 1 ? "" : "s"} name${ext === 1 ? "s" : ""} ` +
+                `no project the workspace declares — external, disclosed without withholding:`,
+            ]
+          : []),
+        ...blind.filter(isExternalSiteFailure).map(formatFailure),
+        ...(dyn > 0
+          ? [
+              `${dyn} non-literal import() argument${dyn === 1 ? "" : "s"} — a declared limit static analysis cannot answer; ` +
+                `the verdict stands over the statically judgeable surface:`,
+            ]
+          : []),
+        ...blind.filter(isDynamicSiteFailure).map(formatFailure),
+      ]
+        .filter(Boolean)
+        .join("\n"),
     );
   }
   return sections.join("\n\n");
@@ -751,6 +792,27 @@ export function formatAcceptedViolations(waived, unresolvedDecisionRefs) {
   ].join("\n\n");
 }
 
+/**
+ * The could-not-look section: the reasons a run that found no violation is
+ * still not a pass, spelled the same way the JSON envelope words them
+ * (`../verdict.mjs`'s `coverageIncompleteReasons`, joined into
+ * `decision.reason`).
+ *
+ * "✔ no boundary violations" states only the boundary half of the verdict —
+ * on a run whose exit is 3, the reader needs the next lines to say WHY the
+ * run failed despite it, or the checkmark reads as a clean tree (P1-04's
+ * repro: an exit-3 run printed the checkmark and nothing else). Empty exactly
+ * when the run reached a verdict on everything it looked at.
+ *
+ * @param {string[]} coverageIncomplete The verdict's reason clauses, in
+ *   `verdictFor`'s pinned order.
+ * @returns {string} Empty exactly when there is nothing to disclose.
+ */
+export function formatCoverageIncomplete(coverageIncomplete) {
+  if (coverageIncomplete.length === 0) return "";
+  return coverageIncomplete.map((reason) => `⚠ ${reason}`).join("\n");
+}
+
 /**
  * The whole report, violations first.
  *
@@ -766,7 +828,7 @@ export function formatAcceptedViolations(waived, unresolvedDecisionRefs) {
  * summary line above only says "no boundary violations" when there is nothing
  * a waiver is covering either.
  *
- * @param {{violations: object[], failures: object[], analyzed: number, projects: number, imports: number, goWork?: object|null, tsconfigPaths?: object|null, declaredEdges?: object|null, intent?: object|null, fitness?: object|null, fitnessOverall?: {verdict: string}|null, customRules?: {decisions: object[], overall: {verdict: string}}|null, coverageGaps?: object[], notes?: string[], policy?: {profile: string|null, source: string, fingerprint: string}|null, unresolvedDecisionRefs?: Set<string>}} run
+ * @param {{violations: object[], failures: object[], analyzed: number, projects: number, imports: number, goWork?: object|null, tsconfigPaths?: object|null, declaredEdges?: object|null, intent?: object|null, fitness?: object|null, fitnessOverall?: {verdict: string}|null, customRules?: {decisions: object[], overall: {verdict: string}}|null, coverageGaps?: object[], notes?: string[], policy?: {profile: string|null, source: string, fingerprint: string}|null, unresolvedDecisionRefs?: Set<string>, coverageIncomplete?: string[]}} run
  * @returns {string}
  */
 export function formatReport({
@@ -786,6 +848,7 @@ export function formatReport({
   notes = [],
   policy = null,
   unresolvedDecisionRefs,
+  coverageIncomplete = [],
 }) {
   const inspected =
     `${imports} import${imports === 1 ? "" : "s"} in ${analyzed} file${analyzed === 1 ? "" : "s"} ` +
@@ -829,6 +892,13 @@ export function formatReport({
     }
   }
 
+  // The could-not-look reasons render BEFORE the per-feature sections, right
+  // after the verdict summary they qualify: a reader who just read "✔ no
+  // boundary violations" needs the next lines to be the reason the exit is
+  // still 3, not go.work bookkeeping.
+  const coverageIncompleteSection = formatCoverageIncomplete(coverageIncomplete);
+  if (coverageIncompleteSection !== "") sections.push(coverageIncompleteSection);
+
   const goWorkSection = formatGoWork(goWork);
   if (goWorkSection !== "") sections.push(goWorkSection);
 

package/src/verdict.mjs

@@ -4,10 +4,10 @@
  *
  * Both sit here rather than in `../cli.mjs` because two callers need them and
  * only one of the two is the CLI shell: `./commands/check.mjs` words its own
- * `--format json` envelope from `verdictFor`, and `../cli.mjs`'s `runCheck`
- * takes the process's exit code from the same call. `../cli.mjs` re-exports
- * `EXIT` under its own name, so every importer that already reads it from
- * there keeps working.
+ * `--format json` envelope's `status` and `exitCode` from `verdictFor`, and
+ * `../cli.mjs`'s `runCheck` takes the process's exit code from the same call.
+ * `../cli.mjs` re-exports `EXIT` under its own name, so every importer that
+ * already reads it from there keeps working.
  */
 
 import { buildDecision } from "./report/evidence.mjs";
@@ -18,6 +18,29 @@ export const EXIT = Object.freeze({
   usage: 2,
   error: 3,
 });
+/**
+ * The coverage clauses of a no-verdict reason, spelled once — the strings
+ * `verdictFor` joins into `decision.reason` and `check`'s text report renders
+ * beside its headline, so the two faces cannot disagree about WHY a run
+ * failed to reach a verdict. The clauses cover only the three coverage axes
+ * (whole-file failures, unresolved sites, zero analysis); the intent,
+ * fitness and custom-rule clauses stay local to `verdictFor` because they
+ * name verdict surfaces the coverage counts cannot see.
+ *
+ * @param {{unchecked: number, blindSpots: number, analyzed: number}} counts
+ * @returns {string[]} One clause per failed coverage axis, in pinned order.
+ */
+export function coverageIncompleteReasons({ unchecked, blindSpots, analyzed }) {
+  return [
+    unchecked > 0
+      ? `${unchecked} file${unchecked === 1 ? "" : "s"} could not be analyzed — coverage incomplete`
+      : null,
+    blindSpots > 0
+      ? `${blindSpots} import site${blindSpots === 1 ? "" : "s"} could not be resolved — coverage incomplete`
+      : null,
+    analyzed === 0 ? "no file in scope could be analyzed — coverage incomplete" : null,
+  ].filter(Boolean);
+}
 /**
  * The one place that turns a run's counts into the verdict every format
  * agrees on. `runCheck` uses it for the process's exit code; `check` uses the
@@ -41,8 +64,12 @@ export const EXIT = Object.freeze({
  * with no findings), which makes a regression in this mapping a loud error
  * rather than a silent one.
  *
- * @param {{violations: number, declaredEdgeFindings: number, goWorkDrift: number, tsconfigPathsDead: number, intentFindings: number, intentUnresolved: number, intentUnresolvedDecisionRefs?: number, unchecked: number, fitnessFail?: number, fitnessUnknown?: number, customRuleFail?: number, customRuleUnknown?: number}} counts
- * @returns {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3, decision: object}}
+ * @param {{violations: number, declaredEdgeFindings: number, goWorkDrift: number, tsconfigPathsDead: number, intentFindings: number, intentUnresolved: number, intentUnresolvedDecisionRefs?: number, unchecked: number, analyzed: number, blindSpots: number, fitnessFail?: number, fitnessUnknown?: number, customRuleFail?: number, customRuleUnknown?: number}} counts
+ * @returns {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3, reasons: string[], decision: object}}
+ *   `reasons` is the coverage clause list behind this verdict — the
+ *   could-not-look clauses on the findings and no-verdict lanes, empty on the
+ *   clean one. `decision.reason` joins it with the intent/fitness/custom
+ *   clauses where the lane is no-verdict.
  */
 export function verdictFor({
   violations,
@@ -53,11 +80,14 @@ export function verdictFor({
   intentUnresolved,
   intentUnresolvedDecisionRefs = 0,
   unchecked,
+  analyzed,
+  blindSpots,
   fitnessFail = 0,
   fitnessUnknown = 0,
   customRuleFail = 0,
   customRuleUnknown = 0,
 }) {
+  const coverageReasons = coverageIncompleteReasons({ unchecked, blindSpots, analyzed });
   if (
     violations > 0 ||
     declaredEdgeFindings > 0 ||
@@ -74,9 +104,10 @@ export function verdictFor({
     return {
       status: "findings",
       exitCode: EXIT.violations,
+      reasons: coverageReasons,
       decision: buildDecision({
         status: "findings",
-        coverageComplete: unchecked === 0,
+        coverageComplete: unchecked === 0 && blindSpots === 0 && analyzed > 0,
         findings:
           violations +
           declaredEdgeFindings +
@@ -90,52 +121,63 @@ export function verdictFor({
   }
   if (
     unchecked > 0 ||
+    // An unresolvable site was seen but never judged (#595): named in
+    // coverage.blindSpots, and echoed here so the exit says it too — a
+    // pass over a site the run could not read claims a verdict it does
+    // not hold.
+    blindSpots > 0 ||
+    // A run that analyzed nothing judged nothing (#599) — a scope that
+    // selected no project-owned file, or in-scope files no analyzer
+    // claims. Judging nothing is not finding nothing.
+    analyzed === 0 ||
     intentUnresolved > 0 ||
     intentUnresolvedDecisionRefs > 0 ||
     fitnessUnknown > 0 ||
     customRuleUnknown > 0
   ) {
+    // The list is built before the return so `decision.reason` joins the very
+    // array the envelope's `reasons` carries — one list, two renderings, and
+    // neither can drift from the other.
+    const reasons = [
+      ...coverageReasons,
+      // The could-not-look condition, named so a reader knows WHICH half of
+      // the run did not reach a verdict (I3). When read-only coverage and
+      // intent both failed, name both — a reason naming only the file count
+      // would hide the unresolved intent boundary from a reader acting on
+      // the reason alone (it stays visible in result.intent.unresolved, and
+      // status is still no-verdict, so nothing is silent). Each clause below
+      // is independent of the others — none is gated on a sibling clause
+      // being zero — so a tree that fails on several axes at once names
+      // every one of them, not only the first the array happens to hit.
+      intentUnresolved > 0
+        ? `${intentUnresolved} architecture-intent boundary or row${intentUnresolved === 1 ? "" : "s"} could not be established`
+        : null,
+      intentUnresolvedDecisionRefs > 0
+        ? `${intentUnresolvedDecisionRefs} intent row${intentUnresolvedDecisionRefs === 1 ? "" : "s"} ${intentUnresolvedDecisionRefs === 1 ? "cites" : "cite"} a decisionRef that does not resolve`
+        : null,
+      fitnessUnknown > 0
+        ? `${fitnessUnknown} fitness functions${fitnessUnknown === 1 ? "" : "s"} could not be determined`
+        : null,
+      customRuleUnknown > 0
+        ? `${customRuleUnknown} custom rule${customRuleUnknown === 1 ? "" : "s"} could not be judged`
+        : null,
+    ].filter(Boolean);
     return {
       status: "no-verdict",
       exitCode: EXIT.error,
+      reasons,
       decision: buildDecision({
         status: "no-verdict",
-        coverageComplete: unchecked === 0,
+        coverageComplete: unchecked === 0 && blindSpots === 0 && analyzed > 0,
         findings: 0,
-        // The could-not-look condition, named so a reader knows WHICH half of
-        // the run did not reach a verdict (I3). When read-only coverage and
-        // intent both failed, name both — a reason naming only the file count
-        // would hide the unresolved intent boundary from a reader acting on
-        // the reason alone (it stays visible in result.intent.unresolved, and
-        // status is still no-verdict, so nothing is silent). Each clause below
-        // is independent of the others — none is gated on a sibling clause
-        // being zero — so a tree that fails on several axes at once names
-        // every one of them, not just the first the array happens to check.
-        reason: [
-          unchecked > 0
-            ? `${unchecked} file${unchecked === 1 ? "" : "s"} could not be analyzed — coverage incomplete`
-            : null,
-          intentUnresolved > 0
-            ? `${intentUnresolved} architecture-intent boundary or row${intentUnresolved === 1 ? "" : "s"} could not be established`
-            : null,
-          intentUnresolvedDecisionRefs > 0
-            ? `${intentUnresolvedDecisionRefs} intent row${intentUnresolvedDecisionRefs === 1 ? "" : "s"} ${intentUnresolvedDecisionRefs === 1 ? "cites" : "cite"} a decisionRef that does not resolve`
-            : null,
-          fitnessUnknown > 0
-            ? `${fitnessUnknown} fitness function${fitnessUnknown === 1 ? "" : "s"} could not be determined`
-            : null,
-          customRuleUnknown > 0
-            ? `${customRuleUnknown} custom rule${customRuleUnknown === 1 ? "" : "s"} could not be judged`
-            : null,
-        ]
-          .filter(Boolean)
-          .join("; "),
+        reason: reasons.join("; "),
       }),
     };
   }
   return {
     status: "ok",
     exitCode: EXIT.ok,
+    reasons: [],
     decision: buildDecision({
       status: "ok",
       coverageComplete: true,