oxlint-architecture-rules 0.1.0-beta.0

package/build/esm/manifest/manifest.js

@@ -0,0 +1,120 @@
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { ResolveConfig } from "../domain/architecture-config.js";
+import { ConfigInvalid } from "../domain/architecture-error.js";
+// A manifest is a tree of nodes keyed by path pattern, where everything the
+// architecture says about a part of the tree is written at that part of the tree.
+// A node is a folder (it has `children` and/or `files`) or a file (its key names
+// a filename pattern).
+//
+// The default is tight: a folder admits only the children it lists, and a node
+// may import only what it or an ancestor allows. Laxity is opted into, by name,
+// at the node that wants it.
+const Globs = Schema.Union([Schema.String, Schema.Array(Schema.String)]);
+// A prohibition. `match`/`matchNot` describe the target; `except` names the
+// importers it does not apply to. The exemption is declared by the author of the
+// prohibition, in the same breath — a descendant still cannot opt itself out.
+const Denial = Schema.Struct({
+    match: Globs,
+    matchNot: Schema.optionalKey(Globs),
+    except: Schema.optionalKey(Globs),
+    message: Schema.String,
+});
+// Outbound: what this part of the tree may reach.
+const Imports = Schema.Struct({
+    message: Schema.optionalKey(Schema.String),
+    // Repo-relative globs, after alias expansion. A target matching none of these
+    // is the violation — so widening is something you do by name, in the open.
+    allow: Schema.optionalKey(Globs),
+    // npm package names. Omit to inherit; `[]` to forbid every external.
+    external: Schema.optionalKey(Schema.Array(Schema.String)),
+    // Checked before `allow`, and wins over it. This is how a rule keeps a
+    // specific, better message for a mistake the allowlist would also catch.
+    deny: Schema.optionalKey(Schema.Array(Denial)),
+    // The one widening mechanism: stop inheriting ancestors' allowances. Inherited
+    // `deny` entries are unaffected — a prohibition only ever accumulates.
+    reset: Schema.optionalKey(Schema.Boolean),
+    // "This tier has no allowlist yet; only the prohibitions below apply." Implies
+    // `reset`. Required whenever a node states `imports` without an `allow`, so
+    // that an untightened tier is a sentence someone wrote rather than a gap in
+    // the config — and so `grep unrestricted` is the adoption backlog.
+    unrestricted: Schema.optionalKey(Schema.Boolean),
+});
+// Inbound: who may reach this part of the tree. Four of the rules governing
+// `domain/` are of this shape — "*.root-ops.ts is private to command handlers" —
+// and stating them here is what stops them being a distant rule with a growing
+// exclusion list on its `from` side.
+const ImportedBy = Schema.Struct({
+    message: Schema.String,
+    allow: Globs,
+    // Targets inside this node's subtree the restriction does not cover — the
+    // module barrel is the obvious one: a module is private except through it.
+    matchNot: Schema.optionalKey(Globs),
+});
+// What shape the variable part of a name must have. A folder's `children` keys
+// already say which stereotypes it admits; this says what the concept name in
+// front of the stereotype may look like, which is the degree of freedom a
+// taxonomy alone leaves open.
+//
+// `like` names an ancestor capture the name must equal — a subdomain folder's
+// root is named after the folder, and nothing else could say so.
+const Naming = Schema.Union([
+    Schema.Literals(["kebab-case", "camelCase", "PascalCase", "snake_case"]),
+    Schema.Struct({ regex: Schema.String, message: Schema.optionalKey(Schema.String) }),
+    Schema.Struct({ like: Schema.String, message: Schema.optionalKey(Schema.String) }),
+]);
+const Members = Schema.Struct({
+    message: Schema.String,
+    subject: Schema.Literals(["type-members", "calls"]),
+    in: Schema.optionalKey(Globs),
+    match: Schema.optionalKey(Globs),
+    matchNot: Schema.optionalKey(Globs),
+    allow: Schema.optionalKey(Globs),
+});
+// Which importers may name a given exported symbol. A path rule cannot say
+// this: every importer of a barrel resolves to the same file, so only the
+// imported name separates a bus factory from the Tag beside it.
+const ExportRestriction = Schema.Struct({
+    name: Schema.String,
+    message: Schema.String,
+    // The module the symbols come from, matched against its RESOLVED path.
+    module: Globs,
+    // Exact exported names. Omit to mean "any named import from that module",
+    // which is how a rule bans a binding form rather than a name.
+    symbols: Schema.optionalKey(Schema.Array(Schema.String)),
+    except: Schema.optionalKey(Globs),
+    fix: Schema.optionalKey(Schema.Literal("subpath-namespace-import")),
+});
+const ManifestNodeSchema = Schema.suspend(() => Schema.Struct({
+    message: Schema.optionalKey(Schema.String),
+    partial: Schema.optionalKey(Schema.Boolean),
+    layout: Schema.optionalKey(Schema.Literal("open")),
+    name: Schema.optionalKey(Naming),
+    imports: Schema.optionalKey(Imports),
+    importedBy: Schema.optionalKey(ImportedBy),
+    members: Schema.optionalKey(Schema.Array(Members)),
+    requires: Schema.optionalKey(Schema.Array(Schema.String)),
+    requiresNot: Schema.optionalKey(Schema.Array(Schema.String)),
+    children: Schema.optionalKey(Schema.Record(Schema.String, ManifestNodeSchema)),
+}));
+export const Manifest = Schema.Struct({
+    // How an import specifier becomes a file. Every pattern below is matched
+    // against a resolved path, so this is what makes the rest of the file mean
+    // anything.
+    resolve: ResolveConfig,
+    baseline: Schema.optionalKey(Schema.String),
+    // Prohibitions that hold everywhere, declared once. `not-to-spec` and the
+    // "this driver lives in one package" rules are statements about the whole
+    // repo, not about a tier — putting them on every tree root would be six
+    // copies and a seventh forgotten.
+    deny: Schema.optionalKey(Schema.Array(Denial)),
+    exports: Schema.optionalKey(Schema.Array(ExportRestriction)),
+    // Shorthands expanded in every glob, so a pattern reads the way the repo's own
+    // imports do rather than repeating `packages/server/src` on every line.
+    aliases: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+    tree: Schema.Record(Schema.String, ManifestNodeSchema),
+});
+export const globsOf = (globs) => typeof globs === "string" ? [globs] : globs;
+const decode = Schema.decodeUnknownResult(Manifest);
+export const decodeManifest = (configPath, input) => Result.mapError(decode(input), (issue) => new ConfigInvalid({ configPath, detail: String(issue) }));
+//# sourceMappingURL=manifest.js.map

