@hublo/sentinel 1.1.0-alpha.2 → 1.1.0-alpha.4

package/README.md

@@ -4,7 +4,7 @@
 
 `sentinel` is a standalone, semver-versioned package (published to a registry, consumed by a repo as a normal dependency) that unifies a repo's tooling, config, and quality checks into one place, so projects stop copying config files everywhere and stop carrying a pile of duplicated tooling dependencies.
 
-> Status: **foundation + the TypeScript tool are shipped** (`@hublo/sentinel@0.1.0-alpha.x` on npm). The rest of this README is the design reference for the tools still to come, added one at a time on top of this foundation.
+> Status: **the foundation, the TypeScript tool and the lint tool are shipped** (`@hublo/sentinel` on npm). The rest of this README is the design reference for the tools still to come, added one at a time on top of this foundation.
 
 ---
 
@@ -19,7 +19,7 @@ A large monorepo accumulates:
 
 ## What it gives you
 
-**The shift:** instead of today's **big-bang** (change every project and every tool at once, untested in isolation), evolution is **app-scoped and versioned**, evolving a project is a **version bump**, a new/swapped tool is just a **new runner**, and a new stack a **new flavour**. No repo-wide edits.
+**The shift:** instead of today's **big-bang** (change every project and every tool at once, untested in isolation), evolution is **app-scoped and versioned**, evolving a project is a **version bump**, a new/swapped tool is just a **new runner**, and a new stack a **new preset**. No repo-wide edits.
 
 - **One source of truth for config** — every project just `extends @hublo/sentinel/...`; the actual rules live in one versioned place. Change a rule once, everyone gets it on the next version bump.
 - **One source of truth for tooling dependencies** — a project depends on `@hublo/sentinel`, not on a scattered pile of eslint / vitest / plugin devDeps. Bump one version and the whole toolchain moves, atomically, tested in isolation first.
@@ -43,12 +43,14 @@ A large monorepo accumulates:
 
 sentinel writes **standard config files** into a project (each just `extends` a sentinel preset) and runs the checks. Your editor and the tools read those **normal files natively**, they never call sentinel at runtime, so nothing is coupled to it or brittle.
 
-> **Shipped today:** only the **TypeScript** tool, so `--init` writes the `tsconfig` stub, and `--run`/`--report`/`--status` work for `--typescript`. The `eslint.config.js` / `--lint` / `--test` snippets below illustrate the end state; those subpaths (`@hublo/sentinel/lint/*`, …) land with their tool ticket.
+> **Shipped today:** the **TypeScript** and **lint** tools. The `--test` / `--build` snippets
+> below illustrate the end state and land with their own ticket.
 
 **Step 1 — put a module on sentinel** (once per module, by a dev; the files are committed). Run from the app dir; `--init` does it all, nothing is hand-edited:
 
 ```bash
-sentinel --init --typescript --flavour <react|nest|node>
+sentinel --init --typescript --preset <react|nest|node|svelte>
+sentinel --init --lint --preset <react|nest|node|svelte>
 pnpm install   # fetch what --init declared, then commit
 ```
 
@@ -56,10 +58,10 @@ pnpm install   # fetch what --init declared, then commit
 
 Those files are tiny, they just point at a sentinel preset. What gets committed:
 
-```js
-// eslint.config.js — generated; overrides go through the sentinel allowlist, not inline
-import react from '@hublo/sentinel/lint/react'
-export default react
+```jsonc
+// .oxlintrc.json — generated. Adoption REPLACES eslint rather than sitting beside it, so
+// the module's eslint config is DELETED and this is the only linter config it keeps.
+{ "extends": ["./node_modules/@hublo/sentinel/oxlint/react.json"] }
 ```
 
 ```jsonc
@@ -122,7 +124,7 @@ pnpm dlx @hublo/sentinel@<exact-version> --inspect --typescript --module <name>
 - [`docs/typescript-adoption.md`](docs/typescript-adoption.md) — the adoption cheat sheet: the two adoption steps, the command model (verb x type x location), options, reading a report, and troubleshooting.
 - [`docs/typescript-traces.md`](docs/typescript-traces.md) — a **generated, versioned** reference of live command + output traces (every verb, option, config result and edge case) against the mock monorepo. Regenerate after CLI changes with `pnpm docs:traces`.
 
