@shivaedev/quality 0.4.0 → 0.5.1

package/src/imports/fences/reach.ts

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

package/src/imports/fences/selectors.ts

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

package/src/imports/fences/vocabulary.ts

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

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