@ecoma-io/archkeep 0.24.0 → 0.25.0

package/src/providers/native/differential.fixtures.mjs

@@ -41,11 +41,13 @@ import { nativeProvider } from "./index.mjs";
  * @param {Record<string, string>} files `{relativePath: text}`.
  */
 export function writeAll(write, files) {
+  // used by its own test
   for (const [path, text] of Object.entries(files)) write(path, text);
 }
 
 /** @param {string} root */
 export function writeIn(root) {
+  // used by its own test
   return (relativePath, text) => {
     mkdirSync(join(root, relativePath, ".."), { recursive: true });
     writeFileSync(join(root, relativePath), text);
@@ -53,7 +55,7 @@ export function writeIn(root) {
 }
 
 /** @param {string} root */
-export function readFileFrom(root) {
+function readFileFrom(root) {
   return (path) => {
     try {
       return readFileSync(join(root, path), "utf8");
@@ -76,6 +78,7 @@ function analyze(root, graph, files, tsConfig) {
 
 /** `{name → {root, type, tags}}`, comparable whichever provider produced it. */
 export const nodeShape = (nodes) =>
+  // used by its own test
   Object.fromEntries(
     Object.entries(nodes).map(([name, node]) => [
       name,
@@ -105,13 +108,14 @@ export const nodeShape = (nodes) =>
  * canonicalisation consistent with the code under test rather than a weaker
  * copy of it. */
 export const dependencyShape = (dependencies) =>
+  // used by its own test
   Object.values(dependencies)
     .flat()
     .map(({ source, target, type }) => JSON.stringify([source, target, type]))
     .sort();
 
 /** `["messageId sourceFile:line:column", ...]`, sorted the same way. */
-export const verdictShape = (violations) =>
+const verdictShape = (violations) =>
   violations.map((v) => `${v.messageId} ${v.sourceFile}:${v.line}:${v.column}`).sort();
 
 /**
@@ -128,6 +132,7 @@ export const verdictShape = (violations) =>
  * @type {typeof runProcess}
  */
 export function runNxGraphSpawn(file, args, cwd) {
+  // used by its own test
   const previous = process.env.NX_DAEMON;
   process.env.NX_DAEMON = "false";
   try {
@@ -157,6 +162,7 @@ export function runNxGraphSpawn(file, args, cwd) {
  * @throws {Error} naming every failing file, when either list is non-empty.
  */
 export function assertNoAnalysisFailures(nxFailures, nativeFailures) {
+  // used by its own test
   const named = [
     ...nxFailures.map((f) => `nx:${f.sourceFile} (${f.reason})`),
     ...nativeFailures.map((f) => `native:${f.sourceFile} (${f.reason})`),
@@ -188,6 +194,7 @@ export function assertNoAnalysisFailures(nxFailures, nativeFailures) {
  *   inherits the `NX_DAEMON` handling rather than choosing between the two.
  */
 export async function runBothProviders({
+  // used by its own test
   nxRoot,
   nxFiles,
   nativeRoot,
@@ -280,6 +287,7 @@ export async function runBothProviders({
  * @returns {{kind: string, subject: string, field: string, nx: unknown, native: unknown}[]}
  */
 export function diffGraphs(nxSide, nativeSide) {
+  // used by its own test
   const rows = [];
 
   const nxNames = new Set(Object.keys(nxSide.nodes));
@@ -417,6 +425,7 @@ export function diffGraphs(nxSide, nativeSide) {
  * detection) are scoped to one fixture pair and cannot silently absorb a
  * disagreement in another. */
 export function namespaced(rows, label) {
+  // used by its own test
   return rows.map((row) => ({ ...row, subject: `${label}:${row.subject}` }));
 }
 
@@ -458,7 +467,7 @@ export function namespaced(rows, label) {
  * `classifyDifferences`, not a search for every place `"native-only"` was
  * spelled as a bare string.
  */
-export const LEDGER_DIRECTIONS = Object.freeze(/** @type {const} */ (["native-only"]));
+const LEDGER_DIRECTIONS = Object.freeze(/** @type {const} */ (["native-only"]));
 
 /**
  * Every entry here is a **difference native reports and Nx does not** — the
@@ -479,7 +488,7 @@ export const LEDGER_DIRECTIONS = Object.freeze(/** @type {const} */ (["native-on
  *
  * @type {readonly LedgerRow[]}
  */
-export const LEDGER = Object.freeze([]);
+export const LEDGER = Object.freeze([]); // used by its own test
 
 /**
  * Every fixture-pair label this file actually runs a comparison over — the
@@ -487,7 +496,7 @@ export const LEDGER = Object.freeze([]);
  * list every `assertPairAgrees`/`pairProblems` call site draws its `label`
  * argument from, so the two can never drift into naming different pairs.
  */
-export const PAIR_LABELS = Object.freeze(["simple", "composite", "layout"]);
+export const PAIR_LABELS = Object.freeze(["simple", "composite", "layout"]); // used by its own test
 
 /**
  * The direction a `diffGraphs` row itself claims, in `LedgerRow.direction`'s
@@ -560,6 +569,7 @@ function differenceDirection(difference) {
  *   difference no ledger row may ever cover.
  */
 export function classifyDifferences(differences, ledger) {
+  // used by its own test
   for (const row of ledger) {
     if (!row.reason?.trim()) {
       throw new Error(`ledger row for "${row.subject}"/"${row.field}" has an empty reason`);
@@ -632,6 +642,7 @@ export function classifyDifferences(differences, ledger) {
  * @returns {string[]}
  */
 export function emptyVerdictBreaches(label, counts) {
+  // used by its own test
   const breaches = [];
   for (const [engine, count] of Object.entries(counts)) {
     if (count === 0) {
@@ -659,6 +670,7 @@ export function emptyVerdictBreaches(label, counts) {
  * @returns {string[]}
  */
 export function perMessageBreaches(label, nxViolations, nativeViolations) {
+  // used by its own test
   /** @param {{messageId: string}[]} violations @returns {Map<string, number>} */
   const countBy = (violations) => {
     const counts = new Map();
@@ -696,6 +708,7 @@ export function perMessageBreaches(label, nxViolations, nativeViolations) {
  * @returns {string[]}
  */
 export function pairProblems(label, result, ledger = LEDGER) {
+  // used by its own test
   const problems = [
     ...emptyVerdictBreaches(label, {
       nx: result.nx.violations.length,
@@ -734,6 +747,7 @@ export function pairProblems(label, result, ledger = LEDGER) {
  * @param {readonly LedgerRow[]} [ledger]
  */
 export function assertPairAgrees(label, result, ledger = LEDGER) {
+  // used by its own test
   const problems = pairProblems(label, result, ledger);
   if (problems.length > 0) {
     throw new Error(`${label}: provider differential disagreement:\n  ${problems.join("\n  ")}`);
@@ -758,6 +772,7 @@ export function assertPairAgrees(label, result, ledger = LEDGER) {
  * @returns {LedgerRow[]}
  */
 export function unknownLabelRows(ledger, knownLabels) {
+  // used by its own test
   return ledger.filter((row) => !knownLabels.includes(row.subject.split(":")[0]));
 }
 
@@ -773,7 +788,7 @@ export function unknownLabelRows(ledger, knownLabels) {
 // staying importable and spawn-free at import time for exactly that reuse,
 // and a second copy here is the drift `../../../../../AGENTS.md`'s "never
 // state a rule twice" rule exists to catch.
-export const SIMPLE_BOUNDARY_CONFIG = `export const depConstraints = [
+export const SIMPLE_BOUNDARY_CONFIG = `export const depConstraints = [ // used by its own test
   { sourceTag: "layer:domain", onlyDependOnLibsWithTags: ["layer:domain"] },
   { sourceTag: "layer:adapter", onlyDependOnLibsWithTags: ["layer:domain", "layer:adapter"] },
 ];
@@ -794,6 +809,7 @@ export const moduleBoundaryOptions = {
 // the wrong way (`domain` reaching into `adapter`). Exported for the same
 // reuse reason as `SIMPLE_BOUNDARY_CONFIG` above.
 export const SIMPLE_GO_FILES = {
+  // used by its own test
   "libs/domain/go.mod": "module example.com/domain\n\ngo 1.24\n",
   "libs/adapter/go.mod": "module example.com/adapter\n\ngo 1.24\n",
   "libs/adapter/adapter.go": 'package adapter\n\nvar Name = "adapter"\n',
@@ -819,6 +835,7 @@ var _ = adapter.Name
  * @returns {string[]}
  */
 export function buildSimpleNxTree(root, { boundaryConfig = "module-boundaries.config.mjs" } = {}) {
+  // used by its own test
   const write = writeIn(root);
   write(
     "nx.json",
@@ -851,7 +868,7 @@ export function buildSimpleNxTree(root, { boundaryConfig = "module-boundaries.co
  * @param {{boundaryConfig?: string}} [options]
  * @returns {string[]}
  */
-export function buildSimpleNativeTree(
+export function buildSimpleNativeTree( // used by its own test
   root,
   { boundaryConfig = "module-boundaries.config.mjs" } = {},
 ) {
@@ -950,7 +967,7 @@ var _ = parent.Name
  * @param {{boundaryConfig?: string}} [options]
  * @returns {string[]}
  */
-export function buildCompositeNxTree(
+export function buildCompositeNxTree( // used by its own test
   root,
   { boundaryConfig = "module-boundaries.config.mjs" } = {},
 ) {
@@ -1029,7 +1046,7 @@ export function buildCompositeNxTree(
  * @param {{boundaryConfig?: string}} [options]
  * @returns {string[]}
  */
-export function buildCompositeNativeTree(
+export function buildCompositeNativeTree( // used by its own test
   root,
   { boundaryConfig = "module-boundaries.config.mjs" } = {},
 ) {
@@ -1175,7 +1192,7 @@ export function buildCompositeNativeTree(
 const LAYOUT_BOUNDARY_CONFIG = `export const depConstraints = [
   { sourceTag: "layer:thing", onlyDependOnLibsWithTags: ["layer:thing"] },
 ];
-export const moduleBoundaryOptions = {
+export const moduleBoundaryOptions = { // used by its own test
   allow: [],
   buildTargets: ["build"],
   enforceBuildableLibDependency: false,
@@ -1227,6 +1244,7 @@ var _ = blocked.Name
  * @returns {string[]}
  */
 export function buildLayoutNxTree(root, { boundaryConfig = "module-boundaries.config.mjs" } = {}) {
+  // used by its own test
   const write = writeIn(root);
   write(
     "nx.json",
@@ -1262,7 +1280,7 @@ export function buildLayoutNxTree(root, { boundaryConfig = "module-boundaries.co
  * @param {{boundaryConfig?: string}} [options]
  * @returns {string[]}
  */
-export function buildLayoutNativeTree(
+export function buildLayoutNativeTree( // used by its own test
   root,
   { boundaryConfig = "module-boundaries.config.mjs" } = {},
 ) {

package/src/providers/native/index.mjs

@@ -61,6 +61,7 @@ function projectOfFactory(projects) {
  *   stale `coverage.exempt` row.
  */
 export function discover({ root, files, readFile }) {
+  // used by its own test
   const model = loadNativeModel(root, { readFile });
   const { projects, failures: discoveryFailures } = discoverNativeProjects({
     root,
@@ -128,7 +129,7 @@ export function discover({ root, files, readFile }) {
  * @param {{discovered: ReturnType<typeof discover>, importSites: object[]}} args
  * @returns {{nodes: Record<string, object>, dependencies: Record<string, object[]>, workspaceLayout?: {appsDir: string, libsDir: string}, exemptedFiles?: string[]}}
  */
-export function buildGraph({ discovered, importSites }) {
+function buildGraph({ discovered, importSites }) {
   return buildNativeGraph({
     projects: discovered.projects,
     importSites,

package/src/providers/native/model.mjs

@@ -191,6 +191,7 @@ function parseArchkeepJson(text) {
  * for a tree that kept Nx-shaped project boundaries without keeping Nx.
  */
 export const DEFAULT_MANIFEST_NAMES = Object.freeze([
+  // used by its own test
   "project.json",
   "package.json",
   "go.mod",
@@ -255,6 +256,7 @@ const PROJECT_TYPES = ["app", "lib", "e2e"];
  * @see DEFAULT_MANIFEST_NAMES
  */
 export const DEFAULT_INFER_EXCLUDE = Object.freeze([
+  // used by its own test
   "**/docs/**",
   "**/fixtures/**",
   "**/__fixtures__/**",
@@ -549,6 +551,7 @@ const TOP_LEVEL_KEYS = [
  * @returns {string[]}
  */
 export function findNativeModelViolations(raw) {
+  // used by its own test
   if (!isPlainObject(raw)) return [`archkeep.json: expected an object, got ${describe(raw)}`];
 
   const violations = [];
@@ -699,6 +702,7 @@ export function findNativeModelViolations(raw) {
  * @returns {object} `NativeModel` — see `./index.mjs`.
  */
 export function normalizeNativeModel(raw) {
+  // used by its own test
   // `raw.projects` may be absent — `findNativeModelViolations` above validates
   // that shape the same way it validates `projects: {}`, so this has to read
   // it back the same way rather than assume the key is always present.

package/src/report/envelope-shape.mjs

@@ -89,6 +89,7 @@ function typeName(value) {
  *   JSON document can carry.
  */
 export function envelopeFieldPaths(envelope) {
+  // used by its own test
   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}`} ` +
@@ -152,6 +153,7 @@ function walk(value, path, byPath) {
  * @returns {{added: string[], removed: string[]}}
  */
 export function compareFieldPaths(recorded, observed) {
+  // used by its own test
   const recordedSet = new Set(recorded);
   const observedSet = new Set(observed);
   return {

package/src/report/json.mjs

@@ -39,6 +39,7 @@
  */
 import { EXIT_FOR_STATUS } from "../verdict.mjs";
 import { verdictForStatus } from "../governance/verdict.mjs";
+import { describe, isNonEmptyString } from "../values.mjs";
 import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
@@ -163,10 +164,11 @@ export function jsonEnvelope({ command, context, status, exitCode, coverage, res
     // `result`. A hand-built "fail" with no findings is still a loud lie
     // (status "findings", exitCode 1, verdict "fail"), never the silent
     // direction.
-    if (decision.verdict === "unknown" && decision.reason === undefined) {
+    if (decision.verdict === "unknown" && !isNonEmptyString(decision.reason)) {
       throw new Error(
         `archkeep: refusing to build a JSON envelope where an "unknown" decision has no reason — ` +
-          `I3: an unknown verdict must say why no verdict was reached, or it reads as a shrug. ` +
+          `I3: an unknown verdict must say why no verdict was reached, or it reads as a shrug ` +
+          `(a reason of ${describe(decision.reason)} is not a reason). ` +
           `This is a bug in the command that built the envelope.`,
       );
     }

package/src/report/sarif.mjs

@@ -62,15 +62,15 @@ import { TSCONFIG_PATHS_MESSAGE_IDS, TSCONFIG_PATHS_MESSAGES } from "../tsconfig
 import { formatConstraint } from "./text.mjs";
 
 /** The schema every consumer of this file validates against. */
-export const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
-export const SARIF_VERSION = "2.1.0";
+const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+const SARIF_VERSION = "2.1.0";
 
 /**
  * The single rule id every failing fitness function's result shares — see
  * `sarifRules()`'s own comment for why one id stands in for the whole
  * open-ended, workspace-declared set.
  */
-export const FITNESS_FAILED_RULE_ID = "fitnessFunctionFailed";
+export const FITNESS_FAILED_RULE_ID = "fitnessFunctionFailed"; // used by its own test
 
 /**
  * A workspace-relative path as a URI reference: each segment percent-encoded,
@@ -106,6 +106,7 @@ export const FITNESS_FAILED_RULE_ID = "fitnessFunctionFailed";
  * @returns {string}
  */
 export function toUriReference(path) {
+  // used by its own test
   return path.split("/").map(encodeURIComponent).join("/");
 }
 
@@ -139,6 +140,7 @@ export function toUriReference(path) {
  * @returns {object[]}
  */
 export function sarifRules(customCatalogue = []) {
+  // used by its own test
   return [
     ...MESSAGE_IDS.map((id) => ({
       id,
@@ -231,6 +233,7 @@ const CUSTOM_RULE_INDEX_BASE =
  * @returns {object}
  */
 export function sarifCustomRuleResult(finding, ruleIndex) {
+  // used by its own test
   const physicalLocation =
     finding.sourceFile === undefined
       ? null
@@ -283,6 +286,7 @@ export function sarifCustomRuleResult(finding, ruleIndex) {
  * @returns {object}
  */
 export function sarifCustomRuleNotification(decision) {
+  // used by its own test
   const posture =
     decision.verdict === "not_applicable" ? "did not apply to this run" : "could not be judged";
   return {
@@ -305,6 +309,7 @@ export function sarifCustomRuleNotification(decision) {
  * @returns {object}
  */
 export function sarifResult(violation) {
+  // used by its own test
   const detail =
     `Import ${JSON.stringify(violation.specifier)} (${violation.kind}) ` +
     `from ${violation.sourceProject ?? "(no project)"} ` +
@@ -364,7 +369,7 @@ export function sarifResult(violation) {
  * @param {object} finding A finding from `../go-work.mjs` `compareGoWork`.
  * @returns {object}
  */
-export function sarifGoWorkResult(finding) {
+function sarifGoWorkResult(finding) {
   const physicalLocation = { artifactLocation: { uri: toUriReference(finding.file) } };
   if (finding.line !== null) {
     physicalLocation.region = { startLine: finding.line, startColumn: finding.column };
@@ -395,7 +400,7 @@ export function sarifGoWorkResult(finding) {
  * @param {object} finding A finding from `../tsconfig-paths.mjs`.
  * @returns {object}
  */
-export function sarifTsconfigPathsResult(finding) {
+function sarifTsconfigPathsResult(finding) {
   return {
     ruleId: finding.messageId,
     ruleIndex:
@@ -444,7 +449,7 @@ export function sarifTsconfigPathsResult(finding) {
  *   `declaredEdgeViolationsForCheck`, extended with `file` — workspace-relative.
  * @returns {object}
  */
-export function sarifDeclaredEdgeResult(finding) {
+function sarifDeclaredEdgeResult(finding) {
   return {
     ruleId: finding.messageId,
     ruleIndex: MESSAGE_IDS.indexOf(finding.messageId),
@@ -472,6 +477,7 @@ export function sarifDeclaredEdgeResult(finding) {
  * @returns {object}
  */
 export function sarifIntentResult(finding) {
+  // used by its own test
   return {
     ruleId: finding.rule,
     ruleIndex:
@@ -516,6 +522,7 @@ export function sarifIntentResult(finding) {
  * @returns {object}
  */
 export function sarifFitnessResult(decision, policySource = null) {
+  // used by its own test
   const result = {
     ruleId: FITNESS_FAILED_RULE_ID,
     ruleIndex:
@@ -548,6 +555,7 @@ export function sarifFitnessResult(decision, policySource = null) {
  * @returns {object}
  */
 export function sarifFitnessNotification(decision) {
+  // used by its own test
   return {
     level: "warning",
     message: {
@@ -567,7 +575,7 @@ export function sarifFitnessNotification(decision) {
  * @param {object} failure An `AnalysisFailure`.
  * @returns {object}
  */
-export function sarifNotification(failure) {
+function sarifNotification(failure) {
   const physicalLocation = { artifactLocation: { uri: toUriReference(failure.sourceFile) } };
   if (failure.line !== null) {
     physicalLocation.region = { startLine: failure.line, startColumn: failure.column };
@@ -601,6 +609,7 @@ export function sarifNotification(failure) {
  * @returns {object}
  */
 export function sarifIntentNotification(entry) {
+  // used by its own test
   return {
     level: "warning",
     message: {
@@ -641,6 +650,7 @@ const UNOWNED_SAMPLE_LIMIT = 10;
  * @returns {object}
  */
 export function sarifCoverageGapNotification(gap) {
+  // used by its own test
   const manifests = gap.manifests ?? [];
   const found = manifests.length > 0 ? `: ${manifests.join(", ")}` : "";
   if (gap.kind === "unregistered-plugin") {
@@ -760,7 +770,7 @@ export function sarifCoverageGapNotification(gap) {
  * @param {string} decisionRef The cited value, exactly as the row spelled it.
  * @returns {object}
  */
-export function sarifDecisionRefNotification(decisionRef) {
+function sarifDecisionRefNotification(decisionRef) {
   return {
     level: "warning",
     message: {
@@ -853,6 +863,7 @@ export function sarifDecisionRefNotification(decisionRef) {
  * @returns {object} A SARIF 2.1.0 log, ready to `JSON.stringify`.
  */
 export function buildSarifLog({
+  // used by its own test
   violations,
   failures,
   goWork,
@@ -1016,6 +1027,7 @@ export function buildSarifLog({
  * @returns {object}
  */
 export function sarifDeltaResult(entry, site) {
+  // used by its own test
   const target = entry.targetIsSpecifier
     ? `specifier ${JSON.stringify(entry.target)}`
     : entry.target;
@@ -1102,6 +1114,7 @@ export function sarifDeltaResult(entry, site) {
  * @returns {object} A SARIF 2.1.0 log, ready to `JSON.stringify`.
  */
 export function buildDeltaSarifLog({ delta, coverage, customCatalogue = [] }) {
+  // used by its own test
   const customRuleIndex = new Map(
     customCatalogue.map((entry, index) => [entry.ruleId, CUSTOM_RULE_INDEX_BASE + index]),
   );

package/src/report/snapshot-text.mjs

@@ -35,7 +35,7 @@ export function sanitize(text) {
  * @param {{name: string, root: string, tags: string[]}} project
  * @returns {string}
  */
-export function formatProject(project) {
+function formatProject(project) {
   const tags =
     project.tags.length > 0 ? ` [${project.tags.map((t) => sanitize(t)).join(", ")}]` : "";
   return `  ${sanitize(project.name)}  ${sanitize(project.root)}${tags}`;
@@ -47,7 +47,7 @@ export function formatProject(project) {
  * @param {{source: string, target: string, type: string}} edge
  * @returns {string}
  */
-export function formatEdge(edge) {
+function formatEdge(edge) {
   return `  ${sanitize(edge.source)} → ${sanitize(edge.target)} (${sanitize(edge.type)})`;
 }
 
@@ -57,7 +57,7 @@ export function formatEdge(edge) {
  * @param {{field: string, baseline: *, head: *}} change
  * @returns {string}
  */
-export function formatChange(change) {
+function formatChange(change) {
   const formatValue = (v) => {
     if (Array.isArray(v)) return v.length > 0 ? v.map((x) => sanitize(x)).join(", ") : "(none)";
     if (v === null || v === undefined) return "(none)";

package/src/report/text.mjs

@@ -94,6 +94,7 @@ function formatEdge(violation) {
  * @returns {string}
  */
 export function formatViolation(violation, unresolvedDecisionRefs) {
+  // used by its own test
   const message = violation.message
     .split("\n")
     .map((line) => (line === "" ? "" : `${CONTINUED}${line}`))
@@ -159,6 +160,7 @@ const formatFailure = (failure) =>
  * @returns {string}
  */
 export function formatFailures(failures) {
+  // used by its own test
   if (failures.length === 0) return "";
   const unchecked = failures.filter(isWholeFileFailure);
   const blind = failures.filter((failure) => !isWholeFileFailure(failure));
@@ -236,6 +238,7 @@ export function formatFailures(failures) {
  * @returns {string} Empty exactly when there is no go.work verdict to render.
  */
 export function formatGoWork(goWork) {
+  // used by its own test
   if (goWork == null) return "";
   const { findings, moduleProjects } = goWork;
   const modules = `${moduleProjects} Go module project${moduleProjects === 1 ? "" : "s"}`;
@@ -291,6 +294,7 @@ export function formatGoWork(goWork) {
  * @returns {string} Empty exactly when there is no declared-edge verdict to render.
  */
 export function formatDeclaredEdges(declaredEdges, unresolvedDecisionRefs) {
+  // used by its own test
   if (declaredEdges == null) return "";
   const { findings, judged, declaration = "implicitDependencies" } = declaredEdges;
   const label = `${judged} implicit edge${judged === 1 ? "" : "s"} judged`;
@@ -345,6 +349,7 @@ export function formatDeclaredEdges(declaredEdges, unresolvedDecisionRefs) {
  * @returns {string} Empty exactly when there is no paths verdict to render.
  */
 export function formatTsconfigPaths(tsconfigPaths) {
+  // used by its own test
   if (tsconfigPaths == null) return "";
   const { tsConfig, findings, aliases, unjudged } = tsconfigPaths;
   const judged =
@@ -393,7 +398,7 @@ export function formatTsconfigPaths(tsconfigPaths) {
  *   unresolvedDecisionRefs?: {kind: string, decisionRef: string}[]}|null|undefined} intent
  * @returns {string} Empty exactly when there is no intent verdict to render.
  */
-export function formatIntentSection(intent) {
+function formatIntentSection(intent) {
   if (intent == null) return "";
   const { verdict, findings, unresolved, boundaries, unresolvedDecisionRefs = [] } = intent;
   const count = boundaries.length;
@@ -542,6 +547,7 @@ function customFindingSite(finding) {
  * @returns {string} Empty exactly when the policy declared no custom rules.
  */
 export function formatCustomRulesSection(customRules) {
+  // used by its own test
   if (customRules == null || customRules.decisions.length === 0) return "";
   const { decisions, overall } = customRules;
   const entries = decisions.map((decision) => {
@@ -596,6 +602,7 @@ export function formatCustomRulesSection(customRules) {
  * @returns {string} Empty exactly when there is no coverage gap to render.
  */
 export function formatCoverageGaps(coverageGaps) {
+  // used by its own test
   if (coverageGaps.length === 0) return "";
   return coverageGaps.map(formatCoverageGap).join("\n");
 }
@@ -792,6 +799,7 @@ function formatUntrackedFilesGap(gap) {
  * @returns {string} Empty exactly when no policy identity was supplied.
  */
 export function formatPolicy(policy) {
+  // used by its own test
   if (policy == null) return "";
   const { profile, source, fingerprint } = policy;
   const law = profile === null ? source : `profile "${profile}" from ${source}`;
@@ -812,7 +820,7 @@ export function formatPolicy(policy) {
  * @param {Set<string>} [unresolvedDecisionRefs] Forwarded to `formatViolation`.
  * @returns {string}
  */
-export function formatAcceptedViolations(waived, unresolvedDecisionRefs) {
+function formatAcceptedViolations(waived, unresolvedDecisionRefs) {
   const rows = waived.map((violation) => {
     const waiver = violation.waivedBy;
     return [

package/src/rules/match.mjs

@@ -85,7 +85,7 @@ import { posix } from "node:path";
  * costs is bounded at the other end, by `MAX_SPECIFIER_LENGTH` below, because
  * a degree-2 pattern is still quadratic in a subject nothing else limits.
  */
-export const MAX_RESPLIT_REPETITIONS = 2;
+const MAX_RESPLIT_REPETITIONS = 2;
 
 /**
  * The most repetitions a SINGLE-DELIMITER chain may carry — the one shape
@@ -114,7 +114,7 @@ export const MAX_RESPLIT_REPETITIONS = 2;
  * path pattern naming every segment of `libs/<area>/<name>/<entry>` needs
  * four.
  */
-export const MAX_DELIMITED_SEGMENTS = 8;
+export const MAX_DELIMITED_SEGMENTS = 8; // used by its own test
 
 /**
  * The longest import specifier this engine will match a consumer-written
@@ -148,7 +148,7 @@ export const MAX_DELIMITED_SEGMENTS = 8;
  * 1024 `b`s. That is the number to compare a change here against; before this
  * bound and the refusals above, the same sweep found 59 SECONDS.
  */
-export const MAX_SPECIFIER_LENGTH = 1024;
+export const MAX_SPECIFIER_LENGTH = 1024; // used by its own test
 
 /**
  * The deepest group nesting this model reads. Past it a pattern is refused
@@ -1123,6 +1123,7 @@ function tradesWithNeighbour(elements, index, last) {
  * @returns {string|null}
  */
 export function regexComplexityError(source) {
+  // used by its own test
   const { root, tooDeep } = parsePattern(source);
   if (tooDeep) {
     return (
@@ -1174,7 +1175,7 @@ function resplitReason(degree) {
  * @param {string} specifier
  * @returns {string|null}
  */
-export function specifierLengthError(specifier) {
+function specifierLengthError(specifier) {
   if (specifier.length <= MAX_SPECIFIER_LENGTH) return null;
   return (
     `is ${specifier.length} characters, past the ${MAX_SPECIFIER_LENGTH} this engine will match ` +
@@ -1538,7 +1539,7 @@ export function findMatchingProjects(patterns, nodes) {
  * anything a real suppression, exemption or project rule plausibly needs to
  * name from ONE glob string.
  */
-export const MAX_GLOB_EXPANSIONS = 512;
+export const MAX_GLOB_EXPANSIONS = 512; // used by its own test
 
 /**
  * A brace group's content matches one of these two shapes instead of a
@@ -1620,6 +1621,7 @@ function rangeCardinality(content) {
  *   certain to exceed `cap`.
  */
 export function braceExpansionCount(pattern, cap) {
+  // used by its own test
   const limit = cap + 1;
   /** @type {{alternatives: number, branchProduct: number, start: number}[]} */
   const frames = [{ alternatives: 0, branchProduct: 1, start: 0 }];

package/src/rules/specifiers.mjs

@@ -48,6 +48,7 @@ export const DEFAULT_WORKSPACE_LAYOUT = Object.freeze({ libsDir: "libs", appsDir
 
 /** `./x` or `../x` — upstream's `isRelative`, from `runtime-lint-utils`. */
 export function isRelative(s) {
+  // used by its own test
   return s.startsWith("./") || s.startsWith("../");
 }
 
@@ -191,6 +192,7 @@ export function getTargetProjectBasedOnRelativeImport(imp, sourceFile, projectRo
  * @returns {boolean}
  */
 export function isConstraintBanningProject(externalProject, constraint, imp) {
+  // used by its own test
   assertMatchableSpecifier(imp, "import specifier judged against the constraint table");
   const { allowedExternalImports, bannedExternalImports } = constraint;
   const { packageName } = externalProject.data;