@shivaedev/quality 0.3.1 → 0.5.0

package/src/config/resolve.ts

@@ -2,14 +2,13 @@ import { Effect } from "effect";
 import type { Level } from "../config.ts";
 import type { Decoded } from "../decoded.ts";
 import type { ActiveRule } from "../engine/run-rules.ts";
+import { covers, type RuleIndex } from "../engine/violation.ts";
 import type { Rule } from "../rule.ts";
 import { builtInRules } from "../rules/built-in.ts";
 import type { ConfigInput } from "./decode.ts";
 
-export interface ResolvedRules {
-	readonly active: ReadonlyArray<ActiveRule>;
-	readonly levels: ReadonlyMap<string, Level>;
-	readonly unregistrable: ReadonlySet<string>;
+export interface ResolvedRules extends RuleIndex {
+	readonly active: readonly ActiveRule[];
 }
 
 type Setting = NonNullable<ConfigInput["rules"]>[string];
@@ -20,7 +19,7 @@ const levelOf = (setting: Setting | undefined): Level => (typeof setting === "st
 
 const optionsOf = (setting: Setting | undefined): unknown => (typeof setting === "object" ? setting.options : undefined);
 
-const duplicateIssues = (rules: ReadonlyArray<Rule>): ReadonlyArray<string> =>
+const duplicateIssues = (rules: readonly Rule[]): readonly string[] =>
 	rules.flatMap((rule, index) =>
 		rules.findIndex((other) => other.id === rule.id) === index ? [] : [`local: rule id "${rule.id}" is already defined`],
 	);
@@ -35,7 +34,7 @@ const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decod
 			(configured): Decoded<ActiveRule | undefined> =>
 				configured._tag === "Invalid"
 					? { _tag: "Invalid", issues: configured.issues.map((issue) => `rules.${rule.id}.options: ${issue}`) }
-					: { _tag: "Valid", value: { check: configured.check, description: rule.description, id: rule.id, level } },
+					: { _tag: "Valid", value: { check: configured.check, description: rule.description, family: rule.family === true, id: rule.id, level } },
 		),
 		Effect.catch((failure: string) =>
 			Effect.succeed<Decoded<ActiveRule | undefined>>({ _tag: "Invalid", issues: [`rules.${rule.id}.options: validation threw: ${failure}`] }),
@@ -45,12 +44,17 @@ const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decod
 
 export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<ResolvedRules>> =>
 	Effect.gen(function* () {
-		const rules: ReadonlyArray<Rule> = [...builtInRules, ...(config.local ?? [])];
+		const rules: readonly Rule[] = [...builtInRules, ...(config.local ?? [])];
 		const settings = config.rules ?? {};
 		const known = new Set(rules.map((rule) => rule.id));
-		const unknown = [...Object.keys(settings).map((id) => `rules.${id}`), ...(config.adopt ?? []).map((id) => `adopt.${id}`)]
-			.filter((path) => !known.has(path.slice(path.indexOf(".") + 1)))
-			.map((path) => `${path}: no built-in or local rule has this id`);
+		const families = new Set(rules.filter((rule) => rule.family === true).map((rule) => rule.id));
+		const adoptable = (id: string): boolean => known.has(id) || [...families].some((family) => covers(family, id));
+		const unknown = [
+			...Object.keys(settings)
+				.filter((id) => !known.has(id))
+				.map((id) => `rules.${id}`),
+			...(config.adopt ?? []).filter((id) => !adoptable(id)).map((id) => `adopt.${id}`),
+		].map((path) => `${path}: no built-in or local rule has this id`);
 		const activated = yield* Effect.forEach(rules, (rule) => activate(rule, settings[rule.id]));
 		const issues = [...duplicateIssues(rules), ...unknown, ...activated.flatMap((result) => (result._tag === "Invalid" ? result.issues : []))];
 		if (issues.length > 0) {
@@ -59,5 +63,5 @@ export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<Resolve
 		const active = activated.flatMap((result) => (result._tag === "Valid" && result.value !== undefined ? [result.value] : []));
 		const levels = new Map(rules.map((rule) => [rule.id, levelOf(settings[rule.id])]));
 		const unregistrable = new Set(rules.filter((rule) => rule.registrable === false).map((rule) => rule.id));
-		return { _tag: "Valid", value: { active, levels, unregistrable } };
+		return { _tag: "Valid", value: { active, families, levels, unregistrable } };
 	});

package/src/config.ts

@@ -7,23 +7,23 @@ export type RuleSetting<Input> = Level | { readonly level?: Level; readonly opti
 
 type InputOf<Candidate> = Candidate extends Rule<string, infer Input> ? Input : never;
 
-export type RuleSettings<Rules extends ReadonlyArray<Rule>> = {
+export type RuleSettings<Rules extends readonly Rule[]> = {
 	readonly [Candidate in Rules[number] as Candidate["id"]]?: RuleSetting<InputOf<Candidate>>;
 };
 
 export type BuiltInRules = typeof builtInRules;
 
-type IdOf<Rules extends ReadonlyArray<Rule>> = Rules[number]["id"];
+type IdOf<Rules extends readonly Rule[]> = Rules[number]["id"];
 
-export interface QualityConfig<Local extends ReadonlyArray<Rule> = ReadonlyArray<Rule>> {
-	readonly sources?: ReadonlyArray<string>;
-	readonly exclude?: ReadonlyArray<string>;
-	readonly extensions?: ReadonlyArray<string>;
-	readonly registry?: string;
+export interface QualityConfig<Local extends readonly Rule[] = readonly Rule[]> {
+	readonly adopt?: readonly IdOf<readonly [...BuiltInRules, ...Local]>[];
 	readonly baseline?: string;
-	readonly adopt?: ReadonlyArray<IdOf<readonly [...BuiltInRules, ...Local]>>;
+	readonly exclude?: readonly string[];
+	readonly extensions?: readonly string[];
 	readonly local?: Local;
+	readonly registry?: string;
 	readonly rules?: RuleSettings<readonly [...BuiltInRules, ...Local]>;
+	readonly sources?: readonly string[];
 }
 
-export const defineConfig = <const Local extends ReadonlyArray<Rule> = readonly []>(config: QualityConfig<Local>): QualityConfig<Local> => config;
+export const defineConfig = <const Local extends readonly Rule[] = readonly []>(config: QualityConfig<Local>): QualityConfig<Local> => config;

package/src/decoded.ts

@@ -2,7 +2,7 @@ import { Effect } from "effect";
 import { SetupFailure } from "./failure.ts";
 import { describeIssue, type StandardSchemaV1 } from "./standard-schema.ts";
 
-export type Decoded<Value> = { readonly _tag: "Valid"; readonly value: Value } | { readonly _tag: "Invalid"; readonly issues: ReadonlyArray<string> };
+export type Decoded<Value> = { readonly _tag: "Valid"; readonly value: Value } | { readonly _tag: "Invalid"; readonly issues: readonly string[] };
 
 export const decodeWith = async <Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown): Promise<Decoded<Output>> => {
 	const result = await schema["~standard"].validate(value);

package/src/engine/baseline-file.ts

@@ -8,8 +8,8 @@ import { SetupFailure } from "../failure.ts";
 import { readOptionalText } from "../inventory/filesystem.ts";
 
 export interface BaselineFile {
+	readonly entries: readonly BaselineEntry[];
 	readonly raw: string | undefined;
-	readonly entries: ReadonlyArray<BaselineEntry>;
 }
 
 export const readInput = (root: string, path: string): Effect.Effect<string | undefined, SetupFailure, FileSystem.FileSystem> =>

package/src/engine/evaluate.ts

@@ -1,36 +1,34 @@
 import { applyBaseline, type Regression, type StaleBaselineEntry } from "../baseline/compare.ts";
 import type { BaselineEntry } from "../baseline/format.ts";
-import type { Level } from "../config.ts";
 import { applyRegistry, type RegistryEntry, type StaleRegistryEntry } from "../exceptions/registry.ts";
-import { byLocation, type Violation } from "./violation.ts";
+import { byLocation, type RuleIndex, type Violation } from "./violation.ts";
 
 export interface Outcome {
-	readonly errors: ReadonlyArray<Violation>;
-	readonly warnings: ReadonlyArray<Violation>;
-	readonly regressions: ReadonlyArray<Regression>;
-	readonly staleBaseline: ReadonlyArray<StaleBaselineEntry>;
-	readonly looseBaseline: ReadonlyArray<StaleBaselineEntry>;
-	readonly staleRegistry: ReadonlyArray<StaleRegistryEntry>;
 	readonly baselined: number;
+	readonly errors: readonly Violation[];
+	readonly looseBaseline: readonly StaleBaselineEntry[];
 	readonly registered: number;
+	readonly regressions: readonly Regression[];
+	readonly staleBaseline: readonly StaleBaselineEntry[];
+	readonly staleRegistry: readonly StaleRegistryEntry[];
+	readonly warnings: readonly Violation[];
 }
 
 export const evaluate = (
-	violations: ReadonlyArray<Violation>,
-	registry: ReadonlyArray<RegistryEntry>,
-	baseline: ReadonlyArray<BaselineEntry>,
-	levels: ReadonlyMap<string, Level>,
-	unregistrable: ReadonlySet<string>,
+	violations: readonly Violation[],
+	registry: readonly RegistryEntry[],
+	baseline: readonly BaselineEntry[],
+	rules: RuleIndex,
 ): Outcome => {
-	const registered = applyRegistry(violations, registry, levels, unregistrable);
-	const baselined = applyBaseline(registered.kept, baseline, levels);
+	const registered = applyRegistry(violations, registry, rules);
+	const baselined = applyBaseline(registered.kept, baseline, rules);
 	const kept = [...baselined.kept].sort(byLocation);
 	return {
 		baselined: baselined.baselined,
 		errors: kept.filter((violation) => violation.level === "error"),
 		looseBaseline: baselined.loose,
-		regressions: baselined.regressions,
 		registered: registered.registered,
+		regressions: baselined.regressions,
 		staleBaseline: baselined.stale,
 		staleRegistry: registered.stale,
 		warnings: kept.filter((violation) => violation.level === "warn"),

package/src/engine/run-rules.ts

@@ -6,34 +6,35 @@ import type { Finding, Findings, RuleInputs } from "../rule.ts";
 import type { ActiveLevel, Violation } from "./violation.ts";
 
 export interface ActiveRule {
-	readonly id: string;
+	readonly check: (inputs: RuleInputs) => Promise<Findings>;
 	readonly description: string;
+	readonly family: boolean;
+	readonly id: string;
 	readonly level: ActiveLevel;
-	readonly check: (inputs: RuleInputs) => Promise<Findings>;
 }
 
 const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
 
 // Registry and baseline entries match on the path, so every finding names its file the same way.
-const repositoryPath = (root: string, file: string): string => posix(isAbsolute(file) ? relative(root, file) : file).replace(/^(\.\/)+/, "");
+const repositoryPath = (root: string, file: string): string => posix(isAbsolute(file) ? relative(root, file) : file).replace(/^(\.\/)+/u, "");
 
 const violationOf = (rule: ActiveRule, root: string, finding: Finding): Violation => ({
 	...finding,
 	file: repositoryPath(root, finding.file),
 	level: rule.level,
-	rule: rule.id,
+	rule: rule.family && finding.subject !== undefined ? `${rule.id}/${finding.subject}` : rule.id,
 });
 
-const runRule = (rule: ActiveRule, inputs: RuleInputs): Effect.Effect<ReadonlyArray<Violation>, SetupFailure> =>
+const runRule = (rule: ActiveRule, inputs: RuleInputs): Effect.Effect<readonly Violation[], SetupFailure> =>
 	Effect.map(
 		Effect.tryPromise({
-			try: () => rule.check(inputs),
 			catch: (cause) => new SetupFailure({ message: `rule ${rule.id} failed: ${messageOf(cause)}` }),
+			try: () => rule.check(inputs),
 		}),
 		(findings) => findings.map((finding) => violationOf(rule, inputs.root, finding)),
 	);
 
-export const runRules = (rules: ReadonlyArray<ActiveRule>, inputs: RuleInputs): Effect.Effect<ReadonlyArray<Violation>, SetupFailure> =>
+export const runRules = (rules: readonly ActiveRule[], inputs: RuleInputs): Effect.Effect<readonly Violation[], SetupFailure> =>
 	Effect.map(
 		Effect.forEach(rules, (rule) => runRule(rule, inputs), { concurrency: "unbounded" }),
 		(results) => results.flat(),

package/src/engine/session.ts

@@ -11,11 +11,11 @@ import { runRules } from "./run-rules.ts";
 import type { Violation } from "./violation.ts";
 
 export interface Session {
+	readonly baseline: BaselineFile;
 	readonly config: ResolvedConfig;
 	readonly inventory: Inventory;
-	readonly violations: ReadonlyArray<Violation>;
-	readonly registry: ReadonlyArray<RegistryEntry>;
-	readonly baseline: BaselineFile;
+	readonly registry: readonly RegistryEntry[];
+	readonly violations: readonly Violation[];
 }
 
 const setup = <Value, Requirements>(

package/src/engine/violation.ts

@@ -4,8 +4,8 @@ import type { Finding } from "../rule.ts";
 export type ActiveLevel = "error" | "warn";
 
 export interface Violation extends Finding {
-	readonly rule: string;
 	readonly level: ActiveLevel;
+	readonly rule: string;
 }
 
 export const keyOf = (rule: string, file: string): string => `${rule}\u0000${file}`;
@@ -13,7 +13,7 @@ export const keyOf = (rule: string, file: string): string => `${rule}\u0000${fil
 export const byLocation = (left: Violation, right: Violation): number =>
 	left.rule.localeCompare(right.rule) || left.file.localeCompare(right.file) || (left.line ?? 0) - (right.line ?? 0);
 
-export const groupBy = <Item>(items: ReadonlyArray<Item>, key: (item: Item) => string): ReadonlyMap<string, ReadonlyArray<Item>> => {
+export const groupBy = <Item>(items: readonly Item[], key: (item: Item) => string): ReadonlyMap<string, readonly Item[]> => {
 	const groups = new Map<string, Item[]>();
 	for (const item of items) {
 		const group = groups.get(key(item));
@@ -26,8 +26,22 @@ export const groupBy = <Item>(items: ReadonlyArray<Item>, key: (item: Item) => s
 	return groups;
 };
 
-export const unusedEntryProblem = (levels: ReadonlyMap<string, Level>, rule: string, unused: string): string => {
-	const level = levels.get(rule);
+export interface RuleIndex {
+	readonly families: ReadonlySet<string>;
+	readonly levels: ReadonlyMap<string, Level>;
+	readonly unregistrable: ReadonlySet<string>;
+}
+
+export const covers = (name: string, rule: string): boolean => rule === name || rule.startsWith(`${name}/`);
+
+const ownerOf = (index: RuleIndex, rule: string): string => [...index.families].find((family) => covers(family, rule)) ?? rule;
+
+export const levelOf = (index: RuleIndex, rule: string): Level | undefined => index.levels.get(ownerOf(index, rule));
+
+export const registrable = (index: RuleIndex, rule: string): boolean => !index.unregistrable.has(ownerOf(index, rule));
+
+export const unusedEntryProblem = (index: RuleIndex, rule: string, unused: string): string => {
+	const level = levelOf(index, rule);
 	if (level === undefined) {
 		return "names no known rule";
 	}

package/src/exceptions/registry.ts

@@ -1,13 +1,12 @@
 import { Schema } from "effect";
-import type { Level } from "../config.ts";
 import { type Decoded, decodeWith } from "../decoded.ts";
-import { unusedEntryProblem, type Violation } from "../engine/violation.ts";
+import { type RuleIndex, registrable, unusedEntryProblem, type Violation } from "../engine/violation.ts";
 
 const RegistryEntry = Schema.Struct({
-	rule: Schema.NonEmptyString,
 	file: Schema.NonEmptyString,
+	reason: Schema.String.check(Schema.isPattern(/\S/u, { expected: "a reason that says why the exception is permanent" })),
+	rule: Schema.NonEmptyString,
 	subject: Schema.optionalKey(Schema.NonEmptyString),
-	reason: Schema.String.check(Schema.isPattern(/\S/, { expected: "a reason that says why the exception is permanent" })),
 });
 
 export type RegistryEntry = typeof RegistryEntry.Type;
@@ -16,7 +15,7 @@ const standard = Schema.toStandardSchemaV1(Schema.fromJsonString(Schema.Array(Re
 	parseOptions: { errors: "all", onExcessProperty: "error" },
 });
 
-export const decodeRegistry = (raw: string | undefined): Promise<Decoded<ReadonlyArray<RegistryEntry>>> =>
+export const decodeRegistry = (raw: string | undefined): Promise<Decoded<readonly RegistryEntry[]>> =>
 	raw === undefined ? Promise.resolve({ _tag: "Valid", value: [] }) : decodeWith(standard, raw);
 
 export interface StaleRegistryEntry {
@@ -25,9 +24,9 @@ export interface StaleRegistryEntry {
 }
 
 export interface RegistryCheck {
-	readonly kept: ReadonlyArray<Violation>;
+	readonly kept: readonly Violation[];
 	readonly registered: number;
-	readonly stale: ReadonlyArray<StaleRegistryEntry>;
+	readonly stale: readonly StaleRegistryEntry[];
 }
 
 const covers = (entry: RegistryEntry, violation: Violation): boolean =>
@@ -35,18 +34,13 @@ const covers = (entry: RegistryEntry, violation: Violation): boolean =>
 
 const UNREGISTRABLE = "names a rule that takes no exceptions. Fix the code, or baseline the violations while the repository adopts the rule";
 
-const coveringEntry = (entries: ReadonlyArray<RegistryEntry>, violation: Violation): RegistryEntry | undefined => {
+const coveringEntry = (entries: readonly RegistryEntry[], violation: Violation): RegistryEntry | undefined => {
 	const matching = entries.filter((entry) => covers(entry, violation));
 	return matching.find((entry) => entry.subject !== undefined) ?? matching[0];
 };
 
-export const applyRegistry = (
-	violations: ReadonlyArray<Violation>,
-	entries: ReadonlyArray<RegistryEntry>,
-	levels: ReadonlyMap<string, Level>,
-	unregistrable: ReadonlySet<string>,
-): RegistryCheck => {
-	const usable = entries.filter((entry) => !unregistrable.has(entry.rule));
+export const applyRegistry = (violations: readonly Violation[], entries: readonly RegistryEntry[], rules: RuleIndex): RegistryCheck => {
+	const usable = entries.filter((entry) => registrable(rules, entry.rule));
 	const used = new Set<RegistryEntry>();
 	const kept = violations.filter((violation) => {
 		const entry = coveringEntry(usable, violation);
@@ -59,7 +53,7 @@ export const applyRegistry = (
 		.filter((entry) => !used.has(entry))
 		.map((entry) => ({
 			entry,
-			problem: unregistrable.has(entry.rule) ? UNREGISTRABLE : unusedEntryProblem(levels, entry.rule, "matches no violation"),
+			problem: registrable(rules, entry.rule) ? unusedEntryProblem(rules, entry.rule, "matches no violation") : UNREGISTRABLE,
 		}));
 	return { kept, registered: violations.length - kept.length, stale };
 };

package/src/git/base.ts

@@ -3,8 +3,8 @@ import { SetupFailure } from "../failure.ts";
 import { type Git, git } from "./command.ts";
 
 export interface Base {
-	readonly ref: string;
 	readonly commit: string;
+	readonly ref: string;
 }
 
 const FALLBACK_BRANCHES = ["origin/main", "origin/master"];
@@ -36,7 +36,7 @@ const isShallow = (root: string): Effect.Effect<boolean, SetupFailure, Git> =>
 const mergeBase = (root: string, ref: string): Effect.Effect<string | undefined, SetupFailure, Git> =>
 	Effect.map(git(root, ["merge-base", "HEAD", ref]), (result) => (result.code === 0 ? result.stdout.trim() : undefined));
 
-const remoteOf = (root: string, ref: string): Effect.Effect<ReadonlyArray<string>, SetupFailure, Git> =>
+const remoteOf = (root: string, ref: string): Effect.Effect<readonly string[], SetupFailure, Git> =>
 	Effect.gen(function* () {
 		const name = (yield* git(root, ["rev-parse", "--symbolic-full-name", ref])).stdout.trim();
 		const remotes = (yield* git(root, ["remote"])).stdout.split("\n");

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] ?? ""));
+}