@ecoma-io/archkeep 0.14.0 → 0.16.0

package/src/commands/history.mjs

@@ -251,6 +251,135 @@ export function nextSequence(read) {
   return String(max + 1).padStart(width, "0");
 }
 
+/**
+ * Classifies ONE transition — the record `computeEvolution` pushes for the
+ * consecutive pair `(from, to)` — together with the raw metadata comparison it
+ * was decided over. Split out of `computeEvolution` so a second consumer
+ * (`./trajectory.mjs`) aggregates the SAME classification instead of growing a
+ * second copy of it: the signals, the disclosure notes and the three-state
+ * metadata facts are decided here once (`../README.md`'s single-home rule),
+ * and both commands read them from this one place.
+ *
+ * The returned `record` is exactly what lands in `history`'s envelope. The
+ * returned `meta` is the untouched `compareSnapshotMetadata` result — the
+ * per-side facts (`policyOneSided`, `provenanceOneSided`, `crossRepo`,
+ * `dirtyBaseline`, `dirtyHead`) that the record's `notes[]` render as prose.
+ * An aggregator that needs to COUNT those facts rather than print them reads
+ * `meta`; parsing `notes` strings would be a second copy of the decision
+ * wearing a parser's name.
+ *
+ * @param {{name: string, path: string, envelope: object, id: string}} from
+ * @param {{name: string, path: string, envelope: object, id: string}} to
+ * @returns {{record: {from: string, to: string, architectureChanged: boolean,
+ *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
+ *     codeDrift: boolean, notes: string[]},
+ *   meta: object}} `meta` is `compareSnapshotMetadata`'s result.
+ */
+export function classifyTransition(from, to) {
+  const meta = compareSnapshotMetadata({
+    baselineProvider: from.envelope.workspace.provider,
+    headProvider: to.envelope.workspace.provider,
+    baselineProvenance: from.envelope.workspace.provenance,
+    headProvenance: to.envelope.workspace.provenance,
+    baselineFingerprint: from.envelope.result.policy?.fingerprint ?? null,
+    headFingerprint: to.envelope.result.policy?.fingerprint ?? null,
+  });
+
+  const notes = [];
+  if (meta.policyChanged === true) {
+    // A policy change is disclosed the way `diff` discloses it — a fact
+    // about how the transition must be interpreted, not a structural
+    // change and not a refusal.
+    notes.push(
+      "policy (the declared architectural intent) changed between these snapshots — " +
+        "the boundary law differs even though the graph may not",
+    );
+  }
+  if (meta.providerChanged) {
+    notes.push(
+      `provider changed (${from.envelope.workspace.provider} → ${to.envelope.workspace.provider}) — ` +
+        "structural differences may be provider-artefacts rather than real architectural changes",
+    );
+  }
+  if (meta.crossRepo) {
+    notes.push("provenance remotes differ — these snapshots may be from unrelated repositories");
+  }
+  // The one-sided cases are the silent direction: a fingerprint or
+  // provenance on one snapshot and not the other cannot be asserted "the
+  // same", so it is disclosed rather than read as unchanged.
+  if (meta.policyOneSided) {
+    notes.push(
+      "policy (the declared architectural intent) could not be compared — one snapshot " +
+        "records the boundary law and the other does not",
+    );
+  }
+  if (meta.provenanceOneSided) {
+    notes.push(
+      "repository provenance could not be compared — one snapshot records its origin and the other does not",
+    );
+  }
+  // A snapshot taken from a dirty tree is not a reproducible claim about the
+  // commit it names, so the transition says which side came from one rather
+  // than reading it as a claim about committed history.
+  if (meta.dirtyBaseline) {
+    const commit = from.envelope.workspace.provenance?.commit;
+    notes.push(
+      "the baseline snapshot was captured from an uncommitted (dirty) tree — its architecture " +
+        `is a claim about uncommitted state${typeof commit === "string" ? `, not about commit '${commit}'` : ""}`,
+    );
+  }
+  if (meta.dirtyHead) {
+    const commit = to.envelope.workspace.provenance?.commit;
+    notes.push(
+      "the head snapshot was captured from an uncommitted (dirty) tree — its architecture " +
+        `is a claim about uncommitted state${typeof commit === "string" ? `, not about commit '${commit}'` : ""}`,
+    );
+  }
+
+  const diff = computeDiff(
+    {
+      projects: from.envelope.result.projects,
+      dependencies: from.envelope.result.dependencies,
+    },
+    {
+      projects: to.envelope.result.projects,
+      dependencies: to.envelope.result.dependencies,
+    },
+  );
+  const architectureChanged =
+    diff.addedProjects.length > 0 ||
+    diff.removedProjects.length > 0 ||
+    diff.changedProjects.length > 0 ||
+    diff.addedEdges.length > 0 ||
+    diff.removedEdges.length > 0;
+
+  // Code drift is a disclosure, so it is only asserted when every signal
+  // that could refute it is verifiable and unchanged: the architecture did
+  // not move, the policy was actually compared and did not change, and
+  // provenance advanced. A `null` policyChanged (one-sided, or neither
+  // snapshot carries a fingerprint) is "could not be compared", not "the
+  // same" — asserting code drift on an unverifiable policy would report a
+  // clean transition where the tool cannot look.
+  const codeDrift =
+    !architectureChanged && meta.policyChanged === false && meta.provenanceChanged === true;
+
+  const record = {
+    from: from.name,
+    to: to.name,
+    architectureChanged,
+    // A provider change is rendered with an empty diff (no graph change on
+    // top of a carrier change), a policy-only transition with null — so a
+    // consumer can tell "the carrier changed" from "only the record's
+    // interpretation changed".
+    changes: architectureChanged || meta.providerChanged ? diff : null,
+    policyChanged: meta.policyChanged,
+    providerChanged: meta.providerChanged,
+    codeDrift,
+    notes,
+  };
+  return { record, meta };
+}
+
 /**
  * Computes the evolution record from a list of snapshots: history order,
  * each snapshot's identity, and the classified transition from each to the
@@ -274,109 +403,7 @@ export function computeEvolution(files) {
   const transitions = [];
 
   for (let i = 0; i + 1 < files.length; i++) {
-    const from = files[i];
-    const to = files[i + 1];
-    const meta = compareSnapshotMetadata({
-      baselineProvider: from.envelope.workspace.provider,
-      headProvider: to.envelope.workspace.provider,
-      baselineProvenance: from.envelope.workspace.provenance,
-      headProvenance: to.envelope.workspace.provenance,
-      baselineFingerprint: from.envelope.result.policy?.fingerprint ?? null,
-      headFingerprint: to.envelope.result.policy?.fingerprint ?? null,
-    });
-
-    const notes = [];
-    if (meta.policyChanged === true) {
-      // A policy change is disclosed the way `diff` discloses it — a fact
-      // about how the transition must be interpreted, not a structural
-      // change and not a refusal.
-      notes.push(
-        "policy (the declared architectural intent) changed between these snapshots — " +
-          "the boundary law differs even though the graph may not",
-      );
-    }
-    if (meta.providerChanged) {
-      notes.push(
-        `provider changed (${from.envelope.workspace.provider} → ${to.envelope.workspace.provider}) — ` +
-          "structural differences may be provider-artefacts rather than real architectural changes",
-      );
-    }
-    if (meta.crossRepo) {
-      notes.push("provenance remotes differ — these snapshots may be from unrelated repositories");
-    }
-    // The one-sided cases are the silent direction: a fingerprint or
-    // provenance on one snapshot and not the other cannot be asserted "the
-    // same", so it is disclosed rather than read as unchanged.
-    if (meta.policyOneSided) {
-      notes.push(
-        "policy (the declared architectural intent) could not be compared — one snapshot " +
-          "records the boundary law and the other does not",
-      );
-    }
-    if (meta.provenanceOneSided) {
-      notes.push(
-        "repository provenance could not be compared — one snapshot records its origin and the other does not",
-      );
-    }
-    // A snapshot taken from a dirty tree is not a reproducible claim about the
-    // commit it names, so the transition says which side came from one rather
-    // than reading it as a claim about committed history.
-    if (meta.dirtyBaseline) {
-      const commit = from.envelope.workspace.provenance?.commit;
-      notes.push(
-        "the baseline snapshot was captured from an uncommitted (dirty) tree — its architecture " +
-          `is a claim about uncommitted state${typeof commit === "string" ? `, not about commit '${commit}'` : ""}`,
-      );
-    }
-    if (meta.dirtyHead) {
-      const commit = to.envelope.workspace.provenance?.commit;
-      notes.push(
-        "the head snapshot was captured from an uncommitted (dirty) tree — its architecture " +
-          `is a claim about uncommitted state${typeof commit === "string" ? `, not about commit '${commit}'` : ""}`,
-      );
-    }
-
-    const diff = computeDiff(
-      {
-        projects: from.envelope.result.projects,
-        dependencies: from.envelope.result.dependencies,
-      },
-      {
-        projects: to.envelope.result.projects,
-        dependencies: to.envelope.result.dependencies,
-      },
-    );
-    const architectureChanged =
-      diff.addedProjects.length > 0 ||
-      diff.removedProjects.length > 0 ||
-      diff.changedProjects.length > 0 ||
-      diff.addedEdges.length > 0 ||
-      diff.removedEdges.length > 0;
-
-    // Code drift is a disclosure, so it is only asserted when every signal
-    // that could refute it is verifiable and unchanged: the architecture did
-    // not move, the policy was actually compared and did not change, and
-    // provenance advanced. A `null` policyChanged (one-sided, or neither
-    // snapshot carries a fingerprint) is "could not be compared", not "the
-    // same" — asserting code drift on an unverifiable policy would report a
-    // clean transition where the tool cannot look.
-    const codeDrift =
-      !architectureChanged && meta.policyChanged === false && meta.provenanceChanged === true;
-
-    transitions.push({
-      from: from.name,
-      to: to.name,
-      architectureChanged,
-      // A provider change is rendered with an empty diff (no graph change on
-      // top of a carrier change), a policy-only transition with null — so a
-      // consumer can tell "the carrier changed" from "only the record's
-      // interpretation changed".
-      changes: architectureChanged || meta.providerChanged ? diff : null,
-      policyChanged: meta.policyChanged,
-      providerChanged: meta.providerChanged,
-      codeDrift,
-      notes,
-    });
+    transitions.push(classifyTransition(files[i], files[i + 1]).record);
   }
 
   return { snapshots, transitions };

package/src/commands/policy.mjs

@@ -8,6 +8,7 @@
  * below argues the order, each arm, and what `profile`/`source` name.
  */
 
