@ecoma-io/archkeep 0.14.0 → 0.16.0

package/src/report/sarif.mjs

@@ -956,6 +956,261 @@ export function buildSarifLog({
   };
 }
 
+/**
+ * One introduced boundary-violation entry, at one of its head sites, as a
+ * SARIF result — the `delta` verb's rendering of the same rule catalogue
+ * `sarifResult` resolves into.
+ *
+ * `ruleId` is the entry's `messageId`, spelled exactly, so a delta upload and
+ * a `check` upload name the same rule for the same law — no new descriptors,
+ * and no second catalogue. The classifier's entry carries no rendered upstream
+ * message (`../commands/delta-classify.mjs` keeps identity and evidence, not
+ * prose), so the message is composed here from the facts the entry does carry:
+ * the classification, both sides' occurrence counts, the edge, and the
+ * constraint row — never empty, because GitHub rejects a result whose
+ * `message.text` is.
+ *
+ * One result per HEAD site: an introduced violation exists at head by
+ * construction (`headCount > 0`), and the head sites are the lines a reviewer
+ * of the change can act on — a base site names code the checkout under review
+ * may no longer contain.
+ *
+ * A waived-introduced entry is still a result (reported, not gating —
+ * `../commands/delta.mjs`'s fold), tagged with the same `accepted` vocabulary
+ * `sarifResult` uses for a waived violation, so one consumer query covers both
+ * verbs' uploads.
+ *
+ * @param {{messageId: string, sourceProject: string|null, target: string,
+ *   targetIsSpecifier: boolean, constraint: object|null, baseCount: number,
+ *   headCount: number, reason?: string, waived?: boolean,
+ *   waivedBy?: {expiresAt?: string, reason?: string}}} entry One `introduced`
+ *   entry from `classifyViolations` (`../commands/delta-classify.mjs`).
+ * @param {{file: string, line: number, column: number, specifier?: string,
+ *   kind?: string}} site One of the entry's head sites — 1-based, as the
+ *   analysis records carry them.
+ * @returns {object}
+ */
+export function sarifDeltaResult(entry, site) {
+  const target = entry.targetIsSpecifier
+    ? `specifier ${JSON.stringify(entry.target)}`
+    : entry.target;
+  const text =
+    `Introduced by this change: ${entry.messageId} — ` +
+    `from ${entry.sourceProject ?? "(no project)"} to ${target} ` +
+    `(${entry.baseCount} occurrence${entry.baseCount === 1 ? "" : "s"} at base, ` +
+    `${entry.headCount} at head)` +
+    `${entry.reason ? ` — ${entry.reason}` : ""}. ` +
+    `Constraint: ${formatConstraint(entry.constraint)}`;
+  return {
+    ruleId: entry.messageId,
+    ruleIndex: MESSAGE_IDS.indexOf(entry.messageId),
+    level: "error",
+    message: { text },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: toUriReference(site.file) },
+          region: { startLine: site.line, startColumn: site.column },
+        },
+      },
+    ],
+    properties: {
+      delta: "introduced",
+      baseCount: entry.baseCount,
+      headCount: entry.headCount,
+      sourceProject: entry.sourceProject,
+      target: entry.target,
+      // The same vocabulary `sarifResult` uses for a waived violation: the
+      // result is still an error (an accepted violation is still a violation),
+      // and the properties say why it does not gate.
+      ...(entry.waived === true
+        ? {
+            accepted: true,
+            acceptedUntil: entry.waivedBy?.expiresAt,
+            acceptedReason: entry.waivedBy?.reason,
+          }
+        : {}),
+    },
+  };
+}
+
+/**
+ * The `delta` verb's SARIF log: the INTRODUCED buckets as results, everything
+ * the classification could not answer as tool-execution notifications.
+ *
+ * Results are introduced entries only — the classified boundary violations
+ * (`sarifDeltaResult`, waived ones included and tagged) and the introduced
+ * custom-rule findings, the latter through the same `sarifCustomRuleResult`
+ * and end-of-catalogue descriptors `check`'s log uses, so a custom finding
+ * resolves in `sarifRules(customCatalogue)` here exactly as it does there.
+ * Resolved and unchanged entries are deliberately NOT results: this log is
+ * uploaded against the head checkout, and an annotation for a violation the
+ * change resolved would mark code that no longer contains it.
+ *
+ * The notification lane is the load-bearing half. `delta` exits 3 on any
+ * `unknown` entry (`../commands/delta.mjs`'s fold), and every one of those
+ * rides here — a violation, unresolvable-record, or custom-rule item whose
+ * identity could not be stated — so an exit-3 delta can never upload a log
+ * byte-identical to a clean run's, the same guarantee `buildSarifLog` keeps
+ * for `check`'s no-verdict lanes. Coverage notes (policy drift, dirty trees,
+ * skipped or removed custom rules) and introduced unresolvable records ride
+ * the same lane: none is a verdict, and dropping any of them is the silent
+ * direction (`../../../../AGENTS.md`).
+ *
+ * `executionSuccessful` stays `true` on every status — the run completed and
+ * classified; the findings are results, not tool errors — and `columnKind`
+ * states the analyzers' real UTF-16 convention, both for the reasons the
+ * module header gives.
+ *
+ * @param {{delta: {violations: {introduced: object[], resolved?: object[],
+ *     unchanged?: object[], unknown: object[]},
+ *   unresolvable: {introduced: object[], resolved?: object[],
+ *     unchanged?: object[], unknown: object[]},
+ *   customRules?: {findings: {introduced: object[], resolved?: object[],
+ *     unchanged?: object[], unknown: object[]}}},
+ *   coverage: {notes?: string[]},
+ *   customCatalogue?: {ruleId: string, rule: string, findingId: string,
+ *     message: string}[]}} run The `deltaCommand` result's `delta` and
+ *   `coverage`, plus the head-declared custom-rule catalogue
+ *   (`../commands/custom-rules.mjs`'s `customRulesForDelta`) — passed
+ *   separately because the envelope deliberately does not carry it.
+ * @returns {object} A SARIF 2.1.0 log, ready to `JSON.stringify`.
+ */
+export function buildDeltaSarifLog({ delta, coverage, customCatalogue = [] }) {
+  const customRuleIndex = new Map(
+    customCatalogue.map((entry, index) => [entry.ruleId, CUSTOM_RULE_INDEX_BASE + index]),
+  );
+  const customIntroduced = delta.customRules?.findings.introduced ?? [];
+  const results = [
+    ...delta.violations.introduced.flatMap((entry) =>
+      entry.headSites.map((site) => sarifDeltaResult(entry, site)),
+    ),
+    ...customIntroduced.flatMap((entry) =>
+      entry.headSites.map((site) => {
+        const rendered = sarifCustomRuleResult(
+          {
+            id: entry.ruleId,
+            message:
+              `Introduced by this change: custom rule finding ${entry.ruleId} ` +
+              `(${entry.baseCount} occurrence${entry.baseCount === 1 ? "" : "s"} at base, ` +
+              `${entry.headCount} at head)` +
+              `${entry.reason ? ` — ${entry.reason}` : ""}` +
+              `${typeof entry.message === "string" && entry.message !== "" ? `: ${entry.message}` : ""}`,
+            ...(typeof site.file === "string" ? { sourceFile: site.file } : {}),
+            ...(typeof site.line === "number" ? { line: site.line } : {}),
+            ...(typeof site.column === "number" ? { column: site.column } : {}),
+            ...(entry.project === null ? {} : { project: entry.project }),
+          },
+          // `?? -1` for the same reason `buildSarifLog` gives: an introduced
+          // finding whose id its own head catalogue does not declare cannot
+          // arrive here, and a regression in that guarantee must be a visibly
+          // broken index rather than an `undefined` GitHub ignores.
+          customRuleIndex.get(entry.ruleId) ?? -1,
+        );
+        return {
+          ...rendered,
+          properties: {
+            ...(rendered.properties ?? {}),
+            delta: "introduced",
+            baseCount: entry.baseCount,
+            headCount: entry.headCount,
+          },
+        };
+      }),
+    ),
+  ];
+  const toolExecutionNotifications = [
+    ...delta.violations.unknown.map((entry) => ({
+      level: "warning",
+      message: {
+        text: `delta could not classify a violation — ${entry.reason}. The run reaches no verdict.`,
+      },
+    })),
+    ...delta.unresolvable.unknown.map((entry) => ({
+      level: "warning",
+      message: {
+        text:
+          `delta could not classify an unresolvable import site — ${entry.reason}. ` +
+          `The run reaches no verdict.`,
+      },
+    })),
+    ...(delta.customRules?.findings.unknown ?? []).map((entry) => ({
+      level: "warning",
+      message: {
+        text:
+          `delta could not classify a custom-rule item` +
+          `${typeof entry.rule === "string" ? ` (rule "${entry.rule}")` : ""} — ` +
+          `${entry.reason}. The run reaches no verdict.`,
+      },
+    })),
+    // Introduced unresolvable records: sites the change added whose target
+    // analysis could not resolve. Never results — no rule reached a verdict
+    // about them — but a change that adds them must not upload the log a
+    // change that adds nothing would.
+    ...delta.unresolvable.introduced.map((entry) => ({
+      level: "warning",
+      message: {
+        text:
+          `This change introduces ${entry.headCount - entry.baseCount} unresolvable import ` +
+          `site${entry.headCount - entry.baseCount === 1 ? "" : "s"} for specifier ` +
+          `${JSON.stringify(entry.specifier)} (${entry.kind || "unknown kind"})` +
+          `${entry.sourceProject === null ? "" : ` in ${entry.sourceProject}`} — ` +
+          `no rule reached a verdict about ${entry.headCount - entry.baseCount === 1 ? "it" : "them"}`,
+      },
+      locations: (entry.headSites ?? [])
+        .filter((site) => typeof site.file === "string")
+        .map((site) => ({
+          physicalLocation: {
+            artifactLocation: { uri: toUriReference(site.file) },
+            ...(typeof site.line === "number"
+              ? {
+                  region: {
+                    startLine: site.line,
+                    ...(typeof site.column === "number" ? { startColumn: site.column } : {}),
+                  },
+                }
+              : {}),
+          },
+        })),
+    })),
+    ...(coverage.notes ?? []).map((note) => ({
+      level: "warning",
+      message: { text: `Coverage note: ${note}` },
+    })),
+  ];
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: { driver: { name: "archkeep", rules: sarifRules(customCatalogue) } },
+        columnKind: "utf16CodeUnits",
+        results,
+        invocations: [
+          {
+            // True even on exit 1 or 3: the classification completed and said
+            // what it could not answer — the same reasoning `buildSarifLog`
+            // states for `check`.
+            executionSuccessful: true,
+            toolExecutionNotifications,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * The delta SARIF log as the bytes to write — pretty-printed with a trailing
+ * newline, the same presentation `formatSarif` gives `check`'s log.
+ *
+ * @param {Parameters<typeof buildDeltaSarifLog>[0]} run
+ * @returns {string}
+ */
+export function formatDeltaSarif(run) {
+  return `${JSON.stringify(buildDeltaSarifLog(run), null, 2)}\n`;
+}
+
 /**
  * The SARIF log as the bytes to write — pretty-printed with a trailing newline,
  * so a file that lands in a diff or a log stays readable.

package/src/report/snapshot-text.mjs

@@ -0,0 +1,123 @@
+/**
+ * Formatters two snapshot-transition reports share — `history-text.mjs` and
+ * `evolution-text.mjs` render the same transition shape (a graph diff, notes,
+ * and a short kind label), and a second copy of these helpers is where the
+ * two renders would drift: one day "code drift" means one thing in `history`
+ * and another in `evolution`, and no gate compares rendered prose.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences in a name or value before
+ * it is printed, so a crafted project/tag/edge name cannot inject escape
+ * sequences into a consumer's terminal (`SECURITY.md`). Real project names are
+ * ordinary characters and pass through untouched; only C0 control characters
+ * (which includes the ESC byte) and DEL become visible escapes.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanitize(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
+    if (c === "\n") return "\\n";
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+
+/**
+ * One project as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{name: string, root: string, tags: string[]}} project
+ * @returns {string}
+ */
+export function formatProject(project) {
+  const tags =
+    project.tags.length > 0 ? ` [${project.tags.map((t) => sanitize(t)).join(", ")}]` : "";
+  return `  ${sanitize(project.name)}  ${sanitize(project.root)}${tags}`;
+}
+
+/**
+ * One edge as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function formatEdge(edge) {
+  return `  ${sanitize(edge.source)} → ${sanitize(edge.target)} (${sanitize(edge.type)})`;
+}
+
+/**
+ * One metadata change as a line, same shape as `diff-text.mjs`.
+ *
+ * @param {{field: string, baseline: *, head: *}} change
+ * @returns {string}
+ */
+export 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)";
+    return sanitize(String(v));
+  };
+  return `  ${change.field}  ${formatValue(change.baseline)} → ${formatValue(change.head)}`;
+}
+
+/**
+ * How the architecture actually changed between two snapshots: the added and
+ * removed projects and edges rendered as one line each. Changed projects
+ * render their changed fields beneath the project line, like `diff`.
+ *
+ * @param {object} changes The `computeDiff` payload.
+ * @returns {string[]}
+ */
+export function formatChanges(changes) {
+  const lines = [];
+  if (changes.addedProjects.length > 0) {
+    const word = changes.addedProjects.length === 1 ? "project" : "projects";
+    lines.push(`+ ${changes.addedProjects.length} added ${word}`);
+    for (const project of changes.addedProjects) lines.push(formatProject(project));
+  }
+  if (changes.removedProjects.length > 0) {
+    const word = changes.removedProjects.length === 1 ? "project" : "projects";
+    lines.push(`- ${changes.removedProjects.length} removed ${word}`);
+    for (const project of changes.removedProjects) lines.push(formatProject(project));
+  }
+  if (changes.changedProjects.length > 0) {
+    const word = changes.changedProjects.length === 1 ? "project" : "projects";
+    lines.push(`~ ${changes.changedProjects.length} changed ${word}`);
+    for (const project of changes.changedProjects) {
+      lines.push(`  ${project.name}`);
+      for (const change of project.changes) lines.push(formatChange(change));
+    }
+  }
+  if (changes.addedEdges.length > 0) {
+    const word = changes.addedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`+ ${changes.addedEdges.length} added ${word}`);
+    for (const edge of changes.addedEdges) lines.push(formatEdge(edge));
+  }
+  if (changes.removedEdges.length > 0) {
+    const word = changes.removedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`- ${changes.removedEdges.length} removed ${word}`);
+    for (const edge of changes.removedEdges) lines.push(formatEdge(edge));
+  }
+  return lines;
+}
+
+/**
+ * Classifies one transition into the short "kind" a reader skims for.
+ *
+ * @param {{architectureChanged: boolean, codeDrift: boolean, policyChanged: boolean|null,
+ *   providerChanged: boolean}} transition
+ * @returns {string}
+ */
+export function transitionKind(transition) {
+  if (transition.architectureChanged) return "architecture";
+  if (transition.providerChanged) return "provider";
+  if (transition.policyChanged === true) return "policy";
+  if (transition.codeDrift) return "code drift";
+  return "unchanged";
+}

