@goodbones/core 0.1.0-beta.1

package/src/core/graph.ts

@@ -0,0 +1,331 @@
+import * as Result from "effect/Result";
+
+import type {
+  GraphConfig,
+  GraphCycleRule,
+  GraphOrphanRule,
+  GraphProbe,
+  GraphReachRule,
+} from "../domain/architecture-config.js";
+import type { PatternInvalid } from "../domain/architecture-error.js";
+import type { Violation } from "../domain/violation.js";
+import { compilePatterns } from "./patterns.js";
+
+// The import graph, as facts: every file the policy walked, and for each the
+// files it resolves to. Externals and builtins are not nodes — a rule about
+// the shape of the repository is about the repository's own files.
+export type Graph = {
+  readonly files: ReadonlyArray<string>;
+  readonly edges: ReadonlyMap<string, ReadonlyArray<string>>;
+};
+
+export type CompiledGraphCycleRule = {
+  readonly name: string;
+  readonly message: string;
+  readonly within: ReadonlyArray<RegExp>;
+  readonly withinNot: ReadonlyArray<RegExp>;
+  readonly probe: GraphProbe;
+};
+
+export type CompiledGraphOrphanRule = CompiledGraphCycleRule & {
+  readonly entry: ReadonlyArray<RegExp>;
+};
+
+export type CompiledGraphReachRule = {
+  readonly name: string;
+  readonly message: string;
+  readonly from: ReadonlyArray<RegExp>;
+  readonly fromNot: ReadonlyArray<RegExp>;
+  readonly to: ReadonlyArray<RegExp>;
+  readonly toNot: ReadonlyArray<RegExp>;
+  readonly via: ReadonlyArray<RegExp>;
+  readonly probe: GraphProbe;
+};
+
+export type CompiledGraph = {
+  readonly cycles: ReadonlyArray<CompiledGraphCycleRule>;
+  readonly orphans: ReadonlyArray<CompiledGraphOrphanRule>;
+  readonly reach: ReadonlyArray<CompiledGraphReachRule>;
+};
+
+export const EMPTY_GRAPH_RULES: CompiledGraph = { cycles: [], orphans: [], reach: [] };
+
+export const hasGraphRules = (rules: CompiledGraph): boolean =>
+  rules.cycles.length + rules.orphans.length + rules.reach.length > 0;
+
+type Fields = ReadonlyArray<readonly [string, string | ReadonlyArray<string> | undefined]>;
+
+const compileFields = (
+  ruleName: string,
+  fields: Fields,
+): Result.Result<ReadonlyArray<ReadonlyArray<RegExp>>, PatternInvalid> => {
+  const compiled: Array<ReadonlyArray<RegExp>> = [];
+  for (const [field, patterns] of fields) {
+    const one = compilePatterns(ruleName, field, patterns);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    compiled.push(one.success);
+  }
+  return Result.succeed(compiled);
+};
+
+const compileCycle = (
+  rule: GraphCycleRule,
+): Result.Result<CompiledGraphCycleRule, PatternInvalid> => {
+  const fields = compileFields(rule.name, [
+    ["within", rule.within],
+    ["withinNot", rule.withinNot],
+  ]);
+  if (Result.isFailure(fields)) return Result.fail(fields.failure);
+  const [within = [], withinNot = []] = fields.success;
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    probe: rule.probe,
+    within,
+    withinNot,
+  });
+};
+
+const compileOrphan = (
+  rule: GraphOrphanRule,
+): Result.Result<CompiledGraphOrphanRule, PatternInvalid> => {
+  const fields = compileFields(rule.name, [
+    ["within", rule.within],
+    ["withinNot", rule.withinNot],
+    ["entry", rule.entry],
+  ]);
+  if (Result.isFailure(fields)) return Result.fail(fields.failure);
+  const [within = [], withinNot = [], entry = []] = fields.success;
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    probe: rule.probe,
+    within,
+    withinNot,
+    entry,
+  });
+};
+
+const compileReach = (
+  rule: GraphReachRule,
+): Result.Result<CompiledGraphReachRule, PatternInvalid> => {
+  const fields = compileFields(rule.name, [
+    ["from", rule.from],
+    ["fromNot", rule.fromNot],
+    ["to", rule.to],
+    ["toNot", rule.toNot],
+    ["via", rule.via],
+  ]);
+  if (Result.isFailure(fields)) return Result.fail(fields.failure);
+  const [from = [], fromNot = [], to = [], toNot = [], via = []] = fields.success;
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    probe: rule.probe,
+    from,
+    fromNot,
+    to,
+    toNot,
+    via,
+  });
+};
+
+export const compileGraphRules = (
+  config: GraphConfig | undefined,
+): Result.Result<CompiledGraph, PatternInvalid> => {
+  const cycles: Array<CompiledGraphCycleRule> = [];
+  for (const rule of config?.cycles ?? []) {
+    const one = compileCycle(rule);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    cycles.push(one.success);
+  }
+  const orphans: Array<CompiledGraphOrphanRule> = [];
+  for (const rule of config?.orphans ?? []) {
+    const one = compileOrphan(rule);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    orphans.push(one.success);
+  }
+  const reach: Array<CompiledGraphReachRule> = [];
+  for (const rule of config?.reach ?? []) {
+    const one = compileReach(rule);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    reach.push(one.success);
+  }
+  return Result.succeed({ cycles, orphans, reach });
+};
+
+const anyMatches = (patterns: ReadonlyArray<RegExp>, value: string): boolean =>
+  patterns.some((pattern) => pattern.test(value));
+
+const inScope = (
+  scope: { readonly within: ReadonlyArray<RegExp>; readonly withinNot: ReadonlyArray<RegExp> },
+  file: string,
+): boolean => anyMatches(scope.within, file) && !anyMatches(scope.withinNot, file);
+
+// Sorted adjacency, so every traversal below is deterministic and a subject
+// rendered from it is the same on every run.
+const neighboursOf = (graph: Graph, file: string): ReadonlyArray<string> =>
+  [...(graph.edges.get(file) ?? [])].sort();
+
+// Tarjan's strongly connected components over the subgraph a rule is about.
+// A component of one node is a cycle only if that node imports itself.
+const stronglyConnected = (
+  nodes: ReadonlyArray<string>,
+  graph: Graph,
+): ReadonlyArray<ReadonlyArray<string>> => {
+  const members = new Set(nodes);
+  const index = new Map<string, number>();
+  const low = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: Array<string> = [];
+  const components: Array<ReadonlyArray<string>> = [];
+  let next = 0;
+
+  const visit = (node: string): void => {
+    index.set(node, next);
+    low.set(node, next);
+    next += 1;
+    stack.push(node);
+    onStack.add(node);
+
+    for (const target of neighboursOf(graph, node)) {
+      if (!members.has(target)) continue;
+      if (!index.has(target)) {
+        visit(target);
+        low.set(node, Math.min(low.get(node) ?? 0, low.get(target) ?? 0));
+      } else if (onStack.has(target)) {
+        low.set(node, Math.min(low.get(node) ?? 0, index.get(target) ?? 0));
+      }
+    }
+
+    if (low.get(node) === index.get(node)) {
+      const component: Array<string> = [];
+      let popped: string | undefined;
+      do {
+        popped = stack.pop();
+        if (popped === undefined) break;
+        onStack.delete(popped);
+        component.push(popped);
+      } while (popped !== node);
+      components.push(component.sort());
+    }
+  };
+
+  for (const node of [...nodes].sort()) if (!index.has(node)) visit(node);
+  return components;
+};
+
+const evaluateCycles = (rule: CompiledGraphCycleRule, graph: Graph): ReadonlyArray<Violation> => {
+  const nodes = graph.files.filter((file) => inScope(rule, file));
+  const violations: Array<Violation> = [];
+  for (const component of stronglyConnected(nodes, graph)) {
+    const [first] = component;
+    if (first === undefined) continue;
+    const isCycle = component.length > 1 || (graph.edges.get(first) ?? []).includes(first);
+    if (!isCycle) continue;
+    // The subject is the component as a set, so the entry survives an edge
+    // added or removed elsewhere in the same cycle.
+    violations.push({
+      kind: "graph",
+      ruleName: rule.name,
+      message: rule.message,
+      file: first,
+      subject: component.join(" ↔ "),
+    });
+  }
+  return violations;
+};
+
+const evaluateOrphans = (rule: CompiledGraphOrphanRule, graph: Graph): ReadonlyArray<Violation> => {
+  const imported = new Set<string>();
+  for (const targets of graph.edges.values()) for (const target of targets) imported.add(target);
+
+  return graph.files
+    .filter((file) => inScope(rule, file) && !anyMatches(rule.entry, file) && !imported.has(file))
+    .map((file) => ({
+      kind: "graph",
+      ruleName: rule.name,
+      message: rule.message,
+      file,
+      subject: null,
+    }));
+};
+
+// Breadth-first from each `from` file, never stepping onto a `via` node, so a
+// `to` reached is one reached without passing through the tier that was
+// supposed to mediate. The route is put in the message, not the subject: the
+// fingerprint is (from, to), which survives the route changing.
+const evaluateReach = (rule: CompiledGraphReachRule, graph: Graph): ReadonlyArray<Violation> => {
+  const violations: Array<Violation> = [];
+  const isTarget = (file: string) => anyMatches(rule.to, file) && !anyMatches(rule.toNot, file);
+
+  for (const origin of graph.files) {
+    if (!anyMatches(rule.from, origin) || anyMatches(rule.fromNot, origin)) continue;
+
+    const parent = new Map<string, string>();
+    const queue: Array<string> = [origin];
+    const seen = new Set<string>([origin]);
+    const reported = new Set<string>();
+
+    while (queue.length > 0) {
+      const node = queue.shift();
+      if (node === undefined) break;
+      for (const target of neighboursOf(graph, node)) {
+        if (seen.has(target)) continue;
+        if (anyMatches(rule.via, target)) continue;
+        seen.add(target);
+        parent.set(target, node);
+        if (isTarget(target) && !reported.has(target)) {
+          reported.add(target);
+          const route: Array<string> = [target];
+          let step: string | undefined = target;
+          while (step !== undefined && step !== origin) {
+            step = parent.get(step);
+            if (step !== undefined) route.unshift(step);
+          }
+          violations.push({
+            kind: "graph",
+            ruleName: rule.name,
+            message: `${rule.message} (route: ${route.join(" → ")})`,
+            file: origin,
+            subject: target,
+          });
+        }
+        queue.push(target);
+      }
+    }
+  }
+  return violations;
+};
+
+export const evaluateGraph = (rules: CompiledGraph, graph: Graph): ReadonlyArray<Violation> => [
+  ...rules.cycles.flatMap((rule) => evaluateCycles(rule, graph)),
+  ...rules.orphans.flatMap((rule) => evaluateOrphans(rule, graph)),
+  ...rules.reach.flatMap((rule) => evaluateReach(rule, graph)),
+];
+
+// A probe is a small synthetic graph the rule must report on.
+export const graphOf = (probe: GraphProbe): Graph => {
+  const edges = new Map<string, Array<string>>();
+  const files = new Set<string>(probe.files ?? []);
+  for (const [from, to] of probe.edges) {
+    files.add(from);
+    files.add(to);
+    const targets = edges.get(from) ?? [];
+    targets.push(to);
+    edges.set(from, targets);
+  }
+  return { files: [...files].sort(), edges };
+};
+
+export const graphRulesFailingTheirProbe = (rules: CompiledGraph): ReadonlyArray<string> => [
+  ...rules.cycles
+    .filter((rule) => evaluateCycles(rule, graphOf(rule.probe)).length === 0)
+    .map((rule) => rule.name),
+  ...rules.orphans
+    .filter((rule) => evaluateOrphans(rule, graphOf(rule.probe)).length === 0)
+    .map((rule) => rule.name),
+  ...rules.reach
+    .filter((rule) => evaluateReach(rule, graphOf(rule.probe)).length === 0)
+    .map((rule) => rule.name),
+];

