@isentinel/eslint-config 6.0.0-beta.9 → 6.0.1

package/README.md

@@ -38,6 +38,16 @@ import isentinel from "@isentinel/eslint-config";
 export default isentinel();
 ```
 
+`@isentinel/eslint-config/eslint` is an explicit alias of the root export, for
+symmetry with `@isentinel/eslint-config/oxlint`:
+
+```ts
+// eslint.config.ts
+import { isentinel } from "@isentinel/eslint-config/eslint";
+
+export default isentinel();
+```
+
 #### Optional: TypeScript Config Support
 
 If you want to use `eslint.config.ts` instead of `.js`, install `jiti` v2.0.0 or
@@ -91,17 +101,20 @@ export default isentinel(
 
 ### Add script for package.json
 
-For example:
+The package ships an `isentinel-lint` bin that runs oxlint and ESLint together.
+The starter wizard adds these for you; to wire them up manually:
 
 ```json
 {
 	"scripts": {
-		"lint": "eslint",
-		"lint:fix": "eslint --fix"
+		"lint": "isentinel-lint",
+		"lint:fix": "isentinel-lint --fix"
 	}
 }
 ```
 
+See [`isentinel-lint`](#isentinel-lint) for what it does and every flag.
+
 ## Recommended Settings
 
 ### TSConfig
@@ -194,6 +207,264 @@ Add the following settings to your `.vscode/settings.json`:
 }
 ```
 
