@goodbones/core 0.1.0-beta.4 → 0.1.0-beta.6

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

@@ -227,6 +227,42 @@ export const cyclesIn = (graph: Graph): ReadonlyArray<ReadonlyArray<string>> =>
     );
   });
 
+// 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/slack.ts

@@ -0,0 +1,135 @@
+import type { Allowance } from "../domain/architecture-config.js";
+import type { ResolvedTarget } from "../ports/module-resolver.js";
+import { vacantNodesOf } from "./coverage.js";
+import type { CompiledImportRule } from "./imports.js";
+import { firstFromMatch, matchesAny } from "./patterns.js";
+
+// Coverage says how many files an allowlist reaches. This is the other
+// question about an allowlist: how much of it is used. A manifest inferred
+// from today's edges reaches every file and constrains nothing, so coverage
+// alone reads as complete while the policy is pure permission; slack is the
+// number that tells the two apart. It is also the signature of an allowlist
+// widened to make a build green — an entry nothing imports through.
+
+// An edge the host resolved: the importer, and what the specifier became.
+export type ObservedEdge = {
+  readonly importer: string;
+  readonly target: ResolvedTarget;
+};
+
+// An allowance no observed edge uses. The same shape the lowering recorded,
+// minus the compiled pattern nobody wrote. When the entry arrived through
+// `use`, `node` is the fragment's name — the line to delete is in `defs` —
+// and `of` says how many nodes wrote the reference that carried it.
+export type Slack = Pick<Allowance, "node" | "kind" | "entry"> & {
+  readonly fragment?: string;
+  readonly of?: number;
+};
+
+// A fragment entry used at some of the nodes it was granted to and not the
+// rest. At the fragment level it is not slack — there is no line nobody
+// needs — but it is a per-file permission written as a many-node allowance,
+// which is what an allowlist widened to make one build green looks like.
+export type Concentration = Pick<Allowance, "kind" | "entry"> & {
+  readonly fragment: string;
+  readonly usedAt: number;
+  readonly of: number;
+};
+
+export type SlackReport = {
+  readonly slack: ReadonlyArray<Slack>;
+  readonly concentration: ReadonlyArray<Concentration>;
+};
+
+const keyOf = (one: Pick<Allowance, "node" | "kind" | "entry">): string =>
+  `${one.node} ${one.kind} ${one.entry}`;
+
+// Whether one edge, from a file this rule selects, passes through this entry.
+const uses = (allowance: Allowance, captures: RegExpExecArray, target: ResolvedTarget): boolean => {
+  if (allowance.kind === "external") {
+    return target.kind === "external" && target.package === allowance.entry;
+  }
+  return allowance.pattern !== undefined && matchesAny([allowance.pattern], captures, target.path);
+};
+
+// One entry as one place wrote it: a node that wrote the line, or a fragment
+// that N nodes pulled in with `use`. Keyed by that place, so a fragment's
+// entry is reported once however many nodes reference it.
+type Declared = {
+  readonly node: string;
+  readonly kind: Allowance["kind"];
+  readonly entry: string;
+  readonly fragment: string | undefined;
+  // The nodes that declared it, vacant ones excluded — every allowance on a
+  // vacant node is unused by construction, and is vacancy, not slack.
+  readonly at: Set<string>;
+};
+
+const groupKeyOf = (one: Allowance): string =>
+  one.fragment === undefined
+    ? `node ${one.node} ${one.kind} ${one.entry}`
+    : `use ${one.fragment} ${one.kind} ${one.entry}`;
+
+// Every allowance the rules carry that no edge uses, in the order the manifest
+// declared them. An entry is inherited by every descendant's rule and written
+// once, so it is keyed by where it was written: an import anywhere under the
+// declaring node is a use. An entry that arrived through `use` is keyed by
+// the fragment, and is slack only when no node it was granted to uses it;
+// used at some and not others, it is reported as concentration instead. A
+// vacant node — one whose allowlist selects no walked file — contributes
+// nothing to either.
+export const slackOf = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  edges: ReadonlyArray<ObservedEdge>,
+  files: ReadonlyArray<string>,
+): SlackReport => {
+  const vacant = vacantNodesOf(rules, files);
+
+  const declared = new Map<string, Declared>();
+  for (const rule of rules) {
+    for (const allowance of rule.allowances) {
+      if (vacant.has(allowance.node)) continue;
+      const key = groupKeyOf(allowance);
+      const group = declared.get(key) ?? {
+        node: allowance.fragment ?? allowance.node,
+        kind: allowance.kind,
+        entry: allowance.entry,
+        fragment: allowance.fragment,
+        at: new Set<string>(),
+      };
+      group.at.add(allowance.node);
+      declared.set(key, group);
+    }
+  }
+
+  // Which (node, kind, entry) some edge passes through.
+  const used = new Set<string>();
+  for (const edge of edges) {
+    for (const rule of rules) {
+      if (rule.allowances.length === 0) continue;
+      const captures = firstFromMatch(rule, edge.importer);
+      if (captures === null) continue;
+      for (const allowance of rule.allowances) {
+        if (uses(allowance, captures, edge.target)) used.add(keyOf(allowance));
+      }
+    }
+  }
+
+  const slack: Array<Slack> = [];
+  const concentration: Array<Concentration> = [];
+  for (const group of declared.values()) {
+    const { entry, kind } = group;
+    const usedAt = [...group.at].filter((node) => used.has(keyOf({ node, kind, entry }))).length;
+    if (group.fragment === undefined) {
+      if (usedAt === 0) slack.push({ node: group.node, kind, entry });
+      continue;
+    }
+    const of = group.at.size;
+    if (usedAt === 0) {
+      slack.push({ node: group.node, kind, entry, fragment: group.fragment, of });
+    } else if (usedAt < of) {
+      concentration.push({ fragment: group.fragment, kind, entry, usedAt, of });
+    }
+  }
+  return { slack, concentration };
+};