package/src/report/trajectory-text.mjs

@@ -0,0 +1,143 @@
+/**
+ * The terminal report for the `trajectory` command: the aggregate signals
+ * across a snapshot history, with what each number is a claim about.
+ *
+ * Every line states counts, never judgments — the report has no "better", no
+ * score, no direction adjective. The header names the observation basis (one
+ * observation is one stored graph snapshot, not a commit or a day), an
+ * insufficient history says so instead of printing zeros, and the disclosures
+ * line prints even when every count is zero, so a reader can tell "nothing
+ * was incomparable" from "the report forgot to say".
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences before anything reaches
+ * the terminal (`SECURITY.md`) — the same sanitation every other renderer
+ * applies. Only paths and snapshot filenames are printed here; project and
+ * edge identities stay aggregated precisely so nothing name-shaped needs to.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function sanitize(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
+    if (c === "\n") return "\\n";
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+
+/**
+ * A delta with its sign, so +2 / -1 / 0 read as movement rather as bare
+ * magnitudes. Zero prints unsigned — it is the absence of movement, not a
+ * positive one.
+ *
+ * @param {number|null} value
+ * @returns {string}
+ */
+function signed(value) {
+  if (value === null) return "n/a";
+  if (value > 0) return `+${value}`;
+  return `${value}`;
+}
+
+/**
+ * A count that is either established or explicitly unavailable. `null`
+ * renders as `n/a` beside the reason the header already stated — never as a
+ * zero that would claim a measurement.
+ *
+ * @param {number|null} value
+ * @returns {string}
+ */
+function counted(value) {
+  return value === null ? "n/a" : `${value}`;
+}
+
+/**
+ * One structural axis as one line: endpoints, then events, then persistence.
+ *
+ * @param {{first: number, current: number, delta: number|null,
+ *   addedEvents: number|null, removedEvents: number|null,
+ *   changedEvents: number|null, introduced: number|null, resolved: number|null,
+ *   persistent: number|null}} axis
+ * @param {boolean} withChanged Whether the axis carries a changed-event count
+ *   (projects do; edges do not — a type flip is remove+add under the triple
+ *   identity).
+ * @returns {string}
+ */
+function formatAxis(axis, withChanged) {
+  const parts = [
+    `first ${axis.first}`,
+    `current ${axis.current}`,
+    `delta ${signed(axis.delta)}`,
+    `added ${counted(axis.addedEvents)}`,
+    `removed ${counted(axis.removedEvents)}`,
+  ];
+  if (withChanged) parts.push(`changed ${counted(axis.changedEvents)}`);
+  parts.push(
+    `introduced ${counted(axis.introduced)}`,
+    `resolved ${counted(axis.resolved)}`,
+    `persistent ${counted(axis.persistent)}`,
+  );
+  return parts.join(" · ");
+}
+
+/**
+ * The whole trajectory report.
+ *
+ * @param {{trajectory: {dir: string, observations: {count: number, basis: string,
+ *   first: string|null, last: string|null, withProvenance: number,
+ *   dirtyProvenance: number}, available: boolean, unavailableReason: string|null,
+ *   transitions: {count: number, architecture: number, policy: number,
+ *     provider: number, codeDrift: number, incomparable: number, unchanged: number},
+ *   disclosures: {policyOneSided: number, provenanceOneSided: number, crossRepo: number},
+ *   projects: object, edges: object}, coverage: object}} input
+ * @returns {string}
+ */
+export function formatTrajectoryReport({ trajectory, coverage }) {
+  const sections = [];
+
+  const observations = trajectory.observations;
+  sections.push(`trajectory  ${trajectory.dir}`);
+  sections.push(
+    `${observations.count} observation${observations.count === 1 ? "" : "s"} ` +
+      `(${observations.basis}), ${trajectory.transitions.count} transition${
+        trajectory.transitions.count === 1 ? "" : "s"
+      }`,
+  );
+
+  if (!trajectory.available) {
+    // Named, not implied: a one-snapshot history cannot show movement, and
+    // every derived number below stays n/a rather than reading as a zero.
+    sections.push(
+      `✖ ${trajectory.unavailableReason}: a trajectory needs at least two observations — ` +
+        "derived values are unavailable, not zero",
+    );
+  }
+
+  const t = trajectory.transitions;
+  sections.push(
+    `signals  architecture ${t.architecture} · policy ${t.policy} · provider ${t.provider} · ` +
+      `code drift ${t.codeDrift} · incomparable ${t.incomparable} · unchanged ${t.unchanged}`,
+  );
+  sections.push(`projects  ${formatAxis(trajectory.projects, true)}`);
+  sections.push(`edges     ${formatAxis(trajectory.edges, false)}`);
+
+  const d = trajectory.disclosures;
+  sections.push(
+    `disclosures  policy incomparable ${d.policyOneSided} · provenance incomparable ` +
+      `${d.provenanceOneSided} · cross-repo ${d.crossRepo} · ` +
+      `dirty captures ${observations.dirtyProvenance} · with provenance ${observations.withProvenance}`,
+  );
+
+  for (const note of coverage.notes) {
+    sections.push(sanitize(note));
+  }
+
+  return sections.join("\n");
+}

