@ecoma-io/archkeep 0.13.0

package/src/commands/provenance-command.mjs

@@ -0,0 +1,352 @@
+/**
+ * The `provenance` command: where this run's facts came from, whether the
+ * governance rows it judges carry an origin to attest them, and whether a
+ * `decisionRef` any of them cite actually resolves to a recorded decision.
+ *
+ * Provenance is descriptive, exactly like `graph`/`diff`/`drift`: it never
+ * changes a verdict, so it never exits 1. It answers three questions:
+ *
+ * 1. **Repository provenance** — the git commit, remote, and dirty state of the
+ *    tree this run judged, through the shared `resolveProvenance`
+ *    (`./provenance.mjs`). This is the answer the JSON envelope already carries
+ *    for `graph`/`diff`/`drift`/`history`; this command makes it a first-class
+ *    report instead of a line inside someone else's envelope.
+ * 2. **Decision provenance** — for every governance row in the workspace's
+ *    declared intent (`architecture-intent.json`) and boundary config
+ *    (`module-boundaries.config.mjs`, the `depConstraints` table), whether the
+ *    row carries an `origin` block (the `by`/`tool`/`on?` record
+ *    `../governance/provenance-record.mjs` owns). A row without an origin is
+ *    flagged — `no origin recorded — cannot attest` — because a row whose
+ *    decision nobody recorded is indistinguishable from a rule that appeared
+ *    by editing the file directly. The report never pretends such a row is
+ *    attested.
+ * 3. **Decision resolution** — the same row walk, checked against the
+ *    workspace's ADR registry (`../governance/adr-registry.mjs`) through
+ *    `readAdrContext` (`./adr.mjs`). `origin` says a decision was recorded;
+ *    `decisionRef` says WHICH one, and until this axis existed nothing ever
+ *    verified the citation was real — `resolveDecisionRef` had no production
+ *    caller, and a row bound to a nonexistent ADR id read as legitimately
+ *    documented everywhere it was rendered. A row with no `decisionRef` is
+ *    not a finding here; a row whose `decisionRef` names nothing the registry
+ *    knows is.
+ *
+ * ## Determinism
+ *
+ * Every artifact this command reads is a static file — the intent, the config,
+ * the ADR registry, git state. Two runs over an unchanged tree produce
+ * byte-identical output, and no wall-clock time ever enters the report
+ * (`../../../../AGENTS.md`).
+ *
+ * ## Fail-closed
+ *
+ * Every path that cannot reach an answer says so, in the imperative case:
+ *
+ * - git is not available or the tree is not a repository → `provenance: null`
+ *   in the JSON envelope (the same explicit-null `graph`/`diff` carry), and the
+ *   text report prints `repo provenance unavailable` rather than pretending a
+ *   commit; the intent/config row arms still answer, because they read
+ *   files, not git;
+ * - the intent file, boundary config, or ADR registry is malformed → throw →
+ *   exit 3, exactly the same loud refusal `drift` makes (`./drift.mjs`): a
+ *   row list — or a resolution verdict — built from a file that could not be
+ *   read would be a claim about rows, or citations, that do not exist.
+ *
+ * An empty `unattested` list must mean exactly "every governance row carries
+ * an origin", an empty `unresolvedDecisionRefs` list must mean exactly "every
+ * decisionRef citation resolves", and neither means the other.
+ */
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatProvenanceReport } from "../report/provenance-text.mjs";
+import { loadIntent } from "../architecture-intent/model.mjs";
+import { loadBoundaryConfig } from "../config.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+import { readAdrContext } from "./adr.mjs";
+import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/adr-registry.mjs";
+
+/**
+ * Whether a row declares a governance origin (`origin.by`/`origin.tool`).
+ * Absence is the finding — a row without an origin cannot be attested.
+ *
+ * @param {object} row
+ * @returns {boolean}
+ */
+export function hasOrigin(row) {
+  return (
+    row !== null &&
+    typeof row === "object" &&
+    !Array.isArray(row) &&
+    "origin" in row &&
+    row.origin !== null &&
+    typeof row.origin === "object" &&
+    !Array.isArray(row.origin) &&
+    "by" in row.origin &&
+    "tool" in row.origin &&
+    typeof row.origin.by === "string" &&
+    row.origin.by.length > 0 &&
+    typeof row.origin.tool === "string" &&
+    row.origin.tool.length > 0
+  );
+}
+
+/**
+ * Describes one row so a human can find it. `kind` already carries the index
+ * and section; this appends the row's identity (the pair a rule reads) when
+ * the row has one.
+ *
+ * @param {string} kind e.g. `allowed[3]` or `depConstraints[0]`.
+ * @param {object} row
+ * @returns {string} e.g. `allowed[3] packages→extensions`
+ */
+export function rowLabel(kind, row) {
+  const identity =
+    typeof row.source === "string" && typeof row.target === "string"
+      ? `${row.source}→${row.target}`
+      : typeof row.from === "string" && typeof row.to === "string"
+        ? `${row.from}→${row.to}`
+        : typeof row.name === "string"
+          ? row.name
+          : typeof row.sourceTag === "string"
+            ? row.sourceTag
+            : "";
+  return `${kind}${identity ? ` ${identity}` : ""}`;
+}
+
+/**
+ * Walks every governance row in the normalized intent model — the same rows
+ * `drift`'s judge counts, so a row list built here always matches the rows a
+ * verdict is a claim about. The intent model's rows carry the origin block
+ * additively (`../architecture-intent/model.mjs`), so a legacy row simply has
+ * no `origin` key.
+ *
+ * @param {object} intent The normalized intent model.
+ * @returns {{kind: string, row: object}[]}
+ */
+export function intentRows(intent) {
+  const list = [];
+  const sections = [
+    ["allowed", intent.allowed ?? []],
+    ["forbidden", intent.forbidden ?? []],
+    ["projects.required", intent.projects?.required ?? []],
+    ["projects.forbidden", intent.projects?.forbidden ?? []],
+    ["dependencies.allowed", intent.dependencies?.allowed ?? []],
+    ["dependencies.forbidden", intent.dependencies?.forbidden ?? []],
+    ["forbiddenTags", intent.forbiddenTags ?? []],
+  ];
+  for (const [key, rows] of sections) {
+    for (const [index, row] of rows.entries()) {
+      list.push({ kind: `${key}[${index}]`, row });
+    }
+  }
+  return list;
+}
+
+/**
+ * Walks the boundary config's constraint rows — the `depConstraints` table,
+ * the same rows `check`/`diff`/`impact` judge through
+ * `../config.mjs`'s `findBoundaryConfigViolations`.
+ *
+ * @param {object} config The loaded boundary config module.
+ * @returns {{kind: string, row: object}[]}
+ */
+export function configRows(config) {
+  const rows = config?.depConstraints ?? [];
+  return rows.map((row, index) => ({ kind: `depConstraints[${index}]`, row }));
+}
+
+/**
+ * Why an unresolved `decisionRef` is a finding, in the one wording every
+ * surface that reports one uses. Exported because `report`
+ * (`./report.mjs`) names the same condition in its own document, and a second
+ * hand-written copy of this sentence would drift from this one the first time
+ * either changed — the rule against stating a rule twice
+ * (`../../../../AGENTS.md`), applied to the sentence that carries it.
+ *
+ * @param {string} decisionRef The citation that resolved to nothing.
+ * @returns {string}
+ */
+export function unresolvedDecisionRefNote(decisionRef) {
+  return `"${decisionRef}" does not resolve — no matching ADR, rule, or fitness record`;
+}
+
+/**
+ * The provenance verdict: three answer surfaces, each fail-closed.
+ *
+ * `repo` is the git provenance, `established` whether git could answer,
+ * `rows`/`unattested` the per-row decision provenance, and
+ * `unresolvedDecisionRefs` every row whose `decisionRef` cites no ADR, rule,
+ * or fitness record this workspace's registry knows. All three are findings
+ * about *documentation*, not about the architecture — this command never
+ * changes what `check` or `drift` decide, and it exits 0 when it completes.
+ *
+ * @param {{root: string, tracked: string[], provider: string, marker: string,
+ *   options: {boundaryConfig: string|object, inline?: boolean}}} commandContext
+ *   From `resolveCommandContext`.
+ * @param {{loadIntentOverride?: (root: string, io: object) => Promise<object>,
+ *   loadConfigOverride?: (root: string, boundaryConfig: string) => Promise<object>,
+ *   loadAdrRegistryOverride?: typeof import("../governance/adr-registry.mjs").loadAdrRegistry}} [io]
+ *   `loadAdrRegistryOverride` is forwarded to `readAdrContext` (`./adr.mjs`)
+ *   unchanged.
+ * @returns {Promise<{status: "ok", repo: {commit: string|null, remote: string|null,
+ *   dirty: boolean|null, established: boolean},
+ *   rows: {kind: string, attested: boolean, origin: object|null}[],
+ *   unattested: {kind: string, label: string, note: string}[],
+ *   unresolvedDecisionRefs: {kind: string, label: string, decisionRef: string, note: string}[],
+ *   report: {text: string, json: string}}>}
+ * @throws {Error} on a malformed intent, boundary config, or ADR registry —
+ *   exit 3, the loud refusal every command that reads them makes.
+ */
+export async function provenanceCommand(commandContext, io = {}) {
+  const { root, tracked, options } = commandContext;
+
+  const repo = resolveProvenance(root);
+  const rowList = [];
+  const unattested = [];
+
+  const intent = await (io.loadIntentOverride ?? loadIntent)(root, { tracked });
+  const introws = intent === undefined ? [] : intentRows(intent);
+  for (const { kind, row } of introws) {
+    const attested = hasOrigin(row);
+    rowList.push({ kind, attested, origin: attested ? row.origin : null });
+    if (!attested) {
+      unattested.push({
+        kind,
+        label: rowLabel(kind, row),
+        note: "no origin recorded — cannot attest",
+      });
+    }
+  }
+
+  // The boundary law is either a filename (the string form `loadBoundaryConfig`
+  // reads) or an inline policy object living directly in `archkeep.json`
+  // (`../providers/native/model.mjs`, `normalizeNativeModel`'s
+  // `inlineBoundaryConfig`). Both are walked — a policy whose rows the report
+  // never inspected would claim "every row attests" over an unread table,
+  // which is the silent direction this command exists to end.
+  const boundaryConfig = options.boundaryConfig;
+  const walked = [];
+  let loadedConfig = null;
+  if (typeof boundaryConfig === "string") {
+    const config = await (io.loadConfigOverride ?? loadBoundaryConfig)(root, boundaryConfig);
+    loadedConfig = config;
+    walked.push(...configRows(config));
+  } else if (
+    boundaryConfig !== null &&
+    typeof boundaryConfig === "object" &&
+    !Array.isArray(boundaryConfig)
+  ) {
+    loadedConfig = boundaryConfig;
+    walked.push(...configRows(boundaryConfig));
+  }
+  for (const { kind, row } of walked) {
+    const attested = hasOrigin(row);
+    rowList.push({ kind, attested, origin: attested ? row.origin : null });
+    if (!attested) {
+      unattested.push({
+        kind,
+        label: rowLabel(kind, row),
+        note: "no origin recorded — cannot attest",
+      });
+    }
+  }
+
+  // Resolution — `row-schema.mjs`'s `decisionRef` half, gated on an
+  // `io.resolve` neither `config.mjs` nor `architecture-intent/model.mjs`
+  // ever supplied. Walked over the same two row lists the attestation loops
+  // above already visited, against the workspace's own ADR registry.
+  const governanceRows = [...introws, ...walked];
+  const adrContext = readAdrContext(root, {
+    tracked,
+    loadAdrRegistryOverride: io.loadAdrRegistryOverride,
+  });
+  // F04: the fitness half of a decisionRef resolves against the ids the
+  // loaded policy DECLARES (`declaredFitnessNames`), never against the ADRs'
+  // own `bindings` — a citation cannot resolve itself. `loadedConfig` is the
+  // policy object walked above; `null` only when no boundary law was declared,
+  // and then no fitness-shaped ref can resolve, which is correct.
+  const unresolvedDecisionRefs = unresolvedDecisionRefRows(
+    governanceRows,
+    adrContext.byId,
+    declaredFitnessNames(loadedConfig),
+  ).map(({ kind, row, decisionRef }) => ({
+    kind,
+    label: rowLabel(kind, row),
+    decisionRef,
+    note: unresolvedDecisionRefNote(decisionRef),
+  }));
+
+  const establishment = repo !== null;
+  const repoResult = establishment ? repo : { commit: null, remote: null, dirty: null };
+  const rowsTotal = rowList.length;
+
+  // "No fact, no claim": the resolution section is rendered only when at
+  // least one row actually cites a decisionRef — a workspace that never uses
+  // the field pays nothing and hears nothing, the same bargain every optional
+  // axis in this tool states.
+  const decisionRefRows = governanceRows.filter(
+    ({ row }) => typeof row?.decisionRef === "string" && row.decisionRef.trim() !== "",
+  );
+  const reportText = formatProvenanceReport({
+    establishment,
+    repo,
+    rowsTotal,
+    unattested,
+    decisionRefTotal: decisionRefRows.length,
+    unresolvedDecisionRefs,
+  });
+
+  const context = {
+    root,
+    provider: /** @type {"nx"|"moon"|"native"} */ (commandContext.provider),
+    marker: commandContext.marker,
+    provenance: establishment ? repo : null,
+  };
+  const envelope = jsonEnvelope({
+    command: "provenance",
+    context,
+    status: "ok",
+    exitCode: 0,
+    coverage: {
+      complete: true,
+      projects: 0,
+      analyzedFiles: 0,
+      imports: 0,
+      notAnalyzed: [],
+      blindSpots: [],
+      notes: [],
+    },
+    // The three answer surfaces; `result.rows` preserves the canonical row
+    // order. `unresolvedDecisionRefs` is unconditional, like `unattested` —
+    // an empty array is itself the claim "every citation resolves", never an
+    // omitted key that would leave a reader unable to tell "checked, clean"
+    // from "never checked" (`../../../../AGENTS.md`).
+    result: {
+      repo: repoResult,
+      established: establishment,
+      rows: rowList.map(({ kind, attested, origin }) => ({
+        kind,
+        attested,
+        origin: origin ?? null,
+      })),
+      unattested: unattested.map(({ kind, label, note }) => ({ kind, label, note })),
+      unresolvedDecisionRefs,
+    },
+  });
+
+  return {
+    status: "ok",
+    repo: { ...repoResult, established: establishment },
+    // The three answer surfaces, also available readably (not only inside the
+    // envelope) so `cli.mjs` can drive the text report from the same facts.
+    rows: rowList.map(({ kind, attested, origin }) => ({
+      kind,
+      attested,
+      origin: origin ?? null,
+    })),
+    unattested: unattested.map(({ kind, label, note }) => ({ kind, label, note })),
+    unresolvedDecisionRefs,
+    report: {
+      text: reportText,
+      json: renderJson(envelope),
+    },
+  };
+}

