@effected/workspaces 0.32.1 → 0.33.0

package/ImportGraph.js

@@ -0,0 +1,525 @@
+import { WorkspaceDiscovery } from "./WorkspaceDiscovery.js";
+import { isIdentifierChar, lex, locate, specifierLiterals, wordEndingAt } from "./internal/sourceText.js";
+import { isTypePositionImport } from "./internal/importPosition.js";
+import { DEFAULT_EXTENSIONS, walkSources } from "./internal/sourceWalk.js";
+import { SourceBoundary } from "./SourceBoundary.js";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { GlobSet } from "@effected/glob";
+
+//#region src/ImportGraph.ts
+/**
+* The entries list named no file to start from, so a walk would prove nothing.
+*
+* @public
+*/
+var NoEntriesError = class extends Schema.TaggedError()("NoEntriesError", { 
+/** The root the walk would have reported against. */
+root: Schema.String }) {
+	/** Renders the root into a one-line message. */
+	get message() {
+		return `No entries to walk under "${this.root}": a walk of nothing proves nothing`;
+	}
+};
+/**
+* An entry named a file no resolution candidate could find. The walk fails
+* rather than starting from nothing: a typo'd entry must never read as clean.
+*
+* @public
+*/
+var EntryNotFoundError = class extends Schema.TaggedError()("EntryNotFoundError", {
+	/** The entry, verbatim. */
+	entry: Schema.String,
+	/** The root it was resolved against. */
+	root: Schema.String
+}) {
+	/** Renders the entry and root into a one-line message. */
+	get message() {
+		return `Entry "${this.entry}" resolves to no file under "${this.root}"`;
+	}
+};
+/**
+* One relative import no file candidate resolved: a link of the graph the
+* walk could not follow, so whatever it would have reached is unproven.
+*
+* @public
+*/
+var UnresolvedImport = class extends Schema.Class("UnresolvedImport")({
+	/** The importing file, relative to the root, with `/` separators. */
+	file: Schema.String,
+	/** The specifier, verbatim. */
+	specifier: Schema.String
+}) {
+	/** `file specifier`, the form an assertion message reads best in. */
+	get label() {
+		return `${this.file} ${this.specifier}`;
+	}
+};
+/**
+* One forbidden import a walk from the entries reached.
+*
+* @public
+*/
+var ReachOffence = class extends Schema.Class("ReachOffence")({
+	/** The importing file, relative to the root, with `/` separators. */
+	file: Schema.String,
+	/** The 1-based line. */
+	line: Schema.Number,
+	/** The 1-based column, in UTF-16 code units. */
+	column: Schema.Number,
+	/** The forbidden specifier, verbatim. */
+	specifier: Schema.String,
+	/**
+	* The files the walk took from an entry to `file`, entry first and `file`
+	* last, each relative to the root with `/` separators. Breadth-first, so
+	* this is a shortest chain; it is the chain the walk first reached `file`
+	* by, and a file is visited once whatever else reaches it.
+	*/
+	chain: Schema.Array(Schema.String)
+}) {
+	/** `file:line:column specifier via chain`, the form an assertion message reads best in. */
+	get label() {
+		return `${this.file}:${this.line}:${this.column} ${this.specifier} via ${this.chain.join(" -> ")}`;
+	}
+};
+/**
+* What a reachability walk read and found.
+*
+* @public
+*/
+var ReachabilityScan = class extends Schema.Class("ReachabilityScan")({
+	/**
+	* Every file the walk reached, entries included, relative to the root with
+	* `/` separators, sorted. Assert it is non-empty: a walk that reached
+	* nothing proves nothing.
+	*/
+	files: Schema.Array(Schema.String),
+	/**
+	* Every relative specifier no file candidate resolved, one per
+	* file-and-specifier pair, sorted by file then specifier. Assert it is
+	* empty, or exactly the generated files you expect: an unresolved link is
+	* a part of the graph the walk could not prove anything about.
+	*/
+	unresolved: Schema.Array(UnresolvedImport),
+	/** Every forbidden import the walk reached, sorted by file, then line, then column. */
+	offences: Schema.Array(ReachOffence)
+}) {
+	/** One `file:line:column specifier via chain` label per offence: `[]` means the entries reach nothing forbidden. */
+	get violations() {
+		return this.offences.map((offence) => offence.label);
+	}
+};
+/**
+* One runtime import the owning package's manifest does not declare.
+*
+* @public
+*/
+var UndeclaredImport = class extends Schema.Class("UndeclaredImport")({
+	/** The name of the package that owns the importing file. */
+	package: Schema.String,
+	/** The importing file, relative to its package, with `/` separators. */
+	file: Schema.String,
+	/** The 1-based line. */
+	line: Schema.Number,
+	/** The 1-based column, in UTF-16 code units. */
+	column: Schema.Number,
+	/** The specifier, verbatim. */
+	specifier: Schema.String,
+	/** The package name the specifier names: `effect` for `effect/Schema`. */
+	dependency: Schema.String
+}) {
+	/** `package file:line:column undeclared dependency`, the form an assertion message reads best in. */
+	get label() {
+		return `${this.package} ${this.file}:${this.line}:${this.column} undeclared ${this.dependency}`;
+	}
+};
+/**
+* What an undeclared-import check read and found.
+*
+* @public
+*/
+var UndeclaredScan = class extends Schema.Class("UndeclaredScan")({
+	/** Every package whose manifest the check read, sorted by name. Assert it is non-empty. */
+	packages: Schema.Array(Schema.String),
+	/**
+	* Every file the check read, relative to the workspace root with `/`
+	* separators, sorted. Each file appears once, listed under its innermost
+	* package even when a wider package's glob also walked it. Assert it is
+	* non-empty: a check that read no file proves nothing, and a mistyped
+	* `include` shows up here.
+	*/
+	files: Schema.Array(Schema.String),
+	/** Every undeclared runtime import, sorted by package, then file, then line, then column. */
+	undeclared: Schema.Array(UndeclaredImport)
+}) {
+	/** One `package file:line:column undeclared dependency` label per import: `[]` means every runtime import is declared. */
+	get violations() {
+		return this.undeclared.map((entry) => entry.label);
+	}
+};
+/** The runtime sources an undeclared check reads when the caller names none. */
+const DEFAULT_INCLUDE = ["src/**"];
+/** A compiled or source extension a specifier may carry, which resolution swaps for the candidates. */
+const COMPILED_EXTENSION = /\.(?:[cm]?js|[cm]?ts|jsx|tsx)$/u;
+/** Any URL-style scheme (`node:`, `http:`), which is never a package specifier. */
+const SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:/u;
+const SPACE = /\s/;
+const byCodeUnit = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const byPosition = (a, b) => byCodeUnit(a.file, b.file) || a.line - b.line || a.column - b.column;
+/** Whether the specifier is a bare package specifier: not relative, not absolute, not a subpath import, not a URL. */
+const isBare = (specifier) => !specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.startsWith("#") && !SCHEME.test(specifier);
+/**
+* The package name a bare specifier names (`effect/Schema` → `effect`,
+* `@org/pkg/x` → `@org/pkg`), or `undefined` for anything that is not one.
+*/
+const packageNameOf = (specifier) => {
+	if (!isBare(specifier)) return void 0;
+	const segments = specifier.split("/");
+	if (specifier.startsWith("@")) return segments.length >= 2 && segments[1] !== "" ? `${segments[0]}/${segments[1]}` : void 0;
+	const name = segments[0] ?? "";
+	return name === "" ? void 0 : name;
+};
+/**
+* The offset just past the `import` or `export` keyword opening the statement
+* the `from` starting at `from` belongs to, walking back over the code view;
+* `undefined` when a `;` or the start of the file comes first, which reads as
+* runtime — the conservative side.
+*/
+const statementStart = (code, from) => {
+	let j = from - 1;
+	while (j >= 0) {
+		const char = code[j] ?? "";
+		if (char === ";") return void 0;
+		if (isIdentifierChar(char)) {
+			let start = j;
+			while (start >= 0 && isIdentifierChar(code[start])) start--;
+			const word = code.slice(start + 1, j + 1);
+			if (word === "import" || word === "export") return j + 1;
+			j = start;
+			continue;
+		}
+		j--;
+	}
+};
+/**
+* Whether the specifier at `literal` sits in a type-only import or re-export
+* (`import type { X } from`, `export type * from`) or in a type-position
+* `import()`, which the compiler erases and so never needs a runtime
+* dependency. A side-effect import, a runtime dynamic `import()`, a
+* `require()` and an `import { type X }` binding list all load at runtime and
+* are not type-only.
+*/
+const isTypeOnly = (code, literal) => {
+	let j = literal.start - 1;
+	while (j >= 0 && SPACE.test(code[j] ?? "")) j--;
+	if (code[j] === "(") return isTypePositionImport(code, j);
+	if (wordEndingAt(code, j) !== "from") return false;
+	let k = j;
+	while (k >= 0 && isIdentifierChar(code[k])) k--;
+	const start = statementStart(code, k + 1);
+	if (start === void 0) return false;
+	let m = start;
+	while (m < code.length && SPACE.test(code[m] ?? "")) m++;
+	let e = m;
+	while (e < code.length && isIdentifierChar(code[e])) e++;
+	if (code.slice(m, e) !== "type") return false;
+	let n = e;
+	while (n < code.length && SPACE.test(code[n] ?? "")) n++;
+	const next = code[n] ?? "";
+	if (next === "{" || next === "*") return true;
+	if (!isIdentifierChar(next)) return false;
+	let w = n;
+	while (w < code.length && isIdentifierChar(code[w])) w++;
+	if (code.slice(n, w) !== "from") return true;
+	let p = w;
+	while (p < code.length && SPACE.test(code[p] ?? "")) p++;
+	if (code[p] === "=") return true;
+	let q = p;
+	while (q < code.length && isIdentifierChar(code[q])) q++;
+	return code.slice(p, q) === "from";
+};
+/**
+* The static prefix of a glob: the text before its first pattern character,
+* cut back to the last `/`, so `src/**` walks `src` and a leading `**` walks
+* everything. Over-cutting is safe — the glob still filters every file — so
+* every character any glob syntax could treat as special cuts.
+*/
+const globPrefix = (pattern) => {
+	const at = pattern.search(/[*?[{\]()!|@]/u);
+	const prefix = at === -1 ? pattern : pattern.slice(0, at);
+	const slash = prefix.lastIndexOf("/");
+	return slash === -1 ? "" : prefix.slice(0, slash);
+};
+/** The distinct walk roots a set of include globs needs, shortest first: a prefix under another walks nothing twice. */
+const includePrefixes = (patterns) => {
+	const prefixes = [...new Set(patterns.map(globPrefix))];
+	return prefixes.filter((prefix) => prefix === "" || !prefixes.some((other) => other !== prefix && prefix.startsWith(`${other}/`)));
+};
+/**
+* Import-graph checks: properties of what the imports of a set of files
+* reach, which no one-file rule can express.
+*
+* @remarks
+* {@link SourceBoundary} checks one file at a time. Two guards consumers want
+* are properties of the import graph itself:
+*
+* - {@link ImportGraph.reachability} answers "nothing reachable from entry X
+*   imports Y". A directory rule approximates that, but a refactor which adds
+*   a new static path from the root entry into an allowed directory still
+*   passes it; a reachability walk follows the real import edges and reports
+*   the chain that reaches the forbidden specifier.
+* - {@link ImportGraph.undeclared} answers "every runtime import is
+*   declared". Workspace hoisting resolves an import of a package the
+*   manifest never declared, and only a packed install catches that today —
+*   far too slow for the edit loop. This check is static and fast: each
+*   package's literal specifiers against its own `dependencies`,
+*   `peerDependencies` and `optionalDependencies`.
+*
+* Both are static analysis of literal specifiers: static imports,
+* re-exports, and `import()`/`require()` calls whose argument is one string
+* literal. There is no dynamic-import guarantee: a computed specifier
+* (`import("./ui/" + name)`) is invisible to both, and a packed install
+* (`PackedInstall`) remains the proof of what actually resolves at
+* runtime. Both reuse the `SourceBoundary` lexer, so a specifier in a
+* comment, a string, template text or a regex body is never an import, and
+* both refuse to pass vacuously: every result reports what it read.
+*
+* @example
+* ```ts
+* import { NodeServices } from "@effect/platform-node";
+* import { ImportGraph } from "@effected/workspaces/testing";
+* import { Effect } from "effect";
+*
+* // Nothing reachable from the root entry may import ink or react.
+* const walk = ImportGraph.reachability({
+*   root: "/repo/packages/ui/src",
+*   entries: ["index.ts"],
+*   forbid: ["ink", "react"],
+* }).pipe(Effect.provide(NodeServices.layer));
+* ```
+*
+* @public
+*/
+var ImportGraph = class {
+	constructor() {}
+	/**
+	* Walk the import graph from `entries` through relative imports and report
+	* every forbidden specifier a reached file imports.
+	*
+	* @remarks
+	* The walk is breadth-first, so a violation's chain is a shortest path
+	* from an entry, and each file is visited once through its `realPath`, so
+	* a symlink loop terminates and a diamond reports one chain. The walk is
+	* conservative: it follows every literal specifier, type-only imports
+	* included, so a forbidden import only a type reaches is still reported.
+	* A bare specifier is checked against `forbid` — the same matcher
+	* `SourceBoundary.check` uses — but only walked into when `followPackage`
+	* names a file for it. A relative specifier that resolves to no file is
+	* reported in `unresolved`, never dropped: the part of the graph behind it
+	* is unproven.
+	*/
+	static reachability = Effect.fn("ImportGraph.reachability")(function* (options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		if (options.entries.length === 0) return yield* Effect.fail(NoEntriesError.make({ root: options.root }));
+		const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+		const posix = (relative) => relative.split(path.sep).join("/");
+		/** The first candidate that exists as a file, or none. */
+		const firstFile = (candidates) => Effect.gen(function* () {
+			for (const candidate of candidates) if (yield* fs.exists(candidate)) {
+				if ((yield* fs.stat(candidate)).type === "File") return Option.some(candidate);
+			}
+			return Option.none();
+		});
+		/** Every file a specifier could name: itself, its stem under each extension, and each extension's index. */
+		const candidatesOf = (target) => {
+			const stem = target.replace(COMPILED_EXTENSION, "");
+			const candidates = [target];
+			for (const extension of extensions) candidates.push(stem + extension, path.join(stem, `index${extension}`));
+			return candidates;
+		};
+		/** An entry or a `followPackage` answer as an absolute path: absolute stays, relative joins under the root. */
+		const absolute = (given) => path.isAbsolute(given) ? given : path.join(options.root, ...given.split("/"));
+		const files = [];
+		const offences = [];
+		const unresolved = [];
+		const reportedUnresolved = /* @__PURE__ */ new Set();
+		const visited = /* @__PURE__ */ new Set();
+		const queue = [];
+		const recordUnresolved = (file, specifier) => {
+			const key = `${file}\u0000${specifier}`;
+			if (reportedUnresolved.has(key)) return;
+			reportedUnresolved.add(key);
+			unresolved.push(UnresolvedImport.make({
+				file,
+				specifier
+			}));
+		};
+		for (const entry of options.entries) {
+			const found = yield* firstFile(candidatesOf(absolute(entry)));
+			if (Option.isNone(found)) return yield* Effect.fail(EntryNotFoundError.make({
+				entry,
+				root: options.root
+			}));
+			const file = posix(path.relative(options.root, found.value));
+			queue.push({
+				full: found.value,
+				file,
+				chain: [file]
+			});
+		}
+		for (let i = 0; i < queue.length; i++) {
+			const current = queue[i];
+			if (current === void 0) continue;
+			const real = yield* fs.realPath(current.full);
+			if (visited.has(real)) continue;
+			visited.add(real);
+			files.push(current.file);
+			const text = yield* fs.readFileString(current.full);
+			for (const offence of SourceBoundary.check(current.file, text, [{ forbidImports: options.forbid }])) offences.push(ReachOffence.make({
+				file: offence.file,
+				line: offence.line,
+				column: offence.column,
+				specifier: offence.detail,
+				chain: [...current.chain]
+			}));
+			for (const specifier of SourceBoundary.importSpecifiers(text)) {
+				let target;
+				if (specifier.startsWith(".")) target = path.resolve(path.dirname(current.full), specifier);
+				else if (options.followPackage !== void 0 && isBare(specifier)) {
+					const mapped = options.followPackage(specifier);
+					if (mapped === void 0) continue;
+					target = absolute(mapped);
+				} else continue;
+				const found = yield* firstFile(candidatesOf(target));
+				if (Option.isNone(found)) {
+					recordUnresolved(current.file, specifier);
+					continue;
+				}
+				const file = posix(path.relative(options.root, found.value));
+				queue.push({
+					full: found.value,
+					file,
+					chain: [...current.chain, file]
+				});
+			}
+		}
+		return ReachabilityScan.make({
+			files: files.sort(byCodeUnit),
+			unresolved: unresolved.sort((a, b) => byCodeUnit(a.file, b.file) || byCodeUnit(a.specifier, b.specifier)),
+			offences: offences.sort(byPosition)
+		});
+	});
+	/**
+	* Check every workspace package's runtime sources for imports its own
+	* manifest does not declare.
+	*
+	* @remarks
+	* For each discovered package, reads the files its `include` globs name
+	* (`src/**` by default) and compares every runtime specifier against the
+	* package's `dependencies`, `peerDependencies` and `optionalDependencies`.
+	* `devDependencies` never declares: an import of one from a runtime source
+	* is exactly the hoisting bug this check exists for. `optionalDependencies`
+	* does declare: npm and pnpm install one by default, so a packed install
+	* resolves the import. A relative,
+	* absolute, `#`-subpath or URL-scheme specifier is never a package import;
+	* a `node:` specifier is always a built-in, and a bare built-in is one only
+	* when `builtins` lists it. A package importing its own name (a
+	* self-reference through `exports`) is declared by definition. A file
+	* under two discovered packages (a nested package under the root) is
+	* checked against its innermost package's manifest only, so a root-wide
+	* `include` never double-reports it. Type-only imports are erased by the
+	* compiler and never flagged: `import type { X } from`, `export type`
+	* re-exports, and an `import()` in a type position (`typeof import("x")`,
+	* an annotation, a type alias right-hand side, a generic argument). The
+	* position is judged by the construct enclosing the call, not by the one
+	* token before it, so a runtime `import("x")` in a typed initializer, an
+	* object literal, a ternary branch or a call argument counts like any
+	* static import. One `import type from "x"` is runtime too — TypeScript
+	* reads it as a default import of a binding named `type`. What the static
+	* pass cannot see — a computed specifier — only `PackedInstall` proves.
+	*/
+	static undeclared = Effect.fn("ImportGraph.undeclared")(function* (options = {}) {
+		const discovery = yield* WorkspaceDiscovery;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const include = options.include ?? DEFAULT_INCLUDE;
+		const globs = yield* GlobSet.compile(include);
+		const prefixes = includePrefixes(include);
+		const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+		const builtins = new Set(options.builtins ?? []);
+		const packages = yield* discovery.listPackages();
+		/**
+		* Whether `file` sits under the directory `dir`: the relative path from
+		* `dir` to `file` stays inside it. A drive or root mismatch surfaces as
+		* an absolute relative path and reads as not under.
+		*/
+		const under = (file, dir) => {
+			const rel = path.relative(dir, file);
+			return rel !== "" && rel !== "." && !path.isAbsolute(rel) && !rel.startsWith(`..${path.sep}`);
+		};
+		/**
+		* The innermost package owning `file`, or `undefined` when no package
+		* contains it. Every file belongs to one package — the deepest one — so
+		* a glob that walks a nested package never checks that package's files
+		* against the outer manifest.
+		*/
+		const ownerOf = (file) => {
+			let owner;
+			for (const candidate of packages) {
+				if (!under(file, candidate.path)) continue;
+				if (owner === void 0 || under(candidate.path, owner.path)) owner = candidate;
+			}
+			return owner;
+		};
+		const names = [];
+		const files = [];
+		const undeclared = [];
+		for (const pkg of packages) {
+			names.push(pkg.name);
+			const declared = /* @__PURE__ */ new Set([
+				...Object.keys(pkg.dependencies),
+				...Object.keys(pkg.peerDependencies),
+				...Object.keys(pkg.optionalDependencies)
+			]);
+			const seen = /* @__PURE__ */ new Set();
+			for (const prefix of prefixes) {
+				const walkRoot = prefix === "" ? pkg.path : path.join(pkg.path, ...prefix.split("/"));
+				if (!(yield* fs.exists(walkRoot))) continue;
+				for (const source of yield* walkSources({
+					root: walkRoot,
+					extensions
+				})) {
+					if (ownerOf(source.path) !== pkg) continue;
+					const file = prefix === "" ? source.file : `${prefix}/${source.file}`;
+					if (seen.has(file) || !globs.matches(file)) continue;
+					seen.add(file);
+					files.push(pkg.relativePath === "." ? file : `${pkg.relativePath}/${file}`);
+					const text = yield* fs.readFileString(source.path);
+					const lexed = lex(text);
+					const at = locate(text);
+					for (const literal of specifierLiterals(lexed)) {
+						if (isTypeOnly(lexed.code, literal)) continue;
+						const dependency = packageNameOf(literal.value);
+						if (dependency === void 0) continue;
+						if (builtins.has(dependency) || dependency === pkg.name || declared.has(dependency)) continue;
+						undeclared.push(UndeclaredImport.make({
+							package: pkg.name,
+							file,
+							...at(literal.start),
+							specifier: literal.value,
+							dependency
+						}));
+					}
+				}
+			}
+		}
+		return UndeclaredScan.make({
+			packages: names.sort(byCodeUnit),
+			files: files.sort(byCodeUnit),
+			undeclared: undeclared.sort((a, b) => byCodeUnit(a.package, b.package) || byCodeUnit(a.file, b.file) || byPosition(a, b))
+		});
+	});
+};
+
+//#endregion
+export { EntryNotFoundError, ImportGraph, NoEntriesError, ReachOffence, ReachabilityScan, UndeclaredImport, UndeclaredScan, UnresolvedImport };

package/README.md

@@ -272,7 +272,7 @@ Windows correctness is therefore the operations you pass, and nothing else. Both
 
 ## Repo-shape checks (`@effected/workspaces/testing`)
 
-A monorepo's shape drifts in ways no unit test sees: a package that should stay platform-free starts reading `process`, a low-level package grows an edge up into an application, or a bin resolves fine inside the workspace and is missing once installed from its tarball. The `@effected/workspaces/testing` subpath holds three checks you run from your own test suite to catch each one. The main entry never re-exports it, so a consumer of `.` never loads a scanner or package-manager orchestration it does not use.
+A monorepo's shape drifts in ways no unit test sees: a package that should stay platform-free starts reading `process`, a root entry grows a static path into a module it must never load, an import resolves only because the workspace hoists it, a low-level package grows an edge up into an application, or a bin resolves fine inside the workspace and is missing once installed from its tarball. The `@effected/workspaces/testing` subpath holds four checks you run from your own test suite to catch each one. The main entry never re-exports it, so a consumer of `.` never loads a scanner or package-manager orchestration it does not use.
 
 Every check refuses to pass vacuously, so every example below pairs "nothing wrong" with "something was checked".
 
@@ -408,6 +408,58 @@ The scanner is a lexer, not a type checker. Its known limits:
 - JSX text reads as code, which is why `.tsx` and `.jsx` are not scanned by default.
 - `forbidImports: ["node:*"]` matches only the `node:` spelling, not a bare `"fs"`. To forbid both, spread Node's list in the test file: `{ forbidImports: ["node:*", ...builtinModules] }`, with `builtinModules` from `node:module`. That also forbids npm packages named like a built-in (`events`, `buffer`).
 
+### Import graph
+
+Two guards are properties of the import graph rather than of one file, so no per-file rule can express them. `ImportGraph.reachability` walks from entry files through relative imports and reports every forbidden specifier a reached file imports, with the chain of files that reaches it. A directory rule approximates reachability, but a refactor that keeps the rule and adds a new static path from the root entry into the allowed directory passes it; the walk follows the real edges. `ImportGraph.undeclared` reports every runtime import whose package the owning package's manifest does not declare in `dependencies`, `peerDependencies` or `optionalDependencies` — what workspace hoisting hides and only a packed install caught before, far too slow for the edit loop.
+
+```ts
+// __test__/graph.test.ts, one level below the workspace root
+import { builtinModules } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { NodeServices } from "@effect/platform-node";
+import { assert, describe, layer } from "@effect/vitest";
+import { Workspaces } from "@effected/workspaces";
+import { ImportGraph } from "@effected/workspaces/testing";
+import { Effect, Layer } from "effect";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const Live = Workspaces.layer({ cwd: ROOT }).pipe(Layer.provideMerge(NodeServices.layer));
+
+describe("import graph", () => {
+  layer(Live)((it) => {
+    it.effect("nothing reachable from the root entry loads ink or react", () =>
+      Effect.gen(function* () {
+        const walk = yield* ImportGraph.reachability({
+          root: join(ROOT, "packages/ui/src"),
+          entries: ["index.ts"],
+          forbid: ["ink", "react"],
+        });
+        assert.isNotEmpty(walk.files, "the walk reached the tree");
+        assert.deepStrictEqual(walk.unresolved, [], "every relative import resolved");
+        assert.deepStrictEqual(walk.violations, []);
+      }),
+    );
+
+    it.effect("every runtime import is declared", () =>
+      Effect.gen(function* () {
+        const scan = yield* ImportGraph.undeclared({ builtins: builtinModules });
+        assert.isNotEmpty(scan.files, "the check read sources");
+        assert.deepStrictEqual(scan.violations, []);
+      }),
+    );
+  });
+});
+```
+
+A violation names the path that reaches it: `src/ui/ink.ts:1:24 ink via index.ts -> ui/shell.ts -> src/ui/ink.ts`. An undeclared import names the package, the file and the specifier: `@my-org/app src/main.ts:7:21 undeclared left-pad`.
+
+The walk is breadth-first, visits each file once through its realpath — a symlink loop terminates, a diamond reports one shortest chain — and it is conservative: it follows every literal specifier, type-only imports included, so a forbidden import only a type reaches is still reported. A relative import that resolves to no file lands in `unresolved`, never dropped silently: the graph behind it is unproven, so assert `unresolved` is empty or exactly the generated files you expect. An entry that resolves to no file fails `EntryNotFoundError`, and an empty entry list fails `NoEntriesError`: the walk never proves nothing silently. `followPackage` is the extension point for workspace-package traversal: it is called with each bare specifier and answers the file to continue from, or `undefined` to stop there; a stale mapping lands in `unresolved` too.
+
+The undeclared check counts `dependencies`, `peerDependencies` and `optionalDependencies` as declared, and never `devDependencies`: an import of one from a runtime source is exactly the bug. An `optionalDependency` does declare — npm and pnpm install one by default, so a packed install resolves the import. It never flags a `node:` specifier, a relative or absolute specifier, a `#` subpath import, or a package's self-reference through its own name. A bare built-in is flagged unless the caller lists it: spread `builtinModules` from `node:module` in the test file, since no built-in list ships here — one would drift with Node releases, the same convention `forbidImports` uses. Type-only imports are erased by the compiler and never flagged: `import type { X } from`, `export type` re-exports, and an `import()` in a type position (`typeof import("x")`, an annotation, a type alias right-hand side, a generic argument). The position is judged by the construct enclosing the call rather than by the one token before it, so a runtime `import("x")` in a typed initializer, an object literal, a ternary branch or a call argument is still reported. One `import type from "x"` is not type-only — TypeScript reads it as a runtime default import of a binding named `type`. `include` globs (default `src/**`, matched against the package-relative path) name the runtime sources; each package is walked from each glob's static prefix, so a build output or a test directory is never walked under the default, and test files importing devDependencies are out of scope by design. A file under two discovered packages belongs to its innermost one: a root-wide glob like `["**/*.ts"]` walks the whole repository, but a nested package's files are checked only against that package's manifest, and each file is listed once.
+
+Both checks are static analysis of literal specifiers — there is no dynamic-import guarantee: a computed specifier (`import("./ui/" + name)`) is invisible — and `PackedInstall` remains the proof of what actually resolves at runtime. Both reuse the `SourceBoundary` lexer, so a specifier in a comment, a string, template text or a regex body is never an import.
+
 ### Packed install
 
 `PackedInstall.run` packs a carrier and every workspace package it needs, then installs the carrier into a fresh project outside the workspace under each package manager that answers `--version`, and checks every expected bin is linked and executable. It carries the traps each manager sets: the parent run's `npm_*` and `pnpm_config_*` context is scrubbed, pnpm's overrides go in `pnpm-workspace.yaml`, Yarn Berry gets the `node-modules` linker, `packageManager` is pinned to the probed version, and lifecycle scripts are skipped. By default it packs each package's built `dist/prod/npm/pkg`, the artifact a release publishes; build first.
@@ -563,7 +615,7 @@ A name miss in the derived `getPackage` fails with the service's own typed `Pack
 - `ReleaseTag` / `TrackingTag` — release-tag formatting (`ReleaseTag.single` / `.scoped`, strict SemVer by default with no `v` prefix) and the floating major/minor alias derivation GitHub Actions-style consumers expect (`v1`, `v1.2`), plus `classifyTag` to tell a release tag from a tracking alias.
 - `VersioningStrategy` — classify a workspace as `single`, `fixed-group` or `independent` from package names and fixed groups, or detect it live against `PublishabilityDetector`, and produce the release tags for a batch with `tagsFor`.
 - `findWorkspaceRootSync` / `getWorkspacePackagesSync` — the synchronous escape hatch for config-time callers that cannot await, over file and path operations you supply.
-- `@effected/workspaces/testing` — a third entry point holding the repo-shape checks: `WorkspaceLayering` and `LayerPolicy` (the package graph against a committed `layers.json`), `SourceBoundary` (a lexer-backed scanner for `process` reads, forbidden imports and console writes, with shipped positive controls) and `PackedInstall` (the carrier's bins installed from packed tarballs under every available package manager).
+- `@effected/workspaces/testing` — a third entry point holding the repo-shape checks: `WorkspaceLayering` and `LayerPolicy` (the package graph against a committed `layers.json`), `SourceBoundary` (a lexer-backed scanner for `process` reads, forbidden imports and console writes, with shipped positive controls), `ImportGraph` (the two import-graph checks: reachability from entry files to a forbidden specifier, with the chain that reaches it, and undeclared runtime imports against each package's manifest) and `PackedInstall` (the carrier's bins installed from packed tarballs under every available package manager).
 - `@effected/workspaces/node-sync` — a second entry point holding the Node bindings for those operations (`nodeFileSystem`, `nodePath` and the `nodeSyncOps` bag), kept off the main entry so `node:*` never reaches a consumer that supplies its own. `nodeFileSystem` implements the optional `readDirectoryWithTypes` fast path, so the bindings enumerate a workspace in one `readdirSync` per directory.
 
 ## License