@goodbones/core 0.1.0-beta.1 → 0.1.0-beta.10

package/src/core/coverage.ts

@@ -59,52 +59,129 @@ const selects = (
   file: string,
 ) => firstFromMatch(rule, file) !== null;
 
-export const coverageOf = (policy: CoverageInputs, files: ReadonlyArray<string>): Coverage => {
-  const allowlists = policy.importRules.filter(isAllowlist);
-  let imports = 0;
-  let enumerated = 0;
-  let open = 0;
-  let members = 0;
-  let surface = 0;
-  let graph = 0;
-
-  for (const file of files) {
-    if (allowlists.some((rule) => selects(rule, file))) imports += 1;
+// Which families reach one file. The one loop both `coverageOf` and
+// `residueOf` run: the first counts, the second keeps the names.
+export type Reach = {
+  readonly file: string;
+  readonly imports: boolean;
+  // Enumerated and open are told apart, as `coverageOf` counts them.
+  readonly structure: "enumerated" | "open" | null;
+  readonly members: boolean;
+  readonly surface: boolean;
+  readonly graph: boolean;
+};
 
+export const reachOf = (
+  policy: CoverageInputs,
+  files: ReadonlyArray<string>,
+): ReadonlyArray<Reach> => {
+  const allowlists = policy.importRules.filter(isAllowlist);
+  return files.map((file) => {
     const folder = dirnameOf(file);
     const governing = policy.structure.folders.filter((rule) =>
       rule.folder.some((pattern) => pattern.test(folder)),
     );
-    if (governing.length > 0) {
-      if (governing.every((rule) => rule.files.some((pattern) => pattern.source === OPEN_LAYOUT))) {
-        open += 1;
-      } else {
-        enumerated += 1;
-      }
-    }
-
-    if (policy.memberRules.some((rule) => selects(rule, file))) members += 1;
-    if (policy.surfaceRules.some((rule) => selects(rule, file))) surface += 1;
-
-    const scoped = [...policy.graph.cycles, ...policy.graph.orphans].some(
-      (rule) =>
-        rule.within.some((pattern) => pattern.test(file)) &&
-        !rule.withinNot.some((pattern) => pattern.test(file)),
-    );
-    if (scoped) graph += 1;
-  }
+    const structure =
+      governing.length === 0
+        ? null
+        : governing.every((rule) => rule.files.some((pattern) => pattern.source === OPEN_LAYOUT))
+          ? "open"
+          : "enumerated";
+    return {
+      file,
+      imports: allowlists.some((rule) => selects(rule, file)),
+      structure,
+      members: policy.memberRules.some((rule) => selects(rule, file)),
+      surface: policy.surfaceRules.some((rule) => selects(rule, file)),
+      graph: [...policy.graph.cycles, ...policy.graph.orphans].some(
+        (rule) =>
+          rule.within.some((pattern) => pattern.test(file)) &&
+          !rule.withinNot.some((pattern) => pattern.test(file)),
+      ),
+    };
+  });
+};
 
+export const coverageOf = (policy: CoverageInputs, files: ReadonlyArray<string>): Coverage => {
+  const reach = reachOf(policy, files);
+  const count = (is: (one: Reach) => boolean): number => reach.filter(is).length;
   const total = files.length;
   return {
     files: total,
-    imports: { covered: imports, total },
-    structure: { enumerated, open, total },
-    members: { covered: members, total },
-    surface: { covered: surface, total },
-    graph: { covered: graph, total },
+    imports: { covered: count((one) => one.imports), total },
+    structure: {
+      enumerated: count((one) => one.structure === "enumerated"),
+      open: count((one) => one.structure === "open"),
+      total,
+    },
+    members: { covered: count((one) => one.members), total },
+    surface: { covered: count((one) => one.surface), total },
+    graph: { covered: count((one) => one.graph), total },
   };
 };
 
+// The files no family reaches — counted by no family's coverage, so a file in
+// an open folder under no allowlist is residue: claimed, not policed — and
+// the folders wholly made of them, each the topmost such folder. A policy
+// that is 40% silence looks exactly like one that is 100% enforced, until
+// counted; this is what the silence is made of.
+export type Residue = {
+  readonly files: ReadonlyArray<string>;
+  readonly folders: ReadonlyArray<string>;
+};
+
+export const residueOf = (policy: CoverageInputs, files: ReadonlyArray<string>): Residue => {
+  const unreached = reachOf(policy, files)
+    .filter(
+      (one) =>
+        !one.imports &&
+        one.structure !== "enumerated" &&
+        !one.members &&
+        !one.surface &&
+        !one.graph,
+    )
+    .map((one) => one.file)
+    .sort();
+  return { files: unreached, folders: foldersWhollyIn(unreached, files) };
+};
+
+// Every ancestor folder of a file, nearest first, the root (`""`) excluded.
+const ancestorsOf = (file: string): ReadonlyArray<string> => {
+  const folders: Array<string> = [];
+  let folder = dirnameOf(file);
+  while (folder !== "") {
+    folders.push(folder);
+    folder = dirnameOf(folder);
+  }
+  return folders;
+};
+
+// The topmost folders every walked file of which is in `subset`. Each is
+// reported once, with none of its subfolders, and a lone file's folder counts
+// — a folder with one file the policy ignores is a folder the policy ignores.
+const foldersWhollyIn = (
+  subset: ReadonlyArray<string>,
+  files: ReadonlyArray<string>,
+): ReadonlyArray<string> => {
+  const walked = new Map<string, number>();
+  for (const file of files) {
+    for (const folder of ancestorsOf(file)) walked.set(folder, (walked.get(folder) ?? 0) + 1);
+  }
+  const inSubset = new Map<string, number>();
+  for (const file of subset) {
+    for (const folder of ancestorsOf(file)) {
+      inSubset.set(folder, (inSubset.get(folder) ?? 0) + 1);
+    }
+  }
+  const whole = [...inSubset.entries()]
+    .filter(([folder, count]) => walked.get(folder) === count)
+    .map(([folder]) => folder)
+    .sort();
+  return whole.filter(
+    (folder) => !whole.some((other) => other !== folder && folder.startsWith(`${other}/`)),
+  );
+};
+
 // A floor the policy states for itself, per family, as a fraction. Structure
 // counts enumerated folders only: an open one is claimed, not policed by name.
 export type CoverageFloors = {
@@ -117,6 +194,59 @@ export type CoverageFloors = {
 
 export type CoverageFamily = keyof CoverageFloors;
 
+// Residue is files no node reaches; this is nodes no file reaches. A node
+// that states an import allowlist and selects no walked file grants
+// permission to nothing: every allowance on it is unused by construction,
+// which is not slack — there is no line to delete, only a node that is a
+// tier declared ahead of its first file, or a pattern that no longer
+// matches. Which of the two, the reader decides; the report tells both
+// apart from slack so nothing has to be read twice.
+export type Vacancy = ReadonlyArray<{
+  readonly node: string;
+  // Distinct entries the node wrote, `allow` and `external` together.
+  readonly allowances: number;
+}>;
+
+// The nodes whose allowances no live rule carries. A node's allowlist is
+// inherited by every descendant's rule until one `reset`s, so a node whose
+// own rule steps aside for an overriding child still reaches that child's
+// files through the child's rule — and is not vacant while the child has any.
+export const vacantNodesOf = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  files: ReadonlyArray<string>,
+): ReadonlySet<string> => {
+  const declaring = new Set<string>();
+  const reached = new Set<string>();
+  for (const rule of rules) {
+    if (rule.allowances.length === 0) continue;
+    const live = files.some((file) => selects(rule, file));
+    for (const { node } of rule.allowances) {
+      declaring.add(node);
+      if (live) reached.add(node);
+    }
+  }
+  return new Set([...declaring].filter((node) => !reached.has(node)));
+};
+
+// Every vacant node with how many entries it wrote, in the order the
+// allowlists declared them.
+export const vacancyOf = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  files: ReadonlyArray<string>,
+): Vacancy => {
+  const vacant = vacantNodesOf(rules, files);
+  const entries = new Map<string, Set<string>>();
+  for (const rule of rules) {
+    for (const { entry, kind, node } of rule.allowances) {
+      if (!vacant.has(node)) continue;
+      const written = entries.get(node) ?? new Set<string>();
+      written.add(`${kind} ${entry}`);
+      entries.set(node, written);
+    }
+  }
+  return [...entries.entries()].map(([node, written]) => ({ node, allowances: written.size }));
+};
+
 export const fractionOf = (covered: number, total: number): number =>
   total === 0 ? 1 : covered / total;
 

package/src/core/graph.ts

@@ -215,6 +215,54 @@ const stronglyConnected = (
   return components;
 };
 
+// Every cycle in the graph, each as its sorted member set. What `infer` asks
+// before it writes a no-cycles rule: a rule the tree fails on day one is a
+// baseline entry, not a description of the tree.
+export const cyclesIn = (graph: Graph): ReadonlyArray<ReadonlyArray<string>> =>
+  stronglyConnected(graph.files, graph).filter((component) => {
+    const [first] = component;
+    return (
+      first !== undefined &&
+      (component.length > 1 || (graph.edges.get(first) ?? []).includes(first))
+    );
+  });
+
+// How far each file stands above a leaf: 0 for a file importing nothing the
+// walk saw, else one more than the tallest thing it imports. A violation on a
+// short target is local to fix; one on a tall target drags the tower with it —
+// so a report lists the short ones first. Measured over the strongly
+// connected components, so the members of a cycle share one height and the
+// answer is finite: a cycle is one thing to fix, not a ladder.
+export const heightOf = (graph: Graph): ReadonlyMap<string, number> => {
+  const components = stronglyConnected(graph.files, graph);
+  const componentOf = new Map<string, number>();
+  components.forEach((component, index) => {
+    for (const file of component) componentOf.set(file, index);
+  });
+
+  const heights = new Map<number, number>();
+  const measure = (index: number): number => {
+    const known = heights.get(index);
+    if (known !== undefined) return known;
+    let tallest = -1;
+    for (const file of components[index] ?? []) {
+      for (const target of neighboursOf(graph, file)) {
+        const other = componentOf.get(target);
+        if (other !== undefined && other !== index) tallest = Math.max(tallest, measure(other));
+      }
+    }
+    heights.set(index, tallest + 1);
+    return tallest + 1;
+  };
+
+  const byFile = new Map<string, number>();
+  for (const file of [...graph.files].sort()) {
+    const index = componentOf.get(file);
+    if (index !== undefined) byFile.set(file, measure(index));
+  }
+  return byFile;
+};
+
 const evaluateCycles = (rule: CompiledGraphCycleRule, graph: Graph): ReadonlyArray<Violation> => {
   const nodes = graph.files.filter((file) => inScope(rule, file));
   const violations: Array<Violation> = [];

package/src/core/imports.ts

@@ -1,6 +1,11 @@
 import * as Result from "effect/Result";
 
-import type { ImportProbe, ImportProbeTarget, ImportRule } from "../domain/architecture-config.js";
+import type {
+  Allowance,
+  ImportProbe,
+  ImportProbeTarget,
+  ImportRule,
+} from "../domain/architecture-config.js";
 import type { ImportUnresolved, PatternInvalid } from "../domain/architecture-error.js";
 import type { Violation } from "../domain/violation.js";
 import type { DependencyKind, ModuleResolver, ResolvedTarget } from "../ports/module-resolver.js";
@@ -25,6 +30,9 @@ export type CompiledImportRule = {
   // Third-party packages the rule permits, by name. Judged before the path
   // patterns, so where a language keeps its packages never reaches a rule.
   readonly externals: ReadonlySet<string>;
+  // Where each `toNot` and external came from, when lowered from a manifest;
+  // empty for a hand-written rule. What `slackOf` reads.
+  readonly allowances: ReadonlyArray<Allowance>;
   readonly dependencyKind: DependencyKind | null;
   readonly probe: ImportProbe;
 };
@@ -52,6 +60,7 @@ export const compileImportRule = (
     to: sourcesOf(rule.to),
     toNot: sourcesOf(rule.toNot),
     externals: new Set(rule.externals ?? []),
+    allowances: rule.allowances ?? [],
     dependencyKind: rule.dependencyKind ?? null,
   });
 };
