@hublo/sentinel 1.5.0-alpha.24 → 1.5.0-alpha.26

package/dist/bin/sentinel.js

@@ -15,7 +15,7 @@ import {
   palette,
   registerAdapters,
   resolve
-} from "../chunk-VQZCC5QQ.js";
+} from "../chunk-WDZRBHMH.js";
 import {
   resolveContext
 } from "../chunk-ZMVI65FF.js";

package/dist/{chunk-VQZCC5QQ.js → chunk-WDZRBHMH.js}

@@ -5488,8 +5488,8 @@ var metricsHelp = {
   },
   deadLinesPercent: {
     label: "Unreachable lines",
-    what: "The share of scanned lines the reachability walk never reached from an entry point.",
-    read: "Higher is worse, and only once the entry-point count above says the question was decidable. Read it next to the four counts below rather than alone: one number covering files, exports, symbols and imports hides four different kinds of work.",
+    what: "The share of scanned lines the reachability walk never reached from an entry point, with the share of FILES those lines sit in beside it.",
+    read: "\u26D4 Read the two denominators together or the figure misleads, and that is measured rather than feared. On `apps/nest/microservices/agency` the line share is 60.21%, which reads as a rotten module or a broken tool; neither is true. 490 of its 504 files are reachable, and ONE unreachable file, a seed data table, holds 52 210 lines, 59.3% of the module by itself. A large line share over a small file share means a generated or seed file, not code anyone writes. Higher is worse, and only once the entry-point count above says the question was decidable. Read it next to the four counts below rather than alone: one number covering files, exports, symbols and imports hides four different kinds of work.",
     caveat: "Unreachable here means unreachable WITHIN this module, and that is a measured limitation rather than a theoretical one. A library is consumed from outside the scan, so its files look unreachable: on a sample of 12 files reported dead, 9 of `libs/front/components` and 7 of `libs/nest/auth` are cited elsewhere in the repository, one of them in 356 files. Test, fixture and story files are also outside the reachability graph, verified on a fixture, so a file reached only by a story is reported unreachable; it is true of the product and false of the repository, and `libs/front/components` has one such file of 915 lines.",
     source: "jscpd's dead-code engine, `deadLines` over `totalLines`. The library figures were measured per module with the workspace's own path aliases, and the story case was isolated on a four-file fixture where the only importer was a `.stories.tsx`."
   },
@@ -6009,6 +6009,7 @@ function renderMarkdown(report) {
     const family = familyOf(finding.metric);
     if (family !== void 0) places.set(family, (places.get(family) ?? 0) + 1);
   }
+  const version = report.settings.find((setting) => setting.key === "sentinel")?.value;
   const present = new Set(report.rows.map((row) => row.metric));
   const rows = FAMILIES.filter(
     (family) => family.metrics.some((metric) => present.has(metric)) || places.has(family.label)
@@ -6016,7 +6017,7 @@ function renderMarkdown(report) {
     const row = report.rows.find((candidate) => candidate.metric === family.headline);
     const marker = row?.status === void 0 ? "" : ` (${row.status})`;
     const shown = row?.unit.split(";")[0] ?? "";
-    const unit = shown === "" ? "" : `${shown === "%" ? "" : " "}${shown}`;
+    const unit = shown === "" ? "" : `${shown.startsWith("%") ? "" : " "}${shown}`;
     const value = row === void 0 ? "--" : `${figure(row)}${unit}${marker}`;
     const label = helpFor(family.headline)?.label ?? family.label;
     return `| ${label} | ${value} | ${places.get(family.label) ?? 0} |`;
@@ -6037,6 +6038,11 @@ ${report.notes.map((note) => `- ${note.split(". ")[0] ?? note}`).join("\n")}
     "> `(ok)` or `(exceed)` is where a figure sits against a PUBLISHED reference; a figure with no",
     "> marker has none, which is a decision and not a gap. A file breaching several rules counts",
     "> once per rule. The code behind every place is in the `static-analysis.html` artifact.",
+    // ⭐ The version that produced these numbers, because the thresholds a module cannot override
+    // live in the tool: nine gauge limits, the complexity bands, the bundle budgets. Two recaps
+    // from two versions are not comparable, and without this nothing on the comment would say so.
+    // Read from the settings the report already carries rather than from the package a second time.
+    ...version === void 0 ? [] : [`> Measured by sentinel ${version}.`],
     ""
   ].join("\n");
 }
