@hublo/sentinel 1.4.2 → 1.4.4

package/docs/static-analysis-study.md

@@ -0,0 +1,527 @@
+# Static analysis: the study behind the role
+
+Research record for the `static-analysis` role (HUB-41506), written 2026-10-06. It is **not a
+specification**: it records what was measured, what was decided, and the reason attached to each
+decision, so that the next person can disagree with a reason rather than with a preference.
+
+Every figure below was measured on this monorepo on `origin/main`, with madge 8.0.0, nx 24,
+jscpd 5.4.0 and oxlint 1.77.0. The conditions matter, and the first section says why.
+
+---
+
+## 0. Notation
+
+Every symbol used below, in one place. They come from four different traditions, which is why
+the same idea sometimes carries two names.
+
+| symbol             | name                                              | what it is                                                                                               |
+| ------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `Ca`               | afferent coupling                                 | how many components depend on this one. Incoming edges                                                   |
+| `Ce`               | efferent coupling                                 | how many components this one depends on. Outgoing edges                                                  |
+| `DC`               | degree centrality                                 | `Ca + Ce`. The overall connectedness of one node. The ACM study calls the two halves `IDC` and `ODC`     |
+| `I`                | instability                                       | `Ce / (Ca + Ce)`, from 0 to 1. 0 is a stable foundation, 1 is a pure consumer                            |
+| `A`                | abstractness                                      | abstract classes over total classes in a component. ArchUnit counts public ones only                     |
+| `D`                | distance from the main sequence                   | `abs(A + I - 1)`. How far a component sits from the ideal line `A + I = 1`                               |
+| `SCC`              | strongly connected component                      | a set of nodes that can all reach each other. One SCC of size n contains every cycle among those n nodes |
+| `CC`               | cyclomatic complexity                             | McCabe's count of independent paths through a function                                                   |
+| `HV`               | Halstead volume                                   | a size measure built from the distinct and total operators and operands                                  |
+| `MI`               | maintainability index                             | a composite of `HV`, `CC` and lines of code. Formula in section 5                                        |
+| `LOC`              | lines of code                                     | physical lines, unless stated otherwise                                                                  |
+| `Q`                | modularity                                        | how well a graph splits into communities, maximised by the Louvain method                                |
+| `H`                | relational cohesion                               | `(R + 1) / N`, with `R` the edges internal to a module and `N` its members                               |
+| `LCOM4`            | lack of cohesion of methods                       | connected components among the methods that share a field. Above 1 signals several responsibilities      |
+| `DependsOn`        | Lakos                                             | the transitive closure of a component, itself included                                                   |
+| `CCD`              | cumulative component dependency                   | the sum of every `DependsOn` in the system                                                               |
+| `ACD`, `RACD`      | average and relative average component dependency | `CCD / N` and `ACD / N`                                                                                  |
+| `NCCD`             | normalised cumulative component dependency        | `CCD` over that of a balanced binary tree of the same size                                               |
+| `RV`, `ARV`, `GRV` | relative visibility, average, global              | visible elements over total elements, per component, averaged, and system wide                           |
+| churn              |                                                   | how many commits touched a file over a period                                                            |
+| entropy            | change entropy                                    | how **scattered** those commits were across files, which is a different question                         |
+
+Two conventions worth stating because they bite. A **percentile** is written `p95` and means the
+value below which 95% of the measured population sits. A **rank correlation** is Spearman's: 1
+means two rankings are identical, 0 means they are unrelated.
+
+---
+
+## 1. Three traps that make a number wrong without saying so
+
+Each was hit while preparing this study. Each produces a plausible figure and no error message,
+which is precisely the failure the ACM study criticises in existing tools: a result nobody can
+trace back to its cause.
+
+### The wrong tsconfig loses 61% of the graph
+
+The 403 path aliases live in `tsconfig.base.json` at the **workspace root**. The applications'
+own tsconfigs declare none. 40% of internal import edges go through an alias, so pointing madge
+at an application's tsconfig hands it an empty resolution table.
+
+| madge invocation                                |     nodes |     edges |
+| ----------------------------------------------- | --------: | --------: |
+| `--ts-config` on the app's tsconfig (0 aliases) |       859 |     1 930 |
+| `--ts-config tsconfig.base.json` (403 aliases)  | **1 785** | **4 882** |
+
+Measured on one subtree. The witness file went from 1 edge to 3: both of its alias imports
+appeared.
+
+### nx `implicit` edges invent 20% of cyclicality
+
+The nx project graph mixes two kinds of edge. A lambda imports its parent project: a `static`
+edge going up. The parent declares that it owns the lambda: an `implicit` edge coming down.
+Tarjan sees a cycle where there is only an ownership relation.
+
+| edges kept            |  SCCs | projects in cycles | cyclicality |
+| --------------------- | ----: | -----------------: | ----------: |
+| `static` + `implicit` |    14 |                 90 |  **20.45%** |
+| `static` only         | **0** |              **0** |   **0.00%** |
+
+Graph-wide: 2 008 `static` edges, 270 `implicit`.
+
+### A partial scan biases every centrality ranking
+
+Scanning a subtree and following its outgoing edges makes libraries appear as targets only.
+Their efferent coupling is then zero by construction and the top of the ranking fills with
+artificial sinks. On a first pass, the four most central files all had `Ce = 0`, not because
+they depend on nothing but because they had not been read.
+
+> **Consequence.** Every published figure carries a resolution fingerprint: tsconfig used, edge
+> types kept, scope scanned, tool versions. Without it, a configuration change reads as an
+> architectural regression.
+
+---
+
+## 2. What the code actually measures
+
+### File graph, whole front end (11 109 files scanned)
+
+|                                        | value                                                                |
+| -------------------------------------- | -------------------------------------------------------------------- |
+| nodes, edges                           | 12 372, 42 472, mean out-degree 3.43                                 |
+| System Cyclicality (Lattix definition) | **1.48%**, 183 files in 68 strongly connected components, largest 12 |
+| connectedness (reachable pairs)        | **4.65%**, against 0.153% edge density                               |
+| DC median / p95 / p99 / max            | 4 / 17 / 43 / 1 244                                                  |
+| DC = 0, dead files                     | **160** (1.3%)                                                       |
+| DC > 15                                | **721** files (5.8%)                                                 |
+
+### Project graph, nx, `static` edges only
+
+440 projects, 2 008 dependencies, **0 cycles**, unstable dependencies 1.1% (23 edges).
+
+> **The architectural reading.** Module boundaries are sound; the disorder is inside the
+> modules. `nx/enforce-module-boundaries` polices the project graph and nothing polices the file
+> graph, so that is where this role adds something nx does not already provide.
+
+### Timings
+
+|                                             |                      |
+| ------------------------------------------- | -------------------- |
+| madge, whole front end                      | **46 s**             |
+| nx graph                                    | **11 s**             |
+| git churn per file, 12 months               | **2 s**              |
+| the same pass with lines, authors and dates | **5 s**              |
+| git churn per function (`git log -L`)       | **106 ms per range** |
+
+Which settles the "continuous" question: per-file analysis is affordable on every pull request.
+Per-function churn is not, at 3.6 hours for the whole front end, but it is affordable on a short
+list: 106 seconds for the 100 most central files.
+
+### The files the graph points at
+
+| file                                        |    DC |    Ca |  Ce |    I | reading                                                                                      |
+| ------------------------------------------- | ----: | ----: | --: | ---: | -------------------------------------------------------------------------------------------- |
+| `libs/front/components/.../Typography.tsx`  | 1 244 | 1 244 |   0 | 0.00 | Healthy. Martin's rule is that a heavily depended-upon component should be stable, and it is |
+| `libs/api-types/bff-admin/.../api-types.ts` |   962 |   962 |   0 | 0.00 | Generated. Must be excluded before any rule speaks about tests                               |
+| `libs/front/tests/src/render/index.ts`      |   910 |   908 |   2 | 0.00 | Touching this helper, or the test setup this package ships, reaches 908 files                |
+| `libs/front/api/src/bff-admin/config.ts`    |   655 |   348 | 307 | 0.47 | **The real finding.** 348 files depend on something that itself depends on 307 others        |
+
+---
+
+## 3. Three measured results that decided the model
+
+Each was run because a plausible assumption deserved a test rather than an argument.
+
+### Centrality is not file size in disguise
+
+A known criticism (Herraiz et al., cited in Hassan's related work) is that most code complexity
+metrics correlate highly with lines of code, so they rediscover that big files are big. Applied
+to centrality, ranking all 12 372 files twice:
+
+**Rank correlation DC against LOC: 0.388.** Far from 1, so the two rankings designate different
+files and centrality carries information size does not. The criticism does not bite here.
+
+### Centrality is not a proxy for change frequency
+
+The hypothesis was that a central file, being heavily used, is frequently changed, which would
+make git history redundant.
+
+|                                   |               |
+| --------------------------------- | ------------- |
+| rank correlation DC against churn | **0.361**     |
+| files common to both top 100      | **13 of 100** |
+
+| counter-example                                  |  DC | churn |
+| ------------------------------------------------ | --: | ----: |
+| `front-legacy/src/constants/routes/index.ts`     | 424 |     2 |
+| `libs/front/translations/.../main.planning.json` |   2 |   309 |
+
+So a central file can be perfectly stable, which is often the sign that it is well made. The two
+are **the two factors of a product, not substitutes**: centrality is the consequence term,
+churn is the likelihood term. This is why CodeScene's hotspot is a multiplication.
+
+> A corollary that shaped the model: a vector of uncorrelated metrics **combines, it does not
+> stack**. Requiring central AND long AND complex AND poor MI selects almost nothing.
+
+### The graph does not see the product
+
+Raised in a tech lead review of the test strategy: none of these metrics says which user journeys
+matter, so a file can be central and uninteresting, or peripheral and critical. The objection
+holds, and it holds twice.
+
+**A screen is a structural leaf.** Over the 596 front end files that live under a `routes/` or a
+`pages/` directory, `routeTree.gen.ts` excluded:
+
+|                                                 | share of the 596 |
+| ----------------------------------------------- | ---------------- |
+| Ca ≤ 1, at most one file depends on them        | **83.2%**        |
+| Ca = 0, nothing in the codebase depends on them | **46.3%**        |
+
+This is not a defect in the metric, it is what afferent coupling means: a screen is where the
+product value is and it is the last node of the graph, so centrality ranks it last by
+construction.
+
+**And the graph cannot carve a journey out on its own.** If a journey were given by its entry
+point, there are two ways to expand it into a set of files, and both collapse. Measured on the
+182 route files of `host-admin`:
+
+| expansion                                              | result                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| transitive closure of one route file                   | median **440** files, max 5 733. The 5 largest routes alone reach **70%** of the app |
+| exclusive, reachable from this route and from no other | median **0**. 13 of the 18 route groups own exactly zero files                       |
+
+The two bracket the problem. Expanded transitively a journey is the whole application; reduced to
+what it owns alone it is empty. The useful set in between, the files that actually carry the
+journey, is not in the graph. It is in the team's head.
+
+---
+
+## 4. What was decided, and why
+
+### No single score. Six categories instead.
+
+Weighting would need experimentation to fix the formula, and a weight nobody can justify is a
+claim nobody can defend. Six correct numbers beat one indefensible score.
+
+This is consistent with three independent positions: the ACM study's own 6D signature per
+module, Lattix's documentation ("it is hard to come up with a single number that represents the
+architectural health of a system... instead, a set of numbers"), and the ACM study's criticism
+of Sonar, which is not that it aggregates but that it aggregates opaquely.
+
+The door stays open: the correlation matrix that would justify weights later is the same one
+that validates the categories now. Two of its cells are already filled, and both are weak.
+
+**A category is sound when its metrics lead to the same action.** Otherwise it is a filing
+cabinet, not a tool.
+
+| category        | the question                    | contains                                      | the action          |
+| --------------- | ------------------------------- | --------------------------------------------- | ------------------- |
+| **Impact**      | what does it break              | Ca, Ce, DC, I, later A and D                  | none. It **orders** |
+| **Activity**    | how much does it move           | churn, entropy, authors, co-change            | none. It **orders** |
+| **Cycles**      | what bites its own tail         | SCCs, System Cyclicality                      | move one import     |
+| **Cohesion**    | is the split right              | Q, H, LCOM4, density per module               | re-cut, move a file |
+| **Complexity**  | is it readable                  | CC, nesting, lines per function, Halstead, MI | split a function    |
+| **Duplication** | does it already exist elsewhere | jscpd                                         | extract, or accept  |
+
+Cycles is separate from Impact although both come from the graph, because the action differs: a
+cycle is fixed, a high centrality is not. **Impact × Activity** are the two terms of risk and
+repair nothing; the other four repair.
+
+On naming: a category is named after what it **measures**, never after where the number comes
+from and never as a verdict. "Centrality" was rejected because it is the name of one metric
+inside the category and describes I, A and D badly. "Importance" was rejected because it smuggles
+a judgement, and the counter-example is in our own data: `Typography.tsx` is the most central
+file in the front end and it is perfectly healthy.
+
+### Everything is computed per module, never globally
+
+A global top 100 by centrality returns 63 files from `libs/front` and 23 from `host-admin`, and
+**three entire applications never appear**: `console` (526 files), `hr-management` (298) and
+`career` (75), whose most central files sit at DC 43, 27 and 25. Such a list does not say "the
+100 most critical files", it says "`libs/front` exists", and three teams never receive a line of
+the report.
+
+Per module also repairs two metrics: density discriminates again at small N, and `H = (R+1)/N`
+only means something with R counted as edges internal to the module.
+
+### The product axis is declared, not observed
+
+The objection above has an obvious candidate answer, production telemetry. Real user monitoring
+(RUM), Datadog's in our case, knows which screens are really used. It was not taken, and the
+reason is not the quality of that data.
+
+**Static analysis runs before, telemetry reports after.** RUM describes what is in production. The
+decisions this role exists to inform are taken earlier: while the code is being written, when a
+technical choice is made, in CI before a merge. Code that is being written now has no traffic, and
+that is not a marginal case here:
+
+| front end `.ts` and `.tsx` files, generated route trees excluded |                   |
+| ---------------------------------------------------------------- | ----------------- |
+| tracked in git                                                   | 10 947            |
+| added in the last 90 days and still present                      | **3 115 (28.4%)** |
+
+The structural axis cannot stand in for the missing signal either, because it does not separate
+that population:
+
+|                           | median DC | DC > 15  | p95 |
+| ------------------------- | --------- | -------- | --- |
+| added in the last 90 days | 4         | **4.3%** | 15  |
+| older                     | 4         | **6.3%** | 18  |
+
+So the input is a **declaration**. The team states which paths carry a critical journey, the way a
+lint configuration states which rules a project wants. It sits in the repository, it is reviewed in
+a pull request, it is versioned with the code it describes, and it can therefore name a feature
+that does not exist in production yet.
+
+```jsonc
+{
+  "critical": [
+    {
+      "name": "contract signature",
+      "paths": ["features/contracts/**", "libs/front/api/src/bff-admin/contracts.ts"],
+    },
+  ],
+  "report": { "top": 100 },
+  "activity": { "months": 12 },
+}
+```
+
+A glob or an explicit file, matched the same way. There is deliberately no grammar for a sequence
+of steps: the order of a journey is never used by anything downstream, so asking for it would be
+asking teams to maintain a fact we do not read.
+
+### A declared set is a named subgraph, not a selector
+
+`critical` is not an input to centrality. It names a subgraph, and **every category is then
+computable on that subgraph** rather than only on the module. That is what the declaration actually
+buys, and for two categories it is the difference between a measurement and no measurement at all.
+
+| category        | on a declared set                                                             | what was impossible without it                                      |
+| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| **Impact**      | the set's own incoming and outgoing coupling, as one unit                     | a journey's blast radius. Per-file `Ca` never sums to it            |
+| **Cohesion**    | internal edge share and `H` of the set                                        | there was no candidate unit to test other than the folder tree      |
+| **Cycles**      | cycles that **cross** two declared sets, reported ahead of cycles inside one  | a cycle's product meaning. Two coupled journeys is a different fact |
+| **Duplication** | clones inside one journey against clones **between** two journeys             | telling local repetition from an unextracted shared concept         |
+| **Complexity**  | the same thresholds, with the declared sets ordered first                     | ordering by anything other than the metric itself                   |
+| **Activity**    | per-function churn, at 106 ms per range, on a short list that means something | the only affordable short list was the top 100 by centrality        |
+
+The shape was checked rather than assumed. Taking `console/src/features/*`, which is literally the
+shape of a `paths` entry:
+
+| feature      | files | internal edge share |         H |
+| ------------ | ----: | ------------------: | --------: |
+| client       |   334 |                 78% |      2.76 |
+| audit        |    42 |                 58% |      2.02 |
+| institutions |    35 |                 61% |      1.63 |
+| auth         |     7 |             **20%** |  **0.57** |
+| home         |     1 |                  0% |      1.00 |
+| **total**    |   419 |             **74%** | mean 1.60 |
+
+74% of the edges stay inside, and 3 of the 5 land in NDepend's 1.5 to 4.0 band for `H`, so a
+declared set behaves like a unit and not like an arbitrary list. And `auth` is immediately a finding
+rather than noise: 7 files with 3 internal edges against 12 outgoing is a wrapper, not a feature.
+
+> ⚠️ **A declared set is a cover, not a partition.** The same file can serve two journeys, which is
+> exactly the exclusive footprint result above. So modularity `Q` does **not** apply to it: `Q` is
+> defined on a partition. What applies is per-set cohesion and conductance, which tolerate overlap.
+> `Q` stays a module-level metric computed on the folder tree.
+
+**Within Impact, the report is two blocks, and their order is the whole point.**
+
+1. the files matching a declared `paths` pattern, grouped under their `name`
+2. the top N, **minus** everything already listed in block 1
+
+N defaults to 100 and is configurable. A file appears once, and a declared file that is also
+central is reported as declared. Without the subtraction the declaration would buy nothing: it
+would add names in front of a list that already contained the central files, and still never
+surface the critical file that is not central, which is the entire gap being closed.
+
+### The line: scope and volume are the team's, thresholds are ours
+
+| the config carries                                                       | the config does not carry    |
+| ------------------------------------------------------------------------ | ---------------------------- |
+| **scope**: which paths carry a journey, and the name the product uses    | the value of any measurement |
+| **volume**: how many files to report, how many months of history to read | what counts as central       |
+
+`DC > 15`, cyclomatic complexity at 30, nesting depth 4, duplication at 50 tokens over 5 lines:
+those stay on this side. A team declares a fact about its domain and chooses how much output it
+wants, it does not move the instrument. Those values will be calibrated from use and from the
+feedback the role collects, which is the same commitment a preset rule carries in
+`CONTRIBUTING.md`.
+
+Two consequences of how it is written, rather than of what it contains:
+
+- It is filled **with the product**, not by developers alone, which is why `name` is a field and
+  not a comment: the name is the part a product person validates, the paths are its translation.
+- `--init` generates it like every other config this tool writes, and the declared part survives a
+  re-init. The precedent is the format role's `$sentinel.local`, where the keys a module owns are
+  **declared rather than inferred**, so that an override survives a preset bump only when someone
+  said out loud that it should.
+
+**Why patterns and not route resolution.** Deriving the journey from the router was considered and
+dropped: only 3 of the 9 front end applications have a `routeTree.gen.ts`, so it would work on a
+third of the code and silently do nothing on the rest. A pattern also reads at review time without
+running anything, and it can name a file that does not exist yet.
+
+### What was deliberately not taken
+
+|                                    | reason                                                                                                                                                                                                                                                                                       |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Sonar's maintainability rating     | `debt / (30 min × LOC)` puts size in the **denominator**, so a longer file gets a better rating at constant debt. The Halstead-based MI subtracts `16.2 × ln(LOC)`, so it gets worse. They move in opposite directions with respect to size and are not two approximations of the same thing |
+| Arcan's dynamic threshold          | It is `max(system threshold, benchmark threshold)` against the Qualitas Corpus, which is Java. And it solves a problem we do not have: DC = 15 sits at the p94 in `host-admin` (5 880 files) and the p94.7 in `career` (75)                                                                  |
+| dependency-cruiser                 | It implements cycles, orphans and Martin's instability with the same formula, and can fail a build, but an earlier benchmark judged its values unreliable. The ACM study kept madge and graphology                                                                                           |
+| Edge density as a threshold        | Measured at 0.00153. It decays as 1/N, so it always reads "very sparse" at our scale. Replaced by Lattix's connectedness                                                                                                                                                                     |
+| A second duplication diff engine   | jscpd 5.4 already has `--baseline`, `--update-baseline`, `--fail-on-new-clones` and `--baseline-from-ref origin/main`                                                                                                                                                                        |
+| RUM traffic as a criticality input | It answers a question this role asks earlier than production can answer it, and 28.4% of the front end is less than 90 days old. Declared paths replace it, see above. Nothing prevents comparing the two later, once there is a report to compare against                                   |
+
+---
+
+## 5. Published thresholds, by source
+
+What each tool publishes, and whether it survives contact with our code.
+
+### NDepend
+
+| metric                        | threshold                                                                                                 | our state                                                                                            |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| cyclomatic complexity         | **> 15** hard, **> 30** split                                                                       | **already enforced**: `complexity: ["error", 30]` in the nest lint preset, exactly their upper bound |
+| lines per method              | > 20 hard, > 40 split                                                                               | not enforced. The ticket allows 50 in TS and 250 in TSX                                              |
+| nesting depth                 | > 4 hard, > 8 extreme                                                                               | not enforced. `max-depth` exists in the planning layer only                                          |
+| efferent coupling, type level | Ce > 50                                                                                                | 11 files. The ACM study's ODC > 15 designates 228                                                 |
+| relational cohesion H         | `(R + 1) / N`, good range **1.5 to 4.0**                                                                  | not computed. Computable on the graph: R = edges internal to the module                              |
+| distance from main sequence   | `                                                                                                         | A + I − 1                                                                                            | `, **> 0.7 problematic** | blocked: A is not graph-derivable |
+| maintainability index         | `MAX(0, (171 − 5.2·ln(HV) − 0.23·CC − 16.2·ln(LOC)) × 100/171)`, Visual Studio bands 0-9 / 10-19 / 20-100 | not computed                                                                                         |
+
+NDepend's own warning about its own metric is the most useful line in their documentation: the
+coefficients were calibrated on languages that predate C#, so an absolute score is not reliable.
+Their recommendation is to **rank the worst**, to **combine with complexity, coupling and change
+history**, and to **detect regressions** rather than impose a floor.
+
+### Lattix
+
+| metric                     | formula                                              | threshold                             |
+| -------------------------- | ---------------------------------------------------- | ------------------------------------- |
+| System Cyclicality         | **percentage** of elements in a cycle, not a count   | none                                  |
+| Intercomponent Cyclicality | same, across components                              | **target: zero**                      |
+| Coupling                   | `100 × n / (V(V−1)/2)`, n = strongly connected pairs | none                                  |
+| Connectedness              | `100 × reachable pairs / V(V−1)`                     | none                                  |
+| System Stability           | `100 − (average impact / atom count) × 100`          | **must increase as the system grows** |
+
+### ArchUnit
+
+| metric                 | formula                                                              | threshold                                                             |
+| ---------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| DependsOn (Lakos)      | transitive closure of a component, itself included                   | none                                                                  |
+| CCD                    | sum of all DependsOn                                                 | lower is better. A cycle inflates it: all members share one value     |
+| ACD, RACD              | `CCD/N`, `ACD/N`                                                     | **RACD bounded by 0.6** for an acyclic graph of at least 5 components |
+| NCCD                   | CCD over that of a balanced binary tree of the same size             | lower is better                                                       |
+| A, abstractness        | abstract over total classes, **public only**                         | none                                                                  |
+| RV, ARV, GRV (Dowalil) | visible over total elements, per component then averaged then global | lower is better                                                       |
+
+`FreezingArchRule` stores **individual violations** under version control; only new ones are
+reported and the store shrinks by itself as violations are fixed. It ignores line numbers, so a
+violation that moves stays known.
+
+Note that `DependsOn` measures the **outgoing** transitive closure, which is what can break this
+component, not what this component breaks. Blast radius is the incoming closure. Measured on our
+project graph, its rank correlation with plain Ce is 0.819, so it adds little to a ranking.
+
+### CodeScene
+
+Code Health is a weighted average of 25+ factors, weighted by each file's lines of code, over
+three bands. Factors include LCOM4 for cohesion, Brain Class and Brain Method, Bumpy Road,
+Complex Conditional and Primitive Obsession. Brain Class is a **conjunction**: many lines, many
+functions, and at least one Brain Method, which makes it harder to contest than a single
+threshold. Numeric thresholds are not published on their documentation pages.
+
+Hotspot is code health **multiplied by** change frequency, and reframes the question from "is
+this code bad" to "is this bad code important now".
+
+### Arcan
+
+| smell               | detection                                                                             | threshold                |
+| ------------------- | ------------------------------------------------------------------------------------- | ------------------------ |
+| Cyclic Dependency   | Sedgewick-Wayne, Tarjan, or Laval-Falleri for layered cycles                          | algorithmic              |
+| God Component       | **too many lines of code** in a container, not too many dependencies                  | `Max(system, benchmark)` |
+| Hub-Like Dependency | `FanIn + FanOut`                                                                      | same dynamic threshold   |
+| Unstable Dependency | a **relation between two containers**: one depends on a less stable one, with a delta | Martin's instability     |
+
+Two vocabulary collisions worth knowing: "God Component" means size here and fan-out in the ACM
+study, and "Unstable Dependency" is a property of an edge here, not of a node.
+
+### Google and Meta, on measuring the analyser rather than the code
+
+| metric                      | formula                                                                                       | threshold                                                                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| not-useful rate (Tricorder) | `NOT USEFUL / (NOT USEFUL + PLEASE FIX + APPLY FIX)`. `PREVIEW FIX` is not in the denominator | **≥ 10% probation, > 25% may be turned off immediately**                                               |
+| fix rate (Infer)            | findings that led to a change, over findings emitted                                          | the same analyser with the same defects: nearly nothing fixed in batch, **over 70% fixed at code review** |
+
+The Infer result is the one with a design consequence: the integration point weighs as much as
+the algorithm, which separates the developer surface (a pull request comment) from the staff
+surface (a trend) even though both run the same engine.
+
+### Change entropy (Hassan, ICSE 2009)
+
+`Hₙ(P) = −Σ pₖ · log₂ pₖ`, where P is, **over a period**, the probability distribution of a
+given file being modified. Maximum entropy when every file changes equally, minimum when one
+file absorbs everything.
+
+Entropy is not churn. Churn counts modifications; entropy measures how **scattered** they were.
+Ten changes in one file is zero entropy; ten changes across ten files is maximal. It is the
+observable trace, in the history, of what modularity claims about the structure.
+
+Three models: the Basic and Extended Code Change models give one value per period for a
+project, and the **File Code Change model redistributes it onto individual files**, which is the one that would serve here. Validated on six large open source
+projects, where the change complexity metrics were better predictors of fault potential than
+prior modifications and than prior faults.
+
+The related work carries two results that challenge the Complexity category: Herraiz et al. show
+that most code complexity metrics correlate highly with LOC, and Moser et al. that process
+metrics outperform code metrics as fault predictors.
+
+---
+
+## 6. Open questions
+
+|                                         | what it needs                                                                                                                                                                                                                                                                                |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Abstractness A in TypeScript            | A is a property of the code, not of the graph. ArchUnit counts public classes only, which suggests "the share of a module's exported API that is a type or an interface". Until it is settled, A and therefore D are blocked                                                                 |
+| Centrality against test coverage        | a per-file coverage source, which the front end does not have today                                                                                                                                                                                                                          |
+| A feedback channel on findings          | without it no rule can ever prove it deserves to exist, and "it depends" simply moves up one level, to our own tools                                                                                                                                                                         |
+| Q and betweenness                       | in the ACM study, absent from the ticket, not computed here                                                                                                                                                                                                                                  |
+| Git history                             | agreed as a second phase. The cost is not the obstacle: 2 seconds per file over twelve months                                                                                                                                                                                                |
+| Cyclomatic complexity as a measurement  | enforced as a lint rule at 30, never measured as a distribution                                                                                                                                                                                                                              |
+| The config's file name                  | `static-config.json` is the working name. This is the first config sentinel owns rather than inherits from a vendor, so there is no `.oxlintrc.json` precedent to follow, and the name is a free choice to make once                                                                         |
+| Merge and precedence                    | two declared journeys can match the same file, and a module config can sit under a workspace one. The rule has to be as explicit as a lint override's, and the report has to be verified for a file counted twice                                                                            |
+| 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 |
+
+---
+
+## 7. Sources
+
+- 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.
+  <https://doi.org/10.1145/3737670>
+- Hassan, A. E. _Predicting Faults Using the Complexity of Code Changes._ ICSE 2009.
+  <https://sailresearch.github.io/sail-website/data/pdfs/ICSE2009_PredictingFaultsUsingTheComplexityOfCodeChanges.pdf>
+- Sadowski, C. et al. _Tricorder: Building a Program Analysis Ecosystem._ Google.
+  <https://research.google/pubs/tricorder-building-a-program-analysis-ecosystem/>
+- _Scaling Static Analyses at Facebook._ Meta.
+  <https://doi.org/10.1145/3338112>
+- NDepend, code metrics: <https://www.ndepend.com/docs/code-metrics>
+- NDepend on the maintainability index: <https://blog.ndepend.com/maintainability-index/>
+- Lattix, metrics: <https://docs.lattix.com/lattix/userGuide/Metrics.html>
+- ArchUnit user guide, metrics and `FreezingArchRule`:
+  <https://www.archunit.org/userguide/html/000_Index.html>
+- Arcan, architectural smells: <https://docs.arcan.tech/latest/architectural_smells/>
+- CodeScene, code health and hotspots: <https://codescene.io/docs/guides/technical/code-health.html>
+- Sonar, Clean as You Code: <https://www.sonarsource.com/blog/clean-as-you-code/>
+- Martin's package metrics: <https://en.wikipedia.org/wiki/Software_package_metrics>

package/docs/typescript-traces.md

@@ -991,7 +991,7 @@ $ sentinel --report --typescript --max-diagnostics 3.9 --module bff-admin
 ```console
 $ sentinel --init --dry-run
   dry run: no files written
-  wrote .oxlintrc.json extending ./node_modules/@hublo/sentinel/lint/nest.json (@hublo/sentinel@1.4.1)
+  wrote .oxlintrc.json extending ./node_modules/@hublo/sentinel/lint/nest.json (@hublo/sentinel@<version>)
   2 rule(s) not enforced by this preset (1 no-barrel-files, 1 core). Run --inspect --lint for each rule and why.
   run `pnpm install`, then `pnpm run lint`
 
@@ -1003,7 +1003,7 @@ $ sentinel --init --dry-run
     +   "ignorePatterns": [
     +     "**/dist/**",
     +     "**/node_modules/**",
-    +     "**/coverage/**",
+    +     "coverage/**",
     +     "**/jest.*.{ts,js,cjs,mjs}",
     +     "**/eslint.config.{js,cjs,mjs}",
     +     "**/*.timestamp*",
@@ -1022,7 +1022,7 @@ $ sentinel --init --dry-run
     +     "lint": "sentinel --run --lint"
     +   },
     +   "devDependencies": {
-    +     "@hublo/sentinel": "1.4.1"
+    +     "@hublo/sentinel": "<version>"
     +   },
     +   "nx": {
     +     "targets": {
@@ -1058,7 +1058,7 @@ $ sentinel --init --dry-run
     +     "typecheck": "sentinel --run --typescript"
     +   },
     +   "devDependencies": {
-    +     "@hublo/sentinel": "1.4.1"
+    +     "@hublo/sentinel": "<version>"
     +   },
     +   "nx": {
     +     "targets": {
@@ -1076,13 +1076,13 @@ $ sentinel --init --dry-run
   build: no Vite config in this module, so there is nothing to point at sentinel. This role moves an existing config's imports; it does not introduce a bundler. If this module builds another way (38 services here build through `@nx/webpack`), the build role does not apply to it.
   test: this module has no test and no jest leftovers, so there is nothing to do here.
   dry run: no files written
-  materialized the nest format preset into .oxfmtrc.json (@hublo/sentinel@1.4.1). oxfmt has no `extends`, so the values live here; `sentinel --status --format` reports modules left behind by a preset change
+  materialized the nest format preset into .oxfmtrc.json (@hublo/sentinel@<version>). oxfmt has no `extends`, so the values live here; `sentinel --status --format` reports modules left behind by a preset change
 
   create .oxfmtrc.json
     + {
     +   "$sentinel": {
     +     "preset": "nest",
-    +     "version": "1.4.1",
+    +     "version": "<version>",
     +     "local": []
     +   },
     +   "printWidth": 80,
@@ -1133,7 +1133,7 @@ $ sentinel --init --dry-run
     +     "format:fix": "sentinel --run --format --fix"
     +   },
     +   "devDependencies": {
-    +     "@hublo/sentinel": "1.4.1"
+    +     "@hublo/sentinel": "<version>"
     +   },
     +   "nx": {
     +     "targets": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hublo/sentinel",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "One CLI that guards code health across Hublo repos: shared lint/typescript/build/test presets, static & dynamic analysis, and architecture checks.",
   "type": "module",
   "license": "MIT",
@@ -180,6 +180,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "vitest run tests/e2e",
+    "test:coverage": "vitest run --coverage --testTimeout=60000",
     "cli": "node --import tsx bin/sentinel.ts",
     "docs:traces": "pnpm build && bash scripts/gen-traces.sh",
     "docs:traces:check": "pnpm build && bash scripts/gen-traces.sh --check",