@ecoma-io/archkeep 0.22.2 → 0.24.0

package/src/commands/README.md

@@ -377,10 +377,19 @@ the resolution order.
   `check` folds into the fitness exit lanes plus the finding catalogue SARIF's
   descriptors are built from; it prints nothing and decides no exit code.
 
-- **`edge-constraints.mjs`** — edge-constraint analysis shared by `diff` and
-  `impact`. Judges a single graph edge against the `depConstraints` table,
-  producing violations with their constraint rows. Checks only tag-based rules
-  (`onlyDependOnLibsWithTags`, `notDependOnLibsWithTags`,
-  `projectWithoutTagsCannotHaveDependencies`); npm/circular/lazy-load rules
-  need import-site details that graph edges do not carry. A consumer who needs
-  the complete verdict should run `check`.
+- **`impact-reachability.mjs`** — reverse reachability (`computeImpact`: a
+  project's direct and transitive dependents) shared by the `impact`,
+  `scenario` and `context --plan` commands and the canonical evaluator
+  (`./evaluation-primitives.mjs`). It lives apart from `./impact.mjs` rather
+  than inside it because that module drives `./impact-statement.mjs`, which
+  drives the evaluator — holding the walk in the command module is what made
+  `evaluation-primitives → impact → impact-statement → evaluation-primitives`
+  the engine's only import cycle (#644). `./impact.mjs` re-exports
+  `computeImpact`, so its existing importers keep resolving; new code imports
+  this module.
+
+The edge-constraint analysis `diff`, `impact` and `check` share is not one of
+these modules: it judges graph edges, so it lives in the rules layer whose
+constraint table and tag matching it reads (`../rules/edge-constraints.mjs`) —
+which is also what lets `../lsp/diagnose.mjs` share it without importing from
+this application layer (#649).

package/src/commands/change-intent.mjs

@@ -41,6 +41,8 @@
 
 import { readFile as readFileFromDisk } from "node:fs/promises";
 
+import { describe, isPlainObject } from "../values.mjs";
+
 /** The only `version` this module accepts. A different value is a load error. */
 export const CHANGE_INTENT_VERSION = "1";
 
@@ -108,17 +110,6 @@ export function edgePairKey({ from, to }) {
   return `${from}\u0000${to}`;
 }
 
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
 /** `key` on `obj` that is not one of `allowed` — the reject-by-name rule. */
 function unknownKeys(obj, allowed) {
   return Object.keys(obj).filter((key) => !allowed.includes(key));

package/src/commands/check.mjs

@@ -12,6 +12,7 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
 
+import { foldMarkdownTrack } from "../analysis/markdown.mjs";
 import {
   blindSpotRows,
   fileFailure,
@@ -23,11 +24,15 @@ import { stripTrailingSlashes } from "../path-util.mjs";
 import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import { suppressionFate } from "../governance/waiver.mjs";
-import { resolveCommandContext, unownedGapWithoutRunConfiguration } from "./context.mjs";
+import {
+  resolveCommandContext,
+  unownedGapWithoutRunConfiguration,
+  untrackedOwnedFiles,
+} from "./context.mjs";
 import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
-import { declaredEdgeViolationsForCheck } from "./edge-constraints.mjs";
+import { declaredEdgeViolationsForCheck, judgeEdge } from "../rules/edge-constraints.mjs";
 import { customRulesForCheck, declaresCustomRules } from "./custom-rules.mjs";
 import { driftForCheck } from "./drift.mjs";
 import { fitnessForCheck } from "./fitness.mjs";
@@ -36,15 +41,17 @@ import { resolvePolicy } from "./policy.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
 import { compareGoWork, parseGoWorkUse } from "../go-work.mjs";
+import { mergeDeclaredEdges } from "../providers/native/graph.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatSarif } from "../report/sarif.mjs";
 import { formatReport } from "../report/text.mjs";
 import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
-import { evaluateRun, exemptResolvedFile } from "../rules/index.mjs";
+import { applySuppressionTable, evaluateRun, exemptResolvedFile } from "../rules/index.mjs";
+import { buildReachability } from "../rules/reachability.mjs";
 import { orphanedNotDependOnTags, unmatchedConstraintRows } from "../rules/tags.mjs";
 import { judgeTsconfigPaths } from "../tsconfig-paths.mjs";
-import { verdictFor } from "../verdict.mjs";
-import { listTrackedFiles } from "../workspace.mjs";
+import { coverageComplete, verdictFor } from "../verdict.mjs";
+import { listTrackedFiles, listUntrackedFiles } from "../workspace.mjs";
 
 /**
  * A total order over violations, so a report's byte sequence is an invariant
@@ -184,10 +191,21 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
  * readers: a test drives the real analysis, the real rules and the real
  * report over a fixture tree, and pins the exact `file:line:column` a
  * developer would act on, without an Nx installation or a git repository.
+ * `listUntracked` is the third git seam, the one the tracked universe is
+ * audited against (#675): it answers with the worktree files the universe
+ * left out (`../workspace.mjs`'s `listUntrackedFiles`). It is injected
+ * separately rather than derived from `listFiles` because the two are only
+ * paired when BOTH are git's — a caller that injected a tracked universe has
+ * already decided what the whole tree is, and asking git what else exists
+ * would answer a different tree than the one `listFiles` named. That is why
+ * the default below resolves the real listing only when `listFiles` is also
+ * the real one, and treats an injected universe as the whole story: its
+ * untracked complement is empty by construction, not by claim.
  *
  * @param {{format: string, config: string|null, paths: string[],
  *   evidenceOut?: string|null}} options
- * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} context
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function,
+ *   listUntracked?: Function}} context
  * @returns {Promise<{report: string, violations: number, declaredEdgeFindings: number,
  *   goWorkDrift: number, tsconfigPathsDead: number, intentFindings: number,
  *   intentUnresolved: number, intentUnresolvedDecisionRefs: number, fitnessFail: number,
@@ -195,7 +213,10 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
  *   customRuleEvidence: {rule: string, bytes: Uint8Array}[], customRulesDeclared: boolean,
  *   analyzed: number, unchecked: number, blindSpots: number, waived?: number}>}
  */
-export async function check(options, { cwd, readGraph, listFiles = listTrackedFiles }) {
+export async function check(
+  options,
+  { cwd, readGraph, listFiles = listTrackedFiles, listUntracked },
+) {
   const commandContext = resolveCommandContext(
     { cwd, paths: options.paths },
     { readGraph, listFiles },
@@ -435,6 +456,41 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     }
   }
 
+  // The markdown document track, keyed by presence like every fold above it:
+  // a policy that declares no `markdown` block reaches nothing here and hears
+  // nothing anywhere — no edges, no failures, no envelope key — so a
+  // config-absent run is byte-identical to one this fold never existed for
+  // (`../../../../AGENTS.md`, "a change to what is reported on an unchanged
+  // workspace is a breaking change"). A policy that DOES declare one has its
+  // documents read (`../analysis/markdown.mjs`'s `foldMarkdownTrack`), the
+  // resolved pairings folded into the graph the way the declared manifest
+  // track's edges already are (`mergeDeclaredEdges`, the same dedup key), and
+  // every whole-file failure the read earned pushed into the same `failures`
+  // funnel the analysis uses — an unresolvable marker is an `unchecked` file,
+  // never a clean one.
+  //
+  // The fold runs BEFORE the walk below on purpose: a document pairing is a
+  // project-to-project dependency claim, and from here on this run's graph
+  // carries it exactly as it carries a csproj's `ProjectReference` — the tag
+  // rows, the circularity walk and the reachability behind them all read one
+  // graph, so a pairing cannot be legal here and violating in `context`.
+  // What it does not join is the twelve non-tag import-site rules: those need
+  // a specifier, a file and a resolution, and a document marker has none of
+  // them — it is judged as the EDGE it drew, the same 3-of-15 limit
+  // `declaredEdgeViolationsForCheck` documents for `implicit` edges.
+  let markdownTrack = null;
+  if (config !== null && config.markdown !== undefined) {
+    markdownTrack = foldMarkdownTrack({
+      tracked,
+      owned: commandContext.owned,
+      readFile: (file) => workspace.readFile(file),
+      workspace,
+      markdown: config.markdown,
+    });
+    mergeDeclaredEdges(graph, markdownTrack.edges);
+    failures.push(...markdownTrack.failures);
+  }
+
   // Both faces of one walk: the run's verdict, and the raw superset it was
   // picked from — every candidate up to each site's surviving group, including
   // the verdicts the suppression table removed to get there. `evaluate` alone
@@ -444,8 +500,66 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
   // the gate's waiver-expiry judgement below and the engine's are the same
   // judgement, not two reads of the clock a boundary instant could split.
   const now = referenceTime();
-  const { violations: judged, rawViolations } = evaluateRun(imports, graph, { ...config, now });
-  const violations = sortViolations(judged);
+  const { violations: judged, rawViolations: judgedRaw } = evaluateRun(imports, graph, {
+    ...config,
+    now,
+  });
+
+  // The document pairings' own verdicts, judged by the machinery that already
+  // existed: `judgeEdge` — the same function `declaredEdgeViolationsForCheck`
+  // runs `implicit` edges through, so a doc pairing and a declared manifest
+  // edge can never disagree about the same boundary — over the graph the fold
+  // above already joined, with reachability built once for the whole claim
+  // list. The same empty-table exit `declaredEdgeViolationsForCheck` takes: a
+  // workspace declaring no `depConstraints` has opted out of tag enforcement
+  // entirely, and folding `projectWithoutTagsCannotHaveDependencies` onto
+  // every marker anyway would flag an opted-out workspace for a reason its
+  // import sites are never flagged for. Each verdict is then reshaped into the
+  // exact `Violation` record `violationOf` builds — position and specifier
+  // from the MARKER (the line a reader edits is the document's), project and
+  // constraint from the edge — so suppression, waiver annotation, sorting and
+  // the SARIF face all treat it as the ordinary violation it is.
+  /** @type {object[]} */
+  const markdownRaw = [];
+  if (config !== null && markdownTrack !== null && config.depConstraints.length > 0) {
+    const reachability = buildReachability(graph);
+    for (const claim of markdownTrack.claims) {
+      for (const verdict of judgeEdge(
+        { source: claim.source, target: claim.target },
+        graph.nodes,
+        graph.dependencies,
+        config.depConstraints,
+        reachability,
+      )) {
+        markdownRaw.push({
+          sourceFile: claim.file,
+          line: claim.line,
+          column: claim.column,
+          specifier: claim.name,
+          kind: claim.type,
+          messageId: verdict.messageId,
+          message: verdict.message,
+          sourceProject: verdict.source,
+          targetProject: verdict.target,
+          constraint: verdict.constraint,
+          data: verdict.data,
+        });
+      }
+    }
+  }
+  // The same table, the same behaviour: a suppression row whose glob covers a
+  // document removes that document's verdict (or waives it, with the same
+  // expiry evidence an import-site waiver carries), and the RAW records join
+  // `rawViolations` below so a row covering only document verdicts still
+  // counts as alive — a table that is doing its job must not read as dead
+  // because the violations it removes live in a different fold.
+  const markdownViolations =
+    config !== null && markdownTrack !== null
+      ? applySuppressionTable(config.suppressions, markdownRaw, now)
+      : [];
+
+  const rawViolations = [...judgedRaw, ...markdownRaw];
+  const violations = sortViolations([...judged, ...markdownViolations]);
   // An ACTIVE waiver keeps the violation it accepts in the findings list,
   // marked `waivedBy` — the run is still non-zero (waiving does not flip
   // exit 1 → 0), and this count is the additive "accepted violations" number
@@ -686,7 +800,10 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     config !== null &&
     options.paths.length === 0 &&
     failures.length === 0 &&
-    (config.suppressions.length > 0 || config.depConstraints.length > 0 || coverageRows.length > 0)
+    (config.suppressions.length > 0 ||
+      config.depConstraints.length > 0 ||
+      coverageRows.length > 0 ||
+      config.markdown !== undefined)
   ) {
     const deadRows = [];
     // The third dead table: a `coverage.unowned` row matching no unowned file
@@ -737,6 +854,34 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
         );
       }
     }
+    // The document track's two dead tables, measured against what the fold
+    // actually selected (`markdownTrack.includeCounts`/`rowMatches` — the
+    // same counts the fold's own selection is built from, not a re-derivation
+    // that could disagree): an include glob matching no tracked document, and
+    // a marker row matching no line in any included document, both govern
+    // nothing while reading as enforced — every pairing the workspace meant
+    // to declare goes unjudged and the run stays green. A whole-file failure
+    // above already disabled this gate, so reaching here with a row that
+    // matched nothing means the tree genuinely has no such line.
+    if (markdownTrack !== null && config.markdown !== undefined) {
+      markdownTrack.includeCounts.forEach((count, index) => {
+        if (count > 0) return;
+        deadRows.push(
+          `markdown.include[${index}]: '${config.markdown.include[index]}' matches no tracked ` +
+            `document — the document track reads nothing, so every marker row below it governs ` +
+            `nothing while reading as enforced. Either the path was never right, or the ` +
+            `documents are not tracked`,
+        );
+      });
+      markdownTrack.rowMatches.forEach((count, index) => {
+        if (count > 0) return;
+        deadRows.push(
+          `markdown.markers[${index}]: the pattern matches no line in any included document — ` +
+            `this row extracts no pairing, so it enforces nothing while reading as enforced. ` +
+            `Either the documents do not carry the marker, or the pattern was never right`,
+        );
+      });
+    }
     if (deadRows.length > 0) {
       throw new Error(
         `archkeep: ${policySource ?? "the boundary config"} describes a workspace that does not ` +
@@ -791,6 +936,45 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     ...(unconstrainedImportNote === null ? [] : [unconstrainedImportNote]),
   ];
 
+  // The tracked-universe boundary, audited (#675): every file a project owns,
+  // that an analyzer could judge, and that this run never read because git
+  // does not track it yet. The universe above is `listFiles(root)` —
+  // `git ls-files` verbatim — so a file that was never `git add`-ed never
+  // entered it, and before this audit a run over such a tree printed the same
+  // clean verdict as a run over the whole tree, byte for byte, with nothing
+  // anywhere naming what the universe had left out. `untrackedOwnedFiles`
+  // (`./context.mjs`) narrows the complement to the files whose absence can
+  // change what the verdict claims; the ownership and language tests are the
+  // two this module already runs over the tracked list, reused rather than
+  // re-derived.
+  //
+  // The verdict posture is the `unowned-files` bargain, and the completeness
+  // law decides it: the three no-verdict axes (`verdictFor`'s `unchecked`,
+  // `blindSpots`, `analyzed`) are all about files the universe CONTAINED —
+  // a whole-file failure, an unjudged site, a run that judged nothing —
+  // and the precedent for withholding (zero analysis, #619/#620/#634) is a
+  // verdict that was VACUOUS, not one that was scoped. This run judged every
+  // file its universe held, so the verdict over that universe stands — exit
+  // code and `coverage.complete` unchanged, exactly as the `coverageGaps`
+  // channel's contract states (`../../../../docs/reference/json-output.md`:
+  // "no kind changes `complete`, `status`, or the exit code") — but the clean
+  // verdict over a partial universe is now distinguishable from a clean
+  // verdict over the whole one, in both faces, with the full list a parser
+  // can act on. What is forbidden here is not exit 0; it is silence.
+  //
+  // Workspace-wide on purpose, the same posture `unownedGap` holds: a
+  // `check <path>` run must not be able to hide an unread file elsewhere in
+  // the tree by naming a path that excludes it. And resolved through the
+  // `listUntracked` seam's conditional default — an injected universe is the
+  // whole story (see this function's doc), so the audit asks git only when
+  // git also built the universe.
+  const untrackedListing =
+    listUntracked ?? (listFiles === listTrackedFiles ? listUntrackedFiles : null);
+  const untrackedOwned = untrackedOwnedFiles({
+    untracked: untrackedListing === null ? [] : untrackedListing(root),
+    projects: commandContext.workspace.projects,
+  });
+
   // A polyglot coverage gap: the Nx graph carries no polyglot edges because
   // the plugin is not registered, but polyglot manifests exist under project
   // roots. The checker still judged every import it found — this is not a
@@ -864,6 +1048,13 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     ...(unsupportedLanguageFiles.length > 0
       ? [{ kind: "unsupported-language", files: [...unsupportedLanguageFiles].sort() }]
       : []),
+    // The universe audit above (#675): project-owned, analyzable files the
+    // worktree holds that this run never read, because the universe is the
+    // tracked set. Contributed only when the list is non-empty, so a tree
+    // with nothing beyond its index reports exactly the bytes it reported
+    // before; sorted already, by the one function that built it, so the row's
+    // bytes cannot vary with git's worktree-traversal order (E-F10).
+    ...(untrackedOwned.length > 0 ? [{ kind: "untracked-files", files: untrackedOwned }] : []),
   ];
 
   // One verdict computation for both faces: the JSON envelope spreads it and
@@ -913,8 +1104,14 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
               // Complete means the run judged everything in scope: no
               // whole-file failure (unchecked), no unresolvable site (#595),
               // and at least one file analyzed (#599 — a run that judged
-              // nothing has no verdict to claim).
-              complete: unchecked === 0 && blindSpotCount === 0 && analyzed > 0,
+              // nothing has no verdict to claim). Read from the one predicate
+              // `verdictFor`'s decision face reads, so this field and the
+              // envelope's `decision.coverageComplete` are one derivation —
+              // the counts are this command's (the go.work/tsconfig failures
+              // pushed above and the accepted files withdrawn above make the
+              // universe wider than `commandContext.analysis`), the law is
+              // not.
+              complete: coverageComplete({ unchecked, blindSpotCount, analyzed }),
               projects: Object.keys(graph.nodes).length,
               analyzedFiles: analyzed,
               imports: imports.length,
@@ -965,6 +1162,31 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
                       judged: declaredEdges.judged,
                       findings: declaredEdges.findings,
                     },
+              // The document track is a policy DECLARATION, so it takes the
+              // same omitted-key-not-null discipline the intent/fitness/
+              // customRules blocks below state: a workspace whose policy
+              // declares no `markdown` block gets no key at all, and its
+              // envelope is byte-identical to the one it got before this
+              // section existed. The findings themselves are NOT restated
+              // here — they are members of `violations` above (sorted with,
+              // suppressible by, and counted into the verdict exactly like
+              // every import-site violation), so an array here would be one
+              // fact counted in two places; the block states what the track
+              // DID: how many documents the globs selected, how many markers
+              // they carried, where each resolution went.
+              ...(markdownTrack === null
+                ? {}
+                : {
+                    markdown: {
+                      checked: true,
+                      documents: markdownTrack.documents,
+                      judged: markdownTrack.judged,
+                      resolved: markdownTrack.resolved,
+                      ...(markdownTrack.selfPaired > 0
+                        ? { selfPaired: markdownTrack.selfPaired }
+                        : {}),
+                    },
+                  }),
               // Intent is a governance DECLARATION, absent when the workspace
               // chose not to make one: the key is omitted, never written as
               // null — the design contract `docs/reference/json-output.md` will

package/src/commands/completeness.mjs

@@ -491,38 +491,6 @@ export function buildEvidenceComplete({
   };
 }
 
-/**
- * Asserts that the Evidence-Complete contract is satisfied.
- * Throws with a detailed message listing every failing gate.
- *
- * @param {EvidenceCompleteContract} ec The Evidence-Complete contract to verify.
- * @returns {void}
- * @throws {Error} When any gate fails.
- */
-export function assertEvidenceComplete(ec) {
-  if (ec.overallComplete) return;
-
-  const contractType = ec.contractType || EVALUATION_CONTRACT_TYPES.SCENARIO;
-  const failures = [];
-  for (const gate of EVIDENCE_COMPLETE_GATES) {
-    const g = ec.gates[gate.key];
-    // Skip non-required gates for this contract type
-    if (g.required === false) continue;
-    if (!g.pass) {
-      failures.push(`${gate.label}: ${JSON.stringify(g.value)} (expected pass)`);
-    }
-  }
-
-  if (failures.length === 0) return;
-
-  throw new Error(
-    `Evidence-Complete contract not satisfied.\n` +
-      `  Contract type: ${contractType}\n` +
-      `  Overall: ${ec.overallStatus}\n` +
-      `  Failed gates:\n    ${failures.join("\n    ")}`,
-  );
-}
-
 // ---------------------------------------------------------------------------
 // Governance completeness
 // ---------------------------------------------------------------------------

package/src/commands/context-command.mjs

@@ -32,16 +32,12 @@
  * than explaining constraints from a graph whose edges silently under-represent
  * the real architecture.
  */
-import {
-  blindSpotRows,
-  isWholeFileFailure,
-  unresolvableLiteralCount,
-} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
-import { judgeEdge } from "./edge-constraints.mjs";
+import { judgeEdge } from "../rules/edge-constraints.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatContextReport } from "../report/context-text.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { readAdrContext } from "./adr.mjs";
 import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
@@ -150,27 +146,23 @@ export function contextCommand(projectName, commandContext, config) {
     );
   }
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  // The same completeness `check` claims (#595, #599): unjudged sites and
-  // a zero-analyzed run defeat it here exactly as they do there, so a
-  // context report cannot look complete over a tree the run could not
-  // fully read.
-  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
-  const complete =
-    notAnalyzed.length === 0 && blindSpotCount === 0 && commandContext.analysis.analyzed > 0;
-  const status = complete ? "ok" : "no-verdict";
-  const exitCode = complete ? 0 : 3;
+  // The completeness verdict is the shared constructor's, not this file's —
+  // the same law `graph`/`discover` run (#595, #599): unjudged sites and a
+  // zero-analyzed run defeat it here exactly as they do there, so a context
+  // report cannot look complete over a tree the run could not fully read
+  // while the faces beside it refuse the same tree. The restatement this
+  // replaces carried all three axes, so composing it moves no byte on any
+  // input.
+  const verdict = coverageVerdict(commandContext);
+  const { complete, status, exitCode } = verdict;
 
   const coverage = {
     complete,
     projects: Object.keys(graph.nodes).length,
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
-    notAnalyzed,
-    blindSpots: blindSpotRows(commandContext.analysis.failures),
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
     notes: [
       "per-edge violations cover only depConstraints (3 of 15 violation types). " +
         "A dependency with no violations here may still violate npm-ban, circular-dependency, " +

package/src/commands/context.mjs

@@ -35,7 +35,7 @@ import { jvmIndexFailures } from "../analysis/jvm/packages.mjs";
 import { languageOf } from "../analysis/registry.mjs";
 import { pythonUnmodelledFailures } from "../analysis/python.mjs";
 import { rustManifestFailures } from "../analysis/rust.mjs";
-import { dedupeWholeFileFailures, fileFailure } from "../analysis/source-util.mjs";
+import { dedupeWholeFileFailures, fileFailure, projectOwning } from "../analysis/source-util.mjs";
 import {
   DEFAULT_OPTIONS,
   NX_CONFIG_FILE,
@@ -54,6 +54,7 @@ import {
 } from "../providers/moon.mjs";
 import { nativeProvider } from "../providers/native/index.mjs";
 import { mergeDeclaredEdges } from "../providers/native/graph.mjs";
+import { requireSingleProjectModel } from "../providers/model-gate.mjs";
 import {
   resolveDeclaredManifestEdges,
   resolveDeclaredManifestFailures,
@@ -119,7 +120,8 @@ function readFileAbsolute(path) {
 
 /**
  * Which Moon directory marks `root` — or none. Presence facts only; see
- * `requireSingleProjectModel` below for the one-decision gate.
+ * `requireSingleProjectModel` (`../providers/model-gate.mjs`) for the
+ * one-decision gate.
  *
  * @param {string} root
  * @returns {{hasNx: boolean, hasNative: boolean, hasMoon: boolean}}
@@ -132,48 +134,6 @@ export function markersAt(root) {
   };
 }
 
-/**
- * The one gate deciding whether `root` may be judged at all: more than ONE
- * project-model marker present is refused, naming what conflicts.
- *
- * Every entry point that picks a provider must answer this identically —
- * `resolveCommandContext` below reads it before any command runs, and
- * `../lsp/workspace-index.mjs`'s index build reads it before choosing a
- * branch. A second copy of the condition was exactly how the faces drifted
- * apart once: the CLI refused a tree carrying a Moon directory beside
- * `nx.json`/`archkeep.json` while the editor indexed it anyway — a clean
- * diagnostic list over a tree nobody agreed could be judged (#223's silent
- * shape, one level up). Moon-versus-Moon coexistence (`.moon/` AND
- * `.config/moon/`) is refused inside `../providers/moon.mjs`'s
- * `moonMarkerAt`, which this gate calls first; the cross-family pairs are
- * refused here, all in the same terms: which model to judge against is a
- * decision nobody made, not one this tool can make for them.
- *
- * @param {string} root
- * @param {{exists?: (path: string) => boolean}} [io] Injectable existence
- *   test (absolute paths), so a test drives this without a filesystem.
- * @returns {{hasNx: boolean, hasNative: boolean, moonMarker: string|null}}
- *   The facts a provider choice needs; `moonMarker` names whichever Moon
- *   directory is present, `null` when neither spelling is.
- * @throws {Error} when more than one marker is present.
- */
-export function requireSingleProjectModel(root, { exists = existsSync } = {}) {
-  const moonMarker = moonMarkerAt(root, { exists });
-  const hasNx = exists(join(root, NX_CONFIG_FILE));
-  const hasNative = exists(join(root, ARCHKEEP_MODEL_FILE));
-  const refusal = (a, b) =>
-    new Error(
-      `archkeep: ${root} declares both ${a} and ${b} — this tool judges a workspace ` +
-        `against exactly one project model, and a tree carrying both is a decision nobody made ` +
-        `rather than one this tool can make for them. Remove whichever one is not the ` +
-        `workspace's real source of truth for projects and tags.`,
-    );
-  if (moonMarker !== null && hasNx) throw refusal(moonMarker, NX_CONFIG_FILE);
-  if (moonMarker !== null && hasNative) throw refusal(moonMarker, ARCHKEEP_MODEL_FILE);
-  if (hasNx && hasNative) throw refusal(NX_CONFIG_FILE, ARCHKEEP_MODEL_FILE);
-  return { hasNx, hasNative, moonMarker };
-}
-
 /**
  * Every marker a workspace root may be recognised by, as one list.
  *
@@ -191,7 +151,8 @@ export function requireSingleProjectModel(root, { exists = existsSync } = {}) {
  * selected the user's home directory as a workspace through `~/.moon`,
  * moonrepo's user-level state directory (#339). A bare `.moon` beside an
  * `nx.json` at a root already chosen is a different question, and stays with
- * `requireSingleProjectModel`'s directory-presence gate below.
+ * `requireSingleProjectModel`'s directory-presence gate
+ * (`../providers/model-gate.mjs`).
  *
  * @type {string[]}
  */
@@ -485,6 +446,43 @@ export function unownedGapWithoutRunConfiguration(gap, configNames) {
   };
 }
 
+/**
+ * The population a tracked-file universe silently leaves out (#675): files
+ * present in the worktree that git does not track, that a project owns, and
+ * that an analyzer could have judged — the exact complement of the universe
+ * `listTrackedFiles` cuts, narrowed to the files whose absence changes what a
+ * verdict can claim.
+ *
+ * Ownership is decided by `projectOwning` — the same predicate
+ * `createWorkspace` attributed the tracked list with, so a file cannot be
+ * "owned" here and unowned there — and the language test is the same one
+ * `unownedAnalyzableFiles` above applies: a file no analyzer claims (a
+ * README, a manifest, an image) could never have entered a verdict, so naming
+ * it would be a gap that fires on every work-in-progress tree and teaches a
+ * reader to skip the line it is written on. Both filters reuse existing
+ * answers; neither re-derives a judgment this module already owns.
+ *
+ * Sorted by plain string comparison, because the caller renders the list as
+ * report bytes: `git ls-files --others` answers in worktree-traversal order,
+ * and a row whose order varied with the order files happened to be created
+ * would break the byte-identity contract (`../../../../docs/reference/json-output.md`)
+ * for a tree that never changed.
+ *
+ * @param {{untracked: string[], projects: {name: string, root: string}[]}} args
+ *   `untracked` is `listUntrackedFiles`' answer (`../workspace.mjs`),
+ *   `projects` the workspace's `{name, root}` list — the same array
+ *   `createWorkspace` attributed the tracked files with.
+ * @returns {string[]} Sorted, deduplicated by construction (git lists a path
+ *   once), and empty exactly when the universe omitted nothing a verdict
+ *   could have reached.
+ */
+export function untrackedOwnedFiles({ untracked, projects }) {
+  const files = untracked.filter(
+    (file) => projectOwning(projects, file) !== null && languageOf(file) !== null,
+  );
+  return files.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
 /**
  * Resolves everything a command needs before it can ask its own question:
  * which workspace, which provider, which files, and what analyzing them
@@ -531,8 +529,9 @@ export function resolveCommandContext(
     );
   }
   // Which provider may judge at all — the one gate
-  // (`requireSingleProjectModel` above) every entry point shares, CLI and
-  // language server alike. Moon-versus-Moon rides it through `moonMarkerAt`.
+  // (`requireSingleProjectModel`, `../providers/model-gate.mjs`) every entry
+  // point shares, CLI and language server alike. Moon-versus-Moon rides it
+  // through `moonMarkerAt`.
   const { hasNative, moonMarker } = requireSingleProjectModel(root);
   const hasMoon = moonMarker !== null;