@shivaedev/quality 0.4.0 → 0.5.1

package/src/git/command.ts

@@ -4,13 +4,13 @@ import { SetupFailure } from "../failure.ts";
 
 export interface GitResult {
 	readonly code: number;
-	readonly stdout: string;
 	readonly stderr: string;
+	readonly stdout: string;
 }
 
 export type Git = ChildProcessSpawner.ChildProcessSpawner;
 
-export const git = (cwd: string, args: ReadonlyArray<string>, env?: Readonly<Record<string, string>>): Effect.Effect<GitResult, SetupFailure, Git> =>
+export const git = (cwd: string, args: readonly string[], env?: Readonly<Record<string, string>>): Effect.Effect<GitResult, SetupFailure, Git> =>
 	Effect.scoped(
 		Effect.gen(function* () {
 			const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -23,7 +23,7 @@ export const git = (cwd: string, args: ReadonlyArray<string>, env?: Readonly<Rec
 		}),
 	).pipe(Effect.mapError((error) => new SetupFailure({ message: `cannot run git: ${error.message}` })));
 
-export const gitOrFail = (cwd: string, args: ReadonlyArray<string>): Effect.Effect<string, SetupFailure, Git> =>
+export const gitOrFail = (cwd: string, args: readonly string[]): Effect.Effect<string, SetupFailure, Git> =>
 	Effect.flatMap(git(cwd, args), (result) =>
 		result.code === 0
 			? Effect.succeed(result.stdout)

package/src/git/history.ts

@@ -20,7 +20,7 @@ const parse = (output: string): Changes => {
 	const moves = new Map<string, string>();
 	for (let index = 0; index < fields.length - 1; ) {
 		const status = fields[index] ?? "";
-		const paths = fields.slice(index + 1, index + (/^[RC]/.test(status) ? 3 : 2));
+		const paths = fields.slice(index + 1, index + (/^[RC]/u.test(status) ? 3 : 2));
 		for (const path of paths) {
 			files.add(path);
 		}
@@ -34,7 +34,7 @@ const parse = (output: string): Changes => {
 };
 
 // Paths are relative to the root, and only tracked files count: a move is seen once both of its sides are staged.
-export const changesSince = (root: string, revision: ReadonlyArray<string>): Effect.Effect<Changes, SetupFailure, Git> =>
+export const changesSince = (root: string, revision: readonly string[]): Effect.Effect<Changes, SetupFailure, Git> =>
 	Effect.map(
 		gitOrFail(root, ["diff", "--no-color", "--no-ext-diff", "--find-renames", "--name-status", "-z", "--relative", ...revision, "--"]),
 		parse,

package/src/imports/ambient.ts

@@ -0,0 +1,54 @@
+import ts from "typescript";
+
+export type Ambient = (specifier: string, projectFiles: ReadonlySet<string>) => boolean;
+
+const WILDCARD = "*";
+
+function isPattern(name: string): boolean {
+	return name !== WILDCARD && name.split(WILDCARD).length <= 2;
+}
+
+function declaredIn(source: ts.SourceFile): readonly string[] {
+	if (ts.isExternalModule(source)) {
+		return [];
+	}
+	return source.statements.flatMap((statement) =>
+		ts.isModuleDeclaration(statement) && ts.isStringLiteral(statement.name) && isPattern(statement.name.text) ? [statement.name.text] : [],
+	);
+}
+
+function wildcardMatches(pattern: string, value: string): boolean {
+	const [head = "", ...rest] = pattern.split(WILDCARD);
+	const tail = rest.pop();
+	if (tail === undefined) {
+		return pattern === value;
+	}
+	const end = value.length - tail.length;
+	if (end < head.length || !value.startsWith(head) || !value.endsWith(tail)) {
+		return false;
+	}
+	let at = head.length;
+	for (const middle of rest) {
+		const found = value.indexOf(middle, at);
+		if (found === -1 || found + middle.length > end) {
+			return false;
+		}
+		at = found + middle.length;
+	}
+	return true;
+}
+
+function isBare(specifier: string): boolean {
+	return !(specifier.startsWith(".") || specifier.startsWith("/"));
+}
+
+// A module declared in a script, not a module, is ambient: it exists for the files of the project that includes the script.
+export function ambientModules(sources: readonly { readonly path: string; readonly syntax: ts.SourceFile }[]): Ambient {
+	const declarations = sources.flatMap(({ path, syntax }) => {
+		const patterns = declaredIn(syntax);
+		return patterns.length === 0 ? [] : [{ path, patterns }];
+	});
+	return (specifier, projectFiles) =>
+		isBare(specifier)
+		&& declarations.some(({ path, patterns }) => projectFiles.has(path) && patterns.some((pattern) => wildcardMatches(pattern, specifier)));
+}

package/src/imports/components.ts

@@ -0,0 +1,80 @@
+interface Frame {
+	next: number;
+	readonly node: string;
+}
+
+interface Search {
+	readonly adjacency: ReadonlyMap<string, readonly string[]>;
+	readonly found: string[][];
+	readonly index: Map<string, number>;
+	readonly low: Map<string, number>;
+	readonly open: Set<string>;
+	readonly stack: string[];
+}
+
+function byPath(left: string, right: string): number {
+	return left.localeCompare(right);
+}
+
+function enter(search: Search, frames: Frame[], node: string): void {
+	const index = search.index.size;
+	search.index.set(node, index);
+	search.low.set(node, index);
+	search.stack.push(node);
+	search.open.add(node);
+	frames.push({ next: 0, node });
+}
+
+function lowOf(search: Search, node: string): number {
+	return search.low.get(node) ?? 0;
+}
+
+function close(search: Search, node: string): void {
+	if (lowOf(search, node) !== search.index.get(node)) {
+		return;
+	}
+	const component: string[] = [];
+	for (let member = search.stack.pop(); member !== undefined; member = member === node ? undefined : search.stack.pop()) {
+		search.open.delete(member);
+		component.push(member);
+	}
+	const loops = (search.adjacency.get(node) ?? []).includes(node);
+	if (component.length > 1 || loops) {
+		search.found.push(component.sort(byPath));
+	}
+}
+
+function step(search: Search, frames: Frame[], frame: Frame): void {
+	const neighbour = (search.adjacency.get(frame.node) ?? [])[frame.next];
+	if (neighbour === undefined) {
+		frames.pop();
+		const parent = frames.at(-1);
+		if (parent !== undefined) {
+			search.low.set(parent.node, Math.min(lowOf(search, parent.node), lowOf(search, frame.node)));
+		}
+		close(search, frame.node);
+		return;
+	}
+	frame.next += 1;
+	if (!search.index.has(neighbour)) {
+		enter(search, frames, neighbour);
+	} else if (search.open.has(neighbour)) {
+		search.low.set(frame.node, Math.min(lowOf(search, frame.node), search.index.get(neighbour) ?? 0));
+	}
+}
+
+// Tarjan's algorithm with an explicit stack, so a long import chain cannot overflow the call stack.
+export function cyclicComponents(adjacency: ReadonlyMap<string, readonly string[]>): readonly (readonly string[])[] {
+	const search: Search = { adjacency, found: [], index: new Map(), low: new Map(), open: new Set(), stack: [] };
+	for (const node of [...adjacency.keys()].sort(byPath)) {
+		if (search.index.has(node)) {
+			continue;
+		}
+		const frames: Frame[] = [];
+		enter(search, frames, node);
+		for (let frame = frames.at(-1); frame !== undefined; frame = frames.at(-1)) {
+			step(search, frames, frame);
+		}
+	}
+	return search.found.sort((left, right) => byPath(left[0] ?? "", right[0] ?? ""));
+}

package/src/imports/extract.ts

@@ -0,0 +1,129 @@
+import ts from "typescript";
+
+export type ImportKind = "import" | "path-reference" | "resolve" | "type-reference";
+
+export interface ImportRequest {
+	readonly kind: ImportKind;
+	readonly line: number;
+	readonly specifier: string;
+	readonly type: boolean;
+}
+
+interface Found {
+	readonly kind: ImportKind;
+	readonly node: ts.Node | undefined;
+	readonly type: boolean;
+}
+
+const MAY_CALL = /\b(?:import|require)\s*\(|\b(?:require|import\.meta)\.resolve\s*\(/u;
+
+const JSDOC_IMPORT = "@import";
+
+function lineAt(source: ts.SourceFile, position: number): number {
+	return source.getLineAndCharacterOfPosition(position).line + 1;
+}
+
+function declared(statement: ts.Statement): Found | undefined {
+	if (ts.isImportDeclaration(statement)) {
+		return { kind: "import", node: statement.moduleSpecifier, type: statement.importClause?.isTypeOnly === true };
+	}
+	if (ts.isExportDeclaration(statement)) {
+		return { kind: "import", node: statement.moduleSpecifier, type: statement.isTypeOnly };
+	}
+	if (ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference)) {
+		return { kind: "import", node: statement.moduleReference.expression, type: statement.isTypeOnly };
+	}
+	return undefined;
+}
+
+function isRequire(call: ts.CallExpression): boolean {
+	return ts.isIdentifier(call.expression) && call.expression.text === "require";
+}
+
+function isImportMeta(node: ts.Expression): boolean {
+	return ts.isMetaProperty(node) && node.keywordToken === ts.SyntaxKind.ImportKeyword && node.name.text === "meta";
+}
+
+function resolver(call: ts.CallExpression): "meta" | "require" | undefined {
+	const callee = call.expression;
+	if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== "resolve") {
+		return undefined;
+	}
+	if (ts.isIdentifier(callee.expression) && callee.expression.text === "require") {
+		return "require";
+	}
+	return isImportMeta(callee.expression) ? "meta" : undefined;
+}
+
+// Node resolves a relative import.meta.resolve() by URL arithmetic alone, so the path need not exist.
+function isRelative(node: ts.Node | undefined): boolean {
+	return node !== undefined && ts.isStringLiteralLike(node) && (node.text.startsWith(".") || node.text.startsWith("/"));
+}
+
+function called(call: ts.CallExpression): Found | undefined {
+	const [argument] = call.arguments;
+	if (call.expression.kind === ts.SyntaxKind.ImportKeyword || isRequire(call)) {
+		return { kind: "import", node: argument, type: false };
+	}
+	const how = resolver(call);
+	const checked = how === "require" || (how === "meta" && !isRelative(argument));
+	return checked ? { kind: "resolve", node: argument, type: false } : undefined;
+}
+
+function nested(node: ts.Node): Found | undefined {
+	if (ts.isCallExpression(node)) {
+		return called(node);
+	}
+	if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+		return { kind: "import", node: node.argument.literal, type: true };
+	}
+	return undefined;
+}
+
+function requestOf(source: ts.SourceFile, at: ts.Node, found: Found | undefined): readonly ImportRequest[] {
+	if (found?.node === undefined || !ts.isStringLiteralLike(found.node)) {
+		return [];
+	}
+	return [{ kind: found.kind, line: lineAt(source, at.getStart(source)), specifier: found.node.text, type: found.type }];
+}
+
+function nestedRequests(source: ts.SourceFile): readonly ImportRequest[] {
+	if (!MAY_CALL.test(source.text)) {
+		return [];
+	}
+	const requests: ImportRequest[] = [];
+	function visit(node: ts.Node): void {
+		requests.push(...requestOf(source, node, nested(node)));
+		ts.forEachChild(node, visit);
+	}
+	visit(source);
+	return requests;
+}
+
+function jsDocRequests(source: ts.SourceFile): readonly ImportRequest[] {
+	if (!source.text.includes(JSDOC_IMPORT)) {
+		return [];
+	}
+	const tags = [...source.statements, source.endOfFileToken]
+		.flatMap((node) => ts.getJSDocCommentsAndTags(node))
+		.flatMap((doc) => (ts.isJSDoc(doc) ? (doc.tags ?? []) : [doc]))
+		.filter(ts.isJSDocImportTag);
+	return tags.flatMap((tag) => requestOf(source, tag, { kind: "import", node: tag.moduleSpecifier, type: true }));
+}
+
+function referenceRequests(source: ts.SourceFile): readonly ImportRequest[] {
+	function requestFor(kind: ImportKind): (reference: ts.FileReference) => ImportRequest {
+		return (reference) => ({ kind, line: lineAt(source, reference.pos), specifier: reference.fileName, type: true });
+	}
+	return [...source.typeReferenceDirectives.map(requestFor("type-reference")), ...source.referencedFiles.map(requestFor("path-reference"))];
+}
+
+export function importsOf(source: ts.SourceFile, declarationFile: boolean): readonly ImportRequest[] {
+	const all = [
+		...referenceRequests(source),
+		...source.statements.flatMap((statement) => requestOf(source, statement, declared(statement))),
+		...jsDocRequests(source),
+		...nestedRequests(source),
+	];
+	return declarationFile ? all.map((request) => ({ ...request, type: true })) : all;
+}

package/src/imports/fences/dsl.ts

@@ -0,0 +1,33 @@
+import type { Examples, Fence, Prohibition, Selector, Target } from "./model.ts";
+
+interface Draft {
+	readonly from: Selector;
+	readonly name: string;
+	readonly rationale: string;
+}
+
+interface Demonstrable {
+	readonly demonstratedBy: (examples: Examples) => Fence;
+}
+
+interface Prohibitions {
+	readonly mayImportOnly: (...subjects: readonly string[]) => { readonly of: (unit: Target) => Demonstrable };
+	readonly mayNotImport: (target: Target) => Demonstrable;
+	readonly mayNotReach: (target: Target) => Demonstrable;
+}
+
+function demonstrable(draft: Draft, prohibition: Prohibition): Demonstrable {
+	return { demonstratedBy: (examples) => ({ _tag: "Fence", examples, from: draft.from, name: draft.name, prohibition, rationale: draft.rationale }) };
+}
+
+function prohibitions(draft: Draft): Prohibitions {
+	return {
+		mayImportOnly: (...subjects) => ({ of: (unit) => demonstrable(draft, { kind: "vocabulary", subjects, unit: unit.selector }) }),
+		mayNotImport: (target) => demonstrable(draft, { kind: "import", to: target.selector }),
+		mayNotReach: (target) => demonstrable(draft, { kind: "reach", to: target.selector }),
+	};
+}
+
+export function fence(name: string): { readonly because: (rationale: string) => { readonly from: (subject: Target) => Prohibitions } } {
+	return { because: (rationale) => ({ from: (subject) => prohibitions({ from: subject.selector, name, rationale }) }) };
+}

package/src/imports/fences/evaluate.ts

@@ -0,0 +1,75 @@
+import type { Finding } from "../../rule.ts";
+import type { ImportEdge, ImportGraph } from "../graph.ts";
+import { type Compiler, compile, type Matcher } from "./match.ts";
+import type { Fence } from "./model.ts";
+import { labelOf, outgoing, reachedFrom } from "./reach.ts";
+import { compileVocabulary, type Vocabulary } from "./vocabulary.ts";
+
+export type FenceGraph = Pick<ImportGraph, "edges" | "modules">;
+
+export type Evaluate = (graph: FenceGraph) => readonly Finding[];
+
+export interface CompiledFence {
+	readonly evaluate: Evaluate;
+	readonly fence: Fence;
+}
+
+function across(fence: Fence): string {
+	return `across the fence "${fence.name}": ${fence.rationale}`;
+}
+
+function vocabularyFinding(fence: Fence, vocabulary: Vocabulary, subjects: readonly string[], edge: ImportEdge): readonly Finding[] {
+	const subject = vocabulary.subjectOf(edge.to);
+	if (subject === undefined || subjects.includes(subject)) {
+		return [];
+	}
+	const message = `Imports "${subject}" of ${vocabulary.folder} ${across(fence)} Use only ${subjects.join(", ")}.`;
+	return [{ file: edge.from, line: edge.line, message, subject: fence.name }];
+}
+
+function vocabularyFindings(compiler: Compiler, fence: Fence, importer: (path: string) => boolean, where: string): Evaluate {
+	if (fence.prohibition.kind !== "vocabulary") {
+		return () => [];
+	}
+	const subjects = fence.prohibition.subjects;
+	const vocabulary = compileVocabulary(compiler, fence.prohibition.unit, subjects, `${where}.of`);
+	if (vocabulary === undefined) {
+		return () => [];
+	}
+	return (graph) => graph.edges.flatMap((edge) => (importer(edge.from) ? vocabularyFinding(fence, vocabulary, subjects, edge) : []));
+}
+
+function importFindings(fence: Fence, importer: (path: string) => boolean, to: Matcher): Evaluate {
+	return (graph) =>
+		graph.edges
+			.filter((edge) => importer(edge.from) && to(edge.to))
+			.map((edge) => ({ file: edge.from, line: edge.line, message: `Imports ${labelOf(edge.to)} ${across(fence)}`, subject: fence.name }));
+}
+
+function reachFindings(fence: Fence, importer: (path: string) => boolean, to: Matcher): Evaluate {
+	return (graph) => {
+		const edgesFrom = outgoing(graph.edges);
+		return graph.modules.filter(importer).flatMap((module) =>
+			reachedFrom(module, edgesFrom, to).map((reached) => ({
+				file: module,
+				line: reached.line,
+				message: `Reaches ${labelOf(reached.target)} through ${reached.path.join(" -> ")} ${across(fence)}`,
+				subject: fence.name,
+			})),
+		);
+	};
+}
+
+export function compileFence(compiler: Compiler, fence: Fence): CompiledFence {
+	const where = `fence "${fence.name}"`;
+	const from = compile(compiler, fence.from, `${where}.from`);
+	function importer(path: string): boolean {
+		return from({ kind: "file", path });
+	}
+	const prohibition = fence.prohibition;
+	if (prohibition.kind === "vocabulary") {
+		return { evaluate: vocabularyFindings(compiler, fence, importer, where), fence };
+	}
+	const to = compile(compiler, prohibition.to, `${where}.to`);
+	return { evaluate: prohibition.kind === "import" ? importFindings(fence, importer, to) : reachFindings(fence, importer, to), fence };
+}

package/src/imports/fences/match.ts

@@ -0,0 +1,148 @@
+import { builtinName, type Endpoint, packageNameOf } from "../resolve.ts";
+import { packageOf, type WorkspacePackage } from "../workspace.ts";
+import type { Selector } from "./model.ts";
+
+export interface PolicyScope {
+	readonly files: readonly string[];
+	readonly packages: readonly WorkspacePackage[];
+}
+
+export type Matcher = (endpoint: Endpoint) => boolean;
+
+export interface Compiler {
+	readonly issues: string[];
+	readonly scope: PolicyScope;
+}
+
+const TRAILING_SLASHES = /\/+$/u;
+
+function unscoped(name: string): string {
+	return name.startsWith("@") ? name.slice(name.indexOf("/") + 1) : name;
+}
+
+export function trimmed(path: string): string {
+	return path.replace(TRAILING_SLASHES, "");
+}
+
+export function holdsFiles(compiler: Compiler, folder: string): boolean {
+	return compiler.scope.files.some((file) => file.startsWith(`${folder}/`));
+}
+
+export function packageNamed(compiler: Compiler, name: string, where: string): WorkspacePackage | undefined {
+	const found = compiler.scope.packages.filter((candidate) => candidate.name === name || unscoped(candidate.name) === name);
+	if (found.length !== 1) {
+		compiler.issues.push(`${where}: ${found.length === 0 ? "no workspace package is named" : "more than one workspace package is named"} "${name}"`);
+	}
+	return found.length === 1 ? found[0] : undefined;
+}
+
+function checkNames(
+	compiler: Compiler,
+	where: string,
+	kind: string,
+	values: readonly string[],
+	problemOf: (value: string) => string | undefined,
+): void {
+	if (values.length === 0) {
+		compiler.issues.push(`${where}: ${kind}() names nothing`);
+	}
+	for (const value of values) {
+		const problem = problemOf(value);
+		if (problem !== undefined) {
+			compiler.issues.push(`${where}: ${kind}("${value}") ${problem}`);
+		}
+	}
+}
+
+function fileWhere(accepts: (path: string) => boolean): Matcher {
+	return (endpoint) => endpoint.kind === "file" && accepts(endpoint.path);
+}
+
+function externalWhere(accepts: (name: string) => boolean): Matcher {
+	return (endpoint) => endpoint.kind === "external" && accepts(endpoint.package);
+}
+
+function isPackageName(name: string): boolean {
+	const scoped = !name.startsWith("@") || name.includes("/");
+	return name.trim() !== "" && !name.startsWith(".") && !name.startsWith("/") && scoped && packageNameOf(name) === name;
+}
+
+function underAny(prefixes: readonly string[], value: string): boolean {
+	return prefixes.some((prefix) => value === prefix || value.startsWith(`${prefix}/`));
+}
+
+function compilePackages(compiler: Compiler, names: readonly string[], where: string): Matcher {
+	checkNames(compiler, where, "packages", names, () => undefined);
+	const directories = new Set(names.flatMap((name) => packageNamed(compiler, name, where)?.directory ?? []));
+	return fileWhere((path) => directories.has(packageOf(compiler.scope.packages, path)?.directory ?? ""));
+}
+
+function compileFolders(compiler: Compiler, paths: readonly string[], where: string): Matcher {
+	const folders = paths.map(trimmed);
+	checkNames(compiler, where, "folders", folders, (folder) => (holdsFiles(compiler, folder) ? undefined : "holds no checked file"));
+	return fileWhere((path) => folders.some((folder) => path.startsWith(`${folder}/`)));
+}
+
+function compileFiles(compiler: Compiler, paths: readonly string[], where: string): Matcher {
+	checkNames(compiler, where, "files", paths, (path) => (compiler.scope.files.includes(path) ? undefined : "is no checked file"));
+	return fileWhere((path) => paths.includes(path));
+}
+
+function compileModules(compiler: Compiler, names: readonly string[], where: string): Matcher {
+	checkNames(compiler, where, "modules", names, (name) =>
+		builtinName(name) !== undefined || isPackageName(name) ? undefined : "is no package name",
+	);
+	const normalized = names.map((name) => builtinName(name) ?? name);
+	return externalWhere((name) => underAny(normalized, name));
+}
+
+function compileScopes(compiler: Compiler, names: readonly string[], where: string): Matcher {
+	checkNames(compiler, where, "scopes", names, (name) =>
+		name.startsWith("@") && name.length > 1 && !name.includes("/") ? undefined : 'is no scope such as "@types"',
+	);
+	return externalWhere((name) => names.some((scope) => name.startsWith(`${scope}/`)));
+}
+
+function compileWorkspace(compiler: Compiler, where: string): Matcher {
+	if (compiler.scope.packages.length === 0) {
+		compiler.issues.push(
+			`${where}: workspace selects nothing, since no named package.json among the sources is a member of the workspace that pnpm-workspace.yaml or the root package.json declares`,
+		);
+	}
+	return fileWhere((path) => packageOf(compiler.scope.packages, path) !== undefined);
+}
+
+function compileGroup(compiler: Compiler, members: readonly Selector[], where: string, kind: string): readonly Matcher[] {
+	if (members.length === 0) {
+		compiler.issues.push(`${where}: ${kind}() names nothing`);
+	}
+	return members.map((member, index) => compile(compiler, member, `${where}.${kind}[${index}]`));
+}
+
+export function compile(compiler: Compiler, selector: Selector, where: string): Matcher {
+	switch (selector.kind) {
+		case "anything":
+			return () => true;
+		case "anyOf": {
+			const members = compileGroup(compiler, selector.members, where, "anyOf");
+			return (endpoint) => members.some((member) => member(endpoint));
+		}
+		case "except": {
+			const base = compile(compiler, selector.base, where);
+			const excluded = compileGroup(compiler, selector.excluded, where, "except");
+			return (endpoint) => base(endpoint) && !excluded.some((member) => member(endpoint));
+		}
+		case "files":
+			return compileFiles(compiler, selector.paths, where);
+		case "folders":
+			return compileFolders(compiler, selector.paths, where);
+		case "modules":
+			return compileModules(compiler, selector.names, where);
+		case "packages":
+			return compilePackages(compiler, selector.names, where);
+		case "scopes":
+			return compileScopes(compiler, selector.names, where);
+		case "workspace":
+			return compileWorkspace(compiler, where);
+	}
+}

package/src/imports/fences/model.ts

@@ -0,0 +1,42 @@
+export type Selector =
+	| { readonly kind: "anything" }
+	| { readonly kind: "anyOf"; readonly members: readonly Selector[] }
+	| { readonly kind: "except"; readonly base: Selector; readonly excluded: readonly Selector[] }
+	| { readonly kind: "files"; readonly paths: readonly string[] }
+	| { readonly kind: "folders"; readonly paths: readonly string[] }
+	| { readonly kind: "modules"; readonly names: readonly string[] }
+	| { readonly kind: "packages"; readonly names: readonly string[] }
+	| { readonly kind: "scopes"; readonly names: readonly string[] }
+	| { readonly kind: "workspace" };
+
+export interface Target {
+	readonly except: (...excluded: readonly Target[]) => Target;
+	readonly selector: Selector;
+}
+
+export interface External {
+	readonly external: string;
+}
+
+export type ExampleStep = string | External;
+
+export type Chain = readonly [string, ExampleStep, ...ExampleStep[]];
+
+export interface Examples {
+	readonly illegal: Chain;
+	readonly legal: Chain;
+}
+
+export type Prohibition =
+	| { readonly kind: "import"; readonly to: Selector }
+	| { readonly kind: "reach"; readonly to: Selector }
+	| { readonly kind: "vocabulary"; readonly subjects: readonly string[]; readonly unit: Selector };
+
+export interface Fence {
+	readonly _tag: "Fence";
+	readonly examples: Examples;
+	readonly from: Selector;
+	readonly name: string;
+	readonly prohibition: Prohibition;
+	readonly rationale: string;
+}

package/src/imports/fences/policy.ts

@@ -0,0 +1,70 @@
+import type { ImportEdge } from "../graph.ts";
+import { type Endpoint, packageNameOf } from "../resolve.ts";
+import { type CompiledFence, compileFence, type FenceGraph } from "./evaluate.ts";
+import type { PolicyScope } from "./match.ts";
+import type { Chain, ExampleStep, Fence } from "./model.ts";
+
+function endpointOf(step: ExampleStep): Endpoint {
+	return typeof step === "string"
+		? { kind: "file", path: step }
+		: { kind: "external", package: packageNameOf(step.external), specifier: step.external };
+}
+
+function chainLabel(chain: Chain): string {
+	return chain.map((step) => (typeof step === "string" ? step : step.external)).join(" -> ");
+}
+
+function graphOf(chain: Chain): FenceGraph | undefined {
+	const importers = chain.slice(0, -1);
+	const files = importers.flatMap((step) => (typeof step === "string" ? [step] : []));
+	if (files.length !== importers.length) {
+		return undefined;
+	}
+	const edges = files.map(
+		(from, index): ImportEdge => ({ from, kind: "import", line: 1, specifier: "", to: endpointOf(chain[index + 1] ?? from), type: false }),
+	);
+	return { edges, modules: files };
+}
+
+function crossedBy(policy: readonly CompiledFence[], graph: FenceGraph): readonly string[] {
+	return policy.filter((compiled) => compiled.evaluate(graph).length > 0).map((compiled) => compiled.fence.name);
+}
+
+function exampleIssues(policy: readonly CompiledFence[], fence: Fence): readonly string[] {
+	const where = `fence "${fence.name}"`;
+	const illegal = graphOf(fence.examples.illegal);
+	const legal = graphOf(fence.examples.legal);
+	if (illegal === undefined || legal === undefined) {
+		return [`${where}: an example imports from an external module; only its last step may be external()`];
+	}
+	const crossed = crossedBy(policy, illegal);
+	const passed = crossedBy(policy, legal);
+	return [
+		...(crossed.length === 1 && crossed[0] === fence.name
+			? []
+			: [
+					`${where}: the illegal example ${chainLabel(fence.examples.illegal)} must cross this fence alone, and crosses ${crossed.join(", ") || "none"}`,
+				]),
+		...(passed.length === 0 ? [] : [`${where}: the legal example ${chainLabel(fence.examples.legal)} crosses ${passed.join(", ")}`]),
+	];
+}
+
+function declarationIssues(fences: readonly Fence[]): readonly string[] {
+	return fences.flatMap((fence, index) => [
+		...(fence.name.trim() === "" ? [`fence ${index}: has no name`] : []),
+		...(fences.findIndex((other) => other.name === fence.name) === index ? [] : [`fence "${fence.name}": an earlier fence has this name`]),
+		...(fence.rationale.trim() === "" ? [`fence "${fence.name}": because() gives no reason`] : []),
+	]);
+}
+
+export function compilePolicy(fences: readonly Fence[], scope: PolicyScope): readonly CompiledFence[] {
+	const issues = [...declarationIssues(fences)];
+	const policy = fences.map((fence) => compileFence({ issues, scope }, fence));
+	if (issues.length === 0) {
+		issues.push(...fences.flatMap((fence) => exampleIssues(policy, fence)));
+	}
+	if (issues.length > 0) {
+		throw new Error(`the fence policy is invalid:\n${issues.map((issue) => `  - ${issue}`).join("\n")}`);
+	}
+	return policy;
+}