oxlint-architecture-rules 0.1.0-beta.0

package/src/core/exports.ts

@@ -0,0 +1,164 @@
+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 { Violation } from "../domain/violation.js";
+import type { ModuleResolver } from "../ports/module-resolver.js";
+import {
+  compilePatterns,
+  firstFromMatch,
+  sourcesOf,
+  targetAllowed,
+  validateTargetPatterns,
+} from "./patterns.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);
+};
+
+// One name pulled across one import edge: `import { makeCommandBus } from "…"`
+// is a single binding, and so is the `Effect` in `import { Effect } from "effect"`.
+export type Binding = {
+  readonly symbol: string;
+  readonly kind: BindingKind;
+};
+
+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);
+
+export const exportRulesFailingTheirProbe = (
+  rules: ReadonlyArray<CompiledExportRule>,
+): 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;
+    return !covers(rule, {
+      symbol: rule.probe.symbol,
+      kind: rule.probe.kind ?? "named",
+    });
+  });

package/src/core/imports.ts

@@ -0,0 +1,138 @@
+import * as Result from "effect/Result";
+
+import type { ImportProbe, 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 } from "../ports/module-resolver.js";
+import {
+  compilePatterns,
+  firstFromMatch,
+  kindOfPath,
+  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>;
+  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),
+    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;
+};
+
+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 (rule.dependencyKind !== null && rule.dependencyKind !== target.kind) continue;
+    if (targetAllowed(rule, captures, target.path)) {
+      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);
+
+// 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;
+    if (rule.dependencyKind !== null && rule.dependencyKind !== kindOfPath(rule.probe.to)) {
+      return true;
+    }
+    return !targetAllowed(rule, captures, rule.probe.to);
+  });

package/src/core/members.ts

@@ -0,0 +1,131 @@
+import * as Result from "effect/Result";
+
+import type { MemberProbe, MemberRule, MemberSubject } from "../domain/architecture-config.js";
+import type { PatternInvalid } from "../domain/architecture-error.js";
+import type { Violation } from "../domain/violation.js";
+import { compilePatterns, firstFromMatch } from "./patterns.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>;
+  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,
+    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);
+};
+
+// One declared or called name, and the declaration it sits in (a type alias's
+// name for `type-members`, absent for `calls`).
+export type MemberSite = {
+  readonly file: string;
+  readonly subject: MemberSubject;
+  readonly name: string;
+  readonly in?: string;
+};
+
+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.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;
+};
+
+export const memberRulesFailingTheirProbe = (
+  rules: ReadonlyArray<CompiledMemberRule>,
+): ReadonlyArray<CompiledMemberRule> =>
+  rules.filter((rule) => {
+    const site: MemberSite = {
+      file: rule.probe.from,
+      subject: rule.subject,
+      name: rule.probe.name,
+      ...(rule.probe.in === undefined ? {} : { in: rule.probe.in }),
+    };
+    if (firstFromMatch(rule, site.file) === null) return true;
+    return evaluateMemberSite([rule], site).length === 0;
+  });

package/src/core/patterns.ts

