@isentinel/eslint-config 6.0.0-beta.12 → 6.0.0-beta.13

package/README.md

@@ -91,17 +91,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 +197,199 @@ 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), 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 single-pass config used
+  by `--fix`, CI and `--type-aware=full`). 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.
+
+- Runs `--fix` sequentially (`oxlint --fix`, then `eslint --fix`) so two writers
+  never race on the same files.
+- 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. `--fix`, CI and `--type-aware=full` runs use the
+> single full config and still report unused directives.
+
+### 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 `.`).
+
+### Flags
+
+| Flag                           | Description                                                                                                                        |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `--eslint`                     | Run only ESLint.                                                                                                                   |
+| `--oxlint`                     | Run only oxlint.                                                                                                                   |
+| `--fix`                        | Apply fixes: `oxlint --fix` then `eslint --fix` (sequential).                                                                      |
+| `--agents`                     | Emit agent-friendly output from both linters.                                                                                      |
+| `--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.                                                                                      |
+| `--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.
+
+### 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:

package/bin/index.js

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

package/bin/lint.js

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