@shivaedev/quality 0.3.1 → 0.5.0

package/src/imports/generated.ts

@@ -0,0 +1,95 @@
+import { execFile } from "node:child_process";
+import { posix } from "node:path";
+import { promisify } from "node:util";
+import { emptyScope, type IgnoreScope, verdictFor, withIgnoreFile } from "../inventory/ignore-scope.ts";
+import type { RuleInputs } from "../rule.ts";
+import type { ImportGraph, UnresolvedImport } from "./graph.ts";
+
+type Reader = Pick<RuleInputs, "readText" | "root">;
+
+const IGNORE_FILE = ".gitignore";
+
+const LEADING_DOT = /^\.\//u;
+
+const TRAILING_SLASHES = /\/+$/u;
+
+const NODE_MODULES = "node_modules";
+
+const NOT_A_REPOSITORY = "not a git repository";
+
+const PLACEHOLDERS = new Set([".gitkeep", ".keep"]);
+
+const run = promisify(execFile);
+
+async function withIgnoreFileIn(reader: Reader, scope: IgnoreScope, directory: string): Promise<IgnoreScope> {
+	const contents = await reader.readText(posix.join(directory, IGNORE_FILE));
+	return contents === undefined || contents === "" ? scope : withIgnoreFile(scope, posix.join(reader.root, directory), contents);
+}
+
+async function ignored(reader: Reader, file: string): Promise<boolean> {
+	const parts = file.split("/");
+	let scope = emptyScope;
+	for (const index of parts.keys()) {
+		scope = await withIgnoreFileIn(reader, scope, parts.slice(0, index).join("/") || ".");
+		if (verdictFor(scope, posix.join(reader.root, ...parts.slice(0, index + 1)), index < parts.length - 1) === "ignored") {
+			return true;
+		}
+	}
+	return false;
+}
+
+async function tracked(root: string, folder: string): Promise<readonly string[]> {
+	try {
+		const { stdout } = await run("git", ["ls-files", "-z", "--", folder], { cwd: root });
+		return stdout.split("\0").filter(Boolean);
+	} catch (error) {
+		if (error instanceof Error && "stderr" in error && String(error.stderr).includes(NOT_A_REPOSITORY)) {
+			return [];
+		}
+		throw error;
+	}
+}
+
+function under(folder: string, path: string | undefined): boolean {
+	return path?.startsWith(`${folder}/`) === true;
+}
+
+async function contentIssue(reader: Reader, folder: string, named: readonly string[]): Promise<string | undefined> {
+	const verdicts = await Promise.all(named.map((file) => ignored(reader, file)));
+	if (verdicts.includes(false)) {
+		return `"${folder}" is not ignored by git, so it holds source, not generated output`;
+	}
+	const kept = (await tracked(reader.root, folder)).find((file) => !PLACEHOLDERS.has(posix.basename(file)));
+	return kept === undefined ? undefined : `"${folder}" holds files git tracks, such as ${kept}, so it is not generated output`;
+}
+
+function placeIssue(graph: ImportGraph, folder: string): string | undefined {
+	if (folder === "" || folder.startsWith("../") || posix.isAbsolute(folder)) {
+		return `"${folder}" is no folder inside the repository`;
+	}
+	if (folder.split("/").includes(NODE_MODULES)) {
+		return `"${folder}" lies in node_modules, which holds installed packages, not generated output`;
+	}
+	return graph.edges.some((edge) => edge.to.kind === "file" && under(folder, edge.to.path))
+		? undefined
+		: `"${folder}" holds no file that an import names`;
+}
+
+async function issueOf(reader: Reader, graph: ImportGraph, folder: string): Promise<string | undefined> {
+	const misplaced = placeIssue(graph, folder);
+	if (misplaced !== undefined) {
+		return misplaced;
+	}
+	const named = [...new Set(graph.edges.flatMap((edge) => (edge.to.kind === "file" && under(folder, edge.to.path) ? [edge.to.path] : [])))];
+	return await contentIssue(reader, folder, named);
+}
+
+// A generated folder may be empty until its generator runs, so a relative import of a missing file in it resolves.
+export async function withoutGenerated(reader: Reader, graph: ImportGraph, declared: readonly string[]): Promise<readonly UnresolvedImport[]> {
+	const folders = declared.map((folder) => posix.normalize(folder).replace(LEADING_DOT, "").replace(TRAILING_SLASHES, ""));
+	const issues = (await Promise.all(folders.map((folder) => issueOf(reader, graph, folder)))).flatMap((issue) => issue ?? []);
+	if (issues.length > 0) {
+		throw new Error(`the generated folders are invalid:\n${issues.map((issue) => `  - ${issue}`).join("\n")}`);
+	}
+	return graph.unresolved.filter((request) => !folders.some((folder) => under(folder, request.missing)));
+}

