ox-dep-lint 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0
+
+### Minor Changes
+
+- 89ab407: New policy `imports.typeOnly`. With `"as-values"`, shipped code's type-only imports (every form, `/// <reference types>` included) are judged by `runtime-module`, `forbidden-external`, `undeclared-import` and `shipped-imports-development-file`. So `import type { Socket } from "bun"` fails in a kind with `runtimeModules: false`, and a vendor's types fail where the kind's `externals` do not allow it. A shipped `@types/x` still declares `x` for a type-only import. The default, `"relaxed"`, keeps 0.1's behaviour: types do not load, so those rules skip them.
+
+  A runtime's own types package (`node`, `@types/node`, `bun-types`, `@types/bun`, `@cloudflare/workers-types`, or a subpath of one) used type-only now counts as that runtime, in shipped and development files alike. So it is never reported as an outside package or as undeclared; until now an undeclared one gave `undeclared-import`. Under `"as-values"`, `runtime-module` judges it where the kind allows no runtime modules; under `"relaxed"` it passes, like other type-only imports.
+
+## 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/README.md

@@ -79,6 +79,9 @@ A kind may use its own kind only when `mayUse` lists it. `imports` holds the pol
 | `manifestEdgeFields` | all four fields                                            | any subset       |
 | `requireDeclared`    | `true`                                                     | `false`          |
 | `shippedFields`      | `dependencies`, `peerDependencies`, `optionalDependencies` | any subset       |
+| `typeOnly`           | `relaxed`                                                  | `as-values`      |
+
+`typeOnly: "as-values"` judges shipped code's type-only imports (`import type`, `export type`, type-level `import()`, `declare module`, `import type X = require()`, `/// <reference types>`) by `runtime-module`, `forbidden-external`, `undeclared-import` and `shipped-imports-development-file`, so `import type { Socket } from "bun"` fails in a kind without runtime modules. Two differences from value imports remain. A shipped field that declares `@types/x` declares `x` for a type-only import, and such an `@types/x` is an outside package too, so `externals` lists both. A runtime's own types package (`node` or `@types/node`, `bun`, `bun-types` or `@types/bun`, `@cloudflare/workers-types`) counts as that runtime, so it is judged by `runtime-module` and never needs declaring. That includes a published package whose emitted declarations reference those types: declare `@types/node` or `bun-types` for its consumers yourself; this check does not ask for it. By default types do not load, so those rules skip type-only imports. Kind edges and `typeOnlyUses` always see the real form.
 
 Misspelled keys, unknown policies and baseline entries without a `target` are configuration errors, never silent defaults.
 
@@ -127,6 +130,12 @@ Where they can still differ: oxlint chooses which files it lints (its own ignore
 - `/// <reference path="..." />` and JSDoc `@import` types are not read.
 - A `require` passed around as a value (`const load = require; load("x")`) is not followed. Telling the global loader from a local of the same name needs scope analysis; until then the check reads `require` only where it is called.
 
+## Contributing and releases
+
+- Commits and pull request titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `chore:`); a `commit-msg` hook and CI check them with commitlint.
+- Every pull request adds a changeset: `bunx changeset` and pick patch, minor or major, or `bunx changeset --empty` when nothing ships. Before 1.0, a breaking change is a minor bump.
+- Versions follow [semantic versioning](https://semver.org/) and are never edited by hand. While changesets wait on main, the `release` workflow keeps a pull request `chore(release): vX.Y.Z` up to date with the bumped `package.json` and the new `CHANGELOG.md` entry. Merging it publishes that version to npm through trusted publishing (with provenance), tags it and makes a GitHub release. Empty changesets alone open no release; they are consumed with the next one.
+
 ## Licence
 
 MIT. The specifier reader and resolver are adapted from phibkro/vektorprogrammet-reimagined, and the rules from that repository and phibkro/file-transfer, all by the same author. The escape-sequence rule closes a bypass found in reebeat/reebeat's tier check. No code from reebeat was copied.

package/dist/check-BIxs2Gr0.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-C1qSxYaL.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-ClNl5rro.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-C1qSxYaL.mjs";
+import { n as formatFinding, t as checkWorkspace } from "./check-BIxs2Gr0.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-ClNl5rro.d.mts

@@ -0,0 +1,118 @@
+/**
+ * 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[];
+  /**
+   * How shipped code's type-only imports (`import type`, `export type`, a type-level `import()`, `declare module`, a
+   * types reference) are judged by `runtime-module`, `forbidden-external`, `undeclared-import` and
+   * `shipped-imports-development-file`. `"relaxed"` (default): types do not load, so those rules skip them and
+   * devDependencies declare them. `"as-values"`: judged like value imports, for kinds whose public types must not name
+   * a runtime or vendor either. Kind edges and `typeOnlyUses` always see the real form.
+   */
+  readonly typeOnly?: "relaxed" | "as-values";
+}
+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 };