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

package/dist/bin/sentinel.js

@@ -15,7 +15,7 @@ import {
   palette,
   registerAdapters,
   resolve
-} from "../chunk-AFM4AJHA.js";
+} from "../chunk-BN6SCBFW.js";
 import {
   resolveContext
 } from "../chunk-KLEXJFJ6.js";

package/dist/{chunk-AFM4AJHA.js → chunk-BN6SCBFW.js}

@@ -5283,14 +5283,25 @@ function scanGraph(cwd, config) {
 import { mkdtempSync as mkdtempSync2, rmSync as rmSync4, writeFileSync as writeFileSync4 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { join as join20 } from "node:path";
-var PUBLISHED_THRESHOLDS = {
-  complexity: 20,
-  "max-depth": 4,
-  "max-lines": 300,
-  "max-lines-per-function": 50,
+var GAUGE_THRESHOLDS = {
+  // McCabe 1976 says 10, our p90 says 11. The only indicator where two independent candidates agree
+  // within one unit, and 94.8% of our functions already sit in the 1-10 band SEI calls low risk.
+  complexity: 10,
+  // IfSQ SP-2, "few people can understand nesting to more than 3 levels". Our p90 agrees at 3.
+  "max-depth": 3,
+  // No research anywhere for a FILE's length: IfSQ's three citations (500, 100-150, 143) are all
+  // about routines. So our p90 of 157, rounded down.
+  "max-lines": 150,
+  // Our p90. IfSQ SP-1 says 150 and is discarded for being more permissive than our own code.
+  "max-lines-per-function": 109,
+  // No research. Our p90 is 15, the rule's default is 10, so the default stays as the stricter one.
   "max-statements": 10,
+  // No research, and none needed: beyond three parameters the fix is an object or currying, so this
+  // is a design boundary and not a dial. Our p90 of 4 is the looser candidate and loses.
   "max-params": 3,
-  "max-nested-callbacks": 10,
+  // Same nesting family as `max-depth`, no citation of its own. Our p90 agrees at 3.
+  "max-nested-callbacks": 3,
+  // 1 is the rule's floor, there is no stricter value to pick.
   "max-classes-per-file": 1
 };
 var CATEGORIES = [
@@ -5312,7 +5323,7 @@ function sizeRulesConfig() {
     // `warn` exits 0, and both report the same 18 diagnostics. So the tool measures, this role
     // judges, and a non-zero exit means the tool failed.
     rules: Object.fromEntries(
-      Object.entries(PUBLISHED_THRESHOLDS).map(([rule, threshold]) => [rule, ["warn", threshold]])
+      Object.entries(GAUGE_THRESHOLDS).map(([rule, threshold]) => [rule, ["warn", threshold]])
     )
   };
 }
@@ -5341,7 +5352,8 @@ function ruleOf(code) {
   return /\(([^)]+)\)\s*$/.exec(code)?.[1];
 }
 function valueOf(message) {
-  return Number(/\((\d+)\)/.exec(message)?.[1] ?? 0);
+  const match = /\((\d+)\)/.exec(message) ?? /complexity of (\d+)/.exec(message);
+  return Number(match?.[1] ?? 0);
 }
 function breachesOf(raw) {
   let parsed;
@@ -5355,7 +5367,7 @@ function breachesOf(raw) {
   for (const diagnostic of diagnostics) {
     const rule = ruleOf(diagnostic.code ?? "");
     const file = diagnostic.filename;
-    if (!rule || !file || !(rule in PUBLISHED_THRESHOLDS)) continue;
+    if (!rule || !file || !(rule in GAUGE_THRESHOLDS)) continue;
     const value = valueOf(diagnostic.message ?? "");
     const line = diagnostic.labels?.[0]?.span?.line ?? 0;
     const key = `${file}\0${rule}`;
@@ -5524,59 +5536,59 @@ var metricsHelp = {
   },
   complexity: {
     label: "Files with a complex function",
-    what: "Files holding at least one function whose cyclomatic complexity passes 20.",
+    what: "Files holding at least one function whose cyclomatic complexity passes 10.",
     read: "Count of files, so it is comparable between modules only against their file count, which the unit carries. It is the same measure as the band rows above, seen per file rather than per function. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
-    caveat: "It does not say which function, nor whether branching is wrong there: a parser legitimately branches. \u26D4 This is a GAUGE and not the line your lint refuses at. It runs oxlint with its own config in a temporary directory, at the threshold the rule publishes, and never reads the module's `.oxlintrc.json`. So it answers the same question the same way in every module, including the 146 of 198 that have not adopted lint, and it WILL disagree with a green build: the `nest` preset refuses `complexity` at 30 while this reports above 20.",
-    source: "oxlint complexity, at ESLint's published default of 20. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    caveat: "It does not say which function, nor whether branching is wrong there: a parser legitimately branches. \u26D4 This is a GAUGE and not the line your lint refuses at. It runs oxlint with its own config in a temporary directory, at a threshold fixed once for every module, and never reads the module's `.oxlintrc.json`. So it answers the same question the same way in every module, including the 146 of 198 that have not adopted lint, and it WILL disagree with a green build: the `nest` preset refuses `complexity` at 30 while this reports above 10.",
+    source: "oxlint complexity, above 10. The threshold comes from McCabe 1976, which puts the limit at 10, and from our own p90 at 11: the one indicator where two independent references agree within a unit. 94.8% of our functions already sit in the 1-10 band. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   "max-depth": {
     label: "Files with deep nesting",
-    what: "Files holding a block nested more than four levels deep.",
+    what: "Files holding a block nested more than three levels deep.",
     read: "The rarest of the indicators, 0.6 firings per 100 files across the repository, so one occurrence is worth opening rather than filtering. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
     caveat: "Depth is not complexity: four flat `if`s in a row never trip it, and one `if` inside three loops does.",
-    source: "oxlint max-depth, at ESLint's published default of 4. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    source: "oxlint max-depth, above 3. The threshold is IfSQ SP-2, which says few people can understand nesting of conditional statements beyond 3 levels, and our p90 agrees at 3. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   "max-lines": {
-    label: "Files over 300 lines",
-    what: "Files longer than 300 lines, blank lines and comments included.",
+    label: "Long files",
+    what: "Files longer than 150 lines, blank lines and comments included.",
     read: "A size signal and nothing else. Read it beside the duplication figure: a long file that duplicates nothing is a different problem from a long file that repeats itself. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
     caveat: "Length is not a defect. A generated file, a long constant table or a barrel is long by nature, which is why this is reported and never failed on.",
-    source: "oxlint max-lines, at ESLint's published default of 300. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    source: "oxlint max-lines, above 150. The threshold is our p90 of 157 rounded down, because no research anywhere sets a FILE's length: IfSQ's three citations (500, 100-150, 143) are all about routines. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   "max-lines-per-function": {
     label: "Files with a long function",
-    what: "Files holding at least one function longer than 50 lines.",
+    what: "Files holding at least one function longer than 109 lines.",
     read: "\u26A0\uFE0F A DESCRIPTOR, not part of the maintainability figure. It fires on 46.9 files per 100 across the repository, so it would fire on nearly every pull request. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
-    caveat: "What is excluded from the figure is the SCORE, not the reading: the count stays here precisely because it is frequent, and a module far from 46.9 is saying something.",
-    source: "oxlint max-lines-per-function, at ESLint's published default of 50. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    caveat: "Length is a signal and not a defect: a long function can be a flat list of fields. Read it beside the statement count, which is the other half of the same question, and which it does NOT duplicate: measured here, 255 long functions breach no statement count and 699 dense ones are not long.",
+    source: "oxlint max-lines-per-function, above 109. The threshold is our p90. IfSQ SP-1 says 150, citing IBM on routines over 500 lines, and is discarded here for being more permissive than our own code. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   "max-statements": {
     label: "Files with a long function body",
     what: "Files holding at least one function of more than ten statements.",
     read: "\u26A0\uFE0F A DESCRIPTOR, not part of the maintainability figure, for the same reason as the row above: 42.9 firings per 100 files. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
     caveat: "It counts statements and not work: ten calls in a row trip it where one dense expression does not.",
-    source: "oxlint max-statements, at ESLint's published default of 10. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    source: "oxlint max-statements, above 10. The threshold is the rule's own default, kept because our p90 of 15 is the looser of the two; it is not redundant with the line count, 699 functions breach it without being long and 255 are long without breaching it. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   "max-params": {
     label: "Files with a wide signature",
     what: "Files holding at least one function taking more than three parameters.",
     read: "The most frequent of the scored indicators, 9.6 per 100 files. A wide signature is usually an object waiting to be named. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
     caveat: "A destructured object parameter counts as one, so the figure does not see a function taking fifteen fields in one bag.",
-    source: "oxlint max-params, at ESLint's published default of 3. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    source: "oxlint max-params, above 3. The threshold is the rule\u2019s own default, kept because our p90 of 4 is looser; beyond three parameters the fix is an object or currying, so this is a design boundary rather than a dial. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   "max-nested-callbacks": {
     label: "Files with nested callbacks",
-    what: "Files holding callbacks nested more than ten deep.",
+    what: "Files holding callbacks nested more than three deep.",
     read: "Zero everywhere measured so far. Kept because a non-zero value is then unambiguous. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
     caveat: "It counts callbacks and not promise chains or awaits, so modern asynchronous code can be deeply sequential without ever tripping it.",
-    source: "oxlint max-nested-callbacks, at ESLint's published default of 10. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    source: "oxlint max-nested-callbacks, above 3. The threshold is IfSQ SP-2 again, same nesting family, and our p90 agrees at 3. It sat at 10 while the deepest chain in the repository is 4, so it reported 0 files for as long as it shipped. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   "max-classes-per-file": {
     label: "Files with several classes",
     what: "Files declaring more than one class.",
     read: "1.8 per 100 files. On a nest service it usually means a DTO file, which is a convention rather than a defect. A file is counted once per indicator, however many times the rule fires inside it. Measured on `libs/nest/auth`, counting diagnostics instead would have inflated the total by 1.8x, and by 2.8x at lower thresholds, because `max-nested-callbacks` reports once per level.",
     caveat: "It says nothing about the size of the classes, and a file with one 800-line class never appears here.",
-    source: "oxlint max-classes-per-file, at ESLint's published default of 1. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
+    source: "oxlint max-classes-per-file, above 1. The threshold is the rule's floor, there is no stricter value to pick. The rule for every one of the eight is `min(research, our p90, the rule's default)`, and a vendor default alone is not a reference: at 50, max-lines-per-function flagged 21.3% of our files and carried 77% of the union of all eight. The exclusions are the same list the duplication product pass is given, passed as `--ignore-pattern`: the `ignorePatterns` key in oxlint's config is accepted and silently ignored, which had this gauge measuring the test suite until the file counts were compared, 137 against 111 on `libs/nest/auth`."
   },
   usedOnlyByTests: {
     label: "Used only by tests",
@@ -5584,6 +5596,13 @@ var metricsHelp = {
     read: "A third state between alive and dead, and the only one of the three that names a design question rather than a defect: a production module shipping something only the suites consume. Zero is the ordinary value.",
     caveat: "It says nothing about whether that is wrong. A test factory deliberately published by a library belongs here and is doing its job. What it refuses to do is call those files dead, which is what a walk that ignores tests does: measured on `libs/nest/auth`, 11 live files are imported only from a test, `auth.module.ts` among them, and 47 projects depend on that module. \u26A0\uFE0F It sees FILES, so an export used only by specs inside a file that production also imports is invisible here.",
     source: "The workspace index in `workspace/consumers.ts`: one scan of the tracked files, specifiers resolved against the tsconfig aliases, an importer classified as a test by the same conventions the duplication pass uses. Measured on this repository: 278 such files in all, 39 of them in `libs/front/components`."
+  },
+  measuredFiles: {
+    label: "Files the gauge read",
+    what: "How many product files the size indicators were measured over.",
+    read: "The denominator of every size row above. None of them compares between modules without it: three breaches over 50 files and three over 3 000 are not the same module.",
+    caveat: "It is the gauge\u2019s population and not the module\u2019s: `src` only, tests, mocks and generated files excluded, which is the same list every other pass is given. So it is smaller than what `ls` would count, deliberately, and it will differ from the duplication pass\u2019s own file count, which drops files shorter than the detection window.",
+    source: "oxlint's `number_of_files` for the run this role drives, with the role's product exclusions passed as `--ignore-pattern`. Verified against the graph pass on `libs/nest/auth`: both read the same 99 files."
   }
 };
 function helpFor(key) {
@@ -6000,7 +6019,7 @@ import { existsSync as existsSync15, mkdirSync, readFileSync as readFileSync16,
 import { dirname as dirname2, join as join21, relative as relative4, resolve as resolve3, sep } from "node:path";
 var CACHE_DIR = join21("node_modules", ".cache", "sentinel");
 var CACHE_FILE = "consumer-index.json";
-var SHAPE = 3;
+var SHAPE = 4;
 var EXTENSIONS2 = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
 function workspaceRootFrom(cwd) {
   let dir = resolve3(cwd);
@@ -6070,6 +6089,24 @@ function resolveSpecifier2(specifier, table, workspaceRoot) {
   }
   return void 0;
 }
+function resolveRelative(importer, specifier, workspaceRoot) {
+  const base = join21(dirname2(importer), specifier).split(sep).join("/");
+  if (base.startsWith("..")) return void 0;
+  const isFile = (candidate) => {
+    try {
+      return statSync4(join21(workspaceRoot, candidate)).isFile();
+    } catch {
+      return false;
+    }
+  };
+  if (isFile(base)) return base;
+  for (const extension of EXTENSIONS2) if (isFile(base + extension)) return base + extension;
+  for (const extension of EXTENSIONS2) {
+    const index = `${base}/index${extension}`;
+    if (isFile(index)) return index;
+  }
+  return void 0;
+}
 function isTestFile(path2) {
   return /\.(test|spec|steps|e2e-spec|integration-spec|stories)\.[cm]?[jt]sx?$|(^|\/)(tests|__tests__|test|testing|stubs|__mocks__|mocks)\//.test(
     path2
@@ -6091,8 +6128,18 @@ function buildConsumerIndex(workspaceRoot, moduleRoots) {
   if (table.size === 0) return { imported, testOnly, builtFrom: "no alias table" };
   const result = spawnSync5(
     "git",
-    ["grep", "-I", "-n", "-o", "-E", "@[A-Za-z0-9_-]+/[A-Za-z0-9_./-]+", "--", "*.ts", "*.tsx"],
-    { cwd: workspaceRoot, encoding: "utf8", maxBuffer: 512 * 1024 * 1024 }
+    [
+      "grep",
+      "-I",
+      "-n",
+      "-o",
+      "-E",
+      "@[A-Za-z0-9_-]+/[A-Za-z0-9_./-]+|from '(\\.\\./)+[^']+'",
+      "--",
+      "*.ts",
+      "*.tsx"
+    ],
+    { cwd: workspaceRoot, encoding: "utf8", maxBuffer: 1024 * 1024 * 1024 }
   );
   if (result.error || result.status !== 0 && result.status !== 1) {
     return { imported, testOnly, builtFrom: "git grep failed" };
@@ -6106,8 +6153,16 @@ function buildConsumerIndex(workspaceRoot, moduleRoots) {
     if (first < 0 || second < 0) continue;
     const importer = line.slice(0, first).split(sep).join("/");
     const specifier = line.slice(second + 1);
-    if (!seen.has(specifier)) seen.set(specifier, resolveSpecifier2(specifier, table, workspaceRoot));
-    const target = seen.get(specifier);
+    let target;
+    const relative5 = /^from '((?:\.\.\/)+[^']+)'$/.exec(specifier)?.[1];
+    if (relative5) {
+      target = resolveRelative(importer, relative5, workspaceRoot);
+    } else {
+      if (!seen.has(specifier)) {
+        seen.set(specifier, resolveSpecifier2(specifier, table, workspaceRoot));
+      }
+      target = seen.get(specifier);
+    }
     if (!target) continue;
     if (moduleOf(importer, moduleRoots) === moduleOf(target, moduleRoots)) continue;
     imported.add(target);
@@ -6478,7 +6533,7 @@ function measuredWith(config) {
     // never appear as `(module)`: a gauge whose scale moves per module compares nothing.
     row(
       "size indicators",
-      `${Object.entries(PUBLISHED_THRESHOLDS).map(([rule, threshold]) => `${rule} ${threshold}`).join(", ")} (published defaults, oxlint run outside the module)`
+      `${Object.entries(GAUGE_THRESHOLDS).map(([rule, threshold]) => `${rule} ${threshold}`).join(", ")} (min(research, our p90, the rule's default), oxlint run outside the module)`
     ),
     // ⚠️ The graph pass's one knob, and it has to be here: it changes both the community count and
     // `Q`, so the two figures are meaningless without it. The seed is NOT printed beside it,
@@ -6773,10 +6828,13 @@ function assembleReport(ctx, config, product, tests, dead, complexity, graph, co
   } else if (!unreadable) {
     notes.push("fewer than two files, so no graph figure is reported");
   }
+  if (size && size.files > 0) {
+    rows.push({ metric: "measuredFiles", value: size.files, unit: "files the gauge read" });
+  }
   if (size) {
     const counts = /* @__PURE__ */ new Map();
     for (const breach of size.breaches) counts.set(breach.rule, (counts.get(breach.rule) ?? 0) + 1);
-    for (const [rule, threshold] of Object.entries(PUBLISHED_THRESHOLDS)) {
+    for (const [rule, threshold] of Object.entries(GAUGE_THRESHOLDS)) {
       const count = counts.get(rule) ?? 0;
       if (count === 0) continue;
       rows.push({

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-AFM4AJHA.js";
+} from "./chunk-BN6SCBFW.js";
 import {
   BaseAdapter
 } from "./chunk-KLEXJFJ6.js";

package/docs/static-analysis-study.md

@@ -548,6 +548,13 @@ The related work carries two results that challenge the Complexity category: Her
 that most code complexity metrics correlate highly with LOC, and Moser et al. that process
 metrics outperform code metrics as fault predictors.
 
+### IfSQ
+
+The one standard found that attaches a citation to a numeric limit, and the only external source
+used to fix this role’s own thresholds. It is a human-inspection standard rather than a tool, so its
+table sits with the decision it serves, in **11.4**: three of its fifteen indicators carry a number,
+and none of them is about a file’s length.
+
 ---
 
 ## 6. The tool, measured rather than read
@@ -866,6 +873,8 @@ each one fires per 100 files, which is measured rather than judged:
 | `max-params`           |                   3 |           9.6 |
 | `max-nested-callbacks` |                  10 |             0 |
 
+⛔ **Superseded by 10.7, and closed by 11.6.** The two figures below, and the break they rest on, were measured on four modules before two defects in the gauge were fixed: diagnostics counted as breaches, and a population that included the test suite. Over 177 modules the same two rules measure 10.4 and 6.9 per 100 files against the next at 4.6, a ratio of 1.5 rather than 4.5. Section 11 then changed the thresholds themselves, and at those the most frequent rule reaches 11.0% of files against 10.7% for the next: there is no break left to split on, so `DESCRIPTORS`, `scored` and `described` are removed and every indicator counts.
+
 **Which are out, and why.** There is a break in the data, a factor of 4.5, not a line we drew:
 
 | kept as a descriptor     | per 100 files |
@@ -968,17 +977,18 @@ touch no production file at all and the median touches **4**.
 
 ### 9.7 What is still a decision
 
-| open                               | what it needs                                                                                    |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
-| the `/10` in the `MI`              | the distribution over the 198 modules. It changes the spread, never the order                    |
-| the criticality order of the seven | one argument per indicator. Rarity rules two out, it does not rank the rest                      |
-| the overhead line of the SQL study | the harness rebuilt. #90 corrects the attribution and withdraws the 71%, which was never a ratio |
-| the workspace index for libraries  | built and measured in 10.4 and 10.5. Nothing open here any more                                  |
-| a feedback channel on findings     | unchanged from section 8, and it is what would let any of this be proven wrong                   |
+| open                                   | what it needs                                                                                                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| the `/10` in the `MI`                  | the distribution over the 198 modules. It changes the spread, never the order                                                         |
+| the criticality order of the **eight** | one argument per indicator. **Rarity no longer rules any out:** see 11.6, where the split is removed. Ranking the eight is still open |
+| the overhead line of the SQL study     | the harness rebuilt. #90 corrects the attribution and withdraws the 71%, which was never a ratio                                      |
+| the workspace index for libraries      | built and measured in 10.4 and 10.5. Nothing open here any more                                                                       |
+| a feedback channel on findings         | unchanged from section 8, and it is what would let any of this be proven wrong                                                        |
 
 The one measurement that unblocks the first two is the same: **the eight indicators over all 198
-modules, once.** Until then the figures in this section come from four modules and are quoted as
-such.
+modules, once.** That measurement now exists, in 10.7 over 177 modules and in 11 over a five-module
+bench, and it is what fixed the thresholds. The figures in THIS section still come from four modules
+and are quoted as such.
 
 ---
 
@@ -1173,7 +1183,245 @@ the binary failing. Measured: same 18 diagnostics either way, exit 1 against exi
 
 ---
 
-## 11. Sources
+### 10.7 The whole repository, measured, and what it does to 9.3
+
+Section 9.3 chose which indicators enter the maintainability figure by how often each fires per 100
+files, and excluded two of them on a **break of a factor 4.5** in that data. Those figures came from
+four modules, measured before two defects found while building the gauge were fixed. Here is the
+same question over **177 modules and 29 770 files**, with the gauge reading `src` only and counting
+a file once per indicator.
+
+| indicator                | per 100 files | modules above zero |
+| ------------------------ | ------------: | -----------------: |
+| `max-lines-per-function` |      **10.4** |                 75 |
+| `max-statements`         |       **6.9** |                 82 |
+| `max-params`             |           4.6 |                 69 |
+| `max-classes-per-file`   |           3.5 |                 53 |
+| `max-lines`              |           2.1 |                 59 |
+| `complexity`             |           0.8 |                 33 |
+| `max-depth`              |           0.0 |                 12 |
+| `max-nested-callbacks`   |           0.0 |                  0 |
+
+⛔ **The 4.5 break is gone, and it was an artefact of the measurement rather than a fact about the
+code.** Section 9.3 reported 46.9 and 42.9 for the two descriptors; the **same three modules**
+measured now give **14.4 and 7.7**. Two defects fixed tonight explain the direction and the order of
+magnitude:
+
+- diagnostics were counted where a breach is a (file, rule) pair. `max-nested-callbacks` fires once
+  per nesting level; measured, counting diagnostics inflates by **1.8x at the published thresholds
+  and 2.8x at lower ones**.
+- the population included the test suite, because `ignorePatterns` in oxlint's config is accepted
+  and silently ignored. Measured on `libs/front/components`: `max-lines-per-function` falls from
+  **33.6 to 23.9** per 100 files once the specs leave.
+
+What the clean data shows instead is a **smooth gradient**, consecutive ratios of 1.5, 1.5, 1.3,
+1.7, then 2.6 and finally 17.1 between `complexity` and `max-depth`:
+
+    max-lines-per-function  10.4  ->  max-statements  6.9   x1.5
+    max-statements           6.9  ->  max-params      4.6   x1.5
+    max-params               4.6  ->  max-classes     3.5   x1.3
+    max-classes              3.5  ->  max-lines       2.1   x1.7
+    max-lines                2.1  ->  complexity      0.8   x2.6
+    complexity               0.8  ->  max-depth       0.0  x17.1
+
+⚠️ **So the descriptor split now rests on nothing measured.** The two rules excluded from the figure
+are still the two most frequent, which is a reason to treat them with care, but 1.5x is not the 4.5x
+the decision was taken on, and inventing a cut here would be exactly the kind of threshold this
+document refuses elsewhere. The relative ORDER did survive: `complexity` below `max-lines` below
+`max-params` as before, with only `max-classes-per-file` moving up, from below `complexity` to above
+it.
+
+**This is left open rather than re-decided.** What the data supports today is one clean statement:
+`max-nested-callbacks` fires **nowhere** in the repository, and `max-depth` in 12 modules for 14
+files in all, so those two carry almost no information here whatever the figure does with them.
+
+---
+
+## 11. How each threshold was chosen
+
+Sections 9.3 and 10.7 left one question open: the gauge ran at the thresholds ESLint ships, which is
+not a choice, and 10.7 showed the one decision taken on those figures rested on a measurement
+defect. This section closes it. Every number in `GAUGE_THRESHOLDS` comes from one rule applied eight
+times, and the rule is stated before any figure so it cannot be fitted to a result afterwards.
+
+### 11.1 The rule: `min(research, our p90, the rule's default)`
+
+Three candidates per indicator, the strictest wins, and there is no fourth. The minimum is what
+makes it safe in **both** directions of failure, and both directions were observed here:
+
+- ⛔ **A threshold above what the code reaches detects nothing.** `max-nested-callbacks` shipped at
+  10 while the deepest chain in the repository is 4. It reported 0 files in 177 modules, for as long
+  as it existed. 10.7 recorded that as "carries almost no information"; the cause is simpler, the
+  scale was wrong.
+- ⛔ **Research can be more permissive than our own code, and then our code wins.** IfSQ's SP-1 puts
+  a routine at 150 lines. Our p90 is 109. Adopting 150 because a published standard says so would
+  relax a control to match a document, which is the opposite of measuring.
+
+A vendor default is a candidate, never a reference: it is shipped to fit every codebase, so it was
+calibrated on none. What it cost here is in 11.6.
+
+### 11.2 Three traps in deriving a threshold from our own distribution
+
+⚠️ **The p90 over the whole population collapses to 0 for four of the eight.** Ninety per cent of
+files never nest a block, never nest a callback, declare at most one class and take at most one
+parameter, so the percentile sits at the floor and a threshold of 0 flags everything. So "our p90"
+means **the p90 over the files the rule touches**, which is the only convention that does not
+collapse:
+
+| indicator              | p90 over all 8 083 files | p90 over the files it touches |
+| ---------------------- | -----------------------: | ----------------------------: |
+| `max-depth`            |                        0 |                             3 |
+| `max-nested-callbacks` |                        0 |                             3 |
+| `max-classes-per-file` |                        0 |                             5 |
+| `max-params`           |                        3 |                             4 |
+
+⚠️ **Rounding goes downward only.** `max-lines` derives a p90 of 157 and publishes 150. Rounding up
+would move a threshold away from the evidence that produced it, in the one direction the rule above
+exists to forbid.
+
+⛔ **The harness read seven of the eight message shapes.** oxlint parenthesises the measured value,
+`too many statements (20)`, except for `complexity`, which writes `has a complexity of 15`. A reader
+of the parenthesised form alone returns 0 for every complexity breach and says nothing about it: the
+first run of this bench reported **0 files above complexity 10, 15 and 20 alike**, which reads as
+"nothing to see" rather than as a broken instrument. The same defect sat in the role's own
+`valueOf`, where it was latent because no report row consumed the value yet. Both are fixed, and the
+regression test now uses the messages oxlint really emits rather than a paraphrase.
+
+### 11.3 The bench
+
+**8 083 product files over five modules**: `console` and `host-admin` (react), `front-components`
+(react library), `recruitment` and `network` (nest). The exclusion list is the role's own, so no
+spec, fixture, mock, story, generated or declaration file is in any figure below. Distributions come
+from one oxlint run per rule set with every maximum at 1, so each occurrence reports its real value
+instead of only its breach.
+
+### 11.4 What IfSQ gives, and what it does not
+
+IfSQ (ifsq.org) is the one standard found that states numeric limits with citations attached. It is
+a standard for **human inspection**: the level pages say what to look for, and `assessment.html`
+says who inspects, from self-assessment to third-party certification. There is no defect-density
+rule and no grade boundary anywhere on the site, checked page by page.
+
+**Three of its fifteen indicators carry a number:**
+
+| code     | indicator           | threshold                                      | citations given                                                                                                                                                                                                    |
+| -------- | ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **SP-1** | Routine Too Long    | > 150 lines, comments and blank lines excluded | IBM, "the most error-prone routines were those larger than 500 lines"; "when routines averaged 100 to 150 lines each, code was more stable"; "routines with 143 lines or less are 2.4 times less expensive to fix" |
+| **SP-2** | Nesting Too Deep    | > 3 levels of conditional nesting              | "few people can understand more than 3 levels of nested if statements". ⚠️ One finding page says "more than four" instead                                                                                          |
+| **SP-3** | Routine Too Complex | > 10 binary terms in conditionals              | McCabe 1976                                                                                                                                                                                                        |
+
+⛔ **IfSQ sources nothing about a FILE's length.** All three citations above are about routines. So
+`max-lines` has no research candidate at all, and its threshold is our p90 and nothing else.
+
+The remaining twelve state a defect to look for with no measurement: WIP-1 Vague "To Do", WIP-2
+Disabled Code, WIP-3 Empty Statement Block, SPM-1 Magic Numbers, SPM-2 Magic Strings, SPM-3
+Copy/Paste Programming, DP-1 Parameter Not Checked, DP-2 Status Ignored After Call, DP-3 Unexpected
+State Not Trapped, and the three Causes for Concern, which are an inspector's judgement. Of those,
+SPM-3 is already covered by the duplication pass and WIP-2 partly by the dead-code pass; WIP-1,
+WIP-3, SPM-1, SPM-2, DP-1 and DP-2 are candidates for indicators this role does not have yet.
+
+### 11.5 The eight thresholds, with their origin
+
+| indicator                | was |  **is** | research | our p90 | what decided it                                                                                           |
+| ------------------------ | --: | ------: | -------- | ------: | --------------------------------------------------------------------------------------------------------- |
+| `complexity`             |  20 |  **10** | 10       |      11 | the only indicator where two independent references agree within a unit                                   |
+| `max-lines-per-function` |  50 | **109** | 150      |     109 | research is more permissive than our code, so our code wins                                               |
+| `max-lines`              | 300 | **150** | none     |     157 | our p90, rounded down. No research sets a file's length                                                   |
+| `max-depth`              |   4 |   **3** | 3        |       3 | research and our code agree                                                                               |
+| `max-nested-callbacks`   |  10 |   **3** | 3 (SP-2) |       3 | same nesting family as SP-2, no citation of its own. Was above the repository's maximum of 4              |
+| `max-statements`         |  10 |  **10** | none     |      15 | the default is the stricter candidate and stays                                                           |
+| `max-params`             |   3 |   **3** | none     |       4 | the default stays. Beyond three parameters the fix is an object or currying, so this is a design boundary |
+| `max-classes-per-file`   |   1 |   **1** | none     |       5 | 1 is the rule's floor, there is no stricter value                                                         |
+
+Five move, and `complexity` is worth one line on its own: 94.8% of our 11 050 measured functions
+already sit in the 1-10 band the SEI calls low risk, so 10 is a ratchet rather than a demand.
+
+| SEI band            | functions |      share |
+| ------------------- | --------: | ---------: |
+| 1-10, low risk      |    10 475 | **94.8 %** |
+| 11-15               |       319 |      2.9 % |
+| 16-20               |       120 |      1.1 % |
+| 21-50, high risk    |       128 |      1.2 % |
+| over 50, untestable |         8 |      0.1 % |
+
+### 11.6 What the eight say together, and the end of the descriptor split
+
+A threshold is only half a decision: what matters is what the **set** reports.
+
+|                        |          at the vendor defaults | at the thresholds above |
+| ---------------------- | ------------------------------: | ----------------------: |
+| union of the eight     |             2 236 files, 27.7 % | **1 708 files, 21.1 %** |
+| largest single rule    | `max-lines-per-function`, 1 724 |   `max-statements`, 891 |
+| its share of the union |                        **77 %** |                **52 %** |
+
+⛔ **At the defaults one rule was the report.** `max-lines-per-function` at 50 flagged 21.3% of all
+product files and carried 77% of the union, so the other seven indicators were inaudible: the
+report said "your functions are longer than 50 lines" and nothing else could be heard beside it.
+
+And this closes what 10.7 left open. The descriptor split held `max-statements` and
+`max-lines-per-function` out of the figure on a **break of a factor 4.5** between 42.9/46.9 and 9.6
+per 100 files. 10.7 already showed those numbers were an artefact of two defects. At the thresholds
+above the two most frequent rules are 11.0% and 10.7%, and the next is 7.8%:
+
+| indicator                | files | per 100 files | ratio to the next |
+| ------------------------ | ----: | ------------: | ----------------: |
+| `max-statements`         |   891 |          11.0 |              1.03 |
+| `max-lines`              |   864 |          10.7 |              1.37 |
+| `max-lines-per-function` |   630 |           7.8 |              1.26 |
+| `complexity`             |   499 |           6.2 |              1.34 |
+| `max-params`             |   373 |           4.6 |              2.32 |
+| `max-classes-per-file`   |   161 |           2.0 |             17.89 |
+| `max-nested-callbacks`   |     9 |           0.1 |              1.13 |
+| `max-depth`              |     8 |           0.1 |                 - |
+
+**The top five are a smooth gradient, 1.03 to 1.37, so there is no population to exclude.** The one
+large break, 17.9, sits at the BOTTOM, between `max-classes-per-file` and the two nesting rules: it
+says those two are rare here, not that the frequent ones are noise. `DESCRIPTORS`, `scored` and
+`described` are removed: every indicator counts, and the asymmetry that needed explaining in two
+places no longer exists. Note also that the two nesting rules moved from reporting **nothing at all**
+to reporting 9 and 8 files: lowering them from 10 and 4 to 3 is what gave them any information.
+
+### 11.7 Why `max-statements` is not a second reading of `max-lines-per-function`
+
+The obvious objection to keeping both is that a long function has many statements. Measured by
+joining the two diagnostics on the same function span, over 25 658 functions of which 10 441 carry
+both values:
+
+|                                         |                      |
+| --------------------------------------- | -------------------: |
+| Pearson, statements against lines       |                0.726 |
+| Spearman                                |                0.600 |
+| lines per statement, p25 / median / p90 | 2.5 / **4.4** / 14.0 |
+
+Correlated, so not independent. But the density varies by a factor of **5.6** across functions, and
+that is what forbids giving them one value. At the chosen thresholds:
+
+|                               | functions | what it is               |
+| ----------------------------- | --------: | ------------------------ |
+| over both                     |       399 | long and dense           |
+| `max-statements` only         |   **699** | dense logic in few lines |
+| `max-lines-per-function` only |   **255** | long with little logic   |
+| overlap                       |  **29 %** |                          |
+
+Both shapes are real, and in this repository they are two different kinds of file:
+
+| file                                    | lines | statements | shape                  |
+| --------------------------------------- | ----: | ---------: | ---------------------- |
+| `add-to-network/JobsEvaluationList.tsx` |   259 |          2 | one large JSX return   |
+| `entities/job-offer.entity.ts`          |    48 |         46 | one statement per line |
+
+So `max-lines-per-function` measures volume including markup, and `max-statements` measures
+imperative density, and neither sees what the other sees. Giving `max-statements` the same 109 would
+kill it: at the median density that is a function of roughly 480 lines, so the line count would
+always fire first and the statement count would never say anything again.
+
+---
+
+## 12. Sources
+
+- IfSQ. _Level 1, Level 2 and Level 3 Standards for Code Quality._ <https://www.ifsq.org/level-1.html>,
+  <https://www.ifsq.org/level-2.html>, <https://www.ifsq.org/structured-programming.html>,
+  <https://www.ifsq.org/research.html>, <https://www.ifsq.org/assessment.html>
 
 - Ben Khalfallah, H. _Code Health Meter: A Quantitative and Graph-Theoretic Foundation for
   Automated Code Quality and Architecture Assessment._ ACM TOSEM 35(4), article 114, March 2026.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hublo/sentinel",
-  "version": "1.5.0-alpha.21",
+  "version": "1.5.0-alpha.22",
   "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",