+## isentinel-lint
+
+The package ships a second bin, `isentinel-lint`, a hybrid runner that drives
+[oxlint](https://oxc.rs/docs/guide/usage/linter/) and ESLint together. Point
+your `lint` script at it and forget the wiring (the starter wizard does this for
+you):
+
+```json
+{
+	"scripts": {
+		"lint": "isentinel-lint",
+		"lint:fix": "isentinel-lint --fix"
+	}
+}
+```
+
+It resolves the `eslint` and `oxlint` binaries from your project's
+`node_modules`, so both must be installed locally.
+
+### What it does
+
+By default (a local run, no `--type-aware`, no `--fix`) it runs **three**
+children concurrently via
+[`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
+  every lintable file (TS/JS, JSON, YAML, TOML, Markdown, Lua). This is where
+  non-TS files are linted.
+- **type-aware pass** — ESLint with only the type-aware rules, over the TS/JS
+  family. The preset's config splits exactly in two, so `fast ∪ type-aware`
+  reproduces the full config rule-for-rule.
+
+The type-aware pass is the expensive one (it builds a TypeScript program), so
+the runner **skips it entirely when nothing type-relevant changed** since the
+last run — it uses the TypeScript builder to find the files whose type-aware
+results could have changed, and if that set is empty it prints a short note to
+stderr and does not start the pass. The fast pass and oxlint always run.
+
+Other behaviours:
+
+- Sizes each ESLint pass's `--concurrency` from how many files it will actually
+  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.
+- 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,
+  `--type-aware=full` and the fix child below). A change to an
+  ESLint/oxlint/Prettier/tsconfig file or a lockfile clears each cache that is
+  actually older than that change; a change to the root `package.json`
+  resolution surface (`exports`, `imports`, `main`, `module`, `types`,
+  `typesVersions`, `dependencies`, `devDependencies`, `peerDependencies`) clears
+  only the type-aware caches (a syntactic lint cannot be affected by
+  resolution). Add `.eslintcache*` to `.gitignore` — a bare `.eslintcache` entry
+  does not match the suffixed names.
+- Splits every cache by **config variant**. ESLint stores a config hash per
+  cache entry, so two runs that resolve even slightly different configs wipe
+  each other's entries when they share one cache file — an agent session and a
+  human session alternating against one cache re-lint the whole project in both
+  directions, every time. The `<key>` above is an 8-character hash of the inputs
+  that make this preset resolve a different config: agent session, editor
+  session and CI. Each variant gets its own cache (and its own builder /
+  `package.json`-hash state), so nothing is invalidated; the variants simply
+  stop overwriting each other. Git-hook runs deliberately share the plain
+  no-agent variant.
+
+  If your own `eslint.config.*` branches on something the runner cannot see —
+  your own agent/editor check, a feature flag, or an explicit `isAgent`,
+  `isInEditor` or `defaultSeverity` option — set `ISENTINEL_LINT_CACHE_KEY` to a
+  value naming that branch. It is folded into the key, giving those configs
+  separate caches too.
+
+- Treats `--fix` as a check followed by a fix, in three steps. `oxlint --fix`
+  goes first and alone, since it rewrites the files the ESLint children are
+  about to read. The run's ESLint passes then run as ordinary **checks** —
+  concurrent, own caches, no writes. By default those are the fast and
+  type-aware passes — the single full pass in CI; an explicit `--type-aware`
+  checks whichever passes that mode selects instead (`full` the single full
+  pass, `only` the type-aware pass alone, `off` the fast pass alone). Finally
+  **one** ESLint child applies fixes to **only the files those checks had
+  messages about**, using the full config (a superset of every pass, so it can
+  fix anything any of them found).
+
+  When the checks report nothing, which is the common case, that last child
+  never spawns and `--fix` costs what a check run costs. Being the run's only
+  ESLint writer, it also cannot race anything.
+
+  The file list comes from the check passes' own caches: ESLint stores each
+  file's result beside its cache entry and replays it on a cache hit, so a warm
+  cache is that pass's whole-tree verdict — including for a pass that
+  auto-skipped, whose verdict stands precisely because nothing it cares about
+  changed. `--no-cache` leaves no verdict to read, so the fix child falls back
+  to linting everything it was given. A target outside the working directory is
+  invisible to the listing the verdict is read against, so it is handed to the
+  fix child as it stands, alongside the reported files; that child runs without
+  the cache, since a stale entry for a file no verdict covers would let ESLint
+  skip it.
+
+- Lets every child run to completion and returns non-zero if any failed — an
+  ordinary lint error in one tool no longer kills the others mid-run.
+
+> **Unused eslint-disable directives.** The default two-pass mode does **not**
+> report unused `eslint-disable` directives: a directive naming a rule that
+> lives in the _other_ pass would look unused to the pass that runs it and
+> produce a false positive. CI and `--type-aware=full` runs use the single full
+> config and still report them.
+>
+> A local `--fix` inherits this from its checks. The fix child runs the full
+> config and would report an unused directive, but it only ever sees the files
+> the checks reported, and a file whose _only_ problem is an unused directive is
+> not one of them — so those directives survive a local fix run. In CI the check
+> is the full config, so they are reported and removed as before.
+
+### Hybrid detection
+
+Running both engines only makes sense when the ESLint config is in **hybrid
+mode** (`oxlint: true`), which drops every oxlint-covered rule from the ESLint
+side so the two engines never overlap. A config that omits `oxlint: true` runs
+every mapped rule in _both_ engines — duplicate diagnostics, and under `--fix` a
+tug-of-war as each rewrites toward its own option resolution. So whenever both
+engines would run (default mode or `--fix`), the runner checks whether the
+resolved config is hybrid; if it is not, it **runs ESLint only, skips oxlint,
+and prints one stderr warning** (enable hybrid mode, or pass `--oxlint` to run
+oxlint explicitly). The check is cheap: the factory records the hybrid status in
+`node_modules/.cache/isentinel-lint/` on every config evaluation, and the runner
+trusts that cache unless your ESLint config is newer, in which case it probes
+`eslint --print-config` once and caches the result. If the status cannot be
+determined it fails open and runs both engines as before. Explicit `--eslint` /
+`--oxlint` runs skip the check entirely.
+
+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                                                                                                                        |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `--eslint`                     | Run only ESLint.                                                                                                                   |
+| `--oxlint`                     | Run only oxlint.                                                                                                                   |
+| `--fix`                        | Check as usual, then fix only the files the checks reported (one child).                                                           |
+| `--agents`, `--no-agents`      | Force agent-friendly output from both linters on or off (default: on in an agent session).                                         |
+| `--type-aware=off\|only\|full` | Force a single ESLint pass: `off` fast-only, `only` type-aware-only, `full` the whole config in one pass. Cannot mix with `--fix`. |
+| `--no-oxlint-type-aware`       | Skip oxlint's type-aware rules (no `oxlint-tsgolint` needed).                                                                      |
+| `--no-cache`                   | Disable ESLint's on-disk cache.                                                                                                    |
+| `--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.                                                                                                                         |
+| `-v`, `--version`              | Show the version.                                                                                                                  |
+
+### Environment
+
+| Variable                | Effect                                                                                                               |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `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).                                                 |
+| `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).                          |
+
+### Type-aware oxlint and tsgolint
+
+By default the runner passes `--type-aware` to oxlint, which needs
+[`oxlint-tsgolint`](https://www.npmjs.com/package/oxlint-tsgolint). If it is not
+installed the runner errors out rather than silently skipping type-aware rules.
+Install it, or pass `--no-oxlint-type-aware` to run oxlint without them:
+
+```bash
+pnpm i -D oxlint oxlint-tsgolint
+```
+
+`--type-aware=off` also drops oxlint's type-aware pass, since the fast mode
+skips type-aware linting entirely.
+
+### CI
+
+When a `CI` environment variable is set the runner skips the two-pass split and
+runs a single full-config ESLint pass (alongside oxlint). CI cores are few, so
+the two-pass parallelism does not pay off, and the full config is the only one
+that reports unused `eslint-disable` directives — which you want enforced in CI.
+The pass also switches to `--cache-strategy content` so caches key on file
+contents rather than timestamps, which are unreliable across fresh checkouts.
+
+### Agent output
+
+`--agents` emits machine-readable output for AI agents: oxlint runs with
+`--format agent`, and ESLint uses the formatter shipped at
+`@isentinel/eslint-config/formatter-agents`, which the runner resolves and
+passes to `eslint --format` for you.
+
+It is on by default whenever an AI coding agent session is detected, so agents
+get agent-shaped output without passing the flag. Detection follows
+[`std-env`](https://github.com/unjs/std-env)'s agent table (Claude Code, Codex,
+Cursor, Gemini CLI, opencode, replit, auggie, goose, junie, devin, kiro, pi),
+plus the `AI_AGENT` variable as an explicit override. Git hook and lint-staged
+runs are excluded — those are human-initiated. Pass `--no-agents` to force human
+output, or set `AI_AGENT` to force detection on.
+
+### Known limitations
+
+The incremental machinery favours speed, and a few edges are deliberately left
+to self-heal or need a one-off nudge:
+
+- **Config changes reached through an imported module are invisible to a
+  _skipped_ typed pass.** The runner busts caches on the mtime of your
+  `eslint.config.*`, tsconfigs and lockfiles, but not on files those configs
+  `import`. ESLint's own per-entry config hash would still catch such a change
+  once the pass runs — but if the typed pass was auto-skipped (nothing
+  type-relevant looked dirty), it never runs to notice. Touch your
+  `eslint.config.*` (or run once with `--no-cache`) after editing a module it
+  imports.
+- **mtime granularity.** Cache freshness is compared by modification time, so
+  the usual coarse-filesystem-timestamp race that affects ESLint's own cache
+  applies here too (edits within the same clock tick as the last run can be
+  missed). CI uses `--cache-strategy content` to sidestep it; locally, a second
+  run settles it.
+- **Solution-style / project-reference tsconfigs.** The TypeScript builder used
+  to find type-affected files does not follow project references, so in a
+  solution-style setup builder invalidation silently becomes a no-op and the
+  runner falls back to plain mtime dirtiness. Type-aware results stay correct
+  (ESLint still lints the dirty files); only the cross-file "an imported type
+  changed" invalidation is skipped.
+- **Hybrid status tracks `eslint.config.*` mtimes only.** If you toggle hybrid
+  mode (`oxlint: true`) from a module the config _imports_ rather than the
+  config file itself, the runner trusts its cached hybrid decision for one more
+  run before the factory's passive write corrects it — it self-heals on the next
+  invocation.
+
 ## Customization
 
 Normally you only need to import the `isentinel` preset:
@@ -526,6 +797,107 @@ otherwise, you can install them manually:
 pnpm i -D eslint-plugin-react-x eslint-plugin-react-jsx eslint-plugin-react-naming-convention eslint-plugin-jest
 ```
 
+#### Anti-Slop
+
+Enable `eslint-plugin-flawless` rules that catch patterns AI-written code tends
+to produce (object-typed parameters, `unknown` returns, unsafe dictionary types,
+conditional empty-object spreads, `Reflect` access) with `antiSlop: true`:
+
+```ts
+// eslint.config.ts
+import isentinel from "@isentinel/eslint-config";
+
+export default isentinel({
+	antiSlop: true,
+});
+```
+
+#### Naming Conventions
+
+Enable the opinionated `flawless/naming-convention` rules with `naming: true`,
+or pass an object to add new selector entries or override the built-in defaults:
+
+```ts
+// eslint.config.ts
+import isentinel from "@isentinel/eslint-config";
+
+export default isentinel({
+	naming: {
+		selectors: [
+			// Override the default variable format
+			{ format: ["snake_case"], selector: "variable" },
+			// Add a new selector not covered by the defaults
+			{ format: ["PascalCase"], prefix: ["I"], selector: "interface" },
+		],
+		// Applied only to .tsx files, before `selectors`
+		selectorsTsx: [{ format: ["StrictPascalCase"], selector: "function" }],
+	},
+});
+```
+
+Entries in `selectors` apply to both the TS and TSX configs; `selectorsTsx`
+applies to the TSX config only. User entries are prepended before the defaults,
+and the rule applies the first matching entry after sorting by specificity — so
+an entry with the same specificity as a default overrides it, while new
+selectors are simply added. A less specific entry cannot override a more
+specific default. The `overridesTypeAware` escape hatch still replaces the whole
+rule if you need full control.
+
+##### Roblox names
+
+`strictCamelCase` and `StrictPascalCase` reject two capitals in a row, so a
+`CFrame` has to be stored in `targetCframe` and the identifier stops matching
+the type it holds. `allowedWords` lets listed words keep their own casing inside
+a name, while the rest of the name is still checked. It is off by default:
+
+```ts
+// eslint.config.ts
+import isentinel from "@isentinel/eslint-config";
+
+export default isentinel({
+	naming: {
+		// Use ROBLOX_ALLOWED_WORDS, generated from `@rbxts/types`
+		allowedWords: true,
+	},
+});
+```
+
+```ts
+const targetCFrame = new CFrame(); // ok
+const listLayoutUIPadding = 0; // ok
+const autoZIndex = 0; // ok - properties count, not just types
+const target_CFrame = 0; // still an error
+const fooXYBar = 0; // still an error - not a Roblox name
+const colorToHSV = 0; // still an error - methods do not count, use `colorToHsv`
+```
+
+The generated list covers type names and data properties, not methods. A call
+spells the API out at the call site, where the naming rules do not reach, so
+`Color3.ToHSV` is no reason to let the variable holding its result skip them.
+
+Pass an array to use exactly those words instead. Spread `ROBLOX_ALLOWED_WORDS`
+to extend the list rather than replace it:
+
+```ts
+import isentinel, { ROBLOX_ALLOWED_WORDS } from "@isentinel/eslint-config";
+
+export default isentinel({
+	naming: {
+		allowedWords: [...ROBLOX_ALLOWED_WORDS, "HTTP", "URL"],
+	},
+});
+```
+
+The list reaches every selector, including your own `selectors` entries. A
+selector opts out with its own `allowedWords: []`. Only the two strict formats
+honour it, so it can never loosen `snake_case` or `UPPER_CASE`, and a word only
+matches at a hump boundary, so it cannot split an existing hump.
+
+At the **start** of a `strictCamelCase` name a word also matches with its first
+character lowercased, since that is the only spelling the format allows there —
+`motor6DWeld` and `targetMotor6DPart` both pass. Everywhere else the word has to
+be spelled as the API spells it, so `targetmotor6DPart` is still an error.
+
 #### Oxlint
 
 The config can run alongside (or be replaced by)
@@ -590,6 +962,53 @@ otherwise, you can install them manually:
 pnpm i -D eslint-plugin-eslint-plugin
 ```
 
+#### Co-located Tests
+
+`projectStructure` requires every source file to sit next to its test file,
+through
+[eslint-plugin-project-structure](https://github.com/Igorkowalski94/eslint-plugin-project-structure).
+`src/place-service.ts` then has to be joined by `src/place-service.spec.ts`.
+Only `enforceExistence` is driven here, so the rule never enforces naming:
+
+```ts
+// eslint.config.ts
+import isentinel from "@isentinel/eslint-config";
+
+export default isentinel({
+	projectStructure: {
+		// The plugin's name placeholders, plus `{ext}` for the extension of the
+		// file that matched. Default: ["{node-name}.spec.{ext}"]
+		enforceExistence: "__tests__/{node-name}.test.{ext}",
+		// Default: every source file the preset lints
+		files: ["src/**/*.{ts,tsx}"],
+		// Default: tests, `.d.ts` files and build configs
+		ignores: ["**/index.ts"],
+		// Default: `process.cwd()`
+		projectRoot: import.meta.dirname,
+		// Restricts the check to one subtree. Default: all of `projectRoot`
+		structureRoot: "src",
+	},
+});
+```
+
+```bash
+pnpm i -D eslint-plugin-project-structure
+```
+
+`{node-name}` matches the kebab-case filenames the preset enforces; the others
+are `{nodeName}`, `{NodeName}`, `{node_name}` and `{NODE_NAME}`. A file already
+matching a template is exempt from it. A source file with no test disables the
+rule at the source.
+
+The rule needs no type information, so oxlint runs it too: the same option is
+accepted by the oxlint factory, and hybrid mode (`oxlint: true`) hands the check
+to oxlint.
+
+Two caveats. Deleting `foo.spec.ts` does not change `foo.ts`, so a cached run
+replays the old clean result — the check is only sound uncached. And the plugin
+writes `projectStructure.cache.json` into `projectRoot` while it has something
+to report, so gitignore it.
+
 ### Git hooks
 
 If you want to apply lint and auto-fix before every commit, use
@@ -619,6 +1038,37 @@ mise use hk pkl # or see https://hk.jdx.dev for other install methods
 hk install
 ```
 
+### pnpm's global virtual store
+
+Only relevant if you have set
+[`enableGlobalVirtualStore: true`](https://pnpm.io/global-virtual-store).
+Otherwise pnpm's hoisting hides the problem and there is nothing to do.
+
+With the setting on, a package's real location moves out of your project, so
+TypeScript resolves each dependency's imports from its own declared dependencies
+alone. Several packages in this preset's tree import types they never declare —
+`eslint-flat-config-utils` imports from `eslint` without declaring it at all.
+`skipLibCheck` hides the resulting `TS2307`, but the type still degrades to
+`any`, which surfaces as misleading reports elsewhere:
+
+```text
+typescript(no-unsafe-argument): Unsafe argument of type Linter.Config[]
+  assigned to a parameter of type TypedFlatConfigItem[]
+```
+
+Since `isentinel()` returns a `FlatConfigComposer` from that package, this hits
+your `eslint.config.ts` directly. Add the companion pnpm plugin, which declares
+the missing imports for you:
+
+```bash
+pnpm add --config @isentinel/pnpm-plugin-eslint-config
+```
+
+pnpm auto-loads any config dependency whose name matches its plugin pattern, so
+there is nothing to configure. Use the CLI rather than hand-editing
+`pnpm-workspace.yaml`: config dependencies are pinned to an exact version and
+verified against an integrity hash that `pnpm add --config` records for you.
+
 ## View what rules are enabled
 
 There is a visual tool to help you view what rules are enabled in your project

package/bin/compile-cache.js

@@ -0,0 +1,8 @@
+import module from "node:module";
+
+// ESLint's own bin enables this, so its CLI already benefits; a language server
+// loading `dist/index.mjs` directly never does. Only the bins call it —
+// `enableCompileCache` is a host-process side effect and the package declares
+// `"sideEffects": false`. Importing it as a module keeps it ahead of the entry:
+// static imports are evaluated before any statement of the importer.
+module.enableCompileCache();

package/bin/index.js

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
 
-import "../dist/cli.js";
+import "./compile-cache.js";
+import "../dist/cli.mjs";

package/bin/lint.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./compile-cache.js";
+import "../dist/lint-cli.mjs";

package/dist/cli.d.mts

@@ -1 +1 @@
-export { };
+export {}