@goodbones/core 0.1.0-beta.1

package/src/core/baseline.ts

@@ -0,0 +1,62 @@
+import type { Violation } from "../domain/violation.js";
+import { fingerprintOf } from "../domain/violation.js";
+
+// A baseline is the set of violations a repository is choosing to carry while it
+// adopts a policy. It exists so a rule can be turned on before the code is
+// clean — the alternative is not turning it on.
+//
+// Two properties make it a ratchet rather than a suppression list:
+//
+//   - Entries are line-independent fingerprints, so an entry survives edits to
+//     the file it names. One keyed on a position would go stale on the first
+//     reformat and silently re-admit the violation it was meant to record.
+//   - An entry that no longer fires is an error, not a shrug. Fixing a violation
+//     must remove its entry, or the floor never rises.
+export type Baseline = {
+  readonly version: 1;
+  readonly entries: ReadonlyArray<string>;
+};
+
+export const EMPTY_BASELINE: Baseline = { version: 1, entries: [] };
+
+export const baselineOf = (violations: Iterable<Violation>): Baseline => ({
+  version: 1,
+  entries: [...new Set([...violations].map(fingerprintOf))].sort(),
+});
+
+export const decodeBaseline = (raw: unknown): Baseline => {
+  if (typeof raw !== "object" || raw === null) return EMPTY_BASELINE;
+  const entries = (raw as { entries?: unknown }).entries;
+  if (!Array.isArray(entries)) return EMPTY_BASELINE;
+  return { version: 1, entries: entries.filter((one): one is string => typeof one === "string") };
+};
+
+export const serializeBaseline = (baseline: Baseline): string =>
+  `${JSON.stringify(baseline, null, 2)}\n`;
+
+export type BaselineFilter = {
+  readonly isBaselined: (violation: Violation) => boolean;
+};
+
+export const makeBaselineFilter = (baseline: Baseline): BaselineFilter => {
+  const entries = new Set(baseline.entries);
+  return { isBaselined: (violation) => entries.has(fingerprintOf(violation)) };
+};
+
+// The ratchet's teeth: entries the code no longer produces. A baseline that is
+// allowed to keep them stops being a record of debt and becomes a place to hide.
+export const staleEntriesOf = (
+  baseline: Baseline,
+  violations: Iterable<Violation>,
+): ReadonlyArray<string> => {
+  const current = new Set([...violations].map(fingerprintOf));
+  return baseline.entries.filter((entry) => !current.has(entry));
+};
+
+export const unbaselined = (
+  baseline: Baseline,
+  violations: Iterable<Violation>,
+): ReadonlyArray<Violation> => {
+  const { isBaselined } = makeBaselineFilter(baseline);
+  return [...violations].filter((violation) => !isBaselined(violation));
+};

package/src/core/coverage.ts

