@ecoma-io/archkeep 0.24.0 → 0.25.0

package/src/commands/drift.mjs

@@ -250,7 +250,7 @@ export async function driftForCheck(commandContext, io = {}) {
  * @param {object} intent The normalized intent model.
  * @returns {{kind: string, row: object}[]}
  */
-export function intentDecisionRefRows(intent) {
+function intentDecisionRefRows(intent) {
   return governanceIntentRows(intent).filter(
     ({ row }) => typeof row?.decisionRef === "string" && row.decisionRef.trim() !== "",
   );

package/src/commands/evaluation-primitives.mjs

@@ -195,7 +195,7 @@ export function buildDecisionImpact(root, constraintImpact, config) {
  *   not available.
  * @returns {{evaluated: boolean, findings: object[], count: number}}
  */
-export function evaluateFindingsImpact(affectedProjects, availableFindings) {
+function evaluateFindingsImpact(affectedProjects, availableFindings) {
   if (!availableFindings || availableFindings.length === 0) {
     return { evaluated: false, findings: [], count: 0 };
   }
@@ -221,7 +221,7 @@ export function evaluateFindingsImpact(affectedProjects, availableFindings) {
  *   entry's associated project.
  * @returns {{evaluated: boolean, debt: object[], count: number}}
  */
-export function evaluateDebtImpact(affectedProjects, availableDebt, resolveProject = null) {
+function evaluateDebtImpact(affectedProjects, availableDebt, resolveProject = null) {
   if (!availableDebt || availableDebt.length === 0) {
     return { evaluated: false, debt: [], count: 0 };
   }
@@ -247,7 +247,7 @@ export function evaluateDebtImpact(affectedProjects, availableDebt, resolveProje
  * @param {string} targetProject The target of the impact analysis.
  * @returns {{boundaries: object[], evaluated: boolean}}
  */
-export function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
+function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
   if (!constraintImpact || constraintImpact.length === 0) {
     return { boundaries: [], evaluated: false };
   }
@@ -339,7 +339,7 @@ export function decisionProvenanceCoverage(decisions) {
  * @param {object} evaluation.evolutionAlignment Evolution alignment.
  * @returns {object} Evidence gate values for buildEvidenceComplete.
  */
-export function deriveEvidenceGates(evaluation) {
+function deriveEvidenceGates(evaluation) {
   const { completeness, constraintImpact, decisionImpact } = evaluation;
 
   // domainCoverage: ratio of evaluated required domains

package/src/commands/evolution.mjs

@@ -138,6 +138,7 @@ function shortSha(sha) {
  *   and a shallow clone whose cut-off sits below the requested revision.
  */
 export function resolveRevision(root, rev, flag, { run = runProcess } = {}) {
+  // used by its own test
   if (typeof rev !== "string" || rev.length === 0) {
     throw new Error(`archkeep: ${flag} needs a revision — a commit, branch, tag, or HEAD~n.`);
   }
@@ -190,6 +191,7 @@ export function resolveRevision(root, rev, flag, { run = runProcess } = {}) {
  *   head's ancestry, or a merge commit inside the range.
  */
 export function selectLinearRange(root, { base, head }, { run = runProcess } = {}) {
+  // used by its own test
   const baseSha = resolveRevision(root, base, "--base", { run });
   const headSha = resolveRevision(root, head ?? "HEAD", "--head", { run });
 

package/src/commands/explain.mjs

@@ -111,6 +111,7 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
  * @throws {UsageError} when the site string is malformed.
  */
 export function parseSite(site) {
+  // used by its own test
   const lastColon = site.lastIndexOf(":");
   if (lastColon === -1 || lastColon === 0) {
     throw new UsageError(
@@ -157,6 +158,7 @@ export function parseSite(site) {
  * @returns {object|null} The matching record, or `null`.
  */
 export function findSite(parsed, imports) {
+  // used by its own test
   return (
     imports.find(
       (site) =>

package/src/commands/graph.mjs

@@ -151,24 +151,26 @@ export function buildDependencies(dependencies) {
  * 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
+ * `options`, `suppressions` and — when the policy declares them — the
+ * `fitness`, `customRules`, `coverage` and `markdown` blocks, plus the
+ * selected profile's NAME when the law was selected by name. 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.
+ * `params` and the policy says something different. The three after those are
+ * argued at their keys below. 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.
+ * The conditional fields are included only when they are DECLARED, and the
+ * absent case contributes no key rather than an empty array. A policy that
+ * declares none 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.
@@ -180,13 +182,33 @@ export function computePolicyFingerprint(config) {
     suppressions: config.suppressions ?? [],
     ...(config.fitness === undefined ? {} : { fitness: config.fitness }),
     ...(config.customRules === undefined ? {} : { customRules: config.customRules }),
-    // The document track is law the same way the two blocks above are: it
+    // The acceptance channel is law the same way the blocks above are: a
+    // `coverage.unowned` row withdraws an unclaimed file's whole-file failure
+    // as a recorded acceptance (`../config.mjs`'s `findCoverageViolations`
+    // owns the shape, `../commands/coverage-acceptance.mjs` matches it), so a
+    // policy that records or removes an acceptance must not share a
+    // fingerprint with one that does not — `diff`'s policy-changed warning
+    // reads this hash (#709: the one block `policyFrom` sets that the hash
+    // skipped). Conditional, like the three above, so a policy recording no
+    // acceptance hashes exactly as it did before this key existed.
+    ...(config.coverage === undefined ? {} : { coverage: config.coverage }),
+    // The document track is law the same way the blocks above are: it
     // decides what this run judges, so a policy that adds or edits a
     // `markdown` block must not share a fingerprint with one that does not —
     // `diff`'s policy-changed warning reads this hash. Conditional, like the
-    // two above, so a policy declaring no block hashes exactly as it did
+    // three above, so a policy declaring no block hashes exactly as it did
     // before this key existed.
     ...(config.markdown === undefined ? {} : { markdown: config.markdown }),
+    // The named selection is law identity the same way the blocks above are:
+    // `profilePolicy` (`../governance/profile-registry.mjs`) sets this key
+    // when the workspace selects a profile by name, and two profiles whose
+    // resolved blocks converge are still two different named laws. Only
+    // `check`'s report names the selection, so a hash blind to it would let a
+    // `delta` across a switch report the law unchanged with nothing anywhere
+    // saying it moved. Conditional, like the four above, so a policy
+    // selected by file or inline — no `profile` key at all — hashes exactly
+    // as it did before the selection was covered.
+    ...(config.profile === undefined ? {} : { profile: config.profile }),
   };
   // Canonicalise: sort object keys at every depth so insertion order does not
   // affect the hash. Semantic equality, not construction order, is the claim —

package/src/commands/history.mjs

@@ -112,6 +112,12 @@ import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
  * Provider and provenance changes surface through the transition
  * classification instead.
  *
+ * This function is the graph-snapshot family's ONE identity — evolution event
+ * sides consume its output through `eventSnapshotSide` below, never a second
+ * derivation (`../../../../docs/adr/0008-snapshot-identity-per-family.md`
+ * records the one-identity-per-family decision, including why the evidence
+ * snapshot family deliberately carries no id at all).
+ *
  * @param {{projects: object[], dependencies: object[], policy?: {fingerprint: string}|null}} snapshot
  * @returns {string} A hex-encoded SHA-256.
  */
@@ -136,6 +142,34 @@ export function snapshotIdentity({ projects, dependencies, policy }) {
   return createHash("sha256").update(canonical).digest("hex");
 }
 
+/**
+ * An evolution event's identity side: the reference to ONE state — a revision
+ * when one is known, plus the snapshot identity of the graph that side was
+ * judged over. `delta` and `change` build every side through this one
+ * function so the identity spelling cannot drift between them, and a storage
+ * path can never re-enter the tuple a committed event store dedupes on
+ * (`docs/concepts/evolution.md`'s "Nor does a storage path"). `history` and
+ * `evolution` spell the same `{revision, snapshot}` shape directly, from a
+ * snapshot whose identity is already computed.
+ *
+ * @param {{revision?: string|null, projects: object[], dependencies: object[],
+ *   policyFingerprint?: string|null}} side
+ * @returns {{revision?: string, snapshot: string}} The identity side.
+ */
+export function eventSnapshotSide({ revision, projects, dependencies, policyFingerprint }) {
+  return {
+    ...(typeof revision === "string" ? { revision } : {}),
+    snapshot: snapshotIdentity({
+      projects,
+      dependencies,
+      policy:
+        policyFingerprint === undefined || policyFingerprint === null
+          ? null
+          : { fingerprint: policyFingerprint },
+    }),
+  };
+}
+
 /**
  * Reads and validates every snapshot in the history directory.
  *
@@ -229,6 +263,7 @@ export function readSnapshots(dir, root) {
  * @returns {string} First 8 hex characters.
  */
 export function shortId(id) {
+  // used by its own test
   return id.slice(0, 8);
 }
 
@@ -248,6 +283,7 @@ export function shortId(id) {
  * @returns {string} Zero-padded sequence, at least four digits.
  */
 export function nextSequence(read) {
+  // used by its own test
   let max = 0;
   for (const file of read.files) {
     const match = /^(\d+)-/.exec(file.name);

package/src/commands/plan-context-command.mjs

@@ -87,7 +87,7 @@ import { declaredFitnessNames, unresolvedDecisionRefRows } from "../governance/a
 import { formatPlanContextReport } from "../report/plan-context-text.mjs";
 
 /** How many dependents are listed before an explicit overflow note. */
-export const DEPENDENT_CAP = 10;
+export const DEPENDENT_CAP = 10; // used by its own test
 
 /**
  * The projects a change touches: the target project, plus every project whose
@@ -100,6 +100,7 @@ export const DEPENDENT_CAP = 10;
  * @returns {string[]} Distinct affected project names, sorted.
  */
 export function collectAffectedProjects(commandContext, paths) {
+  // used by its own test
   const affected = new Set();
   for (const { file, project } of commandContext.owned ?? []) {
     for (const p of paths) {
@@ -124,6 +125,7 @@ export function collectAffectedProjects(commandContext, paths) {
  * @returns {object[]}
  */
 export function collectImpact(projectName, affected, graph) {
+  // used by its own test
   const targets = [...new Set([projectName, ...affected])].sort((a, b) =>
     a < b ? -1 : a > b ? 1 : 0,
   );
@@ -172,6 +174,7 @@ function scopedFiles(commandContext, affected) {
  * @returns {{goWork: object|null, tsconfigPaths: object|null, failures: object[]}}
  */
 export function collectDrift(commandContext) {
+  // used by its own test
   const { root, tracked, workspace } = commandContext;
   const failures = [];
 

package/src/commands/policy.mjs

@@ -26,7 +26,7 @@ import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
  * @param {object} options The resolved options from `resolveCommandContext`.
  * @returns {boolean}
  */
-export function hasProfiles(options) {
+function hasProfiles(options) {
   return typeof options?.profiles === "string" && options.profiles !== "";
 }
 
@@ -86,10 +86,13 @@ export function hasProfiles(options) {
  * @param {string} cwd The process's working directory a relative `--config`
  *   resolves against — kept separate from the workspace root for the reason
  *   above.
- * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: {include: string[], markers: {pattern: string, edge: string}[]}, notes?: string[]}|null, profile: string|null, source: string|null}>}
+ * @returns {Promise<{config: {depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, markdown?: {include: string[], markers: {pattern: string, edge: string}[]}, notes?: string[], profile?: string}|null, profile: string|null, source: string|null}>}
  *   `fitness`, `customRules` and `markdown` are present only when the resolved
  *   policy declares them — an absent key is the workspace's decision not to
  *   declare that law, never an empty one (`../config.mjs`'s `policyFrom`).
+ *   `profile` is present only when the law was selected by name, set by the
+ *   profiles arm (`../governance/profile-registry.mjs`'s `profilePolicy`) so
+ *   the selection the policy was resolved by travels with it.
  * @throws {Error} when a named profile, a `--config` file, or an inline
  *   policy cannot be resolved or is malformed — every arm's existing failure
  *   mode, unchanged by the extraction.

package/src/commands/scenario-evaluation.mjs

@@ -55,7 +55,7 @@ import {
 // ---------------------------------------------------------------------------
 
 /** The supported scenario change types. */
-export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "dependency_removed"]);
+export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "dependency_removed"]); // used by its own test
 
 // ---------------------------------------------------------------------------
 // Input schema types

package/src/commands/snapshot-meta.mjs

@@ -23,6 +23,39 @@
  * `null` before treating either as a boolean.
  */
 
+/**
+ * The one wording for the dirty-baseline disclosure, shared by every command
+ * that compares a snapshot pair (`diff`, `delta`, `change`). Three copies of
+ * one disclosure spell drift three ways, so the wording lives beside the fact
+ * it translates. A consumer that pins the baseline by its own contract names
+ * that pin (`pinned`) — `change`'s contract carries `base.commit`; a diff or
+ * delta pair has no such pin, so its note names the commit the snapshot
+ * itself claims.
+ *
+ * @param {boolean} pinned Whether the consumer's contract pins the base commit.
+ * @returns {string} The disclosure note.
+ */
+export function dirtyBaselineNote(pinned) {
+  return pinned
+    ? "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
+        "claim about the commit the contract pins"
+    : "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
+        "claim about the commit it names";
+}
+
+/**
+ * The one wording for the dirty-head disclosure — byte-identical in every
+ * consumer, so it is stated exactly once.
+ *
+ * @returns {string} The disclosure note.
+ */
+export function dirtyHeadNote() {
+  return (
+    "this run's working tree is dirty — the head side describes uncommitted state, not the " +
+    "commit HEAD names"
+  );
+}
+
 /**
  * Compares the provider, provenance, and policy fingerprint of two graph
  * envelopes.

package/src/commands/trajectory.mjs

@@ -107,7 +107,7 @@ const OBSERVATION_BASIS = "graph_snapshots";
  * constant in the envelope, so a consumer branches on a documented value
  * rather than on prose.
  */
-export const INSUFFICIENT_HISTORY = "insufficient_history";
+export const INSUFFICIENT_HISTORY = "insufficient_history"; // used by its own test
 
 /**
  * The derived-number block for one structural axis (projects keyed by name,
@@ -187,6 +187,7 @@ export const INSUFFICIENT_HISTORY = "insufficient_history";
  *   trends: TrajectoryTrends|null}}
  */
 export function computeTrajectory(files) {
+  // used by its own test
   const n = files.length;
   const available = n >= 2;
 

package/src/config.mjs

@@ -650,7 +650,7 @@ function findCoverageViolations(value) {
  *
  * @type {Readonly<string[]>}
  */
-export const MARKDOWN_EDGE_KINDS = Object.freeze(["resolvedExportOwner"]);
+const MARKDOWN_EDGE_KINDS = Object.freeze(["resolvedExportOwner"]);
 
 /**
  * One markdown marker row's problems, prefixed with its index.

package/src/custom-rules/host.mjs

@@ -124,17 +124,17 @@ export const CUSTOM_RULE_TIMEOUT_MS = 10_000;
  * bundle for a large workspace is smaller — and it is what stops a claimed
  * length from being an allocation instruction.
  */
-export const CUSTOM_RULE_MAX_VERDICT_BYTES = 8 * 1024 * 1024;
+export const CUSTOM_RULE_MAX_VERDICT_BYTES = 8 * 1024 * 1024; // used by its own test
 
 /**
  * The most linear memory a rule may hold at the two boundaries the worker
  * measures. 256 MiB is far past what reading an evidence bundle needs and far
  * short of what a workspace's CI runner can absorb without noticing.
  */
-export const CUSTOM_RULE_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024;
+export const CUSTOM_RULE_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024; // used by its own test
 
 /** The four ABI symbols a rule module must export, and the kind each must be. */
-export const REQUIRED_EXPORTS = Object.freeze({
+const REQUIRED_EXPORTS = Object.freeze({
   memory: "memory",
   archkeep_alloc: "function",
   archkeep_describe: "function",

package/src/custom-rules/values.mjs

@@ -25,10 +25,7 @@
  * to reach it.
  */
 
-export { isPlainObject } from "../values.mjs";
-
-/** @type {(value: unknown) => boolean} */
-export const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+export { isPlainObject, isNonEmptyString } from "../values.mjs";
 
 /**
  * A value's type, for a refusal that shows what was actually there.

package/src/eslint-config.mjs

@@ -235,6 +235,7 @@ function parseRuleValue(value, index) {
  *   severity-only fallback has been applied.
  */
 export function extractBoundaryRule(flatConfig, readerOptions = {}) {
+  // used by its own test
   const pathScopedMode = readerOptions.pathScoped ?? "refuse";
   if (pathScopedMode !== "refuse" && pathScopedMode !== "bind-tree-wide") {
     throw new Error(

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

@@ -36,6 +36,7 @@ const IDENTITY = ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpg
  * than blocking the worker thread forever.
  */
 export function git(cwd, ...args) {
+  // used by its own test
   return execFileSync("git", args, {
     cwd,
     env: environmentForTree(),
@@ -47,12 +48,14 @@ export function git(cwd, ...args) {
 
 /** 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();
@@ -109,12 +112,12 @@ const OPTIONS = `export const moduleBoundaryOptions = {
 };
 `;
 
-export const ALPHA_CLEAN = `package alpha
+export const ALPHA_CLEAN = `package alpha // used by its own test
 
 func Name() string { return "alpha" }
 `;
 
-export const ALPHA_REACHING = `package alpha
+export const ALPHA_REACHING = `package alpha // used by its own test
 
 import (
 	"example.com/beta"
@@ -123,7 +126,7 @@ import (
 func Name() string { return "alpha" + beta.Suffix() }
 `;
 
-export const BETA = `package beta
+export const BETA = `package beta // used by its own test
 
 func Suffix() string { return "-beta" }
 `;
@@ -136,6 +139,7 @@ func Suffix() string { return "-beta" }
  * @param {{rows?: string, fitness?: string}} [law]
  */
 export function writeLaw(root, { rows = "", fitness } = {}) {
+  // used by its own test
   writeIn(
     root,
     "module-boundaries.config.mjs",
@@ -149,7 +153,7 @@ export function writeLaw(root, { rows = "", fitness } = {}) {
  * 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"] },`;
+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
@@ -157,6 +161,7 @@ export const ALLOW_A_TO_B = `  { sourceTag: "layer:a", onlyDependOnLibsWithTags:
  * `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`);
 }
 
@@ -165,6 +170,7 @@ export function writeIntent(root, sections) {
  * `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:");
@@ -184,6 +190,7 @@ export function writeAdr(root, filename, record) {
  * (`../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, {
@@ -201,6 +208,7 @@ export async function runEvolution(cwd, argv) {
  * @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);
@@ -212,6 +220,7 @@ export function evolutionArgs(base, { head, eventOut, format = "json" } = {}) {
  * 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);
 }
@@ -226,6 +235,7 @@ export function readEvents(dir) {
 
 /** 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();
@@ -233,5 +243,6 @@ export function eventFiles(dir) {
 
 /** Removes a throwaway workspace. */
 export function dispose(root) {
+  // used by its own test
   rmSync(root, { recursive: true, force: true });
 }

package/src/go-work.mjs

@@ -113,7 +113,7 @@ const IDENTIFIER_BOUNDARY = new Set([" ", "\t", "\r", '"', "`", "(", ")"]);
  * @throws {Error} on an unterminated string — a string left open would
  *   otherwise swallow the rest of the line silently.
  */
-export function tokenizeGoWorkLine(line, lineNumber) {
+function tokenizeGoWorkLine(line, lineNumber) {
   const tokens = [];
   let at = 0;
   while (at < line.length) {

package/src/governance/adr-registry.mjs

@@ -124,7 +124,7 @@ export function hasAuthority(status) {
  * format outgrows 999 records without breaking; the slug is dash-separated
  * lowercase words.
  */
-export const ADR_FILE_PATTERN = /^(\d{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/u;
+const ADR_FILE_PATTERN = /^(\d{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/u;
 
 /** An ADR id — `NNN-slug` — must match the filename it lives in. */
 export const ADR_ID_PATTERN = /^\d{3,}-[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -236,6 +236,7 @@ function parseProseFields(body) {
  *   that already appears earlier in the same block.
  */
 export function parseFrontmatterFields(text, at) {
+  // used by its own test
   /** @type {Record<string, string|string[]|undefined>} */
   const fields = {};
   let currentList = null;
@@ -307,6 +308,7 @@ function toList(value) {
  * @throws {Error} naming every violation at once.
  */
 export function validateRecord({ id, frontmatter, body = "" }) {
+  // used by its own test
   const fields = frontmatter === null ? {} : parseFrontmatterFields(frontmatter, id);
   const violations = [];
 
@@ -400,6 +402,7 @@ export function validateRecord({ id, frontmatter, body = "" }) {
  * @throws {Error} naming every lineage violation at once.
  */
 export function validateLineage(records) {
+  // used by its own test
   const byId = new Map(records.map((record) => [record.id, record]));
   /** @type {Map<string, string[]>} */
   const supersededBy = new Map(records.map((record) => [record.id, []]));

package/src/governance/debt-ledger.mjs

@@ -143,7 +143,7 @@ function owningProjectForPath(path, byName) {
  * @param {string} source The entry's `source` (its keying field).
  * @returns {string} The stable hex id.
  */
-export function entryId(kind, source) {
+function entryId(kind, source) {
   const semanticKind = kind === "expired-waiver" ? "waiver" : kind;
   return createHash("sha256")
     .update(canonicalizeJson({ kind: semanticKind, source }))

package/src/governance/decision-fitness.mjs

@@ -61,6 +61,7 @@ import { hasAuthority } from "./adr-registry.mjs";
 
 /** The closed set of per-decision fitness levels `computeDecisionFitness` emits. */
 export const DECISION_FITNESS_LEVELS = Object.freeze([
+  // used by its own test
   "enforced",
   "partially-enforced",
   "violated",
@@ -70,6 +71,7 @@ export const DECISION_FITNESS_LEVELS = Object.freeze([
 
 /** Whether a level names a red (never-healthy) direction. */
 export function isRedDirection(level) {
+  // used by its own test
   return level === "violated" || level === "unverifiable";
 }
 

package/src/governance/decision-graph.mjs

@@ -382,6 +382,7 @@ export function forwardDecision(decisionId, ctx) {
  * @returns {GraphWalk}
  */
 export function reverseRow(rowRef, ctx) {
+  // used by its own test
   const g = newWalk();
 
   const row = ctx.rows.find((candidate) => candidate.id === rowRef);