@goodbones/core 0.1.0-beta.1

package/src/domain/architecture-config.ts

@@ -0,0 +1,370 @@
+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` is the target in one of three forms, and the form is its
+// dependency kind: a repo-relative resolved path is `local`, `{ external }`
+// names a third-party package, `{ builtin }` names a runtime module.
+const ImportProbeTarget = Schema.Union([
+  Schema.String,
+  Schema.Struct({ external: Schema.String }),
+  Schema.Struct({ builtin: Schema.String }),
+]);
+
+const ImportProbe = Schema.Struct({
+  from: Schema.String,
+  to: ImportProbeTarget,
+});
+
+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),
+  // Third-party packages this rule permits, by package name. An external
+  // target is judged by its package, never by where the language's resolver
+  // happened to find it on disk — `to`/`toNot` patterns are for the
+  // repository's own files.
+  externals: Schema.optionalKey(Schema.Array(Schema.String)),
+  // `external` is a third-party package, `builtin` a runtime module, `local`
+  // anything in the repository. Compared against what the resolver reports,
+  // never read off a path. Replaces dependency-cruiser's `dependencyTypes`,
+  // whose finer npm grades no rule in this repo distinguishes.
+  dependencyKind: Schema.optionalKey(Schema.Literals(["external", "local", "builtin"])),
+});
+
+// Which language pack resolves and parses the files a scope covers. A monorepo
+// needs several scopes even in one language — the web pass resolves `@/*` the
+// server pass does not — and a second language is one more scope. `options`
+// belong to the language: the policy carries them opaquely and the pack
+// validates them at load, so nothing here knows what a tsconfig is.
+const ResolveScope = Schema.Struct({
+  // A regular-expression source matched against the importing file's path.
+  files: Schema.String,
+  language: Schema.String,
+  options: Schema.optionalKey(Schema.Unknown),
+});
+
+export const ResolveConfig = Schema.Struct({
+  scopes: Schema.Array(ResolveScope),
+  // 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)),
+});
+
+// The autofix strategies a rule may name. Each is a rewrite in one language's
+// module syntax, so a language pack lists the ones it implements.
+export const ExportFix = Schema.Literals(["subpath-namespace-import"]);
+
+// 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"]);
+
+// `source`, when present, is a snippet the loading adapter parses: the probe
+// then holds only if a binding named `symbol` comes out of the parser and the
+// rule covers it, with every edge in the snippet taken to resolve to `to`.
+// Without it the probe is a synthetic binding of `symbol` and `kind`.
+const ExportProbe = Schema.Struct({
+  from: Schema.String,
+  to: Schema.String,
+  symbol: Schema.String,
+  kind: Schema.optionalKey(BindingKind),
+  source: Schema.optionalKey(Schema.String),
+});
+
+// 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, which a language pack may or may not implement:
+  // the loader refuses a rule naming one no loaded language does.
+  // `subpath-namespace-import` is an ES-module rewrite — `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(ExportFix),
+});
+
+// What a name was declared as. For an export site, the declaration that
+// introduced it; for a member site, the declaration it is written in.
+// `expression` is `export default <expr>`; `other` covers a namespace, an
+// `export =`, and a re-export, whose declaration is somewhere else. A second
+// language will want `struct`, `record`, `constant`, `module` here; they are
+// added with the pack that reads them, not before.
+export const DeclarationKind = Schema.Literals([
+  "function",
+  "class",
+  "variable",
+  "type",
+  "interface",
+  "enum",
+  "expression",
+  "other",
+]);
+
+// What kind of name a rule is about. `members` are the names written in a
+// named declaration — a type alias, an interface, a class body — under that
+// declaration's name (a port's method vocabulary); `calls` are called
+// identifiers (the hooks a tier may reach for). Which declarations a `members`
+// rule speaks to is `declares`' to say, so the vocabulary carries no language's
+// split between types and values.
+const MemberSubject = Schema.Literals(["members", "calls"]);
+
+// `source`, when present, is a snippet the loading adapter parses: the probe
+// then holds only if a site named `name` comes out of the parser and the rule
+// reports it — the declaration shape is the parser's to judge, not `in`'s.
+// Without it the probe is a synthetic site of `name` inside `in`, declared as
+// `declares`.
+const MemberProbe = Schema.Struct({
+  from: Schema.String,
+  name: Schema.String,
+  in: Schema.optionalKey(Schema.String),
+  declares: Schema.optionalKey(DeclarationKind),
+  source: 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,
+  // `members` only: which declaration's members are governed, by its name.
+  in: Schema.optionalKey(PatternList),
+  // `members` only: which kinds of declaration are governed. Omit for every
+  // kind — a type alias, an interface and a class body alike.
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+  // 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),
+});
+
+// One export site, as a probe states it: the name (`default` for a default
+// export, `*` for `export *`), its binding kind, and optionally what it was
+// declared as and whether it is a re-export.
+const SurfaceSite = Schema.Struct({
+  name: Schema.String,
+  kind: BindingKind,
+  declares: Schema.optionalKey(DeclarationKind),
+  reexport: Schema.optionalKey(Schema.Boolean),
+});
+
+// A whole surface, because `count` is about the file rather than a site.
+// `source`, when present, is parsed by the loading adapter instead.
+const SurfaceProbe = Schema.Struct({
+  from: Schema.String,
+  sites: Schema.optionalKey(Schema.Array(SurfaceSite)),
+  source: Schema.optionalKey(Schema.String),
+});
+
+// What a file may export. The selectors (`kinds`, `declares`, `reexport`,
+// `match`) say which sites the rule speaks to; exactly one demand says what is
+// required of them. No demand means `forbid`: a selected site is the violation.
+export const SurfaceRule = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: SurfaceProbe,
+  from: PatternList,
+  fromNot: Schema.optionalKey(PatternList),
+  kinds: Schema.optionalKey(Schema.Array(BindingKind)),
+  declares: Schema.optionalKey(Schema.Array(DeclarationKind)),
+  reexport: Schema.optionalKey(Schema.Boolean),
+  match: Schema.optionalKey(PatternList),
+  matchNot: Schema.optionalKey(PatternList),
+  forbid: Schema.optionalKey(Schema.Boolean),
+  // Names that are fine; a selected site named otherwise is the violation.
+  allow: Schema.optionalKey(PatternList),
+  // A regular-expression source every selected name must match.
+  convention: Schema.optionalKey(Schema.String),
+  // How many selected sites the file may have.
+  count: Schema.optionalKey(
+    Schema.Struct({
+      min: Schema.optionalKey(Schema.Finite),
+      max: Schema.optionalKey(Schema.Finite),
+    }),
+  ),
+});
+
+// A small synthetic graph the rule must report on: the edges, and any files
+// that take part without an edge (an orphan has none).
+const GraphProbe = Schema.Struct({
+  edges: Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
+  files: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+// Rules about the shape of the whole import graph, which no single file can
+// answer. The CLI evaluates them; the plugin, which sees one file at a time,
+// compiles and probes them so a vacuous one still fails to load.
+export const GraphCycleRule = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: GraphProbe,
+  within: PatternList,
+  withinNot: Schema.optionalKey(PatternList),
+});
+
+export const GraphOrphanRule = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: GraphProbe,
+  within: PatternList,
+  withinNot: Schema.optionalKey(PatternList),
+  // Files that are imported by nothing by design — the program's entry points.
+  entry: PatternList,
+});
+
+export const GraphReachRule = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  probe: GraphProbe,
+  from: PatternList,
+  fromNot: Schema.optionalKey(PatternList),
+  to: PatternList,
+  toNot: Schema.optionalKey(PatternList),
+  // The tier that was supposed to mediate: a path stepping onto a `via` file is
+  // allowed, so only a path that avoids every `via` is the violation.
+  via: Schema.optionalKey(PatternList),
+});
+
+export const GraphConfig = Schema.Struct({
+  cycles: Schema.optionalKey(Schema.Array(GraphCycleRule)),
+  orphans: Schema.optionalKey(Schema.Array(GraphOrphanRule)),
+  reach: Schema.optionalKey(Schema.Array(GraphReachRule)),
+});
+
+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 — `create-todo.handler` for
+  // `create-todo.handler.ts`, `handler` for `handler.go` — so `{base}.test.ts`
+  // or `{base}_test.go` names the sibling test in either language.
+  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 ImportProbeTarget = (typeof ImportProbeTarget)["Type"];
+export type ExportRule = (typeof ExportRule)["Type"];
+export type ExportProbe = (typeof ExportProbe)["Type"];
+export type BindingKind = (typeof BindingKind)["Type"];
+export type ExportFix = (typeof ExportFix)["Type"];
+export type MemberRule = (typeof MemberRule)["Type"];
+export type MemberProbe = (typeof MemberProbe)["Type"];
+export type MemberSubject = (typeof MemberSubject)["Type"];
+export type GraphProbe = (typeof GraphProbe)["Type"];
+export type GraphCycleRule = (typeof GraphCycleRule)["Type"];
+export type GraphOrphanRule = (typeof GraphOrphanRule)["Type"];
+export type GraphReachRule = (typeof GraphReachRule)["Type"];
+export type GraphConfig = (typeof GraphConfig)["Type"];
+export type DeclarationKind = (typeof DeclarationKind)["Type"];
+export type SurfaceRule = (typeof SurfaceRule)["Type"];
+export type SurfaceProbe = (typeof SurfaceProbe)["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"];
+
+// The file pattern an open folder's layout rule carries: it admits any name,
+// so it claims the folder without policing it. Coverage counts it apart.
+export const OPEN_LAYOUT = "^.*$";
+
+export const patternsOf = (patterns: string | ReadonlyArray<string>): ReadonlyArray<string> =>
+  typeof patterns === "string" ? [patterns] : patterns;

package/src/domain/architecture-error.ts

@@ -0,0 +1,59 @@
+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}`;
+  }
+}
+
+// A `resolve.scopes` entry a language pack cannot build a resolver from: options
+// it does not understand, or a language no pack answers to. Raised by the pack,
+// without the config path, which the loader adds when it reports it.
+export class ScopeInvalid extends Schema.TaggedErrorClass<ScopeInvalid>("ScopeInvalid")(
+  "ScopeInvalid",
+  {
+    files: Schema.String,
+    language: Schema.String,
+    detail: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `resolve scope ${JSON.stringify(this.files)} (${this.language}): ${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/facts.ts

@@ -0,0 +1,47 @@
+import type { BindingKind, DeclarationKind, MemberSubject } from "./architecture-config.js";
+
+// What a policy can know about one source file, read once. Both adapters
+// produce this vocabulary — the plugin from oxlint's syntax tree, the CLI from
+// TypeScript's — which is what keeps them answerable to the same core rather
+// than to each other. A rule is evaluated against these and nothing else.
+
+// 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;
+};
+
+// One declared or called name. For `members`, the declaration it is written in
+// — its name and what it was declared as (`type`, `interface`, `class`); both
+// absent for `calls`.
+export type MemberSite = {
+  readonly file: string;
+  readonly subject: MemberSubject;
+  readonly name: string;
+  readonly in?: string;
+  readonly declares?: DeclarationKind;
+};
+
+// One name a file offers, at its top level: `default` for a default export,
+// `*` for `export *`, the exported (not the local) name otherwise. `declares`
+// is what it was declared as when the declaration is in this file, and `other`
+// for a re-export, whose declaration is elsewhere.
+export type ExportSite = {
+  readonly file: string;
+  readonly name: string;
+  readonly kind: BindingKind;
+  readonly declares: DeclarationKind;
+  readonly reexport: boolean;
+};
+
+export type SourceFacts = {
+  // One entry per import edge, in source order. An edge appears once even if it
+  // carries several bindings.
+  readonly specifiers: ReadonlyArray<string>;
+  // The names pulled across each edge, keyed by specifier.
+  readonly bindings: ReadonlyMap<string, ReadonlyArray<Binding>>;
+  readonly memberSites: ReadonlyArray<MemberSite>;
+  // In source order; a file's whole surface, top-level statements only.
+  readonly exportSites: ReadonlyArray<ExportSite>;
+};

package/src/domain/violation.ts

@@ -0,0 +1,24 @@
+export type ViolationKind = "import" | "export" | "structure" | "member" | "surface" | "graph";
+
+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,136 @@
+// The core's public surface: the manifest vocabulary, the evaluators per
+// family, the ports a language pack implements, and the loader that turns a
+// manifest into a policy. A host composes these with a language pack and the
+// live file system; a language pack implements the ports. Nothing here names a
+// language. The fakes are under `@goodbones/core/testing`.
+export {
+  type Baseline,
+  type BaselineFilter,
+  baselineOf,
+  decodeBaseline,
+  EMPTY_BASELINE,
+  makeBaselineFilter,
+  serializeBaseline,
+  staleEntriesOf,
+  unbaselined,
+} from "./core/baseline.js";
+export {
+  type Coverage,
+  type CoverageFamily,
+  type CoverageFloors,
+  coverageOf,
+  coverageShortfalls,
+  fractionsOf,
+} from "./core/coverage.js";
+export {
+  type BindingEdge,
+  type CompiledExportRule,
+  compileExportRule,
+  compileExportRules,
+  evaluateBindingEdge,
+  evaluateSelectedBindings,
+  exportRulesFailingTheirProbe,
+  exportRulesSelecting,
+  type ExportViolation,
+  type SelectedExportRule,
+} from "./core/exports.js";
+export {
+  type CompiledGraph,
+  compileGraphRules,
+  EMPTY_GRAPH_RULES,
+  evaluateGraph,
+  type Graph,
+  graphRulesFailingTheirProbe,
+  hasGraphRules,
+} from "./core/graph.js";
+export {
+  type CompiledImportRule,
+  compileImportRule,
+  compileImportRules,
+  evaluateImportEdge,
+  evaluateSelectedEdge,
+  type ImportEdge,
+  probeTargetOf,
+  rulesFailingTheirProbe,
+  rulesSelecting,
+  type SelectedRule,
+} from "./core/imports.js";
+export {
+  type CompiledMemberRule,
+  compileMemberRules,
+  evaluateMemberSite,
+  memberRulesFailingTheirProbe,
+  memberRulesSelecting,
+} from "./core/members.js";
+export {
+  type CompiledStructure,
+  compileStructure,
+  EMPTY_STRUCTURE,
+  evaluateStructure,
+  requiredSiblingsOf,
+  structureRulesFailingTheirProbe,
+} from "./core/structure.js";
+export {
+  type CompiledSurfaceRule,
+  compileSurfaceRules,
+  evaluateSurface,
+  surfaceRulesFailingTheirProbe,
+  surfaceRulesSelecting,
+} from "./core/surface.js";
+export {
+  type BindingKind,
+  type DeclarationKind,
+  type ExportFix,
+  type ExportRule,
+  type GraphConfig,
+  type GraphCycleRule,
+  type GraphOrphanRule,
+  type GraphReachRule,
+  type ImportProbe,
+  type ImportProbeTarget,
+  type ImportRule,
+  type MemberRule,
+  type MemberSubject,
+  type ResolveConfig,
+  type ResolveScope,
+  type StructureConfig,
+  type SurfaceRule,
+} from "./domain/architecture-config.js";
+export {
+  ConfigInvalid,
+  ImportUnresolved,
+  PatternInvalid,
+  ScopeInvalid,
+} from "./domain/architecture-error.js";
+export {
+  type Binding,
+  type ExportSite,
+  type MemberSite,
+  type SourceFacts,
+} from "./domain/facts.js";
+export {
+  fingerprintOf,
+  formatMessage,
+  type Violation,
+  type ViolationKind,
+} from "./domain/violation.js";
+export { makeFileSystemLive } from "./infrastructure/file-system-live.js";
+export { DEFAULT_CONFIG_FILENAME, readManifestFile } from "./infrastructure/manifest-file.js";
+export { listSourceFiles, 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 DecodedManifest,
+  decodeManifest,
+  type Manifest,
+  type ManifestNode,
+  Manifest as ManifestSchema,
+} from "./manifest/manifest.js";
+export { type FactExtractor } from "./ports/fact-extractor.js";
+export { type FileSystem } from "./ports/file-system.js";
+export { type Language } from "./ports/language.js";
+export {
+  type DependencyKind,
+  type ModuleResolver,
+  type ResolvedTarget,
+} from "./ports/module-resolver.js";

package/src/infrastructure/fact-extractor-fake.ts

@@ -0,0 +1,28 @@
+import type { SourceFacts } from "../domain/facts.js";
+import type { FactExtractor } from "../ports/fact-extractor.js";
+
+const NOTHING: SourceFacts = {
+  specifiers: [],
+  bindings: new Map(),
+  memberSites: [],
+  exportSites: [],
+};
+
+// Keyed by the source text itself: a core test states what a snippet reads as
+// and never the parse, which has its own tests against the real extractor. A
+// snippet not staged reads as nothing — the shape of a form the extractor is
+// blind to, which is the case a source probe exists to catch.
+export const makeFactExtractorFake = (
+  facts: Readonly<Record<string, Partial<SourceFacts>>>,
+): FactExtractor => ({
+  factsOf: (file, text) => {
+    const found = facts[text];
+    if (found === undefined) return NOTHING;
+    return {
+      ...NOTHING,
+      ...found,
+      memberSites: (found.memberSites ?? []).map((site) => ({ ...site, file })),
+      exportSites: (found.exportSites ?? []).map((site) => ({ ...site, file })),
+    };
+  },
+});

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

@@ -0,0 +1,14 @@
+import type { FileSystem } from "../ports/file-system.js";
+
+// The files that exist, and optionally what some of them say. A file staged
+// with contents exists; one staged by name alone exists and reads as nothing.
+export const makeFileSystemFake = (
+  present: Iterable<string>,
+  contents: Readonly<Record<string, string>> = {},
+): FileSystem => {
+  const paths = new Set([...present, ...Object.keys(contents)]);
+  return {
+    exists: (repoRelativePath) => paths.has(repoRelativePath),
+    readText: (repoRelativePath) => contents[repoRelativePath] ?? null,
+  };
+};