@@ -0,0 +1,154 @@
+import { OPEN_LAYOUT } from "../domain/architecture-config.js";
+import type { CompiledGraph } from "./graph.js";
+import type { CompiledImportRule } from "./imports.js";
+import type { CompiledMemberRule } from "./members.js";
+import { firstFromMatch } from "./patterns.js";
+import type { CompiledStructure } from "./structure.js";
+import type { CompiledSurfaceRule } from "./surface.js";
+
+// A probe proves a rule can fire. This is the other question: does the tree
+// actually reach the files? A file no allowlist selects, in a folder no layout
+// enumerates, is a file the policy has nothing to say about — and a policy that
+// is 40% silence looks exactly like one that is 100% enforced, until counted.
+
+export type FamilyCoverage = {
+  readonly covered: number;
+  readonly total: number;
+};
+
+export type StructureCoverage = {
+  // Its folder's files are listed by name.
+  readonly enumerated: number;
+  // Its folder is claimed, and admits any name — `layout: "open"`.
+  readonly open: number;
+  readonly total: number;
+};
+
+export type Coverage = {
+  readonly files: number;
+  // Under an import allowlist. An `unrestricted` tier emits none, so this is
+  // the honest count of files whose imports are actually bounded.
+  readonly imports: FamilyCoverage;
+  readonly structure: StructureCoverage;
+  readonly members: FamilyCoverage;
+  readonly surface: FamilyCoverage;
+  // In the scope of a cycles or orphans rule.
+  readonly graph: FamilyCoverage;
+};
+
+export type CoverageInputs = {
+  readonly importRules: ReadonlyArray<CompiledImportRule>;
+  readonly structure: CompiledStructure;
+  readonly memberRules: ReadonlyArray<CompiledMemberRule>;
+  readonly surfaceRules: ReadonlyArray<CompiledSurfaceRule>;
+  readonly graph: CompiledGraph;
+};
+
+// An allowlist names no `to`: it fires when the target matches none of its
+// `toNot`. A prohibition names one. Only the former bounds a file.
+const isAllowlist = (rule: CompiledImportRule): boolean =>
+  rule.to.length === 0 && rule.toNot.length > 0;
+
+const dirnameOf = (file: string): string => {
+  const at = file.lastIndexOf("/");
+  return at === -1 ? "" : file.slice(0, at);
+};
+
+const selects = (
+  rule: { from: ReadonlyArray<RegExp>; fromNot: ReadonlyArray<RegExp> },
+  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;
+
+    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 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 },
+  };
+};
+
+// 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 = {
+  readonly imports?: number;
+  readonly structure?: number;
+  readonly members?: number;
+  readonly surface?: number;
+  readonly graph?: number;
+};
+
+export type CoverageFamily = keyof CoverageFloors;
+
+export const fractionOf = (covered: number, total: number): number =>
+  total === 0 ? 1 : covered / total;
+
+export const fractionsOf = (coverage: Coverage): Readonly<Record<CoverageFamily, number>> => ({
+  imports: fractionOf(coverage.imports.covered, coverage.imports.total),
+  structure: fractionOf(coverage.structure.enumerated, coverage.structure.total),
+  members: fractionOf(coverage.members.covered, coverage.members.total),
+  surface: fractionOf(coverage.surface.covered, coverage.surface.total),
+  graph: fractionOf(coverage.graph.covered, coverage.graph.total),
+});
+
+export type Shortfall = {
+  readonly family: CoverageFamily;
+  readonly actual: number;
+  readonly floor: number;
+};
+
+export const coverageShortfalls = (
+  coverage: Coverage,
+  floors: CoverageFloors,
+): ReadonlyArray<Shortfall> => {
+  const actual = fractionsOf(coverage);
+  const families: ReadonlyArray<CoverageFamily> = [
+    "imports",
+    "structure",
+    "members",
+    "surface",
+    "graph",
+  ];
+  return families.flatMap((family) => {
+    const floor = floors[family];
+    if (floor === undefined || actual[family] >= floor) return [];
+    return [{ family, actual: actual[family], floor }];
+  });
+};

package/src/core/exports.ts

