@ecoma-io/archkeep 0.22.2 → 0.24.0

package/src/verdict.mjs

@@ -8,9 +8,15 @@
  * `../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.
+ *
+ * `EXIT` is the one place a status→exit-code number is written. The
+ * status-keyed view of it, `EXIT_FOR_STATUS`, is derived from `EXIT` and is
+ * what the envelope's consistency check (`./report/json.mjs`) asserts against,
+ * so a consumer-facing status and the process's own exit code can never drift
+ * into two encodings of one contract.
  */
 
-import { buildDecision } from "./report/evidence.mjs";
+import { buildDecision } from "./governance/verdict.mjs";
 
 export const EXIT = Object.freeze({
   ok: 0,
@@ -18,6 +24,20 @@ export const EXIT = Object.freeze({
   usage: 2,
   error: 3,
 });
+
+/**
+ * The envelope `status`→`exitCode` view of `EXIT` — the one mapping
+ * `jsonEnvelope` asserts every command's envelope against. Derived from
+ * `EXIT` rather than restated, so the numbers are written exactly once;
+ * `usage` has no status because a usage error never reaches an envelope.
+ *
+ * @type {Readonly<Record<"ok"|"findings"|"no-verdict", 0|1|3>>}
+ */
+export const EXIT_FOR_STATUS = Object.freeze({
+  ok: EXIT.ok,
+  findings: EXIT.violations,
+  "no-verdict": EXIT.error,
+});
 /**
  * The coverage clauses of a no-verdict reason, spelled once — the strings
  * `verdictFor` joins into `decision.reason` and `check`'s text report renders
@@ -41,6 +61,33 @@ export function coverageIncompleteReasons({ unchecked, blindSpots, analyzed }) {
     analyzed === 0 ? "no file in scope could be analyzed — coverage incomplete" : null,
   ].filter(Boolean);
 }
+
+/**
+ * The one completeness predicate — the three coverage axes conjoined, the
+ * boolean twin of `coverageIncompleteReasons` directly above, which words the
+ * same axes as clauses. `coverageVerdict` (`./commands/coverage-verdict.mjs`)
+ * reads its `complete` from here, `verdictFor` reads the decision's
+ * `coverageComplete` from here, and `check`'s coverage block reads its
+ * `complete` from here — three faces of one claim, so the envelope's
+ * `coverage.complete` and its `decision.coverageComplete` cannot disagree
+ * about a run neither re-derives from the other.
+ *
+ * The counts come from the caller because a command's coverage universe is
+ * its own: `check`'s is wider than `commandContext.analysis` (the go.work and
+ * tsconfig whole-file failures it pushes, the accepted `coverage.unowned`
+ * files it withdraws), and each face feeds the counts it is a claim about. A
+ * caller that reads plain `commandContext.analysis` should call
+ * `coverageVerdict` instead — this predicate is the law's last step, not the
+ * place failure classes get decided (`./analysis/source-util.mjs`'s
+ * classifiers own that line).
+ *
+ * @param {{unchecked: number, blindSpotCount: number, analyzed: number}} counts
+ * @returns {boolean} Whether the run judged everything in its scope.
+ */
+export function coverageComplete({ unchecked, blindSpotCount, analyzed }) {
+  return unchecked === 0 && blindSpotCount === 0 && analyzed > 0;
+}
+
 /**
  * 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
@@ -57,7 +104,7 @@ export function coverageIncompleteReasons({ unchecked, blindSpots, analyzed }) {
  * "checked, and fine".
  *
  * The `decision` is the canonical 4-state verb of the same verdict
- * (`./report/evidence.mjs`), built from the same counts so the envelope's
+ * (`./governance/verdict.mjs`), built from the same counts so the envelope's
  * `status` and its `decision.verdict` cannot disagree: `ok`→`pass`,
  * `findings`→`fail`, `no-verdict`→`unknown`. `buildDecision` throws on any
  * invariant the counts violate (a `pass` over incomplete coverage, a `fail`
@@ -103,11 +150,15 @@ export function verdictFor({
   ) {
     return {
       status: "findings",
-      exitCode: EXIT.violations,
+      exitCode: EXIT_FOR_STATUS.findings,
       reasons: coverageReasons,
       decision: buildDecision({
         status: "findings",
-        coverageComplete: unchecked === 0 && blindSpots === 0 && analyzed > 0,
+        // The one completeness predicate, not a restatement: the decision's
+        // `coverageComplete` and the envelope's `coverage.complete` are the
+        // same claim about the same counts (`check` feeds both from one
+        // object), so they read it from one expression.
+        coverageComplete: coverageComplete({ unchecked, blindSpotCount: blindSpots, analyzed }),
         findings:
           violations +
           declaredEdgeFindings +
@@ -164,11 +215,11 @@ export function verdictFor({
     ].filter(Boolean);
     return {
       status: "no-verdict",
-      exitCode: EXIT.error,
+      exitCode: EXIT_FOR_STATUS["no-verdict"],
       reasons,
       decision: buildDecision({
         status: "no-verdict",
-        coverageComplete: unchecked === 0 && blindSpots === 0 && analyzed > 0,
+        coverageComplete: coverageComplete({ unchecked, blindSpotCount: blindSpots, analyzed }),
         findings: 0,
         reason: reasons.join("; "),
       }),
@@ -176,7 +227,7 @@ export function verdictFor({
   }
   return {
     status: "ok",
-    exitCode: EXIT.ok,
+    exitCode: EXIT_FOR_STATUS.ok,
     reasons: [],
     decision: buildDecision({
       status: "ok",

package/src/workspace.mjs

@@ -177,6 +177,35 @@ export function listTrackedFiles(workspaceRoot, { run = runProcess } = {}) {
   return out.split("\0").filter((path) => path !== "");
 }
 
+/**
+ * Every file present in the worktree that git does NOT track, workspace-
+ * relative — the complement of `listTrackedFiles` above, and the answer to
+ * the only question that pair can ask: what exists in the tree the tracked
+ * universe was cut from, but never entered it (#675).
+ *
+ * `--exclude-standard` is what keeps this answer a git answer and not a walk
+ * of our own: ignored files — build outputs, dependency installs, anything a
+ * `.gitignore`, `.git/info/exclude` or `core.excludesFile` names — are not
+ * part of the workspace's population, exactly as for the tracked list. The
+ * header's argument for `git ls-files` over a tree walk applies here with one
+ * more clause: walking the tree for the untracked half would need those ignore
+ * rules reimplemented, and the copy would drift from `.gitignore` the first
+ * time a build directory was added.
+ *
+ * The order is git's worktree-traversal order, not a sorted order — every
+ * consumer of this list sorts before it renders (a file list in a report must
+ * not vary with git's traversal), the same discipline
+ * `../commands/check.mjs`'s `sortViolations` states for the tracked list.
+ *
+ * @param {string} workspaceRoot
+ * @param {{ run?: typeof runProcess }} [io]
+ * @returns {string[]}
+ */
+export function listUntrackedFiles(workspaceRoot, { run = runProcess } = {}) {
+  const out = run("git", ["ls-files", "--others", "--exclude-standard", "-z"], workspaceRoot);
+  return out.split("\0").filter((path) => path !== "");
+}
+
 /**
  * The `Workspace` the analysis contract defines — `{ root, projects, filesOf,
  * readFile, tsConfig }` — plus the per-project file index it is built from,