@ecoma-io/archkeep 0.14.0 → 0.16.0

package/src/commands/delta-classify.mjs

@@ -66,6 +66,7 @@ import { canonicalizeJson } from "../canonical.mjs";
 import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import { suppressionFate } from "../governance/waiver.mjs";
+import { namespacedId } from "./custom-rules.mjs";
 
 /**
  * Computes a violation's architectural identity.
@@ -190,23 +191,7 @@ export function classifyViolations({ base, head, suppressions = [], now = refere
       headSites: headGroup ? headGroup.sites : [],
     };
 
-    if (baseCount === 0) {
-      entry.classification = "introduced";
-      entry.reason = "absent at base";
-    } else if (headCount === 0) {
-      entry.classification = "resolved";
-    } else if (headCount > baseCount) {
-      entry.classification = "introduced";
-      entry.reason = `occurrence growth: ${baseCount} at base, ${headCount} at head`;
-    } else if (headCount < baseCount) {
-      // Still present at head — a shrink is NEVER a resolution.
-      entry.classification = "unchanged";
-      entry.note =
-        `occurrencesReduced: ${baseCount} at base, ${headCount} at head — the violation ` +
-        `still exists`;
-    } else {
-      entry.classification = "unchanged";
-    }
+    Object.assign(entry, occurrenceClassification(baseCount, headCount, "the violation"));
 
     // A resolved item has no head occurrence left; its waive status is judged
     // against the LAST places the violation existed (its base sites) — what
@@ -296,22 +281,7 @@ export function classifyUnresolvableRecords({ base, head, sourceProjectOf }) {
       headSites: headGroup ? headGroup.sites : [],
     };
 
-    if (baseCount === 0) {
-      entry.classification = "introduced";
-      entry.reason = "absent at base";
-    } else if (headCount === 0) {
-      entry.classification = "resolved";
-    } else if (headCount > baseCount) {
-      entry.classification = "introduced";
-      entry.reason = `occurrence growth: ${baseCount} at base, ${headCount} at head`;
-    } else if (headCount < baseCount) {
-      entry.classification = "unchanged";
-      entry.note =
-        `occurrencesReduced: ${baseCount} at base, ${headCount} at head — the site still ` +
-        `exists`;
-    } else {
-      entry.classification = "unchanged";
-    }
+    Object.assign(entry, occurrenceClassification(baseCount, headCount, "the site"));
 
     bucketFor(entry.classification, { introduced, resolved, unchanged }).push(entry);
   }
@@ -319,6 +289,165 @@ export function classifyUnresolvableRecords({ base, head, sourceProjectOf }) {
   return { introduced, resolved, unchanged, unknown };
 }
 
+/**
+ * Computes a custom finding's identity, or the reason it has none.
+ *
+ * The key is `["custom", ruleName, findingId, project ?? null]`: which rule,
+ * which of its declared findings, against which project — the architectural
+ * facts a rule states about a finding. `sourceFile`/`line`/`column` are
+ * attached evidence exactly as a violation's sites are, never identity, and a
+ * finding that names no project keys on `null` rather than being dropped. A
+ * finding with no usable id has nothing to identify it by and is never
+ * guessed into a bucket — the same refusal `violationIdentity` makes for a
+ * violation with no messageId.
+ *
+ * @param {string} ruleName The judged rule's declared name.
+ * @param {unknown} finding One finding from a rule's verdict document.
+ * @returns {{ok: true, key: string, identity: object, site: object}
+ *   |{ok: false, reason: string, finding: unknown}}
+ */
+function customFindingIdentity(ruleName, finding) {
+  if (finding === null || typeof finding !== "object" || Array.isArray(finding)) {
+    return {
+      ok: false,
+      reason: `custom rule "${ruleName}" reported a finding that is ${describe(finding)}, not an object`,
+      finding,
+    };
+  }
+  const { id, project } = /** @type {Record<string, unknown>} */ (finding);
+  if (typeof id !== "string" || id === "") {
+    return {
+      ok: false,
+      reason:
+        `custom rule "${ruleName}" reported a finding with no usable id — got ${describe(id)}, ` +
+        `and a finding that cannot be named cannot be matched across the two sides`,
+      finding,
+    };
+  }
+  const projectName = typeof project === "string" && project !== "" ? project : null;
+  const record = /** @type {Record<string, unknown>} */ (finding);
+  return {
+    ok: true,
+    key: JSON.stringify(["custom", ruleName, id, projectName]),
+    identity: {
+      rule: ruleName,
+      findingId: id,
+      ruleId: namespacedId(ruleName, id),
+      project: projectName,
+      message: record.message,
+    },
+    site: { file: record.sourceFile, line: record.line, column: record.column },
+  };
+}
+
+/**
+ * Classifies the custom-rule findings of a two-sided judgment
+ * (`./custom-rules.mjs`'s `customRulesForDelta`).
+ *
+ * Same identity discipline, same occurrence ladder, same fail-closed unknowns
+ * as the two classifiers above — with one deliberate absence: there is NO
+ * `waived` annotation. Suppressions key on a `messageId`
+ * (`../config.mjs`'s `suppressionCovers`), and a custom finding has none — its
+ * id lives in the `custom/<rule>/<finding>` namespace no suppression row can
+ * name — so by construction every introduced custom finding gates. Every rule
+ * in `unknownRules` becomes one `unknown` entry carrying the rule's reason:
+ * a rule that could not be judged is a question this delta could not answer,
+ * never a silently thinner report.
+ *
+ * @param {object} input
+ * @param {{name: string, baseFindings: object[], headFindings: object[]}[]}
+ *   input.judged Rules evaluated on both sides.
+ * @param {{name: string, reason: string}[]} [input.unknownRules] Rules that
+ *   could not be judged, each with its mandatory reason.
+ * @returns {{introduced: object[], resolved: object[], unchanged: object[],
+ *   unknown: object[]}} Classified entries carry `rule`, `findingId`,
+ *   `ruleId`, `project`, `message`, both sides' counts and sites, and the
+ *   ladder's optional `reason`/`note`. When a rule produced at least one
+ *   no-id finding on either side, every classified entry of that rule also
+ *   carries (or extends) a `note` saying its classification may be incomplete
+ *   — the no-id finding fell out of the grouping, so a counterpart it should
+ *   have matched reads introduced or resolved. Unknown entries are
+ *   `{classification, rule, reason}` plus the offending `finding` where one
+ *   exists.
+ */
+export function classifyCustomFindings({ judged, unknownRules = [] }) {
+  const introduced = [];
+  const resolved = [];
+  const unchanged = [];
+  const unknown = [];
+
+  for (const rule of unknownRules) {
+    unknown.push({ classification: "unknown", rule: rule.name, reason: rule.reason });
+  }
+
+  for (const rule of judged) {
+    const baseIdentified = rule.baseFindings.map((finding) =>
+      customFindingIdentity(rule.name, finding),
+    );
+    const headIdentified = rule.headFindings.map((finding) =>
+      customFindingIdentity(rule.name, finding),
+    );
+    let namelessCount = 0;
+    for (const identified of baseIdentified.concat(headIdentified)) {
+      // The same non-strict narrowing constraint as `classifyViolations`' loop.
+      if (identified.ok === false) {
+        namelessCount += 1;
+        unknown.push({
+          classification: "unknown",
+          rule: rule.name,
+          reason: identified.reason,
+          finding: identified.finding,
+        });
+      }
+    }
+    // A no-id finding fell out of the grouping below, so its identical
+    // counterpart on the other side — if one exists — reads introduced or
+    // resolved with nothing to match against. The unknown entries above keep
+    // the run loud (exit 3); this note keeps the CLASSIFIED entries honest,
+    // because a reader acting on this rule's buckets is acting on a grouping
+    // that may be missing occurrences.
+    const incompleteNote =
+      namelessCount === 0
+        ? null
+        : `classification for this rule may be incomplete: ${namelessCount} finding` +
+          `${namelessCount === 1 ? "" : "s"} had no usable id and could not be matched ` +
+          `across the two sides`;
+
+    const baseGroups = groupBy(baseIdentified);
+    const headGroups = groupBy(headIdentified);
+    const keys = [...new Set([...baseGroups.keys(), ...headGroups.keys()])].sort(cmpString);
+    for (const key of keys) {
+      const baseGroup = baseGroups.get(key);
+      const headGroup = headGroups.get(key);
+      const baseCount = baseGroup ? baseGroup.sites.length : 0;
+      const headCount = headGroup ? headGroup.sites.length : 0;
+      const identity = (baseGroup ?? headGroup).identity;
+
+      /** @type {Record<string, unknown>} */
+      const entry = {
+        classification: "",
+        rule: identity.rule,
+        findingId: identity.findingId,
+        ruleId: identity.ruleId,
+        project: identity.project,
+        message: identity.message,
+        baseCount,
+        headCount,
+        baseSites: baseGroup ? baseGroup.sites : [],
+        headSites: headGroup ? headGroup.sites : [],
+      };
+      Object.assign(entry, occurrenceClassification(baseCount, headCount, "the finding"));
+      if (incompleteNote !== null) {
+        entry.note =
+          typeof entry.note === "string" ? `${entry.note}; ${incompleteNote}` : incompleteNote;
+      }
+      bucketFor(entry.classification, { introduced, resolved, unchanged }).push(entry);
+    }
+  }
+
+  return { introduced, resolved, unchanged, unknown };
+}
+
 /**
  * Runs both classifications over one pair of evidence sets: the raw violations
  * and the unresolvable-site records, each into its own category.
@@ -428,6 +557,39 @@ function isUnresolvable(record) {
   );
 }
 
+/**
+ * The occurrence-count ladder every classifier above shares — one statement of
+ * the header's per-identity rules, so the three cannot drift on the one
+ * decision most likely to be re-litigated (a shrink is NEVER a resolution).
+ *
+ * @param {number} baseCount
+ * @param {number} headCount
+ * @param {string} subject What still exists on a shrink, for the note — "the
+ *   violation", "the site", "the finding".
+ * @returns {{classification: "introduced"|"resolved"|"unchanged",
+ *   reason?: string, note?: string}}
+ */
+function occurrenceClassification(baseCount, headCount, subject) {
+  if (baseCount === 0) return { classification: "introduced", reason: "absent at base" };
+  if (headCount === 0) return { classification: "resolved" };
+  if (headCount > baseCount) {
+    return {
+      classification: "introduced",
+      reason: `occurrence growth: ${baseCount} at base, ${headCount} at head`,
+    };
+  }
+  if (headCount < baseCount) {
+    // Still present at head — a shrink is NEVER a resolution.
+    return {
+      classification: "unchanged",
+      note:
+        `occurrencesReduced: ${baseCount} at base, ${headCount} at head — ${subject} still ` +
+        `exists`,
+    };
+  }
+  return { classification: "unchanged" };
+}
+
 /**
  * Folds identified items into groups keyed by identity: occurrences become a
  * multiset of sites, so duplicate import sites in one file count twice.

package/src/commands/delta-snapshot.mjs

@@ -19,6 +19,23 @@
  * this file is read back by `parseEvidenceSnapshot` alone, never by the report
  * renderers, and the two formats will evolve on different clocks.
  *
+ * ## The two OPTIONAL blocks, and why the version stays 1
+ *
+ * `customRules` (the declared rows: name, artifact, sha256, params) and
+ * `owned` (the workspace's file→project ownership map) are stored only when
+ * the capturing policy declares `customRules` — a workspace that declares
+ * none produces byte-identical snapshots before and after this addition, and
+ * a reader of version 1 that predates the blocks ignores keys it never asks
+ * for. Both are evidence in the same sense the records are: the rows are what
+ * lets a compare run say whether the custom LAW moved between capture and
+ * head (digest or params drift), and `owned` is what lets the base-side
+ * evidence bundle attribute each stored record — ownership is the workspace
+ * layer's answer (`../workspace.mjs`) and cannot be re-derived from a graph
+ * that may have changed since. A baseline WITHOUT the blocks is still legal
+ * (an old capture, or one whose policy declared no rules); downstream every
+ * custom finding then classifies `unknown` with a re-capture reason rather
+ * than the blocks' absence reading as "no custom rules existed at base".
+ *
  * ## Purity seam
  *
  * Everything decidable is pure: `buildEvidenceSnapshot` takes already-resolved
@@ -72,6 +89,14 @@ export const EVIDENCE_SNAPSHOT_SCHEMA_VERSION = 1;
  * @param {object[]} input.records The raw import-site records — the analysis
  *   envelope's `imports` array verbatim (`../analysis/contract.md`), including
  *   the `resolved: null` rows.
+ * @param {{name: string, artifact: string, sha256: string,
+ *   params?: Record<string, any>}[]} [input.customRules] The declared
+ *   custom-rule rows, when the capturing policy declares any — see the header's
+ *   optional-blocks section. Omitted means "the capturing policy declared no
+ *   custom rules", and the snapshot carries no key at all.
+ * @param {{file: string, project: string}[]} [input.owned] The ownership map,
+ *   required exactly when `customRules` is given: the base-side evidence
+ *   bundle cannot attribute a record without it. Stored sorted by file.
  * @returns {object} The snapshot, ready for `serializeEvidenceSnapshot`.
  * @throws {Error} naming the first piece of required structure that is missing
  *   or malformed — a snapshot built over half-specified evidence would fail
@@ -85,6 +110,8 @@ export function buildEvidenceSnapshot({
   coverage,
   graph,
   records,
+  customRules,
+  owned,
 }) {
   if (!tool || typeof tool.name !== "string" || tool.name === "") {
     throw new Error(
@@ -147,6 +174,22 @@ export function buildEvidenceSnapshot({
     }
   }
 
+  if (customRules !== undefined) {
+    const customProblems = describeCustomRuleBlockProblems(customRules, owned);
+    if (customProblems.length > 0) {
+      throw new Error(
+        "archkeep: cannot build an evidence snapshot — the custom-rule evidence is malformed:\n  " +
+          customProblems.join("\n  "),
+      );
+    }
+  } else if (owned !== undefined) {
+    throw new Error(
+      "archkeep: cannot build an evidence snapshot with an `owned` map but no `customRules` " +
+        "rows — the map exists to attribute the base side of a custom-rule re-judgment, and " +
+        "storing it alone would claim custom-rule evidence the snapshot does not hold",
+    );
+  }
+
   const projects = buildProjects(graph.nodes).map((project) => {
     // Re-attach the three rule-relevant fields `buildProjects` strips for the
     // public graph contract. Each is attached only when the node DECLARES it —
@@ -179,7 +222,8 @@ export function buildEvidenceSnapshot({
     storedGraph.exemptedFiles = graph.exemptedFiles.slice().sort(cmpString);
   }
 
-  return {
+  /** @type {Record<string, unknown>} */
+  const snapshot = {
     schemaVersion: EVIDENCE_SNAPSHOT_SCHEMA_VERSION,
     tool: { name: tool.name, version: tool.version },
     provider,
@@ -194,6 +238,25 @@ export function buildEvidenceSnapshot({
     graph: storedGraph,
     records,
   };
+  if (customRules !== undefined) {
+    // The declared rows, each reduced to the four fields a compare run reads:
+    // identity (name), the pinned law (artifact + sha256), and the parameters
+    // that ride inside the evidence bundle — params drift is law drift, the
+    // same as digest drift. `reason` and the governance block stay out: they
+    // explain the row to a human and change no judgment.
+    snapshot.customRules = customRules.map((row) => ({
+      name: row.name,
+      artifact: row.artifact,
+      sha256: row.sha256,
+      ...(row.params === undefined ? {} : { params: row.params }),
+    }));
+    // Sorted by file for byte-determinism; `createWorkspace` derives the map
+    // from a Set walk whose order is an accident of the file listing.
+    snapshot.owned = /** @type {{file: string, project: string}[]} */ (owned)
+      .map(({ file, project }) => ({ file, project }))
+      .sort((a, b) => cmpString(a.file, b.file));
+  }
+  return snapshot;
 }
 
 /**
@@ -400,6 +463,18 @@ export function parseEvidenceSnapshot(text, path) {
     });
   }
 
+  // The optional custom-rule pair: absence is a legal old-or-undeclared
+  // baseline, presence must be sound — a half-readable block consumed
+  // silently would attribute base records against a map that is not one.
+  if (parsed.customRules !== undefined) {
+    problems.push(...describeCustomRuleBlockProblems(parsed.customRules, parsed.owned));
+  } else if (parsed.owned !== undefined) {
+    problems.push(
+      "owned: present without customRules — the map only exists as custom-rule evidence, and " +
+        "half the pair is a snapshot no release ever wrote",
+    );
+  }
+
   if (problems.length > 0) {
     throw new Error(
       `archkeep: the evidence snapshot '${path}' is not a usable baseline:\n  ` +
@@ -487,6 +562,86 @@ function describeCoverageProblems(coverage) {
   return problems;
 }
 
+/**
+ * Everything wrong with the optional custom-rule evidence pair, as messages —
+ * shared by capture-time construction and load-time parsing for the same
+ * reason `describeCoverageProblems` is: one statement of what the blocks are.
+ *
+ * Called only when `customRules` is PRESENT: absence is legal (an old
+ * baseline, or a policy that declares none) and is judged by the caller. When
+ * the rows are present the `owned` map must be too — a base-side re-judgment
+ * without attribution would hand every rule evidence it must refuse, and the
+ * time to say so is when the snapshot is built or read, not per rule at
+ * compare time.
+ *
+ * @param {unknown} customRules The stored (or to-be-stored) rule rows.
+ * @param {unknown} owned The stored (or to-be-stored) ownership map.
+ * @returns {string[]} One entry per problem, empty when both are sound.
+ */
+function describeCustomRuleBlockProblems(customRules, owned) {
+  const problems = [];
+  if (!Array.isArray(customRules)) {
+    problems.push(
+      `customRules: must be an array of declared rule rows when present, got ` +
+        `${describe(customRules)}`,
+    );
+  } else {
+    /** @type {Map<string, number>} */
+    const firstIndexOfName = new Map();
+    customRules.forEach((row, index) => {
+      if (!isPlainObject(row)) {
+        problems.push(`customRules[${index}]: must be an object, got ${describe(row)}`);
+        return;
+      }
+      for (const field of ["name", "artifact", "sha256"]) {
+        if (typeof row[field] !== "string" || row[field] === "") {
+          problems.push(`customRules[${index}].${field}: must be a non-empty string`);
+        }
+      }
+      // A duplicate name is a loud refusal, not a last-one-wins: the compare
+      // side keys stored rows by name (`./custom-rules.mjs`'s
+      // `customRulesForDelta` builds a Map over them), so a second row under
+      // one name would silently shadow the first — and which law the delta
+      // then matched against would be an accident of row order.
+      if (typeof row.name === "string" && row.name !== "") {
+        const first = firstIndexOfName.get(row.name);
+        if (first !== undefined) {
+          problems.push(
+            `customRules[${index}].name: duplicates customRules[${first}].name ("${row.name}") — ` +
+              `rule names are the identity a delta matches base rows by, and two rows under one ` +
+              `name would silently shadow each other`,
+          );
+        } else {
+          firstIndexOfName.set(row.name, index);
+        }
+      }
+      if (row.params !== undefined && !isPlainObject(row.params)) {
+        problems.push(`customRules[${index}].params: must be a plain object when present`);
+      }
+    });
+  }
+  if (!Array.isArray(owned)) {
+    problems.push(
+      `owned: must be an array of {file, project} rows whenever customRules is stored — the ` +
+        `base side of a custom-rule re-judgment cannot attribute a record without it, got ` +
+        `${describe(owned)}`,
+    );
+  } else {
+    owned.forEach((row, index) => {
+      if (!isPlainObject(row)) {
+        problems.push(`owned[${index}]: must be an object, got ${describe(row)}`);
+        return;
+      }
+      for (const field of ["file", "project"]) {
+        if (typeof row[field] !== "string" || row[field] === "") {
+          problems.push(`owned[${index}].${field}: must be a non-empty string`);
+        }
+      }
+    });
+  }
+  return problems;
+}
+
 /**
  * The reason a coverage summary cannot serve as a delta BASELINE, or `null`.
  *