@hublo/sentinel 1.5.0-alpha.21 → 1.5.0-alpha.23

package/docs/static-analysis-adoption.md

@@ -0,0 +1,195 @@
+# Static analysis adoption cheat sheet
+
+A quick reference for adopting the sentinel static analysis role on a module, and for reading what it prints. The reasoning behind every number, and the measurements that fixed the thresholds, are in [`static-analysis-study.md`](static-analysis-study.md); this page is what you need to run it.
+
+**It measures, it never refuses.** Nothing here fails a build or blocks a merge. A figure answers "is this module drifting", which is a question about a trend, and a check that blocks a merge on a trend blocks the wrong thing. Refusing a single unit is the linter's job and oxlint already does it.
+
+## Adopt a module in two steps
+
+Run from the **module's own directory**. You do not need to install sentinel first: use `npx --yes` for a one-off.
+
+```bash
+# 1. write the module's config + the pinned devDependency
+cd apps/.../<module>
+npx --yes @hublo/sentinel@<version> --init --static-analysis
+
+# 2. fetch what step 1 declared
+pnpm install
+```
+
+`--init` writes `static-analysis.config.mjs`, adds the three scripts below to the module's `package.json`, and pins `@hublo/sentinel` into its own `devDependencies`. It prints what it did:
+
+```
+  wrote static-analysis.config.mjs
+  wrote package.json
+  added the three `static-analysis` scripts and static-analysis.config.mjs; declare
+  this module's entry points and journeys there, everything else comes from the role
+```
+
+**Nothing else is required.** The config stub is written with empty `entry` and `journeys` on purpose: for most modules the figures are already right without declaring anything, and the stub exists so you can correct the one case where they are not (see [Declaring entry points](#declaring-entry-points)).
+
+## Verbs at a glance
+
+| Verb        | Who / when         | Runs the tools?   | What you get                                                           |
+| ----------- | ------------------ | ----------------- | ---------------------------------------------------------------------- |
+| `--run`     | dev, everyday      | **yes**           | the figures, in one of three shapes. Never exits non-zero on a finding |
+| `--inspect` | dev, everyday      | no (reads config) | the resolved settings, and whether this module has adopted             |
+| `--init`    | dev, once to adopt | writes files      | the config stub, the three scripts, the pinned dep                     |
+| `--migrate` | planned            | not available yet | reserved for changing an already-initialized setup                     |
+
+**Location** (any verb): from a module dir → that module; from the root → `--module <name>`, `--ci` (affected), or every module. `--init` writes, so it targets one module only.
+
+## Everyday use
+
+```bash
+pnpm run static-analysis         # the summary, in your terminal. Writes nothing
+pnpm run static-analysis:json    # static-analysis-report/static-analysis.json, for a machine
+pnpm run static-analysis:html    # static-analysis-report/static-analysis.html, for a reader
+```
+
+Or without the scripts:
+
+```bash
+sentinel --run --static-analysis                   # same as the first script
+sentinel --run --static-analysis --output html     # same as the third
+sentinel --inspect --static-analysis               # the settings, without running anything
+```
+
+**Which shape to use.** `console` is the one you run in a loop: it writes nothing and skips the expensive drawing. `json` is for CI and for a script. `html` is the one you open and send: it carries the findings, the places to look, and an explorable import graph.
+
+⚠️ The `html` shape pays for a graph layout that the other two skip, 5 seconds on the largest module measured against 14 ms for the rest of the graph pass. That is fine for a page somebody opens and wrong for a commit hook.
+
+## Reading the report
+
+The console summary of a nest microservice, in full:
+
+```
+sentinel static-analysis: contract
+    Duplicated lines                                       3.95 %
+    Clones                                             61 entries
+    Duplicated lines (tests)                              10.93 %
+    Clones (tests)                                    196 entries
+    Entry points                                  46 of 656 files
+    Unreachable lines                                      1.07 %
+    Unreachable files                                     5 files
+    Unused exports                                      1 exports
+    Unused symbols                                      1 symbols
+    Unused imports                                      0 imports
+    Complexity, worst function                27 max per function
+    Complexity 11-20, moderate risk          18 of 1386 functions
+    Complexity 21-50, high risk               1 of 1386 functions
+    Imports between files                  1135 between 495 files
+    Density                          0.0046 of the possible edges
+    Import cycles                               3 groups, 8 files
+    Communities                                   12 of 495 files
+    Modularity (Q)                                          0.753
+    Files the gauge read                 495 files the gauge read
+    Files with a complex function        18 files over 10, of 495
+    Files with deep nesting                4 files over 3, of 495
+    Long files                          43 files over 150, of 495
+    Files with a long function           5 files over 109, of 495
+    Files with a long function body      47 files over 10, of 495
+    Files with a wide signature           33 files over 3, of 495
+    Files with several classes            16 files over 1, of 495
+    Files hard to follow                  23 files over 7, of 495
+```
+
+Four groups, and they answer different questions:
+
+|                    | what it answers                                                                                                                                                               |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| duplication        | how much of this module repeats itself, product and tests counted apart                                                                                                       |
+| dead code          | what nothing reaches: files, exports, symbols, imports                                                                                                                        |
+| complexity         | two measures, on purpose: how hard the hardest functions are to TEST (McCabe) and how hard they are to FOLLOW (cognitive). They disagree on 60% of the files either one flags |
+| structure and size | how the files depend on each other, and which ones are outliers                                                                                                               |
+
+**Every row carries its denominator**, because none of them compares between modules without one: three breaches over 50 files and three over 3 000 are not the same module.
+
+**A row that is absent was not measured.** It is never a silent zero. When a pass cannot produce a figure, the report says so in its own line under the figures rather than printing `0.00%`, because "no dead code" and "the walk had no entry point" are different facts.
+
+### Three rows people misread
+
+**`Unreachable files` is not a delete list.** It means nothing in this module imports them. A file another module's spec imports is alive, and it has its own row, `Used only by tests`. For a library the question cannot even be answered inside the module, so the role leaves it (see below).
+
+**`Import cycles` reports GROUPS, not paths.** A group of six files can hold a dozen distinct circles, and breaking one does not necessarily break the group. The group is the unit precisely for that reason.
+
+**`Density` must not be compared between modules of different sizes.** Its denominator grows with the square of the file count, so a module gets a lower density by growing rather than by improving. Measured: `libs/nest/auth` 0.0216 at 101 files, `apps/front/host-admin` 0.0005 at 4 380. It is good for one module watched over time.
+
+### Where the size thresholds come from
+
+The nine size rows are measured with oxlint at thresholds this role fixes once for every module, so the same question gets the same answer everywhere. Each one is the **strictest of three candidates**: published research, our own p90, and the rule's own default.
+
+| row                               |     threshold | what decided it                                                                           |
+| --------------------------------- | ------------: | ----------------------------------------------------------------------------------------- |
+| `Files with a complex function`   |            10 | McCabe 1976 says 10, our p90 says 11                                                      |
+| `Files with a long function`      |           109 | our p90. IfSQ SP-1 says 150 and loses for being more permissive than our code             |
+| `Long files`                      |           150 | our p90 of 157, rounded down. No research sets a file's length                            |
+| `Files with deep nesting`         |             3 | IfSQ SP-2, and our p90 agrees                                                             |
+| `Files with nested callbacks`     |             3 | same nesting family                                                                       |
+| `Files with a long function body` | 10 statements | the rule's default, already the strictest candidate                                       |
+| `Files with a wide signature`     |  3 parameters | beyond three the fix is an object or currying, so this is a design boundary               |
+| `Files with several classes`      |             1 | the rule's floor                                                                          |
+| `Files hard to follow`            |             7 | Sonar publishes 15 for cognitive complexity and says no formula supports it; our p90 is 7 |
+
+⚠️ **These will disagree with your green lint, out loud.** The `nest` lint preset refuses `complexity` at 30 while this reports above 10, so a nest developer reads breaches beside a passing build. That is correct: the lint is the line your build refuses at, this is a gauge that answers the same question the same way in every module, including the ones that have not adopted lint at all. The report prints its thresholds under `measured with` so the two are never confused.
+
+## The `html` report
+
+Written to `static-analysis-report/`, two files:
+
+- `static-analysis.html`, self-contained: no CDN, no library, no font, nothing fetched. Open it from disk, attach it to a ticket, serve it from a CI artifact.
+- `static-analysis-graph.svg`, the import graph as a plain image, for when you want to paste a picture.
+
+The page carries what the console summary leaves out: every finding with its path, the code of each clone, and an **explorable import graph**. Point at a dot for its path and its two degrees, click it to keep only that file and its neighbours, click the background to come back. The drawing renders with scripting off; the script only adds the naming and the filtering.
+
+⚠️ `static-analysis-report/` is generated. The rule lives in the **root** `.gitignore`, unanchored so it matches at any depth, rather than one line added to every adopting module's own file. You have nothing to do and nothing to commit.
+
+## Declaring entry points
+
+`entry` names the files that **run although nothing imports them**. They are where reachability starts, and they are added to the patterns the role already ships rather than replacing them.
+
+Most modules need nothing. Declare an entry point when the framework loads a file by convention the role has not met, or when code is loaded by name at run time:
+
+```js
+import { defineStaticAnalysis } from '@hublo/sentinel/static-analysis'
+
+export default defineStaticAnalysis({
+  root: import.meta.dirname,
+  entry: ['src/emails/**'],
+  journeys: {},
+})
+```
+
+**The symptom that tells you one is missing**: a large, tightly-grouped block of unreachable files under one directory. Measured on `libs/cloud/hermes`, 228 of its 231 findings sit under `src/emails`, which holds templates loaded by name rather than imported. That is one line of config, not 228 deletions.
+
+## Two limits worth knowing before you read a number
+
+**A single-file component format cannot be parsed.** `.svelte`, `.vue` and `.astro` files are not read, so on a module holding them the role reports the duplication, complexity and size figures and **omits the graph and the dead-code figures entirely**, with the share printed in their place:
+
+```
+    (252 product file(s) in .svelte cannot be parsed, 53% of this module: no graph
+     and no dead-code figure is reported, because a file the role cannot open still
+     imports the files it imports)
+```
+
+Absent with its reason, rather than a figure that is wrong by half.
+
+**A library's dead code is decided outside the module.** An application has an entry point; a library has none, so a module-local walk would report "the module does not import itself", which is true of every library. The role builds a workspace-wide index of who imports what, once, and caches it under `node_modules/.cache/sentinel/`. Measured on `libs/nest/auth`: **15** unreachable files with the index against **87** without it.
+
+## Troubleshooting
+
+|                                                             |                                                                                                                                  |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| a wall of unreachable files under one directory             | an undeclared entry point, see above                                                                                             |
+| the graph and dead-code rows are missing                    | the module holds `.svelte`, `.vue` or `.astro`; the note above the figures says the share                                        |
+| `Entry points 0 of N`                                       | nothing matched, so the walk had no start. Declare `entry`                                                                       |
+| the numbers differ from another module's                    | check `measured with`: a setting this module moved is marked `(module)`, and two modules measured differently cannot be compared |
+| the run is slow                                             | you are on `--output html`, which pays the graph layout. Use the plain script in a loop                                          |
+| `oxlint could not be run, so no size indicator is reported` | the binary did not resolve; the size rows are absent rather than zero                                                            |
+
+## What the role will not do
+
+- **It will not fail your build.** No threshold here refuses anything, by design, for as long as adoption is incomplete. The only non-zero exits are an unknown `--output` value and a tool that could not be run at all, never a finding.
+- **It will not read your module's `.oxlintrc.json`.** The size gauge writes its own config to a temporary directory, so its scale is the same in every module. A gauge whose scale moves per module compares nothing.
+- **It will not look outside the module**, except for the one measurement that cannot be answered inside it: a library's reachability.
+- **It will not measure your tests.** Specs, fixtures, mocks, stories and generated files are out of every product figure. Duplication reports the test suite separately, on its own two rows, because that one is worth seeing and must not be blended into the product number.

package/docs/static-analysis-study.md

@@ -548,6 +548,13 @@ The related work carries two results that challenge the Complexity category: Her
 that most code complexity metrics correlate highly with LOC, and Moser et al. that process
 metrics outperform code metrics as fault predictors.
 
+### IfSQ
+
+The one standard found that attaches a citation to a numeric limit, and the only external source
+used to fix this role’s own thresholds. It is a human-inspection standard rather than a tool, so its
+table sits with the decision it serves, in **11.4**: three of its fifteen indicators carry a number,
+and none of them is about a file’s length.
+
 ---
 
 ## 6. The tool, measured rather than read
@@ -849,7 +856,14 @@ function is reported: sentinel 752 functions and 41 above 15, network 1 701 and
 1 050 and 6, console 510 and 0. Zero fatal errors on 4 572 files, where escomplex fails on 37.9%
 of `network` and 39.0% of `recruitment`. The worst module is this package.
 
-It is absent from oxlint 1.77, so it is written once here and used twice. See 9.5.
+⛔ **Corrected on 2026-10-13: it is not written here, it is LOADED.** oxlint 1.77 accepts an ESLint
+rule as a JS plugin, so Sonar's own rule runs inside our own pass with none of their code in this
+repository. The reasoning, the measurements and the licence that decides it are in **11.8**.
+
+⚠️ **The four figures above were produced with a version this document does not name**, and the
+plugin's behaviour moved between majors: sequences of `||` and `??` stopped incrementing. So treat
+them as an order of magnitude, not as a baseline. The figures measured on the current version, and
+what the metric actually adds beside McCabe, are in 11.8.
 
 ### 9.3 The maintainability figure
 
@@ -866,6 +880,8 @@ each one fires per 100 files, which is measured rather than judged:
 | `max-params`           |                   3 |           9.6 |
 | `max-nested-callbacks` |                  10 |             0 |
 
+⛔ **Superseded by 10.7, and closed by 11.6.** The two figures below, and the break they rest on, were measured on four modules before two defects in the gauge were fixed: diagnostics counted as breaches, and a population that included the test suite. Over 177 modules the same two rules measure 10.4 and 6.9 per 100 files against the next at 4.6, a ratio of 1.5 rather than 4.5. Section 11 then changed the thresholds themselves, and at those the most frequent rule reaches 11.0% of files against 10.7% for the next: there is no break left to split on, so `DESCRIPTORS`, `scored` and `described` are removed and every indicator counts.
+
 **Which are out, and why.** There is a break in the data, a factor of 4.5, not a line we drew:
 
 | kept as a descriptor     | per 100 files |
@@ -968,17 +984,18 @@ touch no production file at all and the median touches **4**.
 
 ### 9.7 What is still a decision
 
-| open                               | what it needs                                                                                    |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
-| the `/10` in the `MI`              | the distribution over the 198 modules. It changes the spread, never the order                    |
-| the criticality order of the seven | one argument per indicator. Rarity rules two out, it does not rank the rest                      |
-| the overhead line of the SQL study | the harness rebuilt. #90 corrects the attribution and withdraws the 71%, which was never a ratio |
-| the workspace index for libraries  | built and measured in 10.4 and 10.5. Nothing open here any more                                  |
-| a feedback channel on findings     | unchanged from section 8, and it is what would let any of this be proven wrong                   |
+| open                                  | what it needs                                                                                                                    |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| the `/10` in the `MI`                 | the distribution over the 198 modules. It changes the spread, never the order                                                    |
+| the criticality order of the **nine** | one argument per indicator. **Rarity no longer rules any out:** see 11.6, where the split is removed. Ranking them is still open |
+| the overhead line of the SQL study    | the harness rebuilt. #90 corrects the attribution and withdraws the 71%, which was never a ratio                                 |
+| the workspace index for libraries     | built and measured in 10.4 and 10.5. Nothing open here any more                                                                  |
+| a feedback channel on findings        | unchanged from section 8, and it is what would let any of this be proven wrong                                                   |
 
 The one measurement that unblocks the first two is the same: **the eight indicators over all 198
-modules, once.** Until then the figures in this section come from four modules and are quoted as
-such.
+modules, once.** That measurement now exists, in 10.7 over 177 modules and in 11 over a five-module
+bench, and it is what fixed the thresholds. The figures in THIS section still come from four modules
+and are quoted as such.
 
 ---
 
@@ -1173,7 +1190,357 @@ the binary failing. Measured: same 18 diagnostics either way, exit 1 against exi
 
 ---
 
-## 11. Sources
+### 10.7 The whole repository, measured, and what it does to 9.3
+
+Section 9.3 chose which indicators enter the maintainability figure by how often each fires per 100
+files, and excluded two of them on a **break of a factor 4.5** in that data. Those figures came from
+four modules, measured before two defects found while building the gauge were fixed. Here is the
+same question over **177 modules and 29 770 files**, with the gauge reading `src` only and counting
+a file once per indicator.
+
+| indicator                | per 100 files | modules above zero |
+| ------------------------ | ------------: | -----------------: |
+| `max-lines-per-function` |      **10.4** |                 75 |
+| `max-statements`         |       **6.9** |                 82 |
+| `max-params`             |           4.6 |                 69 |
+| `max-classes-per-file`   |           3.5 |                 53 |
+| `max-lines`              |           2.1 |                 59 |
+| `complexity`             |           0.8 |                 33 |
+| `max-depth`              |           0.0 |                 12 |
+| `max-nested-callbacks`   |           0.0 |                  0 |
+
+⛔ **The 4.5 break is gone, and it was an artefact of the measurement rather than a fact about the
+code.** Section 9.3 reported 46.9 and 42.9 for the two descriptors; the **same three modules**
+measured now give **14.4 and 7.7**. Two defects fixed tonight explain the direction and the order of
+magnitude:
+
+- diagnostics were counted where a breach is a (file, rule) pair. `max-nested-callbacks` fires once
+  per nesting level; measured, counting diagnostics inflates by **1.8x at the published thresholds
+  and 2.8x at lower ones**.
+- the population included the test suite, because `ignorePatterns` in oxlint's config is accepted
+  and silently ignored. Measured on `libs/front/components`: `max-lines-per-function` falls from
+  **33.6 to 23.9** per 100 files once the specs leave.
+
+What the clean data shows instead is a **smooth gradient**, consecutive ratios of 1.5, 1.5, 1.3,
+1.7, then 2.6 and finally 17.1 between `complexity` and `max-depth`:
+
+    max-lines-per-function  10.4  ->  max-statements  6.9   x1.5
+    max-statements           6.9  ->  max-params      4.6   x1.5
+    max-params               4.6  ->  max-classes     3.5   x1.3
+    max-classes              3.5  ->  max-lines       2.1   x1.7
+    max-lines                2.1  ->  complexity      0.8   x2.6
+    complexity               0.8  ->  max-depth       0.0  x17.1
+
+⚠️ **So the descriptor split now rests on nothing measured.** The two rules excluded from the figure
+are still the two most frequent, which is a reason to treat them with care, but 1.5x is not the 4.5x
+the decision was taken on, and inventing a cut here would be exactly the kind of threshold this
+document refuses elsewhere. The relative ORDER did survive: `complexity` below `max-lines` below
+`max-params` as before, with only `max-classes-per-file` moving up, from below `complexity` to above
+it.
+
+**This is left open rather than re-decided.** What the data supports today is one clean statement:
+`max-nested-callbacks` fires **nowhere** in the repository, and `max-depth` in 12 modules for 14
+files in all, so those two carry almost no information here whatever the figure does with them.
+
+---
+
+## 11. How each threshold was chosen
+
+Sections 9.3 and 10.7 left one question open: the gauge ran at the thresholds ESLint ships, which is
+not a choice, and 10.7 showed the one decision taken on those figures rested on a measurement
+defect. This section closes it. Every number in `GAUGE_THRESHOLDS` comes from one rule applied eight
+times, and the rule is stated before any figure so it cannot be fitted to a result afterwards.
+
+### 11.1 The rule: `min(research, our p90, the rule's default)`
+
+Three candidates per indicator, the strictest wins, and there is no fourth. The minimum is what
+makes it safe in **both** directions of failure, and both directions were observed here:
+
+- ⛔ **A threshold above what the code reaches detects nothing.** `max-nested-callbacks` shipped at
+  10 while the deepest chain in the repository is 4. It reported 0 files in 177 modules, for as long
+  as it existed. 10.7 recorded that as "carries almost no information"; the cause is simpler, the
+  scale was wrong.
+- ⛔ **Research can be more permissive than our own code, and then our code wins.** IfSQ's SP-1 puts
+  a routine at 150 lines. Our p90 is 109. Adopting 150 because a published standard says so would
+  relax a control to match a document, which is the opposite of measuring.
+
+A vendor default is a candidate, never a reference: it is shipped to fit every codebase, so it was
+calibrated on none. What it cost here is in 11.6.
+
+### 11.2 Three traps in deriving a threshold from our own distribution
+
+⚠️ **The p90 over the whole population collapses to 0 for four of the eight.** Ninety per cent of
+files never nest a block, never nest a callback, declare at most one class and take at most one
+parameter, so the percentile sits at the floor and a threshold of 0 flags everything. So "our p90"
+means **the p90 over the files the rule touches**, which is the only convention that does not
+collapse:
+
+| indicator              | p90 over all 8 083 files | p90 over the files it touches |
+| ---------------------- | -----------------------: | ----------------------------: |
+| `max-depth`            |                        0 |                             3 |
+| `max-nested-callbacks` |                        0 |                             3 |
+| `max-classes-per-file` |                        0 |                             5 |
+| `max-params`           |                        3 |                             4 |
+
+⚠️ **Rounding goes downward only.** `max-lines` derives a p90 of 157 and publishes 150. Rounding up
+would move a threshold away from the evidence that produced it, in the one direction the rule above
+exists to forbid.
+
+⛔ **The harness read seven of the eight message shapes.** oxlint parenthesises the measured value,
+`too many statements (20)`, except for `complexity`, which writes `has a complexity of 15`. A reader
+of the parenthesised form alone returns 0 for every complexity breach and says nothing about it: the
+first run of this bench reported **0 files above complexity 10, 15 and 20 alike**, which reads as
+"nothing to see" rather than as a broken instrument. The same defect sat in the role's own
+`valueOf`, where it was latent because no report row consumed the value yet. Both are fixed, and the
+regression test now uses the messages oxlint really emits rather than a paraphrase.
+
+### 11.3 The bench
+
+**8 083 product files over five modules**: `console` and `host-admin` (react), `front-components`
+(react library), `recruitment` and `network` (nest). The exclusion list is the role's own, so no
+spec, fixture, mock, story, generated or declaration file is in any figure below. Distributions come
+from one oxlint run per rule set with every maximum at 1, so each occurrence reports its real value
+instead of only its breach.
+
+### 11.4 What IfSQ gives, and what it does not
+
+IfSQ (ifsq.org) is the one standard found that states numeric limits with citations attached. It is
+a standard for **human inspection**: the level pages say what to look for, and `assessment.html`
+says who inspects, from self-assessment to third-party certification. There is no defect-density
+rule and no grade boundary anywhere on the site, checked page by page.
+
+**Three of its fifteen indicators carry a number:**
+
+| code     | indicator           | threshold                                      | citations given                                                                                                                                                                                                    |
+| -------- | ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **SP-1** | Routine Too Long    | > 150 lines, comments and blank lines excluded | IBM, "the most error-prone routines were those larger than 500 lines"; "when routines averaged 100 to 150 lines each, code was more stable"; "routines with 143 lines or less are 2.4 times less expensive to fix" |
+| **SP-2** | Nesting Too Deep    | > 3 levels of conditional nesting              | "few people can understand more than 3 levels of nested if statements". ⚠️ One finding page says "more than four" instead                                                                                          |
+| **SP-3** | Routine Too Complex | > 10 binary terms in conditionals              | McCabe 1976                                                                                                                                                                                                        |
+
+⛔ **IfSQ sources nothing about a FILE's length.** All three citations above are about routines. So
+`max-lines` has no research candidate at all, and its threshold is our p90 and nothing else.
+
+The remaining twelve state a defect to look for with no measurement: WIP-1 Vague "To Do", WIP-2
+Disabled Code, WIP-3 Empty Statement Block, SPM-1 Magic Numbers, SPM-2 Magic Strings, SPM-3
+Copy/Paste Programming, DP-1 Parameter Not Checked, DP-2 Status Ignored After Call, DP-3 Unexpected
+State Not Trapped, and the three Causes for Concern, which are an inspector's judgement. Of those,
+SPM-3 is already covered by the duplication pass and WIP-2 partly by the dead-code pass; WIP-1,
+WIP-3, SPM-1, SPM-2, DP-1 and DP-2 are candidates for indicators this role does not have yet.
+
+### 11.5 The eight thresholds, with their origin
+
+| indicator                | was |  **is** | research | our p90 | what decided it                                                                                           |
+| ------------------------ | --: | ------: | -------- | ------: | --------------------------------------------------------------------------------------------------------- |
+| `complexity`             |  20 |  **10** | 10       |      11 | the only indicator where two independent references agree within a unit                                   |
+| `max-lines-per-function` |  50 | **109** | 150      |     109 | research is more permissive than our code, so our code wins                                               |
+| `max-lines`              | 300 | **150** | none     |     157 | our p90, rounded down. No research sets a file's length                                                   |
+| `max-depth`              |   4 |   **3** | 3        |       3 | research and our code agree                                                                               |
+| `max-nested-callbacks`   |  10 |   **3** | 3 (SP-2) |       3 | same nesting family as SP-2, no citation of its own. Was above the repository's maximum of 4              |
+| `max-statements`         |  10 |  **10** | none     |      15 | the default is the stricter candidate and stays                                                           |
+| `max-params`             |   3 |   **3** | none     |       4 | the default stays. Beyond three parameters the fix is an object or currying, so this is a design boundary |
+| `max-classes-per-file`   |   1 |   **1** | none     |       5 | 1 is the rule's floor, there is no stricter value                                                         |
+
+Five move, and `complexity` is worth one line on its own: 94.8% of our 11 050 measured functions
+already sit in the 1-10 band the SEI calls low risk, so 10 is a ratchet rather than a demand.
+
+| SEI band            | functions |      share |
+| ------------------- | --------: | ---------: |
+| 1-10, low risk      |    10 475 | **94.8 %** |
+| 11-15               |       319 |      2.9 % |
+| 16-20               |       120 |      1.1 % |
+| 21-50, high risk    |       128 |      1.2 % |
+| over 50, untestable |         8 |      0.1 % |
+
+### 11.6 What the eight size rules say together, and the end of the descriptor split
+
+A threshold is only half a decision: what matters is what the **set** reports.
+
+|                               |          at the vendor defaults | at the thresholds above |
+| ----------------------------- | ------------------------------: | ----------------------: |
+| union of the eight size rules |             2 236 files, 27.7 % | **1 708 files, 21.1 %** |
+| largest single rule           | `max-lines-per-function`, 1 724 |   `max-statements`, 891 |
+| its share of the union        |                        **77 %** |                **52 %** |
+
+⛔ **At the defaults one rule was the report.** `max-lines-per-function` at 50 flagged 21.3% of all
+product files and carried 77% of the union, so the other seven indicators were inaudible: the
+report said "your functions are longer than 50 lines" and nothing else could be heard beside it.
+
+And this closes what 10.7 left open. The descriptor split held `max-statements` and
+`max-lines-per-function` out of the figure on a **break of a factor 4.5** between 42.9/46.9 and 9.6
+per 100 files. 10.7 already showed those numbers were an artefact of two defects. At the thresholds
+above the two most frequent rules are 11.0% and 10.7%, and the next is 7.8%:
+
+| indicator                | files | per 100 files | ratio to the next |
+| ------------------------ | ----: | ------------: | ----------------: |
+| `max-statements`         |   891 |          11.0 |              1.03 |
+| `max-lines`              |   864 |          10.7 |              1.37 |
+| `max-lines-per-function` |   630 |           7.8 |              1.26 |
+| `complexity`             |   499 |           6.2 |              1.34 |
+| `max-params`             |   373 |           4.6 |              2.32 |
+| `max-classes-per-file`   |   161 |           2.0 |             17.89 |
+| `max-nested-callbacks`   |     9 |           0.1 |              1.13 |
+| `max-depth`              |     8 |           0.1 |                 - |
+
+**The top five are a smooth gradient, 1.03 to 1.37, so there is no population to exclude.** The one
+large break, 17.9, sits at the BOTTOM, between `max-classes-per-file` and the two nesting rules: it
+says those two are rare here, not that the frequent ones are noise. `DESCRIPTORS`, `scored` and
+`described` are removed: every indicator counts, and the asymmetry that needed explaining in two
+places no longer exists. Note also that the two nesting rules moved from reporting **nothing at all**
+to reporting 9 and 8 files: lowering them from 10 and 4 to 3 is what gave them any information.
+
+### 11.7 Why `max-statements` is not a second reading of `max-lines-per-function`
+
+The obvious objection to keeping both is that a long function has many statements. Measured by
+joining the two diagnostics on the same function span, over 25 658 functions of which 10 441 carry
+both values:
+
+|                                         |                      |
+| --------------------------------------- | -------------------: |
+| Pearson, statements against lines       |                0.726 |
+| Spearman                                |                0.600 |
+| lines per statement, p25 / median / p90 | 2.5 / **4.4** / 14.0 |
+
+Correlated, so not independent. But the density varies by a factor of **5.6** across functions, and
+that is what forbids giving them one value. At the chosen thresholds:
+
+|                               | functions | what it is               |
+| ----------------------------- | --------: | ------------------------ |
+| over both                     |       399 | long and dense           |
+| `max-statements` only         |   **699** | dense logic in few lines |
+| `max-lines-per-function` only |   **255** | long with little logic   |
+| overlap                       |  **29 %** |                          |
+
+Both shapes are real, and in this repository they are two different kinds of file:
+
+| file                                    | lines | statements | shape                  |
+| --------------------------------------- | ----: | ---------: | ---------------------- |
+| `add-to-network/JobsEvaluationList.tsx` |   259 |          2 | one large JSX return   |
+| `entities/job-offer.entity.ts`          |    48 |         46 | one statement per line |
+
+So `max-lines-per-function` measures volume including markup, and `max-statements` measures
+imperative density, and neither sees what the other sees. Giving `max-statements` the same 109 would
+kill it: at the median density that is a function of roughly 480 lines, so the line count would
+always fire first and the statement count would never say anything again.
+
+---
+
+### 11.8 The ninth indicator: cognitive complexity, loaded rather than written
+
+Section 9.2 chose this metric and said it would be "written once here". It is not written. oxlint
+1.77 accepts an ESLint rule as a JS plugin, so Sonar's own `cognitive-complexity` runs inside the
+same invocation as the eight rules above, through a bridge that re-exposes it and contains none of
+their code.
+
+**Why loaded and not reimplemented**, in order of weight:
+
+⛔ **The licence decides it.** `eslint-plugin-sonarjs` ships under the Sonar Source-Available
+License, whose grant is limited to a "Non-competitive Purpose", and sentinel is published under MIT.
+Depending on a package is not preparing a derivative work of it; transcribing its code into this
+repository would be, in any language, and would mean granting rights we never received. ⚠️ Its
+`package.json` declares `LGPL-3.0-only` while the LICENSE file and every source header say SSAL.
+That contradiction is Sonar's; it is recorded here, not resolved.
+
+**The metric's author works there.** Campbell 2018 is theirs, so their implementation is the
+specification's own house rather than one reading of it among several.
+
+**It costs almost nothing.** Measured: 0 advisories at every level, 94 packages, and `eslint` is
+**not** pulled, because pnpm leaves the peer unmet and oxlint provides the context itself. It does
+pull `typescript`, which nothing of ours imports. The rule adds 2.4 s over 8 083 files to a pass
+that was already reading them.
+
+#### The behaviour is not the paper's, deliberately
+
+Measured on the same file with the same parser, before any of it was believed:
+
+|                             | sonarjs 0.25.1 | sonarjs 4.2.2 |
+| --------------------------- | -------------: | ------------: |
+| `if (a \|\| b \|\| c)`      |              2 |         **1** |
+| `if (a && b && c)`          |              2 |             2 |
+| `const x = a \|\| b \|\| c` |              1 |         **0** |
+
+⛔ **This is not a regression, which is what it was first called here.** Sequences of `||` and `??`
+are excluded on purpose: SonarSource state it themselves, "we tried to adjust the cognitive
+complexity rule to accommodate common idioms", and made the exclusion universal in SonarQube 10.8
+after it had been inconsistent between contexts. In JavaScript those two operators are
+overwhelmingly default-value shorthand rather than control flow. The lesson is the general one: an
+implementation that diverges from a published algorithm is a question to ask, not a defect to
+assume.
+
+#### The host is validated, not assumed
+
+Running somebody else's rule inside another linter removes the question "is our counting right" and
+replaces it with a narrower one: **does oxlint's tree feed the rule the same thing ESLint's does.**
+A fixture cannot answer that, because the constructs at risk are the ones real code has and
+fixtures do not: decorators, enums, `satisfies`, generics, and the JSX short-circuit the rule
+treats specially.
+
+So the same rule was run through both hosts over two real modules and compared **function by
+function**, matched on file and line:
+
+|                          | functions | identical | disagreements | seen by one host only |
+| ------------------------ | --------: | --------: | ------------: | --------------------: |
+| `contract`, nest         |       539 |   **539** |             0 |                     0 |
+| `console`, react and tsx |       581 |   **581** |             0 |                     0 |
+
+⚠️ This was missing when the figure first shipped, and the gap was not obvious: the earlier check
+compared the two hosts on about twenty fixture functions, which proves the plumbing and not the
+parse. It is the same bar `complexity` was held to against oxlint, 839 functions and 839 identical
+values, and it is the bar any rule borrowed from another ecosystem has to clear.
+
+#### The threshold
+
+`min(research, our p90, the rule's default)`, the same rule as the eight above. Sonar publishes
+**15** for S3776, and that is a vendor default rather than a research value: one of their own
+engineers has said publicly that no formula supports it. Our p90 over the files the rule touches is
+**7**, so 7 wins. It reports **342 of 8 083 files, 4.2%**, inside the band the other eight occupy.
+
+#### What it adds, and the honest version of that
+
+⚠️ **Almost nothing to the union.** Of its 342 files, **330 were already flagged** by one of the
+eight: the union goes from 1 708 files to 1 720, 21.1% to 21.3%. Anyone judging the indicator by
+coverage should stop here and conclude it is redundant.
+
+That reading is wrong, and the measurement that shows why is the comparison with McCabe, which is
+the thing it was brought in to complement:
+
+| on 8 083 product files                            |         |
+| ------------------------------------------------- | ------: |
+| flagged by both complexities                      |     242 |
+| **cyclomatic only**, branchy but readable         | **257** |
+| **cognitive only**, tangled without being branchy | **100** |
+| agreement between the two                         | **40%** |
+| Spearman over the 3 823 files carrying both       |   0.764 |
+
+The two disagree on **60% of the files either one flags**, which is the whole point. A flat `switch`
+with twelve cases is cyclomatically 13 and cognitively 1, because nothing is nested and nothing
+surprises; three `if`s inside each other are cyclomatically 4 and cognitively 6, because each level
+is charged for the levels above it. The 257 are the first shape and the 100 are the second. A figure
+that agreed with McCabe would have been the redundant one.
+
+#### Three defects on the way, all with one symptom
+
+Each produced exactly `oxlint could not be run, so no size indicator is reported`, which names
+neither the plugin nor the path, and each silently removed **all nine** figures rather than one:
+
+- the bridge written straight into `plugins/`, which is git-ignored and wiped by every build. It
+  survived until the next `pnpm build`.
+- its path computed by counting `..` from `import.meta.url`. `tsup` bundles into chunks whose depth
+  is not the source tree's, so it resolved from `src/` and not from `dist/`. ⚠️
+  `roles/test/shared-test-config.ts` already records this lesson at length, after it cost a module
+  83 passing tests; it was repeated anyway. The path is now walked up to.
+- the rule is namespaced by its plugin in the config, `sonar/cognitive-complexity`, and bare in the
+  diagnostic. One name in both places gives a config oxlint accepts and a breach map that never
+  matches.
+
+All three are now tests.
+
+---
+
+## 12. Sources
+
+- IfSQ. _Level 1, Level 2 and Level 3 Standards for Code Quality._ <https://www.ifsq.org/level-1.html>,
+  <https://www.ifsq.org/level-2.html>, <https://www.ifsq.org/structured-programming.html>,
+  <https://www.ifsq.org/research.html>, <https://www.ifsq.org/assessment.html>
 
 - Ben Khalfallah, H. _Code Health Meter: A Quantitative and Graph-Theoretic Foundation for
   Automated Code Quality and Architecture Assessment._ ACM TOSEM 35(4), article 114, March 2026.

package/docs/using-sentinel.md

@@ -4,8 +4,9 @@ The commands, what an adopted module ends up looking like, and how versions move
 migrating a module see [`lint-adoption.md`](lint-adoption.md),
 [`format-adoption.md`](format-adoption.md),
 [`typescript-adoption.md`](typescript-adoption.md),
-[`build-adoption.md`](build-adoption.md) and
-[`test-adoption.md`](test-adoption.md), which also carries the reference gate `--test` runs a
+[`build-adoption.md`](build-adoption.md),
+[`test-adoption.md`](test-adoption.md) and
+[`static-analysis-adoption.md`](static-analysis-adoption.md), which also carries the reference gate `--test` runs a
 migration against.
 
 ## The grid