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

package/src/domain/snapshot.ts

@@ -0,0 +1,225 @@
+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."),
+});
+
+const AllowanceKind = describe(
+  Schema.Literals(["allow", "external"]),
+  "`allow` is a path glob under `imports.allow`; `external` a package name under `imports.external`.",
+);
+
+const Entry = describe(Schema.String, "The entry as written, after alias expansion.");
+
+export const SnapshotSlack = Schema.Struct({
+  node: describe(
+    Schema.String,
+    "The manifest node that wrote the entry — or, when `fragment` is set, the `defs` fragment it was written in.",
+  ),
+  kind: AllowanceKind,
+  entry: Entry,
+  fragment: Schema.optionalKey(
+    describe(
+      Schema.String,
+      "Present when the entry arrived through `use`. The nodes that referenced the fragment wrote one word, so the entry is reported once, against the fragment, rather than once per node.",
+    ),
+  ),
+  of: Schema.optionalKey(
+    describe(
+      Schema.Finite,
+      "With `fragment`: how many non-vacant nodes were granted the entry through it. None of them uses it.",
+    ),
+  ),
+});
+
+export const SnapshotConcentration = Schema.Struct({
+  fragment: describe(Schema.String, "The `defs` fragment the entry was written in."),
+  kind: AllowanceKind,
+  entry: Entry,
+  usedAt: describe(Schema.Finite, "Nodes granted the entry through the fragment that use it."),
+  of: describe(Schema.Finite, "Non-vacant nodes granted the entry through the fragment."),
+});
+
+export const SnapshotVacancy = Schema.Struct({
+  node: describe(Schema.String, "The manifest node."),
+  allowances: describe(
+    Schema.Finite,
+    "Distinct entries the node wrote, `allow` and `external` together.",
+  ),
+});
+
+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.",
+  ),
+  vacant: describe(
+    Schema.Array(SnapshotVacancy),
+    "Nodes that state an import allowlist and select no walked file, in manifest order. Every allowance on one is unused by construction, so none is counted as slack; the node is a tier declared ahead of its first file, or a pattern that no longer matches. Residue is files no node reaches; this is nodes no file reaches.",
+  ),
+  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, vacant nodes excluded. A manifest inferred from the tree has none on the day it is written; every entry here is permission nothing needs. An entry that arrived through `use` is reported once, against the fragment, and only when no node granted it uses it.",
+  ),
+  concentration: describe(
+    Schema.Array(SnapshotConcentration),
+    "Fragment entries used at some of the nodes granted them and not the rest. Not slack — the fragment's line is needed somewhere — but a per-file permission written as a many-node allowance, which is what an allowlist widened to make one build green looks like.",
+  ),
+  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;
+export type SnapshotConcentration = typeof SnapshotConcentration.Type;
+export type SnapshotVacancy = typeof SnapshotVacancy.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,12 @@ export {
   coverageOf,
   coverageShortfalls,
   fractionsOf,
+  type Reach,
+  reachOf,
+  type Residue,
+  residueOf,
+  type Vacancy,
+  vacancyOf,
 } from "./core/coverage.js";
 export {
   type BindingEdge,
@@ -43,12 +49,14 @@ export {
   type Graph,
   graphRulesFailingTheirProbe,
   hasGraphRules,
+  heightOf,
 } from "./core/graph.js";
 export {
   type CompiledImportRule,
   compileImportRule,
   compileImportRules,
   evaluateImportEdge,
+  evaluateResolvedEdge,
   evaluateSelectedEdge,
   type ImportEdge,
   probeTargetOf,
@@ -63,6 +71,13 @@ export {
   memberRulesFailingTheirProbe,
   memberRulesSelecting,
 } from "./core/members.js";
+export {
+  type Concentration,
+  type ObservedEdge,
+  type Slack,
+  slackOf,
+  type SlackReport,
+} from "./core/slack.js";
 export {
   type CompiledStructure,
   compileStructure,
@@ -79,6 +94,7 @@ export {
   surfaceRulesSelecting,
 } from "./core/surface.js";
 export {
+  type Allowance,
   type BindingKind,
   type DeclarationKind,
   type ExportFix,
@@ -115,6 +131,18 @@ export {
   type ManifestPosition,
   renderManifestPath,
 } from "./domain/manifest-location.js";
+export {
+  decodeSnapshot,
+  type Snapshot,
+  SNAPSHOT_SCHEMA_ID,
+  SNAPSHOT_VERSION,
+  type SnapshotConcentration,
+  snapshotJsonSchema,
+  Snapshot as SnapshotSchema,
+  type SnapshotSlack,
+  type SnapshotVacancy,
+  type SnapshotViolation,
+} from "./domain/snapshot.js";
 export {
   fingerprintOf,
   formatMessage,
@@ -143,7 +171,12 @@ export {
   type WalkedLanguage,
 } from "./infrastructure/walk.js";
 export { type LoadedPolicy, loadPolicy, type LoadPolicyInput } from "./load/policy.js";
-export { type LoweredRules, lowerManifest, type ProbeLanguage } from "./manifest/compile.js";
+export {
+  type LoweredRules,
+  lowerManifest,
+  type LowerOptions,
+  type ProbeLanguage,
+} from "./manifest/compile.js";
 export {
   type ExpandedManifest,
   type ExpandIssue,

package/src/load/policy.ts

@@ -216,7 +216,7 @@ export const loadPolicy = (
   // The manifest is the authoring surface; these flat rules are the machine's.
   // The languages tell lowering what a source file in each scope is called, so
   // a synthetic probe is a file of the scope's language.
-  const rules = lowerManifest(config, languages);
+  const rules = lowerManifest(config, languages, { substitutions: decoded.success.substitutions });
 
   // The ceilings. A tier that says "not tightened yet" is a sentence someone
   // wrote; a ceiling on how many may say so is what keeps the backlog from

package/src/manifest/compile.ts

@@ -1,4 +1,5 @@
 import {
+  type Allowance,
   type ExportRule,
   type GraphConfig,
   type ImportRule,
@@ -10,6 +11,8 @@ import {
   type StructureRoot,
   type SurfaceRule,
 } from "../domain/architecture-config.js";
+import type { ManifestPath } from "../domain/manifest-location.js";
+import { fragmentOf, type Substitution } from "./expand.js";
 import { anchored, type CaptureIndex, globToRegexSource, prefixed } from "./glob.js";
 import {
   globsOf,
@@ -84,12 +87,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;
@@ -225,22 +227,24 @@ type Denial = {
   readonly probe: string;
 };
 
+// Which `defs` fragment one key of a node's `imports` was written in, when it
+// was written in one. Resolved per key, since `imports: { use: x, allow: […] }`
+// takes `allow` from the reference site and `external` from the fragment.
+type ImportsProvenance = (key: "allow" | "external") => string | undefined;
+
 const mergeImports = (
   frame: Frame,
   spec: ImportsSpec | undefined,
   aliases: Readonly<Record<string, string>>,
   captures: CaptureIndex,
   nextGroup: number,
-): Pick<Frame, "allow" | "externals" | "importsMessage"> & {
+  node: string,
+  provenance: ImportsProvenance,
+): 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 +253,25 @@ const mergeImports = (
         .source,
     );
 
-  const own = globsOf(spec.allow ?? []).map(compileAllow);
-  const external = spec.external ?? [];
+  const via = (key: "allow" | "external"): Pick<Allowance, "fragment"> => {
+    const fragment = provenance(key);
+    return fragment === undefined ? {} : { fragment };
+  };
+  const own: ReadonlyArray<Allowance> = [
+    ...globsOf(spec.allow ?? []).map((glob) => ({
+      node,
+      kind: "allow" as const,
+      entry: expandAliases(glob, aliases),
+      pattern: compileAllow(glob),
+      ...via("allow"),
+    })),
+    ...(spec.external ?? []).map((name) => ({
+      node,
+      kind: "external" as const,
+      entry: name,
+      ...via("external"),
+    })),
+  ];
   const deny = (spec.deny ?? []).flatMap((entry) =>
     globsOf(entry.match).map((glob) => ({
       match: compileAllow(glob),
@@ -266,8 +287,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.
@@ -276,11 +296,20 @@ const mergeImports = (
   };
 };
 
+export type LowerOptions = {
+  // The `use` references the expansion replaced, so an allowance can say
+  // which fragment it came through. A manifest lowered without them is one
+  // whose every entry reads as authored where it sits.
+  readonly substitutions?: ReadonlyArray<Substitution>;
+};
+
 export const lowerManifest = (
   manifest: Manifest,
   languages: ReadonlyArray<ProbeLanguage> = [],
+  options: LowerOptions = {},
 ): LoweredRules => {
   const aliases = manifest.aliases ?? {};
+  const substitutions = options.substitutions ?? [];
 
   // The extension a synthetic probe file carries: the first extension of the
   // language whose scope covers the probe's folder. A probe is matched by its
@@ -343,6 +372,9 @@ export const lowerManifest = (
     parent: Frame,
     name: string,
     siblings: ReadonlyArray<string>,
+    // Where this node sits in the expanded document, so its `imports` keys
+    // can be traced back through any `use` that carried them.
+    nodePath: ManifestPath,
   ): void => {
     const literalSiblings = siblings
       .filter((sibling) => sibling !== key)
@@ -392,15 +424,22 @@ 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,
+      (field) => fragmentOf(substitutions, [...nodePath, "imports", field]),
+    );
     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,
     };
@@ -590,7 +629,11 @@ export const lowerManifest = (
       }
       const siblingKeys = childKeys.map(([childKey]) => childKey);
       for (const [childKey, child] of childKeys) {
-        walk(childKey, child, frame, `${name}/${alternativesOf(childKey)[0] ?? ""}`, siblingKeys);
+        walk(childKey, child, frame, `${name}/${alternativesOf(childKey)[0] ?? ""}`, siblingKeys, [
+          ...nodePath,
+          "children",
+          childKey,
+        ]);
       }
     }
 
@@ -608,9 +651,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 +678,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 +890,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 +904,8 @@ export const lowerManifest = (
     aliases,
     {},
     1,
+    "repo",
+    () => undefined,
   ).deny.entries()) {
     imports.push({
       name: `repo/deny-${String(index)}`,
@@ -898,6 +948,7 @@ export const lowerManifest = (
         .replace(/[^a-zA-Z0-9]+/g, "-")
         .replace(/^-|-$/g, ""),
       Object.keys(manifest.tree),
+      ["tree", key],
     );
   }
 

package/src/manifest/expand.ts

@@ -172,3 +172,12 @@ export const originOf = (
     via: [...outer, { at: innermost.ref, name: innermost.name }],
   };
 };
+
+// The fragment a path in the expanded document was written in, when it was:
+// the innermost `use` the path crossed, or nothing when the value at that path
+// was authored where it sits — including a key written beside `use`, which
+// belongs to the reference site.
+export const fragmentOf = (
+  substitutions: ReadonlyArray<Substitution>,
+  path: ManifestPath,
+): string | undefined => originOf(substitutions, path).via.at(-1)?.name;

package/src/manifest/manifest.ts

@@ -305,6 +305,9 @@ export type DecodedManifest = {
   // Things the manifest said in a form that still loads but is on its way out.
   // The host prints them; nothing else acts on them.
   readonly notices: ReadonlyArray<string>;
+  // Every `use` the expansion replaced. Lowering reads them to say which
+  // fragment an allowance came through; nothing else needs them.
+  readonly substitutions: ReadonlyArray<Substitution>;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -496,5 +499,6 @@ export const decodeManifest = (
   return Result.succeed({
     manifest: decoded.success,
     notices: [...resolve.notices, ...members.notices],
+    substitutions,
   });
 };