package/src/imports/glob.ts

@@ -0,0 +1,142 @@
+type Segment = RegExp | typeof GLOBSTAR;
+
+const STAR = "*";
+
+const GLOBSTAR = "**";
+
+const DOT = ".";
+
+const NO_DOT = "(?!\\.)";
+
+const EXTGLOB = /[?*+@!]\(/u;
+
+const BRACE_RANGE = /^[^,]*\.\.[^,]*$/u;
+
+const REGEX_SYNTAX = /[\\^$.*+?()[\]{}|/]/u;
+
+const CLASS_SYNTAX = /[\\\]^]/gu;
+
+const BRACE_DEPTH = new Map([
+	["{", 1],
+	["}", -1],
+]);
+
+function depthChange(char: string | undefined): number {
+	return BRACE_DEPTH.get(char ?? "") ?? 0;
+}
+
+function charSource(char: string): string {
+	if (char === STAR) {
+		return "[^/]*";
+	}
+	if (char === "?") {
+		return "[^/]";
+	}
+	return REGEX_SYNTAX.test(char) ? `\\${char}` : char;
+}
+
+function unreadable(pattern: string, problem: string): Error {
+	return new Error(`cannot read the workspace pattern "${pattern}": ${problem}`);
+}
+
+function closingBrace(text: string, open: number): number {
+	let depth = 0;
+	for (let index = open; index < text.length; index += 1) {
+		depth += depthChange(text[index]);
+		if (depth === 0) {
+			return index;
+		}
+	}
+	return -1;
+}
+
+function choices(body: string): readonly string[] {
+	const parts = [""];
+	let depth = 0;
+	for (const char of body) {
+		depth += depthChange(char);
+		if (char === "," && depth === 0) {
+			parts.push("");
+		} else {
+			parts[parts.length - 1] += char;
+		}
+	}
+	return parts;
+}
+
+function expanded(pattern: string, whole: string): readonly string[] {
+	const open = pattern.indexOf("{");
+	if (open === -1) {
+		return [pattern];
+	}
+	const close = closingBrace(pattern, open);
+	if (close === -1) {
+		throw unreadable(whole, "a { never closes");
+	}
+	const body = pattern.slice(open + 1, close);
+	if (BRACE_RANGE.test(body)) {
+		throw unreadable(whole, "brace ranges are not supported");
+	}
+	const options = choices(body);
+	if (options.length < 2) {
+		throw unreadable(whole, "a { } needs two or more choices");
+	}
+	return options.flatMap((option) => expanded(`${pattern.slice(0, open)}${option}${pattern.slice(close + 1)}`, whole));
+}
+
+function characterClass(segment: string, start: number, whole: string): { readonly end: number; readonly source: string } {
+	const negated = segment[start + 1] === "!" || segment[start + 1] === "^";
+	const first = start + (negated ? 2 : 1);
+	const end = segment.indexOf("]", segment[first] === "]" ? first + 1 : first);
+	if (end === -1) {
+		throw unreadable(whole, "a [ never closes");
+	}
+	const body = segment.slice(first, end);
+	if (body.includes("[:")) {
+		throw unreadable(whole, "character class names are not supported");
+	}
+	return { end, source: `[${negated ? "^" : ""}${body.replace(CLASS_SYNTAX, "\\$&")}]` };
+}
+
+function segmentOf(segment: string, whole: string): Segment {
+	if (segment === GLOBSTAR) {
+		return GLOBSTAR;
+	}
+	if (EXTGLOB.test(segment)) {
+		throw unreadable(whole, "extended globs are not supported");
+	}
+	let source = "";
+	for (let index = 0; index < segment.length; index += 1) {
+		const char = segment[index] ?? "";
+		if (char === "[") {
+			const found = characterClass(segment, index, whole);
+			source += found.source;
+			index = found.end;
+		} else {
+			source += charSource(char);
+		}
+	}
+	return new RegExp(`^${segment.startsWith(DOT) ? "" : NO_DOT}${source}$`, "u");
+}
+
+function segmentsMatch(pattern: readonly Segment[], path: readonly string[]): boolean {
+	const [first, ...rest] = pattern;
+	if (first === undefined) {
+		return path.length === 0;
+	}
+	if (first === GLOBSTAR) {
+		const hidden = path.findIndex((segment) => segment.startsWith(DOT));
+		const reachable = hidden === -1 ? path.length : hidden;
+		return [...path.keys(), path.length].some((skipped) => skipped <= reachable && segmentsMatch(rest, path.slice(skipped)));
+	}
+	const [head, ...tail] = path;
+	return head !== undefined && first.test(head) && segmentsMatch(rest, tail);
+}
+
+export function globMatcher(pattern: string): (path: string) => boolean {
+	if (pattern.includes("\\")) {
+		throw unreadable(pattern, "escapes are not supported");
+	}
+	const alternatives = expanded(pattern, pattern).map((alternative) => alternative.split("/").map((segment) => segmentOf(segment, pattern)));
+	return (path) => alternatives.some((segments) => segmentsMatch(segments, path.split("/")));
+}

