ox-dep-lint 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.

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-GClvJhK3.mjs → check-BIxs2Gr0.mjs}

@@ -1,4 +1,4 @@
-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 { 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

package/dist/cli.d.mts

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

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/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 { 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";

package/dist/{config-CpuQhyZE.d.mts → config-ClNl5rro.d.mts}

@@ -63,6 +63,14 @@ interface ImportPolicy {
   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/`). */

package/dist/{engine-7N-4EtzS.mjs → engine-C1qSxYaL.mjs}

@@ -85,7 +85,8 @@ const allowedKeys = {
 		"unresolved",
 		"manifestEdgeFields",
 		"requireDeclared",
-		"shippedFields"
+		"shippedFields",
+		"typeOnly"
 	],
 	baseline: [
 		"file",
@@ -102,7 +103,8 @@ const choices = {
 	],
 	selfByName: ["error", "allow"],
 	unresolved: ["error", "ignore"],
-	requireDeclared: [true, false]
+	requireDeclared: [true, false],
+	typeOnly: ["relaxed", "as-values"]
 };
 const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 const unknownKeys = (where, value, allowed) => typeof value === "object" && value !== null && !Array.isArray(value) ? Object.keys(value).filter((key) => !allowed.includes(key)).map((key) => `${where} has the unknown key ${key} (known: ${allowed.join(", ")})`) : [`${where} is not an object`];
@@ -213,7 +215,8 @@ const resolveConfig = (config) => {
 				"dependencies",
 				"peerDependencies",
 				"optionalDependencies"
-			]
+			],
+			typeOnly: config.imports?.typeOnly ?? "relaxed"
 		},
 		baseline: config.baseline ?? [],
 		ignore: config.ignore ?? [],
@@ -800,6 +803,19 @@ const importForms = (path, source) => {
 * it over every file and adds the whole-graph checks (`graph.ts`), so the two never disagree. Rules adapted from the
 * module graph checks of phibkro/file-transfer, phibkro/vektorprogrammet-reimagined and reebeat/reebeat.
 */
+const nodeModules = ["node:module", ...builtinModules];
+/**
+* Packages that hold a runtime's types, and the runtime modules they describe: the package counts as the runtime when
+* the configuration names any of them a runtime module (Node's by its `node:` prefix or any bare built-in).
+*/
+const runtimeTypePackages = {
+	node: nodeModules,
+	"@types/node": nodeModules,
+	bun: ["bun"],
+	"bun-types": ["bun"],
+	"@types/bun": ["bun"],
+	"@cloudflare/workers-types": ["cloudflare:workers"]
+};
 /** The source files the engine reads; anything else (`.vue`, `.json`) is no finding in either front end. */
 const sourceFile = /\.[cm]?[jt]sx?$/u;
 const createEngine = (root, config) => {
@@ -963,10 +979,22 @@ const findingsForFile = (engine, file, text, options = {}) => {
 		column: 0
 	}, `could not be parsed, so its imports cannot be checked: ${message}`, "parse");
 	for (const site of forms.computed) if (config.imports.computed === "error" || config.imports.computed === "error-in-shipped" && shipped) report("computed-import", site, `${site.text}: ${site.reason}; nothing can check what it loads`, site.text);
+	/**
+	* The packages that hold a runtime's own types, by the runtime module they describe: a type-only use of one
+	* (`/// <reference types="node" />`, `import type {} from "bun-types"`) is a use of that runtime, judged by
+	* `runtime-module` like `node:fs` and never as an outside package to declare.
+	*/
+	const runtimeOf = (site) => {
+		return (site.typeOnly ? runtimeTypePackages[packageNameOf(site.specifier)] : void 0)?.find((module) => isRuntimeModule(config, module));
+	};
 	for (const site of forms.imports) {
-		const { typeOnly } = site;
+		const typeOnly = site.typeOnly && config.imports.typeOnly === "relaxed";
 		const specifier = withoutQuery(site.specifier);
-		const target = engine.resolver.resolve(file, site.specifier);
+		const runtime = runtimeOf(site);
+		const target = runtime === void 0 ? engine.resolver.resolve(file, site.specifier) : {
+			kind: "runtime",
+			name: runtime
+		};
 		const resolvedName = target.kind === "external" || target.kind === "workspace" ? target.name : void 0;
 		const subpathOf = (name) => specifier === name || specifier.startsWith(`${name}/`);
 		const names = resolvedName === void 0 || subpathOf(resolvedName) ? [specifier] : [specifier, resolvedName];
@@ -982,7 +1010,7 @@ const findingsForFile = (engine, file, text, options = {}) => {
 		};
 		switch (target.kind) {
 			case "runtime":
-				if (shipped && !typeOnly && kindRule?.runtimeModules === false) report("runtime-module", site, `imports the runtime module ${specifier}, which ${article(kind)} package may not use in shipped code`, specifier);
+				if (shipped && !typeOnly && kindRule?.runtimeModules === false) report("runtime-module", site, `imports ${runtime === void 0 ? `the runtime module ${specifier},` : `the runtime types package ${specifier},`} which ${article(kind)} package may not use in shipped code`, specifier);
 				break;
 			case "virtual": break;
 			case "unknown-workspace":
@@ -1000,7 +1028,7 @@ const findingsForFile = (engine, file, text, options = {}) => {
 					if (config.imports.selfByName === "error") report("self-import-by-name", site, "imports its own package by its name; use a relative path", specifier);
 					break;
 				}
-				const refusal = edgeRefusal(engine, owner, to, typeOnly, specifier);
+				const refusal = edgeRefusal(engine, owner, to, site.typeOnly, specifier);
 				if (refusal !== void 0) report(refusal.rule, site, refusal.why, to.name);
 				if (config.imports.requireDeclared && !declares(engine, owner, to.name, !shipped || typeOnly)) report("undeclared-import", site, `imports ${to.name}, which ${owner.directory}/package.json does not declare${shipped ? " for shipped code" : ""}`, to.name);
 				break;
@@ -1024,7 +1052,7 @@ const findingsForFile = (engine, file, text, options = {}) => {
 				const permitted = (name) => allowed === "any" || allowed?.includes(name) === true || extra.includes(name);
 				if (shipped && !typeOnly && !permitted(target.name)) report("forbidden-external", site, `${article(kind)} package may not import ${target.name} in shipped code`, target.name);
 				const anywhere = !shipped || typeOnly;
-				const declared = declares(engine, owner, target.name, anywhere) || declares(engine, owner, target.written, anywhere) || typeOnly && declares(engine, owner, typesPackage(target.name), true);
+				const declared = declares(engine, owner, target.name, anywhere) || declares(engine, owner, target.written, anywhere) || site.typeOnly && declares(engine, owner, typesPackage(target.name), anywhere);
 				if (config.imports.requireDeclared && !declared) report("undeclared-import", site, `imports ${target.name}, which ${owner.directory}/package.json does not declare${shipped ? " for shipped code" : ""}`, target.name);
 				break;
 			}

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as ImportPolicy, c as PackageRule, d as configProblems, f as defaultFileClasses, i as FilePolicy, l as ResolvedConfig, m as resolveConfig, n as Config, o as KindRule, p as defineConfig, r as FileClass, s as ManifestField, t as BaselineEntry, u as RuleName } from "./config-CpuQhyZE.mjs";
+import { a as ImportPolicy, c as PackageRule, d as configProblems, f as defaultFileClasses, i as FilePolicy, l as ResolvedConfig, m as resolveConfig, n as Config, o as KindRule, p as defineConfig, r as FileClass, s as ManifestField, t as BaselineEntry, u as RuleName } from "./config-ClNl5rro.mjs";
 interface WorkspacePackage {
   readonly name: string;
   /** Repository-relative directory, `/`-separated (`libraries/parcel`). */

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { _ as configProblems, a as findingsForFile, b as resolveConfig, c as withoutBaselined, d as findWorkspaceRoot, f as loadWorkspace, g as matchesGlob, h as matchesAny, i as effectivePolicy, l as importForms, m as packageOfFile, n as createEngine, o as policyOf, p as packageNameOf, s as reads, v as defaultFileClasses, y as defineConfig } from "./engine-7N-4EtzS.mjs";
-import { a as staleBaseline, i as graphFindings, n as formatFinding, r as listSourceFiles, t as checkWorkspace } from "./check-GClvJhK3.mjs";
+import { _ as configProblems, a as findingsForFile, b as resolveConfig, c as withoutBaselined, d as findWorkspaceRoot, f as loadWorkspace, g as matchesGlob, h as matchesAny, i as effectivePolicy, l as importForms, m as packageOfFile, n as createEngine, o as policyOf, p as packageNameOf, s as reads, v as defaultFileClasses, y as defineConfig } from "./engine-C1qSxYaL.mjs";
+import { a as staleBaseline, i as graphFindings, n as formatFinding, r as listSourceFiles, t as checkWorkspace } from "./check-BIxs2Gr0.mjs";
 export { checkWorkspace, configProblems, createEngine, defaultFileClasses, defineConfig, effectivePolicy, findWorkspaceRoot, findingsForFile, formatFinding, graphFindings, importForms, listSourceFiles, loadWorkspace, matchesAny, matchesGlob, packageNameOf, packageOfFile, policyOf, reads, resolveConfig, staleBaseline, withoutBaselined };

package/dist/plugin.mjs

@@ -1,4 +1,4 @@
-import { a as findingsForFile, c as withoutBaselined, d as findWorkspaceRoot, n as createEngine } from "./engine-7N-4EtzS.mjs";
+import { a as findingsForFile, c as withoutBaselined, d as findWorkspaceRoot, n as createEngine } from "./engine-C1qSxYaL.mjs";
 import { statSync } from "node:fs";
 import nodePath from "node:path";
 // src/plugin.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ox-dep-lint",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Module dependency graph rules for oxlint: package kinds, outside packages, runtime and test-only modules, undeclared, escaping and computed imports",
   "license": "MIT",
   "author": "Philip B. Krogh",
@@ -32,13 +32,18 @@
     "build": "vp pack",
     "check": "vp check --deny-warnings && vp test run",
     "test": "vp test run",
-    "prepack": "vp pack"
+    "prepack": "vp pack",
+    "prepare": "vp config",
+    "changeset": "changeset"
   },
   "dependencies": {
     "oxc-parser": "0.153.0",
     "oxc-resolver": "11.24.2"
   },
   "devDependencies": {
+    "@changesets/cli": "3.0.3",
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-conventional": "21.2.3",
     "@types/node": "24.9.1",
     "oxlint": "1.86.0",
     "typescript": "7.0.2",