oxlint-architecture-rules 0.1.0-beta.0

package/src/core/structure.ts

@@ -0,0 +1,348 @@
+import * as Result from "effect/Result";
+
+import type {
+  StructureConfig,
+  StructureFolder,
+  StructureNaming,
+  StructureParity,
+  StructureRoot,
+} from "../domain/architecture-config.js";
+import type { PatternInvalid } from "../domain/architecture-error.js";
+import type { Violation } from "../domain/violation.js";
+import type { FileSystem } from "../ports/file-system.js";
+import { compilePatterns } from "./patterns.js";
+
+export type CompiledStructureRoot = {
+  readonly name: string;
+  readonly message: string;
+  readonly path: ReadonlyArray<RegExp>;
+  readonly probe: string;
+};
+
+export type CompiledStructureFolder = {
+  readonly name: string;
+  readonly message: string;
+  readonly folder: ReadonlyArray<RegExp>;
+  readonly files: ReadonlyArray<RegExp>;
+  readonly probe: string;
+};
+
+export type CompiledStructureParity = {
+  readonly name: string;
+  readonly message: string;
+  readonly file: ReadonlyArray<RegExp>;
+  readonly fileNot: ReadonlyArray<RegExp>;
+  readonly requires: ReadonlyArray<string>;
+  readonly probe: string;
+};
+
+export type CompiledStructureNaming = {
+  readonly name: string;
+  readonly message: string;
+  readonly file: ReadonlyArray<RegExp>;
+  readonly fileNot: ReadonlyArray<RegExp>;
+  readonly subject: number;
+  readonly convention: RegExp | null;
+  readonly sameAs: number | null;
+  readonly probe: string;
+};
+
+export type CompiledStructure = {
+  readonly roots: ReadonlyArray<CompiledStructureRoot>;
+  readonly folders: ReadonlyArray<CompiledStructureFolder>;
+  readonly parity: ReadonlyArray<CompiledStructureParity>;
+  readonly naming: ReadonlyArray<CompiledStructureNaming>;
+};
+
+export const EMPTY_STRUCTURE: CompiledStructure = {
+  roots: [],
+  folders: [],
+  parity: [],
+  naming: [],
+};
+
+const compileRoot = (rule: StructureRoot): Result.Result<CompiledStructureRoot, PatternInvalid> => {
+  const path = compilePatterns(rule.name, "path", rule.path);
+  if (Result.isFailure(path)) return Result.fail(path.failure);
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    path: path.success,
+    probe: rule.probe.path,
+  });
+};
+
+const compileFolder = (
+  rule: StructureFolder,
+): Result.Result<CompiledStructureFolder, PatternInvalid> => {
+  const folder = compilePatterns(rule.name, "folder", rule.folder);
+  if (Result.isFailure(folder)) return Result.fail(folder.failure);
+  const files = compilePatterns(rule.name, "files", rule.files);
+  if (Result.isFailure(files)) return Result.fail(files.failure);
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    folder: folder.success,
+    files: files.success,
+    probe: rule.probe.path,
+  });
+};
+
+const compileParity = (
+  rule: StructureParity,
+): Result.Result<CompiledStructureParity, PatternInvalid> => {
+  const file = compilePatterns(rule.name, "file", rule.file);
+  if (Result.isFailure(file)) return Result.fail(file.failure);
+  const fileNot = compilePatterns(rule.name, "fileNot", rule.fileNot);
+  if (Result.isFailure(fileNot)) return Result.fail(fileNot.failure);
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    file: file.success,
+    fileNot: fileNot.success,
+    requires: [...rule.requires],
+    probe: rule.probe.path,
+  });
+};
+
+const compileNaming = (
+  rule: StructureNaming,
+): Result.Result<CompiledStructureNaming, PatternInvalid> => {
+  const file = compilePatterns(rule.name, "file", rule.file);
+  if (Result.isFailure(file)) return Result.fail(file.failure);
+  const fileNot = compilePatterns(rule.name, "fileNot", rule.fileNot);
+  if (Result.isFailure(fileNot)) return Result.fail(fileNot.failure);
+  const convention = compilePatterns(rule.name, "convention", rule.convention);
+  if (Result.isFailure(convention)) return Result.fail(convention.failure);
+  return Result.succeed({
+    name: rule.name,
+    message: rule.message,
+    file: file.success,
+    fileNot: fileNot.success,
+    subject: rule.subject,
+    convention: convention.success[0] ?? null,
+    sameAs: rule.sameAs ?? null,
+    probe: rule.probe.path,
+  });
+};
+
+const compileAll = <A, B>(
+  items: ReadonlyArray<A>,
+  compile: (item: A) => Result.Result<B, PatternInvalid>,
+): Result.Result<ReadonlyArray<B>, PatternInvalid> => {
+  const compiled: Array<B> = [];
+  for (const item of items) {
+    const one = compile(item);
+    if (Result.isFailure(one)) return Result.fail(one.failure);
+    compiled.push(one.success);
+  }
+  return Result.succeed(compiled);
+};
+
+export const compileStructure = (
+  config: StructureConfig | undefined,
+): Result.Result<CompiledStructure, PatternInvalid> => {
+  if (config === undefined) return Result.succeed(EMPTY_STRUCTURE);
+
+  const roots = compileAll(config.roots ?? [], compileRoot);
+  if (Result.isFailure(roots)) return Result.fail(roots.failure);
+  const folders = compileAll(config.folders ?? [], compileFolder);
+  if (Result.isFailure(folders)) return Result.fail(folders.failure);
+  const parity = compileAll(config.parity ?? [], compileParity);
+  if (Result.isFailure(parity)) return Result.fail(parity.failure);
+  const naming = compileAll(config.naming ?? [], compileNaming);
+  if (Result.isFailure(naming)) return Result.fail(naming.failure);
+
+  return Result.succeed({
+    roots: roots.success,
+    folders: folders.success,
+    parity: parity.success,
+    naming: naming.success,
+  });
+};
+
+const anyMatches = (patterns: ReadonlyArray<RegExp>, value: string): boolean =>
+  patterns.some((pattern) => pattern.test(value));
+
+const dirnameOf = (file: string): string => {
+  const cut = file.lastIndexOf("/");
+  return cut === -1 ? "" : file.slice(0, cut);
+};
+
+const basenameOf = (file: string): string => file.slice(file.lastIndexOf("/") + 1);
+
+// `{base}` is the filename minus its FINAL extension, so `create-todo.handler.ts`
+// yields `create-todo.handler` and `{base}.test.ts` names its sibling test. The
+// dot-delimited stereotype stays part of the base on purpose.
+const baseOf = (basename: string): string => {
+  const cut = basename.lastIndexOf(".");
+  return cut <= 0 ? basename : basename.slice(0, cut);
+};
+
+// A `../` in a required path is resolved against the file's own folder, which is
+// how a port three folders from its adapters names them.
+const resolveSibling = (folder: string, relative: string): string => {
+  const segments = folder === "" ? [] : folder.split("/");
+  for (const segment of relative.split("/")) {
+    if (segment === "..") segments.pop();
+    else if (segment !== "." && segment !== "") segments.push(segment);
+  }
+  return segments.join("/");
+};
+
+export const requiredSiblingsOf = (
+  rule: CompiledStructureParity,
+  file: string,
+): ReadonlyArray<string> => {
+  const base = baseOf(basenameOf(file));
+  const folder = dirnameOf(file);
+  return rule.requires.map((template) =>
+    resolveSibling(folder, template.replaceAll("{base}", base)),
+  );
+};
+
+type NamingMatch = {
+  readonly subject: string;
+  readonly expected: string | null;
+  // Whether the rule asked for a comparison at all. Without this a `sameAs`
+  // naming a group the pattern never fills would fall back to "no convention"
+  // and admit every name — vacuous, in the one family added to stop that.
+  readonly comparing: boolean;
+};
+
+// The rule's pattern carries capture groups; `subject` says which one holds the
+// name being judged, and `sameAs` which one it has to equal.
+const firstNamingMatch = (rule: CompiledStructureNaming, file: string): NamingMatch | null => {
+  for (const pattern of rule.file) {
+    const found = pattern.exec(file);
+    if (found === null) continue;
+    const subject = found[rule.subject];
+    if (subject === undefined) continue;
+    return {
+      subject,
+      expected: rule.sameAs === null ? null : (found[rule.sameAs] ?? null),
+      comparing: rule.sameAs !== null,
+    };
+  }
+  return null;
+};
+
+const namingSatisfied = (rule: CompiledStructureNaming, named: NamingMatch): boolean =>
+  named.comparing
+    ? named.expected !== null && named.subject === named.expected
+    : rule.convention === null || rule.convention.test(named.subject);
+
+export const evaluateStructure = (
+  structure: CompiledStructure,
+  fileSystem: FileSystem,
+  file: string,
+): ReadonlyArray<Violation> => {
+  const violations: Array<Violation> = [];
+  const folder = dirnameOf(file);
+  const basename = basenameOf(file);
+
+  for (const rule of structure.parity) {
+    if (!anyMatches(rule.file, file) || anyMatches(rule.fileNot, file)) continue;
+    for (const sibling of requiredSiblingsOf(rule, file)) {
+      if (fileSystem.exists(sibling)) continue;
+      violations.push({
+        kind: "structure",
+        ruleName: rule.name,
+        message: rule.message,
+        file,
+        subject: sibling,
+      });
+    }
+  }
+
+  for (const rule of structure.naming) {
+    if (anyMatches(rule.fileNot, file)) continue;
+    const named = firstNamingMatch(rule, file);
+    if (named === null || namingSatisfied(rule, named)) continue;
+    violations.push({
+      kind: "structure",
+      ruleName: rule.name,
+      message: rule.message,
+      file,
+      subject: named.subject,
+    });
+  }
+
+  const governing = structure.folders.filter((rule) => anyMatches(rule.folder, folder));
+
+  if (governing.length > 0) {
+    if (!governing.some((rule) => anyMatches(rule.files, basename))) {
+      const rule = governing[0];
+      if (rule !== undefined) {
+        violations.push({
+          kind: "structure",
+          ruleName: rule.name,
+          message: rule.message,
+          file,
+          subject: basename,
+        });
+      }
+    }
+    return violations;
+  }
+
+  // No folder rule governs this folder at all. Inside a taxonomy root that means
+  // the folder itself is not part of the taxonomy — the stray-folder case a
+  // per-file check would otherwise miss entirely.
+  const root = structure.roots.find((candidate) => anyMatches(candidate.path, file));
+  if (root !== undefined) {
+    violations.push({
+      kind: "structure",
+      ruleName: root.name,
+      message: root.message,
+      file,
+      subject: folder,
+    });
+  }
+
+  return violations;
+};
+
+// A structure rule proves itself the same way the other families do: on a path
+// it must reject. Parity is checked structurally — that the rule still selects
+// its probe and still renders a sibling to demand — because asking the real
+// filesystem at config-load time would make the guard depend on a fixture.
+export const structureRulesFailingTheirProbe = (
+  structure: CompiledStructure,
+): ReadonlyArray<string> => {
+  const failing: Array<string> = [];
+
+  for (const rule of structure.naming) {
+    const named = firstNamingMatch(rule, rule.probe);
+    if (named === null || namingSatisfied(rule, named) || anyMatches(rule.fileNot, rule.probe)) {
+      failing.push(rule.name);
+    }
+  }
+
+  for (const rule of structure.parity) {
+    const selects = anyMatches(rule.file, rule.probe) && !anyMatches(rule.fileNot, rule.probe);
+    const demands = requiredSiblingsOf(rule, rule.probe).some((sibling) => sibling.length > 0);
+    if (!selects || !demands) failing.push(rule.name);
+  }
+
+  const layoutOnly = { ...structure, parity: [] };
+  const reported = (file: string): ReadonlyArray<string> =>
+    evaluateStructure(layoutOnly, { exists: () => true }, file).map(
+      (violation) => violation.ruleName,
+    );
+
+  for (const rule of structure.folders) {
+    // A folder that admits any name claims its folder but states no policy, so
+    // there is nothing for a probe to demonstrate.
+    if (rule.files.some((pattern) => pattern.source === "^.*$")) continue;
+    // The rule must govern its probe's folder AND the folder's admitted set —
+    // the union of every governing rule — must still reject the basename.
+    const governs = anyMatches(rule.folder, dirnameOf(rule.probe));
+    if (!governs || reported(rule.probe).length === 0) failing.push(rule.name);
+  }
+  for (const rule of structure.roots) {
+    if (!reported(rule.probe).includes(rule.name)) failing.push(rule.name);
+  }
+
+  return failing;
+};

