@ecoma-io/archkeep 0.23.0 → 0.24.1

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/index.mjs

@@ -815,6 +815,36 @@ function annotatedByTable(suppressions, violation, now) {
   return violation;
 }
 
+/**
+ * The suppression table applied to verdicts that did not come from
+ * `evaluateRun`'s site walk — suppressing rows remove, active waivers mark
+ * `waivedBy`, expired ones re-assert with `evidence`, exactly as the site walk
+ * applies them, because a verdict must ride the same table whichever walk
+ * produced it.
+ *
+ * The one caller is `./commands/check.mjs`'s markdown document track: its
+ * edges are judged per edge through `./edge-constraints.mjs`'s `judgeEdge` —
+ * they have no import site for `candidateGroupsFor` to walk, so there is no
+ * group chain, only a flat list — but a suppression row that names a document
+ * must silence the same verdict here it would silence on an import site, and
+ * a waiver over one must annotate it the same way. Unlike the site walk there
+ * is no second candidate group to fall through to: an edge's verdicts are all
+ * reported together, so a row that removes some leaves the rest standing
+ * rather than promoting anything.
+ *
+ * @param {object[]} suppressions The validated `boundarySuppressions` table.
+ * @param {object[]} violations The unfiltered verdicts, in walk order.
+ * @param {string} [now] Reference instant for waiver expiry; defaults to the
+ *   shared governance clock, as `evaluateRun` does.
+ * @returns {object[]} The survivors, in input order, annotations applied.
+ */
+export function applySuppressionTable(suppressions, violations, now = referenceTime()) {
+  if (suppressions.length === 0) return violations;
+  return violations
+    .filter((violation) => !removedByTable(suppressions, violation, now))
+    .map((violation) => annotatedByTable(suppressions, violation, now));
+}
+
 /**
  * One run of the engine over every import site: the judged verdict per site
  * plus the raw superset it was picked from.

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;

package/src/rules/tags.mjs

@@ -29,7 +29,7 @@ import { tagMatches } from "./match.mjs";
 import { getPath, pathExists } from "./reachability.mjs";
 
 /** `"a", "b"` — how upstream renders a tag list inside a message. */