@@ -0,0 +1,171 @@
+import * as Result from "effect/Result";
+
+import type { BindingKind, ExportProbe, ExportRule } from "../domain/architecture-config.js";
+import type { ImportUnresolved, PatternInvalid } from "../domain/architecture-error.js";
+import type { Binding } from "../domain/facts.js";
+import type { Violation } from "../domain/violation.js";
+import type { FactExtractor } from "../ports/fact-extractor.js";
+import type { ModuleResolver } from "../ports/module-resolver.js";
+import {
+  compilePatterns,
+  firstFromMatch,
+  sourcesOf,
+  targetAllowed,
+  validateTargetPatterns,
+} from "./patterns.js";
+
+export type { Binding } from "../domain/facts.js";
+
+const DEFAULT_KINDS: ReadonlyArray<BindingKind> = ["named"];
+
+export type CompiledExportRule = {
+  readonly name: string;
+  readonly message: string;
+  readonly from: ReadonlyArray<RegExp>;
+  readonly fromNot: ReadonlyArray<RegExp>;
+  readonly to: ReadonlyArray<string>;
+  readonly toNot: ReadonlyArray<string>;
+  readonly symbols: ReadonlySet<string> | null;
+  readonly kinds: ReadonlyArray<BindingKind>;
+  readonly fix: "subpath-namespace-import" | null;
+  readonly probe: ExportProbe;
+};
+
+export const compileExportRule = (
+  rule: ExportRule,
+): Result.Result<CompiledExportRule, PatternInvalid> => {
+  const from = compilePatterns(rule.name, "from", rule.from);
+  if (Result.isFailure(from)) return Result.fail(from.failure);
+  const fromNot = compilePatterns(rule.name, "fromNot", rule.fromNot);
+  if (Result.isFailure(fromNot)) return Result.fail(fromNot.failure);
+
+  const targets = validateTargetPatterns(rule.name, [
+    ["to", rule.to],
+    ["toNot", rule.toNot],
+  ]);
+  if (Result.isFailure(targets)) return Result.fail(targets.failure);
+
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    probe: rule.probe,
+    from: from.success,
+    fromNot: fromNot.success,
+    to: sourcesOf(rule.to),
+    toNot: sourcesOf(rule.toNot),
+    symbols: rule.symbols === undefined ? null : new Set(rule.symbols),
+    kinds: rule.kinds ?? DEFAULT_KINDS,
+    fix: rule.fix ?? null,
+  });
+};
+
+export const compileExportRules = (
+  rules: ReadonlyArray<ExportRule>,
+): Result.Result<ReadonlyArray<CompiledExportRule>, PatternInvalid> => {
+  const compiled: Array<CompiledExportRule> = [];
+  for (const rule of rules) {
+    const one = compileExportRule(rule);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    compiled.push(one.success);
+  }
+  return Result.succeed(compiled);
+};
+
+export type BindingEdge = {
+  readonly importer: string;
+  readonly specifier: string;
+  readonly bindings: ReadonlyArray<Binding>;
+};
+
+export type SelectedExportRule = readonly [CompiledExportRule, RegExpExecArray];
+
+export const exportRulesSelecting = (
+  rules: ReadonlyArray<CompiledExportRule>,
+  importer: string,
+): ReadonlyArray<SelectedExportRule> => {
+  const selected: Array<SelectedExportRule> = [];
+  for (const rule of rules) {
+    const captures = firstFromMatch(rule, importer);
+    if (captures !== null) selected.push([rule, captures]);
+  }
+  return selected;
+};
+
+const covers = (rule: CompiledExportRule, binding: Binding): boolean =>
+  rule.kinds.includes(binding.kind) && (rule.symbols === null || rule.symbols.has(binding.symbol));
+
+export type ExportViolation = {
+  readonly violation: Violation;
+  readonly rule: CompiledExportRule;
+  readonly bindings: ReadonlyArray<Binding>;
+};
+
+export const evaluateSelectedBindings = (
+  selected: ReadonlyArray<SelectedExportRule>,
+  resolver: ModuleResolver,
+  edge: BindingEdge,
+): Result.Result<ReadonlyArray<ExportViolation>, ImportUnresolved> => {
+  if (selected.length === 0 || edge.bindings.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;
+
+  const violations: Array<ExportViolation> = [];
+  for (const [rule, captures] of selected) {
+    if (!targetAllowed(rule, captures, target.path)) continue;
+
+    const offending = edge.bindings.filter((binding) => covers(rule, binding));
+    if (offending.length === 0) continue;
+
+    // A rule carrying a fix reports once for the whole declaration, because the
+    // fix rewrites the declaration as a unit; one without reports per symbol, so
+    // the diagnostic sits on the name that is actually restricted.
+    const groups = rule.fix === null ? offending.map((binding) => [binding]) : [offending];
+    for (const bindings of groups) {
+      violations.push({
+        rule,
+        bindings,
+        violation: {
+          kind: "export",
+          ruleName: rule.name,
+          message: rule.message,
+          file: edge.importer,
+          subject: `${target.path}#${bindings.map((binding) => binding.symbol).join(",")}`,
+        },
+      });
+    }
+  }
+
+  return Result.succeed(violations);
+};
+
+export const evaluateBindingEdge = (
+  rules: ReadonlyArray<CompiledExportRule>,
+  resolver: ModuleResolver,
+  edge: BindingEdge,
+): Result.Result<ReadonlyArray<ExportViolation>, ImportUnresolved> =>
+  evaluateSelectedBindings(exportRulesSelecting(rules, edge.importer), resolver, edge);
+
+// A probe with a `source` is checked through the parser: every edge in the
+// snippet is taken to resolve to `probe.to`, and a binding named `probe.symbol`
+// must come out of the extractor covered by the rule. A probe without one is
+// checked against the rule's patterns alone.
+export const exportRulesFailingTheirProbe = (
+  rules: ReadonlyArray<CompiledExportRule>,
+  extractor: FactExtractor,
+): ReadonlyArray<CompiledExportRule> =>
+  rules.filter((rule) => {
+    const captures = firstFromMatch(rule, rule.probe.from);
+    if (captures === null) return true;
+    if (!targetAllowed(rule, captures, rule.probe.to)) return true;
+
+    if (rule.probe.source === undefined) {
+      return !covers(rule, { symbol: rule.probe.symbol, kind: rule.probe.kind ?? "named" });
+    }
+    const facts = extractor.factsOf(rule.probe.from, rule.probe.source);
+    const bindings = [...facts.bindings.values()].flat();
+    return !bindings.some(
+      (binding) => binding.symbol === rule.probe.symbol && covers(rule, binding),
+    );
+  });