@ecoma-io/archkeep 0.21.0 → 0.22.0

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,

package/src/workspace.mjs

@@ -598,12 +598,130 @@ export function selectFiles(files, paths, { root, cwd, tracked = files }) {
  * @param {{ analyze?: typeof analyzeFile }} [io] Injectable analyzer.
  * @returns {{ imports: object[], failures: object[], analyzed: number, analyzedFiles: string[] }}
  */
+/**
+ * Extensions that cannot carry an import or a boundary crossing, so their
+ * silence in analysis is never a coverage gap (#601): documentation,
+ * structured data and configuration, binary assets, generated lockfiles.
+ * A file in one of these formats has no imports for ANY analyzer to read —
+ * listing it under "unsupported language" would name every README in every
+ * workspace, and a gap that always fires teaches a reader to skip the line
+ * it is written on (the argument `./commands/context.mjs`'s
+ * `unownedAnalyzableFiles` already states for the same reason). The set must
+ * never intersect `LANGUAGE_BY_EXTENSION` — a format that cannot carry an
+ * import cannot become an analyzed language; `workspace.test.mjs` holds that
+ * line, because an entry that crossed it would turn this exemption into the
+ * silent direction.
+ */
+const DATA_BY_EXTENSION = Object.freeze(
+  new Set([
+    // Documentation.
+    ".md",
+    ".txt",
+    ".rst",
+    ".adoc",
+    // Structured data and configuration.
+    ".json",
+    ".json5",
+    ".jsonc",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".ini",
+    ".cfg",
+    ".conf",
+    ".properties",
+    ".xml",
+    // Binary assets.
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".webp",
+    ".ico",
+    ".bmp",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+    ".eot",
+    ".mp4",
+    ".mp3",
+    ".wav",
+    ".pdf",
+    // Archives and generated artifacts.
+    ".zip",
+    ".gz",
+    ".tgz",
+    ".tar",
+    ".br",
+    // Generated lockfiles.
+    ".lock",
+    ".sum",
+  ]),
+);
+
+/**
+ * Extension-less basenames that are workspace furniture, not source: legal
+ * notices and the two command files whose bodies are shell commands rather
+ * than imports. `languageOf` answers `null` for every dotless name already —
+ * this set is what keeps them out of the unsupported-language row without
+ * inventing a general dotfile list.
+ */
+const DOTLESS_FURNITURE = Object.freeze(
+  new Set([
+    "LICENSE",
+    "NOTICE",
+    "AUTHORS",
+    "CHANGELOG",
+    "CODEOWNERS",
+    "CONTRIBUTING",
+    "SECURITY",
+    "Makefile",
+    "Dockerfile",
+  ]),
+);
+
+/**
+ * Whether a file no analyzer claims is nevertheless not a coverage gap —
+ * the predicate `analyzeWorkspace` applies before naming a skipped file
+ * under `unsupported-language` (#601). Three exemptions, each with the same
+ * shape of reason: the file was never part of what this tool could judge.
+ *
+ * @param {string} sourceFile Workspace-relative path.
+ * @returns {boolean}
+ */
+export function exemptFromUnsupportedLanguage(sourceFile) {
+  const base = sourceFile.slice(sourceFile.lastIndexOf("/") + 1);
+  // Dotfiles are editor and tool state (`.gitignore`, `.env`, `.npmrc`).
+  if (base.startsWith(".")) return true;
+  const dot = base.lastIndexOf(".");
+  if (dot > 0 && DATA_BY_EXTENSION.has(base.slice(dot))) return true;
+  if (DOTLESS_FURNITURE.has(base)) return true;
+  // The polyglot manifests the manifest track itself reads — a `go.mod` is
+  // claimed by the engine one layer down, not skipped by it.
+  return basenameMatches(base, POLYGLOT_MANIFEST_NAMES, posix.matchesGlob);
+}
+
 export function analyzeWorkspace(workspace, files, { analyze = analyzeFile } = {}) {
   const imports = [];
   const failures = [];
   const analyzedFiles = [];
+  // Files whose extension no analyzer claims AND whose silence is a coverage
+  // gap (#601): skipped before reading, so naming them here is the only
+  // record the run will ever carry that they existed — "not analyzed" must
+  // not be indistinguishable from "not present". READMEs, manifests and
+  // other formats that cannot carry an import are exempt
+  // (`exemptFromUnsupportedLanguage` above): they are not an unsupported
+  // language, they are workspace furniture the tool has always declined.
+  const unsupportedLanguageFiles = [];
   for (const sourceFile of files) {
-    if (languageOf(sourceFile) === null) continue;
+    if (languageOf(sourceFile) === null) {
+      if (!exemptFromUnsupportedLanguage(sourceFile)) {
+        unsupportedLanguageFiles.push(sourceFile);
+      }
+      continue;
+    }
     const text = workspace.readFile(sourceFile);
     if (text === null) {
       failures.push(fileFailure(sourceFile, "could not be read"));
@@ -614,7 +732,13 @@ export function analyzeWorkspace(workspace, files, { analyze = analyzeFile } = {
     imports.push(...result.imports);
     failures.push(...result.failures);
   }
-  return { imports, failures, analyzed: analyzedFiles.length, analyzedFiles };
+  return {
+    imports,
+    failures,
+    analyzed: analyzedFiles.length,
+    analyzedFiles,
+    unsupportedLanguageFiles,
+  };
 }
 
 /** The polyglot manifests `polyglotManifests` looks for. */