package/src/domain/architecture-config.ts

@@ -27,6 +27,28 @@ const ImportProbe = Schema.Struct({
   to: ImportProbeTarget,
 });
 
+// One entry of an `imports` allowlist, as the author wrote it and where. An
+// allowlist rule compiles its entries into `toNot` patterns and `externals`
+// names, which is all evaluation needs; this is the other direction — from a
+// pattern back to the line in the manifest that put it there — so a report
+// can say which line no import uses. Slack is the signature of an allowlist
+// widened to make a build green, and it is only visible with the entry kept.
+export const Allowance = Schema.Struct({
+  // The manifest node that declared the entry, as rule names name nodes.
+  node: Schema.String,
+  // `allow` is a path glob; `external` is a package name.
+  kind: Schema.Literals(["allow", "external"]),
+  // The entry as written, after alias expansion.
+  entry: Schema.String,
+  // For an `allow`: the compiled target pattern, as `toNot` carries it.
+  pattern: Schema.optionalKey(Schema.String),
+  // The `defs` fragment the entry arrived through, when the node wrote
+  // `use: <name>` rather than the entry itself. Slack is attributed to the
+  // fragment then: the node's authors wrote one word, and the line to delete
+  // is in `defs`.
+  fragment: Schema.optionalKey(Schema.String),
+});
+
 export const ImportRule = Schema.Struct({
   name: Schema.String,
   message: Schema.String,
@@ -35,6 +57,9 @@ export const ImportRule = Schema.Struct({
   fromNot: Schema.optionalKey(PatternList),
   to: Schema.optionalKey(PatternList),
   toNot: Schema.optionalKey(PatternList),
+  // Where each `toNot` pattern and `externals` name came from, for an
+  // allowlist lowered from a manifest. A hand-written rule carries none.
+  allowances: Schema.optionalKey(Schema.Array(Allowance)),
   // Third-party packages this rule permits, by package name. An external
   // target is judged by its package, never by where the language's resolver
   // happened to find it on disk — `to`/`toNot` patterns are for the
@@ -336,6 +361,7 @@ const StructureConfig = Schema.Struct({
   naming: Schema.optionalKey(Schema.Array(StructureNaming)),
 });
 
+export type Allowance = (typeof Allowance)["Type"];
 export type ImportRule = (typeof ImportRule)["Type"];
 export type ResolveConfig = (typeof ResolveConfig)["Type"];
 export type ResolveScope = (typeof ResolveScope)["Type"];