@ecoma-io/archkeep 0.13.0 → 0.15.0

package/src/config.mjs

@@ -96,7 +96,8 @@
  *
  * The `.mjs`/`.js` and `.json` dialects share the same top-level key law: a
  * top-level export (or key) beyond `depConstraints`, `moduleBoundaryOptions`,
- * `boundarySuppressions`, `fitness` and `customRules` is rejected by name. The
+ * `boundarySuppressions`, `fitness`, `customRules` and `coverage` is rejected
+ * by name. The
  * `.mjs` dialect's tolerance for a helper export used to let a misspelled key
  * (`moduleBoundaryOptions` → `moduleBoundaryOption`) disappear into silence —
  * a typo'd law is a law that is not enforced, the exact silent direction this
@@ -557,6 +558,94 @@ function suppressionRowViolations(row, index) {
   return violations;
 }
 
+/**
+ * The keys a `coverage.unowned` row may carry. `reason` is not optional, for
+ * the same reason it is not optional on a suppression row above and on a
+ * native `coverage.exempt` row (`./providers/native/model.mjs`'s
+ * `exemptRowViolations`, whose semantics this row copies exactly): an
+ * accepted coverage hole with no reason written down is indistinguishable
+ * from coverage that quietly stopped being enforced.
+ */
+const COVERAGE_UNOWNED_KEYS = ["path", "reason"];
+
+/**
+ * One `coverage.unowned` row's problems, prefixed with its index.
+ *
+ * @param {unknown} row
+ * @param {number} index
+ * @returns {string[]}
+ */
+function coverageUnownedRowViolations(row, index) {
+  const at = `coverage.unowned[${index}]`;
+  if (!isPlainObject(row)) return [`${at}: must be an object, got ${describe(row)}`];
+
+  const violations = [];
+  if (typeof row.path !== "string" || row.path === "") {
+    violations.push(
+      `${at}.path: must be a non-empty glob over a workspace-relative path, matched with ` +
+        `\`path.posix.matchesGlob\`, got ${describe(row.path)}`,
+    );
+  } else {
+    const problem = globComplexityError(row.path);
+    if (problem) violations.push(`${at}.path: '${row.path}' ${problem}`);
+  }
+  if (typeof row.reason !== "string" || row.reason.trim() === "") {
+    violations.push(
+      `${at}.reason: must be a non-empty string — an accepted coverage hole with no reason ` +
+        `written down reads as coverage that is still enforced`,
+    );
+  }
+  for (const key of Object.keys(row)) {
+    if (!COVERAGE_UNOWNED_KEYS.includes(key)) {
+      violations.push(
+        `${at}.${key}: not a coverage.unowned field — expected one of ` +
+          COVERAGE_UNOWNED_KEYS.join(", "),
+      );
+    }
+  }
+  return violations;
+}
+
+/**
+ * Everything wrong with a policy's `coverage` key, as messages; empty when it
+ * is well-formed.
+ *
+ * The key holds exactly one field: `unowned`, an array of `{path, reason}`
+ * rows — a recorded acceptance of tracked files no project owns, for the Nx
+ * and Moon providers whose project model has no channel of its own for that
+ * decision (`../../../docs/reference/policy-schema.md`, "`coverage`"). A row
+ * is matched ONLY against files already decided to be unowned, so even a `**`
+ * row can never silence a verdict about an owned file — the same guarantee
+ * the native provider's `coverage.exempt` states
+ * (`./providers/native/coverage.mjs`). An empty `unowned` list is accepted
+ * for the reason an empty suppression list is: it accepts nothing, which is
+ * the direction that cannot hide anything.
+ *
+ * @param {unknown} value The parsed `coverage` value.
+ * @returns {string[]}
+ */
+function findCoverageViolations(value) {
+  if (!isPlainObject(value)) {
+    return [`coverage: must be an object carrying an 'unowned' array, got ${describe(value)}`];
+  }
+  const violations = [];
+  if (!Array.isArray(value.unowned)) {
+    violations.push(
+      `coverage.unowned: must be an array of {path, reason} rows, got ${describe(value.unowned)}`,
+    );
+  } else {
+    value.unowned.forEach((row, index) =>
+      violations.push(...coverageUnownedRowViolations(row, index)),
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "unowned") {
+      violations.push(`coverage.${key}: not a coverage field — expected 'unowned'`);
+    }
+  }
+  return violations;
+}
+
 /**
  * The grammar a custom rule's `name` is written in: lowercase letters and
  * digits, single `-` separators, nothing else.
@@ -863,8 +952,14 @@ export function findBoundaryConfigViolations(module, io = {}) {
   if (!isPlainObject(module)) return [`config: expected a module object, got ${describe(module)}`];
 
   const violations = [];
-  const { depConstraints, moduleBoundaryOptions, boundarySuppressions, fitness, customRules } =
-    module;
+  const {
+    depConstraints,
+    moduleBoundaryOptions,
+    boundarySuppressions,
+    fitness,
+    customRules,
+    coverage,
+  } = module;
   // F05: the resolution half of the governance block (`row-schema.mjs`'s
   // `io.resolve`) was validator-only until now — no production caller passed
   // one, so a row bound to a fitness rule that does not exist loaded and ran
@@ -909,6 +1004,16 @@ export function findBoundaryConfigViolations(module, io = {}) {
     violations.push(...findCustomRuleViolations(customRules, io));
   }
 
+  // The unowned-file acceptances — the sixth top-level law, shaped here and
+  // matched by `./commands/coverage-acceptance.mjs` against files already
+  // decided to be unowned, never against owned ones. Absent means "no
+  // acceptance recorded"; present and malformed is refused loudly, because a
+  // row this reader could not understand is an acceptance that would not
+  // apply while the policy still says it does.
+  if (coverage !== undefined) {
+    violations.push(...findCoverageViolations(coverage));
+  }
+
   // 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
@@ -996,8 +1101,15 @@ export function findBoundaryConfigViolations(module, io = {}) {
  * general "ignore unknown" rule, which is exactly the leniency this file's
  * header argues a JSON object must not get). `fitness` is the fourth: the
  * boundary dialect's key for the fitness-functions list, validated as an array
- * of fitness rows. `customRules` is the fifth and newest — the declared rules
+ * of fitness rows. `customRules` is the fifth — the declared rules
  * this engine did not write, validated as an array of custom-rule rows.
+ * `coverage` is the sixth and newest: the recorded acceptances of unowned
+ * files on an Nx or Moon workspace (`findCoverageViolations` above owns the
+ * shape). On a native tree the key is refused — `archkeep.json`'s own
+ * `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.
  *
  * 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
@@ -1010,6 +1122,7 @@ const JSON_POLICY_KEYS = [
   "boundarySuppressions",
   "fitness",
   "customRules",
+  "coverage",
 ];
 
 /**
@@ -1086,7 +1199,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[] }}
+ * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: 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
@@ -1109,6 +1222,7 @@ export function policyFrom(parsed, sourceLabel, extraViolations = []) {
     suppressions: parsed.boundarySuppressions ?? [],
     ...(parsed.fitness === undefined ? {} : { fitness: parsed.fitness }),
     ...(parsed.customRules === undefined ? {} : { customRules: parsed.customRules }),
+    ...(parsed.coverage === undefined ? {} : { coverage: parsed.coverage }),
   };
 }
 
@@ -1125,7 +1239,7 @@ export function policyFrom(parsed, sourceLabel, extraViolations = []) {
  * legitimate namespace to share a helper in gave a typo the same silence.
  *
  * @param {string} path Absolute path of the config file.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unloadable, or malformed.
  */
 async function loadModulePolicy(path) {
@@ -1151,7 +1265,7 @@ async function loadModulePolicy(path) {
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Injectable read, defaulting to `node:fs/promises`' `readFile` — the only
  *   code in this function that reaches outside the process.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unreadable, not valid JSON, or
  *   malformed — either by `findBoundaryConfigViolations`' rules or by carrying
  *   a top-level key none of those rules knows about.
@@ -1198,7 +1312,7 @@ async function loadJsonPolicy(path, { readFile = readFileFromDisk } = {}) {
  * @param {string} path Absolute path of the config file.
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Injectable read, used only by the `.json` dialect — see `loadJsonPolicy`.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], notes?: string[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, notes?: string[] }>}
  *   `suppressions` is `[]` when the config declares none. `notes` is present
  *   only under the ESLint dialect, and only when `./eslint-config.mjs` has
  *   something worth telling a reader about which entry it bound — see
@@ -1250,8 +1364,12 @@ export async function loadBoundaryConfigFile(path, io = {}) {
       // from (see this module's header). Never populated under this dialect —
       // `policyFrom` already resolves that to `[]` since the object above
       // states no `boundarySuppressions` key, and it leaves `customRules`
-      // absent for the same reason, the header's own distinction between an
-      // absent law and an empty one.
+      // and `coverage` absent for the same reason, the header's own
+      // distinction between an absent law and an empty one: a flat config's
+      // one rule entry is a constraint table and its options, with nowhere to
+      // name a rule artifact or an unowned-file acceptance
+      // (`../../../docs/reference/policy-schema.md`'s dialect table names both
+      // gaps on the consumer-facing side).
       ...(note !== undefined ? { notes: [note] } : {}),
     };
   }