package/src/domain/architecture-config.ts

@@ -0,0 +1,206 @@
+import * as Schema from "effect/Schema";
+
+// Every pattern in this config is a JavaScript regular-expression source string
+// matched against a repo-relative, forward-slash path — the same vocabulary
+// dependency-cruiser rules are written in, so a rule ported from there keeps its
+// pattern character-for-character. A list matches when ANY member matches.
+const PatternList = Schema.Union([Schema.String, Schema.Array(Schema.String)]);
+
+// An import edge is a violation when the importer matches `from` (and not
+// `fromNot`) AND the resolved target matches `to` (and not `toNot`). Omitting
+// `to` means "any target", which is how a rule expresses "this folder may not
+// import anything outside its allowlist" as a single `toNot`.
+// A synthetic edge this rule must report. Every rule carries one: a configured
+// rule that reports nothing is indistinguishable from a clean codebase, and that
+// is the failure this package exists to make impossible. `from` is a repo-relative
+// importer path, `to` a repo-relative RESOLVED target (a `node_modules/...` path
+// for an external, `node:<name>` for a builtin).
+const ImportProbe = Schema.Struct({
+  from: Schema.String,
+  to: Schema.String,
+});
+
+export const ImportRule = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: ImportProbe,
+  from: PatternList,
+  fromNot: Schema.optionalKey(PatternList),
+  to: Schema.optionalKey(PatternList),
+  toNot: Schema.optionalKey(PatternList),
+  // `external` is a target inside node_modules, `builtin` a node: module,
+  // `local` anything else. Replaces dependency-cruiser's `dependencyTypes`,
+  // whose finer npm grades no rule in this repo distinguishes.
+  dependencyKind: Schema.optionalKey(Schema.Literals(["external", "local", "builtin"])),
+});
+
+// Resolution is tsconfig-driven, and this monorepo needs two: the web/components
+// pass resolves `@/*` and `@org/components/*` that the server pass does not.
+const ResolveScope = Schema.Struct({
+  files: Schema.String,
+  tsconfig: Schema.String,
+});
+
+export const ResolveConfig = Schema.Struct({
+  scopes: Schema.Array(ResolveScope),
+  extensions: Schema.optionalKey(Schema.Array(Schema.String)),
+  conditionNames: Schema.optionalKey(Schema.Array(Schema.String)),
+  mainFields: Schema.optionalKey(Schema.Array(Schema.String)),
+  // An edge nobody can resolve is an edge no rule can police, which is the
+  // silent-vacuity failure this whole package exists to prevent. Default loud.
+  unresolved: Schema.optionalKey(Schema.Literals(["error", "off"])),
+  ignoreUnresolved: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+// Which binding form an import site used. A rule that fences off a factory
+// function cares about `named`; one steering people to namespace subpath imports
+// cares that `named` was used at all.
+const BindingKind = Schema.Literals(["named", "default", "namespace"]);
+
+const ExportProbe = Schema.Struct({
+  from: Schema.String,
+  to: Schema.String,
+  symbol: Schema.String,
+  kind: Schema.optionalKey(BindingKind),
+});
+
+// Where a given *exported symbol* may be imported. `imports` asks whether one
+// file may reach another at all; this asks which names it may pull across when
+// it does — the distinction a path rule cannot make, because every importer of a
+// barrel resolves to the same file.
+export const ExportRule = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: ExportProbe,
+  from: PatternList,
+  fromNot: Schema.optionalKey(PatternList),
+  to: PatternList,
+  toNot: Schema.optionalKey(PatternList),
+  // Exact exported names. Omit to mean "any name", which is how a rule bans a
+  // whole binding form (every named import from a package barrel, say).
+  symbols: Schema.optionalKey(Schema.Array(Schema.String)),
+  // Defaults to ["named"] — the discriminating form for every rule of this shape
+  // written so far.
+  kinds: Schema.optionalKey(Schema.Array(BindingKind)),
+  // A named autofix strategy. `subpath-namespace-import` rewrites
+  // `import { A, B as C } from "pkg"` into `import * as A from "pkg/A"` /
+  // `import * as C from "pkg/B"`, for packages that publish each module as its own
+  // subpath. A rule carrying a fix reports once per declaration rather than once
+  // per symbol, because the fix rewrites the whole declaration.
+  fix: Schema.optionalKey(Schema.Literals(["subpath-namespace-import"])),
+});
+
+// What kind of declared name a rule is about. `type-members` are the members of
+// a type alias (a port's method vocabulary); `calls` are called identifiers (the
+// hooks a tier may reach for).
+const MemberSubject = Schema.Literals(["type-members", "calls"]);
+
+const MemberProbe = Schema.Struct({
+  from: Schema.String,
+  name: Schema.String,
+  in: Schema.optionalKey(Schema.String),
+});
+
+// Which names a file is allowed to declare or call. This is the one family that
+// needs no module resolution: it is about the vocabulary inside a file, not the
+// edges leaving it.
+export const MemberRule = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: MemberProbe,
+  from: PatternList,
+  fromNot: Schema.optionalKey(PatternList),
+  subject: MemberSubject,
+  // `type-members` only: which declaration's members are governed.
+  in: Schema.optionalKey(PatternList),
+  // Which names the rule speaks to at all. Omit for "every one".
+  match: Schema.optionalKey(PatternList),
+  matchNot: Schema.optionalKey(PatternList),
+  // Names that are fine. A name the rule speaks to and this does not admit is
+  // the violation.
+  allow: Schema.optionalKey(PatternList),
+});
+
+const PathProbe = Schema.Struct({ path: Schema.String });
+
+// The file taxonomy, as three questions rather than one nested tree.
+//
+// `roots` marks the regions where layout is deny-by-default. `folders` says
+// which basenames each folder admits. `parity` says which siblings a file owes.
+// Keeping them apart is what removes the nested config's most fragile rule —
+// that a specific pattern must beat a `*` catch-all — because an exemption is
+// now a `fileNot` on the parity rule that would otherwise fire.
+const StructureRoot = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: PathProbe,
+  // A file under this path whose folder no `folders` rule governs is a file in a
+  // folder the taxonomy does not know about.
+  path: PatternList,
+});
+
+const StructureFolder = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: PathProbe,
+  // Matched against the file's folder, repo-relative, with no trailing slash.
+  folder: PatternList,
+  // Basenames this folder admits. Anything else is the violation.
+  files: PatternList,
+});
+
+const StructureParity = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: PathProbe,
+  file: PatternList,
+  fileNot: Schema.optionalKey(PatternList),
+  // Paths that must exist, relative to the file's own folder. `{base}` is the
+  // filename minus its final extension, so `{base}.test.ts` beside
+  // `create-todo.handler.ts` means `create-todo.handler.test.ts`.
+  requires: Schema.Array(Schema.String),
+});
+
+// What shape the variable part of a name may take. `folders` says which
+// stereotypes a folder admits; this says what the concept name in front of the
+// stereotype may look like — the degree of freedom a taxonomy alone leaves open.
+const StructureNaming = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: PathProbe,
+  // Matched against the whole repo-relative path, and carrying capture groups:
+  // `subject` says which of them holds the name being judged.
+  file: PatternList,
+  fileNot: Schema.optionalKey(PatternList),
+  subject: Schema.Finite,
+  // The shape the subject must have. Exactly one of these.
+  convention: Schema.optionalKey(Schema.String),
+  // A capture group the subject must equal, for "named after its folder".
+  sameAs: Schema.optionalKey(Schema.Finite),
+});
+
+const StructureConfig = Schema.Struct({
+  roots: Schema.optionalKey(Schema.Array(StructureRoot)),
+  folders: Schema.optionalKey(Schema.Array(StructureFolder)),
+  parity: Schema.optionalKey(Schema.Array(StructureParity)),
+  naming: Schema.optionalKey(Schema.Array(StructureNaming)),
+});
+
+export type ImportRule = (typeof ImportRule)["Type"];
+export type ResolveConfig = (typeof ResolveConfig)["Type"];
+export type ResolveScope = (typeof ResolveScope)["Type"];
+export type ImportProbe = (typeof ImportProbe)["Type"];
+export type ExportRule = (typeof ExportRule)["Type"];
+export type ExportProbe = (typeof ExportProbe)["Type"];
+export type BindingKind = (typeof BindingKind)["Type"];
+export type MemberRule = (typeof MemberRule)["Type"];
+export type MemberProbe = (typeof MemberProbe)["Type"];
+export type MemberSubject = (typeof MemberSubject)["Type"];
+export type StructureConfig = (typeof StructureConfig)["Type"];
+export type StructureRoot = (typeof StructureRoot)["Type"];
+export type StructureFolder = (typeof StructureFolder)["Type"];
+export type StructureParity = (typeof StructureParity)["Type"];
+export type StructureNaming = (typeof StructureNaming)["Type"];
+
+export const patternsOf = (patterns: string | ReadonlyArray<string>): ReadonlyArray<string> =>
+  typeof patterns === "string" ? [patterns] : patterns;

