ox-dep-lint 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.1
+
+- 0.1.0 was published without its built `dist` files, so neither the CLI nor the plugin could load. A `prepack` script now builds before every pack and publish, so a package cannot go out without them. Use 0.1.1.
+- The `bin` path is written as npm stores it (`dist/cli.mjs`), so publishing no longer warns that it was corrected.
+- First release published from GitHub Actions through npm trusted publishing, with provenance.
+
+## 0.1.0
+
+- First release: the oxlint plugin `dep-lint/imports` and the `ox-dep-lint` CLI, sharing one engine. See the README for the rules, the configuration and what is not covered yet.

package/dist/check-GClvJhK3.mjs

@@ -0,0 +1,168 @@
+import { a as findingsForFile, c as withoutBaselined, n as createEngine, r as edgeRefusal, s as reads, t as baselineCovers, u as directoriesMatching } from "./engine-7N-4EtzS.mjs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import nodePath from "node:path";
+// src/graph.ts
+/**
+* Checks that need the whole workspace rather than one file: edges declared only in `package.json`, cycles between
+* packages, packages no kind holds, and baseline entries no finding needs any more. Only the CLI runs these, because an
+* oxlint plugin sees one file at a time and never sees `package.json`.
+*/
+const runtimeFields = [
+	"dependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+const graphFindings = (engine) => {
+	const { config, workspace } = engine;
+	const findings = [];
+	const at = {
+		line: 1,
+		column: 0
+	};
+	for (const problem of workspace.problems) findings.push({
+		rule: "invalid-package",
+		file: `${problem.directory}/package.json`,
+		...at,
+		message: problem.message,
+		target: problem.directory
+	});
+	const members = /* @__PURE__ */ new Set([...workspace.packages.map((entry) => entry.directory), ...workspace.problems.map((problem) => problem.directory)]);
+	for (const kind of Object.values(config.kinds)) for (const pattern of kind.packages) for (const directory of directoriesMatching(workspace.root, pattern)) if (!members.has(directory) && existsSync(nodePath.join(workspace.root, directory, "package.json"))) {
+		members.add(directory);
+		findings.push({
+			rule: "package-outside-workspace",
+			file: `${directory}/package.json`,
+			...at,
+			message: `${directory} is a package a kind names, but the root package.json's workspaces leave it out, so nothing in it is checked`,
+			target: directory
+		});
+	}
+	for (const entry of workspace.packages) {
+		const manifest = `${entry.directory}/package.json`;
+		if (engine.kindOf(entry) === void 0) {
+			findings.push({
+				rule: "package-without-kind",
+				file: manifest,
+				...at,
+				message: `${entry.name} matches no kind: add its directory to one`,
+				target: entry.name
+			});
+			continue;
+		}
+		const kindRule = config.kinds[engine.kindOf(entry) ?? ""];
+		const extra = config.packages[entry.name]?.externals ?? [];
+		for (const field of config.imports.shippedFields) for (const name of entry.manifest[field]) {
+			const outside = !workspace.byName.has(name) && !config.workspaceScopes.some((scope) => name.startsWith(scope));
+			const installed = entry.aliases.get(name) ?? name;
+			if (outside && kindRule !== void 0 && kindRule.externals !== "any" && !kindRule.externals.includes(installed) && !extra.includes(installed)) findings.push({
+				rule: "forbidden-external",
+				file: manifest,
+				...at,
+				message: `${field} names ${installed === name ? name : `${name} (${installed})`}, which its kind does not allow`,
+				target: installed
+			});
+		}
+		for (const field of config.imports.manifestEdgeFields) for (const name of entry.manifest[field]) {
+			const to = workspace.byName.get(name);
+			if (to === void 0) {
+				if (config.workspaceScopes.some((scope) => name.startsWith(scope))) findings.push({
+					rule: "unknown-workspace-package",
+					file: manifest,
+					...at,
+					message: `${field} names ${name}, which is not a workspace package`,
+					target: name
+				});
+				continue;
+			}
+			const refusal = edgeRefusal(engine, entry, to, true);
+			if (refusal !== void 0 && to.name !== entry.name) findings.push({
+				rule: refusal.rule,
+				file: manifest,
+				...at,
+				message: `${field}: ${refusal.why}`,
+				target: name
+			});
+		}
+	}
+	findings.push(...packageCycles(engine));
+	return findings;
+};
+/** Cycles between workspace packages through their runtime dependency fields, each reported once. */
+const packageCycles = (engine) => {
+	const { workspace } = engine;
+	const edges = new Map(workspace.packages.map((entry) => [entry.name, [...new Set(runtimeFields.flatMap((field) => entry.manifest[field]))].filter((name) => workspace.byName.has(name) && name !== entry.name)]));
+	const state = /* @__PURE__ */ new Map();
+	const findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (name, path) => {
+		if (state.get(name) === "done") return;
+		if (state.get(name) === "visiting") {
+			const cycle = [...path.slice(path.indexOf(name)), name];
+			const key = cycle.slice(0, -1).toSorted().join(" ");
+			if (!seen.has(key)) {
+				seen.add(key);
+				const first = workspace.byName.get(name);
+				findings.push({
+					rule: "package-cycle",
+					file: `${first?.directory ?? name}/package.json`,
+					line: 1,
+					column: 0,
+					message: `dependency cycle: ${cycle.join(" -> ")}`,
+					target: key
+				});
+			}
+			return;
+		}
+		state.set(name, "visiting");
+		for (const next of edges.get(name) ?? []) visit(next, [...path, name]);
+		state.set(name, "done");
+	};
+	for (const name of [...edges.keys()].toSorted()) visit(name, []);
+	return findings;
+};
+/** Baseline entries that no finding in `findings` needs; each is a finding of its own, so the baseline only shrinks. */
+const staleBaseline = (engine, findings) => engine.config.baseline.filter((entry) => !findings.some((finding) => baselineCovers(entry, finding))).map((entry) => ({
+	rule: "stale-baseline",
+	file: entry.file,
+	line: 1,
+	column: 0,
+	message: `the baseline entry for ${entry.rule}${entry.target === void 0 ? "" : ` (${entry.target})`} is no longer needed: remove it`,
+	target: entry.rule
+}));
+// src/check.ts
+/** The whole check: every source file of the workspace through the engine, plus the whole-graph checks and the baseline. */
+const isFile = (path) => {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+};
+/**
+* Every source file the engine reads, found by walking each package's directory (skipping `node_modules` and dot
+* directories). A walk rather than `git ls-files`: generated and gitignored sources still ship, and a nested repository
+* or submodule inside a package is still part of it.
+*/
+const listSourceFiles = (engine) => {
+	const files = /* @__PURE__ */ new Set();
+	const walk = (relative) => {
+		for (const entry of readdirSync(nodePath.join(engine.workspace.root, relative), { withFileTypes: true })) {
+			const path = `${relative}/${entry.name}`;
+			if (entry.isDirectory() && entry.name !== "node_modules" && !entry.name.startsWith(".")) walk(path);
+			else if ((entry.isFile() || entry.isSymbolicLink() && isFile(nodePath.join(engine.workspace.root, path))) && reads(engine, path)) files.add(path);
+		}
+	};
+	for (const entry of engine.workspace.packages) walk(entry.directory);
+	return [...files].toSorted();
+};
+const checkWorkspace = (root, config) => {
+	const engine = createEngine(root, config);
+	const files = listSourceFiles(engine);
+	const all = [...files.flatMap((file) => findingsForFile(engine, file, readFileSync(nodePath.join(root, file), "utf8"))).filter((finding) => finding.rule !== "package-without-kind"), ...graphFindings(engine)];
+	return {
+		files: files.length,
+		findings: [...withoutBaselined(engine, all), ...staleBaseline(engine, all)]
+	};
+};
+const formatFinding = (finding) => `${finding.file}:${finding.line}:${finding.column + 1} ${finding.rule}: ${finding.message}`;
+export { staleBaseline as a, graphFindings as i, formatFinding as n, listSourceFiles as r, checkWorkspace as t };

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+import { n as Config } from "./config-CpuQhyZE.mjs";
+export declare const loadConfig: (path: string) => Promise<Config>;

