@ecoma-io/archkeep 0.13.0

package/src/commands/explain.mjs

@@ -0,0 +1,359 @@
+/**
+ * The `explain` command: the judgment for one import site, explained.
+ *
+ * `explain` takes a `file:line:column` site, finds the matching import
+ * record, and explains the judgment: which constraint row matched, which tags
+ * applied, whether it is a violation and why. It is descriptive: it never
+ * exits 1, because an explanation of what the rules decided is never a finding
+ * .
+ *
+ * What it needs from its caller is a site string, a `CommandContext`, and the
+ * loaded boundary config — the preamble every command shares
+ * (`./context.mjs`) plus the law the judgment was made under
+ * (`../config.mjs`). What it gives back is a `status`, the explanation 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, `explain` refuses loudly rather than explaining a judgment from a
+ * graph whose edges silently under-represent the real architecture.
+ */
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { UsageError } from "../errors.mjs";
+import { evaluate } from "../rules/index.mjs";
+import { findConstraintsFor } from "../rules/tags.mjs";
+import { findProjectForPath, createProjectRootMappings } from "../rules/specifiers.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatExplainReport } from "../report/explain-text.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+
+/**
+ * Parses a `file:line:column` site string into its components.
+ *
+ * All three parts are required and must be positive integers. The file part
+ * may contain any characters except the two colons that delimit the segments.
+ *
+ * @param {string} site A `file:line:column` string.
+ * @returns {{ sourceFile: string, line: number, column: number }}
+ * @throws {UsageError} when the site string is malformed.
+ */
+export function parseSite(site) {
+  const lastColon = site.lastIndexOf(":");
+  if (lastColon === -1 || lastColon === 0) {
+    throw new UsageError(
+      `archkeep: '${site}' is not a valid site — expected <file>:<line>:<column>`,
+    );
+  }
+  const secondLastColon = site.lastIndexOf(":", lastColon - 1);
+  if (secondLastColon === -1) {
+    throw new UsageError(
+      `archkeep: '${site}' is not a valid site — expected <file>:<line>:<column>`,
+    );
+  }
+  const sourceFile = site.slice(0, secondLastColon);
+  const lineStr = site.slice(secondLastColon + 1, lastColon);
+  const columnStr = site.slice(lastColon + 1);
+
+  if (!sourceFile) {
+    throw new UsageError(`archkeep: '${site}' is not a valid site — the file part is empty`);
+  }
+
+  const line = Number(lineStr);
+  const column = Number(columnStr);
+  if (!Number.isInteger(line) || line < 1) {
+    throw new UsageError(
+      `archkeep: '${site}' is not a valid site — line must be a positive integer, got '${lineStr}'`,
+    );
+  }
+  if (!Number.isInteger(column) || column < 1) {
+    throw new UsageError(
+      `archkeep: '${site}' is not a valid site — column must be a positive integer, got '${columnStr}'`,
+    );
+  }
+  return { sourceFile, line, column };
+}
+
+/**
+ * Finds the import record matching a parsed site.
+ *
+ * An import record matches when its `sourceFile`, `line`, and `column` all
+ * agree. At most one record should match a given site.
+ *
+ * @param {{sourceFile: string, line: number, column: number}} parsed
+ * @param {object[]} imports The analysis import records.
+ * @returns {object|null} The matching record, or `null`.
+ */
+export function findSite(parsed, imports) {
+  return (
+    imports.find(
+      (site) =>
+        site.sourceFile === parsed.sourceFile &&
+        site.line === parsed.line &&
+        site.column === parsed.column,
+    ) ?? null
+  );
+}
+
+/**
+ * Finds the constraint rows that match a source project's tags.
+ *
+ * This is the "allowed" counterpart to `evaluate`: `evaluate` returns
+ * violations, and this returns the constraints that WERE satisfied. A project
+ * with no matching constraints would have been reported as
+ * `projectWithoutTagsCannotHaveDependencies` by `evaluate`, so reaching this
+ * function with no matches means the site was judged before the constraint
+ * table was consulted (e.g. it was `allow`ed, or it reached an app).
+ *
+ * @param {object[]} depConstraints The config's constraint table.
+ * @param {object} sourceProjectNode The graph node for the source project.
+ * @returns {object[]}
+ */
+function findMatchingConstraints(depConstraints, sourceProjectNode) {
+  return findConstraintsFor(depConstraints, sourceProjectNode);
+}
+
+/**
+ * Runs the `explain` command: resolves the command context, finds the import
+ * site, evaluates the rules, and returns the explanation.
+ *
+ * @param {string} site A `file:line:column` string.
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {object} config The loaded boundary config (from `loadBoundaryConfig`).
+ * @returns {{status: "ok"|"no-verdict", explanation: object, coverage: object,
+ *   report: {text: string, json: string}}}
+ * @throws {Error} when the plugin is unregistered on a polyglot Nx workspace,
+ *   when the site string is malformed, or when the site cannot be found.
+ */
+export function explainCommand(site, commandContext, config) {
+  const { root, provider, marker, graph } = commandContext;
+
+  // Descriptive commands refuse when the graph is known to be incomplete.
+  if (
+    provider === "nx" &&
+    !commandContext.pluginGap.registered &&
+    commandContext.pluginGap.manifests.length > 0
+  ) {
+    throw new Error(
+      `archkeep: refusing to explain a judgment for an Nx workspace where this plugin is ` +
+        `not registered but polyglot manifests exist under project roots ` +
+        `(${commandContext.pluginGap.manifests.join(", ")}). The graph would carry no polyglot edges, ` +
+        `so the judgment would be against an incomplete graph. ` +
+        `Register the plugin in nx.json: ` +
+        `"plugins": [{ "plugin": "@ecoma-io/archkeep/nx" }], or remove the polyglot manifests ` +
+        `if they are not in use.`,
+    );
+  }
+
+  const parsed = parseSite(site);
+
+  const notAnalyzed = commandContext.analysis.failures
+    .filter(isWholeFileFailure)
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+
+  const complete = notAnalyzed.length === 0;
+  const status = complete ? "ok" : "no-verdict";
+
+  // Find the import record at this site.
+  const record = findSite(parsed, commandContext.analysis.imports);
+
+  if (record === null) {
+    // Check whether the site's file had a whole-file failure.
+    const wholeFileFailure = commandContext.analysis.failures.find(
+      (f) => isWholeFileFailure(f) && f.sourceFile === parsed.sourceFile,
+    );
+    if (wholeFileFailure) {
+      throw new Error(
+        `archkeep: ${parsed.sourceFile} could not be analyzed at all ` +
+          `(${wholeFileFailure.reason}), so no import site at ` +
+          `${parsed.sourceFile}:${parsed.line}:${parsed.column} exists to explain`,
+      );
+    }
+
+    // Check whether this specific site had a site-level failure.
+    const siteFailure = commandContext.analysis.failures.find(
+      (f) =>
+        !isWholeFileFailure(f) &&
+        f.sourceFile === parsed.sourceFile &&
+        f.line === parsed.line &&
+        f.column === parsed.column,
+    );
+
+    if (siteFailure) {
+      // Site-level failure: the file was analyzed but this import site is
+      // unresolvable. Report it as such — the file was judged, one position
+      // in it has no answer.
+      const explanation = {
+        site: { file: parsed.sourceFile, line: parsed.line, column: parsed.column },
+        import: null,
+        sourceProject: null,
+        targetProject: null,
+        sourceTags: [],
+        targetTags: [],
+        matchedConstraints: [],
+        violations: null,
+        unresolvable: true,
+        reason: siteFailure.reason,
+      };
+
+      const context = { root, provider, marker, provenance: resolveProvenance(root) };
+      const coverage = {
+        complete,
+        projects: Object.keys(graph.nodes).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 result = {
+        site: explanation.site,
+        unresolvable: true,
+        reason: siteFailure.reason,
+      };
+
+      const envelope = jsonEnvelope({
+        command: "explain",
+        context,
+        status,
+        exitCode: complete ? 0 : 3,
+        coverage,
+        result,
+      });
+
+      return {
+        status,
+        explanation,
+        coverage,
+        report: {
+          text: formatExplainReport({ explanation, coverage }),
+          json: renderJson(envelope),
+        },
+      };
+    }
+
+    // No record and no failure at this site — the position does not exist.
+    throw new Error(
+      `archkeep: no import site at ${parsed.sourceFile}:${parsed.line}:${parsed.column} — ` +
+        `that position does not correspond to any import this tool found. ` +
+        `Check the file, line and column; remember that line and column are 1-based.`,
+    );
+  }
+
+  // Evaluate the rules to find violations for ALL sites, then filter to this
+  // one. We run the full evaluation rather than a single-site evaluation
+  // because `evaluate` is pure and some rules (circular dependencies, lazy
+  // loading) depend on the whole file graph — they cannot be computed on one
+  // site in isolation.
+  const allViolations = evaluate(commandContext.analysis.imports, graph, config);
+  const siteViolations = allViolations.filter(
+    (v) =>
+      v.sourceFile === parsed.sourceFile && v.line === parsed.line && v.column === parsed.column,
+  );
+
+  // Derive source and target projects from the graph.
+  // `sourceProject` is NOT on the import record — the analysis contract
+  // (`../analysis/contract.md`) keeps no project name on the record. It is
+  // derived the same way `evaluate` derives it: by walking up the source
+  // file's directory path against the project root mappings. `target` comes
+  // from the record's resolved field, which the analysis resolver provides.
+  const mappings = createProjectRootMappings(graph.nodes);
+  const sourceProjectName = findProjectForPath(record.sourceFile, mappings) ?? null;
+  const targetProjectName = record.resolved?.target ?? null;
+
+  const sourceProjectNode = sourceProjectName ? (graph.nodes[sourceProjectName] ?? null) : null;
+  const targetProjectNode = targetProjectName ? (graph.nodes[targetProjectName] ?? null) : null;
+
+  const sourceTags = sourceProjectNode ? (sourceProjectNode.data?.tags ?? []) : [];
+  const targetTags = targetProjectNode ? (targetProjectNode.data?.tags ?? []) : [];
+
+  // Find which constraint rows match the source project's tags — this is the
+  // "allowed" explanation. A project with no matching constraints would have
+  // been flagged by `evaluate` as `projectWithoutTagsCannotHaveDependencies`.
+  const matchedConstraints = sourceProjectNode
+    ? findMatchingConstraints(config.depConstraints, sourceProjectNode)
+    : [];
+
+  let violations = null;
+  if (siteViolations.length > 0) {
+    // A site can produce multiple violations — e.g. `bannedExternalImports`
+    // and `noTransitiveDependencies` can fire together. An agent seeing only
+    // the first might fix it and be confused when `check` still fails. Return
+    // all of them so the consumer sees the complete picture.
+    violations = siteViolations.map((v) => ({
+      messageId: v.messageId,
+      message: v.message,
+      constraint: v.constraint,
+    }));
+  }
+
+  const explanation = {
+    site: { file: parsed.sourceFile, line: parsed.line, column: parsed.column },
+    import: {
+      specifier: record.specifier,
+      kind: record.kind,
+      sourceProject: sourceProjectName,
+      targetProject: targetProjectName,
+    },
+    sourceProject: sourceProjectName,
+    targetProject: targetProjectName,
+    sourceTags,
+    targetTags,
+    matchedConstraints,
+    violations,
+    unresolvable: false,
+    reason: null,
+  };
+
+  const context = { root, provider, marker, provenance: resolveProvenance(root) };
+  const coverage = {
+    complete,
+    projects: Object.keys(graph.nodes).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 result = {
+    site: explanation.site,
+    import: explanation.import,
+    sourceTags,
+    targetTags,
+    matchedConstraints,
+    violations,
+  };
+
+  const envelope = jsonEnvelope({
+    command: "explain",
+    context,
+    status,
+    exitCode: complete ? 0 : 3,
+    coverage,
+    result,
+  });
+
+  return {
+    status,
+    explanation,
+    coverage,
+    report: {
+      text: formatExplainReport({ explanation, coverage }),
+      json: renderJson(envelope),
+    },
+  };
+}

package/src/commands/fitness.mjs

@@ -0,0 +1,226 @@
+/**
+ * The `fitness` command: every declared fitness function judged against the
+ * observed workspace, as a verdict table.
+ *
+ * Fitness functions are the workspace's executable quality gates
+ * (`module-boundaries.config.mjs`'s `fitness` export, validated by
+ * `../config.mjs`): "the graph stays cycle-free", "no adapter reaches the
+ * domain", "at least 90% of files are analyzed", "no more than N boundary
+ * suppressions". Each is judged deterministically against the SAME observed
+ * facts `check` reads — the project graph, the workspace analysis, the
+ * architecture intent, and the boundary suppressions — through the registry
+ * `../governance/fitness-registry.mjs` (which reuses `resolveMembers` and the
+ * E0 verdict envelope, never duplicating a judge).
+ *
+ * ## Posture
+ *
+ * `fitness` prints a verdict table, and the verdict carries the exit code: a
+ * failing function is a finding (exit 1) and an undetermined one is a
+ * could-not-determine (exit 3) — the same two lanes `check` uses, argued at
+ * the status↔exitCode mapping below (D-09). `check` also folds fitness in by
+ * presence — a workspace whose policy declares fitness gets its per-function
+ * verdicts counted into the same verdict machinery (exit 1 for any `fail`,
+ * exit 3 for any `unknown`, never a new exit code). There is no `--fitness`
+ * flag: an opt-in flag would make a forgotten flag byte-identical to "no
+ * fitness checked", the silent direction this tool exists to end.
+ *
+ * ## Fail-closed
+ *
+ * A declared function that cannot be determined yields `unknown` — never
+ * `pass`. The mirror of `drift`'s refusals: a `layer-dependency` tag no
+ * matched project carries, a `coverage-minimum` over zero owned files, and a
+ * `drift-free` over no architecture-intent.json all answer `unknown` with the
+ * missing fact named. A function whose `match` selects no project is
+ * `skipped` — loud ("declared but matches nothing"), never folded into
+ * `pass`; a `coverage-minimum` row judged from a path-scoped run joins it
+ * there rather than `unknown` (`../governance/fitness-rules.mjs`), because a
+ * scoped `check <path>` structurally cannot answer a whole-tree coverage
+ * question — that is not evidence of a hole, and folding it into `unknown`
+ * used to make `check <path>` exit 3 unconditionally in any workspace
+ * declaring `coverage-minimum` (P1-19).
+ *
+ * ## Determinism
+ *
+ * Rows are judged in declaration order; edges and evidence are plain-`<`
+ * sorted; JSON rides `canonicalizeJson`. Two runs over an unchanged tree and
+ * policy produce byte-identical text and JSON.
+ */
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatFitnessSection } from "../report/text.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+import { driftForCheck } from "./drift.mjs";
+import {
+  evaluateFitness,
+  fitnessSnapshot,
+  fitnessVerdictFor,
+} from "../governance/fitness-registry.mjs";
+
+/**
+ * The `fitness` command's own text report: the same verdict table `check`'s
+ * fold renders (`formatFitnessSection`), so the two faces can never disagree
+ * about a function's verdict.
+ *
+ * @param {object[]} decisions Per-function verdict records.
+ * @param {{verdict: string}} overall From `fitnessVerdictFor`.
+ * @returns {string}
+ */
+function formatFitnessReport(decisions, overall) {
+  return formatFitnessSection(decisions, overall);
+}
+
+/**
+ * The fitness verdicts for `check`'s fold — the policy's rows evaluated
+ * against the run's own facts (`check` needs no override: it already holds the
+ * intent verdict it judged and the suppressions it enforced).
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{rows: object[], intent: object|null, suppressions: object[],
+ *   scoped: boolean}} policy The validated fitness rows plus the run's own
+ *   intent verdict and suppressions, scoped by `paths`.
+ * @returns {{decisions: object[], overall: {verdict: string}}}
+ */
+export function fitnessForCheck(commandContext, { rows, intent, suppressions, scoped }) {
+  const snapshot = fitnessSnapshot(commandContext, { intent, suppressions, scoped });
+  const decisions = evaluateFitness(rows, snapshot);
+  return { decisions, overall: fitnessVerdictFor(decisions) };
+}
+
+/**
+ * Whether a policy declares fitness functions at all — the one condition that
+ * separates "this workspace has no quality gates to judge" from "the gates
+ * could not be judged". `fitnessCommand` refuses (exit 3) when it is false,
+ * because a `fitness` run asked for a table that does not exist; a composing
+ * report reads the same predicate to render `not_applicable` instead, which is
+ * the correct verdict for a workspace that declared none
+ * (`../governance/metrics.mjs`'s header owns that distinction). Exported so the
+ * two callers cannot come to disagree about what "declares fitness" means.
+ *
+ * @param {{fitness?: unknown}|null|undefined} config The loaded boundary policy.
+ * @returns {boolean}
+ */
+export function declaresFitness(config) {
+  return config !== null && config !== undefined && config.fitness !== undefined;
+}
+
+/**
+ * Runs the `fitness` command: loads the boundary policy, evaluates every
+ * declared function against the workspace's facts, and renders the verdict
+ * table.
+ *
+ * The command re-reads the intent itself (its own `architecture-intent.json`
+ * load) and the suppressions from the policy, so its verdict is the same facts
+ * `check` folds — one registry, one snapshot shape, two faces.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{config?: object|null}} [io] The loaded policy, injectable for tests.
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness: object, coverage: object,
+ *   report: {text: string, json: string}}>}
+ * @throws {Error} on every condition the header lists, all exit-3 class.
+ */
+export async function fitnessCommand(commandContext, io = {}) {
+  const { root, provider, marker, analysis } = commandContext;
+
+  const config = io.config ?? null;
+  if (!declaresFitness(config)) {
+    throw new Error(
+      `archkeep: fitness requires a policy that declares fitness functions — ` +
+        `module-boundary config has no \`fitness\` export, so there is nothing to judge`,
+    );
+  }
+
+  // A verdict over a tree it could not fully read is a guess. Same refusal
+  // `drift`/`graph`/`diff` make for the same condition.
+  const notAnalyzed = analysis.failures
+    .filter(isWholeFileFailure)
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+  if (notAnalyzed.length > 0) {
+    throw new Error(
+      `archkeep: fitness has incomplete coverage — ${notAnalyzed.length} file` +
+        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every coverage ` +
+        `and graph claim would be ambiguous between "clean" and "never seen". Fix the ` +
+        `unanalyzed files and re-run.`,
+    );
+  }
+
+  // `drift-free` judges the SAME verdict-shaped intent `check`'s fold builds —
+  // `driftForCheck` (not raw `loadIntent`) — so the two faces can never
+  // disagree about whether the declared intent matches the observed graph. A
+  // drift comparison that cannot be completed surfaces as an `unknown` verdict
+  // on the function, never a `fail` reading "0 findings" over an intent the
+  // command never actually judged. `driftForCheck` is called UNCONDITIONALLY —
+  // never gated on `tracked` the way `check`/`plan-context-command.mjs` gate
+  // their own calls — because this command must still reach
+  // `driftForCheck`'s `refuseIncompleteGraph` guard whether or not intent is
+  // declared: an Nx workspace with an unregistered plugin over polyglot
+  // manifests must refuse loudly regardless of intent. `driftForCheck` itself
+  // resolves an absent intent (`drift.intent === undefined`) to a quiet
+  // result rather than judging one, which is what makes this unconditional
+  // call safe; that signal becomes `intent: null` here, the same value
+  // `check`'s fold passes when no intent file is tracked at all, and
+  // `drift-free` below reads it as `unknown`. `driftForCheck` is NOT caught
+  // here: every OTHER fail-closed condition — that same unregistered-plugin
+  // refusal, an unreadable or invalid intent — must exit 3 exactly as they do
+  // for `drift`/`graph`/`impact`/`explain`, not fold into a verdict-bearing
+  // run over a graph that cannot see the workspace.
+  const drift = await driftForCheck(commandContext);
+  const intent =
+    drift.intent === undefined
+      ? null
+      : {
+          verdict:
+            drift.findings.length > 0
+              ? "findings"
+              : drift.unresolved.length > 0
+                ? "no-verdict"
+                : "ok",
+          boundaries: drift.boundaries,
+          findings: drift.findings,
+          unresolved: drift.unresolved,
+          notes: drift.notes,
+        };
+  const snapshot = fitnessSnapshot(commandContext, {
+    intent,
+    suppressions: config.suppressions,
+  });
+  const decisions = evaluateFitness(config.fitness, snapshot);
+  const overall = fitnessVerdictFor(decisions);
+
+  const coverage = {
+    complete: true,
+    projects: Object.keys(commandContext.graph.nodes).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) };
+  // D-09: a `fitness` run is a verdict, not a print job. `fail` is a finding
+  // (exit 1) and `unknown` is a could-not-determine (exit 3) — the same two
+  // lanes `check` uses, so a CI that gates on `archkeep fitness` cannot be
+  // green over a function the run could not determine. `pass` and a run whose
+  // every function is `not_applicable` are both `ok`: nothing failed and
+  // nothing stayed undetermined. The status↔exitCode pair is asserted by
+  // `jsonEnvelope` (3-on-no-verdict), so a wrong mapping here cannot ship.
+  /** @type {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3}} */
+  const { status, exitCode } =
+    overall.verdict === "fail"
+      ? { status: "findings", exitCode: 1 }
+      : overall.verdict === "unknown"
+        ? { status: "no-verdict", exitCode: 3 }
+        : { status: "ok", exitCode: 0 };
+  const result = { verdict: overall.verdict, functions: decisions };
+
+  const report = {
+    text: formatFitnessReport(decisions, overall),
+    json: renderJson(
+      jsonEnvelope({ command: "fitness", context, status, exitCode, coverage, result }),
+    ),
+  };
+
+  return { status, fitness: result, coverage, report };
+}