@shivaedev/quality 0.3.1 → 0.5.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;
+}

package/src/imports/fences/reach.ts

@@ -0,0 +1,62 @@
+import type { ImportEdge } from "../graph.ts";
+import type { Endpoint } from "../resolve.ts";
+import type { Matcher } from "./match.ts";
+
+export interface Reached {
+	readonly line: number;
+	readonly path: readonly string[];
+	readonly target: Endpoint;
+}
+
+interface Trail {
+	readonly line: number;
+	readonly path: readonly string[];
+}
+
+export function labelOf(endpoint: Endpoint): string {
+	if (endpoint.kind === "file") {
+		return endpoint.path;
+	}
+	const named = endpoint.specifier === endpoint.package || endpoint.specifier.startsWith(`${endpoint.package}/`);
+	return named ? endpoint.specifier : `${endpoint.specifier} (${endpoint.package})`;
+}
+
+export function outgoing(edges: readonly ImportEdge[]): ReadonlyMap<string, readonly ImportEdge[]> {
+	const from = new Map<string, ImportEdge[]>();
+	for (const edge of edges) {
+		const known = from.get(edge.from) ?? [];
+		known.push(edge);
+		from.set(edge.from, known);
+	}
+	return from;
+}
+
+interface Walk {
+	readonly forbidden: Matcher;
+	readonly queue: string[];
+	readonly reached: Map<string, Reached>;
+	readonly trails: Map<string, Trail>;
+}
+
+function follow(walk: Walk, before: Trail, edge: ImportEdge): void {
+	const label = labelOf(edge.to);
+	const trail = { line: before.path.length === 1 ? edge.line : before.line, path: [...before.path, label] };
+	if (walk.forbidden(edge.to)) {
+		walk.reached.set(label, walk.reached.get(label) ?? { ...trail, target: edge.to });
+	} else if (edge.to.kind === "file" && !walk.trails.has(edge.to.path)) {
+		walk.trails.set(edge.to.path, trail);
+		walk.queue.push(edge.to.path);
+	}
+}
+
+// A breadth-first walk that stops at each forbidden endpoint, so a finding names the shortest path to the first forbidden step.
+export function reachedFrom(start: string, edgesFrom: ReadonlyMap<string, readonly ImportEdge[]>, forbidden: Matcher): readonly Reached[] {
+	const walk: Walk = { forbidden, queue: [start], reached: new Map(), trails: new Map([[start, { line: 0, path: [start] }]]) };
+	for (const node of walk.queue) {
+		const before = walk.trails.get(node) ?? { line: 0, path: [node] };
+		for (const edge of edgesFrom.get(node) ?? []) {
+			follow(walk, before, edge);
+		}
+	}
+	return [...walk.reached.values()];
+}

package/src/imports/fences/selectors.ts

@@ -0,0 +1,37 @@
+import type { External, Selector, Target } from "./model.ts";
+
+function target(selector: Selector): Target {
+	return { except: (...excluded) => target({ base: selector, excluded: excluded.map((member) => member.selector), kind: "except" }), selector };
+}
+
+export function packages(...names: readonly string[]): Target {
+	return target({ kind: "packages", names });
+}
+
+export function folders(...paths: readonly string[]): Target {
+	return target({ kind: "folders", paths });
+}
+
+export function files(...paths: readonly string[]): Target {
+	return target({ kind: "files", paths });
+}
+
+export function modules(...names: readonly string[]): Target {
+	return target({ kind: "modules", names });
+}
+
+export function scopes(...names: readonly string[]): Target {
+	return target({ kind: "scopes", names });
+}
+
+export function anyOf(...members: readonly Target[]): Target {
+	return target({ kind: "anyOf", members: members.map((member) => member.selector) });
+}
+
+export const workspace: Target = target({ kind: "workspace" });
+
+export const anything: Target = target({ kind: "anything" });
+
+export function external(specifier: string): External {
+	return { external: specifier };
+}

package/src/imports/fences/vocabulary.ts

@@ -0,0 +1,51 @@
+import type { Endpoint } from "../resolve.ts";
+import { type Compiler, holdsFiles, packageNamed, trimmed } from "./match.ts";
+import type { Selector } from "./model.ts";
+
+export interface Vocabulary {
+	readonly folder: string;
+	readonly subjectOf: (endpoint: Endpoint) => string | undefined;
+}
+
+const SOURCE_FOLDER = "src";
+
+const MODULE_EXTENSION = /\.[cm]?[jt]sx?$/u;
+
+function folderOf(compiler: Compiler, unit: Selector, where: string): string | undefined {
+	if (unit.kind === "packages" && unit.names.length === 1) {
+		const directory = packageNamed(compiler, unit.names[0] ?? "", where)?.directory;
+		return directory === undefined ? undefined : [`${directory}/${SOURCE_FOLDER}`, directory].find((folder) => holdsFiles(compiler, folder));
+	}
+	if (unit.kind === "folders" && unit.paths.length === 1) {
+		const folder = trimmed(unit.paths[0] ?? "");
+		if (!holdsFiles(compiler, folder)) {
+			compiler.issues.push(`${where}: folders("${folder}") holds no checked file`);
+		}
+		return folder;
+	}
+	compiler.issues.push(`${where}: of() takes one package or one folder`);
+	return undefined;
+}
+
+function subjectAt(folder: string, path: string): string | undefined {
+	if (!path.startsWith(`${folder}/`)) {
+		return undefined;
+	}
+	const [first = ""] = path.slice(folder.length + 1).split("/");
+	return first.replace(MODULE_EXTENSION, "");
+}
+
+export function compileVocabulary(compiler: Compiler, unit: Selector, subjects: readonly string[], where: string): Vocabulary | undefined {
+	const folder = folderOf(compiler, unit, where);
+	if (folder === undefined) {
+		return undefined;
+	}
+	const known = new Set(compiler.scope.files.flatMap((file) => subjectAt(folder, file) ?? []));
+	if (subjects.length === 0) {
+		compiler.issues.push(`${where}: mayImportOnly() names no subject`);
+	}
+	for (const subject of subjects.filter((candidate) => !known.has(candidate))) {
+		compiler.issues.push(`${where}: "${subject}" is no module or folder directly in ${folder}`);
+	}
+	return { folder, subjectOf: (endpoint) => (endpoint.kind === "file" ? subjectAt(folder, endpoint.path) : undefined) };
+}