-## Architecture: `target → runner → flavour`
+## Architecture: `target → runner → preset`
 
 Every check is described by three layers:
 
@@ -130,12 +132,12 @@ Every check is described by three layers:
 | -------------------- | --------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
 | **target** (role)    | `--lint`, `--typescript`, … | the _kind_ of check, stable                 | `lint` `format` `typescript` `build` `test` `static-analysis` `runtime-analysis`       |
 | **runner** (adapter) | `--runner=<tool>`           | the _tool_ behind the target, swappable     | lint: `eslint`/`biome`/`oxlint` · types: `tsc`/`tsgo` · build: `vite` · test: `vitest` |
-| **flavour** (preset) | detected / `--flavour`      | the _variant_ per stack (strict by default) | `react` `nest` `node` (svelte declared, preset deferred)                               |
+| **preset** (preset)  | detected / `--preset`       | the _variant_ per stack (strict by default) | `react` `nest` `node` `svelte` (svelte: lint only, no tsconfig preset yet)             |
 
-A run is `target × runner × flavour`, e.g. `sentinel --run --lint --runner=eslint` from the `host-admin` dir.
+A run is `target × runner × preset`, e.g. `sentinel --run --lint --runner=eslint` from the `host-admin` dir.
 
 - `--runner` is an **optional override on a central default**. `sentinel --lint` uses the configured default runner, so swapping a tool globally is a one-place change; `--runner=biome` overrides for a single run (great for benchmarking eslint vs biome vs oxlint, and for gradual migration).
-- The **flavour is detected** from the module's dependencies (deterministic: a framework dep → its flavour, else `node`), and **`--flavour` overrides it**. Detection can be wrong where deps are hoisted at the repo root (it returns `node`), so pass `--flavour` for `--init` (that is where the preset is chosen). `--run`/`--report` don't depend on it, they run the tool on the committed config.
+- The **preset is detected** from the module's dependencies (deterministic: a framework dep → its preset, else `node`), and **`--preset` overrides it**. Detection can be wrong where deps are hoisted at the repo root (it returns `node`), so pass `--preset` for `--init` (that is where the preset is chosen). `--run`/`--report` don't depend on it, they run the tool on the committed config.
 
 ### Adapters & the engine (ports & adapters)
 
@@ -143,14 +145,14 @@ A run is `target × runner × flavour`, e.g. `sentinel --run --lint --runner=esl
 
 - the **engine** (core) is tool-agnostic: it parses the CLI, resolves an adapter, and owns **all IO and repo structure**, finding the project root, reading, merging and writing files;
 - an **adapter** is the boundary to one tool (eslint, tsc, vitest, …). It carries the tool knowledge (how to run it, what its config means) and implements one contract (types in `src/core/types.ts`, optional base in `src/core/base-adapter.ts`);
-- a **context** is a plain data object the engine passes to an adapter for a run (`app`, `cwd`, optional `flavour`, `ci`, `fix`). It is data only, it never carries a filesystem capability.
+- a **context** is a plain data object the engine passes to an adapter for a run (`app`, `cwd`, optional `preset`, `ci`, `fix`). It is data only, it never carries a filesystem capability.
 
 `sentinel` does not reimplement tools. The contract:
 
-- **`appliesTo(flavour)`** — which flavours this adapter handles (resolution filters on it, so a React-only adapter is never picked for Nest)
-- **`plan(flavour)`** — PURE: returns a declarative `UpdatePlan` of file operations (used by `--init`). The adapter never touches the disk; the engine applies the plan.
+- **`appliesTo(preset)`** — which presets this adapter handles (resolution filters on it, so a React-only adapter is never picked for Nest)
+- **`plan(preset)`** — PURE: returns a declarative `UpdatePlan` of file operations (used by `--init`). The adapter never touches the disk; the engine applies the plan.
 - **`run(ctx)`** — invoke the tool's bin against the project (used by `--run`)
-- **`inspect(flavour)`** — the adapter's resolved base config (used by `--inspect`)
+- **`inspect(preset)`** — the adapter's resolved base config (used by `--inspect`)
 - **`report(ctx)`** — metrics (used by `--report`)
 
 **`--init` is a declarative plan, not file-writing inside the adapter.** The adapter describes intent as operations; the engine executes them:
@@ -170,7 +172,7 @@ So the tool-_meaning_ lives in the adapter and the read/merge/write _mechanics_
 ```mermaid
 flowchart LR
   CLI["sentinel --verb --target<br/>[--runner]"] --> D[dispatch]
