@ecoma-io/archkeep 0.26.0 → 0.27.1

package/src/providers/nx-static.mjs

@@ -2,10 +2,10 @@
  * The Nx provider's static acquisition — the graph built from the tree's own
  * tracked `project.json` files, with no Nx process asked.
  *
- * This is the acquisition `../lsp/workspace-index.mjs` composed inline until
- * the Phase 7 collapse: a language server is spawned by an editor, in a
- * directory, with nothing else — no `nx` binary to resolve, and a spawn per
- * index build would put `nx graph` on every file save. So beside
+ * This is the acquisition `../lsp/workspace-index.mjs` composes: a language
+ * server is spawned by an editor, in a directory, with nothing else — no `nx`
+ * binary to resolve, and a spawn per index build would put `nx graph` on
+ * every file save. So beside
  * `./nx.mjs`'s `readProjectGraph` (which asks Nx itself and is what
  * `../../cli.mjs`'s `check` runs) this module builds the same `{nodes,
  * dependencies}`-shaped starting point — here just the nodes; the caller

package/src/report/text.mjs

@@ -774,7 +774,7 @@ function formatUntrackedFilesGap(gap) {
     `⚠ ${count} project-owned file${count === 1 ? "" : "s"} ${count === 1 ? "is" : "are"} ` +
     `not tracked by git — never read by this run, so no boundary verdict here covers ${them}\n` +
     `${lines.join("\n")}\n` +
-    `${DETAIL}git add ${them} so the next run reads ${them}, or let git ignore ${them}`
+    `${DETAIL}git add ${them} so the next run reads ${them}`
   );
 }
 

package/src/rules/edge-constraints.mjs

@@ -66,14 +66,13 @@ import {
  * table — it does NOT mean the edge is free of all boundary violations (see
  * this module's header for what is not checked).
  *
- * One of the FOUR finding families — PD-13 (2026-09-06) outcome (c): no
+ * One of the FOUR finding families: no
  * Finding supertype exists, and the relationship pin lives on `./index.mjs`'s
- * `violationOf` header. These verdicts are NOT `Violation` records: the
+ * `violationOf` header (stated in `../../../../docs/concepts/evidence.md`'s
+ * "Four finding families"). These verdicts are NOT `Violation` records: the
  * markdown-pairing fold in `../commands/check.mjs` reshapes each into the
  * exact record `violationOf` builds, and the families fold into the one
- * verdict lane as count keys into `verdictFor` (`../verdict.mjs`). The
- * canonical statement is the "Finding — the unowned concept" section of
- * `../../../../docs/architecture/refactor/SEMANTIC-MODEL.md`.
+ * verdict lane as count keys into `verdictFor` (`../verdict.mjs`).
  *
  * @param {{source: string, target: string}} edge The graph edge to judge.
  * @param {object} nodes The project graph's `nodes` map (carries `data.tags`).

package/src/rules/index.mjs

@@ -425,20 +425,18 @@ export function exemptResolvedFile(site, exemptedFiles) {
 }
 
 /**
- * Builds one `Violation` — the rules lane's canonical violation record (PD-13
- * (2026-09-06) in `../../../../docs/architecture/refactor/DECISIONS.md`: the
- * Violation concept ruled outcome (a), this constructor its one home).
+ * Builds one `Violation` — the rules lane's canonical violation record (the
+ * relationship pin below, stated in `docs/concepts/evidence.md`).
  *
  * This is also one of the FOUR finding families — `violationOf` here,
  * `judgeEdge` (`./edge-constraints.mjs`), `compareGoWork` (`../go-work.mjs`)
  * and `judgeTsconfigPaths` (`../tsconfig-paths.mjs`) — and no Finding
- * supertype exists (PD-13 outcome (c)): what binds the four is the
- * relationship pin. Each family folds into the one verdict lane as count
- * keys into `verdictFor` (`../verdict.mjs`), and `../commands/check.mjs`'s
- * markdown fold is the documented seam where `judgeEdge`'s verdicts are
- * reshaped into the exact record this function builds. The canonical
- * statement is the "Finding — the unowned concept" section of
- * `../../../../docs/architecture/refactor/SEMANTIC-MODEL.md`.
+ * supertype exists: what binds the four is the relationship pin, stated in
+ * `../../../../docs/concepts/evidence.md`'s "Four finding families". Each
+ * family folds into the one verdict lane as count keys into `verdictFor`
+ * (`../verdict.mjs`), and `../commands/check.mjs`'s markdown fold is the
+ * documented seam where `judgeEdge`'s verdicts are reshaped into the exact
+ * record this function builds.
  */
 function violationOf(site, sourceProject, targetProject, messageId, data = {}, constraint = null) {
   return {

package/src/tsconfig-paths.mjs

@@ -114,13 +114,12 @@ function probeDirectory(target, base, root) {
  * need no filesystem: the table and its base come from the resolver's own
  * parsed context, and existence arrives as a predicate.
  *
- * One of the FOUR finding families — PD-13 (2026-09-06) outcome (c): no
+ * One of the FOUR finding families: no
  * Finding supertype exists, and the relationship pin lives on
- * `./rules/index.mjs`'s `violationOf` header. These findings stay this
+ * `./rules/index.mjs`'s `violationOf` header (stated in
+ * `../../../docs/concepts/evidence.md`'s "Four finding families"). These findings stay this
  * family's own shape and fold into the one verdict lane as count keys into
- * `verdictFor` (`./verdict.mjs`). The canonical statement is the
- * "Finding — the unowned concept" section of
- * `../../../docs/architecture/refactor/SEMANTIC-MODEL.md`.
+ * `verdictFor` (`./verdict.mjs`).
  *
  * @param {{ paths: Record<string, unknown>,
  *   base: string,

package/src/fixtures/evolution-lifecycle/workspace.mjs

@@ -1,248 +0,0 @@
-/**
- * Fixture scaffolding for the Wave 3 W8 evolution-lifecycle conformance suite
- * (`../evolution-lifecycle.integration.test.mjs`). This module is the ONE home
- * for the real-git workspace builders that suite uses — a throwaway native Go
- * workspace per case, materialized through real `git`, driven through the real
- * `archkeep evolution` entry point.
- *
- * It deliberately reuses the native-workspace recipe already proven by
- * `../commands/evolution.cli.integration.test.mjs` (an `archkeep.json` model,
- * a `module-boundaries.config.mjs` law, and Go sources) rather than inventing
- * a second convention, and threads the same environment guard (`../process.mjs`).
- *
- * Nothing here decides a verdict. It builds trees and drives the CLI; the
- * assertions live in the suite. Keeping the builders here (and only here) is
- * what the W8 task boundary requires: fixture scaffolding lives in
- * `./fixtures/evolution-lifecycle/`, nowhere else.
- */
-
-import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { EXIT, runCli } from "../../../cli.mjs";
-import { SPAWN_BUDGET_MS, SPAWN_TEST_BUDGET_MS } from "../../../spawn-budget.mjs";
-import { environmentForTree } from "../../workspace.mjs";
-
-export { SPAWN_TEST_BUDGET_MS, EXIT };
-
-/** Identity flags keeping every fixture commit independent of the machine. */
-const IDENTITY = ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false"];
-
-/**
- * Runs git in `cwd` through the same environment guard production uses, with
- * the single-spawn budget on every child so a wedged git fails the test rather
- * than blocking the worker thread forever.
- */
-export function git(cwd, ...args) {
-  // used by its own test
-  return execFileSync("git", args, {
-    cwd,
-    env: environmentForTree(),
-    encoding: "utf8",
-    timeout: SPAWN_BUDGET_MS,
-    killSignal: "SIGKILL",
-  });
-}
-
-/** Writes `text` to `root/relativePath`, creating parent directories. */
-export function writeIn(root, relativePath, text) {
-  // used by its own test
-  mkdirSync(join(root, relativePath, ".."), { recursive: true });
-  writeFileSync(join(root, relativePath), text);
-}
-
-/** Stages every change and commits with the fixture identity; returns the SHA. */
-export function commit(root, message) {
-  // used by its own test
-  git(root, ...IDENTITY, "add", "-A");
-  git(root, ...IDENTITY, "commit", "-q", "-m", message);
-  return git(root, "rev-parse", "HEAD").trim();
-}
-
-/**
- * Opens a brand-new throwaway native git workspace (never the repository's own
- * tree). `archkeep.json` declares two Go projects on two layers, exactly the
- * MODEL `../commands/evolution.cli.integration.test.mjs` uses, so a case can
- * lay an edge between them and the native provider draws it.
- *
- * @returns {{root: string}}
- */
-export function createWorkspace() {
-  const root = mkdtempSync(join(tmpdir(), "archkeep-lifecycle-"));
-  git(root, "init", "-q", "-b", "main");
-  writeIn(root, "archkeep.json", `${MODEL()}\n`);
-  writeIn(root, "libs/alpha/go.mod", "module example.com/alpha\n\ngo 1.22\n");
-  writeIn(root, "libs/beta/go.mod", "module example.com/beta\n\ngo 1.22\n");
-  return { root };
-}
-
-/**
- * The native workspace model: two Go projects on two layers (alpha is
- * `layer:a`, beta is `layer:b`), the law file exempted from coverage.
- */
-const MODEL = () =>
-  JSON.stringify(
-    {
-      projects: {
-        declared: [
-          { root: "libs/alpha", name: "alpha", tags: ["layer:a"] },
-          { root: "libs/beta", name: "beta", tags: ["layer:b"] },
-        ],
-      },
-      coverage: {
-        exempt: [{ path: "module-boundaries.config.mjs", reason: "the workspace's own law" }],
-      },
-    },
-    null,
-    2,
-  );
-
-/** The eight options a valid boundary law must carry, per `policyFrom`. */
-const OPTIONS = `export const moduleBoundaryOptions = {
-  allow: [],
-  buildTargets: ["build"],
-  enforceBuildableLibDependency: false,
-  allowCircularSelfDependency: false,
-  checkDynamicDependenciesExceptions: [],
-  ignoredCircularDependencies: [],
-  banTransitiveDependencies: false,
-  checkNestedExternalImports: false,
-};
-`;
-
-export const ALPHA_CLEAN = `package alpha // used by its own test
-
-func Name() string { return "alpha" }
-`;
-
-export const ALPHA_REACHING = `package alpha // used by its own test
-
-import (
-	"example.com/beta"
-)
-
-func Name() string { return "alpha" + beta.Suffix() }
-`;
-
-export const BETA = `package beta // used by its own test
-
-func Suffix() string { return "-beta" }
-`;
-
-/**
- * Writes a `module-boundaries.config.mjs` law at `root` with the given
- * `depConstraints` rows and optional `fitness` array.
- *
- * @param {string} root
- * @param {{rows?: string, fitness?: string}} [law]
- */
-export function writeLaw(root, { rows = "", fitness } = {}) {
-  // used by its own test
-  writeIn(
-    root,
-    "module-boundaries.config.mjs",
-    `export const depConstraints = [\n${rows}\n];\n${OPTIONS}` +
-      (fitness === undefined ? "" : `\nexport const fitness = ${fitness};\n`),
-  );
-}
-
-/**
- * A single permitted layer rule (a may reach b). The same ONE_ROW the
- * evolution CLI integration fixtures use, so an allowed alpha→beta edge never
- * trips a boundary rule.
- */
-export const ALLOW_A_TO_B = `  { sourceTag: "layer:a", onlyDependOnLibsWithTags: ["layer:b"] },`; // used by its own test
-
-/**
- * Writes `architecture-intent.json` at `root`. `sections` carries the top-level
- * keys directly (`version`, `boundaries`, `allowed`, `forbidden`,
- * `dependencies`, …); `version` defaults to "1".
- */
-export function writeIntent(root, sections) {
-  // used by its own test
-  writeIn(root, "architecture-intent.json", `${JSON.stringify(sections, null, 2)}\n`);
-}
-
-/**
- * Writes one ADR record under `docs/adr/`, the shape `adr-registry.mjs` reads.
- * `record` is the frontmatter map (`{id, status, supersedes?, bindings?}`).
- */
-export function writeAdr(root, filename, record) {
-  // used by its own test
-  const lines = ["---", `id: ${record.id}`, `status: ${record.status}`];
-  if (record.supersedes?.length) {
-    lines.push("supersedes:");
-    for (const target of record.supersedes) lines.push(`  - ${target}`);
-  }
-  if (record.bindings?.length) {
-    lines.push("bindings:");
-    for (const binding of record.bindings) lines.push(`  - ${binding}`);
-  }
-  lines.push("---", "", `# ${record.id}`, "");
-  writeIn(root, join("docs/adr", filename), `${lines.join("\n")}\n`);
-}
-
-/**
- * Drives the CLI in-process over `cwd`, capturing streams. Returns the exit
- * code and joined `out`/`err`. `runCli` is the real entry point
- * (`../cli.mjs`), never a shell-out to a binary named `archkeep`.
- */
-export async function runEvolution(cwd, argv) {
-  // used by its own test
-  const out = [];
-  const err = [];
-  const exitCode = await runCli(argv, {
-    out: (text) => out.push(text),
-    err: (text) => err.push(text),
-    cwd,
-  });
-  return { exitCode, out: out.join("\n"), err: err.join("\n") };
-}
-
-/**
- * Invokes `evolution --base <base> [--head <head>] [--event-out <dir>] [--format json]`.
- *
- * @param {string} base The base revision (full SHA).
- * @param {{head?: string, eventOut?: string, format?: string}} [options]
- */
-export function evolutionArgs(base, { head, eventOut, format = "json" } = {}) {
-  // used by its own test
-  const args = ["evolution", "--base", base];
-  if (head) args.push("--head", head);
-  if (eventOut) args.push("--event-out", eventOut);
-  if (format) args.push("--format", format);
-  return args;
-}
-
-/**
- * Parses the `--format json` envelope out of a successful evolution run.
- */
-export function parseEnvelope(run) {
-  // used by its own test
-  if (run.exitCode !== EXIT.ok) throw new Error(`evolution exited ${run.exitCode}: ${run.err}`);
-  return JSON.parse(run.out);
-}
-
-/** The parsed event files in `dir`, in filename order. */
-export function readEvents(dir) {
-  return readdirSync(dir)
-    .filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"))
-    .sort()
-    .map((name) => JSON.parse(readFileSync(join(dir, name), "utf8")));
-}
-
-/** The event store's file names in `dir`, in filename order. */
-export function eventFiles(dir) {
-  // used by its own test
-  return readdirSync(dir)
-    .filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"))
-    .sort();
-}
-
-/** Removes a throwaway workspace. */
-export function dispose(root) {
-  // used by its own test
-  rmSync(root, { recursive: true, force: true });
-}