@isentinel/eslint-config 6.0.0 → 6.1.0

package/README.md

@@ -230,8 +230,8 @@ It resolves the `eslint` and `oxlint` binaries from your project's
 
 By default (a local run, no `--type-aware`, no `--fix`) it runs **three**
 children concurrently via
-[`concurrently`](https://www.npmjs.com/package/concurrently), grouping their
-output:
+[`concurrently`](https://www.npmjs.com/package/concurrently)'s core (no shell),
+grouping their output:
 
 - **oxlint** — the full oxlint pass (including its type-aware rules).
 - **fast pass** — ESLint with only the syntactic (non-type-aware) rules, over
@@ -253,6 +253,22 @@ Other behaviours:
   re-lint (its own dirty count), rather than eagerly spinning up a worker per
   CPU. The fast pass is cheap per file, so it packs far more files per worker
   (see `FAST_FILES_PER_WORKER`) than the type-aware pass.
+- Sizes the heap of every ESLint child that builds a TypeScript program (the
+  type-aware pass, the full pass and the fix child). Each worker holds its own
+  program, so the limit that matters is workers × heap. By default the runner
+  splits half the machine's memory (or its cgroup limit, when lower) across
+  those workers, and raises Node's heap limit when the share is larger. When the
+  budget cannot give each worker twice Node's default heap, it runs fewer
+  workers: every worker loads the program of nearly every project, so fewer,
+  larger workers need far less memory in total than more, smaller ones. The flag
+  goes in the child's `NODE_OPTIONS`, which every ESLint worker inherits; oxlint
+  and the fast pass never get it. `--print` shows the chosen workers, files per
+  worker and heap on stderr. If a child still runs out of memory, the runner
+  prints a hint that names `LINT_TYPED_HEAP_MB`. A size set in
+  `LINT_TYPED_HEAP_MB` also caps the workers at budget ÷ size. An explicit
+  `LINT_MAX_WORKERS` or `--concurrency` is never reduced. A
+  `--max-old-space-size` already in `NODE_OPTIONS` wins over all of this: the
+  runner adds nothing and keeps the worker count.
 - Keeps a separate ESLint cache per pass so they never invalidate one another:
   `.eslintcache-fast-<key>` (fast pass), `.eslintcache-typeaware-<key>`
   (type-aware pass), and `.eslintcache-<key>` (the full config, used by CI,
@@ -341,6 +357,32 @@ determined it fails open and runs both engines as before. Explicit `--eslint` /
 
 Any trailing positional arguments are treated as paths to lint (default `.`).
 
+### Large file selections
+
+A git hook that hands the runner thousands of files should not put them on a
+command line: `cmd.exe` stops at 8,191 characters and `CreateProcessW` at
+32,767, so tools end up splitting the list into batches that each start another
+lint stack. Pass the list as data instead:
+
+```bash
+git diff --cached --name-only -z --relative --diff-filter=ACMR | isentinel-lint --files0-from -
+```
+
+`--files0-from <file|->` reads NUL-terminated UTF-8 paths from a file, or from
+stdin for `-` (the `git -z` / `find -print0` shape). Relative entries resolve
+against the working directory, exactly like positional paths (hence `--relative`
+above when running from a sub-package). The paths go through the same planning,
+caching and type-aware skip as positional ones, in one run. An empty list lints
+nothing and exits 0 — it never falls back to `.`. A list that is not valid UTF-8
+or holds an empty entry is refused, as is combining the flag with positional
+paths.
+
+The runner never puts paths on a command line itself either: every oxlint and
+ESLint child is launched as `node <bootstrap> <engine bin>` with no shell, and
+its full argument list is streamed to it over stdin. As a consequence ESLint's
+own `--stdin` / `--stdin-filename` cannot be forwarded through `--eslint-args`
+or `--`.
+
 ### Flags
 
 | Flag                           | Description                                                                                                                        |
@@ -355,6 +397,7 @@ Any trailing positional arguments are treated as paths to lint (default `.`).
 | `--concurrency <n\|off>`       | Override the concurrency heuristic with a fixed worker count.                                                                      |
 | `--eslint-args "<args>"`       | Extra arguments forwarded verbatim to ESLint.                                                                                      |
 | `--oxlint-args "<args>"`       | Extra arguments forwarded verbatim to oxlint.                                                                                      |
+| `--files0-from <file\|->`      | Read the paths to lint from a NUL-delimited UTF-8 list (`-` for stdin); an empty list exits 0.                                     |
 | `--print`                      | Print the composed commands without running them.                                                                                  |
 | `-- <args>`                    | Forward args to the single selected tool (needs `--eslint`/`--oxlint`).                                                            |
 | `-h`, `--help`                 | Show help.                                                                                                                         |
@@ -367,6 +410,7 @@ Any trailing positional arguments are treated as paths to lint (default `.`).
 | `FILES_PER_WORKER`      | Target files a single type-aware ESLint worker handles before adding another (default `350`).                        |
 | `FAST_FILES_PER_WORKER` | Same, for the fast (syntactic) pass, which packs far more files per worker (default `800`).                          |
 | `LINT_MAX_WORKERS`      | Upper bound on ESLint workers (default a quarter of available CPUs).                                                 |
+| `LINT_TYPED_HEAP_MB`    | Heap per worker for the program-building ESLint children: `auto` (default), a size in MB, or `off` (Node's default). |
 | `ESLINT_TYPE_AWARE`     | `off` or `only`; the type-aware mode `--type-aware` sets for the ESLint child (`false` is a legacy alias for `off`). |
 | `CI`                    | When set, the runner uses the single full pass with `--cache-strategy content` (see below).                          |
 

package/dist/cli.mjs

@@ -9,7 +9,7 @@ import path from "node:path";
 import { existsSync, readFileSync } from "fs";
 import { execSync } from "node:child_process";
 //#region package.json
-var version = "6.0.0";
+var version = "6.1.0";
 var package_default = {
 	name: "@isentinel/eslint-config",
 	version,

package/dist/index.d.mts

@@ -28502,7 +28502,14 @@ declare function loadSmallRulesPlugin(): NonNullable<TypedFlatConfigItem["plugin
 declare function smallRules(options?: OptionsComponentExtensions & OptionsFiles & OptionsIsInEditor & OptionsStylistic): Array<TypedFlatConfigItem>;
 //#endregion
 //#region src/eslint/configs/sonarjs.d.ts
-declare function sonarjs({ isInEditor, roblox }: OptionsHasRoblox & Required<OptionsIsInEditor>): Promise<Array<TypedFlatConfigItem>>;
+declare function sonarjs({ complementIgnores, isInEditor, roblox }: OptionsHasRoblox & Required<OptionsIsInEditor> & {
+  /**
+   * When set, re-apply the non-roblox rules to every source file except
+   * these globs (the roblox scope), so the complement is linted as
+   * standard-TS/Node land.
+   */
+  complementIgnores?: Array<string>;
+}): Promise<Array<TypedFlatConfigItem>>;
 //#endregion
 //#region src/eslint/configs/sort.d.ts
 /**

package/dist/index.mjs

@@ -4523,7 +4523,8 @@ function sonarjsTestRules({ jest = false, roblox = true } = {}) {
 }
 //#endregion
 //#region src/eslint/configs/sonarjs.ts
-async function sonarjs({ isInEditor, roblox }) {
+init_globs();
+async function sonarjs({ complementIgnores, isInEditor, roblox }) {
 	return [{
 		name: "isentinel/sonarjs",
 		plugins: { sonar: await interopDefault(import("eslint-plugin-sonarjs")) },
@@ -4531,7 +4532,15 @@ async function sonarjs({ isInEditor, roblox }) {
 			isInEditor,
 			roblox
 		})
-	}];
+	}, ...complementIgnores ? [{
+		name: "isentinel/sonarjs/complement",
+		files: [GLOB_SRC],
+		ignores: complementIgnores,
+		rules: sonarjsRules({
+			isInEditor,
+			roblox: false
+		})
+	}] : []];
 }
 //#endregion
 //#region src/eslint/configs/sort.ts
@@ -5938,7 +5947,6 @@ function typescriptTypeAwareRules({ roblox = true } = {}) {
 		"ts/no-confusing-void-expression": "error",
 		"ts/no-deprecated": "error",
 		"ts/no-duplicate-type-constituents": "error",
-		"ts/no-empty-object-type": "error",
 		"ts/no-floating-promises": ["error", {
 			checkThenables: roblox,
 			ignoreVoid: true
@@ -20314,6 +20322,7 @@ async function isentinel(options, ...userConfigs) {
 		roblox: enableRoblox,
 		stylistic: stylisticOptions
 	}), promise(), sonarjs({
+		...needsComplementOverlay ? { complementIgnores: robloxScopedFiles } : {},
 		isInEditor,
 		roblox: enableRoblox
 	}), typescript({

package/dist/lint-bootstrap.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/lint-bootstrap.mjs

@@ -0,0 +1,98 @@
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+//#region src/lint-cli/bootstrap.ts
+/**
+* Engine bootstrap for the lint runner. Spawned as
+* `node <this file> <engine bin>` with the engine's complete argument list as a
+* JSON string array on stdin; it decodes that list, installs it as
+* `process.argv` and then loads the engine's own bin in this same process.
+*
+* It exists to keep file lists off OS command lines: a hook selecting thousands
+* of files would otherwise overflow `CreateProcessW` (32,767 chars) or cmd.exe
+* (8,191) and have to be split into batches, each one starting another lint
+* stack. The command line that launches this process has the same two
+* arguments however many files the run lints.
+*
+* Kept free of imports beyond Node's own so it loads in milliseconds and
+* nothing it pulls in can observe the placeholder `process.argv`.
+*/
+/** The exit code for a launch this bootstrap could not complete. */
+const BOOTSTRAP_FAILURE = 2;
+/**
+* Read stdin to its end. Asynchronous rather than `readFileSync(0)`, which can
+* fail with `EAGAIN` on a non-blocking pipe before the writer has finished.
+*
+* @returns The bytes stdin carried.
+*/
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8"));
+	return Buffer.concat(chunks);
+}
+/**
+* Whether a decoded payload is an array of strings. Restated rather than
+* imported from the package's guards, so this entry stays dependency-free.
+*
+* @param value - The decoded payload.
+* @returns Whether every element is a string.
+*/
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((element) => typeof element === "string");
+}
+/**
+* Decode the engine argument list the runner streamed in.
+*
+* @param bytes - The raw stdin payload.
+* @returns The arguments, verbatim.
+*/
+function decodeArguments(bytes) {
+	const decoder = new TextDecoder("utf-8", { fatal: true });
+	const parsed = JSON.parse(decoder.decode(bytes));
+	if (!isStringArray(parsed)) throw new TypeError("expected a JSON array of argument strings on stdin");
+	return parsed;
+}
+/**
+* Read and validate everything the launch needs. Only this phase is the
+* bootstrap's own: its failures are reported as such and exit 2.
+*
+* @returns The launch.
+* @rejects {Error} When the usage, stdin or argument payload is invalid.
+*/
+async function prepare() {
+	const [bin, ...extra] = process.argv.slice(2);
+	if (bin === void 0 || bin.length === 0 || extra.length > 0) throw new Error("usage: node bootstrap <engine bin> (arguments as JSON on stdin)");
+	return {
+		args: decodeArguments(await readStdin()),
+		bin
+	};
+}
+/**
+* Prepare the launch, then become the engine.
+*
+* The engine import stays outside the catch around {@link prepare}: its
+* failures are left to Node's default handling, so they surface (stack and
+* exit code included) exactly as they would from a direct `node <bin>` launch.
+*
+* @rejects {Error} Whatever the engine's own module evaluation throws.
+*/
+async function main() {
+	let launch;
+	try {
+		launch = await prepare();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`isentinel-lint: could not start the engine: ${message}\n`);
+		process.exitCode = BOOTSTRAP_FAILURE;
+		return;
+	}
+	process.argv = [
+		process.execPath,
+		launch.bin,
+		...launch.args
+	];
+	await import(pathToFileURL(launch.bin).href);
+}
+main();
+//#endregion
+export {};