package/src/core/imports.ts

@@ -0,0 +1,160 @@
+import * as Result from "effect/Result";
+
+import type { 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";
+import {
+  compilePatterns,
+  firstFromMatch,
+  sourcesOf,
+  targetAllowed,
+  validateTargetPatterns,
+} from "./patterns.js";
+
+export type CompiledImportRule = {
+  readonly name: string;
+  readonly message: string;
+  readonly from: ReadonlyArray<RegExp>;
+  readonly fromNot: ReadonlyArray<RegExp>;
+  // Kept as source strings: a `$1` in a target pattern is substituted from the
+  // `from` match before it is compiled, which is how a rule says "any module but
+  // my own" without naming every module.
+  readonly to: ReadonlyArray<string>;
+  readonly toNot: ReadonlyArray<string>;
+  // 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>;
+  readonly dependencyKind: DependencyKind | null;
+  readonly probe: ImportProbe;
+};
+
+export const compileImportRule = (
+  rule: ImportRule,
+): Result.Result<CompiledImportRule, 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),
+    externals: new Set(rule.externals ?? []),
+    dependencyKind: rule.dependencyKind ?? null,
+  });
+};
+
+export const compileImportRules = (
+  rules: ReadonlyArray<ImportRule>,
+): Result.Result<ReadonlyArray<CompiledImportRule>, PatternInvalid> => {
+  const compiled: Array<CompiledImportRule> = [];
+  for (const rule of rules) {
+    const one = compileImportRule(rule);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    compiled.push(one.success);
+  }
+  return Result.succeed(compiled);
+};
+
+export type ImportEdge = {
+  readonly importer: string;
+  readonly specifier: string;
+};
+
+export type SelectedRule = readonly [CompiledImportRule, RegExpExecArray];
+
+// Returns the rules whose `from` side selects this file. A file no rule selects
+// never needs its imports resolved, which is what keeps resolution off the hot
+// path for the bulk of the repo.
+export const rulesSelecting = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  importer: string,
+): ReadonlyArray<SelectedRule> => {
+  const selected: Array<SelectedRule> = [];
+  for (const rule of rules) {
+    const captures = firstFromMatch(rule, importer);
+    if (captures !== null) selected.push([rule, captures]);
+  }
+  return selected;
+};
+
+// Whether the rule reports this target. The kind comes from the resolver, an
+// external is judged by its package name, and only then do the path patterns
+// speak — so a rule never has to know where a language keeps its packages.
+const reports = (rule: CompiledImportRule, captures: RegExpExecArray, target: ResolvedTarget) => {
+  if (rule.dependencyKind !== null && rule.dependencyKind !== target.kind) return false;
+  if (
+    target.kind === "external" &&
+    target.package !== undefined &&
+    rule.externals.has(target.package)
+  ) {
+    return false;
+  }
+  return targetAllowed(rule, captures, target.path);
+};
+
+export const evaluateSelectedEdge = (
+  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;
+
+  const violations: Array<Violation> = [];
+  for (const [rule, captures] of selected) {
+    if (reports(rule, captures, target)) {
+      violations.push({
+        kind: "import",
+        ruleName: rule.name,
+        message: rule.message,
+        file: edge.importer,
+        subject: target.path,
+      });
+    }
+  }
+
+  return Result.succeed(violations);
+};
+
+export const evaluateImportEdge = (
+  rules: ReadonlyArray<CompiledImportRule>,
+  resolver: ModuleResolver,
+  edge: ImportEdge,
+): Result.Result<ReadonlyArray<Violation>, ImportUnresolved> =>
+  evaluateSelectedEdge(rulesSelecting(rules, edge.importer), resolver, edge);
+
+// A probe states its target in one of three forms, and the form is the kind —
+// so the probe never has to know how a language spells an external's path.
+export const probeTargetOf = (to: ImportProbeTarget): ResolvedTarget => {
+  if (typeof to === "string") return { path: to, kind: "local" };
+  if ("external" in to) return { path: to.external, kind: "external", package: to.external };
+  return { path: to.builtin, kind: "builtin" };
+};
+
+// Every rule must report its own probe. A rule that does not is enforcing
+// nothing while still looking configured and still passing a clean lint run —
+// the one failure mode a linter cannot surface on its own.
+export const rulesFailingTheirProbe = (
+  rules: ReadonlyArray<CompiledImportRule>,
+): ReadonlyArray<CompiledImportRule> =>
+  rules.filter((rule) => {
+    const captures = firstFromMatch(rule, rule.probe.from);
+    if (captures === null) return true;
+    return !reports(rule, captures, probeTargetOf(rule.probe.to));
+  });