@@ -1279,7 +1397,7 @@ export async function loadBoundaryConfigFile(path, io = {}) {
  *   misconfigured tool.
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Forwarded to `loadBoundaryConfigFile` — see there.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], notes?: string[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, notes?: string[] }>}
  * @throws {Error} as `loadBoundaryConfigFile`.
  */
 export async function loadBoundaryConfig(workspaceRoot, boundaryConfig, io = {}) {

package/src/lsp/boundary-config.mjs

@@ -62,7 +62,7 @@ import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
  *
  * @param {string} path Absolute path of the config file.
  * @param {string|number} revision Busts the ESM module cache across edits.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unloadable, or malformed.
  */
 async function readModulePolicy(path, revision) {
@@ -86,7 +86,7 @@ async function readModulePolicy(path, revision) {
  * @param {(path: string, encoding: "utf8") => Promise<string>} readFile
  *   Injected so a test can drive this without a real file — see
  *   `readBoundaryConfig` below.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unreadable, not valid JSON, or
  *   malformed — either by `../config.mjs`'s `findBoundaryConfigViolations` or
  *   by carrying a top-level key none of those rules knows about.
@@ -144,14 +144,19 @@ async function readJsonPolicy(path, readFile) {
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Injectable read, used only by the `.json` dialect, defaulting to
  *   `node:fs/promises`'s `readFile`.
- * @returns {Promise<{depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[]}>}
+ * @returns {Promise<{depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object}>}
  *   `suppressions` is `[]` when the config declares none; `fitness` and
  *   `customRules` are present only when the policy declares them, the same
  *   absent-is-a-decision shape `../config.mjs`'s `policyFrom` returns to
  *   every other face. This server READS both and evaluates neither — a
  *   fitness function and a custom rule are per-run workspace judgments, not
  *   per-file diagnostics — so what it owes them is to load them and to fail
- *   loudly on a row it cannot read.
+ *   loudly on a row it cannot read. `coverage` rides the same bargain one
+ *   key further: unowned-file acceptance is a whole-run coverage decision
+ *   (`../commands/coverage-acceptance.mjs`), never a per-file diagnostic, so
+ *   the server's whole duty to the key is to ACCEPT a config carrying it —
+ *   the same `policyKeyViolations` the CLI runs — rather than reject in the
+ *   editor a law `check` enforces.
  * @throws {Error} when `boundaryConfig` names the ESLint flat-config dialect
  *   or a legacy `.eslintrc*` file (this reader does not read either yet — see
  *   above), or — for a dialect it does read — when the file is missing,

package/src/path-util.mjs

@@ -0,0 +1,40 @@
+/**
+ * Path utilities — operations that would otherwise be scattered as inline
+ * expressions, each a copy that could drift.
+ *
+ * Every function here is pure and typed, so tests need no filesystem.
+ */
+
+/**
+ * Strip trailing slashes from a path — the O(n) alternative to
+ * `.replace(/\/+$/u, "")`.
+ *
+ * The regex form is **vulnerable to polynomial ReDoS** on a run of slashes
+ * that does not reach the string end: `/" + "/×n + "a"` forces the engine to
+ * scan from each position within the run, turning linear work into O(n²).
+ * Measured on V8:
+ *
+ * | n (slash count) | regex        | linear scan |
+ * |-----------------|--------------|-------------|
+ * | 20,000          | 0.24 s       | <0.001 s    |
+ * | 40,000          | 0.86 s       | <0.001 s    |
+ * | 80,000          | 3.4 s        | 0.004 s     |
+ * | 160,000         | 13.6 s       | 0.14 ms     |
+ *
+ * Workspace roots are normally bounded by PATH_MAX (~4096), so the practical
+ * impact is low; but this function is shipped in a published package and
+ * CodeQL correctly flags the `workspaceRoot` argument as library input — the
+ * fix removes the alert class rather than arguing severity. Five call sites
+ * in the codebase used this pattern; all now route through this one helper.
+ *
+ * Semantics are identical to the regex on all edge cases (empty string,
+ * single slash, multiple slashes, no trailing slash, mixed content).
+ *
+ * @param {string} path The path to strip.
+ * @returns {string} `path` with trailing `/` characters removed.
+ */
+export function stripTrailingSlashes(path) {
+  let end = path.length;
+  while (end > 0 && path[end - 1] === "/") end -= 1;
+  return path.slice(0, end);
+}

package/src/providers/native/model.mjs

@@ -520,6 +520,23 @@ export function findNativeModelViolations(raw) {
           (message) => `boundaryConfig.${message}`,
         ),
       );
+      // The policy's `coverage` key is an Nx/Moon channel, refused here BY
+      // NAME on the one provider that already has its own: this very file's
+      // `coverage.exempt` is where a native tree records an unowned-file
+      // acceptance, and two channels for one decision on one tree is how
+      // copies drift (the same posture as the `.moon`-beside-`archkeep.json`
+      // refusal in `../../commands/context.mjs`'s `requireSingleProjectModel`).
+      // The file-dialect spelling of the same mistake — a native tree whose
+      // boundaryConfig FILE declares `coverage` — is refused by
+      // `../../commands/policy.mjs`'s `resolvePolicy`, which is the first
+      // point that knows both the provider and the loaded policy.
+      if ("coverage" in raw.boundaryConfig) {
+        violations.push(
+          `boundaryConfig.coverage: not accepted on a native workspace — this tree records ` +
+            `unowned-file acceptances on archkeep.json's own coverage.exempt, and a second ` +
+            `channel for the same decision is a copy that will drift. Move the rows there`,
+        );
+      }
     } else if (typeof raw.boundaryConfig !== "string") {
       violations.push(
         `boundaryConfig: must be a string (a filename) or an object (an inline policy), got ` +

package/src/report/change-text.mjs

@@ -0,0 +1,148 @@
+/**
+ * The terminal report for the `change` command: a declared change-intent
+ * contract against the architectural delta actually observed
+ * (`../commands/change.mjs`).
+ *
+ * The report is a review document, so it renders every axis separately and in
+ * full: what was declared, what matched, what appeared without a declaration,
+ * which declared changes never happened, how each declared constraint judged,
+ * and — informational, never this command's verdict — how many live boundary
+ * violations the tree currently carries under the current law, with `check`
+ * named as the authority on that axis. A section renders only when it has
+ * content; the closing line always states what was compared and with what
+ * outcome, so an empty reconciliation is a verifiable claim rather than
+ * silence (`../../../../AGENTS.md`).
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`./README.md`).
+ */
+
+/** One expected-fact row as report lines. */
+function factLines(entry) {
+  switch (entry.kind) {
+    case "project-added":
+      return [`  + project ${entry.project}`];
+    case "project-removed":
+      return [`  - project ${entry.project}`];
+    case "edge-added":
+      return [
+        `  + edge ${entry.from} -> ${entry.to}${entry.type === undefined ? "" : ` (${entry.type})`}`,
+      ];
+    case "edge-removed":
+      return [
+        `  - edge ${entry.from} -> ${entry.to}${entry.type === undefined ? "" : ` (${entry.type})`}`,
+      ];
+    case "project-changed": {
+      const lines = [`  ! project ${entry.project} changed:`];
+      for (const change of entry.changes ?? []) {
+        lines.push(
+          `      ${change.field}: ${JSON.stringify(change.baseline)} -> ${JSON.stringify(change.head)}`,
+        );
+      }
+      return lines;
+    }
+    default:
+      return [`  ? ${entry.kind} ${entry.project ?? `${entry.from} -> ${entry.to}`}`];
+  }
+}
+
+/** One constraint verdict row as its report lines. */
+function constraintLines(row) {
+  const glyph = row.verdict === "pass" ? "✔" : row.verdict === "fail" ? "✗" : "?";
+  return [`${glyph} ${row.name}: ${row.verdict} — ${row.message}`];
+}
+
+/** A side's identity for prose: its commit prefix, or an honest absence. */
+function describeOrigin(provenance) {
+  if (!provenance || typeof provenance.commit !== "string") return "unverified origin";
+  const dirty = provenance.dirty ? ", dirty" : "";
+  return `${provenance.commit.slice(0, 8)}${dirty}`;
+}
+
+/**
+ * The whole change report.
+ *
+ * @param {{change: object, coverage: object}} input `change` is
+ *   `../commands/change.mjs`'s result payload; `coverage` its coverage block.
+ * @returns {string}
+ */
+export function formatChangeReport({ change, coverage }) {
+  const { intent, baseline, head, reconciliation, constraints, policy } = change;
+  const sections = [];
+
+  sections.push(
+    `intent     ${intent.file} — base ${intent.base.commit.slice(0, 8)}` +
+      (intent.summary === undefined ? "" : `\n             "${intent.summary}"`),
+  );
+  sections.push(
+    `baseline   ${baseline.path} — ${describeOrigin(baseline.provenance)}, ` +
+      `${baseline.records} record${baseline.records === 1 ? "" : "s"}, ` +
+      `${baseline.projects} project${baseline.projects === 1 ? "" : "s"}`,
+  );
+  sections.push(
+    `head       ${describeOrigin(head.provenance)}, ` +
+      `${head.projects} project${head.projects === 1 ? "" : "s"}`,
+  );
+
+  for (const note of coverage.notes ?? []) sections.push(`⚠ ${note}`);
+
+  const verdictLine = {
+    matched: "✔ MATCHED — the delta is exactly the declared change",
+    undeclared: "⚠ UNDECLARED — the delta contains changes no declaration covers",
+    unfulfilled: "✗ UNFULFILLED — nothing undeclared, but declared changes never happened",
+    unproven: "? UNPROVEN — the base identity could not be established",
+  }[reconciliation.verdict];
+  sections.push(`reconciliation ${verdictLine}`);
+  for (const reason of reconciliation.reasons) sections.push(`  because: ${reason}`);
+
+  if (reconciliation.matched.length > 0) {
+    sections.push(
+      `✔ ${reconciliation.matched.length} declared change${reconciliation.matched.length === 1 ? "" : "s"} observed`,
+      ...reconciliation.matched.flatMap(factLines),
+    );
+  }
+  if (reconciliation.unexpected.length > 0) {
+    sections.push(
+      `! ${reconciliation.unexpected.length} undeclared material change${reconciliation.unexpected.length === 1 ? "" : "s"} — a review signal, not a law verdict`,
+      ...reconciliation.unexpected.flatMap(factLines),
+    );
+  }
+  if (reconciliation.missingExpected.length > 0) {
+    sections.push(
+      `? ${reconciliation.missingExpected.length} declared change${reconciliation.missingExpected.length === 1 ? "" : "s"} never observed`,
+      ...reconciliation.missingExpected.flatMap(factLines),
+    );
+  }
+
+  if (constraints.length > 0) {
+    sections.push("declared constraints");
+    sections.push(...constraints.flatMap(constraintLines));
+  }
+
+  // Informational on purpose: this number says what `check` would count right
+  // now. It gates nothing here — collapsing it into the intent verdict would
+  // hide one signal behind the other.
+  sections.push(
+    policy.liveViolations === null
+      ? `workspace law  not evaluated — the run could not prove the base identity (archkeep check remains the authority)`
+      : `workspace law  ${policy.liveViolations} live violation${policy.liveViolations === 1 ? "" : "s"} under the current law${policy.changedSinceBase ? ", which changed since capture" : ""} — informational; archkeep check remains the authoritative verdict`,
+  );
+
+  // The closing claim always states what was compared, so every outcome —
+  // including a full match over an unchanged tree — is a verifiable statement
+  // rather than silence.
+  const declaredCount =
+    intent.declared.projectsAdd +
+    intent.declared.projectsRemove +
+    intent.declared.edgesAdd +
+    intent.declared.edgesRemove;
+  sections.push(
+    `reconciled ${declaredCount} declared change${declaredCount === 1 ? "" : "s"} and ` +
+      `${constraints.length} declared constraint${constraints.length === 1 ? "" : "s"} — ` +
+      `base ${describeOrigin(baseline.provenance)} (${baseline.projects} projects, ` +
+      `${baseline.records} records) against head ${describeOrigin(head.provenance)} ` +
+      `(${head.projects} projects)`,
+  );
+
+  return sections.join("\n");
+}