@shivaedev/quality 0.0.0 → 0.1.0

package/src/config/load.ts

@@ -0,0 +1,58 @@
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Effect, FileSystem } from "effect";
+import { validOrFail } from "../decoded.ts";
+import { SetupFailure } from "../failure.ts";
+import type { InventoryScope } from "../inventory/collect.ts";
+import { type ConfigInput, decodeConfig } from "./decode.ts";
+import { type ResolvedRules, resolveRules } from "./resolve.ts";
+
+export const CONFIG_FILE = "quality.config.ts";
+
+const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+
+export interface ResolvedConfig extends ResolvedRules, InventoryScope {
+	readonly root: string;
+	readonly file: string;
+	readonly registry: string;
+	readonly baseline: string;
+}
+
+const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
+
+const importDefault = (file: string): Effect.Effect<unknown, SetupFailure> =>
+	Effect.flatMap(
+		Effect.tryPromise({
+			try: async (): Promise<unknown> => import(pathToFileURL(file).href),
+			catch: (cause) => new SetupFailure({ message: `cannot load ${file}: ${messageOf(cause)}` }),
+		}),
+		(loaded) =>
+			typeof loaded === "object" && loaded !== null && "default" in loaded
+				? Effect.succeed(loaded.default)
+				: Effect.fail(new SetupFailure({ message: `${file} has no default export. Export defineConfig({ ... }) as the default.` })),
+	);
+
+const resolved = (root: string, file: string, config: ConfigInput, rules: ResolvedRules): ResolvedConfig => ({
+	...rules,
+	baseline: config.baseline ?? "quality/baseline.json",
+	exclude: config.exclude ?? [],
+	extensions: config.extensions ?? DEFAULT_EXTENSIONS,
+	file,
+	registry: config.registry ?? "quality/registry.json",
+	root,
+	sources: config.sources ?? ["."],
+});
+
+export const loadConfig = (cwd: string, path: string | undefined): Effect.Effect<ResolvedConfig, SetupFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const file = resolve(cwd, path ?? CONFIG_FILE);
+		const present = yield* Effect.orElseSucceed(fs.exists(file), () => false);
+		if (!present) {
+			return yield* new SetupFailure({ message: `no config at ${file}. Create ${CONFIG_FILE} exporting defineConfig({ ... }), or pass --config.` });
+		}
+		const loaded = yield* importDefault(file);
+		const config = yield* validOrFail(file, yield* Effect.promise(() => decodeConfig(loaded)));
+		const rules = yield* validOrFail(file, yield* resolveRules(config));
+		return resolved(dirname(file), file, config, rules);
+	});

package/src/config/resolve.ts