package/src/core/members.ts

@@ -0,0 +1,161 @@
+import * as Result from "effect/Result";
+
+import type {
+  DeclarationKind,
+  MemberProbe,
+  MemberRule,
+  MemberSubject,
+} from "../domain/architecture-config.js";
+import type { PatternInvalid } from "../domain/architecture-error.js";
+import type { MemberSite } from "../domain/facts.js";
+import type { Violation } from "../domain/violation.js";
+import type { FactExtractor } from "../ports/fact-extractor.js";
+import { compilePatterns, firstFromMatch } from "./patterns.js";
+
+export type { MemberSite } from "../domain/facts.js";
+
+export type CompiledMemberRule = {
+  readonly name: string;
+  readonly message: string;
+  readonly from: ReadonlyArray<RegExp>;
+  readonly fromNot: ReadonlyArray<RegExp>;
+  readonly subject: MemberSubject;
+  readonly in: ReadonlyArray<RegExp>;
+  // Which declarations a `members` rule speaks to; `null` for every kind.
+  readonly declares: ReadonlyArray<DeclarationKind> | null;
+  readonly match: ReadonlyArray<RegExp>;
+  readonly matchNot: ReadonlyArray<RegExp>;
+  readonly allow: ReadonlyArray<RegExp>;
+  readonly probe: MemberProbe;
+};
+
+export const compileMemberRule = (
+  rule: MemberRule,
+): Result.Result<CompiledMemberRule, PatternInvalid> => {
+  const fields = [
+    ["from", rule.from],
+    ["fromNot", rule.fromNot],
+    ["in", rule.in],
+    ["match", rule.match],
+    ["matchNot", rule.matchNot],
+    ["allow", rule.allow],
+  ] as const;
+
+  const compiled: Array<ReadonlyArray<RegExp>> = [];
+  for (const [field, patterns] of fields) {
+    const one = compilePatterns(rule.name, field, patterns);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    compiled.push(one.success);
+  }
+  const [from, fromNot, inside, match, matchNot, allow] = compiled as [
+    ReadonlyArray<RegExp>,
+    ReadonlyArray<RegExp>,
+    ReadonlyArray<RegExp>,
+    ReadonlyArray<RegExp>,
+    ReadonlyArray<RegExp>,
+    ReadonlyArray<RegExp>,
+  ];
+
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    probe: rule.probe,
+    subject: rule.subject,
+    from,
+    fromNot,
+    in: inside,
+    declares: rule.declares === undefined ? null : [...rule.declares],
+    match,
+    matchNot,
+    allow,
+  });
+};
+
+export const compileMemberRules = (
+  rules: ReadonlyArray<MemberRule>,
+): Result.Result<ReadonlyArray<CompiledMemberRule>, PatternInvalid> => {
+  const compiled: Array<CompiledMemberRule> = [];
+  for (const rule of rules) {
+    const one = compileMemberRule(rule);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    compiled.push(one.success);
+  }
+  return Result.succeed(compiled);
+};
+
+const anyMatches = (patterns: ReadonlyArray<RegExp>, value: string): boolean =>
+  patterns.some((pattern) => pattern.test(value));
+
+export const memberRulesSelecting = (
+  rules: ReadonlyArray<CompiledMemberRule>,
+  file: string,
+): ReadonlyArray<CompiledMemberRule> => rules.filter((rule) => firstFromMatch(rule, file) !== null);
+
+const governs = (rule: CompiledMemberRule, site: MemberSite): boolean => {
+  if (rule.subject !== site.subject) return false;
+  if (rule.in.length > 0 && (site.in === undefined || !anyMatches(rule.in, site.in))) return false;
+  if (
+    rule.declares !== null &&
+    (site.declares === undefined || !rule.declares.includes(site.declares))
+  ) {
+    return false;
+  }
+  if (rule.match.length > 0 && !anyMatches(rule.match, site.name)) return false;
+  if (rule.matchNot.length > 0 && anyMatches(rule.matchNot, site.name)) return false;
+  return true;
+};
+
+export const evaluateMemberSite = (
+  selected: ReadonlyArray<CompiledMemberRule>,
+  site: MemberSite,
+): ReadonlyArray<Violation> => {
+  const violations: Array<Violation> = [];
+  for (const rule of selected) {
+    if (!governs(rule, site)) continue;
+    if (anyMatches(rule.allow, site.name)) continue;
+
+    violations.push({
+      kind: "member",
+      ruleName: rule.name,
+      message: rule.message,
+      file: site.file,
+      subject: site.name,
+    });
+  }
+  return violations;
+};
+
+// A probe with a `source` is checked through the parser: the snippet must
+// yield a site named `probe.name` that the rule reports. That is the check a
+// synthetic site cannot make — a rule about a declaration shape the extractor
+// does not read passes its synthetic probe and reports nothing. A probe
+// without a source is checked against the rule's patterns alone, as a site
+// declared in the first kind the rule speaks to.
+export const memberRulesFailingTheirProbe = (
+  rules: ReadonlyArray<CompiledMemberRule>,
+  extractor: FactExtractor,
+): ReadonlyArray<CompiledMemberRule> =>
+  rules.filter((rule) => {
+    if (firstFromMatch(rule, rule.probe.from) === null) return true;
+
+    const sites: ReadonlyArray<MemberSite> =
+      rule.probe.source === undefined
+        ? [
+            {
+              file: rule.probe.from,
+              subject: rule.subject,
+              name: rule.probe.name,
+              ...(rule.probe.in === undefined ? {} : { in: rule.probe.in }),
+              ...(rule.probe.declares === undefined
+                ? rule.declares === null
+                  ? {}
+                  : { declares: rule.declares[0] }
+                : { declares: rule.probe.declares }),
+            },
+          ]
+        : extractor
+            .factsOf(rule.probe.from, rule.probe.source)
+            .memberSites.filter((site) => site.name === rule.probe.name);
+
+    return !sites.some((site) => evaluateMemberSite([rule], site).length > 0);
+  });