@@ -7379,6 +7385,19 @@ function measuredWith(config) {
   const moved = (key) => config.moved.some((path2) => path2 === key || path2.startsWith(`${key}.`));
   const row = (key, value) => ({ key, value, moved: moved(key) });
   return [
+    /**
+     * ⭐ The tool's own version, first, and it is the same argument this list already makes about
+     * every other line: "6.81% found with `minTokens` at 50 and 6.81% found with it at 100 are not
+     * the same measurement". The version is the stronger case, because the numbers a module cannot
+     * override live HERE: the nine gauge thresholds, the complexity bands, the bundle budgets, and
+     * what each figure's unit means. `max-nested-callbacks` sat at 10 and now sits at 3;
+     * `complexityMax` carried a unit and no longer does. A report that does not name the version
+     * that produced it cannot be held against a report from last month, and nothing on the page
+     * would say why the two disagree.
+     *
+     * Never `moved`: it is not a setting a module can turn, which is exactly why it has to be said.
+     */
+    { key: "sentinel", value: readOwnPackage().version, moved: false },
     row("duplication.minTokens", String(config.duplication.minTokens)),
     row("duplication.minLines", String(config.duplication.minLines)),
     row("duplication.kinds", config.duplication.kinds.join(", ")),
@@ -7755,7 +7774,25 @@ function assembleReport(ctx, config, product, tests, dead, complexity, graph, co
         value: stats.entryPoints ?? 0,
         unit: `of ${stats.files ?? 0} files`
       },
-      { metric: "deadLinesPercent", value: share(stats), unit: "%" },
+      /**
+       * ⛔ The share of LINES, with the share of FILES beside it, because one without the other
+       * misleads and this was measured rather than imagined.
+       *
+       * On `apps/nest/microservices/agency` the line share reads **60.21%**, which in a
+       * pull-request comment says the module is rotten or the tool is broken. Neither is true:
+       * 490 of its 504 files are reachable, and a SINGLE unreachable file,
+       * `app/database/seed/data/legacy-agencies.ts`, holds **52 210 lines**, 59.3% of the module on
+       * its own. Twelve files carry 53 233 of the 53 242 dead lines.
+       *
+       * With both denominators the sentence reads correctly at a glance: 60% of the lines sit in
+       * 2% of the files, so the reader looks for a big generated or seed file instead of concluding
+       * anything about the code they write. Nothing is computed that the pass did not hand over.
+       */
+      {
+        metric: "deadLinesPercent",
+        value: share(stats),
+        unit: `% of lines, in ${(stats.files ?? 0) - (stats.reachableFiles ?? 0)} of ${stats.files ?? 0} files`
+      },
       // ⛔ Minus the files the TOOL itself labels `used-only-by-tests`. They were counted as
       // unreachable while the tool knew better: measured on `libs/nest/auth`, 5 of the 20. A file a
       // spec reaches is not unreachable, and leaving it in the headline count meant the figure

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-VQZCC5QQ.js";
+} from "./chunk-WDZRBHMH.js";
 import {
   BaseAdapter
 } from "./chunk-ZMVI65FF.js";

package/docs/bundle-analysis-spec.md

@@ -214,12 +214,12 @@ A report nobody opens is a report that changes nothing, and the published cases
 both of them put the figures where the review already happens. So this release does not stop at a
 page on disk.
 
-|                 |                                                                                                                     |
-| --------------- | ------------------------------------------------------------------------------------------------------------------- |
-| what is posted  | a recap of the figures for the fronts the pull request touched, with each band                                      |
-| when            | every run, not only on a breach: a recap that appears only when something is wrong is a recap nobody learns to read |
-| blocking        | **no**, and that is a choice for now rather than an end state                                                       |
-| on a second run | the same comment is updated, never a second one                                                                     |
+|                 |                                                                                                                        |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| what is posted  | one section per module the pull request touched: six rows, one per family, the headline figure and the places it holds |
+| when            | every run, not only on a breach: a recap that appears only when something is wrong is a recap nobody learns to read    |
+| blocking        | **no**, and that is a choice for now rather than an end state                                                          |
+| on a second run | the same comment is updated, never a second one                                                                        |
 
 ⛔ The division of labour matters, because getting it wrong couples this role to one CI provider.
 **sentinel renders the content, the repository's workflow posts it.** The content is markdown
@@ -227,6 +227,33 @@ produced from the same figures the other three shapes carry, which makes it test
 identical to what the console printed. Who holds the token, which event triggers it and how a
 comment is found again are the repository's business, not this role's.
 
+### 8.1 What it is, as built
+
+⚠️ It covers the **whole role**, not the bundle alone, and that is a correction to the line above
+that said "the fronts the pull request touched". A pull request touches libraries and services too,
+and a recap that stayed silent on them would teach a reader that this role only speaks about fronts.
+A module with no build gets five rows and a line saying why the sixth is absent.
+
+Three decisions worth stating, because each one was a fork:
+
+- **The headline per family is declared, not positional.** Three of the six would be wrong taken as
+  "the first metric listed": `importEdges` leads structure and is a size rather than a signal, so a
+  big module would look bad for being big, and `entryPoints` leads dead code and is the walk's
+  starting condition rather than a result.
+- **The row is named by the metric's own help label**, not the family's name. "Duplication | 0.75%"
+  does not say of what; "Duplicated lines" does. One wording, shared with the page.
+- **A marker says where a figure sits against a published reference**, `(ok)` included, and a row
+  with no marker has no reference rather than sitting inside one. Those are different facts, and
+  six of this role's figures genuinely have none.
+
+It reads no source file and lays out no graph: a recap shows no code, so it skips both the 201 file
+reads and the 5-second layout the page pays for.
+
+⛔ And it says on itself that it is **not compared with `main`**. See section 9: the delta needs a
+stored baseline. A figure in a pull-request comment is read as a delta by default, and that reading
+is wrong in the dangerous direction, since a module already at 6.81% looks exactly like one this
+branch pushed there.
+
 ## 9. Deferred, with the reason
 
 Recorded in issue #97. Both need something this release does not have, and neither changes a figure

package/package.json

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