@@ -0,0 +1,60 @@
+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 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>;
+}
+
+type Setting = NonNullable<ConfigInput["rules"]>[string];
+
+const messageOf = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
+
+const levelOf = (setting: Setting | undefined): Level => (typeof setting === "string" ? setting : (setting?.level ?? "error"));
+
+const optionsOf = (setting: Setting | undefined): unknown => (typeof setting === "object" ? setting.options : undefined);
+
+const duplicateIssues = (rules: ReadonlyArray<Rule>): ReadonlyArray<string> =>
+	rules.flatMap((rule, index) =>
+		rules.findIndex((other) => other.id === rule.id) === index ? [] : [`local: rule id "${rule.id}" is already defined`],
+	);
+
+const activate = (rule: Rule, setting: Setting | undefined): Effect.Effect<Decoded<ActiveRule | undefined>> => {
+	const level = levelOf(setting);
+	if (level === "off") {
+		return Effect.succeed({ _tag: "Valid", value: undefined });
+	}
+	return Effect.tryPromise({ catch: messageOf, try: () => rule.configure(optionsOf(setting)) }).pipe(
+		Effect.map(
+			(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 } },
+		),
+		Effect.catch((failure: string) =>
+			Effect.succeed<Decoded<ActiveRule | undefined>>({ _tag: "Invalid", issues: [`rules.${rule.id}.options: validation threw: ${failure}`] }),
+		),
+	);
+};
+
+export const resolveRules = (config: ConfigInput): Effect.Effect<Decoded<ResolvedRules>> =>
+	Effect.gen(function* () {
+		const rules: ReadonlyArray<Rule> = [...builtInRules, ...(config.local ?? [])];
+		const settings = config.rules ?? {};
+		const known = new Set(rules.map((rule) => rule.id));
+		const unknown = Object.keys(settings)
+			.filter((id) => !known.has(id))
+			.map((id) => `rules.${id}: 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) {
+			return { _tag: "Invalid", issues };
+		}
+		const active = activated.flatMap((result) => (result._tag === "Valid" && result.value !== undefined ? [result.value] : []));
+		return { _tag: "Valid", value: { active, levels: new Map(rules.map((rule) => [rule.id, levelOf(settings[rule.id])])) } };
+	});

package/src/config.ts

@@ -0,0 +1,33 @@
+import type { Rule } from "./rule.ts";
+import type { builtInRules } from "./rules/built-in.ts";
+
+/** Every rule defaults to `error`. `warn` is for the transition to a rule and is meant to be temporary. */
+export type Level = "error" | "warn" | "off";
+
+export type RuleSetting<Input> = Level | { readonly level?: Level; readonly options?: Input };
+
+type InputOf<Candidate> = Candidate extends Rule<string, infer Input> ? Input : never;
+
+export type RuleSettings<Rules extends ReadonlyArray<Rule>> = {
+	readonly [Candidate in Rules[number] as Candidate["id"]]?: RuleSetting<InputOf<Candidate>>;
+};
+
+export type BuiltInRules = typeof builtInRules;
+
+export interface QualityConfig<Local extends ReadonlyArray<Rule> = ReadonlyArray<Rule>> {
+	/** Directories or files to check, relative to the config file. Defaults to the whole repository. */
+	readonly sources?: ReadonlyArray<string>;
+	/** Paths never checked, in .gitignore syntax. Ignored files are always skipped. */
+	readonly exclude?: ReadonlyArray<string>;
+	/** Extensions of the source files rules read. Defaults to TypeScript and JavaScript modules. */
+	readonly extensions?: ReadonlyArray<string>;
+	/** Permanent exceptions, each with a reason. Defaults to `quality/registry.json`. */
+	readonly registry?: string;
+	/** Existing violations that may only shrink. Defaults to `quality/baseline.json`. */
+	readonly baseline?: string;
+	/** Repository rules, reported, registered and baselined like the built-in ones. */
+	readonly local?: Local;
+	readonly rules?: RuleSettings<readonly [...BuiltInRules, ...Local]>;
+}
+
+export const defineConfig = <const Local extends ReadonlyArray<Rule> = readonly []>(config: QualityConfig<Local>): QualityConfig<Local> => config;

package/src/decoded.ts

@@ -0,0 +1,15 @@
+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 const decodeWith = async <Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown): Promise<Decoded<Output>> => {
+	const result = await schema["~standard"].validate(value);
+	return result.issues === undefined ? { _tag: "Valid", value: result.value } : { _tag: "Invalid", issues: result.issues.map(describeIssue) };
+};
+
+export const validOrFail = <Value>(file: string, decoded: Decoded<Value>): Effect.Effect<Value, SetupFailure> =>
+	decoded._tag === "Valid"
+		? Effect.succeed(decoded.value)
+		: Effect.fail(new SetupFailure({ message: `${file} is invalid:\n${decoded.issues.map((issue) => `  - ${issue}`).join("\n")}` }));

package/src/engine/evaluate.ts

@@ -0,0 +1,39 @@
+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";
+
+export interface Outcome {
+	readonly errors: ReadonlyArray<Violation>;
+	readonly warnings: ReadonlyArray<Violation>;
+	readonly regressions: ReadonlyArray<Regression>;
+	readonly staleBaseline: ReadonlyArray<StaleBaselineEntry>;
+	readonly staleRegistry: ReadonlyArray<StaleRegistryEntry>;
+	readonly baselined: number;
+	readonly registered: number;
+}
+
+/** Registered exceptions apply first; the baseline then covers what is left, per rule and file. */
+export const evaluate = (
+	violations: ReadonlyArray<Violation>,
+	registry: ReadonlyArray<RegistryEntry>,
+	baseline: ReadonlyArray<BaselineEntry>,
+	levels: ReadonlyMap<string, Level>,
+): Outcome => {
+	const registered = applyRegistry(violations, registry, levels);
+	const baselined = applyBaseline(registered.kept, baseline, levels);
+	const kept = [...baselined.kept].sort(byLocation);
+	return {
+		baselined: baselined.baselined,
+		errors: kept.filter((violation) => violation.level === "error"),
+		regressions: baselined.regressions,
+		registered: registered.registered,
+		staleBaseline: baselined.stale,
+		staleRegistry: registered.stale,
+		warnings: kept.filter((violation) => violation.level === "warn"),
+	};
+};
+
+export const passes = (outcome: Outcome): boolean =>
+	outcome.errors.length === 0 && outcome.staleBaseline.length === 0 && outcome.staleRegistry.length === 0;

package/src/engine/run-rules.ts

@@ -0,0 +1,40 @@
+import { isAbsolute, relative } from "node:path";
+import { Effect } from "effect";
+import { SetupFailure } from "../failure.ts";
+import { posix } from "../inventory/ignore-scope.ts";
+import type { Finding, Findings, RuleInputs } from "../rule.ts";
+import type { ActiveLevel, Violation } from "./violation.ts";
+
+export interface ActiveRule {
+	readonly id: string;
+	readonly description: 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 violationOf = (rule: ActiveRule, root: string, finding: Finding): Violation => ({
+	...finding,
+	file: repositoryPath(root, finding.file),
+	level: rule.level,
+	rule: rule.id,
+});
+
+const runRule = (rule: ActiveRule, inputs: RuleInputs): Effect.Effect<ReadonlyArray<Violation>, SetupFailure> =>
+	Effect.map(
+		Effect.tryPromise({
+			try: () => rule.check(inputs),
+			catch: (cause) => new SetupFailure({ message: `rule ${rule.id} failed: ${messageOf(cause)}` }),
+		}),
+		(findings) => findings.map((finding) => violationOf(rule, inputs.root, finding)),
+	);
+
+export const runRules = (rules: ReadonlyArray<ActiveRule>, inputs: RuleInputs): Effect.Effect<ReadonlyArray<Violation>, SetupFailure> =>
+	Effect.map(
+		Effect.forEach(rules, (rule) => runRule(rule, inputs), { concurrency: "unbounded" }),
+		(results) => results.flat(),
+	);

package/src/engine/session.ts

@@ -0,0 +1,40 @@
+import { join, resolve } from "node:path";
+import { Effect, type FileSystem } from "effect";
+import { type BaselineEntry, decodeBaseline } from "../baseline/format.ts";
+import { loadConfig, type ResolvedConfig } from "../config/load.ts";
+import { validOrFail } from "../decoded.ts";
+import { decodeRegistry, type RegistryEntry } from "../exceptions/registry.ts";
+import { SetupFailure } from "../failure.ts";
+import { collectInventory, type Inventory } from "../inventory/collect.ts";
+import { type FilesystemFailure, readOptionalText } from "../inventory/filesystem.ts";
+import { runRules } from "./run-rules.ts";
+import type { Violation } from "./violation.ts";
+
+export interface Session {
+	readonly config: ResolvedConfig;
+	readonly inventory: Inventory;
+	readonly violations: ReadonlyArray<Violation>;
+	readonly registry: ReadonlyArray<RegistryEntry>;
+	readonly baseline: { readonly raw: string | undefined; readonly entries: ReadonlyArray<BaselineEntry> };
+}
+
+const setup = <Value, Requirements>(
+	effect: Effect.Effect<Value, FilesystemFailure, Requirements>,
+): Effect.Effect<Value, SetupFailure, Requirements> => Effect.mapError(effect, (failure) => new SetupFailure({ message: failure.message }));
+
+const readInput = (root: string, path: string): Effect.Effect<string | undefined, SetupFailure, FileSystem.FileSystem> =>
+	setup(readOptionalText(join(root, path)));
+
+export const openSession = (cwd: string, configPath: string | undefined): Effect.Effect<Session, SetupFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const config = yield* loadConfig(cwd, configPath);
+		const inventory = yield* setup(collectInventory(config.root, config));
+		const registryRaw = yield* readInput(config.root, config.registry);
+		const registry = yield* validOrFail(config.registry, yield* Effect.promise(() => decodeRegistry(registryRaw)));
+		const baselineRaw = yield* readInput(config.root, config.baseline);
+		const baseline = yield* validOrFail(config.baseline, yield* Effect.promise(() => decodeBaseline(baselineRaw)));
+		const services = yield* Effect.context<FileSystem.FileSystem>();
+		const readText = (path: string): Promise<string | undefined> => Effect.runPromiseWith(services)(readOptionalText(resolve(config.root, path)));
+		const violations = yield* runRules(config.active, { files: inventory.files, readText, root: config.root, sources: inventory.sources });
+		return { baseline: { entries: baseline, raw: baselineRaw }, config, inventory, registry, violations };
+	});

package/src/engine/violation.ts

@@ -0,0 +1,35 @@
+import type { Level } from "../config.ts";
+import type { Finding } from "../rule.ts";
+
+export type ActiveLevel = "error" | "warn";
+
+export interface Violation extends Finding {
+	readonly rule: string;
+	readonly level: ActiveLevel;
+}
+
+export const keyOf = (rule: string, file: string): string => `${rule}\u0000${file}`;
+
+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>> => {
+	const groups = new Map<string, Item[]>();
+	for (const item of items) {
+		const group = groups.get(key(item));
+		if (group === undefined) {
+			groups.set(key(item), [item]);
+		} else {
+			group.push(item);
+		}
+	}
+	return groups;
+};
+
+export const unusedEntryProblem = (levels: ReadonlyMap<string, Level>, rule: string, unused: string): string => {
+	const level = levels.get(rule);
+	if (level === undefined) {
+		return "names no known rule";
+	}
+	return level === "off" ? "names a rule that is off" : unused;
+};

package/src/exceptions/registry.ts

@@ -0,0 +1,58 @@
+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";
+
+const RegistryEntry = Schema.Struct({
+	rule: Schema.NonEmptyString,
+	file: 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;
+
+const standard = Schema.toStandardSchemaV1(Schema.fromJsonString(Schema.Array(RegistryEntry)), {
+	parseOptions: { errors: "all", onExcessProperty: "error" },
+});
+
+export const decodeRegistry = (raw: string | undefined): Promise<Decoded<ReadonlyArray<RegistryEntry>>> =>
+	raw === undefined ? Promise.resolve({ _tag: "Valid", value: [] }) : decodeWith(standard, raw);
+
+export interface StaleRegistryEntry {
+	readonly entry: RegistryEntry;
+	readonly problem: string;
+}
+
+export interface RegistryCheck {
+	readonly kept: ReadonlyArray<Violation>;
+	readonly registered: number;
+	readonly stale: ReadonlyArray<StaleRegistryEntry>;
+}
+
+const covers = (entry: RegistryEntry, violation: Violation): boolean =>
+	entry.rule === violation.rule && entry.file === violation.file && (entry.subject === undefined || entry.subject === violation.subject);
+
+const coveringEntry = (entries: ReadonlyArray<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>,
+): RegistryCheck => {
+	const used = new Set<RegistryEntry>();
+	const kept = violations.filter((violation) => {
+		const entry = coveringEntry(entries, violation);
+		if (entry !== undefined) {
+			used.add(entry);
+		}
+		return entry === undefined;
+	});
+	const stale = entries
+		.filter((entry) => !used.has(entry))
+		.map((entry) => ({ entry, problem: unusedEntryProblem(levels, entry.rule, "matches no violation") }));
+	return { kept, registered: violations.length - kept.length, stale };
+};

package/src/failure.ts

@@ -0,0 +1,13 @@
+import { Data, Runtime } from "effect";
+
+/** The check could not run: invalid configuration, unreadable input or a crashed rule. Exits 2. */
+export class SetupFailure extends Data.TaggedError("SetupFailure")<{ readonly message: string }> {
+	override readonly [Runtime.errorReported] = false;
+	override readonly [Runtime.errorExitCode] = 2;
+}
+
+/** The check ran and the repository fails the gate. The report is already printed. Exits 1. */
+export class GateFailed extends Data.TaggedError("GateFailed") {
+	override readonly [Runtime.errorReported] = false;
+	override readonly [Runtime.errorExitCode] = 1;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export type { BuiltInRules, Level, QualityConfig, RuleSetting, RuleSettings } from "./config.ts";
+export { defineConfig } from "./config.ts";
+export type { Configured, Finding, Findings, Rule, RuleContext, RuleInputs, SourceFile } from "./rule.ts";
+export { defineRule } from "./rule.ts";
+export type { StandardIssue, StandardResult, StandardSchemaV1 } from "./standard-schema.ts";

package/src/inventory/collect.ts

@@ -0,0 +1,53 @@
+import { join, relative } from "node:path";
+import { Effect, FileSystem } from "effect";
+import ignore from "ignore";
+import type { SourceFile } from "../rule.ts";
+import { FilesystemFailure, orWhenAbsent, readRequiredText } from "./filesystem.ts";
+import { posix } from "./ignore-scope.ts";
+import { scopeAbove, walk } from "./walk.ts";
+
+export interface InventoryScope {
+	readonly sources: ReadonlyArray<string>;
+	readonly exclude: ReadonlyArray<string>;
+	readonly extensions: ReadonlyArray<string>;
+}
+
+export interface Inventory {
+	readonly files: ReadonlyArray<string>;
+	readonly sources: ReadonlyArray<SourceFile>;
+}
+
+const READ_CONCURRENCY = 16;
+
+export const linesOf = (text: string): ReadonlyArray<string> => {
+	const lines = text.split("\n");
+	return lines.at(-1) === "" ? lines.slice(0, -1) : lines;
+};
+
+const zoneFiles = (root: string, zone: string): Effect.Effect<readonly string[], FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = join(root, zone);
+		if (posix(relative(root, path)).startsWith("..")) {
+			return yield* new FilesystemFailure({ message: `source "${zone}" lies outside the repository at ${root}`, path });
+		}
+		const info = yield* orWhenAbsent<FileSystem.File.Info | undefined>(path, fs.stat(path), undefined);
+		if (info === undefined) {
+			return yield* new FilesystemFailure({ message: `source "${zone}" does not exist in ${root}`, path });
+		}
+		return info.type === "Directory" ? yield* walk(path, yield* scopeAbove(root, path)) : [path];
+	});
+
+const readSource = (root: string, path: string): Effect.Effect<SourceFile, FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.map(readRequiredText(join(root, path)), (text) => ({ lines: linesOf(text), path, text }));
+
+export const collectInventory = (root: string, scope: InventoryScope): Effect.Effect<Inventory, FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const excluded = ignore().add([...scope.exclude]);
+		const zones = yield* Effect.forEach(scope.sources, (zone) => zoneFiles(root, zone), { concurrency: READ_CONCURRENCY });
+		const relativePaths = zones.flat().map((absolute) => posix(relative(root, absolute)));
+		const files = [...new Set(relativePaths)].filter((path) => !excluded.ignores(path)).sort();
+		const sourcePaths = files.filter((path) => scope.extensions.some((extension) => path.endsWith(extension)));
+		const sources = yield* Effect.forEach(sourcePaths, (path) => readSource(root, path), { concurrency: READ_CONCURRENCY });
+		return { files, sources };
+	});

package/src/inventory/filesystem.ts

@@ -0,0 +1,47 @@
+import { dirname } from "node:path";
+import { Data, Effect, FileSystem } from "effect";
+import type { PlatformError } from "effect/PlatformError";
+
+const ABSENT = new Set(["ENOENT", "ENOTDIR"]);
+
+export class FilesystemFailure extends Data.TaggedError("FilesystemFailure")<{
+	readonly message: string;
+	readonly path: string;
+}> {}
+
+// Effect maps ENOTDIR and EISDIR to BadResource; the original errno remains on the cause.
+const errnoOf = (error: PlatformError): string => {
+	const cause: unknown = error.reason.cause;
+	return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string" ? cause.code : "";
+};
+
+const failure = (path: string, error: PlatformError): FilesystemFailure =>
+	new FilesystemFailure({ message: `cannot read ${path}: ${error.message}`, path });
+
+export const orWhenAbsent = <Value>(
+	path: string,
+	action: Effect.Effect<Value, PlatformError, FileSystem.FileSystem>,
+	whenAbsent: Value,
+): Effect.Effect<Value, FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.catchTag(action, "PlatformError", (error) => (ABSENT.has(errnoOf(error)) ? Effect.succeed(whenAbsent) : Effect.fail(failure(path, error))));
+
+export const readOptionalText = (path: string): Effect.Effect<string | undefined, FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		return yield* orWhenAbsent<string | undefined>(path, fs.readFileString(path), undefined);
+	});
+
+export const readRequiredText = (path: string): Effect.Effect<string, FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		return yield* Effect.mapError(fs.readFileString(path), (error) =>
+			ABSENT.has(errnoOf(error)) ? new FilesystemFailure({ message: `required input is missing: ${path}`, path }) : failure(path, error),
+		);
+	});
+
+export const writeText = (path: string, text: string): Effect.Effect<void, FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const written = Effect.andThen(fs.makeDirectory(dirname(path), { recursive: true }), fs.writeFileString(path, text));
+		return yield* Effect.mapError(written, (error) => new FilesystemFailure({ message: `cannot write ${path}: ${error.message}`, path }));
+	});

package/src/inventory/ignore-scope.ts

@@ -0,0 +1,44 @@
+import { relative } from "node:path";
+import ignore from "ignore";
+
+export type Verdict = "ignored" | "kept" | "unknown";
+
+interface IgnoreMatcher {
+	readonly base: string;
+	readonly rules: ReturnType<typeof ignore>;
+}
+
+export interface IgnoreScope {
+	readonly boundary: string | undefined;
+	readonly matchers: readonly IgnoreMatcher[];
+}
+
+export const emptyScope: IgnoreScope = { boundary: undefined, matchers: [] };
+
+export const posix = (path: string): string => path.replaceAll("\\", "/");
+
+export const withIgnoreFile = (scope: IgnoreScope, base: string, contents: string): IgnoreScope => ({
+	boundary: scope.boundary,
+	matchers: [...scope.matchers, { base, rules: ignore().add(contents) }],
+});
+
+// Re-including a directory resets directory rules below that boundary; filename rules still apply.
+export const insideKept = (scope: IgnoreScope, directory: string): IgnoreScope => ({ boundary: directory, matchers: scope.matchers });
+
+const matcherVerdict = (matcher: IgnoreMatcher, boundary: string | undefined, path: string, directory: boolean): Verdict => {
+	const anchor = boundary !== undefined && boundary.length > matcher.base.length ? boundary : matcher.base;
+	const rel = posix(relative(anchor, path));
+	if (rel === "" || rel.startsWith("..")) {
+		return "unknown";
+	}
+	// Directory-only patterns match paths with a trailing slash.
+	const result = matcher.rules.test(directory ? `${rel}/` : rel);
+	if (result.ignored) {
+		return "ignored";
+	}
+	return result.unignored ? "kept" : "unknown";
+};
+
+// The deepest ignore file with an opinion wins.
+export const verdictFor = (scope: IgnoreScope, path: string, directory: boolean): Verdict =>
+	scope.matchers.map((matcher) => matcherVerdict(matcher, scope.boundary, path, directory)).findLast((verdict) => verdict !== "unknown") ?? "unknown";

package/src/inventory/walk.ts

@@ -0,0 +1,58 @@
+import { join, relative, sep } from "node:path";
+import { Effect, FileSystem } from "effect";
+import { type FilesystemFailure, orWhenAbsent, readOptionalText } from "./filesystem.ts";
+import { emptyScope, type IgnoreScope, insideKept, verdictFor, withIgnoreFile } from "./ignore-scope.ts";
+
+const SKIPPED = new Set([".git", "node_modules"]);
+
+export const ignoreScopeAt = (
+	dir: string,
+	inherited: IgnoreScope = emptyScope,
+): Effect.Effect<IgnoreScope, FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.map(readOptionalText(join(dir, ".gitignore")), (contents) =>
+		contents === undefined || contents === "" ? inherited : withIgnoreFile(inherited, dir, contents),
+	);
+
+/** The ignore files of every directory between the root and a walked directory, which the walk itself does not visit. */
+export const scopeAbove = (root: string, dir: string): Effect.Effect<IgnoreScope, FilesystemFailure, FileSystem.FileSystem> => {
+	const parts = relative(root, dir)
+		.split(sep)
+		.filter((part) => part !== "");
+	const ancestors = parts.length === 0 ? [] : [root, ...parts.slice(0, -1).map((_, index) => join(root, ...parts.slice(0, index + 1)))];
+	return Effect.reduce(
+		ancestors,
+		() => emptyScope,
+		(scope, ancestor) => ignoreScopeAt(ancestor, scope),
+	);
+};
+
+export const walk = (dir: string, inherited: IgnoreScope = emptyScope): Effect.Effect<readonly string[], FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const scope = yield* ignoreScopeAt(dir, inherited);
+		const entries = yield* orWhenAbsent<readonly string[]>(dir, fs.readDirectory(dir), []);
+		const nested = yield* Effect.forEach(
+			entries.filter((entry) => !SKIPPED.has(entry)),
+			(entry) => walkEntry(join(dir, entry), scope),
+			{ concurrency: 1 },
+		);
+		return nested.flat();
+	});
+
+const walkEntry = (path: string, scope: IgnoreScope): Effect.Effect<readonly string[], FilesystemFailure, FileSystem.FileSystem> =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const info = yield* orWhenAbsent<FileSystem.File.Info | undefined>(path, fs.stat(path), undefined);
+		if (info === undefined) {
+			return [];
+		}
+		const directory = info.type === "Directory";
+		const verdict = verdictFor(scope, path, directory);
+		if (verdict === "ignored") {
+			return [];
+		}
+		if (!directory) {
+			return [path];
+		}
+		return yield* walk(path, verdict === "kept" ? insideKept(scope, path) : scope);
+	});

package/src/report/plural.ts

@@ -0,0 +1 @@
+export const plural = (count: number, singular: string, many = `${singular}s`): string => `${count} ${count === 1 ? singular : many}`;