package/src/domain/architecture-error.ts

@@ -0,0 +1,43 @@
+import * as Schema from "effect/Schema";
+
+// These errors surface through oxlint's plugin loader, which prints a stack and
+// nothing else. The `message` override is what turns "ConfigInvalid" into an
+// instruction the reader can act on.
+
+export class ConfigInvalid extends Schema.TaggedErrorClass<ConfigInvalid>("ConfigInvalid")(
+  "ConfigInvalid",
+  { configPath: Schema.String, detail: Schema.String },
+) {
+  override get message(): string {
+    return `${this.configPath}: ${this.detail}`;
+  }
+}
+
+export class PatternInvalid extends Schema.TaggedErrorClass<PatternInvalid>("PatternInvalid")(
+  "PatternInvalid",
+  {
+    ruleName: Schema.String,
+    field: Schema.String,
+    pattern: Schema.String,
+    detail: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `rule "${this.ruleName}" has an uncompilable ${this.field} pattern ${JSON.stringify(
+      this.pattern,
+    )}: ${this.detail}`;
+  }
+}
+
+export class ImportUnresolved extends Schema.TaggedErrorClass<ImportUnresolved>("ImportUnresolved")(
+  "ImportUnresolved",
+  {
+    fromFile: Schema.String,
+    specifier: Schema.String,
+    detail: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `${this.fromFile} imports "${this.specifier}", which does not resolve: ${this.detail}`;
+  }
+}

