@hublo/sentinel 1.4.3 → 1.5.0-alpha.10

package/docs/static-analysis-study.md

@@ -0,0 +1,818 @@
+# 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 in sections 1 to 5 was measured on this monorepo on `origin/main`, with madge 8.0.0,
+nx 24 and oxlint 1.77.0. Section 6 measures the tools themselves and names its own versions, jscpd
+5.4.0 and `typhonjs-escomplex` 0.1.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**. Enforced as a lint rule, not measured here   |
+| `CX`               | file complexity                                   | the same count aggregated per **file**: its decision points plus its number of functions                 |
+| `SLOC`             | logical lines of code                             | statements rather than physical lines. Only escomplex produces it                                        |
+| `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                         |
+
+⚠️ Not every symbol above is produced in the first version. `A`, `D`, `H` and `LCOM4` are not:
+`A` is not graph-derivable (section 8), and `LCOM4` was dropped because the front end is functional,
+which leaves it a nest-only metric to be re-examined. The Lakos family, visibility, churn and
+entropy are the second version. What the first one produces is listed in section 7.
+
+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, isolated in the graph          | **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.
+
+### What centrality is evidence FOR, and where that evidence stops
+
+Two measurements above say what centrality is NOT: not file size in disguise, not a proxy for change
+frequency. Neither says what it is good for, and the literature does.
+
+| source                                                                                           | what it establishes                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Zimmermann and Nagappan, ICSE 2008, on Windows Server 2003                                       | models built from network measures reach a recall **10 percentage points** higher than models built from complexity metrics, and network measures identified **60%** of the binaries the developers themselves called critical, **twice** what complexity metrics found |
+| Tosun, Turhan and Bener, PROMISE 2009, five systems (three small embedded, two Eclipse versions) | network measures are important indicators of defective modules for large and complex systems, **and have no significant effect on small-scale projects**                                                                                                                |
+
+⛔ The second one is a boundary on everything this role can claim, so it is written here rather than
+left implicit. Centrality's predictive value is demonstrated on LARGE systems. A module of forty
+files gets a `DC` figure that means exactly what it says about its graph and nothing at all about
+where its defects are. `host-admin` at 5 880 files sits on one side of that line; most of
+`libs/nest` sits on the other. It becomes the `caveat` of the centrality help entry, unchanged.
+
+And it settles what the number is FOR, which is a question the role has to answer before it prints
+anything. Test impact analysis selects: given this diff, which tests can catch a defect in it.
+Centrality is a property of the code and knows nothing about a diff, so it cannot select. What it can
+do is ORDER: which tests to run first, and where strengthening tests pays. The two compose, and the
+composition has a sharp consequence worth stating: a highly central file is precisely the one where
+impact-based selection saves nothing, because changing it reaches almost everything.
+
+### 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     |
+| **Modularity**   | is the split right              | Q, density per module                        | re-cut, move a file |
+| **Complexity**   | is it readable                  | CX per file and per folder, Halstead, MI     | read it, then split |
+| **Duplication**  | does it already exist elsewhere | clones, duplicated lines, share per language | extract, or accept  |
+| **Reachability** | is any of it still run          | dead code, with a confidence per finding     | delete, or declare  |
+
+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, with one measured exception
+
+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 exception is reachability, and it is structural rather than a tuning problem. A library's
+consumers live in other modules: `libs/front/components` declares no `main`, `module`, `types`,
+`exports` or `files`, has no barrel, and is imported through a tsconfig alias
+(`@front/components/data-display/badge/Badge`), so **30.3%** of its lines read as dead from inside
+the module, identically from its root and from `src`. No internal declaration repairs that, and
+declaring every file an entry point would empty the metric. Either that one pass runs at workspace
+scope, or the metric is marked not applicable to a library. Open, see section 8.
+
+### 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 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.
+
+```js
+// static-analysis.config.mjs
+import { defineStaticAnalysis } from '@hublo/sentinel/static-analysis'
+
+export default defineStaticAnalysis({
+  root: import.meta.dirname,
+  journeys: {
+    'contract signature': ['src/features/contracts/**'],
+  },
+  entry: ['**/*.steps.ts'],
+})
+```
+
+The journey's name is the **key**, not a field, and its value is a list of globs or explicit files,
+matched the same way. ⚠️ Those paths are module-relative, because the scan is one module at a time:
+a journey cannot name a file in another module, and one that spans two modules is declared once on
+each side.
+
+Beside it, `entry` declares the files that RUN although nothing imports them, which is where
+reachability starts. It is the single most consequential line in the file: on one real service the
+dead-code figure is 33.4% with nothing declared and 1.0% with two patterns declared.
+
+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. And
+it is a function call rather than a JSON object because a partial declaration has to be mergeable:
+see section 7.
+
+### A declared set is a named subgraph, not a selector
+
+A declared journey 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, by default |
+| **volume**: how many files to report, how many months of history to read | what counts as central                   |
+
+`DC > 15`, duplication at 50 tokens over 5 lines, a complex file at `CX >= 50`: 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. ⚠️ "By default" above is exact and not a hedge: an `overrides` block can move any of
+them, nothing advertises it, and every value it sets is printed as `(module)` in the report, because
+two modules whose thresholds differ silently are no longer comparable. See section 7.
+
+Per-function limits are deliberately absent from that list: cyclomatic complexity per function is a
+lint rule, already at 30 in the nest preset, while `CX` here is **per file**. Same word, two units,
+and the report prints both. 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 the name is the object's
+  key rather than a comment: the name is the part a product person validates, the paths are its
+  translation.
+- `--init` generates `static-analysis.config.mjs` 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. Here the same idea is split by nature: `journeys` and `entry` are
+  **added** to what the role ships, so no team can lose a shipped pattern by declaring one of its
+  own, while `overrides` replaces and is attributed.
+
+**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`                                                                                                                                                                                            |
+| jscpd's `--health` score           | A 0-100 grade from duplication, dead code and complexity: `100 x 0.5^(adjusted/half-life)` per dimension, then the geometric mean across them, with half-lives calibrated on 42 open-source projects. The formula is worth borrowing; weighting the quality of our own modules is our governance, not a vendor's |
+| jscpd's `--semantic` pass          | Type-4 clones through code embeddings, experimental, and it needs a model download. Parked on purpose: the capability is interesting for SAST and taint analysis later, not for a duplication figure now                                                                                                         |
+| 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                                                                       | **both, in two units**: `complexity: ["error", 30]` per FUNCTION in the nest lint preset, and `CX` per file measured by this role, ungated. NDepend's own figure is per method      |
+| 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 | computed by escomplex, on the **raw 0 to 171 scale** and not as a percentage. The residual is coverage, not absence: 32.6% of one nest service does not parse, see sections 6 and 8 |
+
+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. The tool, measured rather than read
+
+The study above was written against `jscpd` 4.0.5. The published version is **5.4.0** (30 September
+2026), a Rust rewrite, and it changes what this role has to build. Everything below was measured
+on this repository, not taken from the documentation; where the documentation and the measurement
+disagree, the measurement is kept and the disagreement is stated.
+
+### What it is
+
+|                  |                                                                                           |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| 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                                                        |
+| 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                                  |
+
+### What it already does, that this role no longer has to write
+
+| planned here                            | 5.4.0                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------------------------------- |
+| warn now, block later                   | `--baseline`, `newClones`, `--baseline-from-ref`, `--fail-on-new-clones`                |
+| cyclomatic complexity                   | `--complexity`, McCabe exact, calibrated below                                          |
+| console, json, html                     | native reporters, plus markdown, sarif, codeclimate, openmetrics, badge                 |
+| git history, deferred to a second phase | `--history`, `--compare`, `--blame`                                                     |
+| nothing                                 | `--dead-code` (a separate engine, `basta`), `--health`, `--dashboard`, `--mcp`, `--lsp` |
+
+### How detection works
+
+Tokenisation follows each language's own grammar, and for JavaScript, TypeScript, JSX and TSX the
+tokens come from the **oxc** parser. A rolling Rabin-Karp hash over the token stream finds every
+repeated window of at least `minTokens` tokens and `minLines` lines, and the window is therefore
+the floor of visibility: a duplication shorter than it does not exist as far as the figure is
+concerned.
+
+Cyclomatic complexity was calibrated against files of known McCabe value, and matches exactly:
+
+| fixture                         | expected |   `CX` |
+| ------------------------------- | -------: | -----: |
+| one function, no decision point |        1 |  **1** |
+| one function, 4 `if`            |        5 |  **5** |
+| one function, 9 `if`            |       10 | **10** |
+| three functions, 2 `if` each    |        9 |  **9** |
+| `for` + `while` + `if` + `&&`   |        5 |  **5** |
+
+### Seven more traps, this time in the tool
+
+These are the reason the role's configuration looks the way it does. Each one was reproduced.
+
+| trap                                                     | measurement                                                                                                                                                                                                                               |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **the entry declaration decides the dead-code figure**   | on `apps/nest/microservices/network`: **33.4%** of lines dead with nothing declared (79 657 lines, 13 entry points), **1.0%** with two patterns declared (2 462 lines, 207 entry points)                                                  |
+| **the share of duplicated lines double-counts**          | two 9-line files report **13 duplicated lines of 18, 72%**, adding an `exact` clone of lines 1-4 to a `similar` clone of lines 1-9 that contains it; the real extent is 9 of 18, 50%. The tool's own answer is to cap the display at 100% |
+| **the language list is not the file extension**          | `typescript` alone scans **300** of `apps/front/console`'s 523 files, because `.tsx` is a separate language; all four scan 522, the one left out being `styles.css`                                                                       |
+| **`maxLines` excludes large files**                      | passing 1000 explicitly drops **22** files on nest/network, exactly those over 1000 lines                                                                                                                                                 |
+| **the duplication window filters the complexity pass**   | at `minTokens` 50 the header reads "3 files analyzed" out of five, the two smallest dropped without a word                                                                                                                                |
+| **a scan that analyses nothing exits 0**                 | with a warning only, so `--fail-on-empty` has to be set                                                                                                                                                                                   |
+| **the configuration is read from the working directory** | a `.jscpd.json` dropped in a module makes the run report **0 clones**, silently. Measured: same fixture, 1 clone from outside the module, 0 from inside it, 1 again when `--config` is passed                                             |
+
+Two further counting facts, both of which change how a figure may be worded:
+
+- `n` identical copies produce **`n - 1`** clone entries, neither `n` occurrences nor the
+  `n(n-1)/2` pairs. And when a third file shares only part of a block, only the longest match per
+  pair is kept, so the same block appears under two fragment identities and the occurrence count
+  cannot be recovered. **Fowler's Rule of Three is therefore a reading instruction, never a
+  threshold.**
+- `--mode mild|weak|strict` measured **identical** on a comment inserted mid-block and on a pure
+  reindentation. The documentation describes the three as dropping whitespace, dropping comments
+  and keeping everything; for JS, TS, JSX and TSX the oxc token stream contains neither, so the
+  option does nothing here and the `mode: strict` inherited from the ACM study is decorative.
+
+### What stays out
+
+|              | why                                                                                                                                                                                                                                                                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--health`   | a composite 0-100 score with a letter grade, from duplication, dead code and complexity. Its formula is `100 x 0.5^(adjusted/half-life)` per dimension and the **geometric mean** across them, with half-lives calibrated on 42 open-source projects. The formula is worth borrowing; weighting the quality of our modules is our governance, not a vendor's |
+| `--semantic` | Type-4 clones through code embeddings, experimental, and it needs a model download. Parked deliberately: the capability is interesting for SAST and taint analysis later, not for a duplication figure now                                                                                                                                                   |
+
+### The benchmark, with its reservation
+
+The project's own benchmark uses a 547-file, 21 645-line corpus on Apple Silicon and reports
+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
+
+`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
+29 ms measured when a process was spawned per file. The obstacle is coverage, not speed:
+
+| module                                | files | failures, default | with `decoratorsLegacy` |
+| ------------------------------------- | ----: | ----------------: | ----------------------: |
+| `apps/front/console/src`              |   523 |      5 = **1.0%** |            5 = **1.0%** |
+| `apps/nest/microservices/network/src` |  2169 |  1045 = **48.2%** |         708 = **32.6%** |
+
+By default 812 of the nest failures are "Decorators must be placed after the `export` keyword":
+its parser forces `decoratorsBeforeExport: false`, which rejects `@Injectable()` above
+`export class`. The option goes through the **fourth** argument of `analyzeModule(source, options,
+parserOptions, parserOverride)`; the third one is a trap, because `BabelParser.parse` does
+`options = typeof options === 'object' ? options : defaultOptions`, so an object passed there
+replaces the whole default plugin set and the TypeScript plugin disappears, taking nest to 97.2%.
+The remaining 708 are `state.generator[node.type] is not a function`, an internal limit.
+
+jscpd, on the same service, reports `statistics.unparsed` of **0** out of 2180. So jscpd owns
+every metric it can compute, and escomplex keeps only what nothing else provides.
+
+---
+
+## 7. What the role does
+
+### Perimeter
+
+The scan is the **module root**, one module at a time, with `node_modules`, `dist`, `build`,
+`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
+manifest and the root configuration files are the authoritative entry points:
+
+| module                            | from the root | from `src` |
+| --------------------------------- | ------------: | ---------: |
+| `apps/front/console`              | **0.8%** dead |  2.1% dead |
+| `apps/nest/microservices/network` |          1.0% |       0.9% |
+| `libs/front/components`           |         30.3% |      30.3% |
+
+### The three outputs, and one naming collision
+
+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.
+
+| script                 | command                            |
+| ---------------------- | ---------------------------------- |
+| `static-analysis`      | `sentinel --run --static-analysis` |
+| `static-analysis:json` | `... --output json`                |
+| `static-analysis:html` | `... --output html`                |
+
+One report under `static-analysis`, not one per metric, assembled from **two** files:
+`jscpd-report.json` and `basta-report.json`.
+
+### The configuration seam
+
+Sentinel exports a function; the module calls it.
+
+```js
+// static-analysis.config.mjs
+import { defineStaticAnalysis } from '@hublo/sentinel/static-analysis'
+
+export default defineStaticAnalysis({
+  root: import.meta.dirname,
+  entry: ['**/*.steps.ts'],
+  journeys: { planning: ['src/planning/**'] },
+})
+```
+
+A function and not `{ ...baseConfig, ... }`, because a spread is shallow: a module writing
+`deadCode: { minConfidence: 80 }` would drop `categories`, and the flattening happens in the
+module's file, before this package sees the object. A function receives the keys the module
+actually set. Second reason: no default is copied into a module, so changing one reaches every
+module at the next release rather than leaving stale copies behind.
+
+|                              | rule                                                                                                                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entry`, `journeys`          | facts a team declares, written in plain sight by `--init`, and **added** to the shipped ones, so no module can lose `**/*.integration-spec.ts` by declaring a third pattern |
+| thresholds, windows, `kinds` | judgments, internal to sentinel, never written into a module                                                                                                                |
+| `overrides`                  | the seam: it **replaces**, including those lists, and every path it sets is recorded so the report can print `(module)` next to the value                                   |
+| no file at all               | the role runs on its own defaults; that is not a failure                                                                                                                    |
+| a file that throws           | distinguished from a missing one and reported, because the two call for opposite actions                                                                                    |
+
+The file is `.mjs` rather than `.mts` because **sentinel** consumes this config and would
+otherwise need a transpiler at runtime to read six lines. `--status` keeps the cheap path
+regardless: adoption is "the module has the script", read from `package.json`, so a
+workspace-wide sweep still executes nothing. And the resolved settings are written to a
+configuration file that is passed with `--config`, so the tool never discovers a stray
+`.jscpd.json`.
+
+### The passes, and who renders the verdict
+
+| pass        | settings                                                                                                           |
+| ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| duplication | `minTokens` 50, `minLines` 5, **`kinds: exact` only**, `--fail-on-empty`, and **never** `--threshold`              |
+| dead code   | `minConfidence` 60, four categories without `unused-member`, entry points `*.integration-spec.ts` and `*.steps.ts` |
+| complexity  | its **own** window at `minTokens` 10, and `--summary-top` raised, since it defaults to 10 entries                  |
+
+**Sentinel renders the verdict, from the statistics, never from the exit code.** Without
+`--threshold` the tool exits 0 even with 32 clones and still writes its report, including when
+nothing is duplicated; a non-zero exit therefore means the tool failed. The first version
+computes over the whole project every time, with no baseline: refining to what a pull request
+changed comes second, and correctness comes first.
+
+`kinds: exact` only is a correctness constraint rather than caution, for the double-counting
+reason above: opening a second kind requires computing the share ourselves from the **union** of
+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 |
+
+### 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`                             |
+
+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`,
+`max-params` and `max-statements`. The role measures the distribution; the linter refuses a unit.
+The two are complementary as long as every figure carries its unit.
+
+---
+
+## 8. 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  | **settled.** jscpd measures it per file and per folder; the lint rule keeps the per-function refusal. The two units are both printed, see section 7                                                                                                                                                                                                                                                                                                                                  |
+| The config's file name                  | **settled.** `static-analysis.config.mjs`, calling an exported function, not a JSON file: sentinel consumes these values, and a function is what makes a partial declaration mergeable. See section 7                                                                                                                                                                                                                                                                                |
+| 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                                                                                                      |
+
+---
+
+## 9. 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>
+- Zimmermann, T. and Nagappan, N. _Predicting Defects using Network Analysis on Dependency Graphs._
+  ICSE 2008.
+  <https://www.microsoft.com/en-us/research/publication/predicting-defects-using-network-analysis-on-dependency-graphs/>
+- Tosun, A., Turhan, B. and Bener, A. _Validation of network measures as indicators of defective
+  modules in software systems._ PROMISE 2009. <https://doi.org/10.1145/1540438.1540446>
+- Hammant, P. _The Rise of Test Impact Analysis._ martinfowler.com, August 2017.
+  <https://martinfowler.com/articles/rise-test-impact-analysis.html>
+- 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>