package/src/rules/index.mjs

@@ -176,13 +176,18 @@ const isProjectGraphProjectNode = (node) =>
  */
 function spellingOf(site) {
   const spelling = site.spelling;
-  if (typeof spelling?.path !== "boolean" || typeof spelling?.relative !== "boolean") {
+  if (
+    typeof spelling?.path !== "boolean" ||
+    typeof spelling?.relative !== "boolean" ||
+    typeof spelling?.namesOnly !== "boolean"
+  ) {
     throw new Error(
       `archkeep: ${site.sourceFile}:${site.line}:${site.column} imports ` +
         `'${site.specifier}' in a record carrying no \`spelling\` — the analysis contract ` +
-        `requires \`{ path, relative }\` on every import site, because whether a specifier ` +
-        `is a path and whether it stays inside its own project are per-language questions ` +
-        `only the analyzer can answer. See src/analysis/contract.md.`,
+        `requires \`{ path, relative, namesOnly }\` on every import site, because whether a ` +
+        `specifier is a path, whether it stays inside its own project, and whether its ` +
+        `language has any path spelling at all are per-language questions only the analyzer ` +
+        `can answer. See src/analysis/contract.md.`,
     );
   }
   return spelling;
@@ -585,8 +590,18 @@ function* candidateGroupsFor(site, ctx) {
   if (!sourceProject) return;
 
   // Relative and absolute paths are judged on their TEXT, before any resolution:
-  // the projects can be correct and the spelling still be the violation.
-  const absoluteIntoAnotherProject = isAbsoluteImportIntoAnotherProject(imp, ctx.workspaceLayout);
+  // the projects can be correct and the spelling still be the violation. The
+  // absolute half is a JavaScript-family convention — a bare `libs/x` deep
+  // import, a `/libs/x` absolute path — so it stands down entirely where the
+  // analyzer declared the language has no path spelling at all
+  // (`spelling.namesOnly`): a Go module path or a C# namespace beginning
+  // `libs/` is a name, and the name is the only spelling the language has
+  // (#376). The edge such an import resolves to is still judged by every check
+  // below — only this spelling check stands down, so gating it too broadly
+  // (on `spelling.path`, which is false for the bare JS form too) would trade
+  // this loud bug for a silent one against ESLint.
+  const absoluteIntoAnotherProject =
+    !spellingOf(site).namesOnly && isAbsoluteImportIntoAnotherProject(imp, ctx.workspaceLayout);
   let targetProject = absoluteIntoAnotherProject
     ? graph.nodes[findProjectForPath(imp, mappings)]
     : graph.nodes[getTargetProjectBasedOnRelativeImport(imp, site.sourceFile, mappings)];

package/src/rules/reachability.mjs

@@ -140,6 +140,8 @@ export function getPath(reach, graph, sourceProjectName, targetProjectName) {
     if (current === targetProjectName) break;
     if (!adjList[current]) break;
     adjList[current]
+      .slice()
+      .sort()
       .filter((adj) => visited.indexOf(adj) === -1)
       .filter((adj) => matrix[adj]?.[targetProjectName])
       .forEach((adj) => {

package/src/rules/tags.mjs

@@ -165,11 +165,13 @@ 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) {
-  const reachable = Object.keys(graph.nodes).filter(
-    (projectName) =>
-      pathExists(reach, targetProject.name, projectName) &&
-      tags.some((tag) => hasTag(graph.nodes[projectName], tag)),
-  );
+  const reachable = Object.keys(graph.nodes)
+    .sort()
+    .filter(
+      (projectName) =>
+        pathExists(reach, targetProject.name, projectName) &&
+        tags.some((tag) => hasTag(graph.nodes[projectName], tag)),
+    );
   return reachable.map((project) =>
     targetProject.name === project
       ? [targetProject]

package/src/rules/topology.mjs

@@ -254,13 +254,15 @@ export function circularViolation({
       targetProjectName: targetProject.name,
       path: circularPath.reduce((acc, v) => `${acc} -> ${v.name}`, sourceProject.name),
       filePaths: circularFilePath
+        .map((files) => files.filter((f) => typeof f === "string"))
         .map((files) =>
           files.length > 1
             ? `[${files.map((f) => `\n${spacer}${spacer}${f}`).join(",")}\n${spacer}]`
             : // Upstream indexes `files[0]` unguarded, printing `undefined` for a
-              // hop with no file to blame. Ours can legitimately have none, since
-              // the index only knows the files it was handed.
-              (files[0] ?? ""),
+              // hop with no file to blame. Ours can legitimately have none —
+              // a manifest-declared edge carries no import site — and a blank
+              // bullet names nothing, so the hop says what it is instead.
+              (files[0] ?? "(no source file — a manifest declares this dependency)"),
         )
         .reduce((acc, files) => `${acc}\n- ${files}`, `- ${sourceFile}`),
     },

package/src/tsconfig-paths.mjs

@@ -77,6 +77,7 @@
  * says (`tsconfigPathsFacts` there).
  */
 import { posix } from "node:path";
+import { stripTrailingSlashes } from "./path-util.mjs";
 
 /**
  * What a hygiene finding means — one entry per `messageId`, the arrangement
@@ -116,7 +117,7 @@ function probeDirectory(target, base, root) {
   // candidates live in its parent.
   const dir =
     prefix === "" || prefix.endsWith("/")
-      ? joined.replace(/\/+$/u, "") || "/"
+      ? stripTrailingSlashes(joined) || "/"
       : posix.dirname(joined);
   if (dir === root) return "";
   return dir.startsWith(`${root}/`) ? dir.slice(root.length + 1) : null;
@@ -144,7 +145,7 @@ function probeDirectory(target, base, root) {
  *   verdict; `malformed` is for `../cli.mjs` to refuse loudly, never to skip.
  */
 export function judgeTsconfigPaths({ paths, base, workspaceRoot, tsConfig, directoryExists }) {
-  const root = workspaceRoot.replace(/\/+$/u, "");
+  const root = stripTrailingSlashes(workspaceRoot);
   const findings = [];
   const malformed = [];
   let aliases = 0;