@ecoma-io/archkeep 0.14.0 → 0.15.0

package/commands.mjs

@@ -0,0 +1,51 @@
+/**
+ * The command layer's public face — what an integration imports from this
+ * package's `./commands` subpath to run the same commands `cli.mjs` runs,
+ * in-process, without spawning the CLI or parsing its text output.
+ *
+ * It holds no logic on purpose, the same bargain `./nx` (`nx.mjs`) makes: a
+ * named entry that is a re-export, so the command layer can grow under
+ * `src/commands/` without a second copy of any decision appearing beside it.
+ * `cli.mjs` and this file are two faces of one layer — the CLI owns argv,
+ * output destinations and exit codes; an importer of this face owns those for
+ * itself, and gets back exactly what the command functions return: statuses,
+ * payloads and reports, never a printed byte.
+ *
+ * Who this is for: integrations that compose the CLI's verbs programmatically
+ * — `packages/archkeep-mcp`, the agent capability interface, is the first. The
+ * engine primitives (discovery and judgment) remain the root entry
+ * (`index.mjs`); a caller that wants to JUDGE import records itself composes
+ * those, while a caller that wants the CLI's answers — a verdict, an impact
+ * set, an explanation — composes these. The two entries never overlap: a
+ * function exported here is never also exported there, so no integration can
+ * accidentally hold two spellings of one decision.
+ *
+ * The roster is exactly what the first consumer composes, no more — a
+ * function joins it when an integration calls it, never in anticipation of
+ * one. What is deliberately absent: the `run*` drivers and argv parsing
+ * (`cli.mjs` alone owns what a process's stdout and exit code mean), and the
+ * renderers (`src/report/` shapes bytes for humans; an importer reads the
+ * envelopes the commands already return).
+ *
+ * The seams the CLI threads are threaded the same way here: `readGraph` and
+ * `listFiles` are injectable on every entry point that reaches outside the
+ * process, so a caller drives the real analysis, rules and reports over a
+ * fixture tree with neither Nx nor git present.
+ */
+
+export { resolveCommandContext, WORKSPACE_MARKERS } from "./src/commands/context.mjs";
+
+export { resolveDescribedPolicy, resolvePolicy } from "./src/commands/policy.mjs";
+
+export { check } from "./src/commands/check.mjs";
+export { graphCommand } from "./src/commands/graph.mjs";
+export { impactCommand } from "./src/commands/impact.mjs";
+export { explainCommand } from "./src/commands/explain.mjs";
+export { driftCommand } from "./src/commands/drift.mjs";
+export { planContextCommand } from "./src/commands/plan-context-command.mjs";
+export { historyCommand } from "./src/commands/history.mjs";
+export { adrCommand } from "./src/commands/adr.mjs";
+export { discoverCommand } from "./src/commands/discover.mjs";
+export { reconcileCommand } from "./src/commands/reconcile.mjs";
+
+export { UsageError } from "./src/errors.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript and Vue",
   "keywords": [
     "architecture",
@@ -28,12 +28,14 @@
   "exports": {
     ".": "./index.mjs",
     "./nx": "./nx.mjs",
+    "./commands": "./commands.mjs",
     "./presets/*.json": "./presets/*.json",
     "./package.json": "./package.json"
   },
   "files": [
     "index.mjs",
     "nx.mjs",
+    "commands.mjs",
     "cli.mjs",
     "lsp.mjs",
     "src/",

package/src/analysis/typescript.mjs

@@ -83,6 +83,7 @@ import { isBuiltin } from "node:module";
 import ts from "typescript";
 
 import { DEFAULT_OPTIONS } from "../options.mjs";
+import { stripTrailingSlashes } from "../path-util.mjs";
 import { normalizePath } from "./manifest-util.mjs";
 import { emptyResult, fileFailure, perWorkspace, projectOwning } from "./source-util.mjs";
 
@@ -378,7 +379,7 @@ function scriptKindFor(sourceFile, lang) {
  * translation to the workspace-relative reader happens here and once.
  */
 function resolutionHostFor(workspace) {
-  const root = workspace.root.replace(/\/+$/, "");
+  const root = stripTrailingSlashes(workspace.root);
   const prefix = `${root}/`;
   const contents = new Map();
   const read = (absolute) => {

package/src/commands/README.md

@@ -56,10 +56,32 @@ the resolution order.
   incomplete head coverage, and an Nx workspace with polyglot manifests but no
   plugin registration; a policy-fingerprint change is a loud coverage note, not
   a refusal. A verdict, not a description: a non-waived introduced violation is
-  a finding (exit 1 — the third verb beside `check` and `fitness`), an
+  a finding (exit 1 — then the third verb beside `check` and `fitness`; `change`
+  and its declared-intent question arrived later as the fourth), an
   unclassifiable item is a no-verdict (exit 3), and a waived-introduced entry
   is reported without gating. Capture stays descriptive: never exits 1.
 
+- **`change`** (`./change.mjs`'s `changeCommand`, with the manifest grammar in
+  `./change-intent.mjs`) — a declared change-intent contract reconciled
+  against the actual architectural delta: did the change produce exactly the
+  material consequences its declaration named? The material delta is
+  `./diff.mjs`'s own `computeDiff` over the baseline evidence snapshot's
+  stored graph and this run's graph — never a second opinion about which edits
+  count; declared constraints re-judge BOTH sides under ONE current law and
+  instant through the same engine `./delta.mjs` uses (`../rules/index.mjs`,
+  `./delta-classify.mjs`, and `../governance/fitness-rules.mjs`'s
+  `cyclicProjects`). Verdicts `matched | undeclared | unfulfilled | unproven`
+  stay separate: an undeclared consequence is a review signal, not a law
+  verdict, and the workspace-law axis it reports is informational — computed,
+  labeled as evidence, never folded into the exit code, because `check`
+  remains the authority on the law. Undeclared, unfulfilled, or a failed
+  declared constraint is a finding (exit 1 — the fourth verb beside `check`,
+  `fitness`, `delta`); an unproven base identity or an undeterminable
+  constraint is exit 3, and constraints are left unevaluated over a base the
+  run cannot vouch for. Refuses a manifest that fails shape or reference
+  validation, an unreadable/malformed/incomplete baseline, a provider
+  mismatch, incomplete head coverage, and the unregistered-plugin graph.
+
 - **`impact`** (`./impact.mjs`'s `impactCommand`) — reverse reachability from
   the project graph: given a project name, lists every project that transitively
   depends on it. Separates direct from transitive dependents. When a boundary
@@ -114,6 +136,35 @@ the resolution order.
   head coverage. Refuses an empty or unreadable directory, and a snapshot that
   parses as an incomplete envelope. Descriptive: never exits 1.
 
+- **`trajectory`** (`./trajectory.mjs`'s `trajectoryCommand`) — the aggregate
+  over the same directory `history` reads: signal counts, structural churn
+  and persistence, derived through `./history.mjs`'s own `readSnapshots` and
+  `classifyTransition` so the two commands cannot disagree about a single
+  classification. One observation is one stored graph snapshot — never a
+  commit or a day. Identities are `./diff.mjs`'s (`edgeIdentityKey`); no
+  violation-level trajectory exists because stored snapshots carry no
+  findings. A one-snapshot directory answers `insufficient_history` with null
+  derived fields, never zeros; an empty or malformed one refuses (exit 3).
+  No boundary law is loaded and nothing is captured here — the fingerprints
+  compared travel inside the snapshots, and exactly one command writes them.
+  Descriptive: never exits 1.
+
+- **`evolution`** (`./evolution.mjs`'s `evolutionCommand`) — the same
+  evolution record across a selected range of Git revisions instead of a
+  snapshot directory. Git answers only which trees to read: both endpoints are
+  resolved with `rev-parse`, base must be an ancestor of head, every commit in
+  `base..head` must be single-parent (a merge refuses loudly rather than being
+  flattened), and each selected commit is materialized into a temporary
+  detached worktree that is released before the run reports — the caller's
+  working tree is never touched. Each materialized tree runs through the
+  ordinary context and policy ladders, and the transitions are classified by
+  `./history.mjs`'s own `computeEvolution`, so the two commands cannot
+  disagree about what a transition means. A change is attributed to the first
+  analyzed revision where it is observable — where history shows it, never why
+  it was made. Refuses every unusable selection and every revision that cannot
+  be fully analyzed, so no failure can read as a shorter history. Descriptive:
+  never exits 1.
+
 - **`provenance`** (`./provenance-command.mjs`'s `provenanceCommand`) — where
   this run's facts came from and which governance rows carry an origin.
   Two surfaces: repository provenance (the git commit, remote and dirty state

package/src/commands/change-intent.mjs

@@ -0,0 +1,461 @@
+/**
+ * The change-intent contract — grammar, validation, and loading.
+ *
+ * A change intent is a PER-CHANGE declaration of the material architectural
+ * consequences its author expects one specific edit to produce: which projects
+ * appear or disappear, which project-to-project dependencies appear or
+ * disappear, and which delta-level constraints the change must hold. It is
+ * written beside the work, verified by the `change` command against the actual
+ * architectural delta (`./change.mjs`), and then belongs to the pull request
+ * as the reviewable answer to "what did this change do to the architecture?".
+ *
+ * This file mirrors `../architecture-intent/model.mjs`'s split — a pure
+ * `(raw) -> string[]` validator, a thin loader that reads, parses, validates
+ * and throws one Error naming every violation at once — and deliberately does
+ * NOT extend that module: architecture-intent.json is the workspace's
+ * long-lived law, judged by `drift`/`check`; a change intent names one
+ * transaction's expected consequences and expires with its pull request. One
+ * grammar per concept, so neither can grow the other's semantics by accident.
+ *
+ * Four contracts, each the honest side of the empty-result invariant
+ * (`../../../../AGENTS.md` — an empty list must mean "nothing unexpected",
+ * and nothing else):
+ *
+ *   - **It is strict JSON, never JSONC**, for the same reason
+ *     `../architecture-intent/model.mjs` refuses comments: this is a
+ *     machine-written declaration a verification run consumes, and a comment
+ *     is a load error, not leniency.
+ *   - **An unknown key is rejected by name**, never ignored — a typo'd
+ *     section would silently declare nothing, and a run over a declaration
+ *     that said nothing must not read as "the change declared nothing
+ *     material".
+ *   - **A duplicate declaration is a load error**, not last-one-wins: the
+ *     contract is a SET of expected facts, and two rows under one fact would
+ *     make the reconciliation depend on array order.
+ *   - **Shape is nodes-free.** Whether a declared project reference can exist
+ *     is a question about the captured baseline, so it belongs to the
+ *     command (`./change.mjs`'s reference check), not here. A manifest must
+ *     load and be told its references are wrong — loudly — rather than fail
+ *     to parse at all.
+ */
+
+import { readFile as readFileFromDisk } from "node:fs/promises";
+
+/** The only `version` this module accepts. A different value is a load error. */
+export const CHANGE_INTENT_VERSION = "1";
+
+/** The only keys a valid change-intent file may carry at the top level. */
+export const CHANGE_INTENT_TOP_LEVEL_KEYS = Object.freeze([
+  "version",
+  "base",
+  "summary",
+  "projects",
+  "edges",
+  "constraints",
+]);
+
+/** The keys the `base` section may carry. */
+export const CHANGE_INTENT_BASE_KEYS = Object.freeze(["commit"]);
+
+/** The sub-keys the `projects` section may carry. */
+export const CHANGE_INTENT_PROJECT_SECTION_KEYS = Object.freeze(["add", "remove"]);
+/** The sub-keys the `edges` section may carry. */
+export const CHANGE_INTENT_EDGE_SECTION_KEYS = Object.freeze(["add", "remove"]);
+/** The keys an edge row may carry. */
+export const CHANGE_INTENT_EDGE_ROW_KEYS = Object.freeze(["from", "to"]);
+/** The keys the `constraints` section may carry. */
+export const CHANGE_INTENT_CONSTRAINT_KEYS = Object.freeze(["noNewViolations", "noNewCycles"]);
+
+/**
+ * The constraints the reconciliation judges, in the fixed order their verdict
+ * rows are emitted — the order itself is part of the deterministic output
+ * contract (`docs/reference/json-output.md`), so a manifest that declares them
+ * in either order gets the same row order.
+ */
+export const CONSTRAINT_ORDER = Object.freeze(["noNewViolations", "noNewCycles"]);
+
+/**
+ * The manifest key a constraint row answers to, keyed by the row name the
+ * report and JSON use. One copy, so a renamed key cannot desynchronize the
+ * loader's accepted set from the judge's row names.
+ */
+export const CONSTRAINT_ROW_NAMES = Object.freeze({
+  noNewViolations: "no-new-violations",
+  noNewCycles: "no-new-cycles",
+});
+
+/** 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)})`;
+}
+
+/** @type {(value: unknown) => value is Record<string, unknown>} */
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** `key` on `obj` that is not one of `allowed` — the reject-by-name rule. */
+function unknownKeys(obj, allowed) {
+  return Object.keys(obj).filter((key) => !allowed.includes(key));
+}
+
+/** Non-empty-string guard with its message fragment. */
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Everything wrong with the `projects`/`edges` sections' shared list shape —
+ * present-or-absent wholesale, an array when present, strings (for projects)
+ * or `{from, to}` rows (for edges) inside, no duplicates within a list, no
+ * member of `add` also in `remove`. Written once for both sections because a
+ * second copy of the duplicate rule is how the two sections drift into
+ * answering "is this a set?" differently.
+ *
+ * @param {unknown} section The raw section value.
+ * @param {{name: string, keys: readonly string[], row: (row: unknown, at: string) => string[],
+ *   identity: (row: unknown) => string|null}} spec
+ *   `name` is the dotted path prefix, `keys` the allowed sub-keys, `row` the
+ *   per-element validator, `identity` the element's dedup key (or `null` when
+ *   the element is malformed and already reported).
+ * @returns {string[]}
+ */
+function sectionListViolations(section, spec) {
+  const problems = [];
+  if (section === undefined) return problems;
+  if (!isPlainObject(section)) {
+    problems.push(`${spec.name}: must be an object when present, got ${describe(section)}`);
+    return problems;
+  }
+  for (const key of unknownKeys(section, spec.keys)) {
+    problems.push(
+      `${spec.name}.${key}: unknown key — ${spec.name} may carry only ${spec.keys.join(", ")}`,
+    );
+  }
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  for (const kind of spec.keys) {
+    const list = section[kind];
+    if (list === undefined) continue;
+    if (!Array.isArray(list)) {
+      problems.push(`${spec.name}.${kind}: must be an array when present, got ${describe(list)}`);
+      continue;
+    }
+    list.forEach((entry, index) => {
+      const at = `${spec.name}.${kind}[${index}]`;
+      const rowProblems = spec.row(entry, at);
+      if (rowProblems.length > 0) {
+        problems.push(...rowProblems);
+        return;
+      }
+      const id = /** @type {string} */ (spec.identity(entry));
+      const first = seen.get(id);
+      if (first !== undefined) {
+        problems.push(
+          `${at}: duplicates ${spec.name}.${kind}[${first}] (${id}) — the contract is a set ` +
+            `of expected facts, and a repeated declaration would make reconciliation depend ` +
+            `on array order`,
+        );
+      } else {
+        seen.set(id, index);
+      }
+    });
+  }
+  // An `add` and a `remove` naming the same fact cancel to nothing while
+  // reading as a declaration — refuse the pair rather than reconcile a
+  // contradiction.
+  if (Array.isArray(section.add) && Array.isArray(section.remove)) {
+    const removeIds = new Set(section.remove.map(spec.identity));
+    section.add.forEach((entry, index) => {
+      const id = spec.identity(entry);
+      if (id !== null && removeIds.has(id)) {
+        problems.push(
+          `${spec.name}.add[${index}]: "${id}" is also declared in ${spec.name}.remove — ` +
+            `a fact cannot be both expected to appear and expected to disappear`,
+        );
+      }
+    });
+  }
+  return problems;
+}
+
+/**
+ * Everything wrong with a raw change-intent file, as messages; empty when it
+ * is well-formed. Pure — no baseline, no graph, no clock: whether a declared
+ * reference CAN exist is `findChangeIntentReferenceViolations`' question,
+ * below.
+ *
+ * @param {unknown} raw The parsed JSON value.
+ * @returns {string[]}
+ */
+export function findChangeIntentViolations(raw) {
+  const violations = [];
+  if (!isPlainObject(raw)) {
+    return [`top level: must be an object, got ${describe(raw)}`];
+  }
+  for (const key of unknownKeys(raw, CHANGE_INTENT_TOP_LEVEL_KEYS)) {
+    violations.push(
+      `unknown key "${key}" — a change intent may carry only ` +
+        `${CHANGE_INTENT_TOP_LEVEL_KEYS.join(", ")}`,
+    );
+  }
+
+  if (raw.version !== CHANGE_INTENT_VERSION) {
+    violations.push(
+      `version: must be exactly "${CHANGE_INTENT_VERSION}", got ${describe(raw.version)}`,
+    );
+  }
+
+  // The base pin is the whole proof that reconciliation compares the same two
+  // architectures the author saw: without a commit there is nothing to verify
+  // the baseline against, and the run must answer unproven rather than guess
+  // (`./change.mjs`). So the section itself is required, not optional.
+  if (!isPlainObject(raw.base)) {
+    violations.push(`base: is required and must be an object, got ${describe(raw.base)}`);
+  } else {
+    for (const key of unknownKeys(raw.base, CHANGE_INTENT_BASE_KEYS)) {
+      violations.push(
+        `base.${key}: unknown key — base may carry only ${CHANGE_INTENT_BASE_KEYS.join(", ")}`,
+      );
+    }
+    if (!nonEmptyString(raw.base.commit)) {
+      violations.push(
+        "base.commit: is required and must be a non-empty string — the git commit the " +
+          "baseline snapshot was captured at (`archkeep delta --capture` records it in the " +
+          "snapshot's provenance)",
+      );
+    }
+  }
+
+  if (raw.summary !== undefined && !nonEmptyString(raw.summary)) {
+    violations.push(
+      `summary: must be a non-empty string when present, got ${describe(raw.summary)} — it is ` +
+        "informational only and is never read by the reconciliation",
+    );
+  }
+
+  violations.push(
+    ...sectionListViolations(raw.projects, {
+      name: "projects",
+      keys: CHANGE_INTENT_PROJECT_SECTION_KEYS,
+      row: (entry, at) =>
+        nonEmptyString(entry)
+          ? []
+          : [`${at}: must be a non-empty project name, got ${describe(entry)}`],
+      identity: (entry) => (typeof entry === "string" ? entry : ""),
+    }),
+  );
+
+  violations.push(
+    ...sectionListViolations(raw.edges, {
+      name: "edges",
+      keys: CHANGE_INTENT_EDGE_SECTION_KEYS,
+      row: (entry, at) => {
+        if (!isPlainObject(entry)) {
+          return [`${at}: must be an object with "from" and "to", got ${describe(entry)}`];
+        }
+        const problems = [];
+        for (const key of unknownKeys(entry, CHANGE_INTENT_EDGE_ROW_KEYS)) {
+          problems.push(
+            `${at}.${key}: unknown key — an edge row may carry only ` +
+              `${CHANGE_INTENT_EDGE_ROW_KEYS.join(", ")}`,
+          );
+        }
+        for (const side of ["from", "to"]) {
+          if (!nonEmptyString(entry[side])) {
+            problems.push(
+              `${at}.${side}: must be a non-empty project name, got ${describe(entry[side])}`,
+            );
+          }
+        }
+        if (nonEmptyString(entry.from) && entry.from === entry.to) {
+          problems.push(
+            `${at}: "from" and "to" are both "${entry.from}" — the project graph strips ` +
+              `self-edges, so a self-dependency can never be observed and the declaration ` +
+              `could never match`,
+          );
+        }
+        return problems;
+      },
+      identity: (entry) =>
+        isPlainObject(entry) && nonEmptyString(entry.from) && nonEmptyString(entry.to)
+          ? `${entry.from}\u0000${entry.to}`
+          : "",
+    }),
+  );
+
+  if (raw.constraints !== undefined) {
+    if (!isPlainObject(raw.constraints)) {
+      violations.push(
+        `constraints: must be an object when present, got ${describe(raw.constraints)}`,
+      );
+    } else {
+      for (const key of unknownKeys(raw.constraints, CHANGE_INTENT_CONSTRAINT_KEYS)) {
+        violations.push(
+          `constraints.${key}: unknown key — constraints may carry only ` +
+            `${CHANGE_INTENT_CONSTRAINT_KEYS.join(", ")}`,
+        );
+      }
+      for (const key of CHANGE_INTENT_CONSTRAINT_KEYS) {
+        const value = raw.constraints[key];
+        if (value === undefined) continue;
+        if (value !== true) {
+          violations.push(
+            `constraints.${key}: must be exactly true when present, got ${describe(value)} — ` +
+              "a constraint this run should not judge is declared by omitting the key, not by " +
+              "writing false",
+          );
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Parses and validates change-intent text into the normalized shape the
+ * `change` command reconciles against. Pure: text in, validated contract out.
+ *
+ * Absent sections normalize to empty expectations — a manifest with no
+ * `projects` section expects no project to appear or disappear, which is a
+ * REAL expectation the reconciliation enforces, never an absence of one.
+ *
+ * @param {string} text The file contents.
+ * @param {string} path The path the text came from, for error messages.
+ * @returns {{
+ *   version: string,
+ *   base: {commit: string},
+ *   summary?: string,
+ *   projects: {add: string[], remove: string[]},
+ *   edges: {add: {from: string, to: string}[], remove: {from: string, to: string}[]},
+ *   constraints: {noNewViolations?: true, noNewCycles?: true},
+ * }}
+ * @throws {Error} naming every violation at once — these become exit-3-class
+ *   input errors upstream, and a run that consumed a malformed declaration
+ *   silently would reconcile against an expectation nobody wrote.
+ */
+export function parseChangeIntent(text, path) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new Error(
+      `archkeep: the change intent '${path}' is not valid JSON: ${cause?.message ?? cause}`,
+      { cause },
+    );
+  }
+  const violations = findChangeIntentViolations(parsed);
+  if (violations.length > 0) {
+    throw new Error(
+      `archkeep: the change intent '${path}' is not a usable contract:\n  ` +
+        violations.join("\n  "),
+    );
+  }
+  return {
+    version: parsed.version,
+    base: { commit: parsed.base.commit },
+    ...(parsed.summary === undefined ? {} : { summary: parsed.summary }),
+    projects: {
+      add: parsed.projects?.add ?? [],
+      remove: parsed.projects?.remove ?? [],
+    },
+    edges: {
+      add: (parsed.edges?.add ?? []).map(({ from, to }) => ({ from, to })),
+      remove: (parsed.edges?.remove ?? []).map(({ from, to }) => ({ from, to })),
+    },
+    constraints: { ...(parsed.constraints ?? {}) },
+  };
+}
+
+/**
+ * Reads the change-intent file from a path — the module's one filesystem seam,
+ * injectable so tests and embedders drive validation without disk.
+ *
+ * @param {string} path Absolute path to the manifest.
+ * @param {{read?: (path: string) => Promise<string>}} [io]
+ * @returns {Promise<object>} Whatever `parseChangeIntent` returns.
+ * @throws {Error} when the file cannot be read, and whatever
+ *   `parseChangeIntent` throws.
+ */
+export async function readChangeIntent(path, io = {}) {
+  const read = io.read ?? ((p) => readFileFromDisk(p, "utf8"));
+  let text;
+  try {
+    text = await read(path);
+  } catch (cause) {
+    throw new Error(
+      `archkeep: cannot read the change intent '${path}': ${cause?.message ?? cause}`,
+      { cause },
+    );
+  }
+  return parseChangeIntent(text, path);
+}
+
+/**
+ * Everything wrong with a loaded manifest's REFERENCES — whether each declared
+ * fact could exist in a tree descended from the captured baseline. Pure: the
+ * baseline's project-name set arrives as an argument.
+ *
+ * These are load errors too (the command throws on the first list), because a
+ * declaration that references a project that exists nowhere would sit in
+ * `missingExpected` forever, reading as "the change forgot something" when
+ * the truth is "the declaration cannot be satisfied by ANY tree".
+ *
+ * @param {object} intent A `parseChangeIntent` result.
+ * @param {Set<string>} baselineProjects Every project name in the captured
+ *   baseline's graph.
+ * @returns {string[]} One entry per problem, empty when every reference lands.
+ */
+export function findChangeIntentReferenceViolations(intent, baselineProjects) {
+  const violations = [];
+  const known = new Set([...baselineProjects, ...intent.projects.add]);
+  for (const name of intent.projects.add) {
+    if (baselineProjects.has(name)) {
+      violations.push(
+        `projects.add: "${name}" already exists at the captured base — a project the base ` +
+          `graph already has cannot be declared as appearing`,
+      );
+    }
+  }
+  for (const name of intent.projects.remove) {
+    if (!baselineProjects.has(name)) {
+      violations.push(
+        `projects.remove: "${name}" does not exist at the captured base — there is no such ` +
+          `project to expect gone`,
+      );
+    }
+  }
+  for (const [kind, list] of [
+    ["add", intent.edges.add],
+    ["remove", intent.edges.remove],
+  ]) {
+    for (const { from, to } of list) {
+      for (const side of ["from", "to"]) {
+        const name = side === "from" ? from : to;
+        if (kind === "add") {
+          if (intent.projects.remove.includes(name)) {
+            violations.push(
+              `edges.${kind}: ${from} -> ${to} names "${name}" in projects.remove — an edge ` +
+                `cannot appear attached to a project declared to disappear`,
+            );
+          } else if (!known.has(name)) {
+            violations.push(
+              `edges.${kind}: ${from} -> ${to} names "${name}", which is neither in the ` +
+                `baseline graph nor declared in projects.add — the reference can never match ` +
+                `anything`,
+            );
+          }
+        } else if (!baselineProjects.has(name)) {
+          violations.push(
+            `edges.${kind}: ${from} -> ${to} names "${name}", which is not in the baseline ` +
+              `graph — an edge of a project the base does not have cannot be expected to ` +
+              `disappear${intent.projects.add.includes(name) ? " (it is declared in projects.add, so it had no base edges)" : ""}`,
+          );
+        }
+      }
+    }
+  }
+  return violations;
+}