-export function stringifyTags(tags) {
+function stringifyTags(tags) {
   return tags.map((t) => `"${t}"`).join(", ");
 }
 
@@ -55,7 +55,7 @@ export function hasTag(project, tag) {
 }
 
 /** True when the project carries NONE of these tags — upstream's spelling. */
-export function hasNoneOfTheseTags(project, tags) {
+function hasNoneOfTheseTags(project, tags) {
   return tags.filter((tag) => hasTag(project, tag)).length === 0;
 }
 
@@ -165,6 +165,7 @@ export function orphanedNotDependOnTags(depConstraints, graph) {
  * are what the message prints so a reader can see the hop that did it.
  */
 export function findDependenciesWithTags(targetProject, tags, graph, reach) {
+  // used by its own test
   const reachable = Object.keys(graph.nodes)
     .sort()
     .filter(

package/src/rules/topology.mjs

@@ -57,6 +57,7 @@ export function appIsMFERemote(project) {
  * — the common case, and the one that keeps `noSelfCircularDependencies` armed.
  */
 export function entryPointOf(file, projectRoot, entryPoints) {
+  // used by its own test
   if (!entryPoints || entryPoints.length === 0) return undefined;
   const fileEntryPoint = entryPoints.find((entry) => entry.file === file);
   if (fileEntryPoint) return fileEntryPoint.file;
@@ -88,7 +89,7 @@ export function entryPointOf(file, projectRoot, entryPoints) {
  * standing in for upstream's module resolution — the resolver already ran; this
  * layer never runs a second one.
  */
-export function secondaryEntryPointPath(resolvedFile, targetProject) {
+function secondaryEntryPointPath(resolvedFile, targetProject) {
   if (!resolvedFile) return undefined;
   return entryPointOf(resolvedFile, targetProject.data.root, targetProject.data?.entryPoints);
 }
@@ -128,6 +129,7 @@ export function belongsToDifferentEntryPoint(resolvedFile, sourceFile, sourcePro
  * @returns {string[]|null}
  */
 export function findDynamicImportPath(graph, sourceProjectName, targetProjectName, visited = []) {
+  // used by its own test
   if (visited.indexOf(sourceProjectName) > -1) return null;
   for (const dependency of graph.dependencies?.[sourceProjectName] ?? []) {
     if (dependency.type !== DYNAMIC) continue;
@@ -152,6 +154,7 @@ export function findDynamicImportPath(graph, sourceProjectName, targetProjectNam
  * fired, and then the verdict would name evidence for a route nobody walked.
  */
 export function hasDynamicImport(graph, sourceProjectName, targetProjectName) {
+  // used by its own test
   return findDynamicImportPath(graph, sourceProjectName, targetProjectName) !== null;
 }
 
@@ -209,6 +212,7 @@ export function createFileDependencyIndex(edges) {
 
 /** The files carrying each hop of a path — one entry per consecutive pair. */
 export function findFilesInCircularPath(fileIndex, circularPath) {
+  // used by its own test
   const chain = [];
   for (let i = 0; i < circularPath.length - 1; i++) {
     chain.push(fileIndex.any.get(edgeKey(circularPath[i].name, circularPath[i + 1].name)) ?? []);
@@ -218,6 +222,7 @@ export function findFilesInCircularPath(fileIndex, circularPath) {
 
 /** The files that lazy-load `target` from inside `source`. */
 export function findFilesWithDynamicImports(fileIndex, sourceProjectName, targetProjectName) {
+  // used by its own test
   return fileIndex.dynamic.get(edgeKey(sourceProjectName, targetProjectName)) ?? [];
 }
 

package/src/verdict.mjs

@@ -61,6 +61,33 @@ export function coverageIncompleteReasons({ unchecked, blindSpots, analyzed }) {
     analyzed === 0 ? "no file in scope could be analyzed — coverage incomplete" : null,
   ].filter(Boolean);
 }
+
+/**
+ * The one completeness predicate — the three coverage axes conjoined, the
+ * boolean twin of `coverageIncompleteReasons` directly above, which words the
+ * same axes as clauses. `coverageVerdict` (`./commands/coverage-verdict.mjs`)
+ * reads its `complete` from here, `verdictFor` reads the decision's
+ * `coverageComplete` from here, and `check`'s coverage block reads its
+ * `complete` from here — three faces of one claim, so the envelope's
+ * `coverage.complete` and its `decision.coverageComplete` cannot disagree
+ * about a run neither re-derives from the other.
+ *
+ * The counts come from the caller because a command's coverage universe is
+ * its own: `check`'s is wider than `commandContext.analysis` (the go.work and
+ * tsconfig whole-file failures it pushes, the accepted `coverage.unowned`
+ * files it withdraws), and each face feeds the counts it is a claim about. A
+ * caller that reads plain `commandContext.analysis` should call
+ * `coverageVerdict` instead — this predicate is the law's last step, not the
+ * place failure classes get decided (`./analysis/source-util.mjs`'s
+ * classifiers own that line).
+ *
+ * @param {{unchecked: number, blindSpotCount: number, analyzed: number}} counts
+ * @returns {boolean} Whether the run judged everything in its scope.
+ */
+export function coverageComplete({ unchecked, blindSpotCount, analyzed }) {
+  return unchecked === 0 && blindSpotCount === 0 && analyzed > 0;
+}
+
 /**
  * The one place that turns a run's counts into the verdict every format
  * agrees on. `runCheck` uses it for the process's exit code; `check` uses the
@@ -127,7 +154,11 @@ export function verdictFor({
       reasons: coverageReasons,
       decision: buildDecision({
         status: "findings",
-        coverageComplete: unchecked === 0 && blindSpots === 0 && analyzed > 0,
+        // The one completeness predicate, not a restatement: the decision's
+        // `coverageComplete` and the envelope's `coverage.complete` are the
+        // same claim about the same counts (`check` feeds both from one
+        // object), so they read it from one expression.
+        coverageComplete: coverageComplete({ unchecked, blindSpotCount: blindSpots, analyzed }),
         findings:
           violations +
           declaredEdgeFindings +
@@ -188,7 +219,7 @@ export function verdictFor({
       reasons,
       decision: buildDecision({
         status: "no-verdict",
-        coverageComplete: unchecked === 0 && blindSpots === 0 && analyzed > 0,
+        coverageComplete: coverageComplete({ unchecked, blindSpotCount: blindSpots, analyzed }),
         findings: 0,
         reason: reasons.join("; "),
       }),

package/src/workspace.mjs

@@ -721,6 +721,7 @@ const DOTLESS_FURNITURE = Object.freeze(
  * @returns {boolean}
  */
 export function exemptFromUnsupportedLanguage(sourceFile) {
+  // used by its own test
   const base = sourceFile.slice(sourceFile.lastIndexOf("/") + 1);
   // Dotfiles are editor and tool state (`.gitignore`, `.env`, `.npmrc`).
   if (base.startsWith(".")) return true;