@ecoma-io/archkeep 0.23.0 → 0.24.0

package/src/config.mjs

@@ -639,6 +639,155 @@ function findCoverageViolations(value) {
   return violations;
 }
 
+/**
+ * The one edge kind a markdown marker row can declare. The name is the claim
+ * the row makes about the graph: the captured symbol is resolved to the project
+ * that exports it, and the edge runs from the document's own project to that
+ * project. Kept as data rather than inlined at the check site so a second kind
+ * (`docs/reference/policy-schema.md`, "markdown") extends this list and nothing
+ * else — and so a row naming a kind this reader cannot draw is refused at load,
+ * where a law that would silently never run belongs.
+ *
+ * @type {Readonly<string[]>}
+ */
+export const MARKDOWN_EDGE_KINDS = Object.freeze(["resolvedExportOwner"]);
+
+/**
+ * One markdown marker row's problems, prefixed with its index.
+ *
+ * `pattern` is a regular-expression SOURCE matched against one line of a
+ * matched document at a time — never a glob, and never a whole-document
+ * match — because the position a violation reports must be a real
+ * `file:line:column` a developer can open. Its FIRST capture group must name
+ * the exported symbol the marker claims; a pattern with no capture group can
+ * match every line it is aimed at and still resolve nothing, which is a law
+ * that reads as enforced while testing nothing — refused here for the reason
+ * every dead shape in this file is refused.
+ *
+ * @param {object} row
+ * @param {number} index
+ * @returns {string[]}
+ */
+function markdownMarkerRowViolations(row, index) {
+  const at = `markdown.markers[${index}]`;
+  if (!isPlainObject(row)) return [`${at}: must be an object, got ${describe(row)}`];
+
+  const violations = [];
+  if (typeof row.pattern !== "string" || row.pattern === "") {
+    violations.push(
+      `${at}.pattern: must be a non-empty regular-expression source matched against one line of ` +
+        `a matched document, got ${describe(row.pattern)}`,
+    );
+  } else {
+    let compiled = null;
+    try {
+      compiled = new RegExp(row.pattern, "u");
+    } catch (cause) {
+      violations.push(
+        `${at}.pattern: '${row.pattern}' is not a valid regular expression under the 'u' flag ` +
+          `(${cause?.message ?? cause})`,
+      );
+    }
+    if (compiled !== null) {
+      // The capture count, read off the standard `pattern|` trick: matching the
+      // empty string yields one element per capture group plus the whole match,
+      // so a pattern that cannot capture anything reports `length === 1` here.
+      // Compiled in its own try, because the appended `|` can fail on a source
+      // the pattern alone accepted; the compile violation above is already
+      // reported in that case, and a second one would name the same row twice.
+      let captures;
+      try {
+        captures = (new RegExp(`${row.pattern}|`, "u").exec("")?.length ?? 1) - 1;
+      } catch {
+        captures = 1; // already refused above by the pattern's own compile check
+      }
+      if (captures < 1) {
+        violations.push(
+          `${at}.pattern: '${row.pattern}' has no capture group — the first capture group must ` +
+            `name the exported symbol the marker claims, and a pattern that captures nothing ` +
+            `resolves nothing while reading as enforced`,
+        );
+      }
+    }
+  }
+  if (!MARKDOWN_EDGE_KINDS.includes(row.edge)) {
+    violations.push(
+      `${at}.edge: ${describe(row.edge)} is not an edge kind this reader can draw — expected ` +
+        `${MARKDOWN_EDGE_KINDS.map((kind) => `"${kind}"`).join(", ")} (the captured symbol is ` +
+        `resolved to the project exporting it, and the edge runs there from the document's own ` +
+        `project)`,
+    );
+  }
+  for (const key of Object.keys(row)) {
+    if (key !== "pattern" && key !== "edge") {
+      violations.push(`${at}.${key}: not a markdown marker field — expected 'pattern' and 'edge'`);
+    }
+  }
+  return violations;
+}
+
+/**
+ * The markdown document track's problems, as messages; empty when it is
+ * well-formed. Pure, so a test drives it without a file on disk.
+ *
+ * `include` names the documents the track reads, by workspace-relative glob —
+ * the same glob machinery `boundarySuppressions` rows and `coverage.unowned`
+ * rows match with (`./rules/match.mjs`'s `safeMatchesGlob`), complexity-checked
+ * here at load for the reason a suppression's `path` is. An ABSOLUTE pattern is
+ * refused rather than left to match nothing forever: it can never match a
+ * workspace-relative document path, so declaring one is a law aimed outside
+ * the tree it governs (the family test is `ABSOLUTE_ARTIFACT_PATH`'s — the same
+ * "absolute in either path family" question, asked of a glob instead of a file).
+ *
+ * @param {unknown} value The parsed `markdown` value.
+ * @returns {string[]}
+ */
+function findMarkdownViolations(value) {
+  if (!isPlainObject(value)) {
+    return [`markdown: must be an object carrying 'include' and 'markers', got ${describe(value)}`];
+  }
+  const violations = [];
+  if (!Array.isArray(value.include) || value.include.length === 0) {
+    violations.push(
+      `markdown.include: must be a non-empty array of workspace-relative glob patterns naming ` +
+        `the documents the track reads, got ${describe(value.include)}`,
+    );
+  } else {
+    value.include.forEach((pattern, index) => {
+      const at = `markdown.include[${index}]`;
+      if (typeof pattern !== "string" || pattern === "") {
+        violations.push(
+          `${at}: must be a non-empty workspace-relative glob, got ${describe(pattern)}`,
+        );
+      } else if (ABSOLUTE_ARTIFACT_PATH.test(pattern)) {
+        violations.push(
+          `${at}: '${pattern}' is an absolute path — an include glob is matched against ` +
+            `workspace-relative document paths, so an absolute one can never match`,
+        );
+      } else {
+        const problem = globComplexityError(pattern);
+        if (problem) violations.push(`${at}: '${pattern}' ${problem}`);
+      }
+    });
+  }
+  if (!Array.isArray(value.markers) || value.markers.length === 0) {
+    violations.push(
+      `markdown.markers: must be a non-empty array of {pattern, edge} rows, got ` +
+        `${describe(value.markers)}`,
+    );
+  } else {
+    value.markers.forEach((row, index) =>
+      violations.push(...markdownMarkerRowViolations(row, index)),
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "include" && key !== "markers") {
+      violations.push(`markdown.${key}: not a markdown field — expected 'include' and 'markers'`);
+    }
+  }
+  return violations;
+}
+
 /**
  * The grammar a custom rule's `name` is written in: lowercase letters and
  * digits, single `-` separators, nothing else.
@@ -945,6 +1094,7 @@ export function findBoundaryConfigViolations(module, io = {}) {
     fitness,
     customRules,
     coverage,
+    markdown,
   } = module;
   // F05: the resolution half of the governance block (`row-schema.mjs`'s
   // `io.resolve`) was validator-only until now — no production caller passed
@@ -1000,6 +1150,19 @@ export function findBoundaryConfigViolations(module, io = {}) {
     violations.push(...findCoverageViolations(coverage));
   }
 
+  // The markdown document track — the seventh top-level law, declared here and
+  // executed at graph level (`../analysis/markdown.mjs`): machine-readable
+  // markers inside tracked markdown documents, each resolved to an edge from
+  // the document's own project to the project that exports the named symbol.
+  // Absent means "no document track" — the workspace decision this key exists
+  // to state, and the state every config-absent run must stay byte-identical
+  // to. Present and malformed is refused here, loudly, for the reason the two
+  // blocks above state: a row this reader cannot understand is a document law
+  // that would not run while the policy still says it does.
+  if (markdown !== undefined) {
+    violations.push(...findMarkdownViolations(markdown));
+  }
+
   // Absent means "nothing is suppressed", which is the only default that fails
   // toward reporting — unlike the eight options above, where a missing value
   // would be a second copy of something ESLint also reads and this module has
@@ -1095,7 +1258,10 @@ export function findBoundaryConfigViolations(module, io = {}) {
  * `coverage.exempt` is that provider's one channel for the same decision —
  * and the refusal lives in `./commands/policy.mjs`'s `resolvePolicy` and
  * `./providers/native/model.mjs`'s inline-policy check, because only they
- * know which provider is reading.
+ * know which provider is reading. `markdown` is the seventh: the document
+ * track (`findMarkdownViolations` above owns the shape), read into the graph
+ * by `../analysis/markdown.mjs` on every provider, because documents belong
+ * to projects under all three.
  *
  * The name says `.json` and the list binds both file dialects: `loadModulePolicy`
  * runs the same check over an ES module's exports, which is what makes a
@@ -1109,6 +1275,7 @@ const JSON_POLICY_KEYS = [
   "fitness",
   "customRules",
   "coverage",
+  "markdown",
 ];
 
 /**
@@ -1185,7 +1352,7 @@ export function policyKeyViolations(parsed, { allowSchema }) {
  *   inline one.
  * @param {string[]} [extraViolations] Violations the caller already found that
  *   `findBoundaryConfigViolations` does not check on its own.
- * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }}
+ * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: object }}
  *   `fitness` and `customRules` are present only when the config declares
  *   them — a workspace without one carries no key, the same "absent is a
  *   decision" posture `cli.mjs`'s `check` uses for a missing
@@ -1209,6 +1376,7 @@ export function policyFrom(parsed, sourceLabel, extraViolations = []) {
     ...(parsed.fitness === undefined ? {} : { fitness: parsed.fitness }),
     ...(parsed.customRules === undefined ? {} : { customRules: parsed.customRules }),
     ...(parsed.coverage === undefined ? {} : { coverage: parsed.coverage }),
+    ...(parsed.markdown === undefined ? {} : { markdown: parsed.markdown }),
   };
 }
 

package/src/errors.mjs

@@ -23,7 +23,10 @@
  * (`../AGENTS.md`, check's four exit codes).
  *
  * One class, nothing else exported: a second class needs a catch site that
- * treats two of these mistakes differently, and none does.
+ * treats two of these mistakes differently, and none does. Beside it sits the
+ * one error-SHAPE predicate the engine shares (`isEnoent` below) — a test of
+ * what a caught value looks like, not a decision about what one means, which
+ * is why it lives with the error primitives rather than at any catch site.
  */
 export class UsageError extends Error {
   /**
@@ -34,3 +37,22 @@ export class UsageError extends Error {
     this.name = "UsageError";
   }
 }
+
+/**
+ * Is this caught value the filesystem's "no such file or directory"?
+ *
+ * Node's `fs` throws the raw error with `code: "ENOENT"` set directly;
+ * `./process.mjs`'s `runProcess` wraps its child's failure and carries the
+ * original on `cause` — so the shape arrives both ways, and every site that
+ * distinguishes "absent" from "could not read" was spelling the test by hand
+ * (`#652`). The two legs together are the one definition; a catch site adds
+ * its own meaning on top (absent store, absent registry, install Moon), which
+ * is exactly the logic this predicate does not own.
+ *
+ * @param {unknown} error The caught value, of any shape.
+ * @returns {boolean}
+ */
+export function isEnoent(error) {
+  const thrown = /** @type {{code?: unknown, cause?: {code?: unknown}}|null|undefined} */ (error);
+  return thrown?.code === "ENOENT" || thrown?.cause?.code === "ENOENT";
+}

package/src/eslint-config.mjs

@@ -71,6 +71,8 @@
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
+import { isPlainObject } from "./values.mjs";
+
 /** The severities ESLint itself recognises for a rule entry. */
 const KNOWN_SEVERITIES = new Set(["off", "warn", "error", 0, 1, 2]);
 const OFF_SEVERITIES = new Set(["off", 0]);
@@ -94,11 +96,6 @@ const OFF_SEVERITIES = new Set(["off", 0]);
 // one — a stricter refusal than strictly necessary, not a silent guess.
 const BARE_EXTENSION_GLOB = /^\*\*\/\*\.[A-Za-z0-9]+$/u;
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** A rule entry's severity — the bare value itself, or the `[severity, …]` pair's first element. */
 function severityOf(value) {
   return Array.isArray(value) ? value[0] : value;

package/src/governance/adr-registry.mjs

@@ -91,6 +91,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "
 import { join } from "node:path";
 
 import { containmentViolation } from "../containment.mjs";
+import { isEnoent } from "../errors.mjs";
 import { describe } from "../values.mjs";
 
 /** The directory, relative to a workspace root, where ADR files live. */
@@ -538,7 +539,7 @@ export function loadAdrRegistry(root, io = {}) {
     // deliberately silent, for the reason this module's header states.
     names = readDir(dir);
   } catch (cause) {
-    if (cause?.code === "ENOENT") return { records: [], byId: new Map() };
+    if (isEnoent(cause)) return { records: [], byId: new Map() };
     throw new Error(`archkeep: cannot read ${ADR_DIR}: ${cause?.message ?? cause}`, { cause });
   }
   names.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));

