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

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,62 @@
+import type { Allowance } from "../domain/architecture-config.js";
+import type { ResolvedTarget } from "../ports/module-resolver.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.
+export type Slack = Pick<Allowance, "node" | "kind" | "entry">;
+
+const keyOf = (one: Slack): 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);
+};
+
+// 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.
+export const slackOf = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  edges: ReadonlyArray<ObservedEdge>,
+): ReadonlyArray<Slack> => {
+  const declared = new Map<string, Slack>();
+  for (const rule of rules) {
+    for (const { entry, kind, node } of rule.allowances) {
+      const one = { node, kind, entry };
+      if (!declared.has(keyOf(one))) declared.set(keyOf(one), one);
+    }
+  }
+
+  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));
+      }
+    }
+  }
+
+  return [...declared.values()].filter((one) => !used.has(keyOf(one)));
+};

package/src/domain/architecture-config.ts

@@ -27,6 +27,23 @@ 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),
+});
+
 export const ImportRule = Schema.Struct({
   name: Schema.String,
   message: Schema.String,
@@ -35,6 +52,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 +356,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"];

package/src/domain/snapshot.ts

@@ -0,0 +1,180 @@
+import * as Schema from "effect/Schema";
+
+import type { ViolationKind } from "./violation.js";
+
+// The conformance snapshot: one JSON document per run saying how far the
+// tree is from the manifest. `architecture conformance --json` emits it, a
+// pull-request check compares two of them, an agent reads one before it
+// edits, and a service that keeps history stores them — so it is a wire
+// format, defined here with a schema before anything consumes it, and
+// versioned so a document that grows it can say which one it grew.
+//
+// Three things it says that `check` does not: the residue (what no family
+// reaches), the slack (what the allowlists permit and nothing uses), and the
+// violations ordered by how much of the graph each fix drags along. Every
+// entry that names a violation names it by its line-independent fingerprint,
+// which is what lets one be tracked across commits.
+
+export const SNAPSHOT_SCHEMA_ID =
+  "https://dataquail.github.io/goodbones/schema/conformance.schema.json";
+
+export const SNAPSHOT_VERSION = 1;
+
+const describe = <S extends Schema.Top>(schema: S, description: string) =>
+  schema.annotate({ description });
+
+const COVERAGE_FAMILIES = ["imports", "structure", "members", "surface", "graph"] as const;
+
+// The kinds `Violation` carries, spelled here as a schema; the `satisfies`
+// below keeps the two lists one.
+const VIOLATION_KINDS = [
+  "import",
+  "export",
+  "structure",
+  "member",
+  "surface",
+  "graph",
+] as const satisfies ReadonlyArray<ViolationKind>;
+
+const Path = describe(Schema.String, "Repo-relative, with forward slashes.");
+
+const FamilyCoverage = Schema.Struct({
+  covered: describe(Schema.Finite, "Files this family reaches."),
+  total: describe(Schema.Finite, "Files walked."),
+  floor: Schema.optionalKey(
+    describe(
+      Schema.Finite,
+      "The fraction the manifest's `limits.coverage` states for this family, when it states one.",
+    ),
+  ),
+});
+
+export const SnapshotViolation = Schema.Struct({
+  fingerprint: describe(
+    Schema.String,
+    "kind|rule|file|subject — line-independent, so it survives edits to the file it names; the baseline's key.",
+  ),
+  kind: Schema.Literals(VIOLATION_KINDS),
+  ruleName: describe(Schema.String, "The manifest node path the rule was lowered from."),
+  file: Path,
+  subject: describe(
+    Schema.NullOr(Schema.String),
+    "The other end of the violated relationship — the resolved target, the restricted symbol, the missing sibling — or null when the file alone is the violation.",
+  ),
+  message: Schema.String,
+  baselined: describe(Schema.Boolean, "Carried by the baseline, so `check` does not fail on it."),
+});
+
+export const SnapshotSlack = Schema.Struct({
+  node: describe(Schema.String, "The manifest node that wrote the entry."),
+  kind: describe(
+    Schema.Literals(["allow", "external"]),
+    "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`.",
+  ),
+  entry: describe(Schema.String, "The entry as written, after alias expansion."),
+});
+
+export const Snapshot = Schema.Struct({
+  version: describe(Schema.Literal(SNAPSHOT_VERSION), "The shape of this document."),
+  manifest: describe(
+    Schema.Struct({
+      path: describe(
+        Path,
+        "The file the policy was read from — the root file, when split with `include`.",
+      ),
+      sha256: describe(
+        Schema.String,
+        "A hash of that file's bytes, so two snapshots can say whether the policy changed between them.",
+      ),
+    }),
+    "The policy this snapshot was taken against — the repository's own, or the one `--against` named.",
+  ),
+  roots: describe(Schema.Array(Path), "The directories walked."),
+  files: describe(Schema.Finite, "Files walked."),
+  ok: describe(
+    Schema.Boolean,
+    "What `check` would exit with: true when no reportable violation, unresolved import, stale baseline entry or coverage shortfall exists.",
+  ),
+  coverage: describe(
+    Schema.Struct(
+      Object.fromEntries(COVERAGE_FAMILIES.map((family) => [family, FamilyCoverage])) as Record<
+        (typeof COVERAGE_FAMILIES)[number],
+        typeof FamilyCoverage
+      >,
+    ),
+    "Per family, how many walked files it reaches. Structure counts enumerated folders only.",
+  ),
+  residue: describe(
+    Schema.Struct({
+      files: describe(Schema.Array(Path), "Files no family reaches, sorted."),
+      folders: describe(
+        Schema.Array(Path),
+        "Folders every walked file of which is residue, each the topmost such folder.",
+      ),
+    }),
+    "What the policy has nothing to say about. A file in an open folder under no allowlist is claimed, not policed, and counts.",
+  ),
+  violations: describe(
+    Schema.Array(SnapshotViolation),
+    "Every finding, baselined ones included, ordered so the ones cheapest to fix come first: by the height of the violated target in the import graph, leaves first.",
+  ),
+  unresolved: describe(
+    Schema.Array(Schema.Struct({ file: Path, specifier: Schema.String, detail: Schema.String })),
+    "Imports the resolver could not turn into a file. Every rule about one enforces nothing.",
+  ),
+  stale: describe(Schema.Array(Schema.String), "Baseline entries the code no longer produces."),
+  baseline: describe(
+    Schema.Struct({
+      size: describe(Schema.Finite, "Entries in the baseline file."),
+    }),
+    "The debt the policy is carrying. The ratchet: it may only shrink.",
+  ),
+  cycles: describe(
+    Schema.Finite,
+    "Strongly connected components of more than one file, or a file importing itself, anywhere in the walked graph — in a cycles rule's scope or not.",
+  ),
+  slack: describe(
+    Schema.Array(SnapshotSlack),
+    "Allowances no observed import uses, in manifest order. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs.",
+  ),
+  adoption: describe(
+    Schema.Struct({
+      unrestricted: describe(Schema.Array(Schema.String), "Nodes that say `unrestricted: true`."),
+      partial: describe(Schema.Array(Schema.String), "Nodes that say `partial: true`."),
+    }),
+    'The tiers that said "not tightened yet", by name; `limits` caps how many may.',
+  ),
+});
+
+export type Snapshot = typeof Snapshot.Type;
+export type SnapshotViolation = typeof SnapshotViolation.Type;
+export type SnapshotSlack = typeof SnapshotSlack.Type;
+
+// Decodes a document some other run wrote — the base of a pull request, a
+// stored one — refusing a key the shape does not declare, so a consumer never
+// reads a field that a later version renamed.
+export const decodeSnapshot = Schema.decodeUnknownResult(Snapshot, {
+  errors: "all",
+  onExcessProperty: "error",
+});
+
+type JsonValue = string | number | boolean | null | JsonObject | ReadonlyArray<JsonValue>;
+type JsonObject = { readonly [key: string]: JsonValue };
+
+// The document's shape as a JSON Schema, generated from the same codec, so
+// the two cannot disagree. Published beside the manifest's.
+export const snapshotJsonSchema = (): JsonObject => {
+  const generated = Schema.toJsonSchemaDocument(Snapshot) as unknown as {
+    readonly schema: JsonObject;
+    readonly definitions: JsonObject;
+  };
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: SNAPSHOT_SCHEMA_ID,
+    title: "Conformance snapshot",
+    description:
+      "How far a repository's tree is from its architecture manifest, as `architecture conformance --json` reports it. See https://dataquail.github.io/goodbones/architecture-rules/enforcement/conformance/.",
+    ...generated.schema,
+    ...(Object.keys(generated.definitions).length === 0 ? {} : { $defs: generated.definitions }),
+  };
+};

package/src/index.ts

@@ -21,6 +21,10 @@ export {
   coverageOf,
   coverageShortfalls,
   fractionsOf,
+  type Reach,
+  reachOf,
+  type Residue,
+  residueOf,
 } from "./core/coverage.js";
 export {
   type BindingEdge,
@@ -43,12 +47,14 @@ export {
   type Graph,
   graphRulesFailingTheirProbe,
   hasGraphRules,
+  heightOf,
 } from "./core/graph.js";
 export {
   type CompiledImportRule,
   compileImportRule,
   compileImportRules,
   evaluateImportEdge,
+  evaluateResolvedEdge,
   evaluateSelectedEdge,
   type ImportEdge,
   probeTargetOf,
@@ -63,6 +69,7 @@ export {
   memberRulesFailingTheirProbe,
   memberRulesSelecting,
 } from "./core/members.js";
+export { type ObservedEdge, type Slack, slackOf } from "./core/slack.js";
 export {
   type CompiledStructure,
   compileStructure,
@@ -79,6 +86,7 @@ export {
   surfaceRulesSelecting,
 } from "./core/surface.js";
 export {
+  type Allowance,
   type BindingKind,
   type DeclarationKind,
   type ExportFix,
@@ -115,6 +123,16 @@ export {
   type ManifestPosition,
   renderManifestPath,
 } from "./domain/manifest-location.js";
+export {
+  decodeSnapshot,
+  type Snapshot,
+  SNAPSHOT_SCHEMA_ID,
+  SNAPSHOT_VERSION,
+  snapshotJsonSchema,
+  Snapshot as SnapshotSchema,
+  type SnapshotSlack,
+  type SnapshotViolation,
+} from "./domain/snapshot.js";
 export {
   fingerprintOf,
   formatMessage,

package/src/manifest/compile.ts

@@ -1,4 +1,5 @@
 import {
+  type Allowance,
   type ExportRule,
   type GraphConfig,
   type ImportRule,
@@ -84,12 +85,11 @@ type Frame = {
   readonly pathGlob: string;
   readonly captures: CaptureIndex;
   readonly nextGroup: number;
-  // Accumulated down the tree. `reset` is the only thing that clears it.
-  readonly allow: ReadonlyArray<string>;
-  // Third-party packages, by name, accumulated and reset the same way. Kept
-  // apart from `allow` because a package is judged by its name and never by
-  // where the language's resolver found it.
-  readonly externals: ReadonlyArray<string>;
+  // The allowlist in force, accumulated down the tree; `reset` is the only
+  // thing that clears it. Each entry remembers the node that wrote it. A path
+  // glob is compiled to a target pattern; a package is judged by its name and
+  // never by where the language's resolver found it, so it carries none.
+  readonly allowances: ReadonlyArray<Allowance>;
   readonly importsMessage: string;
   // Inherited like the allowlist: a tier states its naming convention once.
   readonly naming: NamingSpec | undefined;
@@ -231,16 +231,12 @@ const mergeImports = (
   aliases: Readonly<Record<string, string>>,
   captures: CaptureIndex,
   nextGroup: number,
-): Pick<Frame, "allow" | "externals" | "importsMessage"> & {
+  node: string,
+): Pick<Frame, "allowances" | "importsMessage"> & {
   readonly deny: ReadonlyArray<Denial>;
 } => {
   if (spec === undefined) {
-    return {
-      allow: frame.allow,
-      externals: frame.externals,
-      deny: [],
-      importsMessage: frame.importsMessage,
-    };
+    return { allowances: frame.allowances, deny: [], importsMessage: frame.importsMessage };
   }
 
   const compileAllow = (glob: string): string =>
@@ -249,8 +245,15 @@ const mergeImports = (
         .source,
     );
 
-  const own = globsOf(spec.allow ?? []).map(compileAllow);
-  const external = spec.external ?? [];
+  const own: ReadonlyArray<Allowance> = [
+    ...globsOf(spec.allow ?? []).map((glob) => ({
+      node,
+      kind: "allow" as const,
+      entry: expandAliases(glob, aliases),
+      pattern: compileAllow(glob),
+    })),
+    ...(spec.external ?? []).map((name) => ({ node, kind: "external" as const, entry: name })),
+  ];
   const deny = (spec.deny ?? []).flatMap((entry) =>
     globsOf(entry.match).map((glob) => ({
       match: compileAllow(glob),
@@ -266,8 +269,7 @@ const mergeImports = (
   // a mistake here would be dangerous in.
   const dropping = spec.reset === true || spec.unrestricted === true;
   return {
-    allow: dropping ? own : [...frame.allow, ...own],
-    externals: dropping ? external : [...frame.externals, ...external],
+    allowances: dropping ? own : [...frame.allowances, ...own],
     // Only what this node declares. A prohibition is emitted once, over its whole
     // subtree, so descendants neither re-emit it nor can escape it — which is
     // what makes `reset` structurally unable to make a subtree quieter.
@@ -392,15 +394,14 @@ export const lowerManifest = (
       parent.nextGroup +
       (Object.keys(compiled.captures).length - Object.keys(parent.captures).length);
 
-    const merged = mergeImports(parent, node.imports, aliases, compiled.captures, nextGroup);
+    const merged = mergeImports(parent, node.imports, aliases, compiled.captures, nextGroup, name);
     const ownDenials = merged.deny;
     const frame: Frame = {
       pathSource,
       pathGlob: joinedGlob,
       captures: compiled.captures,
       nextGroup,
-      allow: merged.allow,
-      externals: merged.externals,
+      allowances: merged.allowances,
       importsMessage: merged.importsMessage,
       naming: node.name ?? parent.naming,
     };
@@ -608,9 +609,14 @@ export const lowerManifest = (
       ? probePathOf(joinedGlob, "")
       : probePathOf(joinedGlob, "").replace(/\/[^/]*$/, "");
 
-    const admitsEverything = frame.allow.some((pattern) => pattern === "^.*" || pattern === "^");
-    const hasAllowlist =
-      (frame.allow.length > 0 || frame.externals.length > 0) && !admitsEverything;
+    const allow = frame.allowances.flatMap((one) =>
+      one.pattern === undefined ? [] : [one.pattern],
+    );
+    const externals = frame.allowances
+      .filter((one) => one.kind === "external")
+      .map((one) => one.entry);
+    const admitsEverything = allow.some((pattern) => pattern === "^.*" || pattern === "^");
+    const hasAllowlist = frame.allowances.length > 0 && !admitsEverything;
 
     if (emitsOwnImports && node.imports?.unrestricted !== true && !hasAllowlist) {
       throw new Error(
@@ -630,8 +636,9 @@ export const lowerManifest = (
           probe: { from: scopeProbe, to: probeOutside("nowhere", ownFolder) },
           from: scope,
           ...exemptions,
-          toNot: [...frame.allow],
-          ...(frame.externals.length > 0 ? { externals: [...frame.externals] } : {}),
+          toNot: allow,
+          ...(externals.length > 0 ? { externals } : {}),
+          allowances: frame.allowances,
         });
       }
     }
@@ -841,8 +848,7 @@ export const lowerManifest = (
     pathGlob: "",
     captures: {},
     nextGroup: 1,
-    allow: [],
-    externals: [],
+    allowances: [],
     importsMessage: "This import is not on this folder's allowlist.",
     naming: undefined,
   };
@@ -856,6 +862,7 @@ export const lowerManifest = (
     aliases,
     {},
     1,
+    "repo",
   ).deny.entries()) {
     imports.push({
       name: `repo/deny-${String(index)}`,