@@ -105,17 +114,13 @@ const reports = (rule: CompiledImportRule, captures: RegExpExecArray, target: Re
   return targetAllowed(rule, captures, target.path);
 };
 
-export const evaluateSelectedEdge = (
+// The same judgement over a target the host has already resolved — for a host
+// that resolves each edge once and wants the target for something else too.
+export const evaluateResolvedEdge = (
   selected: ReadonlyArray<SelectedRule>,
-  resolver: ModuleResolver,
-  edge: ImportEdge,
-): Result.Result<ReadonlyArray<Violation>, ImportUnresolved> => {
-  if (selected.length === 0) return Result.succeed([]);
-
-  const resolved = resolver.resolve(edge.importer, edge.specifier);
-  if (Result.isFailure(resolved)) return Result.fail(resolved.failure);
-  const target = resolved.success;
-
+  importer: string,
+  target: ResolvedTarget,
+): ReadonlyArray<Violation> => {
   const violations: Array<Violation> = [];
   for (const [rule, captures] of selected) {
     if (reports(rule, captures, target)) {
@@ -123,13 +128,24 @@ export const evaluateSelectedEdge = (
         kind: "import",
         ruleName: rule.name,
         message: rule.message,
-        file: edge.importer,
+        file: importer,
         subject: target.path,
       });
     }
   }
+  return violations;
+};
+
+export const evaluateSelectedEdge = (
+  selected: ReadonlyArray<SelectedRule>,
+  resolver: ModuleResolver,
+  edge: ImportEdge,
+): Result.Result<ReadonlyArray<Violation>, ImportUnresolved> => {
+  if (selected.length === 0) return Result.succeed([]);
 
-  return Result.succeed(violations);
+  const resolved = resolver.resolve(edge.importer, edge.specifier);
+  if (Result.isFailure(resolved)) return Result.fail(resolved.failure);
+  return Result.succeed(evaluateResolvedEdge(selected, edge.importer, resolved.success));
 };
 
 export const evaluateImportEdge = (

package/src/core/ledger.ts

@@ -0,0 +1,242 @@
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+
+import type { CampaignUnit } from "../domain/architecture-config.js";
+import type { Violation } from "../domain/violation.js";
+
+// A campaign's ledger: every place the pattern still occurs, and the record of
+// every time the count was allowed to go up. It is the baseline's cousin and
+// not the baseline — same fingerprint, different file, different semantics.
+//
+//   - One file per campaign, so two pull requests migrating different
+//     components never conflict, and finishing a campaign is deleting its file.
+//   - Growth is only ever recorded, never silent. `prune` only removes;
+//     `allow` is the one way an entry is added, and it always appends a
+//     regression with a reason, a timestamp and an author.
+//   - The arithmetic is checked: `entries.length === initial + Σ delta − fixed`.
+//     A hand-added entry with no regression record fails the build, with no
+//     git history in the loop.
+//   - A fixed entry is stale, and `check` fails on it as it fails on a stale
+//     baseline entry, so progress lands as a visible diff.
+
+const Regression = Schema.Struct({
+  at: Schema.String,
+  by: Schema.String,
+  delta: Schema.Finite,
+  reason: Schema.String,
+  entries: Schema.Array(Schema.String),
+});
+
+export const Ledger = Schema.Struct({
+  version: Schema.Literal(1),
+  id: Schema.String,
+  created: Schema.String,
+  // The count on the day the ledger was written.
+  initial: Schema.Finite,
+  // Entries removed by `prune` since.
+  fixed: Schema.Finite,
+  // When an entry last left the ledger — what the stall clock reads.
+  lastProgress: Schema.String,
+  regressions: Schema.Array(Regression),
+  // `file` or `file#subject`, deduplicated and sorted.
+  entries: Schema.Array(Schema.String),
+});
+
+export type Ledger = typeof Ledger.Type;
+export type Regression = typeof Regression.Type;
+
+const decode = Schema.decodeUnknownResult(Ledger, { errors: "all", onExcessProperty: "error" });
+
+export const EMPTY_LEDGER = (id: string, now: number): Ledger => {
+  const at = new Date(now).toISOString();
+  return {
+    version: 1,
+    id,
+    created: at,
+    initial: 0,
+    fixed: 0,
+    lastProgress: at,
+    regressions: [],
+    entries: [],
+  };
+};
+
+// A malformed ledger is refused, unlike a malformed baseline, which reads as
+// empty: an empty baseline reports every violation, the safe direction, while
+// an empty ledger would report every hit as unrecorded growth and demand a
+// regression record for debt that was already counted.
+export const decodeLedger = (raw: unknown): Result.Result<Ledger, string> => {
+  const decoded = decode(raw);
+  return Result.isFailure(decoded)
+    ? Result.fail(String(decoded.failure.issue))
+    : Result.succeed(decoded.success);
+};
+
+export const serializeLedger = (ledger: Ledger): string => `${JSON.stringify(ledger, null, 2)}\n`;
+
+// A hit's entry: the file, and its subject when the campaign's unit has one.
+export const entryOf = (violation: Violation): string =>
+  violation.subject === null ? violation.file : `${violation.file}#${violation.subject}`;
+
+const allowedTotal = (ledger: Ledger): number =>
+  ledger.initial + ledger.regressions.reduce((sum, one) => sum + one.delta, 0);
+
+export const ledgerArithmeticHolds = (ledger: Ledger): boolean =>
+  ledger.entries.length === allowedTotal(ledger) - ledger.fixed;
+
+// A `match` entry is `file#anchor#hash`; an edit inside the anchored
+// declaration changes the hash and nothing else, and is the same entry.
+const anchorOf = (entry: string): string => entry.slice(0, entry.lastIndexOf("#"));
+
+export type Reconciliation = {
+  // Hits the ledger already carries, exactly or by anchor.
+  readonly ledgered: ReadonlyArray<Violation>;
+  // Hits the ledger does not carry: unrecorded growth.
+  readonly unrecorded: ReadonlyArray<Violation>;
+  // Entries no hit produces: fixed, and waiting to be pruned.
+  readonly stale: ReadonlyArray<string>;
+  // Entries whose hash moved under a still-present anchor, with what they
+  // read now. `prune` rewrites them; they count as neither fixed nor new.
+  readonly drifted: ReadonlyArray<{ readonly from: string; readonly to: string }>;
+};
+
+export const reconcile = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+): Reconciliation => {
+  const entries = new Set(ledger.entries);
+  const ledgered: Array<Violation> = [];
+  const unmatched: Array<Violation> = [];
+  const current = new Set<string>();
+  for (const hit of hits) {
+    const entry = entryOf(hit);
+    current.add(entry);
+    if (entries.has(entry)) ledgered.push(hit);
+    else unmatched.push(hit);
+  }
+  let stale = ledger.entries.filter((entry) => !current.has(entry));
+  const drifted: Array<{ from: string; to: string }> = [];
+  const unrecorded: Array<Violation> = [];
+
+  if (unit === "match") {
+    // Pair each stale entry with an unmatched hit under the same anchor, in
+    // order, so a declaration with two edited matches keeps two entries.
+    const byAnchor = new Map<string, Array<string>>();
+    for (const entry of stale) {
+      const anchor = anchorOf(entry);
+      byAnchor.set(anchor, [...(byAnchor.get(anchor) ?? []), entry]);
+    }
+    const paired = new Set<string>();
+    for (const hit of unmatched) {
+      const entry = entryOf(hit);
+      const candidates = byAnchor.get(anchorOf(entry));
+      const from = candidates?.shift();
+      if (from === undefined) {
+        unrecorded.push(hit);
+        continue;
+      }
+      paired.add(from);
+      drifted.push({ from, to: entry });
+      ledgered.push(hit);
+    }
+    stale = stale.filter((entry) => !paired.has(entry));
+  } else {
+    for (const hit of unmatched) unrecorded.push(hit);
+  }
+
+  return { ledgered, unrecorded, stale, drifted };
+};
+
+export const staleEntriesOf = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+): ReadonlyArray<string> => reconcile(ledger, hits, unit).stale;
+
+export const newEntriesOf = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+): ReadonlyArray<string> => reconcile(ledger, hits, unit).unrecorded.map(entryOf);
+
+const sorted = (entries: Iterable<string>): ReadonlyArray<string> => [...new Set(entries)].sort();
+
+// A first ledger: every hit is an entry, and the count is the `initial`.
+export const ledgerOf = (id: string, hits: Iterable<Violation>, now: number): Ledger => {
+  const entries = sorted([...hits].map(entryOf));
+  return { ...EMPTY_LEDGER(id, now), initial: entries.length, entries };
+};
+
+// `prune`: the stale entries leave, `fixed` rises by as many, and
+// `lastProgress` moves — only when something left. A drifted entry is
+// rewritten in place and counts as neither.
+export const pruned = (
+  ledger: Ledger,
+  hits: Iterable<Violation>,
+  unit: CampaignUnit,
+  now: number,
+): Ledger => {
+  const { drifted, stale } = reconcile(ledger, hits, unit);
+  const rewritten = new Map(drifted.map((one) => [one.from, one.to]));
+  const gone = new Set(stale);
+  const entries = sorted(
+    ledger.entries
+      .filter((entry) => !gone.has(entry))
+      .map((entry) => rewritten.get(entry) ?? entry),
+  );
+  return {
+    ...ledger,
+    fixed: ledger.fixed + stale.length,
+    lastProgress: stale.length > 0 ? new Date(now).toISOString() : ledger.lastProgress,
+    entries,
+  };
+};
+
+export type RegressionRecord = {
+  readonly at: number;
+  readonly by: string;
+  readonly reason: string;
+};
+
+// `allow`: the entries join the ledger, and a regression records that they
+// did. The delta is what was actually added — an entry already present is
+// not growth.
+export const allowed = (
+  ledger: Ledger,
+  entries: Iterable<string>,
+  record: RegressionRecord,
+): Ledger => {
+  const present = new Set(ledger.entries);
+  const added = sorted([...entries].filter((entry) => !present.has(entry)));
+  if (added.length === 0) return ledger;
+  return {
+    ...ledger,
+    regressions: [
+      ...ledger.regressions,
+      {
+        at: new Date(record.at).toISOString(),
+        by: record.by,
+        delta: added.length,
+        reason: record.reason,
+        entries: added,
+      },
+    ],
+    entries: sorted([...ledger.entries, ...added]),
+  };
+};
+
+// `1 − count / (initial + Σ delta)`: how much of everything the campaign was
+// ever asked to pay down has been paid.
+export const progressOf = (ledger: Ledger): number => {
+  const total = allowedTotal(ledger);
+  return total === 0 ? 1 : 1 - ledger.entries.length / total;
+};
+
+export const isComplete = (ledger: Ledger): boolean => ledger.entries.length === 0;
+
+export const isStalled = (
+  rule: { readonly staleAfter: number },
+  ledger: Ledger,
+  now: number,
+): boolean => !isComplete(ledger) && now - Date.parse(ledger.lastProgress) > rule.staleAfter;