@effected/workspaces 0.25.0 → 0.27.0

package/SourceBoundary.js

@@ -0,0 +1,624 @@
+import { isIdentifierChar, lex, locate, references, specifierLiterals } from "./internal/sourceText.js";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { GlobSet } from "@effected/glob";
+
+//#region src/SourceBoundary.ts
+/**
+* One place a source file breaks a {@link BoundaryRule}.
+*
+* @public
+*/
+var Offence = class extends Schema.Class("Offence")({
+	/** The file, relative to the scanned 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 rule broken. */
+	rule: Schema.Literals([
+		"process",
+		"node:process",
+		"stdout-write",
+		"console",
+		"console-stdout",
+		"forbidImports",
+		"forbidTokens"
+	]),
+	/** What matched: the identifier, the call, the import specifier, or the token. */
+	detail: Schema.String
+}) {
+	/** `file:line:column rule detail`, the form an assertion message reads best in. */
+	get label() {
+		return `${this.file}:${this.line}:${this.column} ${this.rule} ${this.detail}`;
+	}
+};
+/**
+* What a scan read and found.
+*
+* @public
+*/
+var SourceScan = class extends Schema.Class("SourceScan")({
+	/** Every source file visited, relative to the root with `/` separators, sorted. Assert it is non-empty. */
+	files: Schema.Array(Schema.String),
+	/** The visited files an `allow` glob exempted from every rule. */
+	allowed: Schema.Array(Schema.String),
+	/** Every offence, sorted by file, then line, then column. */
+	offences: Schema.Array(Offence),
+	/**
+	* Every offence an `allowRules` glob waived, sorted like `offences`. Assert
+	* it is exactly what you meant to waive: a waiver that no longer waives
+	* anything, or waives more than intended, shows up here.
+	*/
+	waived: Schema.Array(Offence)
+}) {
+	/** One `file:line:column rule detail` label per offence: `[]` means clean. */
+	get violations() {
+		return this.offences.map((offence) => offence.label);
+	}
+};
+const DEFAULT_EXTENSIONS = [
+	".ts",
+	".mts",
+	".cts",
+	".js",
+	".mjs",
+	".cjs"
+];
+const DECLARATION = /\.d\.[cm]?ts$/;
+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;
+const EXEMPT = ["process.env.__PACKAGE_VERSION__"];
+/**
+* The console methods Node writes to stderr. nodejs.org/api/console.html has
+* `error` and `trace` print to stderr and `warn` alias `error`; it names no
+* stream for `assert`, and a probe over a `Console` built on two capturing
+* streams sent a failing `assert` to stderr. Everything else that writes
+* (`log`, `info`, `debug`, `dir`, `dirxml`, `table`, `count`, `group`,
+* `time`) writes to stdout.
+*/
+const STDERR_METHODS = /* @__PURE__ */ new Set([
+	"error",
+	"warn",
+	"trace",
+	"assert"
+]);
+const STDOUT_WRITE = /stdout\s*(?:\?\.|\.)\s*(write|end)/gu;
+/** An `end(` call that passes a final chunk, which `Writable.end` writes before closing. */
+const END_WITH_CHUNK = /^\s*\(\s*[^\s)]/u;
+/** Whether the reference at `at` is itself a member access (`globalThis.process`), which no ignore token exempts. */
+const isMemberAccess = (code, at) => {
+	let j = at - 1;
+	while (j >= 0 && /\s/.test(code[j] ?? "")) j--;
+	return code[j] === ".";
+};
+const processReads = (code, ignoreTokens) => references(code, "process").filter((at) => isMemberAccess(code, at) || !ignoreTokens.some((token) => code.startsWith(token, at) && !isIdentifierChar(code[at + token.length])));
+const stdoutWrites = (code) => [...code.matchAll(STDOUT_WRITE)].map((match) => ({
+	at: match.index ?? 0,
+	end: (match.index ?? 0) + match[0].length,
+	method: match[1] ?? "write"
+})).filter(({ at, end }) => !isIdentifierChar(code[at - 1]) && code[at - 1] !== "#" && !isIdentifierChar(code[end])).filter(({ end, method }) => method === "write" || END_WITH_CHUNK.test(code.slice(end))).map(({ at, method }) => ({
+	at,
+	method
+}));
+/** The member name directly after the reference at `at` (`console.log` → `"log"`, `console?.log` too), or `undefined` when it is not a named member access. */
+const memberAfter = (code, at, name) => {
+	let j = at + name.length;
+	while (j < code.length && /\s/.test(code[j] ?? "")) j++;
+	if (code[j] === "?" && code[j + 1] === ".") j++;
+	if (code[j] !== ".") return void 0;
+	j++;
+	while (j < code.length && /\s/.test(code[j] ?? "")) j++;
+	let end = j;
+	while (isIdentifierChar(code[end])) end++;
+	return end > j ? code.slice(j, end) : void 0;
+};
+/**
+* Every offset where `token` appears in `code` as whole text: a token that
+* starts with an identifier character must not continue one (nor follow `#`),
+* and one that ends with an identifier character must not run into another.
+*/
+const tokenOccurrences = (code, token) => {
+	if (token.length === 0) return [];
+	const guardStart = isIdentifierChar(token[0]);
+	const guardEnd = isIdentifierChar(token[token.length - 1]);
+	const found = [];
+	for (let at = code.indexOf(token); at !== -1; at = code.indexOf(token, at + 1)) {
+		if (guardStart && (isIdentifierChar(code[at - 1]) || code[at - 1] === "#")) continue;
+		if (guardEnd && isIdentifierChar(code[at + token.length])) continue;
+		found.push(at);
+	}
+	return found;
+};
+const forbids = (entry, specifier) => entry.endsWith("*") ? specifier.startsWith(entry.slice(0, -1)) : specifier === entry || specifier.startsWith(`${entry}/`);
+const isNodeModule = (specifier, module) => [module, `node:${module}`].some((name) => specifier === name || specifier.startsWith(`${name}/`));
+const FIXTURES = [
+	{
+		name: "process: destructuring",
+		source: "const { env } = process;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: bracket access",
+		source: "const env = process[\"env\"];",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: a member of globalThis",
+		source: "const cwd = globalThis.process?.cwd();",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: a template substitution",
+		source: "const where = `cwd: ${process.cwd()}`;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: after a string holding a comment opener",
+		source: "const open = \"/*\"; const argv = process.argv; const close = \"*/\";",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: after a regex holding a quote",
+		source: "const re = /\"/; const argv = process.argv; const q = \"x\";",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: after a division",
+		source: "const half = total / 2; const argv = process.argv; const r = 1 / 4;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: a comment",
+		source: "// process.exit(1)\n/* process.cwd() */",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "process: a string",
+		source: "const label = \"process.env\";",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "process: template text",
+		source: "const help = `run process.exit to quit`;",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "process: a regex literal",
+		source: "const re = /process\\.env/g;",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "process: a member of another object",
+		source: "const pid = child.process;",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "process: the build-time version constant",
+		source: "const version = process.env.__PACKAGE_VERSION__;",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "process: the version constant reached through globalThis",
+		source: "const version = globalThis.process.env.__PACKAGE_VERSION__;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: after a non-null assertion divided",
+		source: "const y = x! / 2; const a = process.argv; const b = 1 / 4;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: after a postfix increment divided",
+		source: "const y = i++ / 2; const a = process.argv; const b = 1 / 4;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: after a call divided",
+		source: "const y = f(x) / 2; const a = process.argv; const b = 1 / 4;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: after a regex that follows an if condition",
+		source: "if (x) /\\/*/.test(s);\nconst a = process.argv;\n/* c */",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: a ternary branch",
+		source: "const p = ok ? process : fallback;",
+		rule: "process",
+		flagged: true
+	},
+	{
+		name: "process: an object-literal key",
+		source: "const o = { process: 1 };",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "process: a type member",
+		source: "interface I { process?: string }",
+		rule: "process",
+		flagged: false
+	},
+	{
+		name: "node:process: a static import",
+		source: "import { env } from \"node:process\";",
+		rule: "node:process",
+		flagged: true
+	},
+	{
+		name: "node:process: a dynamic import",
+		source: "const p = await import(\"process\");",
+		rule: "node:process",
+		flagged: true
+	},
+	{
+		name: "node:process: a string that is not a specifier",
+		source: "const s = \"node:process\";",
+		rule: "node:process",
+		flagged: false
+	},
+	{
+		name: "node:process: an unrelated specifier",
+		source: "import { ChildProcess } from \"effect/unstable/process\";",
+		rule: "node:process",
+		flagged: false
+	},
+	{
+		name: "stdout-write: a direct write",
+		source: "process.stdout.write(\"x\");",
+		rule: "stdout-write",
+		flagged: true
+	},
+	{
+		name: "stdout-write: an end with a chunk",
+		source: "process.stdout.end(\"x\");",
+		rule: "stdout-write",
+		flagged: true
+	},
+	{
+		name: "stdout-write: an end without a chunk",
+		source: "process.stdout.end();",
+		rule: "stdout-write",
+		flagged: false
+	},
+	{
+		name: "stdout-write: a string",
+		source: "const s = \"stdout.write\";",
+		rule: "stdout-write",
+		flagged: false
+	},
+	{
+		name: "console: console.log",
+		source: "console.log(\"x\");",
+		rule: "console",
+		flagged: true
+	},
+	{
+		name: "console: console.error",
+		source: "console.error(e);",
+		rule: "console",
+		flagged: true
+	},
+	{
+		name: "console: the Console service",
+		source: "const current = yield* Console.Console;",
+		rule: "console",
+		flagged: false
+	},
+	{
+		name: "console-stdout: console.log",
+		source: "console.log(\"x\");",
+		rule: "console-stdout",
+		flagged: true
+	},
+	{
+		name: "console-stdout: a bare alias",
+		source: "const c = console;",
+		rule: "console-stdout",
+		flagged: true
+	},
+	{
+		name: "console-stdout: console.error",
+		source: "console.error(e);",
+		rule: "console-stdout",
+		flagged: false
+	},
+	{
+		name: "console-stdout: a stderr method through globalThis",
+		source: "globalThis.console.warn(\"x\");",
+		rule: "console-stdout",
+		flagged: false
+	},
+	{
+		name: "console-stdout: the Console service",
+		source: "const current = yield* Console.Console;",
+		rule: "console-stdout",
+		flagged: false
+	},
+	{
+		name: "forbidImports: a platform package",
+		source: "import { NodeServices } from \"@effect/platform-node\";",
+		rule: { forbidImports: ["@effect/platform*"] },
+		flagged: true
+	},
+	{
+		name: "forbidImports: a commented-out import",
+		source: "// import { NodeServices } from \"@effect/platform-node\";",
+		rule: { forbidImports: ["@effect/platform*"] },
+		flagged: false
+	},
+	{
+		name: "forbidTokens: the build-time version constant",
+		source: "export const version = process.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: true
+	},
+	{
+		name: "forbidTokens: the token reached through globalThis",
+		source: "const version = globalThis.process.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: true
+	},
+	{
+		name: "forbidTokens: a string and a comment",
+		source: "const s = \"process.env.__PACKAGE_VERSION__\"; // process.env.__PACKAGE_VERSION__",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
+	},
+	{
+		name: "forbidTokens: a longer identifier",
+		source: "const v = process.env.__PACKAGE_VERSION__X;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
+	},
+	{
+		name: "forbidTokens: the tail of a longer identifier",
+		source: "const v = xprocess.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
+	},
+	{
+		name: "forbidTokens: after a variable named of, divided",
+		source: "const of = 8; const x = of / 2; const v = process.env.__PACKAGE_VERSION__; const y = 8 / 2;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: true
+	},
+	{
+		name: "forbidTokens: a private field",
+		source: "const v = this.#process.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
+	}
+];
+/**
+* Source-text boundary checks: which files read `process`, import a forbidden
+* module, or write to stdout or the console.
+*
+* @remarks
+* Every check runs over one lexer pass that separates code from comments,
+* strings, template text and regex bodies, so `process` in prose, in a string
+* or in an embedded script's template text never counts, and a `/*` inside a
+* string never hides the code behind it. A `/` after an operand divides (an
+* identifier, `)`, `]`, a postfix `++`/`--` or a non-null `!`), while one after
+* an operator, a keyword or the `)` of an `if`/`while`/`for`/`with` condition
+* opens a regex. An object-literal key or type member named `process`
+* (`{ process: 1 }`) is not a read.
+*
+* It is a lexer, not a type checker, and these misses are known:
+*
+* - there is no scope analysis, so ANY local binding named `process` or
+*   `console` is flagged like the global: a parameter
+*   (`(process: Handle) => process.kill()`), a variable, a label, or an
+*   unannotated class field (`process = 1`). An annotated class field
+*   (`process: T`) reads as a type member and is spared. Prefer renaming the
+*   binding; otherwise waive that one rule for the file with an
+*   `allowRules` glob, which leaves every other rule in force and reports
+*   what it waived. An `allow` glob exempts the file from every rule;
+*
+* - a computed access through a string key (`globalThis["process"]`) and a
+*   destructuring of a global (`const { process: p } = globalThis`) are not seen;
+*
+* - a regex literal directly after a block-closing `}` reads as a division, so
+*   a quote or `/*` inside it can hide the code after it;
+*
+* - JSX text reads as code;
+*
+* - a variable named `yield` or `await` in a sloppy-mode script reads as the
+*   keyword, so a `/` after it opens a regex (module and strict code reserve
+*   both words);
+*
+* - `forbidImports: ["node:*"]` does not catch a bare built-in such as
+*   `"fs"` (see {@link BoundaryRule}).
+*
+* Assert on {@link SourceBoundary.verifyFixtures} beside your own scan: it
+* proves the scanner you are trusting still flags what it must and spares
+* what it must.
+*
+* @example
+* ```ts
+* import { SourceBoundary } from "@effected/workspaces/testing";
+*
+* const offences = SourceBoundary.check("src/a.ts", "const { env } = process;", ["process"]);
+* const clean = SourceBoundary.verifyFixtures().length === 0;
+* console.log(offences.map((offence) => offence.label), clean);
+* // => [ 'src/a.ts:1:17 process process' ] true
+* ```
+*
+* @public
+*/
+var SourceBoundary = class SourceBoundary {
+	constructor() {}
+	/** `text` with every comment blanked to spaces; strings, templates and regexes untouched, length and line breaks kept. */
+	static stripComments = (text) => lex(text).withoutComments;
+	/** Whether `text` reads the global `process` in code (see {@link BoundaryRule}). */
+	static referencesProcess = (text, options) => processReads(lex(text).code, [...EXEMPT, ...options?.ignoreTokens ?? []]).length > 0;
+	/** Every module specifier `text` imports: static, side-effect, re-export, type-only, `import(...)` with a literal, and `require(...)`. */
+	static importSpecifiers = (text) => specifierLiterals(lex(text)).map((literal) => literal.value);
+	/** Whether `text` imports the Node built-in `module`, in either its `node:` or bare form. */
+	static importsNode = (text, module) => SourceBoundary.importSpecifiers(text).some((specifier) => isNodeModule(specifier, module));
+	/**
+	* Every place `text` breaks one of `rules`, in source order, attributed to `file`.
+	*
+	* @remarks
+	* A `{ forbidTokens }` entry matches its exact text in code only: comments,
+	* strings, template text and regex bodies are blanked first, so a token that
+	* itself contains a string literal never matches, and whitespace inside a
+	* token must match byte for byte. A token that starts with an identifier
+	* character does not match inside a longer identifier or after `#`, and one
+	* that ends with one does not match when an identifier character follows.
+	* A member access is still a match: `globalThis.process.env.X` contains the
+	* token `process.env.X`. A token listed twice is reported once. A token with
+	* no identifier character at either end (`"=>"`, `"?."`) has no edge guard,
+	* so it matches inside longer punctuation, and consecutive matches of it can
+	* overlap.
+	*/
+	static check = (file, text, rules, options) => {
+		const lexed = lex(text);
+		const at = locate(text);
+		const specifiers = specifierLiterals(lexed);
+		const found = [];
+		for (const rule of rules) if (rule === "process") for (const offset of processReads(lexed.code, [...EXEMPT, ...options?.ignoreTokens ?? []])) found.push({
+			offset,
+			rule,
+			detail: "process"
+		});
+		else if (rule === "node:process") {
+			for (const literal of specifiers) if (isNodeModule(literal.value, "process")) found.push({
+				offset: literal.start,
+				rule,
+				detail: literal.value
+			});
+		} else if (rule === "stdout-write") for (const { at, method } of stdoutWrites(lexed.code)) found.push({
+			offset: at,
+			rule,
+			detail: `stdout.${method}`
+		});
+		else if (rule === "console") for (const offset of references(lexed.code, "console")) found.push({
+			offset,
+			rule,
+			detail: "console"
+		});
+		else if (rule === "console-stdout") for (const offset of references(lexed.code, "console")) {
+			const member = memberAfter(lexed.code, offset, "console");
+			if (member !== void 0 && STDERR_METHODS.has(member)) continue;
+			found.push({
+				offset,
+				rule,
+				detail: member === void 0 ? "console" : `console.${member}`
+			});
+		}
+		else if ("forbidTokens" in rule) for (const token of new Set(rule.forbidTokens)) for (const offset of tokenOccurrences(lexed.code, token)) found.push({
+			offset,
+			rule: "forbidTokens",
+			detail: token
+		});
+		else for (const literal of specifiers) if (rule.forbidImports.some((entry) => forbids(entry, literal.value))) found.push({
+			offset: literal.start,
+			rule: "forbidImports",
+			detail: literal.value
+		});
+		return found.sort((a, b) => a.offset - b.offset).map(({ offset, rule, detail }) => Offence.make({
+			file,
+			...at(offset),
+			rule,
+			detail
+		}));
+	};
+	/**
+	* Check every source file under `root` against `rules`.
+	*
+	* @remarks
+	* Walks with an explicit stack, visiting each real directory once (via
+	* `realPath`), so a symlink loop terminates and a linked directory is not
+	* scanned twice. `node_modules` is never entered. Paths come back relative
+	* and `/`-separated whatever the platform's separator, and that is also
+	* what `allow` globs match against. A missing root fails; it never scans
+	* nothing. A dangling symlink under the root is skipped, having nothing to
+	* scan; any other entry that cannot be read fails the scan.
+	*
+	* @example
+	* ```ts
+	* import { NodeServices } from "@effect/platform-node";
+	* import { SourceBoundary } from "@effected/workspaces/testing";
+	* import { Effect } from "effect";
+	*
+	* const scan = SourceBoundary.scan({
+	*   root: "/repo/packages/engine/src",
+	*   rules: ["process", "node:process", { forbidImports: ["node:*", "@effect/platform*"] }],
+	* }).pipe(Effect.provide(NodeServices.layer));
+	* ```
+	*/
+	static scan = Effect.fn("SourceBoundary.scan")(function* (options) {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const allow = yield* GlobSet.compile(options.allow ?? []);
+		const allowRules = /* @__PURE__ */ new Map();
+		for (const [rule, patterns] of Object.entries(options.allowRules ?? {})) if (patterns !== void 0) allowRules.set(rule, yield* GlobSet.compile(patterns));
+		const extensions = options.extensions ?? DEFAULT_EXTENSIONS;
+		const posix = (relative) => relative.split(path.sep).join("/");
+		const files = [];
+		const allowed = [];
+		const offences = [];
+		const waived = [];
+		const visited = /* @__PURE__ */ new Set();
+		const pending = [options.root];
+		while (pending.length > 0) {
+			const directory = pending.pop();
+			if (directory === void 0) break;
+			const real = yield* fs.realPath(directory);
+			if (visited.has(real)) continue;
+			visited.add(real);
+			for (const name of yield* fs.readDirectory(directory)) {
+				const full = path.join(directory, name);
+				const found = yield* fs.stat(full).pipe(Effect.map(Option.some), Effect.catch((error) => error.reason._tag === "NotFound" ? fs.readLink(full).pipe(Effect.as(Option.none()), Effect.mapError(() => error)) : Effect.fail(error)));
+				if (Option.isNone(found)) continue;
+				const info = found.value;
+				if (info.type === "Directory") {
+					if (name !== "node_modules") pending.push(full);
+					continue;
+				}
+				if (info.type !== "File" || DECLARATION.test(name) || !extensions.some((extension) => name.endsWith(extension))) continue;
+				const file = posix(path.relative(options.root, full));
+				files.push(file);
+				if (allow.matches(file)) {
+					allowed.push(file);
+					continue;
+				}
+				for (const offence of SourceBoundary.check(file, yield* fs.readFileString(full), options.rules, options)) (allowRules.get(offence.rule)?.matches(file) === true ? waived : offences).push(offence);
+			}
+		}
+		return SourceScan.make({
+			files: files.sort(byCodeUnit),
+			allowed: allowed.sort(byCodeUnit),
+			offences: offences.sort(byPosition),
+			waived: waived.sort(byPosition)
+		});
+	});
+	/** The shipped positive- and negative-control snippets, at least one of each per rule kind. */
+	static fixtures = FIXTURES;
+	/** The names of shipped fixtures the scanner now gets wrong; `[]` means it still flags and spares what it must. */
+	static verifyFixtures = () => FIXTURES.filter((fixture) => SourceBoundary.check("fixture.ts", fixture.source, [fixture.rule]).length > 0 !== fixture.flagged).map((fixture) => `${fixture.flagged ? "missed" : "false positive"}: ${fixture.name}`);
+};
+
+//#endregion
+export { Offence, SourceBoundary, SourceScan };