@ecoma-io/archkeep 0.13.0

package/src/commands/graph.mjs

@@ -0,0 +1,297 @@
+/**
+ * The `graph` command: the project graph as a deterministic, serialisable
+ * snapshot.
+ *
+ * `graph` reads the same project model every other command reads — Nx or
+ * native, resolved by `./context.mjs` — and returns it as two sorted arrays:
+ * one of projects and one of edges. It strips every internal field the rule
+ * engine uses but that is not a fact about the consumer's architecture
+ * (`../../AGENTS.md` documents that snapshots do not publish `mfeRemote`,
+ * `entryPoints`, or `declaredPackages`). It is descriptive: it never exits 1,
+ * because a snapshot of what is is never a finding.
+ *
+ * What it needs from its caller is a `CommandContext` — the preamble every
+ * command shares (`./context.mjs`). What it gives back is a `status`, the
+ * 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
+ *
+ * On an Nx workspace whose `nx.json` does not register this plugin but whose
+ * tracked files include polyglot manifests under project roots, `graph`
+ * refuses loudly rather than returning a snapshot whose edges silently
+ * under-represent the real architecture. The refusal is narrowed to that
+ * condition: a pure-TypeScript Nx workspace whose graph is complete without
+ * this plugin is never refused. No escape flag: an option that made analysis
+ * not run would turn an unknown result into an apparently valid snapshot.
+ */
+import { createHash } from "node:crypto";
+
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { canonicalizeJson } from "../canonical.mjs";
+import { DEFAULT_WORKSPACE_LAYOUT } from "../rules/specifiers.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatGraphReport } from "../report/graph-text.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+
+/**
+ * The fields stripped from every project node before it enters the snapshot.
+ * Each of these is a fact about how this tool reads upstream, not a fact about
+ * the consumer's architecture; publishing them in a versioned contract would
+ * freeze upstream's internal shape into ours.
+ */
+const INTERNAL_DATA_FIELDS = Object.freeze(["mfeRemote", "entryPoints", "declaredPackages"]);
+
+/**
+ * Builds the project list for the graph snapshot: one entry per node, sorted
+ * by name using plain string comparison (never `localeCompare` —
+ * two runs over an unchanged tree must produce byte-identical JSON, and
+ * `localeCompare` depends on locale and ICU data).
+ *
+ * `targets` is emitted as `Object.keys(node.data.targets)` only when the node
+ * declares any — the field is omitted, not `[]`, because a native project
+ * genuinely has no target table and an empty array would assert it has none
+ * declared when the concept does not apply. Iterate with `Object.hasOwn`
+ * guards because the native graph's null-prototype containers exist for
+ * `__proto__` safety and a naive `for…in` over a reconstructed object undoes
+ * it.
+ *
+ * @param {object} nodes The `graph.nodes` map from the project graph.
+ * @returns {object[]}
+ */
+export function buildProjects(nodes) {
+  return (
+    Object.values(nodes)
+      .map((node) => {
+        // Strip internal fields: they belong to this tool's rule engine, not to
+        // the consumer's architecture. The project's `data` object may carry
+        // `mfeRemote`, `entryPoints` and `declaredPackages` — computed by
+        // `../workspace.mjs`'s two annotators to reproduce upstream behaviour —
+        // but a versioned contract that published them would freeze upstream's
+        // internal shape into ours.
+        const data = { ...node.data };
+        for (const field of INTERNAL_DATA_FIELDS) {
+          delete data[field];
+        }
+        const project = {
+          name: node.name,
+          root: data.root,
+          type: node.type,
+          tags: (data.tags ?? []).slice().sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+        };
+        // Emit `targets` only when the node declares any. A native project has
+        // no target table, and an empty array would falsely assert "zero
+        // targets declared" when the concept does not apply.
+        const targets =
+          data.targets && Object.hasOwn(data, "targets")
+            ? Object.keys(data.targets).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+            : undefined;
+        if (targets !== undefined && targets.length > 0) {
+          project.targets = targets;
+        }
+        return project;
+      })
+      // Plain string comparison — never localeCompare. Determinism is part of
+      // the contract: two runs over an unchanged tree must produce byte-identical
+      // JSON, because `diff`'s whole premise is that a difference in the bytes
+      // means a difference in the architecture. localeCompare depends on the
+      // locale and the Node build's ICU data, so a snapshot taken on CI and
+      // diffed on a developer's machine could differ in order alone.
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  );
+}
+
+/**
+ * Builds the flat sorted edge array from the Nx source-keyed dependency map.
+ *
+ * Edge identity is `(source, target, type)` — keying on `(source, target)`
+ * alone would hide a `static`->`dynamic` change, a real architectural event.
+ *
+ * @param {object} dependencies The `graph.dependencies` map.
+ * @returns {{source: string, target: string, type: string}[]}
+ */
+export function buildDependencies(dependencies) {
+  const edges = [];
+  for (const source of Object.keys(dependencies)) {
+    if (!Object.hasOwn(dependencies, source)) continue;
+    const targets = dependencies[source];
+    for (const edge of targets) {
+      edges.push({
+        source,
+        target: edge.target,
+        type: edge.type,
+      });
+    }
+  }
+  return edges.sort((a, b) => {
+    // Three-key lexicographic sort, plain string comparison throughout.
+    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;
+  });
+}
+
+/**
+ * Computes a deterministic fingerprint for the boundary policy, so `diff`
+ * can warn when the policy changed between runs without re-implementing the
+ * config comparison logic.
+ *
+ * The fingerprint is SHA-256 of the canonicalized JSON for `depConstraints`,
+ * `options`, `suppressions` and — when the policy declares them — `fitness`
+ * and `customRules`. Those are every field of a loaded policy that states
+ * law: the first three decide which violations `evaluate` produces, the
+ * fourth decides which fitness functions `check` folds into the same exit
+ * code (`../governance/fitness-registry.mjs`), and the fifth names the rule
+ * artifacts a workspace declared, each pinned to the bytes its `sha256` claims
+ * (`../config.mjs`'s `customRuleRowViolations`) — swap one row's hash or its
+ * `params` and the policy says something different. A field that can fail a
+ * build and is not in the hash is a law that can be rewritten while `diff`
+ * reports the policy unchanged — the silent direction, and the reason the list
+ * here and `policyFrom`'s return shape (`../config.mjs`) are revisited
+ * together.
+ *
+ * `fitness` and `customRules` are included only when they are DECLARED, and
+ * the absent case contributes no key rather than an empty array. A policy that
+ * declares neither therefore fingerprints exactly as it did before those
+ * fields were covered, so extending the hash did not move every existing
+ * snapshot's value — only those whose law it was failing to describe.
+ *
+ * @param {object} config The loaded boundary config.
+ * @returns {string} A hex-encoded SHA-256 fingerprint.
+ */
+export function computePolicyFingerprint(config) {
+  const policy = {
+    depConstraints: config.depConstraints ?? [],
+    options: config.options ?? {},
+    suppressions: config.suppressions ?? [],
+    ...(config.fitness === undefined ? {} : { fitness: config.fitness }),
+    ...(config.customRules === undefined ? {} : { customRules: config.customRules }),
+  };
+  // Canonicalise: sort object keys at every depth so insertion order does not
+  // affect the hash. Semantic equality, not construction order, is the claim —
+  // the same canonicalizer the intent fingerprint uses
+  // (`../architecture-intent/intent-fingerprint.mjs`), so two fingerprints
+  // cannot drift from two serializations.
+  const canonical = canonicalizeJson(policy);
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+/**
+ * Runs the `graph` command: resolves the command context, checks the
+ * unregistered-plugin condition, and returns the snapshot.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{config?: object}} [io] Optional IO overrides. `config` is the loaded
+ *   boundary config; when provided, a `policy` fingerprint is included in the
+ *   snapshot so `diff` can warn when the policy changed between runs.
+ * @returns {{status: "ok"|"no-verdict", projects: object[], dependencies: object[],
+ *   workspaceLayout: {appsDir: string, libsDir: string}, workspaceLayoutSource: string,
+ *   policy: {fingerprint: string}|undefined,
+ *   coverage: object, report: {text: string, json: string}}}
+ * @throws {Error} when an Nx workspace has polyglot manifests but the plugin
+ *   is not registered — the graph would silently under-represent the real
+ *   architecture.
+ */
+export function graphCommand(commandContext, { config = null } = {}) {
+  const { root, provider, marker, graph, pluginGap } = commandContext;
+
+  // Descriptive commands refuse when the graph is known to be incomplete.
+  // On an Nx workspace, if the plugin is not registered but polyglot manifests
+  // exist under project roots, the graph carries no polyglot edges and the
+  // snapshot would be a lie about the architecture — every "removed" edge in a
+  // later `diff` would be ambiguous between "gone" and "never seen".
+  if (provider === "nx" && !pluginGap.registered && pluginGap.manifests.length > 0) {
+    throw new Error(
+      `archkeep: refusing to build a graph snapshot for an Nx workspace where this plugin is ` +
+        `not registered but polyglot manifests exist under project roots ` +
+        `(${pluginGap.manifests.join(", ")}). The graph would carry no polyglot edges, ` +
+        `so the snapshot 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.`,
+    );
+  }
+
+  const notAnalyzed = commandContext.analysis.failures
+    .filter(isWholeFileFailure)
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+
+  const complete = notAnalyzed.length === 0;
+  const status = complete ? "ok" : "no-verdict";
+  const exitCode = complete ? 0 : 3;
+
+  const projects = buildProjects(graph.nodes);
+  const dependencies = buildDependencies(graph.dependencies);
+
+  // `workspaceLayout` is carried on the graph object when the provider knows
+  // it. When absent, the engine's own default applies — imported from
+  // `../rules/specifiers.mjs` rather than written a second time here, because
+  // two copies of a default is how a report ends up describing a layout the
+  // engine did not use.
+  const workspaceLayout = Object.hasOwn(graph, "workspaceLayout")
+    ? graph.workspaceLayout
+    : DEFAULT_WORKSPACE_LAYOUT;
+  const workspaceLayoutSource = Object.hasOwn(graph, "workspaceLayout") ? "declared" : "default";
+
+  const coverage = {
+    complete,
+    projects: 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 = {
+    projects,
+    dependencies,
+    workspaceLayout,
+    workspaceLayoutSource,
+  };
+
+  // When the boundary config is provided, include a policy fingerprint so
+  // `diff` can warn when the policy changed between runs. Without a config,
+  // the snapshot carries no policy identity — the consumer did not provide one.
+  if (config) {
+    result.policy = { fingerprint: computePolicyFingerprint(config) };
+  }
+
+  const envelope = jsonEnvelope({
+    command: "graph",
+    context,
+    status,
+    exitCode,
+    coverage,
+    result,
+  });
+
+  return {
+    status,
+    projects,
+    dependencies,
+    workspaceLayout,
+    workspaceLayoutSource,
+    policy: result.policy,
+    coverage,
+    report: {
+      text: formatGraphReport({
+        projects,
+        dependencies,
+        workspaceLayout,
+        workspaceLayoutSource,
+        coverage,
+      }),
+      json: renderJson(envelope),
+    },
+  };
+}

package/src/commands/health.mjs

@@ -0,0 +1,213 @@
+/**
+ * The `health` command: deterministic architecture-health metrics and trends
+ * for the current workspace — the numbers a maintainer acts on, computed
+ * read-only, with no service behind them.
+ *
+ * `health` measures the run's `{ projects, dependencies, analysis, coverage,
+ * intent }` and reports, per metric, a verdict in the canonical vocabulary the
+ * governance wave shares (`../governance/metrics.mjs`'s header owns the four
+ * states). It is **descriptive**, exactly like `graph`/`diff`/`impact`:
+ * it never exits 1, because a description of how healthy the architecture is
+ * is never itself a finding. Which verbs DO carry exit 1 is settled in
+ * `./README.md`, and it is not this one.
+ *
+ * ## What it reports
+ *
+ * - **Per-run metrics** — violation count, waiver surface, debt rows, coverage
+ *   ratio, project/edge counts, cycle count, edge density, and the intent
+ *   (fitness) verdict. Every number is re-derived from records the run already
+ *   holds through the same functions `check`/`graph`/`drift` use, so health
+ *   performs no new scans and cannot disagree with those commands about the
+ *   same tree.
+ * - **Per-metric verdicts** — each metric is decided over complete evidence or
+ *   says it could not look. A metric with no evidence reads `not_applicable`;
+ *   a metric whose evidence is partial reads `unknown`. **A metric is never
+ *   reported as a bare zero over evidence the run could not inspect** — that
+ *   is the empty-result invariant applied at the metric level.
+ * - **Trends** — the same metrics over the snapshot directory `history` reads
+ *   (`.archkeep/history/` by convention), so a maintainer sees how each metric
+ *   moved between snapshots. Trends are limited to what a `graph` snapshot
+ *   carries: structural metrics over the snapshots, with the disclosure that
+ *   rule-impact cannot be re-derived from stored bytes (`../commands/history.mjs`
+ *   states the same limit).
+ *
+ * ## The status contract
+ *
+ * `health` returns `status: "ok"` when every metric reached a verdict
+ * (`ok`, `findings`, or `not_applicable`) and `status: "no-verdict"` when any
+ * metric is `unknown` — a run that could not fully inspect its own evidence is
+ * not a healthy run, and a descriptive command's `no-verdict` is exit 3, the
+ * same code `graph`/`impact` use for incomplete coverage. It never changes
+ * the verdict or exit code of any other command: `health` is purely additive.
+ *
+ * It does not print, and it does not decide the process's exit code —
+ * `../../cli.mjs` owns those (`./README.md`).
+ */
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { buildDependencies, buildProjects } from "./graph.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatHealthReport } from "../report/health-text.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+import { readSnapshots } from "./history.mjs";
+import {
+  boundaryMetrics,
+  couplingMetrics,
+  debtMetric,
+  intentMetric,
+  structuralMetrics,
+} from "../governance/metrics.mjs";
+import { judgeIntent } from "../architecture-intent/judge.mjs";
+
+/**
+ * Computes the intent verdict the fitness metric reads — the same `judgeIntent`
+ * call `drift`/`check` make, so health and those commands cannot disagree about
+ * the same intent file.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {object|null} intent The loaded intent model, or `null` when the
+ *   workspace has no intent file.
+ * @returns {{ok: boolean, findings: object[], unresolved: object[]}|null}
+ */
+function intentVerdict(commandContext, intent) {
+  if (intent === null) return null;
+  const judged = judgeIntent(intent, {
+    nodes: commandContext.graph.nodes,
+    dependencies: commandContext.graph.dependencies,
+  });
+  return {
+    ok: judged.findings.length === 0 && judged.unresolved.length === 0,
+    findings: judged.findings,
+    unresolved: judged.unresolved,
+  };
+}
+
+/**
+ * Runs the `health` command: derives the metrics from the resolved command
+ * context, reads the trend snapshots, and builds the report.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{config?: object|null, intent?: object|null, trendDir?: string|null,
+ *   readSnapshots?: Function}} [io]
+ *   `config` is the loaded boundary law (or `null` when the workspace provides
+ *   none — the same loading `check`/`graph` do, so `--config` in `cli.mjs`
+ *   overrides the workspace's own). `intent` is the loaded intent model (or
+ *   `null`). `trendDir` names the snapshot directory for trends, optional —
+ *   health reports trends only when one is given. `readSnapshots` is
+ *   injectable so a test drives trends without the filesystem.
+ * @returns {{status: "ok"|"no-verdict", metrics: object, trends: object|null,
+ *   coverage: object, report: {text: string, json: string}}}
+ * @throws {Error} when the trend directory cannot be read (the same malformed
+ *   snapshot dir condition `history` exits 3 on).
+ */
+export function healthCommand(commandContext, io = {}) {
+  const { root, provider, marker, graph, analysis, pluginGap } = commandContext;
+  const config = io.config === undefined ? null : io.config;
+  const intent = io.intent === undefined ? null : io.intent;
+
+  const projects = buildProjects(graph.nodes);
+  const edges = buildDependencies(graph.dependencies);
+
+  // The run's coverage facts, the same shape every command's envelope carries.
+  const fileComplete = analysis.failures.filter(isWholeFileFailure).length === 0;
+  // The graph is complete only when the files are AND the graph actually sees
+  // every polyglot edge — an Nx workspace with an unregistered plugin carries
+  // a graph with no Go/Rust/Python edges, which `graph`/`impact` refuse and
+  // health must report `unknown` rather than measure.
+  const graphComplete =
+    fileComplete && !(provider === "nx" && !pluginGap.registered && pluginGap.manifests.length > 0);
+  const coverage = {
+    complete: fileComplete,
+    projects: projects.length,
+    analyzedFiles: analysis.analyzed,
+    imports: analysis.imports.length,
+    notAnalyzed: analysis.failures
+      .filter(isWholeFileFailure)
+      .map(({ sourceFile, reason }) => ({ file: sourceFile, reason })),
+    blindSpots: analysis.failures
+      .filter((f) => !isWholeFileFailure(f))
+      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    notes: graphComplete
+      ? []
+      : [
+          "the Nx plugin is not registered for polyglot manifests — the graph carries no " +
+            "Go/Rust/Python edges, so edge, cycle and boundary metrics read unknown",
+        ],
+  };
+
+  const graphCoverage = { ...coverage, complete: graphComplete };
+  const structural = structuralMetrics({ projects, edges }, coverage, graphComplete);
+  const boundary = boundaryMetrics(analysis.imports, graph, config, graphCoverage);
+  const intentVerd = intentVerdict(commandContext, intent);
+  const fitness = intentMetric(intentVerd);
+  const coupling = couplingMetrics(projects, edges, graphCoverage);
+  const debt = debtMetric(config);
+
+  const metrics = {
+    projects: structural.projects,
+    edges: structural.edges,
+    coverage: structural.coverage,
+    violations: boundary.violations,
+    waiverSurface: boundary.waiverSurface,
+    cycles: coupling.cycles,
+    edgeDensity: coupling.edgeDensity,
+    debt: debt,
+    fitness: fitness,
+  };
+
+  // A run with any `unknown` metric is a no-verdict: it could not fully inspect
+  // its own evidence, so the healthy claim it would make is not one it can
+  // establish. `not_applicable` is fine (a metric with nothing to measure is
+  // not a gap); `unknown` is exactly the gap.
+  const hasUnknown = Object.values(metrics).some((m) => m.verdict === "unknown");
+  const status = hasUnknown ? "no-verdict" : "ok";
+
+  // Trends: the same structural metrics over the snapshots `history` reads.
+  // A trend is available only when a snapshot directory is named, and it is
+  // limited to what a `graph` snapshot carries — rule-impact cannot be
+  // re-derived from stored bytes.
+  let trends = null;
+  if (io.trendDir) {
+    const read = io.readSnapshots
+      ? io.readSnapshots(io.trendDir)
+      : readSnapshots(io.trendDir, root);
+    trends = {
+      snapshots: read.files.map((f) => ({
+        name: f.name,
+        projects: f.envelope.result.projects.length,
+        dependencies: f.envelope.result.dependencies.length,
+      })),
+      notes: [
+        "rule-impact metrics (violations, waivers, debt, fitness) cannot be re-derived from " +
+          "stored snapshots — snapshots carry the graph and the policy fingerprint, not the " +
+          "constraint table or import sites. Run `check` at any commit for those.",
+      ],
+    };
+  }
+
+  const context = { root, provider, marker, provenance: resolveProvenance(root) };
+  const result = {
+    trendDir: io.trendDir ?? null,
+    metrics,
+    trends,
+  };
+
+  const envelope = jsonEnvelope({
+    command: "health",
+    context,
+    status,
+    exitCode: status === "ok" ? 0 : 3,
+    coverage,
+    result,
+  });
+
+  return {
+    status,
+    metrics,
+    trends,
+    coverage,
+    report: {
+      text: formatHealthReport({ metrics, trends, coverage }),
+      json: renderJson(envelope),
+    },
+  };
+}