-  D --> R["registry.resolve<br/>(target, flavour, runner)"]
+  D --> R["registry.resolve<br/>(target, preset, runner)"]
   R --> A["adapter<br/>eslint / tsc / vitest / ..."]
   A -->|"--run"| Run["tool binary on the project"]
   A -->|"--init"| Upd["declarative plan → engine writes"]
@@ -200,6 +202,80 @@ The rules live in `sentinel`. Each module keeps a **thin, generated stub** per t
 - **Per-module install** — `@hublo/sentinel` is added per module, so adoption is **gradual** (migrate lot by lot; a module can adopt sentinel while its neighbour still uses the old config). Root configs are removed only once the **last** module has migrated.
 - **Runner binaries** (`eslint`, `typescript`, `vite`, `vitest`, …) are **resolved from the adopting module** at run time (sentinel looks for the tool in the module, then falls back to `PATH`), so the editor and nx keep using the exact binary the project already installs. sentinel does **not** declare them as dependencies today, so it does not pin their versions: the module still owns its own `typescript`. Having sentinel dictate those versions (as peer dependencies, so the whole toolchain rides the sentinel version) is the intended end state, and it lands with the tool tickets that actually bundle a runner.
 
+## What a preset does not enforce
+
+A preset that silently enforces less than the config it replaced is worse than no preset, so
+every rule that is not enforced carries a reason and is listed by `sentinel --inspect --lint`:
+
+| State          | Meaning                                                              | Can it be switched on?          |
+| -------------- | -------------------------------------------------------------------- | ------------------------------- |
+| **deferred**   | scheduled for a later migration wave                                 | yes, on schedule                |
+| **disabled**   | a decision: it argues with the architecture, or only false-positives | yes, by revisiting the decision |
+| **downgraded** | it runs and reports, it just cannot fail the build                   | yes, once the debt is paid      |
+
+A small number of rules sit outside those three states, because the preset cannot carry them at
+any severity. They are documented here rather than reported by `--inspect`: oxlint validates
+rule and plugin names when it **parses** a config, so naming one would make the config fail to
+parse and the module would lint nothing at all. They are still recorded as data in the preset,
+so the tests can count every rule a module enforces and fail on anything unaccounted for.
+
+### Rules the presets do not carry (nest, react)
+
+| Rule                         | Why                                                                                                                                                                                                       |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `typescript/member-ordering` | oxlint has no native rule, and the preset deliberately does not host `@typescript-eslint/eslint-plugin`: a plugin costs a dependency, a load step and a pass over every file, which is not worth one rule |
+| `no-invalid-this`            | no oxlint equivalent, and hosting does not help (the rule crashes on every file under oxlint's plugin API). Its coverage moves to TypeScript's `noImplicitThis`                                           |
+| `no-octal`                   | no oxlint equivalent                                                                                                                                                                                      |
+| ~15 stylistic rules          | formatting, which the formatter owns. They move to **oxfmt**, deliberately the last step of the migration, so nothing enforces them in between                                                            |
+
+The formatting group is the only one that will ever shrink; the rest are settled losses.
+
+`no-return-await` is **not** in that table, despite having no oxlint rule of that name. It is
+deprecated in ESLint core and oxlint ships the typescript-eslint successor, so the presets carry
+`typescript/return-await` with the `never` option, which is what the old rule meant. It is held
+at `warn`: both modules set the old rule to error, but it was never actually reporting (the nx
+lint target expanded to 2 files of 2888), and running it over every file finds 9 real violations
+on bff-admin and 5 on host-admin. Fix those and it can be raised.
+
+### Rules with no oxlint equivalent (svelte)
+
+Oxlint parses a `.svelte` file's `<script>` block and **not its template**. Measured on oxlint
+1.77 with a component carrying a violation in each half: the `<script>` violation is reported,
+and `{@html}`, `{@debug}` and duplicate style properties in the template produce nothing.
+Adding a svelte plugin does not fix this, because the missing piece is the **parser**, not the
+rule implementations.
+
+So sixteen rules the two svelte modules enforce today have **no oxlint equivalent**. Fourteen
+read the template:
+
+`svelte/comment-directive` · `svelte/no-at-debug-tags` · **`svelte/no-at-html-tags`** ·
+`svelte/no-dupe-else-if-blocks` · `svelte/no-dupe-style-properties` ·
+`svelte/no-dynamic-slot-name` · `svelte/no-inner-declarations` ·
+`svelte/no-not-function-handler` · `svelte/no-object-in-text-mustaches` ·
+`svelte/no-shorthand-style-property-overrides` · `svelte/no-unknown-style-directive-property` ·
+`svelte/no-unused-svelte-ignore` · `svelte/system` · `svelte/valid-compile`
+
+and two core rules oxlint does not implement: `no-dupe-args` (TypeScript rejects duplicate
+parameter names anyway) and `no-octal`.
+
+**The one worth knowing about is `svelte/no-at-html-tags`**, an XSS guard that fires on the
+modules today. Adopting the svelte lint preset gives that check up.
+
+These rules are **absent from the generated config rather than set to `off`**, and that is
+forced, not stylistic. Oxlint rejects an unknown rule or plugin when it _parses_ a config, even
+when the value is `off`:
+
+```console
+$ oxlint -c '{"rules": {"svelte/no-at-html-tags": "off"}}'
+Failed to parse oxlint configuration file.
+  x Plugin 'svelte' not found
+```
+
+Listing them as disabled would not weaken the config, it would stop the config from parsing and
+the module would lint nothing at all. They are recorded as data in the preset (`uncovered`), so
+the preset tests can count every rule the modules enforce and fail on anything unaccounted for,
+and they are documented here for the developers who own those modules.
+
 ## Composition & precedence
 
 A repo often has a base config that is **structural**, not just tooling, e.g. a
@@ -264,11 +340,11 @@ A command **composes** three axes: **verb + type + location**.
 ```
 sentinel <verb> [type] [options]
 
-VERBS      --run       execute the target's tool
-           --inspect   show the resolved configuration (incl. deferred rules)
-           --report    metrics and health
-           --status    adoption + conformity (coverage + drift), read from configs
-           --init    generate/apply the config stubs (writes; one module only)
+VERBS      --run       execute the target's tool (--json for metrics + diagnostics)
+           --inspect   the resolved configuration, what is deferred, adoption + drift
+           --init      generate/apply the config stubs (writes; one module only)
+           --report    deprecated → --run --json
+           --status    deprecated → --inspect
 
 TYPES      --lint  --format  --typescript  --build  --test
            --static-analysis  --runtime-analysis  --arch
@@ -278,27 +354,55 @@ LOCATION   in a MODULE dir      → that module (do NOT pass --module)
            at the workspace ROOT → --module <name> (one) · --ci (affected) · else all
 
 OPTIONS    --module <name>    from the root: scope to one module
-           --flavour <name>   override the detected stack preset (react, nest, ...)
+           --preset <name>   override the detected stack preset (react, nest, ...)
            --runner <tool>    override the default runner
            --ci               from the root: affected only; non-zero exit on failure
            --fix              auto-fix where applicable
            --dry-run          preview a --init without writing
            --json             machine-readable output (report / inspect / status / --dry-run)
+           -- <tool options>  --run only: pass the rest to the tool itself (one type)
 
 EXAMPLES   sentinel --run --typescript                        # in a module → that module
-           sentinel --report --typescript --module bff-admin  # from root  → one module
-           sentinel --report                                  # from root  → all types, all modules
-           sentinel --status --typescript                     # from root  → adoption coverage
-           sentinel --status --ci                             # from root  → fail CI on drift
-           sentinel --init --typescript --flavour react     # write stubs for the current module
+           sentinel --run --typescript -- --noImplicitAny     # ask tsc a question of your own
+           sentinel --run --typescript --module bff-admin     # from root  → one module
+           sentinel --run --json                              # from root  → all types, machine output
+           sentinel --inspect --typescript                    # from root  → adoption coverage
+           sentinel --inspect --ci                            # from root  → fail CI on drift
+           sentinel --init --typescript --preset react     # write stubs for the current module
 ```
 
 `--run`/`--inspect`/`--report`/`--status` share one context rule (developer from a
 module, or from the root for a name / affected / all); `--init` writes, so it targets
 one module only (adopting every module at once is refused, adopt gradually).
 
+### Asking the tool your own question (`--`)
+
+Everything after `--` goes to the tool, not to sentinel. It applies to `--run` only, and
+needs exactly one type named, since one tool's options are not another's:
+
+```bash
+sentinel --run --typescript -- --noImplicitAny    # what would this deferred rule cost?
+sentinel --run --lint -- --deny-warnings          # what would zero warnings take?
+```
+
+This exists because a preset **defers** rules to keep first adoption non-breaking, and
+`--inspect` can only say that a rule is deferred. "Deferred" is honest, and it is not the
+answer anyone wants: the question is how much debt is behind it. Rather than sentinel
+modelling that question one flag at a time, the tool's own options are forwarded, so
+anything the tool can already answer is one command away.
+
+Two things to know:
+
+- **A modified run always says so**, on stderr and in the `--json` envelope (`toolArgs`).
+  These options can weaken a check as easily as strengthen it, and `--run` is what CI
+  calls, so a green result must never be mistakable for a clean standard check.
+- **For TypeScript it changes how tsc is invoked**, because build mode refuses compiler
+  options (`error TS5094`). Sentinel switches to project mode and checks each project the
+  solution `references`, since the solution itself holds no files. Emit is forced off, so a
+  question about the code never writes build output.
+
 **`--status` — adoption + conformity.** A cheap, workspace-wide read (no tool run, no
-flavour guessing): for each module it reads the committed `tsconfig` `extends` chain and
+preset guessing): for each module it reads the committed `tsconfig` `extends` chain and
 reports whether it is **adopted** (extends a sentinel preset), which preset, and whether
 it is **conformant** (drift-free, a re-`update` would change nothing), plus a coverage
 footer. This is the **drift guard** as a command, `--status --ci` exits non-zero when an