package/src/domain/violation.ts

@@ -0,0 +1,24 @@
+export type ViolationKind = "import" | "export" | "structure" | "member";
+
+export type Violation = {
+  readonly kind: ViolationKind;
+  readonly ruleName: string;
+  readonly message: string;
+  // Repo-relative, forward slashes.
+  readonly file: string;
+  // The other end of the violated relationship: the resolved import target, the
+  // restricted symbol, the missing sibling, the disallowed member. `null` when
+  // the file alone is the violation.
+  readonly subject: string | null;
+};
+
+// Deliberately excludes line and column so an entry survives ordinary edits to
+// the file it names — a baseline keyed on positions would go stale on the first
+// reformat and silently re-admit a violation it was never meant to cover.
+export const fingerprintOf = (violation: Violation): string =>
+  [violation.kind, violation.ruleName, violation.file, violation.subject ?? ""].join("|");
+
+// `{name}` in a message is replaced with the subject, so a rule can quote the
+// offending symbol without the config needing a callback.
+export const formatMessage = (violation: Violation): string =>
+  `[${violation.ruleName}] ${violation.message.replaceAll("{name}", violation.subject ?? "")}`;

package/src/index.ts

@@ -0,0 +1,28 @@
+export {
+  type CompiledImportRule,
+  compileImportRule,
+  compileImportRules,
+  evaluateImportEdge,
+  type ImportEdge,
+} from "./core/imports.js";
+export {
+  type ImportRule,
+  type ResolveConfig,
+  type ResolveScope,
+} from "./domain/architecture-config.js";
+export { ConfigInvalid, ImportUnresolved, PatternInvalid } from "./domain/architecture-error.js";
+export {
+  fingerprintOf,
+  formatMessage,
+  type Violation,
+  type ViolationKind,
+} from "./domain/violation.js";
+export { makeModuleResolverFake } from "./infrastructure/module-resolver-fake.js";
+export { makeModuleResolverLive } from "./infrastructure/module-resolver-live.js";
+export { type LoweredRules, lowerManifest } from "./manifest/compile.js";
+export {
+  type Manifest,
+  type ManifestNode,
+  Manifest as ManifestSchema,
+} from "./manifest/manifest.js";
+export { type ModuleResolver, type ResolvedTarget } from "./ports/module-resolver.js";

package/src/infrastructure/file-system-fake.ts

@@ -0,0 +1,6 @@
+import type { FileSystem } from "../ports/file-system.js";
+
+export const makeFileSystemFake = (present: Iterable<string>): FileSystem => {
+  const paths = new Set(present);
+  return { exists: (repoRelativePath) => paths.has(repoRelativePath) };
+};

package/src/infrastructure/file-system-live.ts

@@ -0,0 +1,20 @@
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+
+import type { FileSystem } from "../ports/file-system.js";
+
+// One lint run asks about the same sibling many times — every handler in a
+// folder resolves the same `../../infrastructure/...` shape — so the answers are
+// memoised for the life of the run.
+export const makeFileSystemLive = (repoRoot: string): FileSystem => {
+  const cache = new Map<string, boolean>();
+  return {
+    exists: (repoRelativePath) => {
+      const cached = cache.get(repoRelativePath);
+      if (cached !== undefined) return cached;
+      const answer = existsSync(path.resolve(repoRoot, repoRelativePath));
+      cache.set(repoRelativePath, answer);
+      return answer;
+    },
+  };
+};