package/src/governance/evolution-store.mjs

@@ -51,6 +51,7 @@ import {
 import { join, resolve } from "node:path";
 
 import { containmentViolation } from "../containment.mjs";
+import { isEnoent } from "../errors.mjs";
 import {
   eventDedupeKey,
   eventId,
@@ -222,7 +223,7 @@ export function writeEvent(dir, event, io = {}) {
   try {
     names = readDir(dirAbs);
   } catch (cause) {
-    if (cause?.code === "ENOENT") {
+    if (isEnoent(cause)) {
       // An absent optional store is an empty store: the caller's first event.
       makeDir(dirAbs, { recursive: true });
       names = readDir(dirAbs);
@@ -325,7 +326,7 @@ export function readEvents(dir, io = {}) {
   try {
     names = readDir(dirAbs);
   } catch (cause) {
-    if (cause?.code === "ENOENT") return [];
+    if (isEnoent(cause)) return [];
     throw new Error(
       `archkeep: cannot read the event store '${dirAbs}': ${cause?.message ?? cause}`,
       { cause },

package/src/governance/fitness-registry.mjs

@@ -63,9 +63,6 @@ import {
   tagConformance,
 } from "./fitness-rules.mjs";
 
-/** The one `fitness` list key in the boundary config. */
-export const FITNESS_KEY = "fitness";
-
 /** The condition types the registry can evaluate. */
 export const CONDITION_TYPES = Object.freeze([
   "cycle-free",

package/src/governance/row-schema.mjs

@@ -59,9 +59,6 @@
 import { originViolations } from "./provenance-record.mjs";
 import { describe, isPlainObject } from "../values.mjs";
 
-/** The shape of any `origin.on` producer. Re-exported for a row owner's own docs. */
-export { clockViolations as clockValidation } from "./clock.mjs";
-
 /** The four governance keys a row may carry, in the order reports list them. */
 export const GOVERNANCE_ROW_KEYS = Object.freeze([
   "origin",

package/src/intent/intent-manifest.json

@@ -20,7 +20,7 @@
           "type": "architecture-test",
           "path": "src/conformance/boundary.test.mjs",
           "assertion": "SHIPPED_PACKAGES allow-list prevents unapproved dependencies; specifiersIn() walk catches all imports including createRequire; no provider import found in core layers",
-          "sha256": "12d4e179f88de2622a41e56f42b2bab1c88a677ec2232430752138c57ba5fb18"
+          "sha256": "e4e24ed9f36e31126249c7d079b3656d17ac78ee4f12033321467ffa6666f033"
         },
         {
           "type": "source-evidence",
@@ -104,13 +104,13 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
-          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
+          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
-          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
+          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
         }
       ],
       "status": "proven"
@@ -248,7 +248,7 @@
           "type": "source-evidence",
           "path": "src/commands/context-command.mjs",
           "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)",
-          "sha256": "1f054400e864c381e65904bc20095f4eb6df3198b19ffcb985895af7ec31d80d"
+          "sha256": "f906671ff4a5720d80ea5a3dab2779f1cfd3648fbc1e6a1f3a6d0e6efef21feb"
         },
         {
           "type": "source-evidence",
@@ -286,7 +286,7 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison throughout; never localeCompare",
-          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
+          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
         }
       ],
       "status": "proven"
@@ -312,7 +312,7 @@
           "type": "source-evidence",
           "path": "src/providers/moon.mjs",
           "assertion": "inferWorkspaceLayout returns null for partial layouts — same all-or-nothing contract as Nx and Native",
-          "sha256": "f461cfaa2c8267a78fa9afa4b3267e92be4a85ff5f370b9e4b613a1fb85fc211"
+          "sha256": "2b874da56bda5bc6cfcfb4a984556ace0eafe3a6a98d964c78204bd96cc30e48"
         },
         {
           "type": "behavioral-test",

package/src/providers/moon.mjs

@@ -31,6 +31,7 @@ import { existsSync } from "node:fs";
 import { delimiter, join, posix } from "node:path";
 
 import { environmentForTree, runProcess } from "../process.mjs";
+import { isEnoent } from "../errors.mjs";
 import { buildDependencies } from "./native/graph.mjs";
 
 /**
@@ -905,16 +906,15 @@ function resolveMoonCli(workspaceRoot, { resolveMoon = () => "moon" } = {}) {
  * `nxCli` guards against from the other direction, where only a
  * `MODULE_NOT_FOUND` earns the "not installed" story.
  *
- * `../process.mjs`'s `runProcess` wraps the child's failure and carries the
- * original on `cause`, so the code is read from there; the direct `code` is
- * read too, for a `run` seam that surfaces a spawn error unwrapped.
+ * The shape test itself is `../errors.mjs`'s `isEnoent` — the name stays
+ * because what this file asks is not "is this ENOENT" but "does this failure
+ * carry an install action".
  *
  * @param {unknown} error
  * @returns {boolean}
  */
 function isMoonBinaryMissing(error) {
-  const thrown = /** @type {{code?: unknown, cause?: {code?: unknown}}|null|undefined} */ (error);
-  return thrown?.code === "ENOENT" || thrown?.cause?.code === "ENOENT";
+  return isEnoent(error);
 }
 
 /**

package/src/rules/index.mjs

@@ -815,6 +815,36 @@ function annotatedByTable(suppressions, violation, now) {
   return violation;
 }
 
+/**
+ * The suppression table applied to verdicts that did not come from
+ * `evaluateRun`'s site walk — suppressing rows remove, active waivers mark
+ * `waivedBy`, expired ones re-assert with `evidence`, exactly as the site walk
+ * applies them, because a verdict must ride the same table whichever walk
+ * produced it.
+ *
+ * The one caller is `./commands/check.mjs`'s markdown document track: its
+ * edges are judged per edge through `./edge-constraints.mjs`'s `judgeEdge` —
+ * they have no import site for `candidateGroupsFor` to walk, so there is no
+ * group chain, only a flat list — but a suppression row that names a document
+ * must silence the same verdict here it would silence on an import site, and
+ * a waiver over one must annotate it the same way. Unlike the site walk there
+ * is no second candidate group to fall through to: an edge's verdicts are all
+ * reported together, so a row that removes some leaves the rest standing
+ * rather than promoting anything.
+ *
+ * @param {object[]} suppressions The validated `boundarySuppressions` table.
+ * @param {object[]} violations The unfiltered verdicts, in walk order.
+ * @param {string} [now] Reference instant for waiver expiry; defaults to the
+ *   shared governance clock, as `evaluateRun` does.
+ * @returns {object[]} The survivors, in input order, annotations applied.
+ */
+export function applySuppressionTable(suppressions, violations, now = referenceTime()) {
+  if (suppressions.length === 0) return violations;
+  return violations
+    .filter((violation) => !removedByTable(suppressions, violation, now))
+    .map((violation) => annotatedByTable(suppressions, violation, now));
+}
+
 /**
  * One run of the engine over every import site: the judged verdict per site
  * plus the raw superset it was picked from.

package/src/verdict.mjs

@@ -61,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
@@ -127,7 +154,11 @@ export function verdictFor({
       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 +
@@ -188,7 +219,7 @@ export function verdictFor({
       reasons,
       decision: buildDecision({
         status: "no-verdict",
-        coverageComplete: unchecked === 0 && blindSpots === 0 && analyzed > 0,
+        coverageComplete: coverageComplete({ unchecked, blindSpotCount: blindSpots, analyzed }),
         findings: 0,
         reason: reasons.join("; "),
       }),