package/src/imports/graph.ts

@@ -0,0 +1,81 @@
+import { realpathSync } from "node:fs";
+import { join, posix } from "node:path";
+import type { RuleInputs, SourceFile } from "../rule.ts";
+import { parse } from "../rules/syntax.ts";
+import { ambientModules } from "./ambient.ts";
+import { type ImportKind, type ImportRequest, importsOf } from "./extract.ts";
+import { projectsFor } from "./projects.ts";
+import { type Endpoint, isDeclarationFile, resolveImport } from "./resolve.ts";
+import { type WorkspacePackage, workspacePackages } from "./workspace.ts";
+
+export interface ImportEdge {
+	readonly from: string;
+	readonly kind: ImportKind;
+	readonly line: number;
+	readonly specifier: string;
+	readonly to: Endpoint;
+	readonly type: boolean;
+}
+
+export type UnresolvedImport = Omit<ImportEdge, "to"> & { readonly missing: string | undefined };
+
+export interface ImportGraph {
+	readonly edges: readonly ImportEdge[];
+	readonly modules: readonly string[];
+	readonly packages: readonly WorkspacePackage[];
+	readonly unresolved: readonly UnresolvedImport[];
+}
+
+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.";
+
+// A relative import of a missing file still names a path, so fences see it before its generator writes it.
+function missingTarget(from: string, request: ImportRequest): string | undefined {
+	const relative = request.kind === "path-reference" || request.specifier.startsWith("./") || request.specifier.startsWith("../");
+	const target = posix.join(posix.dirname(from), request.specifier.replace(QUERY, ""));
+	return relative && !target.startsWith("../") ? target : undefined;
+}
+
+function walk(inputs: RuleInputs, root: string): Pick<ImportGraph, "edges" | "modules" | "unresolved"> {
+	const projectOf = projectsFor(root);
+	const parsed = inputs.sources.flatMap((file) => {
+		const syntax = parse(file);
+		return syntax === undefined ? [] : [{ file, path: join(root, file.path), syntax }];
+	});
+	const ambient = ambientModules(parsed);
+	const edges: ImportEdge[] = [];
+	const unresolved: UnresolvedImport[] = [];
+	for (const { file, path, syntax } of parsed) {
+		const project = projectOf(path);
+		for (const request of importsOf(syntax, isDeclarationFile(file.path))) {
+			const to = resolveImport(root, ambient, request, path, project);
+			if (to === undefined) {
+				const missing = missingTarget(file.path, request);
+				unresolved.push({ ...request, from: file.path, missing });
+				edges.push(...(missing === undefined ? [] : [{ ...request, from: file.path, to: { kind: "file" as const, path: missing } }]));
+			} else {
+				edges.push({ ...request, from: file.path, to });
+			}
+		}
+	}
+	return { edges, modules: parsed.map(({ file }) => file.path), unresolved };
+}
+
+async function build(inputs: RuleInputs): Promise<ImportGraph> {
+	const walked = walk(inputs, realpathSync(inputs.root));
+	if (walked.modules.length === 0) {
+		throw new Error(NO_MODULES);
+	}
+	return { ...walked, packages: await workspacePackages(inputs) };
+}
+
+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.
+export function importGraph(inputs: RuleInputs): Promise<ImportGraph> {
+	const known = graphs.get(inputs.sources) ?? build(inputs);
+	graphs.set(inputs.sources, known);
+	return known;
+}

package/src/imports/paths.ts

@@ -0,0 +1,28 @@
+function trail(previous: ReadonlyMap<string, string | undefined>, node: string): readonly string[] {
+	const path: string[] = [];
+	for (let step: string | undefined = node; step !== undefined; step = previous.get(step)) {
+		path.unshift(step);
+	}
+	return path;
+}
+
+export function shortestPath(
+	start: string,
+	neighbours: (node: string) => readonly string[],
+	goal: (node: string) => boolean,
+): readonly string[] | undefined {
+	const previous = new Map<string, string | undefined>([[start, undefined]]);
+	const queue = [start];
+	for (const node of queue) {
+		for (const next of neighbours(node)) {
+			if (goal(next)) {
+				return [...trail(previous, node), next];
+			}
+			if (!previous.has(next)) {
+				previous.set(next, node);
+				queue.push(next);
+			}
+		}
+	}
+	return undefined;
+}

