ox-dep-lint 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- e75db50: Sources under a workspace glob no longer escape the check unreported: each one is read, or the reason it cannot be read is a finding. Plain files at a glob's level (`packages/x.ts`, outside every package directory) and entries that are neither files, directories nor links (FIFOs, sockets) are still not reported. This can add findings to a repository that passed before, so upgrade with the CLI once and baseline or fix what it reports.
+
+  - The walk now reads dot directories inside a package (`src/.internal/x.ts`), as oxlint already did; it skips only `node_modules` and `.git`.
+  - `output` now defaults to `dist/**`, `coverage/**` and the caches tools write at a package root: `.wrangler/**`, `.astro/**`, `.svelte-kit/**`, `.next/**`, `.turbo/**`, `.vercel/**`, `.nuxt/**`, `.output/**`. Setting `output` replaces the defaults; it does not add to them.
+  - `symbolic-link`: every symbolic link under a package directory, whatever it points at and whatever its name (`.d.ts`, `.md`, `.json`, extensionless); a link a `workspaces` or kind glob matches or names literally; and a link a glob passes through (`packages` itself a link). Links are never followed: 0.2 read a link to a file as if it were the file, skipped a link to a directory silently, and followed a linked `packages`. Only links inside directories the check skips on purpose are not reported: `node_modules`, `.git`, and directories that `ignore`, `output` or an unchecked file class cover through a trailing `/**`. A baseline entry names the link as `file` and its destination, as written, as `target`; baselined or not, what a link points at is never read. A Nix `result` link inside a package is a finding; `ignore: ["**/result/**"]` clears it. The oxlint plugin reports it on each file oxlint reaches through a link and reads nothing else in that file.
+  - `unreadable-path`: a directory the walk, a `workspaces` glob or a kind's glob cannot list, or a source file the check cannot read (`EACCES`), unless the check skips it on purpose. 0.2 stopped with exit code 2 and the error instead.
+  - `directory-without-package`: a directory a root `workspaces` glob matches that has no `package.json` and lies neither inside nor above a member, so nothing checks its files; and a dot directory such a glob would match (`packages/.template`), with or without a `package.json`, since npm and Bun workspaces never match dot directories. Only the topmost of nested ones is reported, and a negated glob (`!tools/legacy` or `!tools/legacy/**`) leaves it out. No new configuration key: add `dir/**` to `ignore`, or baseline it, to keep one.
+
+  A workspaces entry or kind glob that names or passes through a symbolic link no longer finds packages there: the link is reported instead of followed. `listSourceFiles` no longer lists a file reached through a link; the new `walkSources` returns the files with the walk's findings. `Workspace` has a new field, `globs`, the root's `workspaces` globs.
+
+## 0.3.0
+
+### Minor Changes
+
+- 7af0fef: An internal refactor with no change in behaviour for configurations written as plain data (objects, arrays and strings, without getters, Proxies or custom iterators): every finding and every message is the same as in 0.2.0, in the same order, and so is every configuration error. Output differs only where 0.2.0 crashed: a hole in a sparse `fileClasses` or `baseline` list (`[ , ]` in an `.mjs` file) is now reported as `fileClasses must be a list of objects` or `baseline must be a list of objects`, also when a Symbol elsewhere would have crashed first; and a chain of thousands of packages, which exhausted 0.2.0's stack, is now checked. A Symbol written into a message (a baseline entry's file, a kind in `mayUse`) still crashes (exit 2) when no such hole is present, though the TypeError's wording can differ when another value that cannot become a string (an object without a usable `toString`) is also present, because the checks run in another order. A configuration built from getters, Proxies or custom iterators can now be read differently, because validation reads values (including those of unknown keys) that 0.2.0 never read.
+
+  The configuration is validated by valibot schemas whose issues map to 0.2's messages, cycles between packages come from Tarjan's strongly connected components (iterative, so a long chain of packages cannot exhaust the stack) with the same routes as before, and the walk through development files reads its queue from a head index instead of `shift()`.
+
+  New runtime dependency: `valibot` 1.5.0 (MIT). The public types are unchanged and written out as before; the emitted declarations do not import valibot.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -11,27 +11,30 @@ ox-dep-lint replaces the hand-written module graph checks of three repositories
 
 ## What it checks
 