package/build/esm/manifest/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/manifest/manifest.ts"],"names":[],"mappings":"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"}

package/build/esm/ports/file-system.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file-system.js.map

package/build/esm/ports/file-system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-system.js","sourceRoot":"","sources":["../../../src/ports/file-system.ts"],"names":[],"mappings":""}

package/build/esm/ports/module-resolver.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=module-resolver.js.map

package/build/esm/ports/module-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-resolver.js","sourceRoot":"","sources":["../../../src/ports/module-resolver.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "oxlint-architecture-rules",
+  "version": "0.1.0-beta.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Architecture policy as configuration, enforced as one oxlint plugin: import boundaries over resolved module paths, restricted export sites, folder taxonomy with sibling parity, and declared-member allowlists.",
+  "author": "zacharyweidenbach",
+  "keywords": [
+    "oxlint",
+    "oxlint-plugin",
+    "architecture",
+    "lint",
+    "import-boundaries",
+    "hexagonal",
+    "monorepo",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dataquail/oxlint-utils.git",
+    "directory": "packages/oxlint-architecture-rules"
+  },
+  "homepage": "https://dataquail.github.io/oxlint-utils",
+  "bugs": {
+    "url": "https://github.com/dataquail/oxlint-utils/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/dts/index.d.ts",
+      "default": "./build/esm/index.js"
+    },
+    "./plugin": {
+      "types": "./build/dts/adapters/oxlint/plugin.d.ts",
+      "default": "./build/esm/adapters/oxlint/plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./build/dts/index.d.ts",
+  "bin": {
+    "architecture": "./build/esm/adapters/cli/main.js"
+  },
+  "files": [
+    "build/dts",
+    "build/esm",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "dependencies": {
+    "effect": "4.0.0-beta.94",
+    "typescript": "^5.9.3",
+    "unrs-resolver": "^1.12.2"
+  },
+  "peerDependencies": {
+    "oxlint": ">=1.77.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.4",
+    "oxlint": "1.77.0"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "check": "tsc -b tsconfig.json",
+    "clean": "rm -rf build .tsbuildinfo",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage"
+  }
+}

package/src/adapters/cli/main.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+
+import { run } from "./run.js";
+
+const exit = await Effect.runPromiseExit(run(process.cwd(), process.argv.slice(2)));
+
+if (Exit.isFailure(exit)) {
+  // The expected failures carry their own sentence; anything else is a defect
+  // and deserves the full cause.
+  const squashed = Cause.squash(exit.cause);
+  const message =
+    typeof squashed === "object" && squashed !== null && "message" in squashed
+      ? String(squashed.message)
+      : Cause.pretty(exit.cause);
+  process.stderr.write(`\n${message}\n`);
+  process.exitCode = 1;
+}

package/src/adapters/cli/run.ts

@@ -0,0 +1,270 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+
+import {
+  type Baseline,
+  baselineOf,
+  decodeBaseline,
+  EMPTY_BASELINE,
+  serializeBaseline,
+  staleEntriesOf,
+  unbaselined,
+} from "../../core/baseline.js";
+import { evaluateSelectedBindings, exportRulesSelecting } from "../../core/exports.js";
+import { evaluateSelectedEdge, rulesSelecting } from "../../core/imports.js";
+import { evaluateMemberSite, memberRulesSelecting } from "../../core/members.js";
+import { evaluateStructure, requiredSiblingsOf } from "../../core/structure.js";
+import { fingerprintOf, formatMessage, type Violation } from "../../domain/violation.js";
+import { type LoadedPolicy, loadPolicy } from "../oxlint/config-loader.js";
+import { sourceFactsOf } from "./source-facts.js";
+import { listSourceFiles } from "./source-files.js";
+
+// The policy, run with no linter in the loop.
+//
+// oxlint's JS plugin API is alpha, and a policy that can only be evaluated by
+// one alpha host is a policy with a single point of failure. This adapter is the
+// second way to ask the same question — and the only way to write a baseline,
+// since that needs every finding at once rather than one file at a time.
+//
+// It covers all four families. The two that need a syntax tree read TypeScript's
+// rather than oxlint's; both adapters meet at the same vocabulary — a specifier,
+// a binding, a member site — so they answer to the same core rather than to each
+// other.
+
+export type CliFailure = { readonly _tag: "CliFailure"; readonly message: string };
+
+const fail = (message: string): CliFailure => ({ _tag: "CliFailure", message });
+
+export type Findings = {
+  readonly violations: ReadonlyArray<Violation>;
+  readonly unresolved: ReadonlyArray<string>;
+  readonly files: number;
+};
+
+export const collectFindings = (policy: LoadedPolicy, roots: ReadonlyArray<string>): Findings => {
+  const files = listSourceFiles(policy.repoRoot, roots);
+  const violations: Array<Violation> = [];
+  const unresolved: Array<string> = [];
+
+  for (const file of files) {
+    for (const violation of evaluateStructure(policy.structure, policy.fileSystem, file)) {
+      violations.push(violation);
+    }
+
+    const selectedImports = rulesSelecting(policy.importRules, file);
+    const selectedExports = exportRulesSelecting(policy.exportRules, file);
+    const selectedMembers = memberRulesSelecting(policy.memberRules, file);
+    if (selectedImports.length + selectedExports.length + selectedMembers.length === 0) continue;
+
+    const facts = sourceFactsOf(policy.repoRoot, file);
+
+    for (const site of facts.memberSites) {
+      for (const violation of evaluateMemberSite(selectedMembers, site)) violations.push(violation);
+    }
+
+    for (const specifier of facts.specifiers) {
+      const edge = { importer: file, specifier };
+
+      const imported = evaluateSelectedEdge(selectedImports, policy.resolver, edge);
+      if (Result.isFailure(imported)) {
+        if (policy.config.resolve.unresolved === "off") continue;
+        if (policy.ignoreUnresolved.some((pattern) => pattern.test(specifier))) continue;
+        unresolved.push(`${file} → ${specifier} (${imported.failure.detail})`);
+        continue;
+      }
+      for (const violation of imported.success) violations.push(violation);
+
+      const bound = facts.bindings.get(specifier) ?? [];
+      const exported = evaluateSelectedBindings(selectedExports, policy.resolver, {
+        ...edge,
+        bindings: bound,
+      });
+      if (!Result.isFailure(exported)) {
+        for (const { violation } of exported.success) violations.push(violation);
+      }
+    }
+  }
+
+  return { violations, unresolved, files: files.length };
+};
+
+const baselinePathOf = (policy: LoadedPolicy): string | null =>
+  policy.config.baseline === undefined
+    ? null
+    : path.resolve(policy.repoRoot, policy.config.baseline);
+
+const readBaseline = (policy: LoadedPolicy): Baseline => {
+  const at = baselinePathOf(policy);
+  if (at === null) return EMPTY_BASELINE;
+  try {
+    return decodeBaseline(JSON.parse(readFileSync(at, "utf8")) as unknown);
+  } catch {
+    return EMPTY_BASELINE;
+  }
+};
+
+const report = (lines: ReadonlyArray<string>): Effect.Effect<void> =>
+  Effect.sync(() => {
+    for (const line of lines) process.stdout.write(`${line}\n`);
+  });
+
+const describe = (violation: Violation): string =>
+  `  ${violation.file}\n      ${formatMessage(violation)}`;
+
+export const check = (
+  policy: LoadedPolicy,
+  roots: ReadonlyArray<string>,
+): Effect.Effect<void, CliFailure> =>
+  Effect.gen(function* () {
+    const findings = collectFindings(policy, roots);
+    const baseline = readBaseline(policy);
+    const reportable = unbaselined(baseline, findings.violations);
+    const stale = staleEntriesOf(baseline, findings.violations);
+
+    yield* report(reportable.map(describe));
+    yield* report(findings.unresolved.map((one) => `  unresolved: ${one}`));
+
+    const carried = findings.violations.length - reportable.length;
+    yield* report([
+      "",
+      `${String(findings.files)} files, ${String(reportable.length)} violations` +
+        (carried > 0 ? `, ${String(carried)} carried by the baseline` : ""),
+    ]);
+
+    if (stale.length > 0) {
+      // The ratchet: a fixed violation must leave the baseline, or the floor
+      // never rises and the file stops describing anything real.
+      yield* report([
+        "",
+        `${String(stale.length)} baseline entries no longer fire. The code was fixed; prune them:`,
+        ...stale.map((entry) => `  ${entry}`),
+        "",
+        "  architecture baseline    # rewrites the file from what still fires",
+      ]);
+      return yield* Effect.fail(fail("stale baseline entries"));
+    }
+
+    if (reportable.length > 0 || findings.unresolved.length > 0) {
+      return yield* Effect.fail(fail("architecture violations"));
+    }
+  });
+
+export const writeBaseline = (
+  policy: LoadedPolicy,
+  roots: ReadonlyArray<string>,
+): Effect.Effect<void, CliFailure> =>
+  Effect.gen(function* () {
+    const at = baselinePathOf(policy);
+    if (at === null) {
+      return yield* Effect.fail(
+        fail("this policy declares no `baseline` path, so there is nowhere to write one"),
+      );
+    }
+
+    const findings = collectFindings(policy, roots);
+    const baseline = baselineOf(findings.violations);
+    yield* Effect.sync(() => {
+      writeFileSync(at, serializeBaseline(baseline));
+    });
+    yield* report([
+      `${String(baseline.entries.length)} violations recorded in ${path.relative(policy.repoRoot, at)}.`,
+      "Each one is debt the policy is carrying. Fixing one means deleting its line.",
+    ]);
+  });
+
+// The question a tree config makes harder to answer than a flat one: given a
+// file, what governs it? A flat config you grep; a tree you have to walk.
+export const explain = (policy: LoadedPolicy, file: string): Effect.Effect<void, CliFailure> =>
+  Effect.gen(function* () {
+    const relative = path.relative(policy.repoRoot, path.resolve(policy.repoRoot, file));
+    const selected = rulesSelecting(policy.importRules, relative);
+
+    // An allowlist rule names no `to` — it fires when the target matches none of
+    // its patterns. A prohibition names one.
+    const allowlists = selected.filter(([rule]) => rule.to.length === 0 && rule.toNot.length > 0);
+    const prohibitions = selected.filter(([rule]) => rule.to.length > 0);
+
+    const owed = policy.structure.parity
+      .filter(
+        (rule) =>
+          rule.file.some((pattern) => pattern.test(relative)) &&
+          !rule.fileNot.some((pattern) => pattern.test(relative)),
+      )
+      .flatMap((rule) => requiredSiblingsOf(rule, relative));
+
+    const governing = policy.structure.folders.filter((rule) =>
+      rule.folder.some((pattern) => pattern.test(path.dirname(relative))),
+    );
+
+    const naming = policy.structure.naming.filter(
+      (rule) =>
+        rule.file.some((pattern) => pattern.test(relative)) &&
+        !rule.fileNot.some((pattern) => pattern.test(relative)),
+    );
+
+    const firstSentence = (message: string) => `${message.split(". ")[0] ?? message}.`;
+
+    yield* report([
+      relative,
+      "",
+      allowlists.length === 0
+        ? "  may import: anything (no tier above this file states an allowlist)"
+        : "  may import:",
+      ...allowlists.flatMap(([rule]) => [
+        `    — ${rule.name}`,
+        ...rule.toNot.map((pattern) => `        ${pattern}`),
+      ]),
+      "",
+      "  may not import:",
+      ...(prohibitions.length === 0
+        ? ["    (nothing beyond the allowlist above)"]
+        : prohibitions.map(([rule]) => `    ${rule.name} — ${firstSentence(rule.message)}`)),
+      "",
+      `  lives in: ${governing.length === 0 ? "a folder no rule governs" : governing.map((rule) => rule.name).join(", ")}`,
+      ...(naming.length === 0
+        ? []
+        : [
+            "  is named by:",
+            ...naming.map(
+              (rule) =>
+                `    ${rule.name} — ${rule.sameAs !== null ? "its folder's own name" : (rule.convention?.source ?? "")}`,
+            ),
+          ]),
+      ...(owed.length === 0 ? [] : ["  owes:", ...owed.map((one) => `    ${one}`)]),
+    ]);
+  });
+
+export const run = (
+  repoRoot: string,
+  argv: ReadonlyArray<string>,
+): Effect.Effect<void, CliFailure> =>
+  Effect.gen(function* () {
+    const [command = "check", ...rest] = argv;
+    const policy = yield* Effect.tryPromise({
+      try: () => loadPolicy(repoRoot),
+      catch: (cause) => fail(String(cause)),
+    });
+
+    const roots = rest.length > 0 ? rest : ["packages"];
+
+    switch (command) {
+      case "check":
+        return yield* check(policy, roots);
+      case "baseline":
+        return yield* writeBaseline(policy, roots);
+      case "explain": {
+        const [file] = rest;
+        if (file === undefined) return yield* Effect.fail(fail("explain needs a file path"));
+        return yield* explain(policy, file);
+      }
+      default:
+        return yield* Effect.fail(
+          fail(`unknown command "${command}". Try: check | baseline | explain <file>`),
+        );
+    }
+  });
+
+export const fingerprint = fingerprintOf;

package/src/adapters/cli/source-facts.ts

@@ -0,0 +1,137 @@
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+
+import ts from "typescript";
+
+import type { Binding } from "../../core/exports.js";
+import type { MemberSite } from "../../core/members.js";
+
+// Everything the policy needs to know about one file, read once.
+//
+// The oxlint adapter gets these facts from oxlint's AST; this one reads them
+// from TypeScript's. They meet at the same vocabulary — a specifier, a binding,
+// a member site — which is what keeps the two adapters answerable to the same
+// core rather than to each other.
+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>;
+};
+
+const scriptKindOf = (file: string): ts.ScriptKind =>
+  file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+
+const nameOf = (node: ts.PropertyName | ts.ModuleExportName | undefined): string | null => {
+  if (node === undefined) return null;
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isStringLiteral(node)) return node.text;
+  return null;
+};
+
+const bindingsOfImportClause = (clause: ts.ImportClause | undefined): ReadonlyArray<Binding> => {
+  if (clause === undefined) return [];
+  const found: Array<Binding> = [];
+  if (clause.name !== undefined) found.push({ symbol: "default", kind: "default" });
+  const bindings = clause.namedBindings;
+  if (bindings !== undefined) {
+    if (ts.isNamespaceImport(bindings)) found.push({ symbol: "*", kind: "namespace" });
+    else {
+      for (const element of bindings.elements) {
+        const symbol = nameOf(element.propertyName ?? element.name);
+        if (symbol !== null) found.push({ symbol, kind: "named" });
+      }
+    }
+  }
+  return found;
+};
+
+// `export { a } from "m"` — `propertyName` is the name in the source module when
+// the export is renamed, so it is the one the policy is about.
+const bindingsOfExportClause = (
+  clause: ts.NamedExportBindings | undefined,
+): ReadonlyArray<Binding> => {
+  if (clause === undefined || ts.isNamespaceExport(clause)) return [];
+  const found: Array<Binding> = [];
+  for (const element of clause.elements) {
+    const symbol = nameOf(element.propertyName ?? element.name);
+    if (symbol !== null) found.push({ symbol, kind: "named" });
+  }
+  return found;
+};
+
+const calleeNameOf = (expression: ts.LeftHandSideExpression): string | null => {
+  if (ts.isIdentifier(expression)) return expression.text;
+  if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.name)) {
+    return expression.name.text;
+  }
+  return null;
+};
+
+export const sourceFactsOf = (repoRoot: string, file: string): SourceFacts => {
+  const text = readFileSync(path.join(repoRoot, file), "utf8");
+  const parsed = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKindOf(file));
+
+  const specifiers: Array<string> = [];
+  const bindings = new Map<string, Array<Binding>>();
+  const memberSites: Array<MemberSite> = [];
+
+  const record = (specifier: string, found: ReadonlyArray<Binding>): void => {
+    if (!bindings.has(specifier)) {
+      specifiers.push(specifier);
+      bindings.set(specifier, []);
+    }
+    const existing = bindings.get(specifier);
+    if (existing !== undefined) for (const binding of found) existing.push(binding);
+  };
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      // A side-effect import carries no bindings but is still an edge — the
+      // `import "server-only"` form a regex cannot see.
+      record(node.moduleSpecifier.text, bindingsOfImportClause(node.importClause));
+    } else if (
+      ts.isExportDeclaration(node) &&
+      node.moduleSpecifier !== undefined &&
+      ts.isStringLiteral(node.moduleSpecifier)
+    ) {
+      record(node.moduleSpecifier.text, bindingsOfExportClause(node.exportClause));
+    } else if (
+      ts.isImportEqualsDeclaration(node) &&
+      ts.isExternalModuleReference(node.moduleReference) &&
+      ts.isStringLiteral(node.moduleReference.expression)
+    ) {
+      record(node.moduleReference.expression.text, []);
+    } else if (ts.isCallExpression(node)) {
+      const [first] = node.arguments;
+      const isModuleCall =
+        node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(node.expression) && node.expression.text === "require");
+      if (isModuleCall && first !== undefined && ts.isStringLiteral(first)) {
+        record(first.text, []);
+      }
+
+      const callee = calleeNameOf(node.expression);
+      if (callee !== null) memberSites.push({ file, subject: "calls", name: callee });
+    } else if (ts.isTypeAliasDeclaration(node) && ts.isTypeLiteralNode(node.type)) {
+      const declaration = node.name.text;
+      for (const member of node.type.members) {
+        // A computed key is not a name a vocabulary rule can speak about.
+        if (!ts.isPropertySignature(member) && !ts.isMethodSignature(member)) continue;
+        if (ts.isComputedPropertyName(member.name)) continue;
+        const name = nameOf(member.name);
+        if (name !== null) {
+          memberSites.push({ file, subject: "type-members", name, in: declaration });
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(parsed);
+
+  return { specifiers, bindings, memberSites };
+};