@hublo/sentinel 1.5.0-alpha.9 → 1.5.0

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
@@ -563,7 +570,7 @@ disagree, the measurement is kept and the disagreement is stated.
 | ---------------- | ----------------------------------------------------------------------------------------- |
 | shape            | a 20 KB launcher plus one of eight per-platform binaries, pulled as optional dependencies |
 | npm dependencies | **zero** (4.0.5 carried nine)                                                             |
-| engines          | `>=18`, so the Node 20 floor holds                                                        |
+| engines          | `>=18`, so our own floor holds whatever it is                                             |
 | speed            | 180 files in **28 ms**; the dead-code pass on a 2180-file service in **84 ms**            |
 | provenance       | same repository `kucherenko/jscpd`, same maintainer, MIT                                  |
 
@@ -634,7 +641,7 @@ The project's own benchmark uses a 547-file, 21 645-line corpus on Apple Silicon
 jscpd at **84 ms** against PMD CPD at **35 980 ms**. But jscpd analysed **347** of the 547 files
 and PMD **71**, so "the fastest of the set" holds and the factor of 428 does not.
 
-### What escomplex is still needed for, and what it costs
+### ⛔ Superseded by 9.1: what escomplex WAS needed for, before it was removed
 
 `typhonjs-escomplex` is the only source for logical `SLOC`, the Halstead set and `MI`. It is also
 far faster than previously recorded: **0.8 to 1.6 ms per file** in a single process, not the 23 to
