@shivaedev/quality 0.17.0 → 0.19.0

package/src/hooks/preCommit.ts

@@ -0,0 +1,68 @@
+import { join } from "node:path";
+import { Console, Effect, Schema } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { lint } from "#cli/lint.ts";
+import { loadConfig } from "#config/load.ts";
+import { decodeWith, validOrFail } from "#decoded.ts";
+import { GateFailed, SetupFailure } from "#failure.ts";
+import { readOptionalText } from "#inventory/filesystem.ts";
+
+const COMMIT_AGAIN =
+	"help: fix what the output above reports, then commit again; `quality hooks pre-commit` repeats these checks without committing.";
+
+const Manifest = Schema.toStandardSchemaV1(
+	Schema.fromJsonString(
+		Schema.Struct({
+			packageManager: Schema.optionalKey(Schema.String),
+			scripts: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+		}),
+	),
+);
+
+const commitScripts = Effect.fnUntraced(function* (root: string) {
+	const file = join(root, "package.json");
+	const text = yield* readOptionalText(file).pipe(Effect.mapError((error) => new SetupFailure({ message: error.message })));
+	if (text === undefined) {
+		return { manager: "npm", scripts: [] };
+	}
+	const manifest = yield* validOrFail(file, yield* Effect.promise(() => decodeWith(Manifest, text)));
+	const manager = manifest.packageManager?.split("@")[0] ?? "npm";
+	if (!["npm", "pnpm", "yarn", "bun"].includes(manager)) {
+		return yield* new SetupFailure({ message: `${file}: unsupported packageManager "${manager}". Use npm, pnpm, yarn or bun.` });
+	}
+	return { manager, scripts: ["typecheck", "quality:commit"].filter((script) => manifest.scripts?.[script] !== undefined) };
+});
+
+const runScript = Effect.fnUntraced(
+	function* (root: string, manager: string, script: string) {
+		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+		const child = yield* spawner.spawn(
+			ChildProcess.make(manager, ["run", script], { cwd: root, stderr: "inherit", stdin: "inherit", stdout: "inherit" }),
+		);
+		return Number(yield* child.exitCode);
+	},
+	Effect.scoped,
+	Effect.mapError((error) => new SetupFailure({ message: `cannot run a pre-commit script: ${error.message}` })),
+);
+
+export const preCommitHook = Effect.fn("Hooks.preCommitHook")(function* (cwd: string, path: string | undefined) {
+	const config = yield* loadConfig(cwd, path);
+	const { manager, scripts } = yield* commitScripts(config.root);
+	const linted = yield* lint(cwd, path, "summary").pipe(
+		Effect.as(true),
+		Effect.catchTag("GateFailed", () => Effect.succeed(false)),
+	);
+	const failed = linted ? [] : ["quality lint"];
+	for (const script of scripts) {
+		const command = `${manager} run ${script}`;
+		yield* Console.log(`quality: running \`${command}\``);
+		const code = yield* runScript(config.root, manager, script);
+		if (code !== 0) {
+			failed.push(`\`${command}\` (exit code ${code})`);
+		}
+	}
+	if (failed.length > 0) {
+		yield* Console.error(`quality: pre-commit failed: ${failed.join(", ")}.\n${COMMIT_AGAIN}`);
+		return yield* new GateFailed();
+	}
+});

package/src/hooks/shim.ts

@@ -0,0 +1,28 @@
+import { type HookCommand, shellWords } from "./command.ts";
+
+const OWNER = "# Installed by @shivaedev/quality: `quality hooks install` writes it, `quality hooks uninstall` removes it.";
+
+export function isHookShim(text: string): boolean {
+	return text.split("\n").includes(OWNER);
+}
+
+// The hook moves to the checked-out worktree first, so each worktree commits under its own config and its own quality.
+// Git sets GIT_DIR for a hook in a linked worktree, which makes git take the current folder as the worktree root unless GIT_WORK_TREE names it.
+export function hookShim(directory: string, command: HookCommand): string {
+	const folder = directory === "" ? "" : `/${shellWords([directory])}`;
+	const exec = [shellWords(command.runner), '"$quality"', shellWords(command.args)].filter((part) => part !== "");
+	return [
+		"#!/bin/sh",
+		OWNER,
+		'top="$(git rev-parse --show-toplevel)" || exit 2',
+		'if [ -n "$GIT_DIR" ] && [ -z "$GIT_WORK_TREE" ]; then export GIT_WORK_TREE="$top"; fi',
+		`cd "$top"${folder} || exit 2`,
+		`quality=${shellWords([command.launcher])}`,
+		'if [ ! -e "$quality" ]; then',
+		'\tprintf \'quality: cannot check this commit: %s/%s does not exist.\\nhelp: install the dependencies of this worktree, then commit again.\\n\' "$PWD" "$quality" >&2',
+		"\texit 2",
+		"fi",
+		`exec ${exec.join(" ")}`,
+		"",
+	].join("\n");
+}

