@hublo/sentinel 1.5.0-alpha.9 → 1.5.0

package/docs/static-analysis-adoption.md

@@ -0,0 +1,285 @@
+# 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` along with its nx target, pins `@hublo/sentinel` into its own `devDependencies`, and ignores the report directory in the repository's root `.gitignore`. 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 there, everything else comes from the role
+  ignored static-analysis-report/ in the root .gitignore
+  run `pnpm install` to apply the workspace changes
+```
+
+⚠️ **If your module has a `project.json` and no `package.json`, `--init` creates one.** Measured on
+this repository, **49 of 243** nx projects are in that case, and none of them has adopted any
+sentinel role yet, which is the same fact seen from the other side. The consequence is worth
+knowing before you read the diff: the pnpm workspace globs are `apps/**` and `libs/**`, so a new
+`package.json` there makes the directory a workspace package and the lockfile gains an importer for
+it. Verified: `pnpm install` stays green, and nx keeps reading the project, now from two files.
+
+This is not specific to this role. `--init --format` on the same module prints `create
+package.json` too: it is the shape of every sentinel adoption, because a role declares its nx
+target in `package.json` and nowhere else.
+
+**Nothing else is required.** The config stub is written with an empty `entry` 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 four 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.
+
+⚠️ **From the workspace root, `pnpm exec sentinel` does not resolve.** sentinel is a devDependency of each adopting MODULE, not of the root, so the root's `.bin` has no `sentinel` and you get `Command "sentinel" not found`. Three things do work:
+
+```bash
+pnpm --filter <module> exec sentinel --run --static-analysis   # the module becomes the cwd
+pnpm --filter <module> run static-analysis                      # its own script, same thing
+npx @hublo/sentinel --run --static-analysis --module <module>    # when nothing is installed
+```
+
+`--module` is for the third form. With the first two the cwd is already the module, so it is redundant.
+
+## 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 --run --static-analysis --output markdown # static-analysis.md, the pull-request recap
+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 every place with **the code behind it** and an explorable import graph. `markdown` is six lines for a pull-request comment, and it has no npm script on purpose: nobody runs it by hand.
+
+⚠️ The `html` shape pays for a graph layout that the other three 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. `html` and `json` also open the source files behind the places they list, 201 of them on the largest front measured; `console` and `markdown` print no code and open none.
+
+## 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.
+
+**An absent row means one of two things, and the notes tell you which.** When a pass could not 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. When a COUNT is zero, the row is dropped silently and on purpose: the complexity bands and the nine size indicators would otherwise print a column of zeroes on a healthy module, which makes the normal case the loudest part of the report.
+
+So: a row missing **with** a note under the figures was not measured; a row missing **without** one was measured and found nothing.
+
+### 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.
+
+## Bundle analysis, for a front application
+
+Six rows appear when the module is a front application **that has been built**. They answer how much
+JavaScript a user downloads to open it, and what that costs twice over.
+
+| row                       | what it is                                                                        |
+| ------------------------- | --------------------------------------------------------------------------------- |
+| initial load, transfer    | gzipped, what crosses the network, against a **170 KB** budget and the web median |
+| initial load, to parse    | decompressed, what the engine reads, against **717 KB**                           |
+| initial load, files       | how many files the entry pulls                                                    |
+| heaviest single asset     | the largest file, named, against **100 KB** per script                            |
+| dynamic layer             | what no entry references statically, as a pair of bounds over its group count     |
+| referenced by the entries | everything the entries reference, read as code-splitting health                   |
+
+**Why two weights and never one.** Compression is a network lever with no effect on the engine:
+"900 KB of decompressed JavaScript is still 900 KB to the parser and compiler, even though it may be
+roughly 300 KB when compressed." Measured across these fronts the ratio runs from 3.30 to 3.70, so
+neither figure can be read off the other.
+
+**Why two references for the transfer weight.** The web median answers _are we normal_, the
+engineering budget answers _are we good_, and they routinely disagree: every front here sits below
+the median and above the budget. Both are true. The budget carries its conditions, and they travel
+with it: getting interactive in under five seconds on a slow 3G connection on a median mobile
+device.
+
+Each figure's band is the word beside it: `ok` below 70% of its reference, `near` from 70% to 100%,
+`exceed` above. And each row carries its own lever and its sources in the `html` report, because a
+weight nobody can act on is a weight nobody acts on.
+
+⚠️ **Three conditions are printed with the figures, and they decide what the figures mean**: how old
+the build is, that the brand it was built for is not recorded anywhere in the output, and any path
+the manifest announced that resolved to no file. A measurement on a stale build is silently wrong.
+
+⚠️ **No build, no figures, and the report says so** rather than printing zeros. A module that has
+never been built and a module weighing nothing are different facts. A component library or a
+back-end service produces no entry manifest at all, so it will always read that line: that is the
+perimeter, not a defect.
+
+**You also get a recap on the pull request**, for the fronts it touched, with each band. It is
+posted on every run rather than only on a breach, because a comment that appears only when
+something is wrong is a comment nobody learns to read, and it updates the same comment instead of
+adding a second one.
+
+⛔ **It measures, it never refuses.** Nothing here fails a build, including that comment. Blocking
+is a later choice, and the thing worth blocking on is the **delta** against the default branch
+rather than the level: that needs CI to keep a baseline, so it comes with the baseline.
+
+## 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, and it is laid out the way a scanner is: **one card per figure**, grouped into tabs by family, each carrying its own help and its own places. A place is a card too: the path with its line, the measure in its own unit, the rule it broke, and **the code**, collapsed.
+
+The code is read from your source files for every place the page lists, not just for clones: a clone comes with its fragment, while a size or complexity finding is a file and a line, so the page opens the file. Which lines it shows depends on what the rule points at, which was measured rather than assumed: a rule naming a declaration shows ten lines from it, `max-depth` and `max-nested-callbacks` show the three lines above too because the nesting they report is there, and `max-lines` shows the file's HEAD because it reports at the file's last line. A dead export with no line is located by its name when exactly one line declares it, and shows nothing rather than a guess otherwise.
+
+The **import graph** is explorable. Point at a dot for its path, which the browser shows under your cursor; 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 filtering.
+
+## The pull-request recap
+
+`--output markdown` writes `static-analysis-report/static-analysis.md`: one table, one row per family, the headline figure and how many places that family holds. It is what a workflow posts as a comment, one section per affected module.
+
+⛔ **It does not compare with `main`.** It says so on itself, because a number in a pull-request comment is read as a delta by default, and that reading is wrong in the dangerous direction: a module already at 6.81% looks exactly like one this branch pushed there. Comparing needs a baseline kept between runs, which is the next version's work.
+
+⚠️ `static-analysis-report/` is generated, and **`--init` ignores it for you**: it writes one line into your repository's root `.gitignore`, unanchored so it matches at every depth, rather than one line in every adopting module's own file. It checks first, in any spelling, so adopting a second module adds nothing. You have nothing to do and nothing to commit beyond that line.
+
+⛔ **The one case where it is not there**: a repository that runs the role WITHOUT ever adopting it, which is what a CI workflow measuring modules with `npx` does. `--init` never ran, so nothing wrote the rule, and every measured module leaves an untracked directory. If that is your situation, add the line yourself:
+
+```gitignore
+static-analysis-report/
+```
+
+⚠️ This paragraph said the opposite for one commit, on the strength of that very case: the line was missing from a repository where no module had adopted, and the conclusion drawn was that the documentation lied, without checking what writes it. `--init` does, in `src/core/workspace-prep.ts`. Verify yours with `git check-ignore -v <module>/static-analysis-report/`.
+
+## 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/**'],
+})
+```
+
+**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.