package/src/imports/pnpm-workspace.ts

@@ -0,0 +1,134 @@
+const KEY = /^(?:packages|"packages"|'packages')\s*:/u;
+
+const ITEM = "-";
+
+const SPACE = /\s/u;
+
+const LINE_BREAK = /\r?\n/u;
+
+function failure(problem: string, cause?: unknown): Error {
+	return new Error(`pnpm-workspace.yaml: ${problem}`, { cause });
+}
+
+function withoutComment(line: string): string {
+	let quote: string | undefined;
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index];
+		if (quote !== undefined) {
+			quote = char === quote ? undefined : quote;
+		} else if (char === '"' || char === "'") {
+			quote = char;
+		} else if (char === "#" && (index === 0 || SPACE.test(line[index - 1] ?? ""))) {
+			return line.slice(0, index).trimEnd();
+		}
+	}
+	return line.trimEnd();
+}
+
+function scalar(raw: string): string {
+	const value = raw.trim();
+	if (value.startsWith('"') && value.endsWith('"') && value.length > 1) {
+		try {
+			return String(JSON.parse(value));
+		} catch (error) {
+			throw failure(`cannot read "${value}" in packages`, error);
+		}
+	}
+	if (value.startsWith("'") && value.endsWith("'") && value.length > 1) {
+		return value.slice(1, -1).replaceAll("''", "'");
+	}
+	if (value === "" || value.includes(": ") || value.endsWith(":") || ["[", "{", "'", '"'].some((opening) => value.startsWith(opening))) {
+		throw failure(`cannot read "${value}" in packages`);
+	}
+	return value;
+}
+
+const FLOW_INDICATOR = /[{}[\]]/u;
+
+interface FlowScan {
+	current: string;
+	readonly entries: string[];
+	quote: string | undefined;
+}
+
+function flowScalar(raw: string): string {
+	const value = raw.trim();
+	const quoted = value.startsWith('"') || value.startsWith("'");
+	if (!quoted && FLOW_INDICATOR.test(value)) {
+		throw failure(`cannot read "${value}" in packages; quote a pattern that holds { } [ ] or ,`);
+	}
+	return scalar(value);
+}
+
+function closed(scan: FlowScan, rest: string): readonly string[] {
+	if (rest.trim() !== "") {
+		throw failure(`cannot read "${rest.trim()}" after the packages list`);
+	}
+	return [...scan.entries, scan.current].filter((entry) => entry.trim() !== "").map(flowScalar);
+}
+
+function scanned(scan: FlowScan, char: string): "close" | undefined {
+	if (scan.quote !== undefined) {
+		scan.quote = char === scan.quote ? undefined : scan.quote;
+	} else if (char === "]") {
+		return "close";
+	} else if (char === ",") {
+		scan.entries.push(scan.current);
+		scan.current = "";
+		return undefined;
+	} else if (char === '"' || char === "'") {
+		scan.quote = char;
+	}
+	scan.current += char;
+	return undefined;
+}
+
+function flowList(lines: readonly string[]): readonly string[] {
+	const scan: FlowScan = { current: "", entries: [], quote: undefined };
+	for (const [number, line] of lines.map(withoutComment).entries()) {
+		for (let index = number === 0 ? 1 : 0; index < line.length; index += 1) {
+			if (scanned(scan, line[index] ?? "") === "close") {
+				return closed(scan, line.slice(index + 1));
+			}
+		}
+		scan.current += " ";
+	}
+	throw failure("the packages list never closes");
+}
+
+function blockList(lines: readonly string[]): readonly string[] {
+	const patterns: string[] = [];
+	for (const line of lines.map(withoutComment)) {
+		const trimmed = line.trim();
+		if (trimmed === "") {
+			continue;
+		}
+		const item = trimmed === ITEM || trimmed.startsWith(`${ITEM} `);
+		if (!(item || line.startsWith(" ") || line.startsWith("\t"))) {
+			break;
+		}
+		if (!item) {
+			throw failure(`cannot read "${trimmed}" in packages`);
+		}
+		patterns.push(scalar(trimmed.slice(ITEM.length)));
+	}
+	return patterns;
+}
+
+export function pnpmWorkspacePatterns(text: string): readonly string[] {
+	const lines = text.split(LINE_BREAK);
+	const start = lines.findIndex((line) => KEY.test(line));
+	if (start === -1) {
+		return [];
+	}
+	const rest = withoutComment(lines[start] ?? "")
+		.replace(KEY, "")
+		.trim();
+	if (rest.startsWith("[")) {
+		return flowList([rest, ...lines.slice(start + 1)]);
+	}
+	if (rest !== "") {
+		throw failure(`cannot read "${rest}" in packages`);
+	}
+	return blockList(lines.slice(start + 1));
+}

