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

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

@@ -53,15 +53,16 @@ import {
   selfCommand,
   splitToolArgs,
   walk
-} from "./chunk-KLEXJFJ6.js";
+} from "./chunk-IFK6KGUW.js";
 import {
   DEFAULT_MAX_DIAGNOSTICS,
   WORKSPACE_ROOT_MARKER,
   findWorkspaceRoot,
   moduleName,
+  ownPackageDir,
   readOwnPackage,
   readProjectPackageJson
-} from "./chunk-YQRDKWSH.js";
+} from "./chunk-JEYGPPSL.js";
 import {
   REPORT_DIR,
   SCRIPTS,
@@ -5104,7 +5105,7 @@ var SIZE = { width: 1600, height: 1200, margin: 30 };
 function hueOf(community) {
   return `hsl(${community * 137 % 360} 65% 52%)`;
 }
-function writeGraphPicture(graph, communities, path2) {
+function layOut(graph, communities) {
   const drawn = graph.copy();
   circular.assign(drawn);
   forceAtlas2.assign(drawn, { iterations: ITERATIONS, settings: forceAtlas2.inferSettings(drawn) });
@@ -5116,11 +5117,144 @@ function writeGraphPicture(graph, communities, path2) {
     drawn.setNodeAttribute(node, "color", hueOf(communities[node] ?? 0));
     drawn.setNodeAttribute(node, "label", named.has(node) ? node.split("/").pop() ?? node : BLANK);
   });
+  return drawn;
+}
+function writeGraphPicture(drawn, path2) {
   return new Promise((resolve5) => {
     renderSvg(drawn, path2, SIZE, () => resolve5());
   });
 }
 
+// src/roles/static-analysis/graph/explorer.ts
+function place(graph) {
+  const nodes = graph.nodes();
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (const node of nodes) {
+    const x = graph.getNodeAttribute(node, "x");
+    const y = graph.getNodeAttribute(node, "y");
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+  const usableWidth = SIZE.width - 2 * SIZE.margin;
+  const usableHeight = SIZE.height - 2 * SIZE.margin;
+  const spanX = maxX - minX || 1;
+  const spanY = maxY - minY || 1;
+  const scale = Math.min(usableWidth / spanX, usableHeight / spanY);
+  const offsetX = SIZE.margin + (usableWidth - spanX * scale) / 2;
+  const offsetY = SIZE.margin + (usableHeight - spanY * scale) / 2;
+  const placed = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const x = graph.getNodeAttribute(node, "x");
+    const y = graph.getNodeAttribute(node, "y");
+    placed.set(node, {
+      x: offsetX + (x - minX) * scale,
+      y: offsetY + (y - minY) * scale,
+      // `size` is already the sqrt-damped degree `picture.ts` computed, in the same units as the
+      // standalone image, so the two drawings show a file at the same weight.
+      r: graph.getNodeAttribute(node, "size")
+    });
+  }
+  return placed;
+}
+function round(value) {
+  return (Math.round(value * 100) / 100).toString();
+}
+function hueOf2(community) {
+  return `hsl(${community * 137 % 360} 65% 52%)`;
+}
+function jsonInScript(value) {
+  return value.replace(/</g, "\\u003c");
+}
+function buildExplorer(drawn, communities) {
+  const placed = place(drawn);
+  const nodes = [...placed.keys()];
+  const index = new Map(nodes.map((node, position) => [node, position]));
+  const edges = [];
+  const segments = [];
+  drawn.forEachEdge((_edge, _attributes, source, target) => {
+    const from = placed.get(source);
+    const to = placed.get(target);
+    const sourceIndex = index.get(source);
+    const targetIndex = index.get(target);
+    if (!from || !to || sourceIndex === void 0 || targetIndex === void 0) return;
+    segments.push(`M${round(from.x)} ${round(from.y)}L${round(to.x)} ${round(to.y)}`);
+    edges.push(sourceIndex, targetIndex);
+  });
+  const used = [...new Set(nodes.map((node) => communities[node] ?? 0))].sort((a, b) => a - b);
+  const palette2 = used.map((community) => `.g svg .k${community}{fill:${hueOf2(community)}}`).join("");
+  const circles = nodes.map((node) => {
+    const spot = placed.get(node);
+    if (!spot) return "";
+    const community = communities[node] ?? 0;
+    return `<circle cx="${round(spot.x)}" cy="${round(spot.y)}" r="${round(spot.r)}" class="k${community}"/>`;
+  }).join("");
+  const payload = JSON.stringify({ f: nodes, e: edges });
+  const markup = `<section class="g">
+  <p class="read">One dot per file, sized by how many imports touch it, coloured by the community it landed in. The shape is the answer to how many lobes there are and whether they are joined. <b>Point at a dot for its path, click it to keep only that file and its neighbours, click the background to come back.</b></p>
+  <div class="gbar"><output id="gname">&nbsp;</output><button type="button" id="greset" hidden>show everything</button></div>
+  <svg viewBox="0 0 ${SIZE.width} ${SIZE.height}" role="img" aria-label="The module's import graph, one dot per file">
+    <path class="ge" d="${segments.join("")}"/>
+    <path class="gh" d=""/>
+    <g class="gn">${circles}</g>
+  </svg>
+  <style>${palette2}</style>
+  <script type="application/json" id="gdata">${jsonInScript(payload)}</script>
+  <script>${SCRIPT}</script>
+</section>`;
+  return { markup, bytes: Buffer.byteLength(markup, "utf8") };
+}
+var SCRIPT = `(function(){
+  var root=document.currentScript.closest('.g');
+  var data=JSON.parse(root.querySelector('#gdata').textContent);
+  var dots=root.querySelectorAll('.gn circle');
+  var name=root.querySelector('#gname');
+  var reset=root.querySelector('#greset');
+  var highlight=root.querySelector('.gh');
+  var out=[],inn=[];
+  for(var i=0;i<data.f.length;i++){out.push([]);inn.push([]);}
+  for(var k=0;k<data.e.length;k+=2){out[data.e[k]].push(data.e[k+1]);inn[data.e[k+1]].push(data.e[k]);}
+  function show(i){
+    name.textContent=data.f[i]+'  ('+out[i].length+' imported, '+inn[i].length+' importing)';
+  }
+  function clear(){
+    root.classList.remove('gsel');
+    highlight.setAttribute('d','');
+    for(var i=0;i<dots.length;i++)dots[i].classList.remove('gon','gpick');
+    name.innerHTML='&nbsp;';
+    reset.hidden=true;
+  }
+  function pick(i){
+    root.classList.add('gsel');
+    var near={};near[i]=1;
+    var d='';
+    function seg(a,b){
+      d+='M'+dots[a].getAttribute('cx')+' '+dots[a].getAttribute('cy')+'L'+dots[b].getAttribute('cx')+' '+dots[b].getAttribute('cy');
+    }
+    for(var a=0;a<out[i].length;a++){near[out[i][a]]=1;seg(i,out[i][a]);}
+    for(var b=0;b<inn[i].length;b++){near[inn[i][b]]=1;seg(inn[i][b],i);}
+    highlight.setAttribute('d',d);
+    for(var j=0;j<dots.length;j++){
+      dots[j].classList.toggle('gon',!!near[j]);
+      dots[j].classList.toggle('gpick',j===i);
+    }
+    show(i);
+    reset.hidden=false;
+  }
+  for(var n=0;n<dots.length;n++){
+    (function(i){
+      dots[i].addEventListener('mouseenter',function(){show(i);});
+      dots[i].addEventListener('click',function(event){event.stopPropagation();pick(i);});
+    })(n);
+  }
+  root.querySelector('svg').addEventListener('click',clear);
+  reset.addEventListener('click',clear);
+})();`;
+
 // src/roles/static-analysis/graph/scan.ts
 import Graph from "graphology";
 import louvain from "graphology-communities-louvain";
@@ -5283,16 +5417,35 @@ 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,
-  "max-classes-per-file": 1
+  // 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,
+  // Cognitive complexity, Campbell 2018, measured by Sonar's own rule, loaded
+  // through `plugins/sonar-cognitive.js`.
+  // Sonar publishes 15 for S3776, and that is a vendor default rather than a research value: one of
+  // their own engineers has said publicly that no formula supports it. Our p90 is 7, so 7 wins, and
+  // it reports 342 of 8 083 files, 4.2%, which sits inside the band the eight above occupy.
+  "cognitive-complexity": 7
 };