@@ -320,14 +424,14 @@ src/
   core/
     types.ts                 # the adapter contract, pure types (Adapter, FileOperation, UpdatePlan)
     base-adapter.ts          # optional convenience base class for adapters
-    domain.ts                # vocabulary + derived types (verbs, targets, flavours)
+    domain.ts                # vocabulary + derived types (verbs, targets, presets)
     settings.ts              # tunables (workspace-root marker, ...)
-    registry.ts              # register + flavour-aware resolve
+    registry.ts              # register + preset-aware resolve
     dispatch.ts              # verb → adapter method
     apply-plan.ts            # the engine's filesystem port (applies --init operations)
   roles/<config-role>/       # lint, format, typescript, build, test
     adapters/<runner>/       # one adapter per tool (implements the contract)
-    flavours/<stack>/        # config presets per stack (react, nest, svelte, ...)
+    presets/<stack>/        # config presets per stack (react, nest, svelte, ...)
   roles/{static-analysis,runtime-analysis}/   # analysis roles
     configs/                 # fixed configs (internal, not exported)
     runners/                 # one runner per sub-tool (duplication, complexity, ...)
@@ -336,9 +440,18 @@ tests/                       # unit tests + tests/e2e (runs the built dist binar
 .github/workflows/           # ci.yml (PR checks) + publish.yml (manual, version-input publish)
 ```
 
-Subpath exports (in `package.json`) expose presets to consumers. Shipped today:
-`@hublo/sentinel/tsconfig/react` · `.../tsconfig/nest` · `.../tsconfig/node`. Other
-subpaths (e.g. `.../lint/react`) land with their tool ticket.
+Presets reach consumers two different ways, decided by the tool rather than by us:
+
+- **tsconfig, as subpath exports**: `@hublo/sentinel/tsconfig/react` · `.../tsconfig/nest` ·
+  `.../tsconfig/node`. tsc resolves `extends` through the `exports` map.
+- **oxlint, as physical paths at the package root**: `oxlint/react.json`, `oxlint/nest.json`,
+  `oxlint/node.json`, `oxlint/svelte.json`, referenced as
+  `./node_modules/@hublo/sentinel/oxlint/<preset>.json`. Oxlint resolves every `extends`
+  entry as a PATH and never as a package specifier, so it never consults `exports` and the
+  physical layout IS the contract. The same is true of `jsPlugins`, which is why the local
+  Hublo plugin ships beside them in `plugins/`.
+
+Presets for the remaining tools land with their own ticket.
 
 ## FAQ