@hublo/sentinel 1.3.0 → 1.4.0-alpha.2

package/docs/format-adoption.md

@@ -0,0 +1,321 @@
+# Format adoption cheat sheet
+
+Migrating one module from Prettier to oxfmt, through sentinel. For linting see
+[`lint-adoption.md`](lint-adoption.md), for TypeScript
+[`typescript-adoption.md`](typescript-adoption.md).
+
+## Adopt a module
+
+Run from the **module's own directory**.
+
+```bash
+cd apps/.../<module>
+npx --yes @hublo/sentinel@<version> --init --preset <react|nest|node|svelte>
+pnpm install
+```
+
+`--init` with no target adopts every role, and that is the intended order: lint fixes what it
+can, then the formatter runs **last** and formats everything every role wrote. Adopting the
+formatter alone is `--init --format`.
+
+**`--init` reformats your module.** That is deliberate: adoption that leaves a module failing
+its own new format check is not adoption, it is a chore handed to someone else. Commit it on
+its own, so the reformat is one reviewable diff rather than noise on top of a real change.
+
+> **Order matters, and `--init` with no target gets it right for you.** The linter's autofix
+> rewrites code, and sentinel writes JSON in its own style, so **formatting has to come after
+> linting**, never before. Run whole-module `--init` and it happens automatically: format runs
+> LAST, over everything every role wrote. If you adopt roles one at a time, run
+> `sentinel --init --format` after `sentinel --init --lint`, or your first `pnpm run lint`
+> fails at a formatting step that has nothing to do with linting.
+
+## What `--init` does
+
+| It writes                       | Why                                                                          |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| `.oxfmtrc.json`                 | the preset's options, **materialized**, plus anything your module differs on |
+| `format` / `format:fix` scripts | `format` is the CHECK (what CI runs), `format:fix` writes                    |
+| the nx `format` target          | with the config as an input, so a preset change invalidates the cache        |
+| `@hublo/sentinel` devDependency | pinned, so the CLI resolves                                                  |
+
+| It removes                          | Why                                                                                                |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| your `.prettierrc*`                 | adoption REPLACES Prettier; two configured formatters means whichever the runner picks wins        |
+| your module's Prettier dependencies | they served that config. The **root** keeps its tooling, which every unmigrated module still needs |
+
+Any other script that called `prettier` is rewritten too (a `format:check` left pointing at a
+removed binary fails the first time someone runs it, not at adoption when it would be obvious).
+Only the prettier segment is replaced, so `svelte-kit sync && <format> && eslint .` keeps its
+other commands.
+
+## Commands
+
+Every verb, for every role, plus scoping a run to some files and what a fully adopted module
+looks like: [`using-sentinel.md`](using-sentinel.md).
+
+## Why this config is not a one-line stub
+
+Every other role commits a stub that `extends` a preset shipped inside the package. **oxfmt has
+no `extends`, and it ignores unknown top-level keys silently.** A stub like
+
+```json
+{ "extends": ["./node_modules/@hublo/sentinel/oxfmt/base.json"] }
+```
+
+parses fine, reports as adopted, and formats with oxfmt's **defaults** (double quotes,
+semicolons). Verified: under that stub a file in this repo's style fails the check and a file
+in oxfmt's default style passes. Shipping it would have rewritten the whole monorepo into a
+style nobody chose.
+
+Note that `base` here **is** a preset you name, unlike the other roles. Formatting does not
+vary by stack: the repo has always formatted Nest, React, Svelte and tooling from one root
+`.prettierrc`, so there is one style and `base` is it (`svelte` and `nest` are that same style
+with one option flipped). In the lint, typescript and build roles the shared layer is called
+`shared.json`, is never published, and is not something a module names.
+
+So the preset's values are written INTO your config. Two things follow:
+
+- Your editor's oxfmt extension reads this file, so format-on-save agrees with CI.
+- A preset change does **not** reach you by reinstalling. It needs a re-`init`.
+  `sentinel --inspect --format` from the root reports which modules are behind.
+
+## Keeping your module's own formatting
+
+The preset carries the repo's formatting. If your module genuinely differs, that is recorded
+rather than overwritten: adoption reads your Prettier config and carries what it finds. Three
+modules in this repo already differ (tabs at 100 columns, semicolons), and reformatting them
+on the way past would have destroyed the adoption diff.
+
+An override lives in the config and is DECLARED in `$sentinel.local`:
+
+```json
+{
+  "$sentinel": { "preset": "base", "version": "1.1.0", "local": ["printWidth", "useTabs"] },
+  "printWidth": 100,
+  "useTabs": true,
+  "semi": false
+}
+```
+
+A re-`init` keeps exactly the keys listed in `local` and refreshes the rest. Adding an override
+by hand means adding the key **and** listing it there; a value that differs without being
+declared is reported as drift, because nobody said this module should format differently.
+
+`ignorePatterns` and `overrides` are always yours and never need declaring.
+
+A setting is carried only if oxfmt accepts the **value**, not just the key: what it rejects is
+dropped and named in the adoption output (see "What did not survive the move"). The check asks
+oxfmt's own shipped schema, so it stays true across oxfmt releases.
+
+### What sentinel adds to `ignorePatterns`, and why
+
+Prettier ran from the workspace **root**, so the root `.prettierignore` governed every file in
+the repo. oxfmt reads `.gitignore` and `.prettierignore` from its **current directory**, and
+sentinel runs it in your module, so the root file is simply not seen.
+
+Left alone that silently widens what gets formatted, and oxfmt's reach is wider than
+Prettier's was here: it formats markdown, YAML, HTML, CSS **and Handlebars**. The root file
+excludes `**/*.md` and `**/*.hbs` among others, so the first `format:fix` would have
+reformatted every README and rewritten Handlebars templates as HTML.
+
+So `--init` reads the root file and carries forward the patterns that were already reaching
+into your module: those with no slash (`node_modules`), and those anchored at the root but
+spanning any depth (`/**/*.md` becomes `**/*.md`). Root-only patterns like `/dist` are
+**not** carried, because they never applied inside a module and carrying them would ignore
+more than before.
+
+Your module's own `.prettierignore` is left exactly as it is: it sits in the module
+directory, so oxfmt already reads it.
+
+### And your module is excluded from the ROOT Prettier
+
+The mirror of the same problem. The root Prettier still owns every file in the repo, and it
+does not know your module now formats itself, so `nx format:write` or `prettier --write .`
+from the root would reformat your module back to the ROOT's style, and your next
+`pnpm run format` would reverse it. Whichever ran last wins, which is precisely the state
+adoption removes inside a module.
+
+So `--init --format` adds one line to the root `.prettierignore`:
+
+```
+# @hublo/sentinel: modules formatted by oxfmt, not by the root Prettier
+/apps/front/your-module/
+```
+
+This is the only file outside your module that adoption touches, and it is the same
+deliberate exception the workspace prep already makes. The root Prettier config itself is
+untouched: it still serves every module that has not migrated.
+
+## Svelte modules
+
+Svelte is the one preset with a formatting difference, and it is not a style. oxfmt reads
+`.svelte` files only when its `svelte` option is on (its default is **disabled**), so on the
+base preset a Svelte module adopts cleanly, exits 0, and quietly stops formatting the files it
+is mostly made of. `--preset svelte` materializes the same style with `"svelte": true`:
+
+```json
+{
+  "$sentinel": { "preset": "svelte", "version": "1.1.0", "local": [] },
+  "printWidth": 80,
+  "svelte": true
+}
+```
+
+Prettier said the same thing through `prettier-plugin-svelte`, which adoption removes, so this
+carries your formatting across rather than adding to it. oxfmt does not bundle the Svelte
+compiler: it requires `svelte` from your module, which every Svelte module has.
+
+## What did not survive the move
+
+Adoption reads your Prettier config and reports, per module, what it could not carry. Across
+this repo that is:
+
+- **`endOfLine: "auto"`**: oxfmt accepts `lf`, `crlf` and `cr` only. It always writes LF, which
+  is what git stores anyway. Carried verbatim it produced a config oxfmt refuses to parse, so a
+  value oxfmt rejects is now dropped and reported rather than written.
+- **`prettier-plugin-gherkin`**, a real loss: `.feature` files stop being formatted. They are
+  not source, no check enforces their formatting today, and oxfmt has no plugin API to carry
+  it. Accepted, and written down here rather than discovered later.
+- **`prettier-plugin-svelte`**, which is NOT a loss: `--preset svelte` covers it (above), and
+  adoption says so rather than listing it as dropped.
+
+Prettier `overrides` are translated, not copied: `files` is a string in Prettier and a list in
+oxfmt, and an override whose only option was a `parser` (a plugin concept) is dropped whole
+rather than written empty.
+
+`sortPackageJson` is switched **off**. Left on, the first `format:fix` in every module reorders
+its `package.json` into a diff nobody can review beside the adoption itself.
+
+## Import ordering: on for nest, off for the front
+
+Since 1.1.3, **adoption reformats your module; whether it also reorders your imports depends
+on your stack**, because the two stacks were in genuinely different positions.
+
+| Preset                                          | Import ordering | Why                                                                                                                                         |
+| ----------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nest`                                          | **on**          | `import/order` is enforced in `eslint.config.back.js`. Turning it off would remove a check you have today                                   |
+| `react`, `react-lib`, `node`, `svelte`, `tools` | **off**         | The front and root ESLint configs order nothing. You never had the check, and adoption should not charge you thousands of files to gain one |
+
+### Where the number came from
+
+Share of reformatted files whose diff touches **only** the import block, on 1.1.2:
+
+| Module              | Files reformatted | Import-block only |
+| ------------------- | ----------------: | ----------------: |
+| `host-admin`        |             2,670 |   **2,374 (89%)** |
+| `bff-admin`         |             1,740 |   **1,590 (91%)** |
+| `hr-management`     |               303 |     **290 (96%)** |
+| `libs/front/shared` |                13 |           7 (54%) |
+
+The two halves had different causes, which is why they get different answers.
+
+**The front had no ordering at all**, so sorting moved almost every import. Off is also
+oxfmt's own default, so `base` now simply stops overriding it. Written as
+`"sortImports": false` rather than omitted, so the config states the decision.
+
+**Nest was already ordered, and its churn was not sorting.** Of bff-admin's 1,740 changed
+files, **1,687 differed by one blank line** and only 3 by a real reordering. ESLint grouped the
+workspace scopes (`@hublo/**`, `@shared/**`, ...) as _internal_; oxfmt reads them as
+_external_, so two groups collapsed into one and the line between them disappeared.
+
+The `nest` preset restores the grouping with `customGroups`:
+
+```json
+"sortImports": {
+  "customGroups": [
+    { "groupName": "workspace",
+      "elementNamePattern": ["@hublo/**", "@shared/**", "@front/**", "@network/**"] }
+  ],
+  "groups": ["builtin", "external", "workspace", ["parent", "index"], "sibling"],
+  "newlinesBetween": true
+}
+```
+
+Measured on bff-admin: **1,740 changed files down to 91**, of which 43 are genuine ordering
+fixes worth having and 48 are formatting.
+
+`internalPattern` looks like the option for this and is not: in oxfmt 0.63.0 setting it
+collapses the external and internal groups into one whatever the pattern (a pattern matching
+only `zod` produced the same single block as one matching only `@hublo/`). `customGroups` is
+the one that works.
+
+### Turning ordering on for a front module
+
+One line, and it is worth doing in a commit of its own:
+
+```jsonc
+// .oxfmtrc.json
+{
+  "sortImports": true,
+}
+```
+
+Declare it in `$sentinel.local` so a re-`init` keeps it, then run `pnpm run format:fix` and
+expect most of the module to be touched.
+
+### Finding the modules that do not check it
+
+`sentinel --inspect --format` reports it, per module, under **not checked at all**:
+
+```console
+  ✓ host-admin (react) format — adopted=true preset=base conformant=true
+      not checked at all:
+        • sortImports — import order is not checked here. Enable it with `"sortImports": true` …
+```
+
+The gap is reported rather than warned on every run: it is a state of the module, not an
+event. A message that fires on every `pnpm run lint` is a message people stop reading.
+
+### The one grouping difference, and why it stands
+
+`import/order` explicitly listed this repo's 14 workspace scopes (`@hublo/**`, `@shared/**`,
+`@front/**`, `@network/**`, and the rest) as **internal**. oxfmt classifies them as
+**external**, because to a formatter they look like any other scoped package. `@/...` is
+still recognised as internal, and builtins and relative imports are unaffected.
+
+So on adoption, imports of workspace packages move from the internal group up into the
+external one. It is cosmetic, it happens once, and it is part of the reformat commit.
+
+It is not fixed by configuration, and that was checked rather than assumed. oxfmt's
+`sortImports` accepts an `internalPattern` key, but in 0.63.0 setting it **collapses the
+external and internal groups into one**, whatever the pattern: a pattern matching only `zod`
+produced the same single block as a pattern matching only `@hublo/`. The default behaviour
+keeps three distinct groups and is the better of the two, so sentinel does not set it. If a
+later oxfmt implements it properly, one line in the preset restores the old grouping and
+`--inspect` will report every module as behind until they re-`init`.
+
+## Troubleshooting
+
+| Symptom                                            | Cause                                                                                                        |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `could not find the oxfmt binary`                  | oxfmt ships with sentinel; the module needs `pnpm install`                                                   |
+| `no sentinel .oxfmtrc.json in this module`         | not adopted yet (an `.oxfmtrc.json` you wrote yourself is not adoption, `--init` records provenance)         |
+| `--inspect` says the module has **drifted**        | a preset-owned value was edited without declaring it in `$sentinel.local`, or the preset moved on. Re-`init` |
+| `pnpm run format` fails on files you did not touch | the module was adopted but never formatted. Run `pnpm run format:fix` as its own commit                      |
+| `.feature` files lost their formatting             | expected, see above                                                                                          |
+
+### `TS(1098): Type parameter list cannot be empty` (and friends)
+
+oxfmt refuses to format a file it cannot parse, and its TypeScript parser is stricter than
+Prettier's. **Two files in the whole monorepo** are affected, both `.d.ts`, both genuine
+TypeScript errors that Prettier recovered from:
+
+| File                                            | Error                                        | Fix                                        |
+| ----------------------------------------------- | -------------------------------------------- | ------------------------------------------ |
+| `apps/front/hr-management/src/app.d.ts`         | `TS(1098)` `interface HTMLAttributes<>`      | delete the empty `<>`                      |
+| `libs/front/theme/types/breakpoints/index.d.ts` | `TS(1039)` an initializer in an ambient file | it holds a value, so it belongs in a `.ts` |
+
+This is debt the migration surfaces rather than causes, and it is yours to fix: a formatter
+cannot invent the missing syntax, and silently adding the file to `ignorePatterns` would be the
+tool deciding to stop checking your code without telling you.
+
+You will not have to go looking. `--init` names each file, its line and the reason, and says
+that `pnpm run format` fails until they are fixed. It still exits 0: adoption itself worked, and
+a module reported as un-adopted gets reverted for no reason.
+
+### `.svelte files are not formatted yet`
+
+Expected on the first adoption of a Svelte module. oxfmt does not bundle the Svelte compiler, it
+loads it from your module, and `npx --yes ... --init` writes the config before any install has
+happened. Run `pnpm install`, then `pnpm run format:fix` — both of which adoption tells you to
+run anyway.

package/docs/lint-adoption.md

@@ -0,0 +1,290 @@
+# Lint adoption cheat sheet
+
+Migrating one module from ESLint to Oxlint, through sentinel. For the formatter see
+[`format-adoption.md`](format-adoption.md), for TypeScript
+[`typescript-adoption.md`](typescript-adoption.md); each is a separate role and can adopt
+independently.
+
+## Adopt a module in two steps
+
+Run from the **module's own directory**. You do not need sentinel installed to run it.
+
+```bash
+cd apps/.../<module>
+npx --yes @hublo/sentinel@<version> --init --preset <react|nest|node|svelte>
+pnpm install
+```
+
+Then run `pnpm run lint`.
+
+`--init` with no target adopts **every role sentinel ships**, and for lint that is the
+intended way round: it runs the linter's autofix, then writes the format config and formats
+the module, so the files it generated are already in your module's style. Adopting lint
+ALONE (`--init --lint`) leaves you to format them yourself.
+
+`--init` fixes what a machine can fix, once. It does not loop, and it does not edit your code
+beyond what the tools' own fixers do. What is left afterwards is real debt: see
+[Reading the numbers](#reading-the-numbers).
+
+> **Order matters, and `--init` with no target gets it right for you.** The linter's autofix
+> rewrites code, and sentinel writes JSON in its own style, so **formatting has to come after
+> linting**, never before. Run whole-module `--init` and it happens automatically: format runs
+> LAST, over everything every role wrote. If you adopt roles one at a time, run
+> `sentinel --init --format` after `sentinel --init --lint`, or your first `pnpm run lint`
+> fails at a formatting step that has nothing to do with linting.
+
+## What `--init` does
+
+| It writes                       | Why                                                                                    |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `.oxlintrc.json`                | a stub that `extends` the shipped preset, plus the ignore patterns (see below)         |
+| `lint` script                   | so `pnpm run lint` and the nx target cannot disagree about which linter runs           |
+| the nx `lint` target            | replaced, not merged: the ESLint executor's options mean nothing to a different runner |
+| `@hublo/sentinel` devDependency | pinned, so the preset resolves                                                         |
+
+| It removes                        | Why                                                                                                |
+| --------------------------------- | -------------------------------------------------------------------------------------------------- |
+| your `eslint.config.*`            | adoption REPLACES ESLint; two configured linters means whichever the runner picks wins             |
+| your module's ESLint dependencies | they served that config. The **root** keeps its tooling, which every unmigrated module still needs |
+
+**It then runs the autofix once, and tells you what that did.** Adoption enforces rules your
+module may have had switched off, and the fixer acts on them immediately, so this is the step
+that can change your source:
+
+```console
+  fixing what lint can fix automatically...
+  the lint autofix rewrote 12 files: src/a.ts, src/b.ts and 10 more. Review the diff
+  before committing: rules this module used to have switched off are enforced from now on.
+```
+
+It says `changed nothing` when there was nothing to do, and says so explicitly when the pass
+**could not run** at all, which used to be silent: neither the exit status nor the output
+stream distinguishes "your config did not load" from "here are your remaining violations", so
+a module could look adopted while nothing had been checked.
+
+It also **rewrites suppression comments** that a plugin rename would otherwise void. A hosted
+plugin can be registered under a different name than ESLint knows it by (`@nx/eslint-plugin`
+is hosted as `nx`), and every rule id changes with it, so `// eslint-disable @nx/...` would
+silently stop suppressing while the findings it held back reappear. One stale comment produced
+80 phantom warnings during the proof of concept. Same for `@next/next/*`, which oxlint ships
+natively as `nextjs/*`.
+
+**Import ordering is not a lint rule here.** `import/order` moved to the format role: oxfmt
+rewrites the whole import block, so it sorts a file completely in one pass, where a lint fixer
+emits edits over overlapping ranges and needs several. `eslint-plugin-import` is no longer
+hosted at all, since its only other rule (`no-duplicates`) is native in oxlint.
+
+### Why `ignorePatterns` is in your config and the rules are not
+
+The rules stay in the preset, so changing them reaches every module by reinstalling. Ignore
+patterns cannot work that way: oxlint does **not** inherit `ignorePatterns` through `extends`
+(verified), so a preset declaring them gives them to nobody.
+
+Sentinel used to compensate by passing `--ignore-pattern` flags whenever it ran oxlint. That
+made the committed config correct only while sentinel was the thing running it. Everything
+else read the file and linted your build output:
+
+```console
+$ oxlint -c .oxlintrc.json .            # what your IDE effectively does
+dist/built.js:1:1              error eslint(no-var)
+node_modules/junk/bad.js:1:1   error eslint(no-var)
+```
+
+So they are written into your module's config. Your own patterns are carried across from the
+eslint config on top of the defaults, minus any that merely restate one (`dist/**` beside
+`**/dist/**`).
+
+If `--run --lint` warns that your config declares no `ignorePatterns`, it was written by an
+older sentinel: re-run `sentinel --init --lint`.
+
+## Commands
+
+Every verb, for every role, plus scoping a run to some files and what a fully adopted module
+looks like: [`using-sentinel.md`](using-sentinel.md).
+
+## Presets, and the one you don't choose
+
+Declare the stack: `react`, `nest`, `svelte`, or `node` (the stack-less base, for a module
+that belongs to no stack).
+
+**React has two tiers, and you do not pick them.** `apps/**` gets the application set, `libs/**`
+gets the library set, because that is a structural fact of the workspace rather than a
+judgement call. They differ by 96 rules, 61 of which are accessibility: an app shell has a
+user to be accessible to, a component library does not, and a library instead runs rules an
+app has no use for (`nextjs/*`, `jest-dom/*`, and the `storybook/*` rules that apply only to
+`*.stories.*`).
+
+Always pass `--preset` in a monorepo. Dependencies are hoisted, so detection honestly answers
+`node` for a React app that declares no `react` of its own.
+
+### Your module extends exactly one of them
+
+There is nothing to stack. Every preset already contains the shared rule layer, flattened in
+at build time, so the file you extend is self-contained:
+
+| preset      | rules | of which shared by every stack |
+| ----------- | ----- | ------------------------------ |
+| `react`     | 188   | 21                             |
+| `react-lib` | 134   | 21                             |
+| `nest`      | 110   | 21                             |
+| `svelte`    | 81    | 21                             |
+| `tools`     | 67    | 21                             |
+| `node`      | 21    | 21 (the shared layer alone)    |
+
+The layer lives in the repo as `src/roles/lint/presets/shared.json` and is never published on
+its own. If you are reading the source, that file is ours, not something a module names.
+
+### If a rule you need is missing
+
+Tell us and it goes in the preset, where every module gets it. That is the whole point of
+sentinel: the rules were the same in module after module, each copy free to drift, and they
+now live in one place.
+
+If your team genuinely needs something the preset should not impose on everyone, declare it as
+a **layer above the preset**, the way the planning team did:
+
+```json
+{ "extends": [".../lint/nest.json", "./team-rules.json"] }
+```
+
+Order matters, sentinel's preset first, or your layer cannot override anything. `--inspect`
+reports the layer so it stays visible.
+
+Think of it as a queue rather than a fork: a rule promoted into the preset is deleted from the
+layer. It is the exact mirror of `.oxlintrc.baseline.json`, which holds rules **below** the
+preset and empties as debt is fixed, while a layer holds rules **above** it and empties as they
+are adopted.
+
+**Wire your layer before your first `--init`, not after.** `--init` prefixes the preset onto
+whatever `extends` it finds, so a layer already there survives and is respected by the autofix
+that follows. Added afterwards, the autofix has already run, and nothing undoes what it
+rewrote. One team met this as twelve rewritten files.
+
+## What a preset does not enforce
+
+Every unenforced rule carries a reason, readable with `sentinel --inspect --lint`:
+
+| State                         | Meaning                                                                        |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| **not enforced, by decision** | it argues with a deliberate architectural choice, or only false-positives here |
+| **reported, not blocking**    | it runs and reports; it just cannot fail a build, so the debt stays visible    |
+| **uncovered**                 | oxlint cannot run it at all, so it can be neither enforced nor switched off    |
+
+`uncovered` is the one to read before adopting, because it is the only state where a check you
+had simply stops existing. The clearest case is `no-restricted-syntax`: oxlint has no such
+rule, so AST-selector guards cannot be carried across as configuration. This repo's eight
+frontend selectors were rewritten as real rules in sentinel's own `hublo` plugin, which the
+React tiers host. A Nest service that had architectural guards of its own has nowhere for them
+to land yet, and one adopter lost two that way before noticing.
+
+If that is your module, tell us which guards you rely on and they ship in the `hublo` plugin
+alongside the frontend ones. A house rule copied per module drifts, which is what sentinel
+exists to stop.
+
+The governing rule for both: **adoption never turns a green module red.** A rule that would
+newly fail is held at `warn`, visibly and with its reason, even when the previous
+configuration was wrong or was not really running. You were green on Tuesday; you do not
+arrive to a red build on Wednesday for code that was already there.
+
+### How that promise is kept, since 1.1.1
+
+Two mechanisms, and the second exists because the first is not enough on its own.
+
+The **preset** holds back rules measured as newly-failing across the repository. That is
+correct on the day it is measured and decays from then on: the repository keeps moving, and a
+commit landing afterwards can violate a rule the preset recorded as clean. The failure then
+arrives for whoever adopts LAST, on code they did not write. It happened: `host-admin` adopted
+green on 1.1.0 and red a week later, on `jsx-a11y/no-noninteractive-tabindex` and
+`typescript/no-duplicate-type-constituents`, neither of which the repo's ESLint had ever
+enforced.
+
+So `--init` also measures **your module**, after the autofix pass, with type information, and
+writes what it already violates to `.oxlintrc.baseline.json`:
+
+```jsonc
+{
+  "rules": {
+    // 1 violation when this module adopted
+    "jsx-a11y/no-noninteractive-tabindex": "warn",
+  },
+}
+```
+
+Your `.oxlintrc.json` extends it after the preset, which is what lowers the severity. Four
+things follow, and they are the point:
+
+- the rules still **run and still report**, they just cannot fail the build for code that
+  predates the migration. A hold is never `off`;
+- the file is **regenerated, not accumulated**. Fix the last violation, re-run
+  `sentinel --init --lint`, and the rule drops out and returns to the preset severity;
+- your own config stays `extends` + `ignorePatterns`, so a rule **you** change by hand is
+  still reported as drift and is never confused with a hold sentinel made;
+- `--init` says what it held and how many violations each hold covers, so the debt is
+  announced rather than discovered.
+
+Do not edit `.oxlintrc.baseline.json` by hand. Commit it: it is part of the adoption, and it
+is what makes the promise above true on the day you adopt rather than on the day the preset
+was built.
+
+A small number of rules cannot be carried at any severity, because oxlint validates rule and
+plugin names when it _parses_ a config: naming one it does not know makes the config fail to
+parse and the module lints **nothing**. Those are documented in the README rather than
+silently dropped.
+
+## Ask the linter your own question
+
+Everything after `--` goes to oxlint:
+
+```bash
+sentinel --run --lint -- --deny-warnings     # what would zero warnings take?
+sentinel --run --lint -- --max-warnings 100  # hold a ceiling while you pay debt down
+```
+
+A run with extra options says so on every line of output and carries `toolArgs` in the
+`--json` envelope, because these options can weaken a check as easily as strengthen it, and
+`--run` is what CI calls. Never put one in a committed `lint` script.
+
+## Reading the numbers
+
+```console
+$ sentinel --run --lint --json --max-diagnostics 2
+{
+  "results": [
+    {
+      "project": "hr-management",
+      "adopted": true,
+      "errors": 0,
+      "warnings": 72,
+      "rules": [
+        { "rule": "no-explicit-any", "severity": "warning", "count": 54 },
+        { "rule": "no-unused-vars", "severity": "warning", "count": 15 }
+      ],
+      "diagnostics": [{ "file": "src/…/index.ts", "line": 91, "col": 37, "rule": "no-explicit-any", … }],
+      "diagnosticsTruncated": true
+    }
+  ]
+}
+```
+
+The `rules` breakdown is the useful part: a total tells you a module is dirty, a per-rule
+count tells you which rule to fix first, and across the fleet, which rule to fix everywhere.
+The numbers come from oxlint's own JSON, not from parsing what it prints for humans.
+
+## Troubleshooting
+
+| Symptom                                                    | Cause and fix                                                                                                                                                                                                                       |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pnpm run lint` fails on **Prettier** right after adopting | you adopted lint alone, so the files sentinel generated are not in your module's format. Run `sentinel --init --format` (or your formatter) on them                                                                                 |
+| `Plugin 'x' not found` / `extends … does not exist`        | the preset path assumes pnpm's isolated layout. Run `pnpm install` in the module; if the workspace switched to a hoisted linker, that breaks every adopted module at once                                                           |
+| A file that was never linted now reports errors            | your ESLint config ignored it. `--init` carries your module's `ignores` across, but it **cannot read a computed one** (e.g. `includeIgnoreFile(gitignorePath)`) and says so when it hits one. Add what you need to `ignorePatterns` |
+| `error: Unexpected token` in a `.svelte` file              | oxlint reads a `<script>` block as JavaScript unless it declares `lang="ts"`. Add it, or ignore the file                                                                                                                            |
+| Type-aware rules seem not to run                           | they need `oxlint-tsgolint`, which ships with sentinel. `sentinel --inspect --lint` reports `typeAware` so you can check rather than assume                                                                                         |
+| A `eslint-disable` comment stopped working                 | its rule was renamed by a plugin alias. `--init` rewrites the ones it knows; `--inspect` lists the renames a preset causes                                                                                                          |
+
+## Svelte, specifically
+
+Oxlint parses a `.svelte` file's `<script>` block and **not its template**. Fourteen
+`svelte/*` rules therefore cannot run at all, whatever the config says, including
+`svelte/no-at-html-tags`, an XSS guard that fires on the modules today. Adding a Svelte
+plugin does not help: the missing piece is the parser. This is documented rather than hidden,
+and it is the honest cost of the migration for those two modules.

package/docs/performance.md

@@ -0,0 +1,49 @@
+# Performance baseline
+
+Numbers so a regression is something you can see rather than argue about. Reproduce with:
+
+```bash
+pnpm build && pnpm bench <workspace-root>
+```
+
+Recorded against the Hublo monorepo (**441 nx projects**, ~2900 source files in the largest
+module) on an Apple Silicon laptop, sentinel `1.1.0-alpha.4`. Machine, disk and cache state all
+move these, so compare **ratios to this table**, not absolute milliseconds. A number that
+doubles is a finding; a number that moves 30% is a different laptop.
+
+| What                                              |    Baseline | Why it is measured                                                                                          |
+| ------------------------------------------------- | ----------: | ----------------------------------------------------------------------------------------------------------- |
+| `--version`                                       |   **33 ms** | the floor under every command. If this grows, everything grows                                              |
+| `--inspect --lint` in one module                  |   **35 ms** | sentinel's own overhead: config reads, no tool spawned                                                      |
+| `--inspect --lint --json` across the workspace    | **1300 ms** | what the migration status page runs, and the only command whose cost grows with the repo. ~3 ms per project |
+| `--run --format` (144 files, sentinel's own repo) |  **291 ms** | oxfmt doing real work                                                                                       |
+| `--run --lint` (one module)                       |  **~1.3 s** | dominated by oxlint, including its type-aware pass                                                          |
+
+## Measured separately
+
+**The source probe** (`hasSourceFiles`, which decides whether a role has anything to do) is not
+in `pnpm bench`: timing it would mean exporting it from the package's public entry point, and
+widening the published surface to benchmark something is the wrong trade. Measured directly:
+
+|                                                     |             |
+| --------------------------------------------------- | ----------: |
+| `apps/front/host-admin` (4210 files), match found   | **0.11 ms** |
+| `libs/api-types` (2001 files), match found          | **0.44 ms** |
+| worst case: exhaust a 2001-file tree, match nothing |   **47 ms** |
+
+It stops at the first match and never descends into `node_modules` or build output, which is
+where the difference comes from: a `**` glob over the same tree measured **515 ms** against
+**2 ms** bounded.
+
+## What is deliberately not optimised
+
+`readOwnPackage()` walks up the filesystem and re-parses sentinel's own manifest at each of its
+call sites, with no memo. At this scale it is invisible, and a module-level cache is a footgun
+in tests. If the whole-workspace scan ever becomes a problem, measure before assuming this is
+why.
+
+## If a number regresses
+
+Take the ratio, not the difference. The scan is the one to watch: it is per-project work, so a
+change that adds one file read per module costs 441 of them. The probe is the other, because it
+runs on every `--init` and its worst case is unbounded by anything except the tree it walks.