@hublo/sentinel 1.5.0-alpha.6 → 1.5.0-alpha.8

package/dist/bin/sentinel.js

@@ -15,7 +15,7 @@ import {
   palette,
   registerAdapters,
   resolve
-} from "../chunk-JJKFLYHK.js";
+} from "../chunk-DKLQYGPI.js";
 import {
   resolveContext
 } from "../chunk-KLEXJFJ6.js";
@@ -26,7 +26,7 @@ import {
   readOwnVersion,
   readProjectPackageJson
 } from "../chunk-YQRDKWSH.js";
-import "../chunk-DVKTH3RY.js";
+import "../chunk-EDFIVLUA.js";
 import "../chunk-O7REVMOC.js";
 import "../chunk-QXFCZON7.js";
 

package/dist/{chunk-JJKFLYHK.js → chunk-DKLQYGPI.js}

@@ -65,7 +65,7 @@ import {
   REPORT_DIR,
   defineStaticAnalysis,
   isPlainObject
-} from "./chunk-DVKTH3RY.js";
+} from "./chunk-EDFIVLUA.js";
 import {
   parseJsonc
 } from "./chunk-QXFCZON7.js";
@@ -4788,11 +4788,25 @@ function adopt(exported) {
 var metricsHelp = {
   duplicatedLinesPercent: {
     label: "Duplicated lines",
-    what: "The share of lines jscpd found in at least one clone, over the lines it scanned.",
-    read: "Higher is worse. It is computed per module, so two modules compare directly; the repository-wide figure is not the average of theirs, because modules differ in size.",
-    caveat: "A clone is not automatically a defect. Two screens that genuinely do the same thing are supposed to look alike, and extracting them can couple two features that have no reason to change together. The usual reading is the Rule of Three: a second occurrence is tolerable, a third is the signal to refactor. This share cannot apply that rule for you, because it counts lines, not how many times one fragment occurs.",
+    what: "The share of lines jscpd found in at least one clone, over the lines of the files it was able to scan.",
+    read: "Higher is worse. It is computed per module, so two modules compare directly as long as they measured with the same settings, which is what the settings printed under the figures are for; the repository-wide figure is not the average of theirs, because modules differ in size.",
+    caveat: "A clone is not automatically a defect. Two screens that genuinely do the same thing are supposed to look alike, and extracting them can couple two features that have no reason to change together. The usual reading is the Rule of Three: a second occurrence is tolerable, a third is the signal to refactor. This share cannot apply that rule for you, because it counts lines, not how many times one fragment occurs. The denominator is also narrower than the module: a file shorter than the detection window cannot contain a clone, so the tool leaves it out of both counts, which on one front app is 31 files of 596, or 5%.",
     source: "jscpd, over the token stream rather than the text: for JavaScript and TypeScript the tokens come from the oxc parser, which emits neither whitespace nor comments, so reindenting a block is not a clone and `--mode` measured identical on all three values. Rule of Three: Fowler, Refactoring, crediting Don Roberts."
   },
+  duplicatedLinesPercentTests: {
+    label: "Duplicated lines (tests)",
+    what: "The same share, measured over this module's test files alone.",
+    read: "Read it DIFFERENTLY from the figure above rather than as a worse version of it. Repetition in a spec is often deliberate: a test that spells out its own setup can be read on its own, and factoring that setup into a helper is what makes a failing test hard to diagnose. The figure is here because its size is a fact about the specs, not because it is a debt to pay down.",
+    caveat: "It says nothing about whether the tests are good, and a high value is not automatically a problem: the two common causes are a deliberately explicit setup, which is a defensible style, and a suite copied file by file as the module grew, which is not, and this number cannot tell them apart. The split is also why it exists at all: measured across 8 modules of the three families, 71% of all duplicated lines are between two test files, so a single blended figure was mostly this one wearing the name of the module.",
+    source: "Same tool and same detection window as the figure above, over the files matching this role's test glob, which is printed under the figures. The 71% was measured on apps/front/console, host-admin, hr-management, libs/front/components, libs/front/shared, apps/nest/microservices/contract, apps/nest/microservices/agency and libs/nest/auth."
+  },
+  clonesTests: {
+    label: "Clones (tests)",
+    what: "How many duplicated fragments the test pass reported.",
+    read: "A count, with the same reserves as the product one above.",
+    caveat: "Everything the product clone count does not say applies here unchanged. One more thing is specific to the split: the two passes partition the files, so a fragment shared between a test and a product file has a partner in NEITHER pass and is counted in neither number. Measured on the same 8 modules, that is 42 entries of 5117, 0.8%, and 650 lines.",
+    source: "jscpd report statistics for the test pass. The partition and its loss were verified on apps/front/console: 478 product files plus 87 test files are the 565 of a blended scan, and 32 plus 40 are its 72 entries."
+  },
   clones: {
     label: "Clones",
     what: "How many duplicated fragments jscpd reported, each entry linking two places that match.",
@@ -4817,6 +4831,9 @@ function renderConsole(report) {
   for (const row of report.rows) {
     lines.push(`    ${label(row).padEnd(labelWidth)}  ${value(row).padStart(valueWidth)}`);
   }
+  if (!report.passes.some((pass) => pass.includes("tests"))) {
+    lines.push("    (no test file to measure, so no test figure is reported)");
+  }
   if (report.settings.length > 0) {
     const keyWidth = Math.max(...report.settings.map((setting) => setting.key.length));
     lines.push("", "  measured with");
@@ -4830,13 +4847,13 @@ function renderConsole(report) {
     }
   }
   if (report.byLanguage && Object.keys(report.byLanguage).length > 0) {
-    lines.push("", "  per language, where a clone was found");
+    lines.push("", "  per language, where a clone was found in the product code");
     for (const [language, stats] of Object.entries(report.byLanguage)) {
       lines.push(
         `    ${language.padEnd(12)} ${stats.percentage.toFixed(2)}% (${stats.duplicatedLines} lines over ${stats.files} files)`
       );
     }
-    lines.push("    a language with no clone is not listed");
+    lines.push("    a language is absent when no file of it was long enough to scan");
   }
   const caveats = report.rows.map((row) => ({ row, help: helpFor(row.metric) })).filter(
     (entry) => Boolean(entry.help)
@@ -4933,7 +4950,20 @@ ${settings}
 import { mkdtempSync, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join as join18 } from "node:path";
-function fileSettings(config) {
+var OWN_ARTEFACTS = [`**/${STATIC_CONFIG_FILE}`, `**/${REPORT_DIR}/**`];
+function testGlobs(config) {
+  const relative4 = config.duplication.tests;
+  return {
+    ignore: relative4.map((glob) => `**/${glob}`),
+    // A one-item brace group is avoided rather than trusted: nothing guarantees `{x}` expands.
+    pattern: relative4.length === 1 ? `**/${relative4[0]}` : `**/{${relative4.join(",")}}`
+  };
+}
+function exclusions(config, scope = "tests") {
+  const tests = scope === "product" ? testGlobs(config).ignore : [];
+  return [.../* @__PURE__ */ new Set([...config.ignore, ...OWN_ARTEFACTS, ...tests])];
+}
+function fileSettings(config, scope) {
   return {
     // The detection window. Stated rather than defaulted, because it decides what is invisible.
     minTokens: config.duplication.minTokens,
@@ -4941,7 +4971,7 @@ function fileSettings(config) {
     // `format` is jscpd's name for what we call `languages`. Naming `typescript` alone would
     // leave out `.tsx`, which is a separate language to it: 300 files of 523 on front/console.
     format: config.languages,
-    ignore: config.ignore,
+    ignore: exclusions(config, scope),
     // A scan that analyses nothing otherwise exits 0 with only a warning, which reads as a pass.
     failOnEmpty: true,
     // The dead-code engine keeps its own section, and its own `minLines`: jscpd's documentation is
@@ -4955,14 +4985,19 @@ function fileSettings(config) {
     ...config.tools.jscpd
   };
 }
-function duplicationRun(config, paths) {
+function duplicationRun(config, paths, scope) {
   const dir = mkdtempSync(join18(tmpdir(), "sentinel-static-"));
   const configPath = join18(dir, "jscpd.json");
-  writeFileSync3(configPath, `${JSON.stringify(fileSettings(config), null, 2)}
+  writeFileSync3(configPath, `${JSON.stringify(fileSettings(config, scope), null, 2)}
 `, "utf8");
   const args = [
     "--config",
     configPath,
+    // The test pass SELECTS its files; the product pass excludes them through `ignore` above. A
+    // flag and not a config key, because `--pattern` is the only documented way in and it takes
+    // exactly one glob, braces expanded. Verified: 478 product files + 87 test files = the 565 of
+    // a blended scan on `apps/front/console`.
+    ...scope === "tests" ? ["--pattern", testGlobs(config).pattern] : [],
     // Always json, and only json, whatever shape the caller asked for. The three shapes are
     // rendered by this role from the figures, not by the tool: one report lives under
     // `static-analysis`, assembled from several passes, so a per-pass console table from the tool
@@ -5094,41 +5129,21 @@ var JscpdAdapter = class extends BaseAdapter {
       return { ok: false, code: 1 };
     }
     const { paths } = splitToolArgs(ctx.cwd, ctx.toolArgs, { valueFlags: ["-c", "--config"] });
-    const { args, rawReportDir, dispose } = duplicationRun(config, paths.length > 0 ? paths : ["."]);
-    try {
-      const result = spawnSync5(jscpd, args, { cwd: ctx.cwd, encoding: "utf8" });
-      if (result.error) {
-        process.stderr.write(
-          `sentinel static-analysis(jscpd): could not run jscpd (${result.error.message})
-`
-        );
-        return { ok: false, code: 1 };
-      }
-      if (result.status !== 0) {
-        if (analysedNothing(result.stderr)) {
-          process.stderr.write(
-            `sentinel static-analysis(jscpd): nothing left to measure in this module once the exclusions applied, so no figure is reported (a figure of 0% would be a different claim).
+    const scanned = paths.length > 0 ? paths : ["."];
+    const product = runPass(jscpd, config, scanned, "product", ctx.cwd);
+    if (product.kind === "failed") return { ok: false, code: product.code };
+    if (product.kind === "empty") {
+      process.stderr.write(
+        `sentinel static-analysis(jscpd): nothing left to measure in this module once the exclusions applied, so no figure is reported (a figure of 0% would be a different claim).
 `
-          );
-          return { ok: true, code: 0 };
-        }
-        process.stderr.write(
-          `sentinel static-analysis(jscpd): jscpd exited ${result.status}
-${result.stderr ?? ""}`
-        );
-        return { ok: false, code: result.status ?? 1 };
-      }
-      const report = buildReport(ctx, rawReportDir, config);
-      if (!report) {
-        process.stderr.write(`sentinel static-analysis(jscpd): jscpd wrote no report
-`);
-        return { ok: false, code: 1 };
-      }
-      if (emitting) emit(report, shape, ctx.cwd);
-      return { ok: true, code: 0, metrics: metricsOf(report) };
-    } finally {
-      dispose();
+      );
+      return { ok: true, code: 0 };
     }
+    const tests = runPass(jscpd, config, scanned, "tests", ctx.cwd);
+    if (tests.kind === "failed") return { ok: false, code: tests.code };
+    const report = assemble(ctx, config, product, tests);
+    if (emitting) emit(report, shape, ctx.cwd);
+    return { ok: true, code: 0, metrics: metricsOf(report) };
   }
   /** `--run`: measure and show it. */
   async run(ctx) {
@@ -5174,28 +5189,68 @@ function duplicationSettings(config) {
     row("duplication.minLines", String(config.duplication.minLines)),
     row("duplication.kinds", config.duplication.kinds.join(", ")),
     row("languages", `${config.languages.length}: ${config.languages.join(", ")}`),
-    row("ignore", `${config.ignore.length} patterns`)
+    // The count the SCAN received, not the module's list: the role unions its own artefacts in,
+    // and printing 20 while measuring with 22 is the kind of small lie that costs an afternoon.
+    // The product pass, which is the one the headline figure comes from.
+    row("ignore", `${exclusions(config, "product").length} patterns`),
+    row("duplication.tests", config.duplication.tests.join("  "))
   ];
 }
-function buildReport(ctx, reportDir, config) {
-  const path = join19(reportDir, "jscpd-report.json");
-  if (!existsSync14(path)) return void 0;
-  let parsed;
+function runPass(jscpd, config, paths, scope, cwd) {
+  const { args, rawReportDir, dispose } = duplicationRun(config, paths, scope);
   try {
-    parsed = JSON.parse(readFileSync14(path, "utf8"));
+    const result = spawnSync5(jscpd, args, { cwd, encoding: "utf8" });
+    if (result.error) {
+      process.stderr.write(
+        `sentinel static-analysis(jscpd): could not run the ${scope} pass (${result.error.message})
+`
+      );
+      return { kind: "failed", code: 1 };
+    }
+    if (result.status !== 0) {
+      if (analysedNothing(result.stderr)) return { kind: "empty" };
+      process.stderr.write(
+        `sentinel static-analysis(jscpd): the ${scope} pass exited ${result.status}
+${result.stderr ?? ""}`
+      );
+      return { kind: "failed", code: result.status ?? 1 };
+    }
+    const path = join19(rawReportDir, "jscpd-report.json");
+    const parsed = existsSync14(path) ? safeParse(readFileSync14(path, "utf8")) : void 0;
+    const total = parsed?.statistics?.total;
+    if (!total) {
+      process.stderr.write(
+        `sentinel static-analysis(jscpd): the ${scope} pass wrote no readable report
+`
+      );
+      return { kind: "failed", code: 1 };
+    }
+    return { kind: "figures", total, formats: parsed?.statistics?.formats ?? {} };
+  } finally {
+    dispose();
+  }
+}
+function safeParse(text) {
+  try {
+    return JSON.parse(text);
   } catch {
     return void 0;
   }
-  const total = parsed.statistics?.total;
-  if (!total) return void 0;
-  const percent = Number((total.percentage ?? 0).toFixed(2));
+}
+function assemble(ctx, config, product, tests) {
+  const share = (total) => Number((total.percentage ?? 0).toFixed(2));
   const rows = [
-    { metric: "duplicatedLinesPercent", value: percent, unit: "%" },
-    { metric: "clones", value: total.clones ?? 0, unit: "entries" }
+    { metric: "duplicatedLinesPercent", value: share(product.total), unit: "%" },
+    { metric: "clones", value: product.total.clones ?? 0, unit: "entries" }
   ];
-  const formats = parsed.statistics?.formats ?? {};
+  if (tests.kind === "figures") {
+    rows.push(
+      { metric: "duplicatedLinesPercentTests", value: share(tests.total), unit: "%" },
+      { metric: "clonesTests", value: tests.total.clones ?? 0, unit: "entries" }
+    );
+  }
   const byLanguage = Object.fromEntries(
-    Object.entries(formats).map(([language, stats]) => [
+    Object.entries(product.formats).map(([language, stats]) => [
       language,
       {
         files: stats.sources ?? 0,
@@ -5206,7 +5261,7 @@ function buildReport(ctx, reportDir, config) {
   );
   return {
     module: ctx.module,
-    passes: ["duplication"],
+    passes: tests.kind === "figures" ? ["duplication", "duplication (tests)"] : ["duplication"],
     rows,
     settings: duplicationSettings(config),
     byLanguage

package/dist/{chunk-DVKTH3RY.js → chunk-EDFIVLUA.js}

@@ -12,7 +12,6 @@ var shared_default = {
     "**/build/**",
     "**/coverage/**",
     "**/.next/**",
-    "**/static-analysis-report/**",
     "**/__mocks__/**",
     "**/mocks/**",
     "**/_mock_/**",
@@ -33,7 +32,11 @@ var shared_default = {
   duplication: {
     minTokens: 50,
     minLines: 5,
-    kinds: ["exact"]
+    kinds: ["exact"],
+    tests: [
+      "*.{test,spec,steps,e2e-spec,integration-spec}.{ts,tsx,js,jsx}",
+      "{tests,__tests__}/**/*.{ts,tsx,js,jsx}"
+    ]
   },
   deadCode: {
     minConfidence: 60,
@@ -94,4 +97,4 @@ export {
   REPORT_DIR,
   defineStaticAnalysis
 };
-//# sourceMappingURL=chunk-DVKTH3RY.js.map
+//# sourceMappingURL=chunk-EDFIVLUA.js.map

package/dist/chunk-EDFIVLUA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared/deep-merge.ts","../src/roles/static-analysis/presets/shared.json","../src/roles/static-analysis/preset-data.ts","../src/roles/static-analysis/configs/define.ts"],"sourcesContent":["/**\n * Is this a plain JSON object?\n *\n * The file is named for a `deepMerge` that no longer exists. It was written when the engine\n * merged JSON in memory and wrote the result; that approach was replaced by editing the\n * document IN PLACE with jsonc-parser, so a project's comments, key order and formatting\n * survive a `merge-json` op. Nothing has called `deepMerge` since, except its own recursion,\n * so it went.\n *\n * What remains is the predicate the in-place merge still needs, to decide whether a value is\n * a branch to walk into or a leaf to set.\n */\n\n/** True for a mergeable plain object (not null, not an array). */\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n","{\n  \"entry\": [\"**/*.integration-spec.ts\", \"**/*.steps.ts\"],\n  \"ignore\": [\n    \"**/node_modules/**\",\n    \"**/dist/**\",\n    \"**/build/**\",\n    \"**/coverage/**\",\n    \"**/.next/**\",\n    \"**/__mocks__/**\",\n    \"**/mocks/**\",\n    \"**/_mock_/**\",\n    \"**/**Mock**/**\",\n    \"**/__fixtures__/**\",\n    \"**/fixtures/**\",\n    \"**/public/**\",\n    \"**/.husky/**\",\n    \"**/.vscode/**\",\n    \"**/.idea/**\",\n    \"**/.github/**\",\n    \"**/*.d.ts\",\n    \"**/*.gen.ts\",\n    \"**/*.generated.ts\"\n  ],\n  \"languages\": [\"javascript\", \"typescript\", \"jsx\", \"tsx\", \"css\", \"scss\"],\n  \"journeys\": {},\n  \"duplication\": {\n    \"minTokens\": 50,\n    \"minLines\": 5,\n    \"kinds\": [\"exact\"],\n    \"tests\": [\n      \"*.{test,spec,steps,e2e-spec,integration-spec}.{ts,tsx,js,jsx}\",\n      \"{tests,__tests__}/**/*.{ts,tsx,js,jsx}\"\n    ]\n  },\n  \"deadCode\": {\n    \"minConfidence\": 60,\n    \"categories\": [\"unused-file\", \"unused-export\", \"unused-symbol\", \"unused-import\"]\n  },\n  \"tools\": {\n    \"jscpd\": {}\n  }\n}\n","/**\n * The static analysis preset: the role's settings, as data.\n *\n * One shared layer and no per-stack preset yet, because nothing measured so far varies by stack:\n * duplication, dead code and complexity are the same questions in Nest and in React. The split\n * that is already foreseen is `LCOM4`, which is meaningless on a functional front end and real on\n * nest's 16 568 classes; when it arrives it becomes `nest.json` beside this layer, which is why\n * the values live here as JSON rather than inline in the code.\n *\n * ## Why these values are the role's and not the module's\n *\n * A team declares FACTS about its own domain (which journeys exist, which files are entry points);\n * it does not declare the values a number is judged by. Two files with the same measurement\n * getting different verdicts in two modules would make every figure incomparable, and the first\n * thing this role has to be able to say is that a number means the same thing everywhere.\n *\n * That is a default, not a wall: a module CAN move any of them (see `configs/define.ts`), and when\n * it does the report prints `(module)` next to the value. The seam exists from the first commit\n * because retrofitting one later means rewriting every module's file.\n *\n * ⛔ There are no thresholds here, and their absence is a decision rather than an omission.\n *\n * A threshold was written first, at 5% of duplicated lines, and then removed. Measured over all 228\n * nx projects: 5% flags 65 of the 201 measurable modules, a third of the repository, and moving the\n * figure until the count felt manageable is not calibration, it is fitting the instrument to the\n * answer. Calibration is legitimate when a bench is polluted and the noise is removed, or when the\n * reference frame changes; neither applies to a share of duplicated lines.\n *\n * And there is nothing to calibrate AGAINST: of the sources in `docs/static-analysis-study.md`\n * section 5, NDepend, Lattix, ArchUnit, CodeScene and Arcan, none publishes a threshold for\n * duplicated lines. One invented here would travel as if it were published.\n *\n * So the role reports the measurement. What makes a single figure readable is the distribution it\n * sits in, which only a workspace-wide run can know, so that belongs to the sweep and to the\n * migration page, not to a module's own report. The first defensible warning will not be an absolute\n * number either: a module that got WORSE than its own previous measurement is a signal that needs no\n * invented bar, which is what a baseline gives, and that was already deferred for its own reasons.\n *\n * ## Where each value comes from, so nobody has to guess later\n *\n *  - `entry` is the single most consequential line in the file. Measured on\n *    `apps/nest/microservices/network` with jscpd 5.4.0: with nothing declared the dead-code pass\n *    reports **33.4%** of lines dead (79 657 lines, 232 files, 13 entry points); with these two\n *    patterns declared it reports **1.0%** (2 462 lines, 207 entry points). The cause is a naming\n *    convention and not a bug: our integration tests are `foo.integration-spec.ts` with a HYPHEN,\n *    so they do not end in `.spec.ts` and the tool's own test-file detection never sees them, and\n *    the 115 `.steps.ts` BDD definitions are tests by no convention it knows. A module ADDS to\n *    this list rather than replacing it, precisely so no team can lose these two by declaring a\n *    third.\n *\n *  - `languages` is this role's name for what the tool calls `format`, a word that already names\n *    another sentinel role and means something else there. Stating it has a measured cost either\n *    way: on `apps/front/console`, naming `typescript` alone scans 300 of 523 files because `.tsx`\n *    is a SEPARATE language to the tool, naming all four scans 522 (the one left out being\n *    `styles.css`), and naming nothing scans every one of its 224 languages, json and markdown\n *    included. Stylesheets are in deliberately: measured on `libs/front` they duplicate at 9.64%\n *    against 3.50% for the code, a signal that only survives because the report is broken down per\n *    language.\n *\n *  - `duplication.minTokens` and `minLines` are the detection window, and the window decides what\n *    is INVISIBLE: a fragment shorter than it is not reported at all, so a reader comparing two\n *    runs has to know both values. They are the tool's own defaults, written out rather than\n *    inherited for that reason.\n *\n *  - `duplication.kinds` is `exact` alone, and that is a correctness constraint rather than\n *    caution. Measured: with a second kind enabled, `duplicatedLines` adds up overlapping clones.\n *    Two 9-line files reported 13 duplicated lines out of 18, 72%, because an `exact` clone of\n *    lines 1-4 and a `similar` clone of lines 1-9 containing it were both counted; the real extent\n *    is 9 of 18, 50%. The tool's own answer is to cap the display at 100%, which does not make a\n *    threshold meaningful. Opening another kind therefore requires computing the share ourselves\n *    from the UNION of the line ranges.\n *\n *  - `duplication.tests` is the glob that splits the pass in two, and the split is the finding that\n *    forced it. Measured across 8 modules of the three families, **71% of all duplicated lines are\n *    between two test files**: `libs/nest/auth` reports 35.77% and its product code is at 5.96%,\n *    `apps/front/host-admin` 7.91% against 3.59%. A single blended figure is therefore mostly a\n *    measure of spec duplication wearing the name of the module's duplication, and the number\n *    travels while that nuance does not. So the role reports the two side by side, the way it\n *    already refuses to blend languages, and neither is hidden: a module whose specs carry 93% of\n *    its clones is saying something about its specs that excluding them would erase.\n *\n *    ⚠️ The two passes PARTITION the files and therefore lose a clone that spans them: a fragment\n *    shared between a test and a product file has no partner in either scan. Measured on the same\n *    8 modules, that is 42 entries of 5117, 0.8%, 650 lines. Stated in the caveat rather than\n *    silently accepted, and it is the price of the split.\n *\n *    Two patterns and not one, because a suffix convention does not cover a DIRECTORY convention,\n *    and the directory one is not a quirk: 635 files across 26 modules live under `tests/` or\n *    `__tests__/` without a name this role's suffixes recognise, `apps/nest/microservices/recruitment`\n *    alone holding 160. They are step definitions, in-memory doubles and stubs, which is test-side\n *    code by any reading. A role default rather than 26 identical overrides.\n *\n *    ⚠️ The patterns are RELATIVE here, and the adapter prefixes and composes them, because the\n *    tool's `--pattern` takes exactly one glob. Verified on four modules that the two passes\n *    partition exactly: console 479 + 87 = 566, contract 399 + 151 = 550, backends-for-frontends/admin\n *    2062 + 773 = 2835, recruitment 936 + 621 = 1557.\n *\n *    ⚠️ And a trap that cost a wrong table before it was caught: these globs contain commas, so they\n *    survive the config FILE and are destroyed by the `-i` command-line flag, which splits on\n *    commas and cuts `{test,spec}` in half. The adapter writes a file, which is one more reason it\n *    does.\n *\n *  - `deadCode.minConfidence` is the tool's own default of 60. It scores every finding and names\n *    what lowered it (a file calling `eval`, an unrecognised decorator, a name appearing in a\n *    string literal, a file in the scan that did not parse). Measured on sentinel: 60 yields 20\n *    files, 10 exports and 22 symbols; 90 yields 18 files; 100 yields nothing.\n *\n *  - `deadCode.categories` leaves out `unused-member` deliberately: without type information\n *    `x.render()` could reach any `render` in the project, which the tool itself calls its least\n *    certain rule.\n *\n *  - `ignore` excludes generated, vendored and fixture code, which duplicates by nature and buries\n *    the clones a developer can act on. It is load-bearing rather than tidy: measured on this\n *    package, scanning the module root with no ignore list reports 18 186 files and 32 153 clones,\n *    **31 969** of them touching `node_modules`; with the list, 408 files and zero.\n *\n *  - `tools.jscpd` is passed to the tool verbatim, and it is **sentinel's own** escape hatch, not a\n *    module's: `defineStaticAnalysis` excludes it from what a module can override. Everything above\n *    uses OUR key names, translated on the way out, so that replacing the tool one day does not\n *    oblige a single module to edit its config file, and a module only ever knows the ROLE. This\n *    block is where that guarantee stops, which is why it stays on this side and why it is empty:\n *    the first thing to put in it would be an option a single preset needs, not a workaround.\n */\nimport sharedData from './presets/shared.json'\n\n/**\n * Where the json and html reports are written, relative to the module.\n *\n * Named for the role rather than left on the tool's default `report/`, and added to `.gitignore`\n * by `--init`. Both halves matter: the format role once shipped a `lint/` directory that nothing\n * ignored, and every adopting module grew an untracked directory nobody could explain.\n */\nexport const REPORT_DIR = 'static-analysis-report'\n\nexport type StaticDefaults = {\n  entry: string[]\n  ignore: string[]\n  languages: string[]\n  journeys: Record<string, string[]>\n  duplication: { minTokens: number; minLines: number; kinds: string[]; tests: string[] }\n  deadCode: { minConfidence: number; categories: string[] }\n  tools: { jscpd: Record<string, unknown> }\n}\n\n/** The role's settings. Read-only here; `defineStaticAnalysis` resolves a module against them. */\nexport const defaults: StaticDefaults = sharedData as StaticDefaults\n","/**\n * `defineStaticAnalysis`: what a module imports to declare its own static analysis settings.\n *\n * ```js\n * // static-analysis.config.mjs\n * import { defineStaticAnalysis } from '@hublo/sentinel/static-analysis'\n *\n * export default defineStaticAnalysis({\n *   root: import.meta.dirname,\n *   entry: ['**\\/*.steps.ts'],\n *   journeys: { planning: ['src/planning/**'] },\n * })\n * ```\n *\n * ## Why a function and not `{ ...baseConfig, ... }`\n *\n * A spread is SHALLOW, so a module writing `deadCode: { minConfidence: 80 }` would replace the\n * whole block and silently lose `categories`. And the flattening happens in the module's file,\n * before this package ever sees the object, so nothing here could tell \"set one key, keep the\n * rest\" from \"set one key, drop the rest\". A function receives the module's INTENT, the keys it\n * actually passed, and merges them here. Second reason: the defaults are never copied into a\n * module, so changing one reaches every module at the next release instead of leaving 108 stale\n * copies behind.\n *\n * Same shape as `reactTestConfig` in the test role, for the same reasons.\n *\n * ## Two semantics, one obvious and one deliberate\n *\n * `entry` and `journeys` are FACTS a team declares, and they ADD to what this role ships: no\n * module can lose `**\\/*.integration-spec.ts` by declaring a third pattern, which matters\n * because that one pattern is the difference between 33.4% and 1.0% of dead code on a real\n * service (see `defaults.ts`).\n *\n * `overrides` REPLACES, including those lists. It is the seam for the day a team has a real\n * reason, it is not documented anywhere a developer would meet it, and every path it sets is\n * recorded in `moved` so the report can print `(module)` next to the value. Without that trace\n * two modules stop being comparable and nobody knows. It reaches every setting EXCEPT the vendor\n * passthrough, for the reason stated on the field itself.\n */\nimport { isPlainObject } from '../../../shared/deep-merge.js'\nimport { defaults, type StaticDefaults } from '../preset-data.js'\n\ntype DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] }\n\n/** What a module's config file passes. Everything is optional, including the file itself. */\nexport interface StaticAnalysisInput {\n  /** The module's own directory, normally `import.meta.dirname`. */\n  root?: string\n  /** Files that run although nothing imports them. ADDED to the shipped patterns. */\n  entry?: string[]\n  /** Named journeys, as `{ name: [globs] }`. MERGED by name with any shipped ones. */\n  journeys?: Record<string, string[]>\n  /**\n   * The seam. Replaces whatever it names, and every path it sets lands in `moved`.\n   *\n   * ⛔ `tools` is excluded, and the reason is the whole point of translating the vocabulary: a\n   * module knows the ROLE, not the tool underneath it. A key named after the vendor would mean\n   * nothing to the person reading their own config file, and showing it would invite them to learn\n   * a name we are working to keep out of their world. The passthrough still exists, on sentinel's\n   * side, for a preset that needs a vendor option; a module that genuinely needs one gets a key in\n   * OUR vocabulary, which is the right friction because it goes through a review instead of\n   * spreading silently.\n   */\n  overrides?: DeepPartial<Omit<StaticDefaults, 'tools'>>\n}\n\nexport interface ResolvedStaticConfig extends StaticDefaults {\n  /** The module's directory, or null when its config file did not say. */\n  root: string | null\n  /**\n   * Dotted paths the module set through `overrides`, so the report can mark them. Sorted, so\n   * two runs on the same config produce the same report.\n   */\n  moved: string[]\n}\n\n/**\n * Merge `patch` into `base`, recursively, patch winning.\n *\n * Not the `deepMerge` this repo once had: that one existed for WRITING a module's json and was\n * replaced by an in-place jsonc edit, which is why only `isPlainObject` survived. This is the\n * read side, which has no file to preserve and only has to resolve two objects into one.\n *\n * Arrays are replaced, never concatenated. Additive behaviour is a decision about a specific\n * key, which `defineStaticAnalysis` makes explicitly for `entry`, rather than a property of the\n * merge: a merge that silently concatenates cannot express \"replace this list\", and a team\n * reaching for `overrides` is asking for exactly that.\n */\nfunction mergeInto<T>(base: T, patch: unknown): T {\n  if (!isPlainObject(patch)) return base\n  if (!isPlainObject(base)) return patch as T\n  const out: Record<string, unknown> = { ...base }\n  for (const [key, value] of Object.entries(patch)) {\n    out[key] = isPlainObject(value) ? mergeInto(out[key], value) : value\n  }\n  return out as T\n}\n\n/** Every leaf path in `patch`, dotted, so a reader can be told what the module decided. */\nfunction leafPaths(patch: unknown, prefix = ''): string[] {\n  if (!isPlainObject(patch)) return prefix ? [prefix] : []\n  return Object.entries(patch).flatMap(([key, value]) =>\n    leafPaths(value, prefix ? `${prefix}.${key}` : key),\n  )\n}\n\n/** The same list with duplicates dropped, keeping the first occurrence's order. */\nfunction unique(values: string[]): string[] {\n  return [...new Set(values)]\n}\n\n/**\n * Drop the vendor passthrough from what a module sent.\n *\n * ⚠️ Enforced here and not by the type, because the type cannot: a module's config file is `.mjs`,\n * so nothing type-checks it, and `Omit` on the input would be documentation that compiles away. A\n * `tools` key written there is dropped and NAMED on stderr rather than ignored, so a developer who\n * found the key somewhere learns why it did nothing instead of concluding the role is broken.\n */\nfunction withoutVendorKeys(overrides: unknown): unknown {\n  if (!isPlainObject(overrides) || !('tools' in overrides)) return overrides\n  const { tools: _vendor, ...rest } = overrides\n  process.stderr.write(\n    'sentinel static-analysis: ignoring `overrides.tools` from this module. The tool underneath ' +\n      \"the role is not part of a module's surface; if a setting is missing, it needs a key of \" +\n      'its own.\\n',\n  )\n  return rest\n}\n\n/** Resolve a module's declaration against this role's defaults. */\nexport function defineStaticAnalysis(input: StaticAnalysisInput = {}): ResolvedStaticConfig {\n  const declared: StaticDefaults = {\n    ...defaults,\n    entry: unique([...defaults.entry, ...(input.entry ?? [])]),\n    journeys: { ...defaults.journeys, ...(input.journeys ?? {}) },\n  }\n  const overrides = withoutVendorKeys(input.overrides)\n\n  return {\n    ...mergeInto(declared, overrides),\n    root: input.root ?? null,\n    moved: leafPaths(overrides).sort(),\n  }\n}\n"],"mappings":";AAcO,SAAS,cAAc,OAAkD;AAC9E,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;;;AChBA;AAAA,EACE,OAAS,CAAC,4BAA4B,eAAe;AAAA,EACrD,QAAU;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,WAAa,CAAC,cAAc,cAAc,OAAO,OAAO,OAAO,MAAM;AAAA,EACrE,UAAY,CAAC;AAAA,EACb,aAAe;AAAA,IACb,WAAa;AAAA,IACb,UAAY;AAAA,IACZ,OAAS,CAAC,OAAO;AAAA,IACjB,OAAS;AAAA,MACP;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAAA,EACA,UAAY;AAAA,IACV,eAAiB;AAAA,IACjB,YAAc,CAAC,eAAe,iBAAiB,iBAAiB,eAAe;AAAA,EACjF;AAAA,EACA,OAAS;AAAA,IACP,OAAS,CAAC;AAAA,EACZ;AACF;;;AC2FO,IAAM,aAAa;AAanB,IAAM,WAA2B;;;ACzDxC,SAAS,UAAa,MAAS,OAAmB;AAChD,MAAI,CAAC,cAAc,KAAK,EAAG,QAAO;AAClC,MAAI,CAAC,cAAc,IAAI,EAAG,QAAO;AACjC,QAAM,MAA+B,EAAE,GAAG,KAAK;AAC/C,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,GAAG,IAAI,cAAc,KAAK,IAAI,UAAU,IAAI,GAAG,GAAG,KAAK,IAAI;AAAA,EACjE;AACA,SAAO;AACT;AAGA,SAAS,UAAU,OAAgB,SAAS,IAAc;AACxD,MAAI,CAAC,cAAc,KAAK,EAAG,QAAO,SAAS,CAAC,MAAM,IAAI,CAAC;AACvD,SAAO,OAAO,QAAQ,KAAK,EAAE;AAAA,IAAQ,CAAC,CAAC,KAAK,KAAK,MAC/C,UAAU,OAAO,SAAS,GAAG,MAAM,IAAI,GAAG,KAAK,GAAG;AAAA,EACpD;AACF;AAGA,SAAS,OAAO,QAA4B;AAC1C,SAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;AAC5B;AAUA,SAAS,kBAAkB,WAA6B;AACtD,MAAI,CAAC,cAAc,SAAS,KAAK,EAAE,WAAW,WAAY,QAAO;AACjE,QAAM,EAAE,OAAO,SAAS,GAAG,KAAK,IAAI;AACpC,UAAQ,OAAO;AAAA,IACb;AAAA,EAGF;AACA,SAAO;AACT;AAGO,SAAS,qBAAqB,QAA6B,CAAC,GAAyB;AAC1F,QAAM,WAA2B;AAAA,IAC/B,GAAG;AAAA,IACH,OAAO,OAAO,CAAC,GAAG,SAAS,OAAO,GAAI,MAAM,SAAS,CAAC,CAAE,CAAC;AAAA,IACzD,UAAU,EAAE,GAAG,SAAS,UAAU,GAAI,MAAM,YAAY,CAAC,EAAG;AAAA,EAC9D;AACA,QAAM,YAAY,kBAAkB,MAAM,SAAS;AAEnD,SAAO;AAAA,IACL,GAAG,UAAU,UAAU,SAAS;AAAA,IAChC,MAAM,MAAM,QAAQ;AAAA,IACpB,OAAO,UAAU,SAAS,EAAE,KAAK;AAAA,EACnC;AACF;","names":[]}

package/dist/index.js

@@ -6,12 +6,12 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-JJKFLYHK.js";
+} from "./chunk-DKLQYGPI.js";
 import {
   BaseAdapter
 } from "./chunk-KLEXJFJ6.js";
 import "./chunk-YQRDKWSH.js";
-import "./chunk-DVKTH3RY.js";
+import "./chunk-EDFIVLUA.js";
 import "./chunk-O7REVMOC.js";
 import "./chunk-QXFCZON7.js";
 export {

package/dist/roles/static-analysis/config.d.ts

@@ -7,6 +7,7 @@ type StaticDefaults = {
         minTokens: number;
         minLines: number;
         kinds: string[];
+        tests: string[];
     };
     deadCode: {
         minConfidence: number;

package/dist/roles/static-analysis/config.js

@@ -1,6 +1,6 @@
 import {
   defineStaticAnalysis
-} from "../../chunk-DVKTH3RY.js";
+} from "../../chunk-EDFIVLUA.js";
 export {
   defineStaticAnalysis
 };

package/package.json

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

package/dist/chunk-DVKTH3RY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/shared/deep-merge.ts","../src/roles/static-analysis/presets/shared.json","../src/roles/static-analysis/preset-data.ts","../src/roles/static-analysis/configs/define.ts"],"sourcesContent":["/**\n * Is this a plain JSON object?\n *\n * The file is named for a `deepMerge` that no longer exists. It was written when the engine\n * merged JSON in memory and wrote the result; that approach was replaced by editing the\n * document IN PLACE with jsonc-parser, so a project's comments, key order and formatting\n * survive a `merge-json` op. Nothing has called `deepMerge` since, except its own recursion,\n * so it went.\n *\n * What remains is the predicate the in-place merge still needs, to decide whether a value is\n * a branch to walk into or a leaf to set.\n */\n\n/** True for a mergeable plain object (not null, not an array). */\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n","{\n  \"entry\": [\"**/*.integration-spec.ts\", \"**/*.steps.ts\"],\n  \"ignore\": [\n    \"**/node_modules/**\",\n    \"**/dist/**\",\n    \"**/build/**\",\n    \"**/coverage/**\",\n    \"**/.next/**\",\n    \"**/static-analysis-report/**\",\n    \"**/__mocks__/**\",\n    \"**/mocks/**\",\n    \"**/_mock_/**\",\n    \"**/**Mock**/**\",\n    \"**/__fixtures__/**\",\n    \"**/fixtures/**\",\n    \"**/public/**\",\n    \"**/.husky/**\",\n    \"**/.vscode/**\",\n    \"**/.idea/**\",\n    \"**/.github/**\",\n    \"**/*.d.ts\",\n    \"**/*.gen.ts\",\n    \"**/*.generated.ts\"\n  ],\n  \"languages\": [\"javascript\", \"typescript\", \"jsx\", \"tsx\", \"css\", \"scss\"],\n  \"journeys\": {},\n  \"duplication\": {\n    \"minTokens\": 50,\n    \"minLines\": 5,\n    \"kinds\": [\"exact\"]\n  },\n  \"deadCode\": {\n    \"minConfidence\": 60,\n    \"categories\": [\"unused-file\", \"unused-export\", \"unused-symbol\", \"unused-import\"]\n  },\n  \"tools\": {\n    \"jscpd\": {}\n  }\n}\n","/**\n * The static analysis preset: the role's settings, as data.\n *\n * One shared layer and no per-stack preset yet, because nothing measured so far varies by stack:\n * duplication, dead code and complexity are the same questions in Nest and in React. The split\n * that is already foreseen is `LCOM4`, which is meaningless on a functional front end and real on\n * nest's 16 568 classes; when it arrives it becomes `nest.json` beside this layer, which is why\n * the values live here as JSON rather than inline in the code.\n *\n * ## Why these values are the role's and not the module's\n *\n * A team declares FACTS about its own domain (which journeys exist, which files are entry points);\n * it does not declare the values a number is judged by. Two files with the same measurement\n * getting different verdicts in two modules would make every figure incomparable, and the first\n * thing this role has to be able to say is that a number means the same thing everywhere.\n *\n * That is a default, not a wall: a module CAN move any of them (see `configs/define.ts`), and when\n * it does the report prints `(module)` next to the value. The seam exists from the first commit\n * because retrofitting one later means rewriting every module's file.\n *\n * ⛔ There are no thresholds here, and their absence is a decision rather than an omission.\n *\n * A threshold was written first, at 5% of duplicated lines, and then removed. Measured over all 228\n * nx projects: 5% flags 65 of the 201 measurable modules, a third of the repository, and moving the\n * figure until the count felt manageable is not calibration, it is fitting the instrument to the\n * answer. Calibration is legitimate when a bench is polluted and the noise is removed, or when the\n * reference frame changes; neither applies to a share of duplicated lines.\n *\n * And there is nothing to calibrate AGAINST: of the sources in `docs/static-analysis-study.md`\n * section 5, NDepend, Lattix, ArchUnit, CodeScene and Arcan, none publishes a threshold for\n * duplicated lines. One invented here would travel as if it were published.\n *\n * So the role reports the measurement. What makes a single figure readable is the distribution it\n * sits in, which only a workspace-wide run can know, so that belongs to the sweep and to the\n * migration page, not to a module's own report. The first defensible warning will not be an absolute\n * number either: a module that got WORSE than its own previous measurement is a signal that needs no\n * invented bar, which is what a baseline gives, and that was already deferred for its own reasons.\n *\n * ## Where each value comes from, so nobody has to guess later\n *\n *  - `entry` is the single most consequential line in the file. Measured on\n *    `apps/nest/microservices/network` with jscpd 5.4.0: with nothing declared the dead-code pass\n *    reports **33.4%** of lines dead (79 657 lines, 232 files, 13 entry points); with these two\n *    patterns declared it reports **1.0%** (2 462 lines, 207 entry points). The cause is a naming\n *    convention and not a bug: our integration tests are `foo.integration-spec.ts` with a HYPHEN,\n *    so they do not end in `.spec.ts` and the tool's own test-file detection never sees them, and\n *    the 115 `.steps.ts` BDD definitions are tests by no convention it knows. A module ADDS to\n *    this list rather than replacing it, precisely so no team can lose these two by declaring a\n *    third.\n *\n *  - `languages` is this role's name for what the tool calls `format`, a word that already names\n *    another sentinel role and means something else there. Stating it has a measured cost either\n *    way: on `apps/front/console`, naming `typescript` alone scans 300 of 523 files because `.tsx`\n *    is a SEPARATE language to the tool, naming all four scans 522 (the one left out being\n *    `styles.css`), and naming nothing scans every one of its 224 languages, json and markdown\n *    included. Stylesheets are in deliberately: measured on `libs/front` they duplicate at 9.64%\n *    against 3.50% for the code, a signal that only survives because the report is broken down per\n *    language.\n *\n *  - `duplication.minTokens` and `minLines` are the detection window, and the window decides what\n *    is INVISIBLE: a fragment shorter than it is not reported at all, so a reader comparing two\n *    runs has to know both values. They are the tool's own defaults, written out rather than\n *    inherited for that reason.\n *\n *  - `duplication.kinds` is `exact` alone, and that is a correctness constraint rather than\n *    caution. Measured: with a second kind enabled, `duplicatedLines` adds up overlapping clones.\n *    Two 9-line files reported 13 duplicated lines out of 18, 72%, because an `exact` clone of\n *    lines 1-4 and a `similar` clone of lines 1-9 containing it were both counted; the real extent\n *    is 9 of 18, 50%. The tool's own answer is to cap the display at 100%, which does not make a\n *    threshold meaningful. Opening another kind therefore requires computing the share ourselves\n *    from the UNION of the line ranges.\n *\n *  - `deadCode.minConfidence` is the tool's own default of 60. It scores every finding and names\n *    what lowered it (a file calling `eval`, an unrecognised decorator, a name appearing in a\n *    string literal, a file in the scan that did not parse). Measured on sentinel: 60 yields 20\n *    files, 10 exports and 22 symbols; 90 yields 18 files; 100 yields nothing.\n *\n *  - `deadCode.categories` leaves out `unused-member` deliberately: without type information\n *    `x.render()` could reach any `render` in the project, which the tool itself calls its least\n *    certain rule.\n *\n *  - `ignore` excludes generated, vendored and fixture code, which duplicates by nature and buries\n *    the clones a developer can act on. It is load-bearing rather than tidy: measured on this\n *    package, scanning the module root with no ignore list reports 18 186 files and 32 153 clones,\n *    **31 969** of them touching `node_modules`; with the list, 408 files and zero.\n *\n *  - `tools.jscpd` is passed to the tool verbatim, and it is **sentinel's own** escape hatch, not a\n *    module's: `defineStaticAnalysis` excludes it from what a module can override. Everything above\n *    uses OUR key names, translated on the way out, so that replacing the tool one day does not\n *    oblige a single module to edit its config file, and a module only ever knows the ROLE. This\n *    block is where that guarantee stops, which is why it stays on this side and why it is empty:\n *    the first thing to put in it would be an option a single preset needs, not a workaround.\n */\nimport sharedData from './presets/shared.json'\n\n/**\n * Where the json and html reports are written, relative to the module.\n *\n * Named for the role rather than left on the tool's default `report/`, and added to `.gitignore`\n * by `--init`. Both halves matter: the format role once shipped a `lint/` directory that nothing\n * ignored, and every adopting module grew an untracked directory nobody could explain.\n */\nexport const REPORT_DIR = 'static-analysis-report'\n\nexport type StaticDefaults = {\n  entry: string[]\n  ignore: string[]\n  languages: string[]\n  journeys: Record<string, string[]>\n  duplication: { minTokens: number; minLines: number; kinds: string[] }\n  deadCode: { minConfidence: number; categories: string[] }\n  tools: { jscpd: Record<string, unknown> }\n}\n\n/** The role's settings. Read-only here; `defineStaticAnalysis` resolves a module against them. */\nexport const defaults: StaticDefaults = sharedData as StaticDefaults\n","/**\n * `defineStaticAnalysis`: what a module imports to declare its own static analysis settings.\n *\n * ```js\n * // static-analysis.config.mjs\n * import { defineStaticAnalysis } from '@hublo/sentinel/static-analysis'\n *\n * export default defineStaticAnalysis({\n *   root: import.meta.dirname,\n *   entry: ['**\\/*.steps.ts'],\n *   journeys: { planning: ['src/planning/**'] },\n * })\n * ```\n *\n * ## Why a function and not `{ ...baseConfig, ... }`\n *\n * A spread is SHALLOW, so a module writing `deadCode: { minConfidence: 80 }` would replace the\n * whole block and silently lose `categories`. And the flattening happens in the module's file,\n * before this package ever sees the object, so nothing here could tell \"set one key, keep the\n * rest\" from \"set one key, drop the rest\". A function receives the module's INTENT, the keys it\n * actually passed, and merges them here. Second reason: the defaults are never copied into a\n * module, so changing one reaches every module at the next release instead of leaving 108 stale\n * copies behind.\n *\n * Same shape as `reactTestConfig` in the test role, for the same reasons.\n *\n * ## Two semantics, one obvious and one deliberate\n *\n * `entry` and `journeys` are FACTS a team declares, and they ADD to what this role ships: no\n * module can lose `**\\/*.integration-spec.ts` by declaring a third pattern, which matters\n * because that one pattern is the difference between 33.4% and 1.0% of dead code on a real\n * service (see `defaults.ts`).\n *\n * `overrides` REPLACES, including those lists. It is the seam for the day a team has a real\n * reason, it is not documented anywhere a developer would meet it, and every path it sets is\n * recorded in `moved` so the report can print `(module)` next to the value. Without that trace\n * two modules stop being comparable and nobody knows. It reaches every setting EXCEPT the vendor\n * passthrough, for the reason stated on the field itself.\n */\nimport { isPlainObject } from '../../../shared/deep-merge.js'\nimport { defaults, type StaticDefaults } from '../preset-data.js'\n\ntype DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] }\n\n/** What a module's config file passes. Everything is optional, including the file itself. */\nexport interface StaticAnalysisInput {\n  /** The module's own directory, normally `import.meta.dirname`. */\n  root?: string\n  /** Files that run although nothing imports them. ADDED to the shipped patterns. */\n  entry?: string[]\n  /** Named journeys, as `{ name: [globs] }`. MERGED by name with any shipped ones. */\n  journeys?: Record<string, string[]>\n  /**\n   * The seam. Replaces whatever it names, and every path it sets lands in `moved`.\n   *\n   * ⛔ `tools` is excluded, and the reason is the whole point of translating the vocabulary: a\n   * module knows the ROLE, not the tool underneath it. A key named after the vendor would mean\n   * nothing to the person reading their own config file, and showing it would invite them to learn\n   * a name we are working to keep out of their world. The passthrough still exists, on sentinel's\n   * side, for a preset that needs a vendor option; a module that genuinely needs one gets a key in\n   * OUR vocabulary, which is the right friction because it goes through a review instead of\n   * spreading silently.\n   */\n  overrides?: DeepPartial<Omit<StaticDefaults, 'tools'>>\n}\n\nexport interface ResolvedStaticConfig extends StaticDefaults {\n  /** The module's directory, or null when its config file did not say. */\n  root: string | null\n  /**\n   * Dotted paths the module set through `overrides`, so the report can mark them. Sorted, so\n   * two runs on the same config produce the same report.\n   */\n  moved: string[]\n}\n\n/**\n * Merge `patch` into `base`, recursively, patch winning.\n *\n * Not the `deepMerge` this repo once had: that one existed for WRITING a module's json and was\n * replaced by an in-place jsonc edit, which is why only `isPlainObject` survived. This is the\n * read side, which has no file to preserve and only has to resolve two objects into one.\n *\n * Arrays are replaced, never concatenated. Additive behaviour is a decision about a specific\n * key, which `defineStaticAnalysis` makes explicitly for `entry`, rather than a property of the\n * merge: a merge that silently concatenates cannot express \"replace this list\", and a team\n * reaching for `overrides` is asking for exactly that.\n */\nfunction mergeInto<T>(base: T, patch: unknown): T {\n  if (!isPlainObject(patch)) return base\n  if (!isPlainObject(base)) return patch as T\n  const out: Record<string, unknown> = { ...base }\n  for (const [key, value] of Object.entries(patch)) {\n    out[key] = isPlainObject(value) ? mergeInto(out[key], value) : value\n  }\n  return out as T\n}\n\n/** Every leaf path in `patch`, dotted, so a reader can be told what the module decided. */\nfunction leafPaths(patch: unknown, prefix = ''): string[] {\n  if (!isPlainObject(patch)) return prefix ? [prefix] : []\n  return Object.entries(patch).flatMap(([key, value]) =>\n    leafPaths(value, prefix ? `${prefix}.${key}` : key),\n  )\n}\n\n/** The same list with duplicates dropped, keeping the first occurrence's order. */\nfunction unique(values: string[]): string[] {\n  return [...new Set(values)]\n}\n\n/**\n * Drop the vendor passthrough from what a module sent.\n *\n * ⚠️ Enforced here and not by the type, because the type cannot: a module's config file is `.mjs`,\n * so nothing type-checks it, and `Omit` on the input would be documentation that compiles away. A\n * `tools` key written there is dropped and NAMED on stderr rather than ignored, so a developer who\n * found the key somewhere learns why it did nothing instead of concluding the role is broken.\n */\nfunction withoutVendorKeys(overrides: unknown): unknown {\n  if (!isPlainObject(overrides) || !('tools' in overrides)) return overrides\n  const { tools: _vendor, ...rest } = overrides\n  process.stderr.write(\n    'sentinel static-analysis: ignoring `overrides.tools` from this module. The tool underneath ' +\n      \"the role is not part of a module's surface; if a setting is missing, it needs a key of \" +\n      'its own.\\n',\n  )\n  return rest\n}\n\n/** Resolve a module's declaration against this role's defaults. */\nexport function defineStaticAnalysis(input: StaticAnalysisInput = {}): ResolvedStaticConfig {\n  const declared: StaticDefaults = {\n    ...defaults,\n    entry: unique([...defaults.entry, ...(input.entry ?? [])]),\n    journeys: { ...defaults.journeys, ...(input.journeys ?? {}) },\n  }\n  const overrides = withoutVendorKeys(input.overrides)\n\n  return {\n    ...mergeInto(declared, overrides),\n    root: input.root ?? null,\n    moved: leafPaths(overrides).sort(),\n  }\n}\n"],"mappings":";AAcO,SAAS,cAAc,OAAkD;AAC9E,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;;;AChBA;AAAA,EACE,OAAS,CAAC,4BAA4B,eAAe;AAAA,EACrD,QAAU;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,WAAa,CAAC,cAAc,cAAc,OAAO,OAAO,OAAO,MAAM;AAAA,EACrE,UAAY,CAAC;AAAA,EACb,aAAe;AAAA,IACb,WAAa;AAAA,IACb,UAAY;AAAA,IACZ,OAAS,CAAC,OAAO;AAAA,EACnB;AAAA,EACA,UAAY;AAAA,IACV,eAAiB;AAAA,IACjB,YAAc,CAAC,eAAe,iBAAiB,iBAAiB,eAAe;AAAA,EACjF;AAAA,EACA,OAAS;AAAA,IACP,OAAS,CAAC;AAAA,EACZ;AACF;;;ACgEO,IAAM,aAAa;AAanB,IAAM,WAA2B;;;AC3BxC,SAAS,UAAa,MAAS,OAAmB;AAChD,MAAI,CAAC,cAAc,KAAK,EAAG,QAAO;AAClC,MAAI,CAAC,cAAc,IAAI,EAAG,QAAO;AACjC,QAAM,MAA+B,EAAE,GAAG,KAAK;AAC/C,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,QAAI,GAAG,IAAI,cAAc,KAAK,IAAI,UAAU,IAAI,GAAG,GAAG,KAAK,IAAI;AAAA,EACjE;AACA,SAAO;AACT;AAGA,SAAS,UAAU,OAAgB,SAAS,IAAc;AACxD,MAAI,CAAC,cAAc,KAAK,EAAG,QAAO,SAAS,CAAC,MAAM,IAAI,CAAC;AACvD,SAAO,OAAO,QAAQ,KAAK,EAAE;AAAA,IAAQ,CAAC,CAAC,KAAK,KAAK,MAC/C,UAAU,OAAO,SAAS,GAAG,MAAM,IAAI,GAAG,KAAK,GAAG;AAAA,EACpD;AACF;AAGA,SAAS,OAAO,QAA4B;AAC1C,SAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;AAC5B;AAUA,SAAS,kBAAkB,WAA6B;AACtD,MAAI,CAAC,cAAc,SAAS,KAAK,EAAE,WAAW,WAAY,QAAO;AACjE,QAAM,EAAE,OAAO,SAAS,GAAG,KAAK,IAAI;AACpC,UAAQ,OAAO;AAAA,IACb;AAAA,EAGF;AACA,SAAO;AACT;AAGO,SAAS,qBAAqB,QAA6B,CAAC,GAAyB;AAC1F,QAAM,WAA2B;AAAA,IAC/B,GAAG;AAAA,IACH,OAAO,OAAO,CAAC,GAAG,SAAS,OAAO,GAAI,MAAM,SAAS,CAAC,CAAE,CAAC;AAAA,IACzD,UAAU,EAAE,GAAG,SAAS,UAAU,GAAI,MAAM,YAAY,CAAC,EAAG;AAAA,EAC9D;AACA,QAAM,YAAY,kBAAkB,MAAM,SAAS;AAEnD,SAAO;AAAA,IACL,GAAG,UAAU,UAAU,SAAS;AAAA,IAChC,MAAM,MAAM,QAAQ;AAAA,IACpB,OAAO,UAAU,SAAS,EAAE,KAAK;AAAA,EACnC;AACF;","names":[]}