package/dist/cli.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { d as findWorkspaceRoot } from "./engine-7N-4EtzS.mjs";
+import { n as formatFinding, t as checkWorkspace } from "./check-GClvJhK3.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import nodePath from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+// src/cli.ts
+/**
+* `ox-dep-lint [--root <dir>] [--config <file>]`: checks the workspace and exits 1 on any finding. The configuration is
+* `ox-dep-lint.config.{ts,mts,js,mjs,json}` at the workspace root unless `--config` names one.
+*/
+const configNames = [
+	"ox-dep-lint.config.ts",
+	"ox-dep-lint.config.mts",
+	"ox-dep-lint.config.js",
+	"ox-dep-lint.config.mjs",
+	"ox-dep-lint.config.json"
+];
+const argument = (name) => {
+	const index = process.argv.indexOf(name);
+	return index === -1 ? void 0 : process.argv[index + 1];
+};
+const loadConfig = async (path) => {
+	if (path.endsWith(".json")) return JSON.parse(readFileSync(path, "utf8"));
+	const loaded = await import(pathToFileURL(path).href);
+	if (typeof loaded !== "object" || loaded === null || !("default" in loaded)) throw new Error(`${path} has no default export`);
+	return loaded.default;
+};
+const main = async () => {
+	const root = argument("--root") ?? findWorkspaceRoot(process.cwd());
+	if (root === void 0) {
+		process.stderr.write("ox-dep-lint: no package.json with workspaces at or above this directory; pass --root\n");
+		process.exitCode = 2;
+		return;
+	}
+	const named = argument("--config");
+	const configPath = named === void 0 ? configNames.map((name) => nodePath.join(root, name)).find((path) => existsSync(path)) : nodePath.resolve(named);
+	if (configPath === void 0) {
+		process.stderr.write(`ox-dep-lint: no configuration (${configNames.join(", ")}) in ${root}\n`);
+		process.exitCode = 2;
+		return;
+	}
+	const started = performance.now();
+	const result = checkWorkspace(root, await loadConfig(configPath));
+	for (const finding of result.findings) process.stdout.write(`${formatFinding(finding)}\n`);
+	const seconds = ((performance.now() - started) / 1e3).toFixed(2);
+	process.stdout.write(`ox-dep-lint: ${result.files} files, ${result.findings.length} findings (${seconds} s)\n`);
+	process.exitCode = result.findings.length === 0 ? 0 : 1;
+};
+try {
+	await main();
+} catch (error) {
+	process.stderr.write(`ox-dep-lint: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 2;
+}
+export { loadConfig };

package/dist/config-CpuQhyZE.d.mts

@@ -0,0 +1,110 @@
+/**
+ * How a file is checked. `shipped`: every rule. `development` (tests, scripts, fixtures): kind edges, relative imports
+ * and unresolved imports are still checked, but devDependencies, test-only specifiers, runtime modules, outside
+ * packages and computed `import()` are allowed. `unchecked`: not read at all.
+ */
+type FilePolicy = "shipped" | "development" | "unchecked";
+/** One kind of package (a layer of the workspace): which packages it holds and what they may import. */
+interface KindRule {
+  /** Globs over package directories, relative to the repository root (`libraries/*`, `packages/core`). */
+  readonly packages: readonly string[];
+  /** Kinds whose packages this kind may import, its own included only when listed; `"any"` for tools. */
+  readonly mayUse: readonly string[] | "any";
+  /** Outside packages shipped code may import and `package.json` may name in `dependencies`, or `"any"`. Default `"any"`. */
+  readonly externals?: readonly string[] | "any";
+  /** Whether shipped code may import runtime modules (`node:fs`, `fs`, `bun`, `cloudflare:workers`). Default true. */
+  readonly runtimeModules?: boolean;
+}
+/** Refinements for one package, keyed by its name. */
+interface PackageRule {
+  /** The workspace packages it may import, a subset of what its kind allows. */
+  readonly uses?: readonly string[];
+  /** Outside packages beyond its kind's. */
+  readonly externals?: readonly string[];
+  /** Workspace packages it may import only with `import type`, `export type` or a type-level `import()`. */
+  readonly typeOnlyUses?: readonly string[];
+  /** Globs over specifiers of a `typeOnlyUses` package that may still be imported as values (`@acme/core/steps`). */
+  readonly valueSpecifiers?: readonly string[];
+  /** Package-relative globs of files checked as development files though they ship (a conformance suite's entry). */
+  readonly testSupportFiles?: readonly string[];
+}
+/** Files of one policy, by package-relative globs. The first class that matches a file wins; others are shipped. */
+interface FileClass {
+  readonly files: readonly string[];
+  readonly policy: FilePolicy;
+}
+declare const ruleNames: readonly ["unknown-workspace-package", "package-without-kind", "package-outside-workspace", "invalid-package", "forbidden-edge", "type-only-edge", "relative-import-leaves-package", "package-path-escape", "shipped-imports-development-file", "self-import-by-name", "forbidden-external", "runtime-module", "test-only-in-shipped", "undeclared-import", "computed-import", "unresolved-import", "package-cycle", "stale-baseline", "parse-error"];
+type RuleName = (typeof ruleNames)[number];
+/** A finding the repository tolerates for now. The check fails when no finding needs it any more, so the list shrinks. */
+interface BaselineEntry {
+  /** Repository-relative file (or `package.json` path for a manifest finding). */
+  readonly file: string;
+  readonly rule: RuleName;
+  /** The specifier or package the finding names. */
+  readonly target: string;
+  readonly reason: string;
+}
+type ManifestField = "dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies";
+interface ImportPolicy {
+  /** `import(expression)`, an escaped literal, `createRequire`: an error in shipped code (default), everywhere, or never. */
+  readonly computed?: "error-in-shipped" | "error" | "allow";
+  /** A package importing itself by its own name. Default `"allow"`. */
+  readonly selfByName?: "error" | "allow";
+  /** A relative path or alias that names no file. Default `"error"`. */
+  readonly unresolved?: "error" | "ignore";
+  /** Which `package.json` fields count as edges between workspace packages. Default all four. */
+  readonly manifestEdgeFields?: readonly ManifestField[];
+  /**
+   * Every package a file imports must be declared in its own `package.json`. Shipped code needs `dependencies`,
+   * `peerDependencies` or `optionalDependencies` (`shippedFields`); a type-only import and a development file may also
+   * use devDependencies and the root's. Default true. knip's `unlisted` misses files no entry reaches and root
+   * devDependencies used by shipped code.
+   */
+  readonly requireDeclared?: boolean;
+  /** The fields that satisfy a shipped import. Default `dependencies`, `peerDependencies`, `optionalDependencies`. */
+  readonly shippedFields?: readonly ManifestField[];
+}
+interface Config {
+  /** Scopes whose specifiers must name a workspace package (`@file-transfer/`). */
+  readonly workspaceScopes: readonly string[];
+  readonly kinds: Readonly<Record<string, KindRule>>;
+  readonly packages?: Readonly<Record<string, PackageRule>>;
+  /** Default: tests, scripts and fixtures are development files. */
+  readonly fileClasses?: readonly FileClass[];
+  /** Default: `node:`, `bun:`, `cloudflare:` prefixes and every bare Node built-in plus `bun`. */
+  readonly runtimeModules?: {
+    readonly prefixes?: readonly string[];
+    readonly names?: readonly string[];
+  };
+  /** Prefixes of a bundler's virtual modules, which have nothing on disk to check. Default `virtual:`, `astro:`. */
+  readonly virtualModules?: readonly string[];
+  /** Globs over specifiers only development files may import: `fast-check` is that specifier alone, `fast-check/**` its subpaths. */
+  readonly testOnlySpecifiers?: readonly string[];
+  readonly imports?: ImportPolicy;
+  readonly baseline?: readonly BaselineEntry[];
+  /** Repository-relative globs of files never read. */
+  readonly ignore?: readonly string[];
+  /** Package-relative globs of build output, never read. Default `dist/**` and `coverage/**`; `[]` reads everything. */
+  readonly output?: readonly string[];
+}
+/** The configuration with every default filled in. */
+interface ResolvedConfig {
+  readonly workspaceScopes: readonly string[];
+  readonly kinds: Readonly<Record<string, Required<KindRule>>>;
+  readonly packages: Readonly<Record<string, PackageRule>>;
+  readonly fileClasses: readonly FileClass[];
+  readonly runtimePrefixes: readonly string[];
+  readonly runtimeNames: ReadonlySet<string>;
+  readonly virtualPrefixes: readonly string[];
+  readonly testOnlySpecifiers: readonly string[];
+  readonly imports: Required<ImportPolicy>;
+  readonly baseline: readonly BaselineEntry[];
+  readonly ignore: readonly string[];
+  readonly output: readonly string[];
+}
+declare const defaultFileClasses: readonly FileClass[];
+/** Identity, for type checking a configuration file. */
+declare const defineConfig: (config: Config) => Config;
+declare const configProblems: (config: Config) => string[];
+declare const resolveConfig: (config: Config) => ResolvedConfig;
+export { ImportPolicy as a, PackageRule as c, configProblems as d, defaultFileClasses as f, FilePolicy as i, ResolvedConfig as l, resolveConfig as m, Config as n, KindRule as o, defineConfig as p, FileClass as r, ManifestField as s, BaselineEntry as t, RuleName as u };