package/src/commands/provenance.mjs

@@ -0,0 +1,159 @@
+/**
+ * Optional repository provenance: git commit, remote, and dirty state.
+ *
+ * Provenance is captured when git is available (it is a hard dependency for
+ * the CLI's `git ls-files` file-list, but the LSP and test paths may not
+ * have it). When it cannot be read, provenance is `null` — the envelope
+ * carries no origin claim it cannot verify. A `null` provenance is explicit,
+ * not implicit: a consumer reading a baseline with `provenance: null` knows
+ * the snapshot's origin is unverified, rather than guessing from
+ * `workspace.root` (a local path that varies by machine and cannot serve as
+ * repository identity).
+ *
+ * Git is NOT made a new core dependency by this module. The CLI already
+ * requires it for `listTrackedFiles` (`../../workspace.mjs`); this module
+ * reuses that availability. Test harnesses and the LSP continue to work
+ * without git, producing `provenance: null`.
+ *
+ * ## Why not timestamps
+ *
+ * No timestamp in the provenance. The envelope's determinism guarantee
+ * (`../../../../AGENTS.md`: "two runs over an unchanged tree produce
+ * byte-identical JSON") would break if the output varied by wall-clock time.
+ * A git commit hash is a stable identity for the same tree state; a
+ * timestamp is not.
+ */
+
+import { execFileSync } from "node:child_process";
+
+import { environmentForTree } from "../process.mjs";
+
+/**
+ * Resolves repository provenance from the workspace root.
+ *
+ * Returns `null` when git is not available or the directory is not a git
+ * repository — the snapshot carries no origin claim rather than a false one.
+ *
+ * Throws when the directory IS a git repository but has no commits. Git keeps
+ * no identity for a tree whose HEAD is unborn: `git ls-files` answers an
+ * empty list, so a run over a commitless tree would otherwise report a clean
+ * workspace over zero files — the exact silent direction this repository
+ * runs on ("an empty result is a claim, not a shrug", `../../../../AGENTS.md`).
+ * Read as `null` it would look identical to "no origin claim", which is a
+ * factually different statement from "the tree's own git cannot name its
+ * state". The throw makes the commitless tree a loud could-not-look at every
+ * call site (exit 3), instead of a clean-looking run over nothing.
+ *
+ * @param {string} root The workspace root directory.
+ * @returns {{ commit: string, remote: string | null, dirty: boolean } | null}
+ * @throws {Error} when `root` is a git repository with no commits.
+ */
+export function resolveProvenance(root) {
+  // G-09: every git spawn routes through the shared environment guard, so an
+  // ambient GIT_DIR/GIT_WORK_TREE from a wrapping tool (the editor hooks, an
+  // outer `git` call) can never make these spawns read a repository other
+  // than the tree at `root`.
+  const env = environmentForTree();
+  // First, the "is this even a git repository at all" question, asked before
+  // `rev-parse HEAD` so an unborn HEAD (a commitless repo) is distinguishable
+  // from "not a repo" — the two must not share the `null` answer, because
+  // only the first is a legitimate "no origin claim".
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd: root,
+      env,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    // git not available, or not a git repository. Return null — the envelope
+    // carries no origin claim rather than a false one.
+    return null;
+  }
+  let commit;
+  try {
+    commit = execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+      cwd: root,
+      env,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    // `--is-inside-work-tree` passed above, so a repo EXISTS here, and
+    // `--verify` (the two-argument form) failed to resolve HEAD. Two states
+    // share that failure, and they need different messages:
+    //   - an UNBORN HEAD (a commitless repo: `git init` with nothing ever
+    //     committed). Git keeps no identity for it — `git ls-files` answers an
+    //     empty list, so a run otherwise reports a clean workspace over zero
+    //     files, the exact silent direction this repository refuses.
+    //   - a BROKEN HEAD (a repo with commits whose HEAD points at a ref that
+    //     no longer exists — `git symbolic-ref HEAD refs/heads/nonexistent`).
+    //     The tree HAS identity; only the ref is corrupt, and telling the
+    //     user to "commit at least once" would be factually false.
+    // The count of commits reachable from any ref (`--all`, includes HEAD via
+    // its reflog) distinguishes them: zero means genuinely unborn, nonzero
+    // means the HEAD ref is broken.
+    let reachable;
+    try {
+      reachable = execFileSync("git", ["rev-list", "--count", "--all"], {
+        cwd: root,
+        env,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      // `rev-list --all` failing too is a degenerate repo; treat it as unborn
+      // rather than inventing a third class.
+    }
+    if (reachable === undefined || reachable === "0") {
+      throw new Error(
+        `archkeep: ${root} is a git repository with no commits — no commit or tracked ` +
+          `file exists to establish evidence, so there is nothing this run could look at. ` +
+          `Commit at least once before running a Archkeep command.`,
+      );
+    }
+    throw new Error(
+      `archkeep: ${root} is a git repository whose HEAD cannot be resolved (the ` +
+        `HEAD ref appears to point at a nonexistent branch), even though the repository ` +
+        `has commits. Fix the broken HEAD before running a Archkeep command.`,
+    );
+  }
+
+  // `git remote` may return empty for a repo with no remotes (e.g. a local
+  // test fixture). That is a legitimate state — the commit still identifies
+  // the tree.
+  let remote = null;
+  try {
+    const remotes = execFileSync("git", ["remote"], {
+      cwd: root,
+      env,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (remotes) {
+      // Use the first remote's URL — typically "origin".
+      const firstRemote = remotes.split("\n")[0].trim();
+      remote = execFileSync("git", ["remote", "get-url", firstRemote], {
+        cwd: root,
+        env,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    }
+  } catch {
+    // No remotes configured — `remote` stays null.
+  }
+
+  // Dirty: any uncommitted change to tracked files means the working tree
+  // does not match the commit. A baseline from a dirty tree is not a
+  // reproducible claim about that commit.
+  const status = execFileSync("git", ["status", "--porcelain"], {
+    cwd: root,
+    env,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+  const dirty = status.length > 0;
+
+  return { commit, remote, dirty };
+}