+import { existsSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 
 import { containmentViolation } from "../containment.mjs";
@@ -118,6 +119,62 @@ export async function resolvePolicy(options, commandContext, cwd) {
   return resolved;
 }
 
+/**
+ * The policy load for a command that DESCRIBES the workspace rather than
+ * judging it — `graph`'s own arm, held here beside the ladder it wraps so
+ * every future descriptive surface (`./graph.mjs`'s MCP caller among them)
+ * answers from one copy of the "absent default law" decision rather than
+ * re-deriving it.
+ *
+ * What is skipped is the load of a file that is NOT THERE. A boundary config
+ * that exists and will not load still fails the run, because an absent law
+ * and a broken one must not report alike; a `--config`, a profile, and an
+ * inline `archkeep.json` policy are explicit declarations and stay loud.
+ * Every command that JUDGES against the law keeps loading it unconditionally
+ * through `resolvePolicy` — making it optional for those would turn a missing
+ * file into a silent no-law run.
+ *
+ * `boundaryConfigDeclared` is what keeps this guard to the un-overridden
+ * default, and it is load-bearing rather than belt-and-braces. The name
+ * alone cannot answer it: `commandContext.options.boundaryConfig` is a
+ * string BOTH when it came from `../options.mjs`'s `DEFAULT_OPTIONS` and
+ * when the consumer WROTE it into `nx.json`'s plugin options or
+ * `archkeep.json`, and a workspace is free to declare the convention
+ * filename itself, so comparing against the default would still read a
+ * deliberate declaration as an assumption. Measured on a committed native
+ * tree whose `archkeep.json` declares a `boundaryConfig` that file does not
+ * contain: skipping on name alone made `graph` exit 0 with no `policy` field
+ * — byte-identical to a workspace that never had a law — where the same tree
+ * with that file present but unparseable exited 3. A law someone named and
+ * then renamed or deleted is exactly the case that must stay loud, so the
+ * provenance survives the options layer instead
+ * (`../options.mjs`'s `resolveOptions`,
+ * `../providers/native/model.mjs`'s `normalizeNativeModel`, and
+ * `./context.mjs`'s three branches carry it; Moon answers `false` because it
+ * has no table to declare one in).
+ *
+ * @param {{config: string|null}} options The command's own parsed flags.
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {string} cwd The process's working directory a relative `--config`
+ *   resolves against.
+ * @returns {Promise<{config: object|null, profile: string|null, source: string|null}>}
+ *   `null` config only on the absent-un-overridden-default arm.
+ * @throws {Error} through `resolvePolicy` for every law that is named but
+ *   cannot be loaded.
+ */
+export async function resolveDescribedPolicy(options, commandContext, cwd) {
+  const workspaceDefault =
+    !options.config &&
+    !hasProfiles(commandContext.options) &&
+    commandContext.options.boundaryConfigDeclared === false &&
+    typeof commandContext.options.boundaryConfig === "string"
+      ? resolve(commandContext.root, commandContext.options.boundaryConfig)
+      : null;
+  return workspaceDefault !== null && !existsSync(workspaceDefault)
+    ? { config: null, profile: null, source: null }
+    : resolvePolicy(options, commandContext, cwd);
+}
+
 /**
  * The four arms of the ladder, unguarded — `resolvePolicy` above wraps this
  * with the one post-resolution refusal that needs both the provider and the

package/src/commands/provenance.mjs

@@ -24,9 +24,7 @@
  * timestamp is not.
  */
 
-import { execFileSync } from "node:child_process";
-
-import { environmentForTree } from "../process.mjs";
+import { runProcess } from "../process.mjs";
 
 /**
  * Resolves repository provenance from the workspace root.
@@ -49,22 +47,12 @@ import { environmentForTree } from "../process.mjs";
  * @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"],
-    });
+    runProcess("git", ["rev-parse", "--is-inside-work-tree"], root);
   } catch {
     // git not available, or not a git repository. Return null — the envelope
     // carries no origin claim rather than a false one.
@@ -72,12 +60,7 @@ export function resolveProvenance(root) {
   }
   let commit;
   try {
-    commit = execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
-      cwd: root,
-      env,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
+    commit = runProcess("git", ["rev-parse", "--verify", "HEAD"], root).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
@@ -95,12 +78,7 @@ export function resolveProvenance(root) {
     // 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();
+      reachable = runProcess("git", ["rev-list", "--count", "--all"], root).trim();
     } catch {
       // `rev-list --all` failing too is a degenerate repo; treat it as unborn
       // rather than inventing a third class.
@@ -124,21 +102,11 @@ export function resolveProvenance(root) {
   // the tree.
   let remote = null;
   try {
-    const remotes = execFileSync("git", ["remote"], {
-      cwd: root,
-      env,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
+    const remotes = runProcess("git", ["remote"], root).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();
+      remote = runProcess("git", ["remote", "get-url", firstRemote], root).trim();
     }
   } catch {
     // No remotes configured — `remote` stays null.
@@ -147,12 +115,7 @@ export function resolveProvenance(root) {
   // 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 status = runProcess("git", ["status", "--porcelain"], root).trim();
   const dirty = status.length > 0;
 
   return { commit, remote, dirty };