@ecoma-io/archkeep 0.13.0

package/src/report/envelope-shape.mjs

@@ -0,0 +1,161 @@
+/**
+ * The envelope's field roster, as something a test can compare.
+ *
+ * `../../../../docs/reference/json-output.md` promises that every field name
+ * in it, and `schemaVersion` itself, are a public contract: no field is
+ * renamed, no field changes type, and a capability that does not fit the
+ * current shape ships as a new field rather than as a change to an existing
+ * one. Until this module existed, nothing in the tree went red when a field
+ * was renamed or dropped — the promise was prose, and `./json.mjs` enforces
+ * only the three consistency rules between `status`, `exitCode`, `coverage`
+ * and `decision`, never the roster itself.
+ *
+ * This module is the half that can be measured. It turns an envelope into a
+ * flat, sorted list of `path: type` entries, and `../../e2e/envelope-shape.e2e.mjs`
+ * compares that list — for every command the CLI declares — against the
+ * snapshot committed beside it.
+ *
+ * ## What the roster is, and what it is NOT
+ *
+ * It is a MEASURED shape, in the sense `scripts/differential-real-trees.mjs`
+ * uses for `expectViolations`: the answer a real run gives today, written
+ * down so that a change to it has to be made on purpose. It is not a second
+ * copy of the documentation's field tables, and it must not be maintained as
+ * one — a hand-written roster would be exactly the second statement of a rule
+ * `../../../../AGENTS.md` refuses, drifting from both the docs and the code.
+ * The snapshot is regenerated from a run and reviewed as a diff; the diff IS
+ * the review question ("is this rename allowed by the promise?").
+ *
+ * ## Why every node carries an entry, containers included
+ *
+ * A roster of leaves alone cannot see an emptied object: drop every key of
+ * `workspace` and the leaf list simply loses four rows, which reads the same
+ * as four fields having been renamed elsewhere. So each node emits its own
+ * `path: type` — `workspace: object` survives its children — and the type
+ * vocabulary keeps `null` apart from `object`, because `result.goWork` being
+ * `null` on a tree with no `go.work` and being an object on a tree with one
+ * is precisely the difference a consumer branches on.
+ *
+ * ## Arrays collapse, and that is the point
+ *
+ * Every element of an array folds onto one `path[]` prefix, so a roster does
+ * not grow with the number of violations a fixture happens to produce — the
+ * shape is what is under contract, not the count. A path that appears with
+ * two types across elements (an optional field present on one row and absent
+ * on another) yields both entries, which is how an optional field is
+ * recorded rather than hidden.
+ *
+ * The root itself gets no entry: `./json.mjs` cannot return anything but an
+ * object, so a row asserting it is one would be a row that can never move.
+ */
+
+/**
+ * The type name a roster entry carries. Deliberately coarser than JavaScript's
+ * own vocabulary in one place and finer in two: `null` is its own name rather
+ * than `object`, and arrays are `array` rather than `object`, because those
+ * are the two distinctions a consumer's parser actually branches on.
+ *
+ * @param {unknown} value
+ * @returns {"null"|"array"|"object"|"string"|"number"|"boolean"}
+ */
+function typeName(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  const type = typeof value;
+  if (type === "object" || type === "string" || type === "number" || type === "boolean") {
+    return type;
+  }
+  // `undefined`, a function, a symbol, a bigint: none can survive
+  // `JSON.stringify`, so a value of that type in an envelope is a bug in the
+  // command that built it rather than a shape to record. Naming it is the
+  // loud direction — recording it as some neighbouring type would put a row
+  // in the roster describing a field no consumer will ever receive.
+  throw new Error(
+    `archkeep: refusing to build an envelope roster over a ${type} — an envelope holds only ` +
+      `JSON values, so a ${type} in it is a bug in the command that built the envelope.`,
+  );
+}
+
+/**
+ * Every node of `envelope`, as sorted `"<path>: <type>"` entries.
+ *
+ * Paths are dotted, with `[]` marking a step through an array: a violation's
+ * message id is `result.violations[].messageId`. Duplicate entries — the same
+ * path with the same type on many array elements — collapse to one.
+ *
+ * @param {object} envelope The envelope `./json.mjs` built.
+ * @returns {string[]} Sorted, unique `path: type` entries.
+ * @throws {Error} when the envelope is not an object, or holds a value no
+ *   JSON document can carry.
+ */
+export function envelopeFieldPaths(envelope) {
+  if (envelope === null || typeof envelope !== "object" || Array.isArray(envelope)) {
+    throw new Error(
+      `archkeep: refusing to build an envelope roster over ${envelope === null ? "null" : `a ${Array.isArray(envelope) ? "array" : typeof envelope}`} ` +
+        `— an envelope is the object ./json.mjs returns.`,
+    );
+  }
+  /** @type {Map<string, Set<string>>} */
+  const byPath = new Map();
+  walk(envelope, "", byPath);
+  // Sorted by path first and type second, rather than by the rendered string:
+  // `"tool.name: string"` sorts BEFORE `"tool: object"` under a plain string
+  // sort (`.` is below `:`), which would print every child above its own
+  // parent and make the snapshot's diffs harder to read than they need to be.
+  return [...byPath.keys()]
+    .sort()
+    .flatMap((path) => [...(byPath.get(path) ?? [])].sort().map((type) => `${path}: ${type}`));
+}
+
+/**
+ * Records `value` at `path` and descends. `path` is `""` only for the root,
+ * whose own entry is deliberately not recorded (see this module's header).
+ *
+ * @param {unknown} value
+ * @param {string} path
+ * @param {Map<string, Set<string>>} byPath
+ */
+function walk(value, path, byPath) {
+  if (path !== "") {
+    const types = byPath.get(path) ?? new Set();
+    types.add(typeName(value));
+    byPath.set(path, types);
+  }
+  if (value === null) return;
+  if (Array.isArray(value)) {
+    for (const element of value) walk(element, `${path}[]`, byPath);
+    return;
+  }
+  if (typeof value !== "object") return;
+  for (const key of Object.keys(value)) {
+    walk(
+      /** @type {Record<string, unknown>} */ (value)[key],
+      path === "" ? key : `${path}.${key}`,
+      byPath,
+    );
+  }
+}
+
+/**
+ * The two directions a roster can move, named separately because they are not
+ * the same review question.
+ *
+ * `added` is the additive direction the promise allows — a new field, which
+ * still has to be recorded so that "additive" is a claim someone made rather
+ * than a diff nobody read. `removed` is the direction the promise forbids: a
+ * field that was in the roster and is not in the run either was renamed,
+ * dropped, or changed type, and every one of those breaks a consumer that
+ * parses this output today.
+ *
+ * @param {string[]} recorded The snapshot's entries for this command.
+ * @param {string[]} observed `envelopeFieldPaths` over a real run.
+ * @returns {{added: string[], removed: string[]}}
+ */
+export function compareFieldPaths(recorded, observed) {
+  const recordedSet = new Set(recorded);
+  const observedSet = new Set(observed);
+  return {
+    added: observed.filter((entry) => !recordedSet.has(entry)),
+    removed: recorded.filter((entry) => !observedSet.has(entry)),
+  };
+}