-| Rule                               | Finding                                                                                                                                                                                                                                                                                                                                                           | Front end                       |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| `forbidden-edge`                   | A load of a workspace package that its kind (or its `uses`) does not allow. The same check runs on edges declared in `package.json`: all four dependency fields by default, devDependencies included.                                                                                                                                                             | both                            |
-| `type-only-edge`                   | A value import of a package listed in `typeOnlyUses`. Only `import type` and `export type` declarations are type-only; an inline `import { type X }` still loads the module under `verbatimModuleSyntax`.                                                                                                                                                         | both                            |
-| `unknown-workspace-package`        | A name under a workspace scope that no package has, in an import or a `package.json`.                                                                                                                                                                                                                                                                             | both                            |
-| `package-path-escape`              | A package specifier with `.` or `..` after the name (`@acme/a/../b/src/x.ts`).                                                                                                                                                                                                                                                                                    | both                            |
-| `relative-import-leaves-package`   | A relative path, alias, root-absolute path or worker URL that resolves into another package, into `node_modules` or out of the repository. Import a package by its name instead.                                                                                                                                                                                  | both                            |
-| `shipped-imports-development-file` | Shipped code importing a development file (of its own package, or one another package exports), or a file under `output` or `ignore`, that would not pass as shipped code itself: a test helper using `fast-check`, a script using `node:fs`. A development file that would pass, such as a shared helper under `scripts/`, may be imported.                      | both                            |
-| `forbidden-external`               | An outside package that the kind's `externals` does not allow, in shipped code or in `package.json`'s shipped fields. An outside package is named by the package it installs (the `name` in its installed `package.json`, or an `npm:` alias's target), so an alias cannot pass one package off as another; `externals` name real packages.                       | both, `package.json` in the CLI |
-| `runtime-module`                   | `node:*`, a bare Node built-in (`fs`), `bun`, `bun:*` or `cloudflare:*`, also when a package import (`#crypto`) maps to one, in the shipped code of a kind with `runtimeModules: false`.                                                                                                                                                                          | both                            |
-| `test-only-in-shipped`             | A `testOnlySpecifiers` match (`fast-check`, `vite-plus/test`) in shipped code, with any `?query` stripped.                                                                                                                                                                                                                                                        | both                            |
-| `undeclared-import`                | A package the file's own `package.json` does not declare. Shipped code needs `dependencies`, `peerDependencies` or `optionalDependencies` (`imports.shippedFields`); type-only imports and development files may also use devDependencies and the root's. This covers what knip misses: files no entry reaches, and shipped code leaning on a root devDependency. | both                            |
-| `computed-import`                  | A load whose module the check cannot read: `import(expression)`, `require(expression)`, `import.meta.glob`, a kept `createRequire` function, or a literal written with an escape sequence (which is also checked by the module it spells). Shipped code only, by default.                                                                                         | both                            |
-| `unresolved-import`                | A relative path or alias (`#x`, `@/x`, `~/x`) that names no file.                                                                                                                                                                                                                                                                                                 | both                            |
-| `self-import-by-name`              | A package importing itself by its own name (off by default).                                                                                                                                                                                                                                                                                                      | both                            |
-| `package-without-kind`             | A workspace package that no kind's globs hold.                                                                                                                                                                                                                                                                                                                    | both                            |
-| `package-outside-workspace`        | A directory a kind names, with a `package.json`, that the root `workspaces` leave out, so nothing in it would be checked.                                                                                                                                                                                                                                         | CLI                             |
-| `invalid-package`                  | A workspace member whose `package.json` cannot be read, has no name, or has another member's name.                                                                                                                                                                                                                                                                | CLI                             |
-| `package-cycle`                    | A cycle between packages through their runtime dependency fields.                                                                                                                                                                                                                                                                                                 | CLI                             |
-| `stale-baseline`                   | A baseline entry that no finding needs any more, so the baseline can only shrink.                                                                                                                                                                                                                                                                                 | CLI                             |
-| `parse-error`                      | A file that does not parse, so its imports cannot be checked.                                                                                                                                                                                                                                                                                                     | both                            |
+| Rule                               | Finding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Front end                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `forbidden-edge`                   | A load of a workspace package that its kind (or its `uses`) does not allow. The same check runs on edges declared in `package.json`: all four dependency fields by default, devDependencies included.                                                                                                                                                                                                                                                                                                                                                                                       | both                                                         |
+| `type-only-edge`                   | A value import of a package listed in `typeOnlyUses`. Only `import type` and `export type` declarations are type-only; an inline `import { type X }` still loads the module under `verbatimModuleSyntax`.                                                                                                                                                                                                                                                                                                                                                                                   | both                                                         |
+| `unknown-workspace-package`        | A name under a workspace scope that no package has, in an import or a `package.json`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | both                                                         |
+| `package-path-escape`              | A package specifier with `.` or `..` after the name (`@acme/a/../b/src/x.ts`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | both                                                         |
+| `relative-import-leaves-package`   | A relative path, alias, root-absolute path or worker URL that resolves into another package, into `node_modules` or out of the repository. Import a package by its name instead.                                                                                                                                                                                                                                                                                                                                                                                                            | both                                                         |
+| `shipped-imports-development-file` | Shipped code importing a development file (of its own package, or one another package exports), or a file under `output` or `ignore`, that would not pass as shipped code itself: a test helper using `fast-check`, a script using `node:fs`. A development file that would pass, such as a shared helper under `scripts/`, may be imported.                                                                                                                                                                                                                                                | both                                                         |
+| `forbidden-external`               | An outside package that the kind's `externals` does not allow, in shipped code or in `package.json`'s shipped fields. An outside package is named by the package it installs (the `name` in its installed `package.json`, or an `npm:` alias's target), so an alias cannot pass one package off as another; `externals` name real packages.                                                                                                                                                                                                                                                 | both, `package.json` in the CLI                              |
+| `runtime-module`                   | `node:*`, a bare Node built-in (`fs`), `bun`, `bun:*` or `cloudflare:*`, also when a package import (`#crypto`) maps to one, in the shipped code of a kind with `runtimeModules: false`.                                                                                                                                                                                                                                                                                                                                                                                                    | both                                                         |
+| `test-only-in-shipped`             | A `testOnlySpecifiers` match (`fast-check`, `vite-plus/test`) in shipped code, with any `?query` stripped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | both                                                         |
+| `undeclared-import`                | A package the file's own `package.json` does not declare. Shipped code needs `dependencies`, `peerDependencies` or `optionalDependencies` (`imports.shippedFields`); type-only imports and development files may also use devDependencies and the root's. This covers what knip misses: files no entry reaches, and shipped code leaning on a root devDependency.                                                                                                                                                                                                                           | both                                                         |
+| `computed-import`                  | A load whose module the check cannot read: `import(expression)`, `require(expression)`, `import.meta.glob`, a kept `createRequire` function, or a literal written with an escape sequence (which is also checked by the module it spells). Shipped code only, by default.                                                                                                                                                                                                                                                                                                                   | both                                                         |
+| `unresolved-import`                | A relative path or alias (`#x`, `@/x`, `~/x`) that names no file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | both                                                         |
+| `self-import-by-name`              | A package importing itself by its own name (off by default).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | both                                                         |
+| `package-without-kind`             | A workspace package that no kind's globs hold.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | both                                                         |
+| `package-outside-workspace`        | A directory a kind names, with a `package.json`, that the root `workspaces` leave out, so nothing in it would be checked.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | CLI                                                          |
+| `invalid-package`                  | A workspace member whose `package.json` cannot be read, has no name, or has another member's name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | CLI                                                          |
+| `directory-without-package`        | A directory a root `workspaces` glob matches that has no `package.json` and lies neither inside nor above a member, so no package owns its files and nothing checks them (tsukuri's "directory in no tier"). Also a dot directory such a glob would match (`packages/.template`), with or without a `package.json`: npm and Bun workspaces never match dot directories, so it is no package. Only the topmost of nested ones is reported; a negated glob (`!tools/legacy` or `!tools/legacy/**`) leaves the directory out. Silence one with `ignore` (`tools/vendored/**`) or the baseline. | CLI                                                          |
+| `symbolic-link`                    | Every symbolic link under a package directory, whatever it points at (a file, a directory, nothing, a cycle) and whatever its name (`.d.ts`, `.md`, `.json`, extensionless); a link a `workspaces` or kind glob matches or names (`packages/x -> ../elsewhere`); and a link a glob passes through (`packages` itself a link). The check never follows one. It skips only links inside directories it skips on purpose: `node_modules`, `.git`, and directories `ignore`, `output` or an unchecked file class cover through a trailing `/**`.                                                | both (the plugin on each file oxlint reaches through a link) |
+| `unreadable-path`                  | A directory the walk, a `workspaces` glob or a kind glob cannot list, or a source file the check cannot read (`EACCES`), unless the check skips it on purpose. It used to stop the check with exit code 2.                                                                                                                                                                                                                                                                                                                                                                                  | CLI                                                          |
+| `package-cycle`                    | A cycle between packages through their runtime dependency fields.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | CLI                                                          |
+| `stale-baseline`                   | A baseline entry that no finding needs any more, so the baseline can only shrink.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | CLI                                                          |
+| `parse-error`                      | A file that does not parse, so its imports cannot be checked.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | both                                                         |
 
 A load is any of: `import` and `export ... from` (static, `defer` and `source` phases), `import()`, a type-level `import("...")`, `import x = require("...")`, a string-named `declare module "..."`, `/// <reference types="..." />`, `require`, `require.resolve`, `module.require`, `import.meta.require`, `import.meta.resolve`, `process.getBuiltinModule`, `createRequire(...)("...")`, and a `new URL("...", import.meta.url)` passed to `new Worker`, `new SharedWorker` or `navigator.serviceWorker.register` (bundlers load it as a module, extension or not; any other `new URL` locates a file to read or an asset to serve, and is not a load). `require.resolve` and `import.meta.resolve` with a literal are edges; with an expression they load nothing.
 
@@ -43,7 +46,7 @@ The first matching file class decides how a file is checked. Globs in a class ar
 - **development:** kind edges, relative imports and unresolved imports are still checked. The file may use devDependencies (its own and the root's), test-only specifiers, runtime modules, any outside package and computed `import()`.
 - **unchecked:** the file is not read.
 
-By default, `test/**`, `tests/**`, `e2e/**`, `scripts/**`, package-root `*.config.*`, `**/__tests__/**`, `**/fixtures/**` and `**/*.{test,spec,bench}.*` are development files. A package's `dist/**` and `coverage/**` are not read; `output` changes that list (`[]` reads everything). A package's `testSupportFiles` are development files too (a conformance suite's entry, for example).
+By default, `test/**`, `tests/**`, `e2e/**`, `scripts/**`, package-root `*.config.*`, `**/__tests__/**`, `**/fixtures/**` and `**/*.{test,spec,bench}.*` are development files. A package's build output and the caches tools write at its root are not read: `output` defaults to `dist/**`, `coverage/**`, `.wrangler/**`, `.astro/**`, `.svelte-kit/**`, `.next/**`, `.turbo/**`, `.vercel/**`, `.nuxt/**` and `.output/**`. Setting `output` replaces these defaults rather than adding to them, so list the ones you still want (`[]` reads everything). Shipped code that imports a file under `output` still has that file judged. A package's `testSupportFiles` are development files too (a conformance suite's entry, for example).
 
 ## Configuration
 
@@ -85,6 +88,10 @@ A kind may use its own kind only when `mayUse` lists it. `imports` holds the pol
 
 Misspelled keys, unknown policies and baseline entries without a `target` are configuration errors, never silent defaults.
 
+The root `workspaces` globs also say where packages live: a directory they match without a `package.json` is a `directory-without-package` finding, so no new key is needed. To keep such a directory (vendored sources that are not a package), add `dir/**` to `ignore` or baseline it with `file` and `target` both set to the directory.
+
+A `symbolic-link` baseline entry names the link as `file` and its destination, as the link writes it, as `target`, so pointing the link elsewhere makes the entry stale. Baselining a link does not make the check read through it: what a link points at is never read, baselined or not. A Nix `result` link (from `nix build`) left inside a package is a finding too; build outside packages, or add `**/result/**` to `ignore`.
+
 ## Installing
 
 ```sh
@@ -95,7 +102,7 @@ Releases are published from a `v*` tag by `.github/workflows/release.yml`, with
 
 ## Running it
 
-The CLI walks every workspace package's directory (skipping `node_modules`, dot directories and `output`), so generated and gitignored sources and nested repositories are checked too, and runs the whole-graph checks:
+The CLI walks every workspace package's directory, dot directories included (`src/.internal/`), skipping only `node_modules` and `.git` and reading nothing under `output`, so generated and gitignored sources and nested repositories are checked too, and runs the whole-graph checks. Tool caches such as `.wrangler` and `.astro` are in the default `output`; for another cache, set `output` to the defaults plus its glob, since `output` replaces the defaults. The CLI never follows a symbolic link: every link is a `symbolic-link` finding, and a directory it cannot list or a file it cannot read is an `unreadable-path` finding. What it still does not report: plain files directly at a workspace glob's level (`packages/x.ts`), and FIFOs and sockets.
 
 ```sh
 ox-dep-lint            # finds ox-dep-lint.config.{ts,mts,js,mjs,json} at the workspace root
@@ -120,7 +127,7 @@ export default defineConfig({
 
 The plugin and the CLI call one function per file, and a test runs both under real oxlint and requires the same findings at the same places. In a long-lived process (an editor's language server) the plugin rebuilds its view of the workspace when a `package.json` changes, and looks again for a file it could not resolve.
 
-Where they can still differ: oxlint chooses which files it lints (its own ignores), and the CLI reads the files of workspace packages. oxlint shows line-1 columns of a file that starts with a byte order mark three further on than the CLI does.
+Where they can still differ: oxlint chooses which files it lints (its own ignores), and the CLI reads the files of workspace packages. oxlint follows symbolic links, so the plugin reports `symbolic-link` at line 1 of each file it is given through a link (and reads nothing else in it), where the CLI reports the link once; a link to a file oxlint does not lint (`README.md`) is reported by the CLI alone. Both read dot directories. oxlint shows line-1 columns of a file that starts with a byte order mark three further on than the CLI does.
 
 ## Not yet
 

package/dist/check-BbeuFBNh.mjs

@@ -0,0 +1,341 @@
+import { C as attempt, D as matchesGlob, c as linkDestination, d as reads, f as reportsLink, g as withoutBaselined, h as unreadablePathFinding, i as edgeRefusal, l as passedOver, m as symbolicLinkFinding, n as coversDirectory, o as findingsForFile, p as skipsDirectory, r as createEngine, s as ignoresDirectory, t as baselineCovers, v as directoriesMatching, w as codeOf } from "./engine-DmECSDnu.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, directories the workspaces match that no package owns, 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)]);
+	const unlistedByKinds = {
+		links: [],
+		unreadable: [],
+		dotDirectories: []
+	};
+	for (const kind of Object.values(config.kinds)) for (const pattern of kind.packages) for (const directory of directoriesMatching(workspace.root, pattern, unlistedByKinds)) 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
+		});
+	}
+	findings.push(...directoriesWithoutPackage(engine, members, unlistedByKinds));
+	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;
+};
+const isDirectory = (absolute) => {
+	try {
+		return statSync(absolute).isDirectory();
+	} catch {
+		return false;
+	}
+};
+/** Whether `absolute`, links followed, is something other than a directory; false when nothing is there. */
+const isFile = (absolute) => {
+	try {
+		return !statSync(absolute).isDirectory();
+	} catch {
+		return false;
+	}
+};
+/** The error code of a directory that cannot be listed, or undefined when it can. */
+const unreadable = (absolute) => {
+	try {
+		readdirSync(absolute);
+		return;
+	} catch (cause) {
+		return codeOf(cause);
+	}
+};
+/**
+* What the root's `workspaces` globs (and a kind's globs) match that is no package: a directory without a
+* `package.json`, whose files no package owns and so nothing checks (only the topmost of nested ones); a dot directory,
+* which no workspaces glob matches; a directory the globs cannot list; and a symbolic link to a directory (or to
+* nothing), which is never followed. Inside a member the walk reports these, so they are left to it. A directory above a member (under `packages/**`), one a negated glob or `ignore` leaves out, and
+* anything under `node_modules` or `.git` are not reported.
+*/
+const directoriesWithoutPackage = (engine, members, unlistedByKinds) => {
+	const { workspace } = engine;
+	const negated = workspace.globs.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1).replace(/^\.\//u, "").replace(/\/$/u, ""));
+	const inside = (path) => [...members].some((member) => path === member || path.startsWith(`${member}/`));
+	const above = (path) => [...members].some((member) => member.startsWith(`${path}/`));
+	const leftOut = (path) => path.split("/").some(passedOver) || negated.some((pattern) => matchesGlob(path, pattern) || coversDirectory(pattern, path)) || ignoresDirectory(engine, path);
+	const candidates = /* @__PURE__ */ new Map();
+	const unlisted = {
+		links: [...unlistedByKinds.links],
+		unreadable: [...unlistedByKinds.unreadable],
+		dotDirectories: []
+	};
+	for (const glob of workspace.globs.filter((pattern) => !pattern.startsWith("!"))) for (const directory of directoriesMatching(workspace.root, glob, unlisted)) if (!candidates.has(directory)) candidates.set(directory, glob);
+	const withoutPackage = (directory, glob) => {
+		if (above(directory) || !isDirectory(nodePath.join(workspace.root, directory))) return;
+		const code = unreadable(nodePath.join(workspace.root, directory));
+		return code === void 0 ? {
+			rule: "directory-without-package",
+			file: directory,
+			line: 1,
+			column: 0,
+			message: `${directory} matches the workspaces glob ${glob} but has no package.json, so no package owns what it holds and nothing in it is checked: make it a package, remove it, or add ${directory}/** to ignore`,
+			target: directory
+		} : unreadablePathFinding(directory, code);
+	};
+	const dotDirectory = (directory) => ({
+		rule: "directory-without-package",
+		file: directory,
+		line: 1,
+		column: 0,
+		message: `${directory} is a dot directory, which workspaces globs never match, so it is no package${existsSync(nodePath.join(workspace.root, directory, "package.json")) ? " though it has a package.json" : ""} and nothing in it is checked: rename it, list it in workspaces by its full path, remove it, or add ${directory}/** to ignore`,
+		target: directory
+	});
+	const pending = [
+		...unlisted.unreadable.map(({ directory, code }) => ({
+			path: directory,
+			finding: () => unreadablePathFinding(directory, code)
+		})),
+		...[...candidates].map(([directory, glob]) => ({
+			path: directory,
+			finding: () => withoutPackage(directory, glob)
+		})),
+		...unlisted.dotDirectories.map((directory) => ({
+			path: directory,
+			finding: () => dotDirectory(directory)
+		})),
+		...unlisted.links.map((link) => ({
+			path: link,
+			finding: () => isFile(nodePath.join(workspace.root, link)) ? void 0 : symbolicLinkFinding(link, linkDestination(nodePath.join(workspace.root, link)))
+		}))
+	].toSorted((left, right) => left.path.split("/").length - right.path.split("/").length || left.path.localeCompare(right.path));
+	const findings = /* @__PURE__ */ new Map();
+	for (const { path, finding } of pending) {
+		const reportedAbove = [...findings.keys()].some((reported) => path.startsWith(`${reported}/`));
+		if (findings.has(path) || inside(path) || leftOut(path) || reportedAbove) continue;
+		const made = finding();
+		if (made !== void 0) findings.set(path, made);
+	}
+	return [...findings.values()].toSorted((left, right) => left.file.localeCompare(right.file));
+};
+/**
+* Tarjan's strongly connected components, iterative so that a long chain of packages cannot exhaust the stack. The
+* search starts from `roots` in order and follows each node's `successors` in order, so components and routes are
+* deterministic.
+*/
+const stronglyConnectedComponents = (roots, successors) => {
+	const index = /* @__PURE__ */ new Map();
+	const lowLink = /* @__PURE__ */ new Map();
+	const stack = [];
+	const onStack = /* @__PURE__ */ new Set();
+	const frames = [];
+	const pathPosition = /* @__PURE__ */ new Map();
+	const components = [];
+	const routes = [];
+	const enter = (name) => {
+		const order = index.size;
+		index.set(name, order);
+		lowLink.set(name, order);
+		stack.push(name);
+		onStack.add(name);
+		pathPosition.set(name, frames.length);
+		frames.push({
+			name,
+			next: 0
+		});
+	};
+	for (const root of roots) {
+		if (index.has(root)) continue;
+		enter(root);
+		for (let frame = frames.at(-1); frame !== void 0; frame = frames.at(-1)) {
+			const target = (successors.get(frame.name) ?? [])[frame.next];
+			if (target !== void 0) {
+				frame.next += 1;
+				if (!index.has(target)) enter(target);
+				else if (onStack.has(target)) {
+					lowLink.set(frame.name, Math.min(lowLink.get(frame.name) ?? 0, index.get(target) ?? 0));
+					const position = pathPosition.get(target);
+					if (position !== void 0) routes.push([...frames.slice(position).map((onPath) => onPath.name), target]);
+				}
+				continue;
+			}
+			frames.pop();
+			pathPosition.delete(frame.name);
+			const link = lowLink.get(frame.name) ?? 0;
+			if (link === index.get(frame.name)) {
+				const component = [];
+				for (let member = stack.pop(); member !== void 0; member = member === frame.name ? void 0 : stack.pop()) {
+					onStack.delete(member);
+					component.push(member);
+				}
+				components.push(component);
+			}
+			const parent = frames.at(-1);
+			if (parent !== void 0) lowLink.set(parent.name, Math.min(lowLink.get(parent.name) ?? 0, link));
+		}
+	}
+	return {
+		components,
+		routes
+	};
+};
+/**
+* Cycles between workspace packages through their runtime dependency fields. Every route the search closes is a
+* finding, once per set of packages, starting at the package the search reached first; so a component with several
+* cycles can have several findings.
+*/
+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 findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const cycle of stronglyConnectedComponents([...edges.keys()].toSorted(), edges).routes) {
+		const key = cycle.slice(0, -1).toSorted().join(" ");
+		if (!seen.has(key)) {
+			seen.add(key);
+			const first = cycle[0] ?? "";
+			findings.push({
+				rule: "package-cycle",
+				file: `${workspace.byName.get(first)?.directory ?? first}/package.json`,
+				line: 1,
+				column: 0,
+				message: `dependency cycle: ${cycle.join(" -> ")}`,
+				target: key
+			});
+		}
+	}
+	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. */
+/**
+* Every source file the engine reads, found by walking each package's directory (skipping `node_modules` and `.git`;
+* other dot directories hold sources too). 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. A symbolic link is never followed:
+* every one is a finding, whatever it points at, unless it lies in a directory the check skips on purpose; and so is a
+* directory the walk cannot list.
+*/
+const walkSources = (engine) => {
+	const files = /* @__PURE__ */ new Set();
+	const findings = /* @__PURE__ */ new Map();
+	const { root } = engine.workspace;
+	const walk = (relative) => {
+		let entries;
+		try {
+			entries = readdirSync(nodePath.join(root, relative), { withFileTypes: true });
+		} catch (cause) {
+			if (!skipsDirectory(engine, relative)) findings.set(relative, unreadablePathFinding(relative, codeOf(cause)));
+			return;
+		}
+		for (const entry of entries) {
+			const path = `${relative}/${entry.name}`;
+			if (entry.isDirectory()) {
+				if (!passedOver(entry.name)) walk(path);
+			} else if (entry.isSymbolicLink()) {
+				if (reportsLink(engine, path)) findings.set(path, symbolicLinkFinding(path, linkDestination(nodePath.join(root, path))));
+			} else if (entry.isFile() && reads(engine, path)) files.add(path);
+		}
+	};
+	for (const entry of engine.workspace.packages) walk(entry.directory);
+	return {
+		files: [...files].toSorted(),
+		findings: [...findings.values()].toSorted((left, right) => left.file.localeCompare(right.file))
+	};
+};
+/** The source files `walkSources` finds. */
+const listSourceFiles = (engine) => [...walkSources(engine).files];
+const checkWorkspace = (root, config) => {
+	const engine = createEngine(root, config);
+	const { files, findings: walked } = walkSources(engine);
+	const perFile = files.flatMap((file) => {
+		const text = attempt(() => readFileSync(nodePath.join(root, file), "utf8"));
+		return text.ok ? findingsForFile(engine, file, text.value) : [unreadablePathFinding(file, codeOf(text.error), "file")];
+	}).filter((finding) => finding.rule !== "package-without-kind");
+	const all = [
+		...walked,
+		...perFile,
+		...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 { graphFindings as a, walkSources as i, formatFinding as n, staleBaseline as o, listSourceFiles as r, checkWorkspace as t };

package/dist/cli.d.mts

@@ -1,2 +1,2 @@
-import { n as Config } from "./config-ClNl5rro.mjs";
+import { n as Config } from "./config-CmWm5RyK.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-C1qSxYaL.mjs";
-import { n as formatFinding, t as checkWorkspace } from "./check-BIxs2Gr0.mjs";
+import { y as findWorkspaceRoot } from "./engine-DmECSDnu.mjs";
+import { n as formatFinding, t as checkWorkspace } from "./check-BbeuFBNh.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import nodePath from "node:path";
 import process from "node:process";

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

@@ -33,7 +33,7 @@ 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"];
+declare const ruleNames: readonly ["unknown-workspace-package", "package-without-kind", "package-outside-workspace", "directory-without-package", "invalid-package", "symbolic-link", "unreadable-path", "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 {
@@ -113,6 +113,7 @@ interface ResolvedConfig {
 declare const defaultFileClasses: readonly FileClass[];
 /** Identity, for type checking a configuration file. */
 declare const defineConfig: (config: Config) => Config;
+/** Problems that make a configuration unusable, as messages: the outline's alone when it does not hold, else every other. */
 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 };