package/src/imports/projects.ts

@@ -0,0 +1,106 @@
+import { dirname, join, relative } from "node:path";
+import ts from "typescript";
+
+export interface Project {
+	readonly cache: ts.ModuleResolutionCache;
+	readonly files: ReadonlySet<string>;
+	readonly options: ts.CompilerOptions;
+	readonly typesCache: ts.ModuleResolutionCache;
+	readonly typesOptions: ts.CompilerOptions;
+}
+
+interface ParsedProject {
+	readonly files: ReadonlySet<string>;
+	readonly key: string;
+	readonly options: ts.CompilerOptions;
+	readonly references: readonly string[];
+}
+
+const CONFIG = "tsconfig.json";
+
+const SOURCE_CONDITION = "source";
+
+const quietHost: ts.ParseConfigFileHost = { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => undefined };
+
+function resolutionOptions(options: ts.CompilerOptions, declarations: boolean): ts.CompilerOptions {
+	return {
+		...options,
+		allowArbitraryExtensions: declarations,
+		allowImportingTsExtensions: true,
+		allowJs: true,
+		customConditions: [...new Set([SOURCE_CONDITION, ...(options.customConditions ?? [])])],
+		module: ts.ModuleKind.ESNext,
+		moduleResolution: ts.ModuleResolutionKind.Bundler,
+		noDtsResolution: !declarations,
+		resolveJsonModule: true,
+		resolvePackageJsonExports: true,
+		resolvePackageJsonImports: true,
+	};
+}
+
+function projectOf(root: string, parsed: ParsedProject | undefined): Project {
+	const runtime = resolutionOptions(parsed?.options ?? {}, false);
+	const types = resolutionOptions(parsed?.options ?? {}, true);
+	return {
+		cache: ts.createModuleResolutionCache(root, (file) => file, runtime),
+		files: parsed?.files ?? new Set(),
+		options: runtime,
+		typesCache: ts.createModuleResolutionCache(root, (file) => file, types),
+		typesOptions: types,
+	};
+}
+
+function parse(path: string): ParsedProject {
+	const parsed = ts.getParsedCommandLineOfConfigFile(path, {}, quietHost);
+	return {
+		files: new Set(parsed?.fileNames ?? []),
+		key: path,
+		options: parsed?.options ?? {},
+		references: (parsed?.projectReferences ?? []).map((reference) => ts.resolveProjectReferencePath(reference)),
+	};
+}
+
+function nearestConfig(root: string, file: string): string | undefined {
+	for (let directory = dirname(file); !relative(root, directory).startsWith(".."); directory = dirname(directory)) {
+		const candidate = join(directory, CONFIG);
+		if (ts.sys.fileExists(candidate)) {
+			return candidate;
+		}
+		if (directory === root) {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+function memo<Value>(compute: (key: string) => Value): (key: string) => Value {
+	const known = new Map<string, Value>();
+	return (key) => {
+		const value = known.get(key) ?? compute(key);
+		known.set(key, value);
+		return value;
+	};
+}
+
+// A file resolves with the options of the project that includes it: the nearest tsconfig.json, or a project it references.
+export function projectsFor(root: string): (file: string) => Project {
+	const parsedAt = memo(parse);
+	function withReferences(path: string, seen: Set<string>): readonly ParsedProject[] {
+		if (seen.has(path)) {
+			return [];
+		}
+		seen.add(path);
+		const project = parsedAt(path);
+		return [project, ...project.references.flatMap((reference) => withReferences(reference, seen))];
+	}
+	const familyAt = memo((config) => withReferences(config, new Set()));
+	const projects = new Map<string, Project>();
+	return (file) => {
+		const config = nearestConfig(root, file);
+		const owner = config === undefined ? undefined : (familyAt(config).find((candidate) => candidate.files.has(file)) ?? parsedAt(config));
+		const key = owner?.key ?? "";
+		const project = projects.get(key) ?? projectOf(root, owner);
+		projects.set(key, project);
+		return project;
+	};
+}