@@ -666,7 +673,9 @@ The scan is the **module root**, one module at a time, with `node_modules`, `dis
 `coverage`, the report directory, generated files and fixtures excluded, on top of the
 `.gitignore` the tool already honours. Both halves are measured: without an ignore list the
 sentinel package itself reports 18 186 files and 32 153 clones, **31 969** of them touching
-`node_modules`; with it, 408 files and **zero**. And the root rather than `src` because the
+`node_modules`; with it, 408 files and **zero**. ⛔ The paragraph that follows is superseded by
+10.1: the scan is **`src`**, or the module itself when it has none. It read "the root rather than
+`src`" because the
 manifest and the root configuration files are the authoritative entry points:
 
 | module                            | from the root | from `src` |
@@ -675,7 +684,11 @@ manifest and the root configuration files are the authoritative entry points:
 | `apps/nest/microservices/network` |          1.0% |       0.9% |
 | `libs/front/components`           |         30.3% |      30.3% |
 
-### The three outputs, and one naming collision
+### The outputs, and one naming collision
+
+⚠️ There are **four** shapes: `console`, `json`, `html` and `markdown`. The three npm scripts below
+are correct and deliberate: `markdown` is the recap a CI workflow produces, not a command anyone
+types, so it gets no script.
 
 Every target name is a CLI flag, so `--format` already belongs to the format role and cannot mean
 an output shape. `--json` already exists engine-wide, documented for every verb.
@@ -745,24 +758,47 @@ the line ranges.
 
 ### Metrics by source
 
-| metric                                                    | tool               |
-| --------------------------------------------------------- | ------------------ |
-| clones, duplicated lines and tokens, share per language   | jscpd              |
-| dead code, four categories, with a confidence per finding | jscpd (`basta`)    |
-| `CC` per file and per folder, physical lines, tokens      | jscpd              |
-| logical `SLOC`, Halstead, `MI`                            | escomplex          |
-| cycles, `Q`, density, `Ca` / `Ce` / `DC` / `I`            | madge + graphology |
+⛔ **Superseded by 9.1 and 10.3.** Three rows below name a tool the role does not use. `escomplex`
+was removed with Halstead, `MI` and logical `SLOC` (9.1): it fails to read 708 of 2 169 files of one
+nest service, and Halstead's target is not defined anywhere. `madge` was never taken: the graph is
+built from the role's own oxc parse, which costs 18 packages and 5.1 MB against madge's 136 and
+48.4 MB. And jscpd's per-file `CC` is not published: its unit sums a file, so ten trivial functions
+score what one function of 10 does. The table as shipped is below it.
+
+| metric                                                    | tool                   |
+| --------------------------------------------------------- | ---------------------- |
+| clones, duplicated lines and tokens, share per language   | jscpd                  |
+| dead code, four categories, with a confidence per finding | jscpd (`basta`)        |
+| ~~`CC` per file and per folder, physical lines, tokens~~  | ~~jscpd~~              |
+| ~~logical `SLOC`, Halstead, `MI`~~                        | ~~escomplex~~          |
+| ~~cycles, `Q`, density, `Ca` / `Ce` / `DC` / `I`~~        | ~~madge~~ + graphology |
+
+**As shipped:**
+
+| metric                                                    | tool                              |
+| --------------------------------------------------------- | --------------------------------- |
+| clones, duplicated lines and tokens, share per language   | jscpd                             |
+| dead code, four categories, with a confidence per finding | jscpd (`basta`)                   |
+| `CC` per **function**, in McCabe's risk bands             | the role, over the oxc parse      |
+| cycles, `Q`, density, `Ca` / `Ce` / `DC` / `I`            | the role's own graph + graphology |
+| nine size indicators                                      | oxlint, at our own thresholds     |
+| the bundle, transfer and parsed                           | the TanStack entry manifest       |
 
 ### The unit is part of the number
 
 Two tools use the word complexity for two different units, and a report that omits them will look
 like it contradicts itself in public:
 
-|                      | unit                                              | value here                             |
-| -------------------- | ------------------------------------------------- | -------------------------------------- |
-| oxlint `complexity`  | per **function**                                  | 30, in the nest preset, blocking today |
-| jscpd `CX`           | per **file**, decision points plus function count | measured, not gated                    |
-| jscpd "complex file" | per file                                          | `CX >= 50`                             |
+⛔ **Superseded by 9.5.** `CX` is NOT a figure this role publishes: jscpd's per-file sum was
+rejected once it was measured, and complexity here is per FUNCTION, computed by the role over the
+oxc parse and reported in McCabe's bands. The row is kept because the unit collision it warns about
+is still real for anyone comparing with another tool.
+
+|                     | unit                                              | value here                     |
+| ------------------- | ------------------------------------------------- | ------------------------------ |
+| oxlint `complexity` | per **function**                                  | 10, the role's gauge threshold |
+| this role           | per **function**, McCabe                          | bands 11-20, 21-50, 51+        |
+| ~~jscpd `CX`~~      | ~~per file, decision points plus function count~~ | ⛔ not published, see 9.5      |
 
 So this role does not re-judge a single function: a per-function or per-file limit is a lint rule,
 and oxlint already ships `complexity`, `max-lines`, `max-lines-per-function`, `max-depth`,
@@ -785,11 +821,781 @@ The two are complementary as long as every figure carries its unit.
 | Merge and precedence                    | **settled.** The project wins; declared facts are added, `overrides` replaces and every path it sets is printed as `(module)`. A file matched by two declared journeys is still to be verified in the report                                                                                                                                                                                                                                                                         |
 | A stricter threshold on a declared path | the lint override analogy invites it, and the recommendation is to refuse it in a first version: a per-path threshold makes two files with the same measurement get different verdicts, and the first thing this role has to be able to say is that a number means the same thing everywhere                                                                                                                                                                                         |
 | Dead code inside a library              | `libs/front/components` reports **30.3%** of its lines dead, and no internal declaration fixes it: the package declares no `main`, `module`, `types`, `exports` or `files`, it has no barrel, and consumers import deep paths through a tsconfig alias (`@front/components/data-display/badge/Badge`). Reachability inside a library is therefore meaningless at module scope. Either the pass runs at workspace scope for libraries, or the metric is marked not applicable to them |
-| Halstead and MI on nest                 | escomplex parses **67.4%** of `network`, and a module-level `MI` computed over two thirds of its files is not that module's `MI`. Three ways out: publish it with its coverage beside it, find whether one node type explains the 708 internal failures, or recompute Halstead on `oxc-parser`, which is already a direct dependency and parses everything the lint role parses                                                                                                      |
+| Halstead and MI on nest                 | **settled: both leave, and cognitive complexity takes their place.** The third way out was written and measured; see section 9                                                                                                                                                                                                                                                                                                                                                       |
 
 ---
 
-## 9. Sources
+## 9. The two scores: what is settled, what is still ours to choose
+
+Section 8 left `MI` open on escomplex's coverage. Working that question through replaced it. This
+section records the model that came out, every step of it measured, and marks plainly what is
+still a decision rather than a finding.
+
+### 9.1 Halstead and `MI` leave, and the reason is not the code
+
+The third way out of section 8, recomputing Halstead on `oxc-parser`, was written and run against
+escomplex over the 443 files of `apps/front/console` that it reads:
+
+| count                  | identical |
+| ---------------------- | --------: |
+| n1, distinct operators |     93.9% |
+| N1, total operators    |     82.8% |
+| n2, distinct operands  |     74.3% |
+| N2, total operands     |     26.0% |
+| logical SLOC           |     42.7% |
+
+Five causes were found by measuring and closed, each worth tens of points: `ignoreKeys`, walking
+INTO `TS*` nodes rather than skipping their subtree, suppressing annotations only inside a
+parameter list, one statement per function or class scope, and the implicit return of an
+expression-bodied arrow. The rest is a long tail of single-rule differences in both directions.
+
+⛔ **The gap cannot be closed, because the target is not defined.**
+
+- **IBM publishes the seven formulas and not the classification.** Its documentation says the
+  measures come directly from the operators and operands, and defines neither.
+- **The ecosystem is one implementation.** `code-complexity`, `complexity-report` and `plato` all
+  depend on escomplex; `typhonjs-escomplex` is a fork of it.
+- **The one independent implementation disagrees.** `ts-complex`, built on the TypeScript
+  compiler, agrees with escomplex on operands 8 fixtures out of 12 and on operators **0 out of
+  12**: it counts neither `[]` nor `{}` nor `()`. On `return [1, 2, 3]` one says `n1 = 4`, the
+  other `n1 = 1`. On the 8 agreeing fixtures ours matches both.
+- ⚠️ **And `ts-complex` cannot be the reference anyway.** It reads 3 683 files here with zero
+  failures, which looks better than escomplex until the instrument is checked: it runs on
+  TypeScript 2.9.2 and, on `satisfies`, `??` and `?.`, raises nothing and returns operand lists
+  containing an empty string. Silent degradation is worse than a throw.
+- **A check needing no tool was tried and failed.** Halstead's length equation does not
+  discriminate: swapping operators and operands entirely leaves the correlation at 0.9222,
+  unchanged, because it is symmetric in `n1` and `n2`. It detects only total randomness.
+
+⛔ **Deleted on 2026-10-13**, with `src/roles/static-analysis/complexity/halstead.ts`, 412 lines
+imported by nothing. Keeping dead code as a record is a habit this role exists to break, and the
+record is this section.
+
+⛔ **Logical `SLOC` goes with it, and so do `LOC` and `PLOC` as metrics of ours.** Their only
+source was escomplex, which this section rules out, so a V1 entry was left with no producer and no
+decision written against it: exactly the gap that surfaces in a demo as "and where is SLOC?". The
+decision is that we do not look for another source. Size is already answered by three figures that
+do exist, `max-lines`, `max-lines-per-function` and `max-statements`, each with a threshold
+derived in section 11, and a fourth count of lines would add a number without adding a question.
+
+⚠️ `LOC` still appears below inside OTHER tools' formulas, Sonar's maintainability rating and the
+`MI` equation. Those are descriptions of what someone else computes, not metrics this role emits.
+
+### 9.2 Cognitive complexity takes the place
+
+|                            | Halstead and `MI`                    | cognitive complexity              |
+| -------------------------- | ------------------------------------ | --------------------------------- |
+| specification of the count | **none** published for TypeScript    | Campbell 2018, an exact algorithm |
+| reference implementation   | two, disagreeing 12 times out of 12  | `eslint-plugin-sonarjs`, by Sonar |
+| reads our code             | 61% to 99% depending on the family   | **100%**, 0 fatal errors          |
+| published threshold        | none transferable on the 0-171 scale | **15**, rule S3776                |
+| how ours gets validated    | hand-counted fixtures only           | function by function, as `CC` was |
+
+Sonar's own implementation, run over four modules with its threshold lowered to 0 so that every
+function is reported: sentinel 752 functions and 41 above 15, network 1 701 and 19, recruitment
+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.
+
+⛔ **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
+
+**Which indicators are in it.** Each at its published threshold, and the ranking is by how often
+each one fires per 100 files, which is measured rather than judged:
+
+| indicator              | published threshold | per 100 files |
+| ---------------------- | ------------------: | ------------: |
+| `max-depth`            |                   4 |           0.6 |
+| `max-classes-per-file` |                   1 |           1.8 |
+| `complexity`           |                  20 |           3.7 |
+| cognitive complexity   |           15, S3776 |           6.5 |
+| `max-lines`            |                 300 |           7.5 |
+| `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 |
+| ------------------------ | ------------: |
+| `max-statements`         |          42.9 |
+| `max-lines-per-function` |          46.9 |
+
+They fire on nearly one file in two, so they would fire on nearly every pull request. A gate that
+always fires is noise. They stay in the report as descriptors and out of the figure.
+
+⚠️ **Rarity is not severity.** It says what _can_ be a gate, not what is serious. Ordering the
+seven that remain still needs one argument per indicator, and that is open; see 9.6.
+
+**The computation.**
+
+```
+per file   breaches_f = indicators above their published threshold, in that file
+           → names the worst file, and counts the clean ones
+the figure rate = Σ breaches / files × 100
+           MI   = 1 / (1 + rate/10)        0 to 1, higher is better
+beside it  the share of files with no breach at all
+```
+
+Measured: console 0.651, components 0.390, recruitment 0.237, sentinel 0.234. Clean files: 95%,
+87%, 74%, 82%.
+
+⛔ **Three things the measurement forced, each against an idea that looked better:**
+
+- **Equal weights.** A coefficient fitted to today's distribution expires when the distribution
+  moves, which is an argument for no weights rather than for smarter ones.
+- **A denominator is unavoidable.** `1/Σ` ranks by module size, and all four modules land between
+  0.0005 and 0.0042, unreadable. `1/log(1+Σ)` does not fix it, it compresses it: a factor 1.4
+  between best and worst. No monotone transform of a raw count escapes size; only dividing by one.
+- **Never the mean of a per-file score.** 74% to 95% of files are clean, so the mean of `1/(1+n)`
+  saturates between 0.86 and 0.97, a factor 1.13, and the median is 1.000 everywhere. Jensen. The
+  per-file computation is kept for what it alone gives: the worst file, named, and the share that
+  is clean.
+
+⚠️ The `/10` is a display scale, chosen here and arbitrary. It changes the spread, never the
+order, and it is to be replaced; see 9.6. And sentinel at 0.234 and recruitment at 0.240 are
+indistinguishable, not ranked.
+
+### 9.4 Structure is not a score
+
+Each of these says its own thing, and they are reported side by side. Summing them would mean
+inventing both a scale and a direction, which is exactly what 9.3 eliminated.
+
+| metric                | what it says                             | why it cannot be summed                                   |
+| --------------------- | ---------------------------------------- | --------------------------------------------------------- |
+| cycles                | files importing each other in a circle   | 0 expected, **size-independent**: the only summable one   |
+| `Q` + community count | the quality of the assignment            | high is not good: a module split into islands scores high |
+| `Ca` / `Ce` / `I`     | coupling, per file, the 10 most imported | Martin defined them for a component, not a file           |
+| `DC`                  | centrality, beside the raw count         | normalised by `n − 1`, so incomparable between modules    |
+| density               | a web or a tree                          | 0.0216 at 101 files, 0.0005 at 4 380: size, not structure |
+
+### 9.5 Where a rule lives: gate or gauge
+
+The same algorithm is written once and consumed twice, and the split is forced by adoption rather
+than preferred.
+
+|              | the lint plugin                         | the static-analysis role                    |
+| ------------ | --------------------------------------- | ------------------------------------------- |
+| what it is   | a **gate**: it refuses                  | a **gauge**: it measures                    |
+| configurable | yes, a team may derogate                | **no**, or a number stops meaning one thing |
+| threshold    | whatever the preset sets                | the published one, identical everywhere     |
+| reaches      | **52 modules of 198** that adopted lint | **198**, it reads the oxc tree              |
+
+A score sourced from the plugin would exist on a quarter of the repository and be incomparable
+between two modules that configured the rules differently. Hence the gauge, always present.
+
+**The role never runs the module's lint.** It writes its own config to a tmpdir and passes it to
+oxlint, exactly as `tool-config.ts` already does for jscpd. Verified: a config outside the module,
+with `jsPlugins` naming a plugin by path, lints 523 files and leaves `.oxlintrc.json` untouched.
+So no new setting reaches a module's configuration, and the gauge's thresholds live in a file the
+module never sees, which is what makes them non-negotiable.
+
+> ⚠️ Gate and gauge will disagree out loud, and the report must say so. `complexity` is published
+> at 20 and the `nest` preset refuses at 30, so a nest developer will read breaches beside a green
+> lint. That is correct, not a defect: the figure compares modules, the rule refuses code. Each
+> number is printed with the line that produced it, under "measured with".
+
+### 9.6 The gate is on the diff, because on a module it saturates
+
+A worst-breach rating needs no weights and no denominator, which is why it was tried. Measured
+both ways:
+
+|     | the whole module      | one commit |
+| --- | --------------------- | ---------: |
+| A   | —                     |   39 (85%) |
+| C   | —                     |    6 (13%) |
+| D   | console               |          0 |
+| E   | sentinel, recruitment |     1 (2%) |
+
+On a module it saturates: at 1 500 to 3 700 functions, something crosses any per-function line.
+On a diff it discriminates, and the shape suits it: over 300 first-parent commits of 90 days, 18%
+touch no production file at all and the median touches **4**.
+
+> The 46-commit figure reads the files' **current** content, not their content at the commit, so
+> it answers "would this change be flagged today" rather than "did it introduce the defect".
+
+### 9.7 What is still a decision
+
+| open                                  | what it needs                                                                                                                                                   |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ~~the `/10` in the `MI`~~             | ⛔ **Closed by 11.6**: there is no `MI` and no composite figure. The descriptor split it scaled rested on a break that was an artefact of the vendor thresholds |
+| 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.** 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.
+
+---
+
+## 10. What the perimeter is, and what a figure refuses to answer
+
+Section 9 settled the two scores. Building them raised a different question four times in one
+evening, always the same one under a new coat: **on which files does a figure speak, and what is
+it entitled to conclude about them?** Every answer below is measured, and two of them reverse a
+decision taken earlier in this document.
+
+### 10.1 The measured perimeter is a PLACE, not a list of patterns
+
+What is measured is `src`, or the module itself when it has none.
+
+| over the 208 modules with a `src` |   files |
+| --------------------------------- | ------: |
+| product files under `src`         |  30 008 |
+| outside it                        |   4 004 |
+| of those, tooling configuration   | **205** |
+
+The rest outside `src` is mostly `tests/doubles/`. One rule answers, identically for every pass,
+the three questions a reader actually asks: no, your `jest.config.ts` is not measured; no, your
+tests are not; no, nothing outside `src` is. A list of 24 exclusion patterns answered the same
+questions one argument at a time, and left the configs in.
+
+⚠️ The fallback is not a detail: **232 of the 440 nx projects have no `src` at all**, mostly cloud
+lambdas. Measuring nothing there would be a silence that reads as a pass.
+
+### 10.2 Being measured and being a USER are two different roles
+
+⭐ **A file outside the perimeter is never counted in a figure, and still proves that what it
+imports is alive.** A test is not measured; a test that imports a file shows the file is used.
+
+The measurement that forced it, on `libs/nest/auth`: **11 production files are imported only from a
+test file**, `auth.module.ts` among them, and **47 projects depend on that module**. Treating "not
+measured" as "does not exist" turns all 11 into dead code.
+
+So reachability reads imports from everywhere, and only the population reported on is bounded.
+The same holds for a configuration file: it is never measured, and an import from it still counts.
+
+⚠️ And a file that **only** tests import is not dead either, it is _used only by tests_: a third
+category with its own line. Measured: 6 such entry points on `auth`, **39 on `libs/front/components`**
+(`CalendarHeader`, `MonthCalendar`, `Cell`).
+
+### 10.3 A figure nothing can reach is not published
+
+Two of the four original passes answer a question of the form "does anything reach this?", and both
+become WRONG rather than partial when a file cannot be parsed. Measured on `apps/front/hr-management`,
+232 product `.ts`/`.js` beside 252 `.svelte`:
+
+| what was reported                                           | what it was worth                                                                                                       |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| 161 edges, 124 communities, 163 entry points over 232 files | dust, not an application                                                                                                |
+| 33 files reported unused                                    | **41 of the 232 are imported only from a `.svelte` file**: `debounce.ts`, `clickOutside.ts`, `isMobile.ts`, `modals.ts` |
+
+So the graph and the dead-code figures are suppressed for such a module, and the drawing with them:
+figures carry their reserve in the report, an image carries none. Duplication and complexity stay,
+because each value they produce is true of the file it was measured on.
+
+⛔ **By language, not by a share.** A cut on the unreadable proportion would be a threshold nobody
+can source, and the defect does not arrive gradually: one unreadable component disconnects the
+helpers only it imports. Across the repository this touches **2 modules of 175**: `libs/front/ui`
+(73% unreadable) and `apps/front/hr-management` (52%).
+
+### 10.4 For a library, reachability is decided outside the module
+
+This reverses section 7's assumption that one module's graph can answer its own dead code.
+
+An application has an entry point: something runs, and what it cannot reach is dead. A library has
+none. Its consumers are outside, and the role's graph stops at the module edge on purpose. So the
+figure does not measure dead code there, it measures "the module does not import itself", which is
+true of every library.
+
+| `libs/nest/auth`, 100 production files |        |
+| -------------------------------------- | -----: |
+| reported dead by the entry-point walk  | **87** |
+| `Ca = 0` inside the module graph       |     29 |
+| of those, imported from another module |     17 |
+| **imported by nobody, anywhere**       | **12** |
+
+⛔ **An index, real or synthetic, does not rescue it.** On `libs/front/components`, 432 distinct
+specifiers are used across the repository and **4 go through a barrel, 428 enter by a deep path**.
+The barrel exists and is bypassed 99 times out of 100, so a synthetic index would have to re-export
+everything and the figure would read **0% by construction**. Shape of the 164 libraries with a
+`src`: wildcard alias only **75 (46%)**, barrel and wildcard **71 (43%)**, barrel only **3 (2%)**,
+no alias of their own 15 (9%).
+
+So the decision is to extend `Ca` past the module edge for a library, and only for a library: an
+application is imported by nothing, so its outside `Ca` is zero by construction, and 39 of its 44
+already declare what runs.
+
+**The sentence of principle, written rather than slipped in.** For this one figure, and only this
+one, the role reads outside the module. Everywhere else the module edge is the boundary and that is
+deliberate: a figure comparable between modules must be computed the same way in each. Here the
+question is _who imports this_, the answer is by definition elsewhere, and refusing to look does not
+make the figure local, it makes it wrong. Measured on `libs/nest/auth`: 87 against 12.
+
+**Built, and what changed.** The walk is kept and **seeded** rather than replaced, so it keeps the
+one thing it does that a degree count cannot: transitivity, a file reachable only through a dead one
+stays dead. Its entry points become the module's declared patterns plus the files another module
+imports.
+
+| module                  | unused files |     dead lines | used only by tests |
+| ----------------------- | -----------: | -------------: | -----------------: |
+| `libs/nest/auth`        |  **87 → 20** | 40,1 % → 4,9 % |                  6 |
+| `libs/front/components` | **362 → 10** |        → 1,4 % |             **39** |
+| `recruitment`, an app   |      10 → 10 |        → 1,1 % |                  - |
+| `console`, an app       |        2 → 2 |        → 0,8 % |                  - |
+
+⚠️ **Two of those columns moved afterwards**, and the shipped figures are below. `unused files` now
+subtracts the files the tool itself labels `used-only-by-tests`, which were counted as unreachable
+while the tool knew better; and `used only by tests` became the UNION of two disjoint sources, that
+label and the workspace index. Re-measured on 2026-10-14 with 1.5.0-alpha.26:
+
+| module                  | unused files | dead lines | used only by tests |
+| ----------------------- | -----------: | ---------: | -----------------: |
+| `libs/nest/auth`        |       **15** |     4,85 % |             **11** |
+| `libs/front/components` |            8 |     1,42 % |                 40 |
+| `console`, an app       |            0 |     0,78 % |                  2 |
+
+The two libraries move and the two applications do not, which is the shape the measurement
+predicted: an application is imported by nothing, so its outside `Ca` is zero by construction.
+
+⭐ **And a third state appeared, which neither of the two could hold.** A file no production code
+imports but another module's **specs** do is not dead, and not plainly alive either: it is alive for
+the tests alone. `usedOnlyByTests` is its own row, 6 files on `auth` and **39** on
+`libs/front/components`, among them `CalendarHeader`, `MonthCalendar` and `Cell`.
+
+⚠️ The role got **faster**, not slower: `auth` runs in 529 ms against 873 ms before the index
+existed, because the walk has far less to report.
+
+### 10.5 The index: the cost is I/O, so the answer is amortisation and not a data structure
+
+Finding a library's consumers costs 2 to 5 seconds with `git grep`, against 873 ms for the whole
+role on `auth`. The reflex is to reach for a better structure. Measured, that is the wrong end:
+
+|                                                            |         time |
+| ---------------------------------------------------------- | -----------: |
+| enumerate the 39 308 files (`git ls-files`)                |    **56 ms** |
+| `git grep` for a pattern that matches **nothing**          | **8 994 ms** |
+| `git grep` for the real pattern, 2 708 lines found         |     9 343 ms |
+| `git grep` for **every** alias at once, 22 303 lines found |     9 349 ms |
+| build the in-memory index from that output, 5 089 entries  |    **13 ms** |
+
+A pattern that finds nothing costs what a pattern finding 22 303 lines costs: the price is reading
+the disk. A balanced tree would accelerate an insertion that already takes 13 ms, and a lookup that
+is free.
+
+⭐ **The lever is in the last row: one scan serves every library.** The index is built once, not per
+module.
+
+|                                  |           |
+| -------------------------------- | --------: |
+| today, per library               | ~4 900 ms |
+| one scan, the whole index        |  9 024 ms |
+| amortised over the 164 libraries | **55 ms** |
+
+Thirteen minutes become nine seconds. Restricting the scan to the consumers' `src` saves nothing
+(4 884 against 4 911 ms) and loses 5 real consumers, so it is not done.
+
+**Where the cache lives: `node_modules/.cache/sentinel/`.** Not per module, because the index
+describes the workspace and 164 copies would be 164 different staleness states. Not inside the
+installed package, because that is the tool's directory rather than the workspace's, and an install
+replaces it.
+
+The convention already exists in this repository: `node_modules/.cache` holds 208 MB and six tools
+use it, `prettier` and `storybook` among them. Three consequences come free: nothing to add to
+`.gitignore` since `node_modules` is already ignored, one cache per workspace which is the scope the
+data has, and a fresh install clearing it.
+
+⚠️ **That it survives an install is measured, not assumed**: `node_modules/.cache` was last written
+on 2026-09-17 and `.modules.yaml`, which pnpm rewrites on every install, carries 2026-09-27. An
+install ran ten days later and the cache is still there. pnpm removes only what it tracks.
+
+And if the workspace ever switches to a hoisted linker: no collision is possible, since an npm
+package name cannot begin with a dot; the index itself is unaffected, since it maps specifiers to
+this repository's own sources and never reads `node_modules`; and the switch rebuilds `node_modules`
+wholesale, so the cache is lost once and rebuilt in nine seconds, which is the correct invalidation
+for a change that can change the installed code.
+
+Keyed on the git state, `HEAD` plus the uncommitted files, rather than on mtimes: a `git checkout`
+moves every mtime without changing a byte.
+
+### 10.6 The size indicators, and three silent traps
+
+⚠️ **Two figures here were superseded by section 11**: there are **nine** rules, not seven, and
+they run at `min(research, our p90, the rule's default)` rather than at the threshold each rule
+publishes. The three traps below are unchanged and are why this section exists.
+
+The size rules are measured with oxlint, run from a config in a temporary directory, and the
+module's own `.oxlintrc.json` is never read. Each trap below
+cost a wrong measurement before it was found, and none of them produced an error:
+
+- **oxlint loads 65 rules by default.** Neither `plugins: []` nor `categories: {}` stops it. On
+  `libs/nest/auth` it reported `no-unused-vars` and `no-useless-rename`, which are not indicators of
+  this gauge. Every category has to be named and turned off; then exactly 8 load.
+- **`ignorePatterns` in the config is accepted and ignored.** Same patterns on the same module: 137
+  files read through the config key against **111** through `--ignore-pattern`, and the worst file
+  it produced was a 1 436-line `permissions.guard.spec.ts`. The gauge was measuring the test suite.
+- **A diagnostic is not a breach.** `max-nested-callbacks` fires once per nesting level, so the unit
+  is the (file, rule) pair: counting diagnostics inflates the rate by **1.8x** at the published
+  thresholds and **2.8x** at lower ones.
+
+And `warn` rather than `error`, for the reason `tool-config.ts` already gives about jscpd's
+`threshold`: at `error`, oxlint exits 1 on any breach and a finding becomes indistinguishable from
+the binary failing. Measured: same 18 diagnostics either way, exit 1 against exit 0.
+
+---
+
+### 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.