@ecoma-io/archkeep 0.14.0 → 0.15.0

package/src/report/delta-text.mjs

@@ -6,7 +6,10 @@
  * Sections render only when they have content — introduced (with waived
  * annotations), resolved, unchanged (with the occurrences-reduced note where
  * one applies), unknown (with the reason each identity could not be stated),
- * and the unresolvable-import block — and the summary line always states what
+ * the unresolvable-import block, and the custom-rules block (only when the
+ * delta computed one — `../commands/delta.mjs` keeps it absent for a
+ * workspace where neither side declares custom rules) — and the summary line
+ * always states what
  * was compared: base and head identity, record and project counts, and the
  * bucket totals. "No introduced violations" is a claim about a comparison the
  * reader can verify, never silence (`../../../../AGENTS.md`).
@@ -59,6 +62,71 @@ function unknownLines(entry) {
   return [`  ? ${entry.reason}`];
 }
 
+/** One classified custom-finding entry as its report lines. */
+function customFindingLines(entry) {
+  const where = entry.project === null ? "" : `  in ${entry.project}`;
+  const counts = `${entry.baseCount} at base, ${entry.headCount} at head`;
+  const lines = [`  ${entry.ruleId}${where}  (${counts})`];
+  if (entry.message !== undefined) lines.push(`    ${entry.message}`);
+  if (entry.note !== undefined) lines.push(`    ${entry.note}`);
+  const sites = entry.headSites.length > 0 ? entry.headSites : entry.baseSites;
+  for (const site of sites) {
+    // A custom finding states a position only when its rule stated one — a
+    // whole-workspace finding has no file, and no line is printed for it.
+    if (site.file !== undefined) lines.push(`    at ${site.file}:${site.line}:${site.column}`);
+  }
+  return lines;
+}
+
+/** One unknown custom entry — the rule name plus the mandatory reason. */
+function customUnknownLines(entry) {
+  return [`  ? ${entry.rule}: ${entry.reason}`];
+}
+
+/**
+ * The custom-rules block, rendered only when the delta computed one — a
+ * workspace where neither side declares custom rules keeps the exact report
+ * it already had.
+ *
+ * @param {{judged: object[], skipped: object[], removed: string[],
+ *   findings: object}} customRules
+ * @param {{customFindings: {introduced: number, resolved: number,
+ *   unchanged: number, unknown: number}}} summary
+ * @returns {string[]}
+ */
+function customRulesSections(customRules, summary) {
+  const { judged, skipped, removed, findings } = customRules;
+  const counts = summary.customFindings;
+  const lines = [
+    `custom rules (${judged.length} judged, ${skipped.length} skipped, ${removed.length} removed)`,
+  ];
+  lines.push(
+    ...section(
+      `  ⚠ ${counts.introduced} introduced custom finding${counts.introduced === 1 ? "" : "s"}`,
+      findings.introduced.map(customFindingLines),
+    ),
+  );
+  lines.push(
+    ...section(
+      `  ✔ ${counts.resolved} resolved custom finding${counts.resolved === 1 ? "" : "s"}`,
+      findings.resolved.map(customFindingLines),
+    ),
+  );
+  lines.push(
+    ...section(
+      `  = ${counts.unchanged} unchanged custom finding${counts.unchanged === 1 ? "" : "s"}`,
+      findings.unchanged.map(customFindingLines),
+    ),
+  );
+  lines.push(
+    ...section(
+      `  ? ${counts.unknown} unclassifiable custom item${counts.unknown === 1 ? "" : "s"}`,
+      findings.unknown.map(customUnknownLines),
+    ),
+  );
+  return lines;
+}
+
 /**
  * One classification bucket as a section, or nothing when it is empty.
  *
@@ -162,6 +230,10 @@ export function formatDeltaReport({ delta, coverage }) {
     );
   }
 
+  if (delta.customRules !== undefined) {
+    sections.push(...customRulesSections(delta.customRules, summary));
+  }
+
   // The closing claim always states what was compared, so an empty delta is a
   // verifiable statement rather than silence.
   const compared =
@@ -178,6 +250,15 @@ export function formatDeltaReport({ delta, coverage }) {
         `waived — ${compared}`,
     );
   }
+  // The custom gate's own closing claim, so a delta whose only introduction is
+  // a custom finding does not end on a line reading clean.
+  if (delta.customRules !== undefined && summary.customFindings.introduced > 0) {
+    const count = summary.customFindings.introduced;
+    sections.push(
+      `⚠ ${count} introduced custom finding${count === 1 ? "" : "s"} — custom findings have ` +
+        `no waiver lane, every one gates`,
+    );
+  }
 
   return sections.join("\n");
 }

package/src/report/evolution-text.mjs

@@ -0,0 +1,83 @@
+/**
+ * The terminal report for the `evolution` command: the selected revisions in
+ * history order, each transition classified, and what the whole record can
+ * and cannot say.
+ *
+ * Like `history-text.mjs`, counts end every section so a reader never decides
+ * whether an omission is content or silence — and the summary line names the
+ * range the record is a claim ABOUT, because "how the architecture evolved"
+ * without naming the compared revisions is not a reproducible claim.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`); the transition formatters are
+ * shared with `history-text.mjs` (`./snapshot-text.mjs`) so both commands
+ * render one classification the same way.
+ */
+
+import { formatChanges, sanitize, transitionKind } from "./snapshot-text.mjs";
+
+/**
+ * The whole evolution report.
+ *
+ * @param {{result: {base: string, head: string,
+ *   revisions: {commit: string, id: string}[],
+ *   transitions: {from: string, to: string, architectureChanged: boolean,
+ *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
+ *     codeDrift: boolean, notes: string[]}[]}, coverage: object}} input
+ * @returns {string}
+ */
+export function formatEvolutionReport({ result, coverage }) {
+  const sections = [];
+
+  const transitionWord = result.transitions.length === 1 ? "transition" : "transitions";
+  const revisionWord = result.revisions.length === 1 ? "revision" : "revisions";
+  const inspected = `${coverage.imports} import${
+    coverage.imports === 1 ? "" : "s"
+  } in ${coverage.analyzedFiles} file${
+    coverage.analyzedFiles === 1 ? "" : "s"
+  } across ${coverage.projects} project${coverage.projects === 1 ? "" : "s"}`;
+
+  sections.push(
+    `evolution  ${sanitize(result.base.slice(0, 12))}..${sanitize(result.head.slice(0, 12))}`,
+  );
+  sections.push(
+    `${result.revisions.length} ${revisionWord}, ${result.transitions.length} ${transitionWord} (${inspected})`,
+  );
+
+  for (const [i, revision] of result.revisions.entries()) {
+    sections.push(`${i}  ${sanitize(revision.commit)}  ${revision.id.slice(0, 8)}`);
+  }
+
+  // The footer counts true architectural change only — the same discipline as
+  // `history-text.mjs`: a policy or provider transition is a change to how the
+  // record reads, not to the architecture itself.
+  let changed = 0;
+  for (const transition of result.transitions) {
+    if (transition.architectureChanged) changed += 1;
+    const kind = transitionKind(transition);
+    sections.push(`~ ${sanitize(transition.from)} → ${sanitize(transition.to)}  (${kind})`);
+    if (transition.changes) {
+      for (const line of formatChanges(transition.changes)) sections.push(`  ${line}`);
+    }
+    for (const note of transition.notes) {
+      sections.push(`  ${note}`);
+    }
+  }
+
+  if (changed === 0) {
+    const anySignal = result.transitions.some(
+      (t) => t.policyChanged === true || t.providerChanged || t.codeDrift,
+    );
+    sections.push(
+      anySignal
+        ? "✔ no architectural change across the selected revisions (only policy, provider, or drift signals)"
+        : "✔ no change at all across the selected revisions",
+    );
+  } else {
+    sections.push(
+      `${changed} transition${changed === 1 ? "" : "s"} recorded an architectural change`,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/report/history-text.mjs

@@ -7,122 +7,12 @@
  * actually holds. Counts end every section, so a reader is never left deciding
  * whether an omission is content or silence.
  *
- * This module decides nothing. A formatter that filtered would be a rule
- * wearing a formatter's name (`../README.md`).
+ * The per-transition formatters live in `./snapshot-text.mjs`, beside the
+ * ones `evolution-text.mjs` renders from — one home for the way a transition
+ * becomes prose, so the two commands cannot disagree about it.
  */
 
-/**
- * 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}
- */
-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}
- */
-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}
- */
-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}
- */
-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[]}
- */
-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}
- */
-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";
-}
+import { formatChanges, transitionKind } from "./snapshot-text.mjs";
 
 /**
  * The whole history report.

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.