+var COGNITIVE = "cognitive-complexity";
+var cognitivePlugin = () => join20(ownPackageDir(), "plugins", "sonar-cognitive.js");
 var CATEGORIES = [
   "correctness",
   "suspicious",
@@ -5306,13 +5459,20 @@ function sizeRulesConfig() {
   return {
     plugins: [],
     categories: Object.fromEntries(CATEGORIES.map((category) => [category, "off"])),
+    // Sonar's cognitive complexity, in the SAME run as the eight above rather than a second
+    // invocation: the parse is the expensive part and it is already paid here. Measured over the
+    // whole bench, 8 083 files, the rule adds 2.4 s to a pass that was going to read them anyway.
+    jsPlugins: [cognitivePlugin()],
     // ⛔ `warn` and not `error`, for the reason `tool-config.ts` gives about jscpd's `threshold`:
     // at `error` oxlint exits 1 as soon as one file breaches, which is indistinguishable from the
     // binary failing to run. Measured on `libs/nest/auth`, same config otherwise: `error` exits 1,
     // `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 === COGNITIVE ? `sonar/${rule}` : rule,
+        ["warn", threshold]
+      ])
     )
   };
 }
@@ -5341,7 +5501,10 @@ 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) ?? // Sonar's own wording, a third shape again: "reduce its Cognitive Complexity from 7 to the 0
+  // allowed". It parenthesises nothing, and the `0` after it is the threshold, not the value.
+  /Complexity from (\d+) to/.exec(message);
+  return Number(match?.[1] ?? 0);
 }
 function breachesOf(raw) {
   let parsed;
@@ -5355,7 +5518,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 +5687,66 @@ 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`."
+  },
+  "cognitive-complexity": {
+    label: "Files hard to follow",
+    what: "Files holding at least one function whose cognitive complexity passes 7.",
+    read: "The other complexity figure, and it answers a different question from McCabe's: not how many paths a test suite must cover, but how much a reader has to hold in their head. The two disagree on purpose. A flat `switch` with twelve cases is cyclomatically 13 and cognitively 1, because nothing is nested and nothing surprises; three `if`s inside each other are cyclomatically 4 and cognitively 6, because each level is charged for the levels above it. When a file is high here and low there, the code is tangled rather than merely branchy, and that is the one this role would act on first.",
+    caveat: "\u26A0\uFE0F In JavaScript and TypeScript, sequences of `||` and `??` do NOT increment, deliberately: in this language they are overwhelmingly default-value shorthand rather than control flow, and SonarSource made that exclusion universal in SonarQube 10.8. So a long chain of fallbacks scores zero here while `&&` chains are charged. \u26D4 And it is a GAUGE, not the line your lint refuses at: no preset in this repository enforces cognitive complexity at all today.",
+    source: "Sonar's own `cognitive-complexity` rule from `eslint-plugin-sonarjs`, loaded into oxlint through `plugins/sonar-cognitive.js` and run in the same invocation as the size rules. It is USED and never copied: that package ships under the Sonar Source-Available License and sentinel is MIT. The algorithm is Campbell 2018 and its author works at SonarSource, so their implementation is the specification's own house rather than one reading of it; verified against Campbell's published example, which scores 7 in both. The threshold is 7, from `min(research, our p90, the rule's default)`: Sonar publishes 15 for S3776 and that is a vendor default rather than a research value, since one of their own engineers has said publicly that no formula supports it, while our p90 over the files the rule touches is 7. It reports 342 of 8 083 files on the bench, 4.2%."
   },
   usedOnlyByTests: {
     label: "Used only by tests",
@@ -5584,6 +5754,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) {
@@ -5883,8 +6060,35 @@ ${rest > 0 ? `    <p class="sub">The ${HTML_GROUP_LIMIT} longest are listed; ${r
     white-space: nowrap;
   }
   /* The graph. The svg carries a viewBox, so dropping its fixed width lets it fill the column. */
-  .picture svg { width: 100%; height: auto; display: block; }
-  .picture p.read { margin: 0 0 0.8rem; padding: 0 0.6rem; color: var(--ink-soft); font-size: 0.88rem; max-width: 52rem; }
+  .g svg { width: 100%; height: auto; display: block; }
+  .g p.read { margin: 0 0 0.8rem; padding: 0 0.6rem; color: var(--ink-soft); font-size: 0.88rem; max-width: 52rem; }
+  /* Every edge in one path, faint: it carries the shape, not a readable dependency. */
+  .g .ge { stroke: var(--rule); stroke-width: 0.6; fill: none; }
+  /* The selected file's own edges, drawn on top only once something is picked. */
+  .g .gh { stroke: var(--brand); stroke-width: 1.4; fill: none; }
+  .g .gn circle { cursor: pointer; }
+  /* Dim the module once a file is picked, so its neighbourhood is what is left to read. The
+     opacity sits on the GROUP and the exceptions raise themselves back: one rule instead of one
+     class per dot, which matters at 4 380 of them. */
+  .g.gsel .gn circle { opacity: 0.12; }
+  .g.gsel .gn circle.gon { opacity: 1; }
+  .g.gsel .gn circle.gpick { opacity: 1; stroke: var(--ink); stroke-width: 2; }
+  .g.gsel .ge { opacity: 0.25; }
+  /* The caption. A min-height and not a conditional row: the drawing must not jump by a line
+     when a name appears, which is exactly what pointing at a dot would cause. */
+  .gbar {
+    display: flex; gap: 0.6rem; align-items: center; justify-content: space-between;
+    min-height: 1.9rem; padding: 0 0.6rem; margin-bottom: 0.3rem;
+  }
+  .gbar output {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.82rem;
+    color: var(--ink); overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .gbar button {
+    font: inherit; font-size: 0.8rem; cursor: pointer; white-space: nowrap;
+    padding: 0.2rem 0.6rem; border: 1px solid var(--rule); border-radius: 0.3rem;
+    background: var(--surface); color: var(--ink-soft);
+  }
 
   /* The collapsed reserves. Closed by default: the figures are what the page opens on. */
   details { border-bottom: 1px solid var(--rule); }
@@ -5965,10 +6169,7 @@ ${report.notes.map((note) => `      <tr><td class="read">${escape(note)}</td></t
 ` : ""}
 ${report.picture ? `
   <h2>Shape</h2>
-  <section class="picture">
-    <p class="read">One dot per file, sized by how many imports touch it, coloured by the community it landed in. It shows the SHAPE: how many lobes, whether they are joined, where everything converges. The names are in the tables below.</p>
 ${report.picture}
-  </section>
 ` : ""}
   <h2>What these numbers do not say</h2>
   <section>
@@ -6000,7 +6201,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 +6271,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 +6310,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 +6335,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 +6715,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 +7010,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({
@@ -6824,11 +7064,12 @@ async function emit(report, shape, cwd, graph, coverage) {
   mkdirSync2(join22(cwd, REPORT_DIR), { recursive: true });
   const written = [];
   if (shape === "html" && graph.files > 1 && !hasUnreadableCode(coverage)) {
+    const drawn = layOut(graph.graph, graph.communityOf);
     const picture = `${TARGET}-graph.svg`;
     const path2 = join22(cwd, REPORT_DIR, picture);
-    await writeGraphPicture(graph.graph, graph.communityOf, path2);
+    await writeGraphPicture(drawn, path2);
     written.push(`${REPORT_DIR}/${picture}`);
-    report.picture = inlineable(readFileSync17(path2, "utf8"));
+    report.picture = buildExplorer(drawn, graph.communityOf).markup;
   }
   const name = shape === "json" ? "static-analysis.json" : "static-analysis.html";
   const body = shape === "json" ? renderJson(report) : renderHtml(report);
@@ -6838,9 +7079,6 @@ async function emit(report, shape, cwd, graph, coverage) {
   written: ${written.join(", ")}
 `);
 }
-function inlineable(svg) {
-  return svg.replace(/^<\?xml[^>]*\?>\s*/, "").replace(/^(<svg)\s+width="[^"]*"\s+height="[^"]*"/, "$1");
-}
 function metricsOf(report) {
   return {
     passes: report.passes,

package/dist/index.js

@@ -6,11 +6,11 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-AFM4AJHA.js";
+} from "./chunk-TL2P2X45.js";
 import {
   BaseAdapter
-} from "./chunk-KLEXJFJ6.js";
-import "./chunk-YQRDKWSH.js";
+} from "./chunk-IFK6KGUW.js";
+import "./chunk-JEYGPPSL.js";
 import "./chunk-AYEOGJQR.js";
 import "./chunk-O7REVMOC.js";
 import "./chunk-QXFCZON7.js";

package/dist/roles/test/setup/jest-parity.js

@@ -3,13 +3,13 @@ import {
 } from "../../../chunk-NUOQXAYR.js";
 import {
   installWorkspaceSetup
-} from "../../../chunk-AMCGMLPS.js";
+} from "../../../chunk-SPES5MQT.js";
 import "../../../chunk-ELZHIN6E.js";
 import {
   clearDeepMocks,
   resetDeepMocks
 } from "../../../chunk-2XLX6PFR.js";
-import "../../../chunk-YQRDKWSH.js";
+import "../../../chunk-JEYGPPSL.js";
 
 // src/roles/test/setup/jest-parity.ts
 import { expect, vi } from "vitest";

package/dist/roles/test/setup/workspace-entry.js

@@ -1,8 +1,8 @@
 import {
   pinWorkspaceTimezone
-} from "../../../chunk-AMCGMLPS.js";
+} from "../../../chunk-SPES5MQT.js";
 import "../../../chunk-ELZHIN6E.js";
-import "../../../chunk-YQRDKWSH.js";
+import "../../../chunk-JEYGPPSL.js";
 
 // src/roles/test/setup/workspace-entry.ts
 await pinWorkspaceTimezone();

package/dist/{validate-AWWMBSH5.js → validate-7VBODB4M.js}

@@ -7,8 +7,8 @@ import {
   readTestAdoption,
   resolveVitest,
   suiteOf
-} from "./chunk-KLEXJFJ6.js";
-import "./chunk-YQRDKWSH.js";
+} from "./chunk-IFK6KGUW.js";
+import "./chunk-JEYGPPSL.js";
 import "./chunk-O7REVMOC.js";
 import "./chunk-QXFCZON7.js";