@ecoma-io/archkeep 0.13.0

package/src/commands/diff.mjs

@@ -0,0 +1,523 @@
+/**
+ * The `diff` command: two graph snapshots compared, edge by edge.
+ *
+ * `diff` takes a baseline snapshot FILE (not a git ref —
+ * a ref baseline means building a second graph at another commit, a much larger
+ * claim about what the tool is allowed to do to a repository) and the head
+ * context this run resolves, and computes what changed between them: projects
+ * added, removed, or changed in metadata, and edges added, removed, or changed
+ * in type. It is descriptive: it never exits 1, because a description of what changed is
+ * never a finding.
+ *
+ * When a boundary config is provided (via `--config` or the workspace's own
+ * declaration), `diff` also computes the rule-impact: which boundary violations
+ * the added edges introduce and which the removed edges resolve. This is
+ * narrower than `check` — it checks only `depConstraints` (tag-based), not
+ * npm/circular/lazy-load rules that need import-site details. A consumer who
+ * needs the complete verdict should run `check`.
+ *
+ * `diff` refuses an incomplete baseline or head. If either side could not read
+ * part of the tree, every "removed" project and edge is ambiguous between
+ * "gone" and "never seen" — reporting the diff anyway would manufacture
+ * architectural changes out of a broken run. Exit 3 with that sentence in the
+ * message.
+ *
+ * What it needs from its caller is a `CommandContext` for the head, the path
+ * to the baseline file, and an optional `readBaseline` seam (injected the same
+ * way every IO seam in this codebase is — pure function of its arguments, no
+ * filesystem in unit tests). What it gives back is a `status`, the diff
+ * payload for both the text and the JSON renderers, and enough coverage
+ * information to build a correct envelope. It does not print, and it does not
+ * decide the process's exit code — `../../cli.mjs` owns those
+ * (`./README.md`).
+ *
+ * ## The unregistered-plugin refusal
+ *
+ * Same as `graph`: on an Nx workspace whose `nx.json` does not register this
+ * plugin but whose tracked files include polyglot manifests under project
+ * roots, `diff` refuses loudly rather than computing a diff against a head
+ * whose edges silently under-represent the real architecture.
+ */
+import { readFileSync } from "node:fs";
+
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
+import { computeRuleImpact } from "./edge-constraints.mjs";
+import { SCHEMA_VERSION } from "../report/json.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatDiffReport } from "../report/diff-text.mjs";
+import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+
+/**
+ * Reads and validates a baseline snapshot from `path`.
+ *
+ * Returns the parsed envelope's `result` (the `{projects, dependencies}`
+ * payload) and `coverage`. Throws on every condition that would make the diff
+ * dishonest: a file that cannot be read, an envelope whose schema version this
+ * tool does not know, or a baseline whose coverage is not complete (every
+ * "removed" entry would be ambiguous between "gone" and "never seen").
+ *
+ * @param {string} path Absolute path to the baseline JSON file.
+ * @returns {{projects: object[], dependencies: object[], coverage: object, policy: object|null,
+ *   provider: string|null, provenance: {commit: string, remote: string|null, dirty: boolean}|null}}
+ * @throws {Error}
+ */
+function readBaselineFromDisk(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (cause) {
+    throw new Error(
+      `archkeep: cannot read the baseline snapshot from '${path}': ${cause?.message ?? cause}`,
+      { cause },
+    );
+  }
+
+  return parseBaseline(text, path);
+}
+
+/**
+ * Parses and validates a baseline snapshot from its text content. Separated
+ * from `readBaselineFromDisk` so a test can inject the content without the
+ * filesystem.
+ *
+ * @param {string} text The raw JSON text of the baseline envelope.
+ * @param {string} path The path to name in error messages.
+ * @returns {{projects: object[], dependencies: object[], coverage: object, policy: object|null,
+ *   provider: string|null, provenance: {commit: string, remote: string|null, dirty: boolean}|null,
+ *   toolVersion: string|null}}
+ * @throws {Error}
+ */
+export function parseBaseline(text, path) {
+  let envelope;
+  try {
+    envelope = JSON.parse(text);
+  } catch (cause) {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' is not valid JSON: ${cause?.message ?? cause}`,
+      { cause },
+    );
+  }
+
+  if (envelope === null || typeof envelope !== "object" || Array.isArray(envelope)) {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' is not a JSON object — it is not a ` +
+        `archkeep graph envelope`,
+    );
+  }
+
+  if (typeof envelope.schemaVersion !== "number") {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' has no schemaVersion field — it is not a ` +
+        `archkeep graph envelope`,
+    );
+  }
+
+  // A consumer that reads a schemaVersion it does not recognise should refuse
+  // to parse the rest (`docs/reference/json-output.md`). This tool IS that
+  // consumer when reading a baseline — a future schema version could change
+  // the edge shape in ways this diff code would silently misinterpret.
+  if (envelope.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' uses schemaVersion ${envelope.schemaVersion}, ` +
+        `but this build only understands schemaVersion ${SCHEMA_VERSION}. A baseline from a later ` +
+        `major version may have a different shape this diff would silently misread; upgrade ` +
+        `archkeep or regenerate the snapshot.`,
+    );
+  }
+
+  if (envelope.command !== "graph") {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' is a '${envelope.command}' envelope, not a ` +
+        `'graph' envelope — diff requires a graph snapshot as its baseline`,
+    );
+  }
+
+  if (!envelope.coverage?.complete) {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' has incomplete coverage — every "removed" ` +
+        `entry in the diff would be ambiguous between "gone" and "never seen", so diff refuses ` +
+        `to compute against a baseline that could not fully read its tree`,
+    );
+  }
+
+  if (!Array.isArray(envelope.result?.projects)) {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' has no result.projects array — it is not a ` +
+        `archkeep graph snapshot`,
+    );
+  }
+
+  if (!Array.isArray(envelope.result?.dependencies)) {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' has no result.dependencies array — it is not a ` +
+        `archkeep graph snapshot`,
+    );
+  }
+
+  // Per-record validation: every project must have a name, root, and — when
+  // present — a `tags` array (an absent tags is the pre-tags shape; a malformed
+  // one would make the diff and every renderer misread the record). Every
+  // dependency must have source, target, and type. A malformed record would
+  // make the diff silently miscompute which projects or edges changed.
+  for (const [i, project] of envelope.result.projects.entries()) {
+    if (typeof project.name !== "string" || typeof project.root !== "string") {
+      throw new Error(
+        `archkeep: the baseline snapshot at '${path}' has a result.projects[${i}] record ` +
+          `missing 'name' or 'root' — it is not a valid archkeep project record`,
+      );
+    }
+    if (project.tags !== undefined && !Array.isArray(project.tags)) {
+      throw new Error(
+        `archkeep: the baseline snapshot at '${path}' has a result.projects[${i}] record whose ` +
+          `'tags' is not an array — it is not a valid archkeep project record`,
+      );
+    }
+  }
+
+  for (const [i, edge] of envelope.result.dependencies.entries()) {
+    if (
+      typeof edge.source !== "string" ||
+      typeof edge.target !== "string" ||
+      typeof edge.type !== "string"
+    ) {
+      throw new Error(
+        `archkeep: the baseline snapshot at '${path}' has a result.dependencies[${i}] record ` +
+          `missing 'source', 'target', or 'type' — it is not a valid archkeep dependency record`,
+      );
+    }
+  }
+
+  return {
+    projects: envelope.result.projects,
+    dependencies: envelope.result.dependencies,
+    coverage: envelope.coverage,
+    policy: envelope.result.policy ?? null,
+    provider: envelope.workspace?.provider ?? null,
+    provenance: envelope.workspace?.provenance ?? null,
+    toolVersion: envelope.tool?.version ?? null,
+  };
+}
+
+/**
+ * Builds the head snapshot from the command context using the same
+ * `buildProjects`/`buildDependencies` functions `graphCommand` uses, so the
+ * baseline is the only thing that comes from outside the run.
+ *
+ * @param {object} commandContext
+ * @returns {{projects: object[], dependencies: object[]}}
+ */
+function buildHeadSnapshot(commandContext) {
+  const { graph } = commandContext;
+  return {
+    projects: buildProjects(graph.nodes),
+    dependencies: buildDependencies(graph.dependencies),
+  };
+}
+
+/**
+ * Computes the diff between two graph snapshots.
+ *
+ * Edge identity is `(source, target, type)` — a `static` edge becoming
+ * `dynamic` is an added edge under the new type and a removed edge under the
+ * old one, which is exactly what a consumer wants to see: it is a real
+ * architectural event, not an implementation detail.
+ *
+ * @param {{projects: object[], dependencies: object[]}} baseline
+ * @param {{projects: object[], dependencies: object[]}} head
+ * @returns {{addedProjects: object[], removedProjects: object[],
+ *   changedProjects: {name: string, changes: {field: string, baseline: *, head: *}[]}[],
+ *   addedEdges: object[], removedEdges: object[]}}
+ */
+export function computeDiff(baseline, head) {
+  const baselineProjects = new Map(baseline.projects.map((p) => [p.name, p]));
+  const headProjects = new Map(head.projects.map((p) => [p.name, p]));
+
+  const addedProjects = [];
+  const removedProjects = [];
+  const changedProjects = [];
+
+  for (const [name, project] of headProjects) {
+    if (!baselineProjects.has(name)) {
+      addedProjects.push(project);
+      continue;
+    }
+    // Project exists in both — detect metadata changes.
+    const baselineProject = baselineProjects.get(name);
+    const changes = [];
+
+    // Tags change: array content differs.
+    const baselineTags = baselineProject.tags ?? [];
+    const headTags = project.tags ?? [];
+    if (baselineTags.length !== headTags.length || baselineTags.some((t, i) => t !== headTags[i])) {
+      changes.push({ field: "tags", baseline: baselineTags, head: headTags });
+    }
+
+    // Type change: one is undefined and the other is not, or both defined but different.
+    const baselineType = baselineProject.type ?? undefined;
+    const headType = project.type ?? undefined;
+    if (baselineType !== headType) {
+      changes.push({
+        field: "type",
+        baseline: baselineType ?? null,
+        head: headType ?? null,
+      });
+    }
+
+    // Root change: project directory moved.
+    if (baselineProject.root !== project.root) {
+      changes.push({ field: "root", baseline: baselineProject.root, head: project.root });
+    }
+
+    if (changes.length > 0) {
+      changedProjects.push({ name, changes });
+    }
+  }
+  for (const [name, project] of baselineProjects) {
+    if (!headProjects.has(name)) removedProjects.push(project);
+  }
+  // Deterministic order — plain string comparison.
+  addedProjects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  removedProjects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  changedProjects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  // Index edges by the (source, target, type) triple — the identity key.
+  const baselineEdges = new Map(
+    baseline.dependencies.map((e) => [`${e.source}\0${e.target}\0${e.type}`, e]),
+  );
+  const headEdges = new Map(
+    head.dependencies.map((e) => [`${e.source}\0${e.target}\0${e.type}`, e]),
+  );
+
+  const addedEdges = [];
+  const removedEdges = [];
+
+  for (const [key, edge] of headEdges) {
+    if (!baselineEdges.has(key)) addedEdges.push(edge);
+  }
+  for (const [key, edge] of baselineEdges) {
+    if (!headEdges.has(key)) removedEdges.push(edge);
+  }
+
+  const edgeSort = (a, b) => {
+    if (a.source < b.source) return -1;
+    if (a.source > b.source) return 1;
+    if (a.target < b.target) return -1;
+    if (a.target > b.target) return 1;
+    if (a.type < b.type) return -1;
+    if (a.type > b.type) return 1;
+    return 0;
+  };
+  addedEdges.sort(edgeSort);
+  removedEdges.sort(edgeSort);
+
+  return { addedProjects, removedProjects, changedProjects, addedEdges, removedEdges };
+}
+
+/**
+ * Runs the `diff` command: reads the baseline, resolves the head context,
+ * checks refusals, and computes the diff.
+ *
+ * @param {string} baselinePath Absolute path to the baseline JSON file.
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{readBaseline?: (path: string) => {projects: object[], dependencies: object[], coverage: object, policy?: object|null,
+ *   provider?: string|null, provenance?: {commit: string, remote: string|null, dirty: boolean}|null,
+ *   toolVersion?: string|null},
+ *   config?: object}} [io]
+ *   Injectable baseline reader, so a test drives the diff without a real file.
+ *   When omitted, reads from the real filesystem. `config` is the loaded
+ *   boundary config; when provided, rule-impact analysis is computed alongside
+ *   the structural diff.
+ * @returns {{status: "ok"|"no-verdict", diff: object, coverage: object,
+ *   report: {text: string, json: string}}}
+ * @throws {Error} when the baseline cannot be read or is incomplete, when
+ *   the head is incomplete, or when an Nx workspace has polyglot manifests
+ *   but the plugin is not registered.
+ */
+export function diffCommand(
+  baselinePath,
+  commandContext,
+  { readBaseline = readBaselineFromDisk, config = null } = {},
+) {
+  const { root, provider, marker, pluginGap } = commandContext;
+
+  // Descriptive commands refuse when the graph is known to be incomplete.
+  if (provider === "nx" && !pluginGap.registered && pluginGap.manifests.length > 0) {
+    throw new Error(
+      `archkeep: refusing to compute a diff for an Nx workspace where this plugin is ` +
+        `not registered but polyglot manifests exist under project roots ` +
+        `(${pluginGap.manifests.join(", ")}). The head graph would carry no polyglot edges, ` +
+        `so the diff would silently under-represent the real architecture. ` +
+        `Register the plugin in nx.json: ` +
+        `"plugins": [{ "plugin": "@ecoma-io/archkeep/nx" }], or remove the polyglot manifests ` +
+        `if they are not in use.`,
+    );
+  }
+
+  // Read and validate the baseline before looking at the head — a bad baseline
+  // is a caller error, not a workspace fact, and it should name the file.
+  const baseline = readBaseline(baselinePath);
+
+  // Refuse an incomplete head — same reasoning as the incomplete baseline
+  // refusal: every "added" or "removed" entry would be ambiguous.
+  const notAnalyzed = commandContext.analysis.failures
+    .filter(isWholeFileFailure)
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+
+  if (notAnalyzed.length > 0) {
+    throw new Error(
+      `archkeep: the head graph has incomplete coverage — ${notAnalyzed.length} file` +
+        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "added" or ` +
+        `"removed" entry in the diff would be ambiguous between a real change and a coverage ` +
+        `gap. Fix the unanalyzed files and re-run.`,
+    );
+  }
+
+  const head = buildHeadSnapshot(commandContext);
+
+  const diff = computeDiff(baseline, head);
+
+  const coverage = {
+    complete: true,
+    projects: head.projects.length,
+    analyzedFiles: commandContext.analysis.analyzed,
+    imports: commandContext.analysis.imports.length,
+    notAnalyzed: [],
+    blindSpots: commandContext.analysis.failures
+      .filter((f) => !isWholeFileFailure(f))
+      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    notes: [],
+  };
+
+  const context = { root, provider, marker, provenance: resolveProvenance(root) };
+  const result = {
+    baseline: {
+      path: baselinePath,
+      projects: baseline.projects.length,
+      edges: baseline.dependencies.length,
+      toolVersion: baseline.toolVersion,
+    },
+    head: { projects: head.projects.length, edges: head.dependencies.length },
+    addedProjects: diff.addedProjects,
+    removedProjects: diff.removedProjects,
+    changedProjects: diff.changedProjects,
+    addedEdges: diff.addedEdges,
+    removedEdges: diff.removedEdges,
+  };
+
+  // Provider, provenance, and policy comparison — the same facts `history`
+  // classifies as changes, compared here through the shared
+  // `./snapshot-meta.mjs` so the two commands cannot disagree about them.
+  // Each mismatch becomes a `coverage.notes` warning rather than a refusal:
+  // a provider migration, a cross-repository diff, or a policy change between
+  // baseline and head are all legitimate states a consumer must be told about.
+  const headProvenance = resolveProvenance(root);
+  const headFingerprint = config ? computePolicyFingerprint(config) : null;
+  const meta = compareSnapshotMetadata({
+    baselineProvider: baseline.provider,
+    headProvider: provider,
+    baselineProvenance: baseline.provenance,
+    headProvenance,
+    baselineFingerprint: baseline.policy?.fingerprint ?? null,
+    headFingerprint,
+  });
+
+  if (meta.providerChanged) {
+    coverage.notes.push(
+      `baseline provider (${baseline.provider}) differs from head provider (${provider}) — ` +
+        `structural differences may be provider-artefacts rather than real architectural changes`,
+    );
+  }
+
+  if (meta.crossRepo) {
+    coverage.notes.push(
+      `baseline provenance remote (${baseline.provenance.remote}) differs from head provenance remote (${headProvenance.remote}) — ` +
+        `the diff may be across unrelated repositories rather than two revisions of the same one`,
+    );
+  } else if (baseline.provenance && !headProvenance) {
+    coverage.notes.push(
+      `baseline carries provenance but the head does not — the consumer cannot verify the diff is between revisions of the same repository`,
+    );
+  } else if (!baseline.provenance && headProvenance) {
+    coverage.notes.push(
+      `head carries provenance but the baseline does not — the consumer cannot verify the diff is between revisions of the same repository`,
+    );
+  }
+
+  if (meta.policyChanged === true) {
+    // A policy change between baseline and head means every "introduced" or
+    // "resolved" violation in the rule-impact analysis may be an artefact of
+    // the policy change, not of a structural change — recorded so the
+    // consumer knows to interpret the diff with caution.
+    result.policyMismatch = meta.policyMismatch;
+  }
+
+  if (meta.policyOneSided) {
+    // One-sided policy warning: when only one side carries a policy
+    // fingerprint, rule-impact numbers (if any) are based on an incomplete
+    // picture. The consumer should interpret them with caution.
+    const side = baseline.policy?.fingerprint ? "baseline" : "head";
+    coverage.notes.push(
+      `policy fingerprint is present only on the ${side} side — ` +
+        `rule-impact results may not reflect the policy the other side was judged under`,
+    );
+  }
+
+  // Rule-impact analysis: when the boundary config is provided, judge each
+  // added/removed edge against the constraint table. This is not the full
+  // `evaluate` pipeline — it checks only the `depConstraints` violations
+  // that depend on project tags (3 of 15 violation types; not npm/circular/
+  // lazy-load rules, which need import-site details). A consumer who needs
+  // the complete verdict should run `check`.
+  if (config && config.depConstraints) {
+    const ruleImpact = computeRuleImpact(
+      diff,
+      commandContext.graph.nodes,
+      commandContext.graph.dependencies,
+      baseline.projects,
+      baseline.dependencies,
+      config.depConstraints,
+    );
+    result.ruleImpact = {
+      introduced: ruleImpact.introduced,
+      resolved: ruleImpact.resolved,
+    };
+    // The rule-impact analysis covers depConstraints only (3 of 15 violation
+    // types). A consumer seeing no introduced/resolved violations must not
+    // conclude the workspace is free of all boundary violations — only that
+    // no depConstraints violations were introduced or resolved on the changed
+    // edges. Run `check` for the complete verdict.
+    coverage.notes.push(
+      "per-edge rule-impact covers only depConstraints (3 of 15 violation types). " +
+        "A dependency with no rule-impact may still violate npm-ban, circular-dependency, " +
+        "lazy-load, or other rules that require import-site details. Run check for the " +
+        "complete verdict.",
+    );
+  }
+
+  // Diff is descriptive — always status "ok" when it completes. Even an
+  // architecture with many changes is not a "finding" in the boundary-enforcement
+  // sense, so this command never claims a violation's exit code.
+  const status = "ok";
+  const exitCode = 0;
+
+  const envelope = jsonEnvelope({
+    command: "diff",
+    context,
+    status,
+    exitCode,
+    coverage,
+    result,
+  });
+
+  return {
+    status,
+    diff: result,
+    coverage,
+    report: {
+      text: formatDiffReport({ diff: result, coverage }),
+      json: renderJson(envelope),
+    },
+  };
+}

package/src/commands/discover.mjs

@@ -0,0 +1,159 @@
+/**
+ * The `discover` command: observed facts first, and — under `--propose` — the
+ * candidate architecture those facts imply, marked as proposals that are never
+ * decisions.
+ *
+ * `discover` is descriptive, exactly like `graph`/`diff`/`drift`: it reads the
+ * resolved `CommandContext` (the same project model and analysis every command
+ * shares) and returns a report. It never exits 1. The two modes:
+ *
+ * - **descriptive (default)** — reports what was observed: projects, edges,
+ *   tags, and the analysis coverage. This is the read-only "what is here"
+ *   answer, one level richer than `graph` because it also states the coverage
+ *   a verdict over this tree could trust.
+ * - **`--propose`** — computes the candidate architecture over those same
+ *   observations (`src/governance/discovery-proposal.mjs`'s
+ *   `evaluateDiscovery`) and emits it with `proposed: true` and
+ *   `notAuthoritative: true` on every candidate. It never writes
+ *   `architecture-intent.json`, never mutates the workspace, and never hands
+ *   a candidate the authority of a decision.
+ *
+ * ## The empty-result invariant
+ *
+ * A workspace the run could not fully read (`notAnalyzed` non-empty) returns
+ * `status: "no-verdict"` → exit 3, the same refusal `graph`/`drift` make:
+ * every missing edge would be ambiguous between "gone" and "never seen".
+ * An Nx workspace with polyglot manifests and no plugin registration is
+ * refused the same way `graph` refuses it — the graph would silently
+ * under-represent the real architecture, and a candidate derived from it
+ * would be a fabrication wearing a proposal's name.
+ *
+ * A workspace with zero projects is NOT a refusal: it is the empty proposal
+ * with `unknown: true` (`evaluateDiscovery`'s contract), because zero observed
+ * projects is a complete observation — the honest answer is "nothing to
+ * propose", not a fabricated candidate set.
+ *
+ * ## Determinism
+ *
+ * The proposal evaluator sorts every leaf by plain string comparison, and the
+ * report renderers never re-sort, so two runs over an unchanged tree produce
+ * byte-identical text and JSON — the same promise `graph`'s snapshots make,
+ * which is what lets a consumer `diff` two proposals meaningfully.
+ */
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { evaluateDiscovery } from "../governance/discovery-proposal.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatDiscoverReport } from "../report/discover-text.mjs";
+import { buildDependencies, buildProjects } from "./graph.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+import { refuseIncompleteGraph } from "./drift.mjs";
+
+/**
+ * The observed side of discovery: the same project model `graph` builds,
+ * shared with `graph`/`drift` so the facts `discover` reports are the facts
+ * every other command judges. Edges whose target is not a project in the
+ * model are dropped, the same filter drift applies (`./drift.mjs`): an
+ * external package is not a project a candidate can ever name.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @returns {{projects: object[], edges: object[]}}
+ */
+export function buildObserved(commandContext) {
+  const { graph } = commandContext;
+  const projects = buildProjects(graph.nodes);
+  const projectNames = new Set(projects.map((p) => p.name));
+  const edges = [];
+  for (const edge of buildDependencies(graph.dependencies)) {
+    if (edge.type === "implicit") continue;
+    if (projectNames.has(edge.source) && projectNames.has(edge.target)) {
+      edges.push(edge);
+    }
+  }
+  return { projects, edges };
+}
+
+/**
+ * Runs the `discover` command: observes the workspace, optionally proposes the
+ * candidate architecture over it, and returns the report.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{propose?: boolean}} [options]
+ * @returns {{status: "ok"|"no-verdict", discovery: object, proposal: object|null,
+ *   coverage: object, report: {text: string, json: string}}}
+ * @throws {Error} on every condition the header lists, all exit-3 class.
+ */
+export function discoverCommand(commandContext, { propose = false } = {}) {
+  const { root, provider, marker, analysis } = commandContext;
+
+  refuseIncompleteGraph(commandContext);
+
+  const notAnalyzed = analysis.failures
+    .filter(isWholeFileFailure)
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+
+  const observed = buildObserved(commandContext);
+
+  const proposal = propose ? evaluateDiscovery(observed) : null;
+
+  // A proposal over an unread tree would be a fabrication wearing a
+  // proposal's name: every candidate edge would be ambiguous between "gone"
+  // and "never seen". Refuse loudly — the same reasoning `drift`'s refusal
+  // gives — rather than print a proposal and a warning that it may be lying.
+  if (propose && notAnalyzed.length > 0) {
+    throw new Error(
+      `archkeep: discover --propose has incomplete coverage — ${notAnalyzed.length} file` +
+        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every candidate ` +
+        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and ` +
+        `re-run.`,
+    );
+  }
+
+  const complete = notAnalyzed.length === 0;
+  const status = complete ? "ok" : "no-verdict";
+  const exitCode = complete ? 0 : 3;
+
+  const coverage = {
+    complete,
+    projects: observed.projects.length,
+    analyzedFiles: analysis.analyzed,
+    imports: analysis.imports.length,
+    notAnalyzed,
+    blindSpots: analysis.failures
+      .filter((failure) => !isWholeFileFailure(failure))
+      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    notes: [],
+  };
+
+  const context = { root, provider, marker, provenance: resolveProvenance(root) };
+  const discovery = {
+    projects: observed.projects,
+    edges: observed.edges,
+    tags: Array.from(new Set(observed.projects.flatMap((project) => project.tags))).sort((a, b) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    ),
+  };
+
+  const envelope = jsonEnvelope({
+    command: "discover",
+    context,
+    status,
+    exitCode,
+    coverage,
+    result: { discovery, ...(proposal ? { proposal } : {}) },
+  });
+
+  return {
+    status,
+    discovery,
+    proposal,
+    coverage,
+    report: {
+      text: formatDiscoverReport({
+        discovery,
+        proposal,
+        coverage,
+      }),
+      json: renderJson(envelope),
+    },
+  };
+}