package/src/report/evidence.mjs

@@ -0,0 +1,157 @@
+/**
+ * The decision builder: turns a command's verdict counts into the `decision`
+ * the envelope optionally carries, enforcing the five evidence invariants
+ * (`../governance/verdict.mjs` states them) in code rather than leaving them
+ * to a docs page a later command author might not read.
+ *
+ * This module decides nothing about whether a finding IS one — the command
+ * that built the envelope owns that. What it decides is whether the verdict
+ * and its evidence AGREE, and it throws when they do not, the same posture
+ * `jsonEnvelope` takes for the three consistency rules it enforces: a
+ * mismatch here is a bug in the command, not a fact about the workspace.
+ *
+ * The shape it produces:
+ *
+ *   {
+ *     verdict: "pass" | "fail" | "unknown" | "not_applicable",
+ *     reason?: string,                // always present for unknown
+ *     notApplicableReason?: string,   // always present for not_applicable
+ *     sampleTime?: string             // opt-in, never on a deterministic envelope
+ *   }
+ *
+ * A caller may pass `reason` for `unknown` — it names WHICH could-not-look
+ * condition fired (coverage incomplete, an unresolved intent boundary, a
+ * thrown analysis). Without it, `buildDecision` states the generic one. The
+ * reason field itself is always present on an `unknown` decision (I3).
+ *
+ * ## Determinism is the default
+ *
+ * The envelope this decision rides on is byte-deterministic
+ * (`docs/reference/json-output.md`: no timestamp, no random identifier). So
+ * `sampleTime` is OPT-IN by construction: a command passes it explicitly when
+ * it is an age/count capability (waivers, debt, health — the features
+ * `../governance/clock.mjs` serves), and a command whose verdict must stay
+ * reproducible over an unchanged tree emits a decision with no time at all.
+ * That is how the determinism↔time tension is resolved — the clock is
+ * injectable (a test drives the same code with a fixed time), never asserted
+ * from the wall clock.
+ *
+ * ## The invariants, executable
+ *
+ * I1. `pass` requires complete coverage. A run that could not fully read the
+ *     tree can never pass — the same refusal `jsonEnvelope` makes for
+ *     `status: "ok"` over incomplete coverage, at the verdict layer.
+ * I2. `fail` requires at least one finding. A failing verdict that names no
+ *     finding leaves the reader guessing what failed.
+ * I3. `unknown` requires a reason. `unknown` is a claim that something could
+ *     not be determined, and the reader has to be able to tell what.
+ * I4. `not_applicable` requires `notApplicableReason`. "Did not apply" and
+ *     "did not run" are indistinguishable without it.
+ * I5. The cardinal rule: a failed analysis or an unresolved question must
+ *     emit `unknown`, NEVER `pass` — enforced here by I1's first check
+ *     (pass + not-complete throws) and by every caller choosing `unknown`
+ *     wherever the run did not reach a verdict.
+ *
+ * `not_applicable` has no envelope status, so `buildDecision` reaches it only
+ * through an explicit `verdict` — the route a Fitness or Waiver capability
+ * (a later governance wave) takes. Engine behavior today never passes it:
+ * `jsonEnvelope` refuses a `decision.verdict` that contradicts the envelope's
+ * `status`, and no status maps to `not_applicable`, so the state is locked
+ * out of every envelope this release builds.
+ */
+import { verdictForStatus } from "../governance/verdict.mjs";
+
+/**
+ * Builds the `decision` a verdict's counts produce.
+ *
+ * @param {{
+ *   verdict?: "pass"|"fail"|"unknown"|"not_applicable",
+ *   status?: "ok"|"findings"|"no-verdict",
+ *   coverageComplete: boolean,
+ *   findings: number,
+ *   reason?: string|null,
+ *   notApplicableReason?: string|null,
+ *   sampleTime?: string
+ * }} run
+ * @returns {{verdict: string, reason?: string, notApplicableReason?: string,
+ *   sampleTime?: string}}
+ * @throws {Error} on any invariant violation (I1–I4).
+ */
+export function buildDecision(run) {
+  if (run.verdict === undefined && run.status === undefined) {
+    // No status, no explicit verdict — a builder called with neither is a
+    // programming error, not a fact about the workspace.
+    throw new Error("archkeep: buildDecision needs either a status or an explicit verdict");
+  }
+  const verdict = run.verdict ?? verdictForStatus(run.status);
+  if (
+    run.verdict !== undefined &&
+    run.status !== undefined &&
+    run.verdict !== verdictForStatus(run.status)
+  ) {
+    throw new Error(
+      `archkeep: refusing to build a decision where verdict "${run.verdict}" contradicts status ` +
+        `"${run.status}" — status implies ${verdictForStatus(run.status)}, and a decision that ` +
+        `disagrees with its own status would make one of the two a lie. ` +
+        `This is a bug in the command that built the decision.`,
+    );
+  }
+
+  if (verdict === "pass") {
+    if (run.coverageComplete !== true) {
+      throw new Error(
+        `archkeep: refusing to emit a "pass" decision over incomplete coverage ` +
+          `(coverage.complete: ${run.coverageComplete}) — a run that could not fully read the ` +
+          `tree can never pass. This is a bug in the command that built the decision.`,
+      );
+    }
+    if (run.findings > 0) {
+      throw new Error(
+        `archkeep: refusing to emit a "pass" decision with ${run.findings} finding(s) — ` +
+          `"pass" and "fail" cannot both be true of the same run. This is a bug in the command.`,
+      );
+    }
+    return withSampleTime({ verdict }, run.sampleTime);
+  }
+
+  if (verdict === "fail") {
+    if (run.findings < 1) {
+      throw new Error(
+        `archkeep: refusing to emit a "fail" decision with no findings — a failing verdict ` +
+          `must name what failed. This is a bug in the command that built the decision.`,
+      );
+    }
+    return withSampleTime({ verdict }, run.sampleTime);
+  }
+
+  if (verdict === "unknown") {
+    const reason =
+      run.reason ??
+      (run.coverageComplete === true ? "no verdict was reached" : "coverage was incomplete");
+    return withSampleTime({ verdict, reason }, run.sampleTime);
+  }
+
+  // verdict === "not_applicable" (I4).
+  if (!run.notApplicableReason) {
+    throw new Error(
+      `archkeep: refusing to emit a "not_applicable" decision without notApplicableReason — ` +
+        `"did not apply" and "did not run" must never be indistinguishable. ` +
+        `This is a bug in the command that built the decision.`,
+    );
+  }
+  return withSampleTime({ verdict, notApplicableReason: run.notApplicableReason }, run.sampleTime);
+}
+
+/**
+ * Adds `sampleTime` to the decision only when the caller opted into time —
+ * the determinism rule in this module's header. Absent `sampleTime`, the
+ * decision object carries exactly the invariant-bearing fields and nothing
+ * more.
+ *
+ * @param {object} decision
+ * @param {string|undefined} sampleTime
+ * @returns {object}
+ */
+function withSampleTime(decision, sampleTime) {
+  return sampleTime === undefined ? decision : { ...decision, sampleTime };
+}

