@ecoma-io/archkeep 0.13.0

package/src/governance/row-schema.mjs

@@ -0,0 +1,208 @@
+/**
+ * The shared governance row schema — the ONE row extension every governance
+ * capability in this wave reads from, and the single set of validators that
+ * row owners invoke. Contract 2 of the master plan.
+ *
+ * A "row" is one rule/fitness statement in a governance declaration: a
+ * `depConstraints` entry in the boundary law, a row in `architecture-intent.json`
+ * (`allowed`/`forbidden`/`projects`/`dependencies`/`forbiddenTags`), a fitness
+ * rule, an ADR decision. Every row may optionally carry the governance block:
+ *
+ * ```json
+ * {
+ *   "origin": { "by": "jane@example.com", "tool": "archkeep:v1" },
+ *   "rationale": "why this row exists",
+ *   "decisionRef": "adr:0012",
+ *   "fitnessBindings": ["fitness:hotspot"]
+ * }
+ * ```
+ *
+ * ## The additivity rule — old rows stay valid, byte-identical
+ *
+ * Every key below is optional. A row written before governance existed does
+ * not carry the block, and it must parse to exactly the same object it parsed
+ * to before this module existed — the block is a delta a row owner accepts,
+ * never a reshape. That is the byte-identity half of the invariant; the
+ * owners (`../config.mjs`, `../architecture-intent/model.mjs`) call the
+ * validators and pass the row through untouched.
+ *
+ * ## One validator set, no duplicates across the wave
+ *
+ * Every governance capability's row gains the same four keys from this one
+ * module, so there is one shape check per key for the whole wave. A row owner
+ * that hand-rolled its own `origin` check would be a second copy that drifts
+ * the first time provenance-record.mjs changes. `rowSchemaViolations` is the
+ * entry; the four key-specific validators live here and nowhere else.
+ *
+ * ## The `decisionRef` and `fitnessBindings` resolution contract
+ *
+ * `decisionRef` names the ADR (or rule/fitness id) that decides the row;
+ * `fitnessBindings` names the fitness rules that measure it. Shape is
+ * validated here; RESOLUTION is the capability that owns the registry
+ * (the ADR capability's registry, the fitness catalogue), injected rather
+ * than imported so this module stays the small contract and nothing here
+ * hard-codes which governance objects exist. A reference that cannot resolve
+ * is a load error, loud — a rule that reads as bound while nothing binds it
+ * is the silent direction (`AGENTS.md`).
+ *
+ * ## Determinism
+ *
+ * `origin.on` — the only timestamp a row may carry — is produced by
+ * `../governance/provenance-record.mjs`'s `recordOrigin`, which refuses to run
+ * without `../governance/clock.mjs`. Read-side validation here checks an
+ * `on` already committed as a static fact, never invents one: a row that
+ * omits `on` stays byte-identical across every run, and a row that records it
+ * records a fact about committed bytes, not about the wall clock of whatever
+ * machine happened to read the file.
+ */
+
+import { originViolations } from "./provenance-record.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",
+  "rationale",
+  "decisionRef",
+  "fitnessBindings",
+]);
+
+/**
+ * @typedef {import("./provenance-record.mjs").OriginRecord} OriginRecord
+ */
+
+/**
+ * @typedef {object} GovernanceRowBlock
+ * @property {OriginRecord} [origin] Who decided the row, with which tool and —
+ *   when the clock was passed — when.
+ * @property {string} [rationale] Free-text "why", for a human or an agent
+ *   reading the row. No format enforced.
+ * @property {string} [decisionRef] Id of the decision that makes the row
+ *   enforceable — an ADR id (`adr:0012` / `0012-slug`), a rule id
+ *   (`rule:no-direct-dep`), or a fitness id (`fitness:hotspot`).
+ * @property {string[]} [fitnessBindings] Fitness ids this row is bound to.
+ */
+
+/** @type {(value: unknown) => value is Record<string, unknown>} */
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** 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)})`;
+}
+
+/**
+ * Everything wrong with a row's `rationale`, `decisionRef`, or
+ * `fitnessBindings` — the three string-shaped governance keys. `origin` has
+ * its own validator (`./provenance-record.mjs`); this one covers the rest so
+ * a row owner asks exactly one function.
+ *
+ * @param {unknown} raw The raw row object.
+ * @param {string} at Dotted path of the row, e.g. `forbidden[3]`, for messages.
+ * @returns {string[]}
+ */
+export function governanceBlockViolations(raw, at) {
+  if (!isPlainObject(raw)) return [];
+  const violations = [];
+
+  if ("rationale" in raw) {
+    if (typeof raw.rationale !== "string" || raw.rationale.trim() === "") {
+      violations.push(
+        `${at}.rationale: must be a non-empty string when present, got ${describe(raw.rationale)} — ` +
+          `a reason that cannot be read is a reason nobody can rely on`,
+      );
+    }
+  }
+
+  if ("decisionRef" in raw) {
+    if (typeof raw.decisionRef !== "string" || raw.decisionRef.trim() === "") {
+      violations.push(
+        `${at}.decisionRef: must be a non-empty string naming a decision (an ADR id like "adr:0012", ` +
+          `or a rule/fitness id like "rule:keep-a" / "fitness:hotspot"), got ${describe(raw.decisionRef)}`,
+      );
+    }
+  }
+
+  if ("fitnessBindings" in raw) {
+    const bindings = raw.fitnessBindings;
+    if (!Array.isArray(bindings)) {
+      violations.push(
+        `${at}.fitnessBindings: must be an array of non-empty strings, got ${describe(bindings)}`,
+      );
+    } else if (bindings.length === 0) {
+      violations.push(
+        `${at}.fitnessBindings: must not be empty — a list present but empty reads as binding while ` +
+          `binding nothing`,
+      );
+    } else {
+      bindings.forEach((binding, index) => {
+        if (typeof binding !== "string" || binding.trim() === "") {
+          violations.push(
+            `${at}.fitnessBindings[${index}]: must be a non-empty string, got ${describe(binding)}`,
+          );
+        }
+      });
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * The full governance-block validation for one row: `origin` shape (via the
+ * provenance record), then the three string-shaped keys. Resolution of a
+ * `decisionRef` / `fitnessBindings` id is the registry capability's, injected
+ * as `io.resolve` when a caller has one.
+ *
+ * @param {unknown} raw The raw row object.
+ * @param {string} at Dotted path of the row, for messages, e.g. `forbidden[3]`.
+ * @param {{resolve?: (key: "decisionRef"|"fitnessBindings", id: string) => boolean,
+ *   kindLabel?: string}} [io] `resolve` answers "does this id name something
+ *   known?"; `kindLabel` names what `resolve` knows about, for the error
+ *   message.
+ * @returns {string[]} Empty when the row's governance block is valid.
+ */
+export function rowSchemaViolations(raw, at, io = {}) {
+  if (!isPlainObject(raw)) return [];
+
+  const violations = [];
+
+  if ("origin" in raw) {
+    violations.push(...originViolations(raw.origin).map((m) => `${at}.${m}`));
+  }
+  violations.push(...governanceBlockViolations(raw, at));
+
+  // Resolution half — a reference that cannot resolve is a load error, loud.
+  if (io.resolve) {
+    if (typeof raw.decisionRef === "string" && raw.decisionRef.trim() !== "") {
+      if (!io.resolve("decisionRef", raw.decisionRef)) {
+        violations.push(
+          `${at}.decisionRef: "${raw.decisionRef}" does not resolve — it names no ${io.kindLabel ?? "declared decision"} ` +
+            `(no ADR with that id, and no rule or fitness id with that name). A rule that cannot be ` +
+            `bound is the silent direction; fix the reference or record the decision it names.`,
+        );
+      }
+    }
+    if (Array.isArray(raw.fitnessBindings)) {
+      raw.fitnessBindings.forEach((binding, index) => {
+        if (
+          typeof binding === "string" &&
+          binding.trim() !== "" &&
+          !io.resolve("fitnessBindings", binding)
+        ) {
+          violations.push(
+            `${at}.fitnessBindings[${index}]: "${binding}" does not resolve — it names no ${io.kindLabel ?? "declared fitness"} ` +
+              `with that id. A rule that cannot be measured is the silent direction; fix the binding or record the fitness rule it names.`,
+          );
+        }
+      });
+    }
+  }
+
+  return violations;
+}

package/src/governance/verdict.mjs

@@ -0,0 +1,127 @@
+/**
+ * The canonical 4-state verdict vocabulary every governance capability emits
+ * and consumes — the single answer shape an architecture-governance envelope
+ * carries.
+ *
+ * The vocabulary exists because the three statuses the envelope has always
+ * used (`"ok"` / `"findings"` / `"no-verdict"`) are about THIS run's position
+ * on THIS tree, while the governance wave needs a verdict an evidencing
+ * process can compare across runs, feeds, and capabilities. The mapping is
+ * the interesting part and it is one-way on purpose:
+ *
+ *   `"ok"`         → `"pass"`
+ *   `"findings"`   → `"fail"`
+ *   `"no-verdict"` → `"unknown"`
+ *
+ * and `"not_applicable"` has no source status in this release — it is the
+ * vocabulary for Fitness functions and Waivers (a follow-up capability),
+ * never for engine behavior today.
+ *
+ * ## The invariants, I1–I5
+ *
+ * I1. `pass` implies complete coverage — a run that could not fully read the
+ *     tree can never pass. A `pass` without coverage is a claim the evidence
+ *     cannot back.
+ * I2. `fail` implies at least one finding — a failing verdict that names no
+ *     finding leaves the reader to guess what failed.
+ * I3. `unknown` implies "could not look" — coverage incomplete, an unresolved
+ *     question, or a thrown analysis. `unknown` is never a degraded `pass`.
+ * I4. `not_applicable` requires `notApplicableReason` — the reader has to be
+ *     able to tell WHY a rule did not apply, since "did not apply" and "did
+ *     not run" are indistinguishable otherwise.
+ * I5. The cardinal rule: an analysis that failed, or a rule that could not
+ *     determine, must emit `unknown`, NEVER `pass`. `pass` is the loudest
+ *     claim the vocabulary makes and the hardest to disprove, so every other
+ *     state exists to refuse it.
+ *
+ * The enforcer that makes the invariants executable lives in
+ * `../report/evidence.mjs` (`buildDecision`) — this module owns the closed
+ * vocabulary and its relation to the envelope's existing statuses, and the
+ * report module owns the runtime check a command's counts go through.
+ */
+
+/** The four canonical verdict values. */
+export const VERDICTS = Object.freeze(["pass", "fail", "unknown", "not_applicable"]);
+
+/** The single mapping from an envelope status to a verdict. */
+export const VERDICT_FOR_STATUS = Object.freeze({
+  ok: "pass",
+  findings: "fail",
+  "no-verdict": "unknown",
+});
+
+/**
+ * Whether a string names one of the four verdicts.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isVerdict(value) {
+  return typeof value === "string" && VERDICTS.includes(value);
+}
+
+/**
+ * The verdict an envelope status implies. Unknown statuses refuse loudly
+ * rather than map to a guess — a status this vocabulary has never heard of is
+ * a caller reading from the future, and guessing which verdict it implied
+ * would make the evidence lie about what actually ran.
+ *
+ * @param {string} status One of `"ok"` | `"findings"` | `"no-verdict"`.
+ * @returns {"pass"|"fail"|"unknown"}
+ * @throws {Error} when `status` is not one of the three the envelope can hold.
+ */
+export function verdictForStatus(status) {
+  const verdict = VERDICT_FOR_STATUS[status];
+  if (verdict === undefined) {
+    throw new Error(
+      `archkeep: status "${status}" has no verdict — expected one of ` +
+        `${Object.keys(VERDICT_FOR_STATUS).join(", ")}`,
+    );
+  }
+  return verdict;
+}
+
+/**
+ * One function's verdict record — the evidence envelope every governance
+ * consumer (a fitness function, a waiver judge) reads.
+ *
+ * `evidence` is an object of deterministic facts the verdict is a claim over
+ * (the same facts a report row renders), and `message` is human text naming
+ * what was decided and why. `rows` is optional per-function observed detail
+ * (matched projects, judged edges); it rides along so a report can show the
+ * function's coverage without re-deriving it a second way.
+ *
+ * A `not_applicable` verdict carries its `notApplicableReason` (invariant I4):
+ * "did not apply" and "did not run" are indistinguishable otherwise, and a
+ * reader has to be told which one this was.
+ *
+ * @param {{verdict: (typeof VERDICTS)[number], name: string, evidence: object,
+ *   message: string, rows?: object[], notApplicableReason?: string}} decision
+ * @returns {object}
+ * @throws {Error} on a verdict outside the four — a programming error in the
+ *   function that built the decision, not a fact about the workspace — and on
+ *   a `not_applicable` verdict without its `notApplicableReason`.
+ */
+export function fitnessVerdict({ verdict, name, evidence, message, rows, notApplicableReason }) {
+  if (!isVerdict(verdict)) {
+    throw new Error(
+      `archkeep: fitness function "${name}" returned verdict ${JSON.stringify(verdict)} — ` +
+        `expected one of ${VERDICTS.join(", ")}.`,
+    );
+  }
+  if (verdict === "not_applicable" && notApplicableReason === undefined) {
+    throw new Error(
+      `archkeep: fitness function "${name}" returned "not_applicable" without ` +
+        `notApplicableReason — invariant I4: the reader must be told why the ` +
+        `function did not apply.`,
+    );
+  }
+  return {
+    verdict,
+    name,
+    evidence,
+    message,
+    ...(rows === undefined ? {} : { rows }),
+    ...(notApplicableReason === undefined ? {} : { notApplicableReason }),
+  };
+}

package/src/governance/waiver.mjs

@@ -0,0 +1,105 @@
+/**
+ * The waiver model: a `boundarySuppressions` row with an `expiresAt` is a
+ * WAIVER, and this module is the single place that decides what one does at a
+ * given reference time.
+ *
+ * The distinction from a legacy suppression (a row with no `expiresAt`) is the
+ * whole point of the feature:
+ *
+ * - a **suppression** removes a violation the workspace decided to accept,
+ *   permanently, and a run whose violations are all suppressed reads clean
+ *   (exit 0 — that is the existing boundary feature, unchanged);
+ * - a **waiver** accepts a violation TEMPORARILY. It never removes the
+ *   violation from the run's findings — a run whose only findings are waived
+ *   is NOT clean (the exit code stays 1), because accepting a boundary breach
+ *   for a fixed term is a tracked decision, not a fix. An ACTIVE waiver marks
+ *   the violation as waived (the report renders it under "accepted
+ *   violations"); an EXPIRED waiver stops covering it, and the violation
+ *   re-asserts itself in full with the evidence `"expired waiver"`.
+ *
+ * That preserves the load-bearing invariant in `../../../../AGENTS.md`: an
+ * empty diagnostic list must mean "no violation" and nothing else. Waiving
+ * never makes a finding disappear; it annotates one. And because suppressions
+ * filter VERDICTS after every site has been judged (never skip sites
+ * up-front), a waiver can never promote `unknown` → `pass` — the "could not
+ * tell" failures travel beside the records and no waiver ever touches them.
+ *
+ * The clock is the shared governance contract (`./clock.mjs`): injectable,
+ * so the bytes a run emits are reproducible over an unchanged tree and an
+ * unchanged injected reference time (the determinism rule every governance
+ * capability shares).
+ */
+
+import { referenceTime } from "./clock.mjs";
+
+/** The evidence a re-asserted violation carries after its waiver expired. */
+export const EXPIRED_WAIVER_EVIDENCE = "expired waiver";
+
+/**
+ * Whether a suppression row is a waiver. Presence of `expiresAt` is the
+ * distinguishing field — validated by `../config.mjs` to be a parseable ISO
+ * instant when present, so a malformed one never reaches this module.
+ *
+ * @param {object|null|undefined} row A `boundarySuppressions` entry.
+ * @returns {boolean}
+ */
+export function isWaiver(row) {
+  return row != null && typeof row === "object" && "expiresAt" in row;
+}
+
+/**
+ * The waiver's expiry as epoch milliseconds. Only called on rows `isWaiver`
+ * accepts, which config validation has guaranteed parseable.
+ *
+ * @param {object} row A `boundarySuppressions` entry with `expiresAt`.
+ * @returns {number}
+ */
+export function expiresAtMs(row) {
+  return Date.parse(String(row.expiresAt));
+}
+
+/**
+ * Whether the waiver is in force at `now`. `now` is included: a waiver whose
+ * expiry exactly equals the reference time is expired — a waiver "valid
+ * through" a term means it covers strictly before `expiresAt`.
+ *
+ * @param {object} row A waiver (has `expiresAt`).
+ * @param {string} [now] Reference instant, ISO-8601; defaults to the shared clock.
+ * @returns {"active"|"expired"}
+ */
+export function waiverStatus(row, now = referenceTime()) {
+  return Date.parse(now) >= expiresAtMs(row) ? "expired" : "active";
+}
+
+/**
+ * Milliseconds until expiry — negative when expired. Fractional-time aware
+ * (epoch-ms precision), which is the boundary every clock test drives.
+ *
+ * @param {object} row A waiver (has `expiresAt`).
+ * @param {string} [now] Reference instant, ISO-8601; defaults to the shared clock.
+ * @returns {number}
+ */
+export function remainingMs(row, now = referenceTime()) {
+  return expiresAtMs(row) - Date.parse(now);
+}
+
+/**
+ * What a suppression entry does to the violation it covers at `now`.
+ *
+ * - `"suppress"` — a legacy row (no expiry): the violation is removed, the
+ *   existing boundary feature's semantics, unchanged.
+ * - `"waive"` — an active waiver: the violation stays in this run's findings,
+ *   marked `waivedBy` so the report can render it as an accepted violation.
+ *   The run is still findings (exit 1) — waiving does not flip exit 1 → 0.
+ * - `"reassert"` — an expired waiver: the violation stays, carrying
+ *   `evidence: "expired waiver"`. A waiver that stopped being in force is
+ *   a waiver that covers nothing, and the boundary it accepted is live again.
+ *
+ * @param {object} row A `boundarySuppressions` entry.
+ * @param {string} [now] Reference instant, ISO-8601; defaults to the shared clock.
+ * @returns {"suppress"|"waive"|"reassert"}
+ */
+export function suppressionFate(row, now = referenceTime()) {
+  if (!isWaiver(row)) return "suppress";
+  return waiverStatus(row, now) === "expired" ? "reassert" : "waive";
+}

package/src/graph/create-dependencies.mjs

@@ -0,0 +1,96 @@
+/**
+ * The graph layer: cross-project EDGES for Go, Rust, and Python, in the shape
+ * Nx's `createDependencies` hook returns. Nothing else — nodes still come from
+ * each project's hand-written `project.json`, and targets are never inferred
+ * (`packages/archkeep/AGENTS.md`).
+ *
+ * This is the plugin half of the tool, and it is deliberately separate from
+ * `../analysis/`. The two answer different questions over the same tree: the
+ * graph asks "does project A depend on project B", which is all `nx affected`
+ * can act on, while analysis asks "which import, written where, in what form" —
+ * a superset a boundary rule needs and an Nx edge cannot carry
+ * (`../analysis/contract.md`). Keeping them apart is what stops the graph from
+ * growing fields Nx will drop and analysis from being trimmed to what Nx keeps.
+ *
+ * Each resolver reads tracked manifests and sources statically (regex for Go
+ * imports, smol-toml for Cargo/pyproject manifests) so the graph computes
+ * without any language toolchain installed. A workspace with no Go/Rust/Python
+ * projects pays nothing: every resolver keys off `<projectRoot>/<manifest>`
+ * existing in the project's tracked files. A resolver may THROW instead of
+ * returning — the Python one does, for a declared path dependency it cannot
+ * attribute to any project (`../analysis/python.mjs` header) — and the throw
+ * is deliberate: edges and an error are the only two outputs this hook has,
+ * and an edge quietly missing from the graph is the failure mode this plugin
+ * exists to close.
+ *
+ * Resolver contract (kept identical across languages, see `../analysis/*.mjs`):
+ *   resolve(projects, filesOf, readFile) -> [{ source, target, sourceFile, type }]
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { containmentViolation } from "../containment.mjs";
+import { resolveGoDependencies } from "../analysis/go.mjs";
+import { resolvePythonDependencies } from "../analysis/python.mjs";
+import { resolveRustDependencies } from "../analysis/rust.mjs";
+import { resolveOptions } from "../options.mjs";
+
+/** Pure core over an abstract workspace; injectable for tests. */
+export function resolvePolyglotDependencies(projects, filesOf, readFile) {
+  const deps = [
+    ...resolveGoDependencies(projects, filesOf, readFile),
+    ...resolveRustDependencies(projects, filesOf, readFile),
+    ...resolvePythonDependencies(projects, filesOf, readFile),
+  ];
+  // One edge per (source, target, sourceFile) — a Go project importing a
+  // sibling from ten files yields ten sourceFile-attributed edges upstream
+  // of us; Nx dedupes too, this just keeps the plugin's output canonical.
+  const seen = new Set();
+  return deps.filter((d) => {
+    const key = `${d.source} ${d.target} ${d.sourceFile}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * The Nx hook.
+ *
+ * `options` is validated and then not used, and both halves of that are
+ * deliberate. Edge resolution reads language manifests, whose names are fixed
+ * external contracts rather than options (`../options.mjs` says why) — so
+ * nothing here needs a value from the table. Validating it anyway is what makes
+ * a typo'd key fail at the FIRST graph computation, which every `nx` invocation
+ * performs, instead of waiting for whichever later CLI or editor run happens to
+ * read the same table. The alternative is a workspace that lints green all week
+ * and discovers on Friday that its `tsConfig` was spelled `tsconfigBase` and no
+ * path alias ever resolved.
+ */
+export const createDependencies = (options, context) => {
+  resolveOptions(options);
+  const projects = Object.entries(context.projects).map(([projectName, config]) => ({
+    name: projectName,
+    root: config.root,
+  }));
+  const filesOf = (projectName) =>
+    (context.fileMap?.projectFileMap?.[projectName] ?? []).map((f) => f.file);
+  const readFile = (workspaceRelativePath) => {
+    const abs = join(context.workspaceRoot, workspaceRelativePath);
+    // Every value this reader is handed comes from the tree's own `fileMap` —
+    // attacker-supplied the moment a PR adds a tracked path. A tracked symlink
+    // whose realpath leaves the workspace would draw a dependency edge from
+    // outside bytes into `nx affected`'s graph; refusing (null) drops the
+    // read so the file produces no edge (the `resolvePolyglotDependencies`
+    // contract is a null read = no edge, not a throw — this hook cannot exit
+    // non-zero by design). A plugin that never resolves outside bytes stays
+    // silent-green only when the bytes are really inside (`../containment.mjs`).
+    if (containmentViolation(context.workspaceRoot, abs) !== null) return null;
+    try {
+      return readFileSync(abs, "utf8");
+    } catch {
+      return null;
+    }
+  };
+  return resolvePolyglotDependencies(projects, filesOf, readFile);
+};