package/src/hooks/uninstall.ts

@@ -0,0 +1,19 @@
+import { Console, Effect, FileSystem } from "effect";
+import { SetupFailure } from "#failure.ts";
+import { readOptionalText } from "#inventory/filesystem.ts";
+import { hookLocation } from "./location.ts";
+import { isHookShim } from "./shim.ts";
+
+export const uninstallHook = Effect.fn("Hooks.uninstallHook")(function* (cwd: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const { file } = yield* hookLocation(cwd);
+	const existing = yield* Effect.mapError(readOptionalText(file), (failure) => new SetupFailure({ message: failure.message }));
+	if (existing === undefined) {
+		return yield* Console.log(`quality: there is no pre-commit hook at ${file}.`);
+	}
+	if (!isHookShim(existing)) {
+		return yield* Console.error(`quality: kept ${file}: it is not quality's pre-commit hook.`);
+	}
+	yield* Effect.mapError(fs.remove(file), (error) => new SetupFailure({ message: `cannot remove ${file}: ${error.message}` }));
+	yield* Console.log(`quality: removed the pre-commit hook at ${file}.`);
+});

package/src/imports/browserGlobals.ts

@@ -0,0 +1,142 @@
+import ts from "typescript";
+import type { Finding, SourceFile } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+import { browserNames } from "./browserNames.ts";
+
+function checkerOf(source: ts.SourceFile): ts.TypeChecker {
+	const options: ts.CompilerOptions = { allowJs: true, noLib: true, noResolve: true };
+	const host = ts.createCompilerHost(options);
+	host.getSourceFile = (path) => (path === source.fileName ? source : undefined);
+	return ts.createProgram([source.fileName], options, host).getTypeChecker();
+}
+
+function unbound(checker: ts.TypeChecker, node: ts.Identifier): boolean {
+	return (checker.getSymbolAtLocation(node)?.declarations ?? []).length === 0;
+}
+
+function globalThisRoot(expression: ts.Expression, checker: ts.TypeChecker): boolean {
+	let root = expression;
+	while (
+		ts.isParenthesizedExpression(root)
+		|| ts.isAsExpression(root)
+		|| ts.isTypeAssertionExpression(root)
+		|| ts.isNonNullExpression(root)
+		|| ts.isSatisfiesExpression(root)
+	) {
+		root = root.expression;
+	}
+	return ts.isIdentifier(root) && root.text === "globalThis" && unbound(checker, root);
+}
+
+function qualifiedName(node: ts.PropertyAccessExpression | ts.ElementAccessExpression, checker: ts.TypeChecker): string | undefined {
+	const root = node.expression;
+	if (!globalThisRoot(root, checker)) {
+		return undefined;
+	}
+	if (ts.isPropertyAccessExpression(node)) {
+		return node.name.text;
+	}
+	return ts.isStringLiteral(node.argumentExpression) ? node.argumentExpression.text : undefined;
+}
+
+function bindingName(node: ts.Identifier): boolean {
+	const parent = node.parent;
+	return ts.isBindingElement(parent) && (parent.name === node || parent.propertyName === node);
+}
+
+function globalName(node: ts.Node, checker: ts.TypeChecker): string | undefined {
+	if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+		return qualifiedName(node, checker);
+	}
+	if (!ts.isIdentifier(node)) {
+		return undefined;
+	}
+	const parent = node.parent;
+	if (bindingName(node) || ts.isLabeledStatement(parent) || ts.isBreakStatement(parent) || ts.isContinueStatement(parent)) {
+		return undefined;
+	}
+	if ((ts.isPropertyAccessExpression(parent) && parent.name === node) || (ts.isPropertyAssignment(parent) && parent.name === node)) {
+		return undefined;
+	}
+	if (ts.isShorthandPropertyAssignment(parent)) {
+		return checker.getShorthandAssignmentValueSymbol(parent) === undefined ? node.text : undefined;
+	}
+	return unbound(checker, node) ? node.text : undefined;
+}
+
+function propertyName(node: ts.Node): readonly string[] {
+	if (ts.isComputedPropertyName(node) && ts.isStringLiteral(node.expression)) {
+		return [node.expression.text];
+	}
+	return ts.isIdentifier(node) || ts.isStringLiteral(node) ? [node.text] : [];
+}
+
+function destructuringOf(
+	node: ts.Node,
+): { readonly pattern: ts.ObjectBindingPattern | ts.ObjectLiteralExpression; readonly root: ts.Expression } | undefined {
+	if ((ts.isVariableDeclaration(node) || ts.isParameter(node)) && ts.isObjectBindingPattern(node.name) && node.initializer !== undefined) {
+		return { pattern: node.name, root: node.initializer };
+	}
+	if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isObjectLiteralExpression(node.left)) {
+		return { pattern: node.left, root: node.right };
+	}
+	return undefined;
+}
+
+function destructuredNames(node: ts.Node, checker: ts.TypeChecker): readonly string[] {
+	const destructuring = destructuringOf(node);
+	if (destructuring === undefined) {
+		return [];
+	}
+	const { pattern, root } = destructuring;
+	if (!globalThisRoot(root, checker)) {
+		return [];
+	}
+	if (ts.isObjectBindingPattern(pattern)) {
+		return pattern.elements.flatMap((element) => (element.dotDotDotToken === undefined ? propertyName(element.propertyName ?? element.name) : []));
+	}
+	return pattern.properties.flatMap((property) =>
+		ts.isShorthandPropertyAssignment(property) || ts.isPropertyAssignment(property) ? propertyName(property.name) : [],
+	);
+}
+
+function superclassesOf(node: ts.HeritageClause): readonly ts.Expression[] {
+	if (node.token !== ts.SyntaxKind.ExtendsKeyword || !(ts.isClassDeclaration(node.parent) || ts.isClassExpression(node.parent))) {
+		return [];
+	}
+	return node.types.map((base) => base.expression);
+}
+
+export function browserGlobals(file: SourceFile): readonly Finding[] {
+	const parsed = parse(file);
+	if (parsed === undefined) {
+		return [];
+	}
+	const source = parsed;
+	const checker = checkerOf(source);
+	const findings: Finding[] = [];
+	function visit(node: ts.Node): void {
+		if (ts.isHeritageClause(node)) {
+			for (const expression of superclassesOf(node)) {
+				visit(expression);
+			}
+			return;
+		}
+		if (ts.isTypeNode(node) || ts.isImportDeclaration(node) || ts.isExportSpecifier(node)) {
+			return;
+		}
+		const direct = globalName(node, checker);
+		const names = [...destructuredNames(node, checker), ...(direct === undefined ? [] : [direct])];
+		for (const name of names.filter((candidate) => browserNames.has(candidate))) {
+			findings.push({
+				file: file.path,
+				line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+				message: `Shared code uses browser global "${name}". Move browser-dependent code into src/client/ or pass the value into shared code.`,
+				subject: name,
+			});
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(source);
+	return findings;
+}

package/src/imports/browserNames.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import ts from "typescript";
+
+const portable = new Set([
+	"AbortController",
+	"AbortSignal",
+	"Blob",
+	"BroadcastChannel",
+	"ByteLengthQueuingStrategy",
+	"CompressionStream",
+	"CountQueuingStrategy",
+	"Crypto",
+	"CryptoKey",
+	"CustomEvent",
+	"DOMException",
+	"DecompressionStream",
+	"Event",
+	"EventTarget",
+	"File",
+	"FormData",
+	"Headers",
+	"MessageChannel",
+	"MessageEvent",
+	"MessagePort",
+	"Performance",
+	"PerformanceEntry",
+	"PerformanceMark",
+	"PerformanceMeasure",
+	"PerformanceObserver",
+	"PerformanceObserverEntryList",
+	"PerformanceResourceTiming",
+	"ReadableByteStreamController",
+	"ReadableStream",
+	"ReadableStreamBYOBReader",
+	"ReadableStreamBYOBRequest",
+	"ReadableStreamDefaultController",
+	"ReadableStreamDefaultReader",
+	"Request",
+	"Response",
+	"SubtleCrypto",
+	"TextDecoder",
+	"TextDecoderStream",
+	"TextEncoder",
+	"TextEncoderStream",
+	"TransformStream",
+	"TransformStreamDefaultController",
+	"URL",
+	"URLPattern",
+	"URLSearchParams",
+	"WebSocket",
+	"WritableStream",
+	"WritableStreamDefaultController",
+	"WritableStreamDefaultWriter",
+	"atob",
+	"btoa",
+	"clearInterval",
+	"clearTimeout",
+	"console",
+	"crypto",
+	"fetch",
+	"performance",
+	"queueMicrotask",
+	"setInterval",
+	"setTimeout",
+	"structuredClone",
+]);
+
+function namesInDom(): readonly string[] {
+	const path = join(dirname(ts.getDefaultLibFilePath({})), "lib.dom.d.ts");
+	const source = ts.createSourceFile(path, readFileSync(path, "utf8"), ts.ScriptTarget.Latest, true);
+	return source.statements.flatMap((statement) => {
+		if (ts.isVariableStatement(statement)) {
+			return statement.declarationList.declarations.flatMap(({ name }) => (ts.isIdentifier(name) ? [name.text] : []));
+		}
+		return ts.isFunctionDeclaration(statement) && statement.name !== undefined ? [statement.name.text] : [];
+	});
+}
+
+export const browserNames: ReadonlySet<string> = new Set(namesInDom().filter((name) => !portable.has(name)));

package/src/imports/fences/check.ts

@@ -0,0 +1,12 @@
+import { importGraph } from "#imports/graph.ts";
+import type { Findings, RuleInputs } from "#rule.ts";
+import { discoverFences } from "./discover.ts";
+import type { Fence } from "./model.ts";
+import { compilePolicy } from "./policy.ts";
+
+export async function checkFences(inputs: RuleInputs, configured: readonly Fence[]): Promise<Findings> {
+	const graph = await importGraph(inputs);
+	const fences = [...configured, ...(await discoverFences(inputs, graph.packages))];
+	const policy = compilePolicy(fences, { files: inputs.files, packages: graph.packages });
+	return policy.flatMap((compiled) => compiled.evaluate(graph));
+}

package/src/imports/fences/declarations.ts

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+import { decodeWith } from "#decoded.ts";
+import type { Fence, Selector } from "./model.ts";
+
+const SelectorInput: Schema.Codec<Selector> = Schema.suspend(() =>
+	Schema.Union([
+		Schema.Struct({ kind: Schema.Literal("anything") }),
+		Schema.Struct({ kind: Schema.Literal("workspace") }),
+		Schema.Struct({ kind: Schema.Literal("anyOf"), members: Schema.Array(SelectorInput) }),
+		Schema.Struct({ base: SelectorInput, excluded: Schema.Array(SelectorInput), kind: Schema.Literal("except") }),
+		Schema.Struct({ kind: Schema.Literals(["files", "folders"]), paths: Schema.Array(Schema.String) }),
+		Schema.Struct({ kind: Schema.Literals(["modules", "packages", "scopes"]), names: Schema.Array(Schema.String) }),
+	]),
+);
+
+const ExampleStep = Schema.Union([Schema.String, Schema.Struct({ external: Schema.String })]);
+
+const Chain = Schema.TupleWithRest(Schema.Tuple([Schema.String, ExampleStep]), [ExampleStep]);
+
+const FenceInput: Schema.Codec<Fence> = Schema.Struct({
+	_tag: Schema.Literal("Fence"),
+	examples: Schema.Struct({ illegal: Chain, legal: Chain }),
+	from: SelectorInput,
+	name: Schema.String,
+	prohibition: Schema.Union([
+		Schema.Struct({ kind: Schema.Literals(["import", "reach"]), to: SelectorInput }),
+		Schema.Struct({ kind: Schema.Literal("vocabulary"), subjects: Schema.Array(Schema.String), unit: SelectorInput }),
+	]),
+	rationale: Schema.String,
+});
+
+export const Declarations = Schema.Array(FenceInput);
+
+const standard = Schema.toStandardSchemaV1(Declarations, { parseOptions: { errors: "all", onExcessProperty: "error" } });
+
+export function decodeDeclarations(value: unknown) {
+	return decodeWith(standard, value);
+}

package/src/imports/fences/discover.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { posix, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { WorkspacePackage } from "#imports/workspace.ts";
+import type { RuleInputs } from "#rule.ts";
+import { decodeDeclarations } from "./declarations.ts";
+import type { Fence } from "./model.ts";
+
+const BOUNDARY_FILE = "quality.fences.config.ts";
+
+async function loadBoundary(inputs: RuleInputs, directory: string): Promise<readonly Fence[]> {
+	const file = posix.join(directory, BOUNDARY_FILE);
+	try {
+		const text = await inputs.readText(file);
+		if (text === undefined) {
+			return [];
+		}
+		const url = pathToFileURL(resolve(inputs.root, file));
+		url.searchParams.set("content", createHash("sha256").update(text).digest("hex"));
+		const loaded: unknown = await import(url.href);
+		if (typeof loaded !== "object" || loaded === null || !("default" in loaded)) {
+			throw new Error("export an array of fence() declarations as the default export");
+		}
+		const decoded = await decodeDeclarations(loaded.default);
+		if (decoded._tag === "Invalid") {
+			throw new Error(`export an array of fence() declarations:\n${decoded.issues.join("\n")}`);
+		}
+		return decoded.value;
+	} catch (cause) {
+		throw new Error(`cannot load boundary at ${file}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+}
+
+export async function discoverFences(inputs: RuleInputs, packages: readonly WorkspacePackage[]): Promise<readonly Fence[]> {
+	const boundaries = await Promise.all([".", ...packages.map((owner) => owner.directory)].map((directory) => loadBoundary(inputs, directory)));
+	return boundaries.flat();
+}

package/src/imports/graph.ts

@@ -29,7 +29,7 @@ export interface ImportGraph {
 const QUERY = /\?.*$/u;
 
 const NO_MODULES =
-	"the import graph covers no modules: the sources hold no TypeScript or JavaScript module. Point `sources` at the code, or turn the imports rules off.";
+	"the import graph covers no modules: the sources hold no TypeScript or JavaScript module. Point `sources` at the TypeScript or JavaScript code.";
 
 function relativeTarget(from: string, request: ImportRequest): string | undefined {
 	const relative = request.kind === "path-reference" || request.specifier.startsWith("./") || request.specifier.startsWith("../");
@@ -77,7 +77,7 @@ async function build(inputs: RuleInputs): Promise<ImportGraph> {
 
 const graphs = new WeakMap<readonly SourceFile[], Promise<ImportGraph>>();
 
-// The three imports rules run on one scan, so they share the graph built from its sources.
+// Import rules run on one scan, so they share the graph built from its sources.
 export function importGraph(inputs: RuleInputs): Promise<ImportGraph> {
 	const known = graphs.get(inputs.sources) ?? build(inputs);
 	graphs.set(inputs.sources, known);

package/src/imports/projects.ts

@@ -73,8 +73,8 @@ function nearestConfig(root: string, file: string): string | undefined {
 	return undefined;
 }
 
-function memo<Value>(compute: (key: string) => Value): (key: string) => Value {
-	const known = new Map<string, Value>();
+function memo<TValue>(compute: (key: string) => TValue): (key: string) => TValue {
+	const known = new Map<string, TValue>();
 	return (key) => {
 		const value = known.get(key) ?? compute(key);
 		known.set(key, value);

package/src/imports/runtime.ts

@@ -0,0 +1,37 @@
+import { statSync } from "node:fs";
+import { join, posix } from "node:path";
+import type { RuleInputs } from "#rule.ts";
+import { packageOf, type WorkspacePackage } from "./workspace.ts";
+
+export type Runtime = "client" | "server" | "shared";
+
+function directoryExists(path: string): boolean {
+	try {
+		return statSync(path).isDirectory();
+	} catch (cause) {
+		if (cause instanceof Error && "code" in cause && (cause.code === "ENOENT" || cause.code === "ENOTDIR")) {
+			return false;
+		}
+		throw cause;
+	}
+}
+
+export function runtimeOf(inputs: RuleInputs, packages: readonly WorkspacePackage[]): (path: string) => Runtime | undefined {
+	const owners = [...packages, { directory: ".", name: "." }];
+	const adopted = new Set(
+		owners
+			.filter((owner) => ["client", "server"].some((folder) => directoryExists(join(inputs.root, owner.directory, "src", folder))))
+			.map((owner) => owner.directory),
+	);
+	return (path) => {
+		const owner = packageOf(packages, path)?.directory ?? ".";
+		if (!adopted.has(owner)) {
+			return undefined;
+		}
+		const local = posix.relative(owner, path);
+		if (local.startsWith("src/client/")) {
+			return "client";
+		}
+		return local.startsWith("src/server/") ? "server" : "shared";
+	};
+}

package/src/imports/workspace.ts

@@ -1,4 +1,7 @@
 import { posix } from "node:path";
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
+import { Effect } from "effect";
+import { manifestsIn } from "#manifests/sorted.ts";
 import type { RuleInputs } from "#rule.ts";
 import { globMatcher } from "./glob.ts";
 import { pnpmWorkspacePatterns } from "./pnpm-workspace.ts";
@@ -8,7 +11,7 @@ export interface WorkspacePackage {
 	readonly name: string;
 }
 
-type Reader = Pick<RuleInputs, "files" | "readText">;
+type Reader = Pick<RuleInputs, "files" | "readText"> & Partial<Pick<RuleInputs, "root">>;
 
 const MANIFEST = "package.json";
 
@@ -60,7 +63,9 @@ async function memberOf(inputs: Reader): Promise<(directory: string) => boolean>
 
 export async function workspacePackages(inputs: Reader): Promise<readonly WorkspacePackage[]> {
 	const member = await memberOf(inputs);
-	const directories = inputs.files
+	const manifests =
+		inputs.root === undefined ? inputs.files : await Effect.runPromise(manifestsIn(inputs.root).pipe(Effect.provide(NodeFileSystem.layer)));
+	const directories = manifests
 		.filter((file) => posix.basename(file) === MANIFEST && file !== MANIFEST)
 		.map((manifest) => posix.dirname(manifest))
 		.filter(member);

package/src/inventory/collect.ts

@@ -46,7 +46,14 @@ export const collectInventory = (root: string, scope: InventoryScope): Effect.Ef
 		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 files = [...new Set(relativePaths)]
+			.filter((path) => !excluded.ignores(path))
+			.sort((left, right) => {
+				if (left === right) {
+					return 0;
+				}
+				return left < right ? -1 : 1;
+			});
 		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/trackedPaths.ts

@@ -0,0 +1,28 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+async function listedPaths(directory: string, options: readonly string[]): Promise<readonly string[]> {
+	try {
+		const { stdout } = await run("git", ["ls-files", "-z", ...options, "--", "."], { cwd: directory, maxBuffer: 2 ** 30 });
+		return stdout
+			.split("\0")
+			.filter(Boolean)
+			.map((path) => join(directory, path));
+	} catch (error) {
+		if (error instanceof Error && "stderr" in error && String(error.stderr).includes("not a git repository")) {
+			return [];
+		}
+		throw error;
+	}
+}
+
+export function trackedPaths(directory: string): Promise<readonly string[]> {
+	return listedPaths(directory, []);
+}
+
+export function ignoredTrackedPaths(directory: string): Promise<readonly string[]> {
+	return listedPaths(directory, ["--cached", "--ignored", "--exclude-standard"]);
+}