package/src/report/explain-text.mjs

@@ -0,0 +1,159 @@
+/**
+ * The terminal report for the `explain` command: one import site's judgment,
+ * explained.
+ *
+ * The first line is `file:line:column`, unindented and with no prefix — the
+ * same shape the terminal and the editor both make clickable, and the same
+ * shape `./text.mjs` uses for violations. Everything after it is indented,
+ * so the position line stands alone.
+ *
+ * Seven things are printed, each with a reader in mind:
+ *
+ * - the import specifier and its kind (what was written)
+ * - the source project and its tags (who wrote it)
+ * - the target project and its tags (where it reaches)
+ * - the constraint row(s) that matched (which rule applied)
+ * - the verdict (violation or allowed)
+ * - the message, when there is one (what the verdict means in prose)
+ * - coverage information (whether this explanation is complete)
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/** Two spaces of indent for detail lines. */
+const DETAIL = "  ";
+
+/**
+ * Tags rendered as a bracketed list: `[layer:domain, scope:billing]`.
+ * An empty list renders as `[]`.
+ *
+ * @param {string[]} tags
+ * @returns {string}
+ */
+function formatTags(tags) {
+  return `[${tags.join(", ")}]`;
+}
+
+/**
+ * A project name with its tags: `billing-core [layer:domain, scope:billing]`.
+ * A null project renders as `(unresolved)`.
+ *
+ * @param {string|null} name
+ * @param {string[]} tags
+ * @returns {string}
+ */
+function formatProject(name, tags) {
+  if (name === null) return "(unresolved)";
+  return `${name} ${formatTags(tags)}`;
+}
+
+/**
+ * One constraint row rendered from the row's own keys — the same function
+ * `./text.mjs`'s `formatConstraint` uses, copied here because that function
+ * is not exported (it does not need to be; the two are parallel renderers).
+ *
+ * @param {object|null} constraint A `depConstraints` row, or `null`.
+ * @returns {string}
+ */
+function formatConstraint(constraint) {
+  if (!constraint) {
+    return "not driven by a depConstraints row — this check fires before the table is read";
+  }
+  const source =
+    "allSourceTags" in constraint
+      ? `allSourceTags [${constraint.allSourceTags.join(", ")}]`
+      : `sourceTag ${constraint.sourceTag}`;
+  const rest = Object.entries(constraint)
+    .filter(([key]) => key !== "sourceTag" && key !== "allSourceTags")
+    .map(([key, value]) => `${key} [${(Array.isArray(value) ? value : [value]).join(", ")}]`);
+  return [source, ...rest].join(" → ");
+}
+
+/**
+ * One matched constraint row rendered as a readable line.
+ *
+ * @param {object} constraint A `depConstraints` row.
+ * @returns {string}
+ */
+function formatMatchedConstraint(constraint) {
+  return formatConstraint(constraint);
+}
+
+/**
+ * The whole explain report.
+ *
+ * @param {{explanation: object, coverage: object}} input
+ * @returns {string}
+ */
+export function formatExplainReport({ explanation, coverage }) {
+  const { site } = explanation;
+  const sections = [];
+
+  // The position line — same shape as a violation entry.
+  sections.push(`${site.file}:${site.line}:${site.column}`);
+
+  if (explanation.unresolvable) {
+    sections.push(`${DETAIL}unresolvable  ${explanation.reason}`);
+    sections.push(
+      `${DETAIL}verdict      UNRESOLVABLE — this import site could not be resolved statically, ` +
+        `so no judgment was reached`,
+    );
+  } else {
+    const imp = explanation.import;
+    sections.push(`${DETAIL}import       ${JSON.stringify(imp.specifier)} (${imp.kind})`);
+    sections.push(
+      `${DETAIL}source       ${formatProject(explanation.sourceProject, explanation.sourceTags)}`,
+    );
+    sections.push(
+      `${DETAIL}target       ${formatProject(explanation.targetProject, explanation.targetTags)}`,
+    );
+
+    if (explanation.matchedConstraints.length > 0) {
+      for (const constraint of explanation.matchedConstraints) {
+        sections.push(`${DETAIL}constraint   ${formatMatchedConstraint(constraint)}`);
+      }
+    } else {
+      sections.push(
+        `${DETAIL}constraint   (none — the source project matches no depConstraints row)`,
+      );
+    }
+
+    if (explanation.violations && explanation.violations.length > 0) {
+      for (const v of explanation.violations) {
+        sections.push(`${DETAIL}verdict      VIOLATION — ${v.messageId}`);
+        // The rendered message — same indent as the violation report.
+        const message = v.message
+          .split("\n")
+          .map((line) => (line === "" ? "" : `${DETAIL}    ${line}`))
+          .join("\n");
+        sections.push(message);
+        if (v.constraint?.description) {
+          sections.push(`${DETAIL}rule         ${v.constraint.description}`);
+        }
+        if (v.constraint?.remediation) {
+          sections.push(`${DETAIL}remediation  ${v.constraint.remediation}`);
+        }
+      }
+    } else {
+      sections.push(`${DETAIL}verdict      allowed — no constraint was violated`);
+    }
+  }
+
+  // Coverage — same shape as every other command's footer.
+  const inspected =
+    `${coverage.imports} import${coverage.imports === 1 ? "" : "s"} in ` +
+    `${coverage.analyzedFiles} file${coverage.analyzedFiles === 1 ? "" : "s"} across ` +
+    `${coverage.projects} project${coverage.projects === 1 ? "" : "s"}`;
+
+  if (coverage.complete) {
+    sections.push(`✔ coverage complete (${inspected})`);
+  } else {
+    sections.push(
+      `✖ coverage incomplete — ${coverage.notAnalyzed.length} file${coverage.notAnalyzed.length === 1 ? "" : "s"} ` +
+        `could not be analyzed (${inspected})`,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/report/graph-text.mjs

@@ -0,0 +1,116 @@
+/**
+ * The terminal report for the `graph` command: the project graph as readable
+ * text.
+ *
+ * Each project lists its outgoing edges beneath it — the reading order an
+ * architect uses ("what does this project reach?"). A project with no
+ * dependencies renders `(no dependencies)` rather than an omitted section,
+ * because a project with no edges and a project the renderer forgot look
+ * identical otherwise — the same reasoning as `./text.mjs`'s
+ * `formatGoWork` clean-result line.
+ *
+ * The coverage claim sits ABOVE the listing, not below it, so the reader knows
+ * whether the snapshot is complete before reading any entry — an incomplete
+ * snapshot printed in full would have the "this may under-represent" warning
+ * buried at the bottom.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * One project as a line: name, root, type, and tags.
+ *
+ * @param {{name: string, root: string, type?: string, tags: string[]}} project
+ * @returns {string}
+ */
+function formatProject(project) {
+  const type = project.type ? `  ${project.type}` : "";
+  const tags = project.tags.length > 0 ? ` [${project.tags.join(", ")}]` : "";
+  return `  ${project.name}  ${project.root}${type}${tags}`;
+}
+
+/**
+ * One edge as a line: source -> target (type).
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+function formatEdge(edge) {
+  return `    → ${edge.target} (${edge.type})`;
+}
+
+/**
+ * The whole graph report.
+ *
+ * @param {{projects: object[], dependencies: object[], workspaceLayout: object,
+ *   workspaceLayoutSource: string, coverage: object}} input
+ * @returns {string}
+ */
+export function formatGraphReport({
+  projects,
+  dependencies,
+  workspaceLayout,
+  workspaceLayoutSource,
+  coverage,
+}) {
+  const sections = [];
+
+  // Coverage claim goes FIRST — above the listing — so the reader knows
+  // whether the snapshot is complete before reading any entry.
+  const inspected =
+    `${coverage.imports} import${coverage.imports === 1 ? "" : "s"} in ` +
+    `${coverage.analyzedFiles} file${coverage.analyzedFiles === 1 ? "" : "s"} across ` +
+    `${coverage.projects} project${coverage.projects === 1 ? "" : "s"}`;
+
+  if (coverage.complete) {
+    sections.push(`✔ graph snapshot complete (${inspected})`);
+  } else {
+    const notAnalyzedCount = coverage.notAnalyzed.length;
+    sections.push(
+      `✖ graph snapshot incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
+        `could not be analyzed, so this snapshot may under-represent the architecture (${inspected})`,
+    );
+  }
+
+  // Layout line
+  const layoutSource = workspaceLayoutSource === "declared" ? "declared in workspace" : "default";
+  sections.push(`layout ${workspaceLayout.appsDir}/${workspaceLayout.libsDir} (${layoutSource})`);
+
+  // Project count header
+  const projectWord = projects.length === 1 ? "project" : "projects";
+  sections.push(`${projects.length} ${projectWord}`);
+
+  // Build per-project edge map for the dependency sub-lists
+  const edgesBySource = new Map();
+  for (const edge of dependencies) {
+    let list = edgesBySource.get(edge.source);
+    if (!list) {
+      list = [];
+      edgesBySource.set(edge.source, list);
+    }
+    list.push(edge);
+  }
+
+  // Each project lists its outgoing edges beneath it
+  for (const project of projects) {
+    sections.push(formatProject(project));
+    const edges = edgesBySource.get(project.name);
+    if (edges && edges.length > 0) {
+      for (const edge of edges) {
+        sections.push(formatEdge(edge));
+      }
+    } else {
+      // A project with no dependencies still gets a line, so the reader can
+      // tell the project exists from the report alone — the same reasoning
+      // as `./text.mjs`'s `formatGoWork` clean-result line.
+      sections.push("    (no dependencies)");
+    }
+  }
+
+  // Flat edge count for summary
+  const edgeWord = dependencies.length === 1 ? "edge" : "edges";
+  sections.push(`${dependencies.length} ${edgeWord}`);
+
+  return sections.join("\n");
+}