@@ -0,0 +1,122 @@
+import * as Result from "effect/Result";
+
+import { patternsOf } from "../domain/architecture-config.js";
+import { PatternInvalid } from "../domain/architecture-error.js";
+import type { DependencyKind } from "../ports/module-resolver.js";
+
+const BACKREFERENCE = /\$([1-9])/g;
+
+// Validation-only stand-in so `new RegExp` sees a syntactically complete pattern
+// where a backreference will later be spliced.
+const withPlaceholderCaptures = (pattern: string): string => pattern.replaceAll(BACKREFERENCE, "x");
+
+const compilePattern = (
+  ruleName: string,
+  field: string,
+  pattern: string,
+): Result.Result<RegExp, PatternInvalid> => {
+  try {
+    return Result.succeed(new RegExp(pattern));
+  } catch (cause) {
+    return Result.fail(new PatternInvalid({ ruleName, field, pattern, detail: String(cause) }));
+  }
+};
+
+export const compilePatterns = (
+  ruleName: string,
+  field: string,
+  patterns: string | ReadonlyArray<string> | undefined,
+): Result.Result<ReadonlyArray<RegExp>, PatternInvalid> => {
+  const sources = patterns === undefined ? [] : patternsOf(patterns);
+  const compiled: Array<RegExp> = [];
+  for (const source of sources) {
+    const one = compilePattern(ruleName, field, source);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    compiled.push(one.success);
+  }
+  return Result.succeed(compiled);
+};
+
+// Target patterns are compiled per edge (a `$1` is only known once the `from`
+// side has matched), so they are validated separately at load. A typo in a
+// `toNot` must fail the config, not lie dormant until some file happens to
+// select the rule.
+export const validateTargetPatterns = (
+  ruleName: string,
+  fields: ReadonlyArray<readonly [string, string | ReadonlyArray<string> | undefined]>,
+): Result.Result<void, PatternInvalid> => {
+  for (const [field, patterns] of fields) {
+    const validated = compilePatterns(
+      ruleName,
+      field,
+      patterns === undefined ? undefined : patternsOf(patterns).map(withPlaceholderCaptures),
+    );
+    if (Result.isFailure(validated)) return Result.fail(validated.failure);
+  }
+  return Result.succeed(undefined);
+};
+
+export const sourcesOf = (
+  patterns: string | ReadonlyArray<string> | undefined,
+): ReadonlyArray<string> => (patterns === undefined ? [] : [...patternsOf(patterns)]);
+
+// A capture is one path segment from the importer, spliced into a target
+// pattern as `$1`. It is data, not pattern syntax: a folder named `my.module`
+// must match itself, not "my" plus any character plus "module".
+const REGEX_METACHARACTER = /[.*+?^${}()|[\]\\]/g;
+
+const substitute = (pattern: string, captures: RegExpExecArray): string =>
+  pattern.replaceAll(BACKREFERENCE, (whole, index: string) => {
+    const capture = captures[Number(index)];
+    return capture === undefined ? whole : capture.replace(REGEX_METACHARACTER, "\\$&");
+  });
+
+const targetCache = new Map<string, RegExp>();
+
+const compiledTarget = (pattern: string): RegExp => {
+  const cached = targetCache.get(pattern);
+  if (cached !== undefined) return cached;
+  const compiled = new RegExp(pattern);
+  targetCache.set(pattern, compiled);
+  return compiled;
+};
+
+export const matchesAny = (
+  patterns: ReadonlyArray<string>,
+  captures: RegExpExecArray,
+  value: string,
+): boolean => patterns.some((pattern) => compiledTarget(substitute(pattern, captures)).test(value));
+
+export type Selectable = {
+  readonly from: ReadonlyArray<RegExp>;
+  readonly fromNot: ReadonlyArray<RegExp>;
+};
+
+export const firstFromMatch = (rule: Selectable, importer: string): RegExpExecArray | null => {
+  if (rule.fromNot.some((pattern) => pattern.test(importer))) return null;
+  for (const pattern of rule.from) {
+    const captures = pattern.exec(importer);
+    if (captures !== null) return captures;
+  }
+  return null;
+};
+
+// A probe states its target as a resolved path, so its dependency kind is read
+// back off that path rather than restated in the config.
+export const kindOfPath = (path: string): DependencyKind =>
+  path.startsWith("node:") ? "builtin" : path.includes("node_modules/") ? "external" : "local";
+
+export type Targeted = Selectable & {
+  readonly to: ReadonlyArray<string>;
+  readonly toNot: ReadonlyArray<string>;
+};
+
+export const targetAllowed = (
+  rule: Targeted,
+  captures: RegExpExecArray,
+  targetPath: string,
+): boolean => {
+  if (rule.to.length > 0 && !matchesAny(rule.to, captures, targetPath)) return false;
+  if (rule.toNot.length > 0 && matchesAny(rule.toNot, captures, targetPath)) return false;
+  return true;
+};