@hublo/sentinel 1.5.0-alpha.16 → 1.5.0-alpha.18

package/dist/bin/sentinel.js

@@ -15,7 +15,7 @@ import {
   palette,
   registerAdapters,
   resolve
-} from "../chunk-S3LXWTKH.js";
+} from "../chunk-OKHGGXNC.js";
 import {
   resolveContext
 } from "../chunk-KLEXJFJ6.js";
@@ -26,7 +26,7 @@ import {
   readOwnVersion,
   readProjectPackageJson
 } from "../chunk-YQRDKWSH.js";
-import "../chunk-UUPP5UQS.js";
+import "../chunk-AYEOGJQR.js";
 import "../chunk-O7REVMOC.js";
 import "../chunk-QXFCZON7.js";
 

package/dist/{chunk-UUPP5UQS.js → chunk-AYEOGJQR.js}

@@ -41,14 +41,18 @@ var shared_default = {
     minLines: 5,
     kinds: ["exact"],
     tests: [
-      "*.{test,spec,steps,e2e-spec,integration-spec}.{ts,tsx,js,jsx}",
-      "{tests,__tests__}/**/*.{ts,tsx,js,jsx}"
+      "*.{test,spec,steps,e2e-spec,integration-spec,stories}.{ts,tsx,js,jsx}",
+      "*.{msw,mock,test-data}.{ts,tsx,js,jsx}",
+      "{tests,__tests__,test,testing,stubs}/**/*.{ts,tsx,js,jsx}"
     ]
   },
   deadCode: {
     minConfidence: 60,
     categories: ["unused-file", "unused-export", "unused-symbol", "unused-import"]
   },
+  graph: {
+    resolution: 1
+  },
   tools: {
     jscpd: {}
   }
@@ -162,4 +166,4 @@ export {
   overridableSettings,
   defineStaticAnalysis
 };
-//# sourceMappingURL=chunk-UUPP5UQS.js.map
+//# sourceMappingURL=chunk-AYEOGJQR.js.map

package/dist/chunk-AYEOGJQR.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\": [\n    \"**/*.integration-spec.ts\",\n    \"**/*.steps.ts\",\n    \"src/client.tsx\",\n    \"src/start.ts\",\n    \"src/router.tsx\",\n    \"src/RouterContext.tsx\"\n  ],\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,stories}.{ts,tsx,js,jsx}\",\n      \"*.{msw,mock,test-data}.{ts,tsx,js,jsx}\",\n      \"{tests,__tests__,test,testing,stubs}/**/*.{ts,tsx,js,jsx}\"\n    ]\n  },\n  \"deadCode\": {\n    \"minConfidence\": 60,\n    \"categories\": [\"unused-file\", \"unused-export\", \"unused-symbol\", \"unused-import\"]\n  },\n  \"graph\": {\n    \"resolution\": 1\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 *    ⭐ The four `src/` files are the FRONT bootstrap, and they are the most consequential thing\n *    measured on this pass. The tool recognises around fifty frameworks and TanStack Start is not\n *    one of them, so nothing in the repository imports these files: the framework finds them by\n *    convention at build time. Measured without them declared, `apps/front/console` reports\n *    `src/client.tsx`, `src/router.tsx` and `src/start.ts` among its 5 dead files, which are its\n *    hydration entry, its router factory and its Start config. `host-admin` reports `client.tsx`\n *    too and `career` reports `router.tsx` and `RouterContext.tsx`. Three of console's five\n *    findings were its own bootstrap, and the first team to see that stops trusting the tool on\n *    the spot. They exist in 2 to 3 front apps each.\n *\n *    ⛔ `scripts/**` is deliberately NOT here, although 8 modules have one and\n *    `apps/nest/microservices/contract` reports two `scripts/e2e-*.ts` as dead. No `package.json`\n *    script invokes them, so whether they run at all is a fact only the team holds. Declaring them\n *    would hide a finding that may well be true, and that is the opposite of this role's job.\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 *  - `graph.resolution` is Louvain's, and it is 1 because that is the value the papers use and\n *    graphology's own default. It decides how large a community must be to survive, so it changes\n *    both the community count and `Q`, and graphology's documentation warns in its own words that\n *    it is finicky to tweak. `code-health-meter` ships 0.74, arrived at by trying values until the\n *    partition looked right; this role declines to do that, for the same reason it ships no\n *    duplication threshold. A module that has a reason can move it, and the report prints the\n *    value every figure was produced with.\n *\n *    ⚠️ What is NOT tunable is the random seed, and that is deliberate. Louvain is greedy, so its\n *    answer depends on the order it visits nodes, which graphology draws from `Math.random`.\n *    Measured over 20 runs per module: `console` produced 16 distinct values of `Q` and between 12\n *    and 14 communities, `recruitment` 19 distinct values spanning 0.0357. With the role's own\n *    generator all five modules produce one value. A figure that moves on its own between two runs\n *    is not a figure a team can act on, so this one is the role's and nobody's to change.\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\n/** The target this role serves, which is also the npm script a module runs and the nx target. */\nexport const TARGET = 'static-analysis'\n\n/** The output shapes `--run` can produce. `console` writes nothing to disk. */\nexport const SHAPES = ['console', 'json', 'html'] as const\n\n/**\n * The npm scripts a module gets, one per shape.\n *\n * Here rather than in the adapter because the REPORT needs them too, to tell a reader of the\n * console summary where the detail is, and two spellings of one script name is drift nobody\n * notices until a developer types the one that does not exist.\n */\nexport const SCRIPTS = {\n  console: TARGET,\n  json: `${TARGET}:json`,\n  html: `${TARGET}:html`,\n} as const\n\n/**\n * What each language the role scans is called on disk.\n *\n * ⚠️ Two lists that MUST agree, and they were maintained separately: the role declares the\n * languages it asks the tool to scan, and the adapter declared the extensions it looks for when\n * deciding whether a module has anything to measure at all. A module that narrowed `languages`\n * would still be probed for the extensions it had removed, and a language added to the preset\n * would never reach the probe. Derived from one source now, with a test that every language maps.\n */\nconst EXTENSIONS_BY_LANGUAGE: Record<string, string[]> = {\n  javascript: ['.js', '.mjs', '.cjs'],\n  typescript: ['.ts'],\n  jsx: ['.jsx'],\n  tsx: ['.tsx'],\n  css: ['.css'],\n  scss: ['.scss'],\n}\n\n/** The file extensions of the languages given, for deciding whether a module has anything to read. */\nexport function extensionsOf(languages: readonly string[]): string[] {\n  return [...new Set(languages.flatMap((language) => EXTENSIONS_BY_LANGUAGE[language] ?? []))]\n}\n\n/** Every language the mapping knows, so a test can hold it against the preset. */\nexport const MAPPED_LANGUAGES = Object.keys(EXTENSIONS_BY_LANGUAGE)\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  graph: { resolution: number }\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/**\n * Keys a module declares DIRECTLY rather than through `overrides`, and how each one combines.\n *\n * They are apart because the verb differs: these two are added to and merged, so a team cannot\n * lose what the role ships by declaring its own. Everything else replaces.\n */\nconst DECLARED: Record<string, string> = {\n  entry: 'added to the patterns the role ships, never replacing them',\n  journeys: \"merged by name with the role's\",\n}\n\n/**\n * ⛔ Not a module's to set, and the catalogue says so rather than leaving it absent: a key that is\n * simply missing from a list reads as an oversight, and someone will try it. Passing it is dropped\n * with a message, see `configs/define.ts`.\n */\nconst NOT_YOURS: Record<string, string> = {\n  tools: \"sentinel's own passthrough to the tool underneath; a module never names the vendor\",\n}\n\n/** A value as a reader compares it: short lists in full, long ones as a count. */\nfunction render(value: unknown): string {\n  if (Array.isArray(value)) {\n    const joined = value.join(', ')\n    return value.length <= 6 && joined.length <= 72 ? joined : `${value.length} patterns`\n  }\n  if (value && typeof value === 'object') return `${Object.keys(value).length} entries`\n  return String(value)\n}\n\n/** One documented key: its path, the role's value, and the note a reader needs. */\nexport interface OverridableSetting {\n  /** The dotted path a module writes, e.g. `duplication.minTokens`. */\n  key: string\n  /** The role's current value, rendered. */\n  value: string\n  /** How it combines, or why it is not available. */\n  note: string\n  /** Where it goes: directly in the config, inside `overrides`, or nowhere. */\n  where: 'declared' | 'overrides' | 'refused'\n}\n\n/**\n * Every setting a module can touch, DERIVED from the values rather than written beside them.\n *\n * Héla's ask, and the reason it is generated: a hand-written list is a second copy of the preset,\n * and the first setting somebody adds makes it a lie that nobody notices, because a stale comment\n * fails no test. Here a new key appears in the next module's config file on its own, with its real\n * value, and `tests/role-layout.test.ts` refuses a key that reaches none of the three groups.\n *\n * It is a snapshot: `--init` leaves an EXISTING config alone, by design, so a module that adopted\n * earlier keeps the catalogue of that day. The report is the live answer, since it prints the value\n * every figure was produced with.\n */\nexport function overridableSettings(from: StaticDefaults = defaults): OverridableSetting[] {\n  const rows: OverridableSetting[] = []\n\n  for (const [key, value] of Object.entries(from)) {\n    if (key in NOT_YOURS) {\n      rows.push({ key, value: render(value), note: NOT_YOURS[key] ?? '', where: 'refused' })\n      continue\n    }\n    if (key in DECLARED) {\n      rows.push({ key, value: render(value), note: DECLARED[key] ?? '', where: 'declared' })\n      continue\n    }\n    // A group is documented by its leaves, because `duplication` whole is not what anyone writes.\n    const leaves =\n      value && typeof value === 'object' && !Array.isArray(value)\n        ? Object.entries(value).map(([leaf, own]) => ({ key: `${key}.${leaf}`, own }))\n        : [{ key, own: value }]\n    for (const leaf of leaves) {\n      rows.push({ key: leaf.key, value: render(leaf.own), note: 'replaced', where: 'overrides' })\n    }\n  }\n\n  return rows\n}\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;AAAA,IACP;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,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,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,YAAc;AAAA,EAChB;AAAA,EACA,OAAS;AAAA,IACP,OAAS,CAAC;AAAA,EACZ;AACF;;;AC8GO,IAAM,aAAa;AAGnB,IAAM,SAAS;AAGf,IAAM,SAAS,CAAC,WAAW,QAAQ,MAAM;AASzC,IAAM,UAAU;AAAA,EACrB,SAAS;AAAA,EACT,MAAM,GAAG,MAAM;AAAA,EACf,MAAM,GAAG,MAAM;AACjB;AAWA,IAAM,yBAAmD;AAAA,EACvD,YAAY,CAAC,OAAO,QAAQ,MAAM;AAAA,EAClC,YAAY,CAAC,KAAK;AAAA,EAClB,KAAK,CAAC,MAAM;AAAA,EACZ,KAAK,CAAC,MAAM;AAAA,EACZ,KAAK,CAAC,MAAM;AAAA,EACZ,MAAM,CAAC,OAAO;AAChB;AAGO,SAAS,aAAa,WAAwC;AACnE,SAAO,CAAC,GAAG,IAAI,IAAI,UAAU,QAAQ,CAAC,aAAa,uBAAuB,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC;AAC7F;AAGO,IAAM,mBAAmB,OAAO,KAAK,sBAAsB;AAc3D,IAAM,WAA2B;AAQxC,IAAM,WAAmC;AAAA,EACvC,OAAO;AAAA,EACP,UAAU;AACZ;AAOA,IAAM,YAAoC;AAAA,EACxC,OAAO;AACT;AAGA,SAAS,OAAO,OAAwB;AACtC,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,UAAM,SAAS,MAAM,KAAK,IAAI;AAC9B,WAAO,MAAM,UAAU,KAAK,OAAO,UAAU,KAAK,SAAS,GAAG,MAAM,MAAM;AAAA,EAC5E;AACA,MAAI,SAAS,OAAO,UAAU,SAAU,QAAO,GAAG,OAAO,KAAK,KAAK,EAAE,MAAM;AAC3E,SAAO,OAAO,KAAK;AACrB;AA0BO,SAAS,oBAAoB,OAAuB,UAAgC;AACzF,QAAM,OAA6B,CAAC;AAEpC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,IAAI,GAAG;AAC/C,QAAI,OAAO,WAAW;AACpB,WAAK,KAAK,EAAE,KAAK,OAAO,OAAO,KAAK,GAAG,MAAM,UAAU,GAAG,KAAK,IAAI,OAAO,UAAU,CAAC;AACrF;AAAA,IACF;AACA,QAAI,OAAO,UAAU;AACnB,WAAK,KAAK,EAAE,KAAK,OAAO,OAAO,KAAK,GAAG,MAAM,SAAS,GAAG,KAAK,IAAI,OAAO,WAAW,CAAC;AACrF;AAAA,IACF;AAEA,UAAM,SACJ,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,IACtD,OAAO,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,MAAM,GAAG,OAAO,EAAE,KAAK,GAAG,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,IAC3E,CAAC,EAAE,KAAK,KAAK,MAAM,CAAC;AAC1B,eAAW,QAAQ,QAAQ;AACzB,WAAK,KAAK,EAAE,KAAK,KAAK,KAAK,OAAO,OAAO,KAAK,GAAG,GAAG,MAAM,YAAY,OAAO,YAAY,CAAC;AAAA,IAC5F;AAAA,EACF;AAEA,SAAO;AACT;;;ACpNA,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/{chunk-S3LXWTKH.js → chunk-OKHGGXNC.js}

@@ -71,7 +71,7 @@ import {
   extensionsOf,
   isPlainObject,
   overridableSettings
-} from "./chunk-UUPP5UQS.js";
+} from "./chunk-AYEOGJQR.js";
 import {
   parseJsonc
 } from "./chunk-QXFCZON7.js";
@@ -4758,8 +4758,8 @@ function registerLint() {
 
 // src/roles/static-analysis/adapters/jscpd/jscpd.adapter.ts
 import { spawnSync as spawnSync5 } from "node:child_process";
-import { existsSync as existsSync14, mkdirSync, readFileSync as readFileSync15, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join19 } from "node:path";
+import { existsSync as existsSync14, mkdirSync, readFileSync as readFileSync16, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join20 } from "node:path";
 
 // src/roles/static-analysis/complexity/scan.ts
 import { readFileSync as readFileSync14 } from "node:fs";
@@ -5049,6 +5049,179 @@ function scanComplexity(cwd, config) {
   };
 }
 
+// src/roles/static-analysis/graph/picture.ts
+import forceAtlas2 from "graphology-layout-forceatlas2";
+import circular from "graphology-layout/circular.js";
+import renderSvg from "graphology-svg";
+var ITERATIONS = 300;
+var LABELLED = 10;
+var BLANK = " ";
+var SIZE = { width: 1600, height: 1200, margin: 30 };
+function hueOf(community) {
+  return `hsl(${community * 137 % 360} 65% 52%)`;
+}
+function writeGraphPicture(graph, communities, path) {
+  const drawn = graph.copy();
+  circular.assign(drawn);
+  forceAtlas2.assign(drawn, { iterations: ITERATIONS, settings: forceAtlas2.inferSettings(drawn) });
+  const named = new Set(
+    drawn.nodes().sort((left, right) => drawn.degree(right) - drawn.degree(left) || left.localeCompare(right)).slice(0, LABELLED)
+  );
+  drawn.forEachNode((node) => {
+    drawn.setNodeAttribute(node, "size", 2 + Math.sqrt(drawn.degree(node)));
+    drawn.setNodeAttribute(node, "color", hueOf(communities[node] ?? 0));
+    drawn.setNodeAttribute(node, "label", named.has(node) ? node.split("/").pop() ?? node : BLANK);
+  });
+  return new Promise((resolve4) => {
+    renderSvg(drawn, path, SIZE, () => resolve4());
+  });
+}
+
+// src/roles/static-analysis/graph/scan.ts
+import Graph from "graphology";
+import louvain from "graphology-communities-louvain";
+import { stronglyConnectedComponents } from "graphology-components";
+import { degreeCentrality } from "graphology-metrics/centrality/degree.js";
+import { density } from "graphology-metrics/graph/density.js";
+
+// src/roles/static-analysis/graph/imports.ts
+import { readFileSync as readFileSync15 } from "node:fs";
+import { dirname, join as join19 } from "node:path";
+import { parseSync as parseSync3 } from "oxc-parser";
+import { globSync as globSync2 } from "tinyglobby";
+var EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+var TS_BEHIND_JS = {
+  ".js": [".ts", ".tsx"],
+  ".mjs": [".mts"],
+  ".cjs": [".cts"]
+};
+function specifiersOf(program) {
+  const found = [];
+  const walk3 = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const child of node) walk3(child);
+      return;
+    }
+    const current = node;
+    const source = current.source?.value;
+    switch (current.type) {
+      // `import x from './a'`, and the two re-export forms, which are imports that also publish.
+      case "ImportDeclaration":
+      case "ExportNamedDeclaration":
+      case "ExportAllDeclaration":
+        if (typeof source === "string") found.push(source);
+        break;
+      // `import('./a')`, the lazy route and the split bundle.
+      case "ImportExpression":
+        if (typeof source === "string") found.push(source);
+        break;
+      case "CallExpression": {
+        const argument = current.arguments?.[0]?.value;
+        if (current.callee?.name === "require" && typeof argument === "string") found.push(argument);
+        break;
+      }
+      default:
+        break;
+    }
+    for (const [field, value] of Object.entries(current)) {
+      if (field === "type" || field === "start" || field === "end") continue;
+      walk3(value);
+    }
+  };
+  walk3(program);
+  return found;
+}
+function resolveSpecifier(from, specifier, known) {
+  if (!specifier.startsWith(".")) return void 0;
+  const base = join19(dirname(from), specifier);
+  if (known.has(base)) return base;
+  for (const extension of EXTENSIONS) {
+    if (known.has(base + extension)) return base + extension;
+  }
+  const written = EXTENSIONS.find((extension) => base.endsWith(extension));
+  for (const extension of TS_BEHIND_JS[written ?? ""] ?? []) {
+    const swapped = base.slice(0, -(written ?? "").length) + extension;
+    if (known.has(swapped)) return swapped;
+  }
+  for (const extension of EXTENSIONS) {
+    const index = join19(base, `index${extension}`);
+    if (known.has(index)) return index;
+  }
+  return void 0;
+}
+function buildImportGraph(cwd, config) {
+  const extensions = extensionsOf(config.languages).map((extension) => extension.slice(1)).join(",");
+  const files = globSync2([`**/*.{${extensions}}`], {
+    cwd,
+    ignore: exclusions(config, "product"),
+    dot: false
+  });
+  const known = new Set(files);
+  const tree = {};
+  for (const file of files) {
+    tree[file] = [];
+    let parsed;
+    try {
+      parsed = parseSync3(file, readFileSync15(join19(cwd, file), "utf8"));
+    } catch {
+      continue;
+    }
+    if (parsed.errors.length > 0) continue;
+    for (const specifier of specifiersOf(parsed.program)) {
+      const target = resolveSpecifier(file, specifier, known);
+      if (target && target !== file && !tree[file].includes(target)) tree[file].push(target);
+    }
+  }
+  return tree;
+}
+
+// src/roles/static-analysis/graph/scan.ts
+var MOST_IMPORTED_LISTED = 10;
+function seeded() {
+  let state = 42;
+  return () => {
+    state = (state * 1664525 + 1013904223) % 4294967296;
+    return state / 4294967296;
+  };
+}
+function toGraph(tree) {
+  const graph = new Graph({ type: "directed", allowSelfLoops: false });
+  for (const file of Object.keys(tree)) if (!graph.hasNode(file)) graph.addNode(file);
+  for (const [from, targets2] of Object.entries(tree)) {
+    for (const to of targets2) {
+      if (!graph.hasNode(to)) graph.addNode(to);
+      if (from !== to && !graph.hasDirectedEdge(from, to)) graph.addDirectedEdge(from, to);
+    }
+  }
+  return graph;
+}
+function scanGraph(cwd, config) {
+  const graph = toGraph(buildImportGraph(cwd, config));
+  const cycles = stronglyConnectedComponents(graph).filter((component) => component.length > 1).map((files) => ({ files })).sort((left, right) => right.files.length - left.files.length);
+  const partition = graph.size > 0 ? louvain.detailed(graph, { resolution: config.graph.resolution, rng: seeded() }) : { count: graph.order, modularity: void 0, communities: {} };
+  const centrality = degreeCentrality(graph);
+  const mostImported = graph.nodes().map((path) => ({
+    path,
+    importedBy: graph.inDegree(path),
+    centrality: centrality[path] ?? 0
+  })).filter((file) => file.importedBy > 0).sort(
+    (left, right) => right.importedBy - left.importedBy || left.path.localeCompare(right.path)
+  ).slice(0, MOST_IMPORTED_LISTED);
+  return {
+    files: graph.order,
+    edges: graph.size,
+    density: graph.order > 1 ? density(graph) : 0,
+    cycles,
+    filesInCycles: cycles.reduce((total, cycle) => total + cycle.files.length, 0),
+    communities: partition.count,
+    modularity: partition.modularity,
+    mostImported,
+    graph,
+    communityOf: partition.communities
+  };
+}
+
 // src/roles/static-analysis/help/metrics.ts
 var metricsHelp = {
   duplicatedLinesPercent: {
@@ -5148,6 +5321,48 @@ var metricsHelp = {
     read: "A count, so it grows with the size of the module. Read it next to the duplicated-line share rather than on its own, and treat it as the number of places to go and look at.",
     caveat: "Not a count of duplicated places, and the gap is measured, not theoretical: five identical files produce four entries, all of them naming one file in common, so n copies give n-1 entries, neither n nor the n(n-1)/2 pairs. Worse for reading occurrences, jscpd keeps only the longest match per pair of files, so when a third file shares just part of a block, that block is reported under two different fragments and its real number of occurrences cannot be recovered from the report. Size is invisible too: one clone of sixty lines and one of six both count as one.",
     source: "jscpd report statistics. Counting behaviour measured on fixtures with jscpd 5.4.0; the shared file is not the same one across major versions, so only the count is relied on."
+  },
+  cycles: {
+    label: "Import cycles",
+    what: "Groups of files that import each other in a circle, directly or through other files.",
+    read: "Expect zero, and read any value as a count of places to go and break one edge. The figure beside it is how many FILES are caught, which is the size of the problem: one group of forty is a different afternoon from twenty groups of two.",
+    caveat: "A cycle is reported, not judged, and some are harmless in practice: a type-only import is erased at build time and two files that merely reference each other's types will never deadlock. What the measurement cannot tell you is which kind yours is, because it does not read the `type` keyword. It also reports GROUPS and not paths, so a group of six files may contain a dozen distinct circles; breaking one of them does not necessarily break the group, which is exactly why the group is the unit.",
+    source: "Tarjan's strongly connected components, via graphology-components. Held against madge's own `circular()` on five modules of the three families: the set of files caught was identical every time (2, 110, 11, 13 and 2), and only the count differed, because madge enumerates paths where this groups them."
+  },
+  importEdges: {
+    label: "Imports between files",
+    what: "How many times one of the module's own files imports another of them.",
+    read: "Read it against the file count beside it rather than on its own: roughly two to three edges per file is what the modules measured here sit at. It is the size of the graph every other figure on this block is computed over.",
+    caveat: "Module-local on purpose, so it says nothing about what the module pulls from the rest of the workspace: a front app importing three hundred components from `libs/` shows none of that here. Tests are outside the graph too, specs and the support beside them, so a file every spec imports does not look busy because of them: measured on `apps/front/host-admin`, 113 helpers in a `testing/` or `test/` directory or named `*.msw.ts` were counted as product code until the role's glob learnt those conventions, and each was showing up as a community of its own. Generated code is out as well: on `apps/front/console`, excluding `routeTree.gen.ts` removes 20 edges and the module's only cycle, which is TanStack's own and which nobody can fix by hand.",
+    source: "Built from the oxc parse of every file the role scans, resolving relative specifiers only. The resolution was held against madge, which follows the workspace path aliases, over five modules with the same exclusions on both sides: 16 052 edges, no code edge missed and none invented, the 28 differences all imports of files outside the scanned languages."
+  },
+  graphDensity: {
+    label: "Density",
+    what: "The share of all the edges that could exist between these files that actually do.",
+    read: "Between 0 and 1, and near 0 in real code. It is a shape, not a score: it tells you whether the module is a web or a tree.",
+    caveat: "\u26D4 Do NOT compare it between modules of different sizes, and the reason is arithmetic rather than opinion: the denominator grows with the SQUARE of the file count, so a module gets a lower density by growing, not by improving. Measured here: `libs/nest/auth` 0.0216 at 101 files and `apps/front/host-admin` 0.0005 at 4 380, which says almost nothing about either. What it is good for is one module watched over time at a stable size.",
+    source: "graphology-metrics, graph density, the standard definition for a directed graph."
+  },
+  communities: {
+    label: "Communities",
+    what: "How many clusters of files the partition found, where a cluster is a set of files much more connected to each other than to the rest.",
+    read: "Read it against the module's own directories, which is the grouping the team wrote by hand. Expect it to be HIGHER: the partition refines the folders rather than reproducing them, measured at 24 communities for 16 domains on a nest service and 208 for 20 modules on the largest front app. Held against the directories over five modules, each community sits inside one directory 58% to 85% of the time, and each directory splits across several communities, so the agreement is a refinement and not a match.",
+    caveat: "The count depends on a setting, `graph.resolution`, which the report prints: changing it changes the answer, and graphology warns in its own documentation that it is finicky to tweak. The role ships the published value of 1 rather than one chosen to make the partition look right. The algorithm is also greedy, so this is one good partition, not the best one. \u26A0\uFE0F And a community holding two directories is NOT a statement that they depend on each other: a file both of them import pulls them together on its own. Measured on `apps/nest/microservices/recruitment`, one community holds 79 files of `candidate-management` and 64 of `application-management` with 4 edges between the two halves, because 12 shared enums sit between them, one of which is imported 58 times. \u26A0\uFE0F A community of ONE file means the module's own code neither imports it nor is imported by it, which is a strong signal and not a verdict. Measured on `apps/front/host-admin`: 53 such files, of which 37 have no reference anywhere and are dead, 10 are routes the framework loads by convention, and 5 are test helpers whose naming this role does not recognise. \u26D4 Read it WITH the dead-code figures rather than against them: this pass sees a file as a node, so it can only say that nothing reaches it, while the dead-code pass looks inside the files and reports an unused export or an unused symbol in a file that is otherwise very much alive. Two scales, not two answers to one question.",
+    source: "Louvain, via graphology-communities-louvain, with the role's own random seed so the figure reproduces. Blondel, Guillaume, Lambiotte and Lefebvre, 2008."
+  },
+  modularity: {
+    label: "Modularity (Q)",
+    what: "The quality of the ASSIGNMENT of files to communities: how much more densely connected the files inside a community are than the same files would be in a random network. Both halves of the words a team already uses are in that sentence, which is why the figure is worth having: dense inside is cohesion, the degree to which the elements of a part belong together, and sparse between is what makes a part independent enough to be given an interface.",
+    read: "Between -1 and 1. It judges the partition, not the code, and that is what makes it architectural: Louvain already maximised it, so a low value does not mean a poor partition was picked, it means no good one exists and the module does not decompose along its imports. A high value says the opposite, that a modular model is there to be read, and the drawing is where to read it. The five modules measured here sit between 0.58 and 0.84.",
+    caveat: "\u26A0\uFE0F Do not read the fourth decimal. Louvain is greedy, so Q is the value of ONE local optimum: measured over 20 runs with the library's own randomness, `console` produced 16 different values and `recruitment` spanned 0.0357. The role pins its seed, which makes the figure reproducible but not exact, so a change smaller than a hundredth between two runs of two different versions means nothing. A high Q also does not mean the clusters are the right ones: it says they are separable, not that they match any boundary a team cares about. Read as cohesion it is a practical one: files that interact are a population that lives together, the way Louvain was meant to divide a social network, so it catches technical and functional coupling alike. What it will not give you is a place to go, because it is one average over the whole module. The communities themselves are, and the drawing is there for that.",
+    source: "Newman-Girvan modularity, via graphology-metrics, which states in its own source that it stays true to Newman's original definition. Q is the measure; Louvain is the algorithm that maximises it. The wording of what it quantifies, the quality of an assignment of nodes to communities, is Neo4j's graph data science documentation."
+  },
+  mostImported: {
+    label: "Most imported files",
+    what: "The files the rest of the module leans on, by how many of its own files import them.",
+    read: "Context, not a defect list: every module has a most-imported file and a type definition used everywhere is doing its job. It is worth a look when the file at the top is one that CHANGES often, because then its import count is the number of files a change there can reach.",
+    caveat: "\u26A0\uFE0F If you compare this with another tool, note the unit. The count here is raw, how many files import this one. graphology's degree centrality, which `code-health-meter` reports, is NORMALISED by the file count, and the two can disagree in direction: `libs/nest/auth`'s busiest file is imported 18 times and scores 0.18, `apps/front/host-admin`'s is imported 122 times and scores 0.028. There is no threshold here and the role proposes none.",
+    source: "In-degree of the module import graph, with graphology degree centrality carried beside it for anyone holding this against another tool."
   }
 };
 function helpFor(key) {
@@ -5167,11 +5382,23 @@ var HTML_GROUP_LIMIT = 50;
 function figure(row) {
   return row.unit === "%" && typeof row.value === "number" ? row.value.toFixed(2) : String(row.value);
 }
+function caveatsOf(report) {
+  const keys = [...report.rows.map((row) => row.metric), ...report.findings.map((f) => f.metric)];
+  const seen = /* @__PURE__ */ new Set();
+  const found = [];
+  for (const key of keys) {
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const help = helpFor(key);
+    if (help) found.push(help);
+  }
+  return found;
+}
 function renderConsole(report) {
   const lines = [];
   const width = (pick) => Math.max(...report.rows.map((row) => pick(row).length));
   const label = (row) => helpFor(row.metric)?.label ?? row.metric;
-  const value = (row) => `${figure(row)} ${row.unit}`;
+  const value = (row) => `${figure(row)} ${row.unit}`.trim();
   const labelWidth = width(label);
   const valueWidth = width(value);
   lines.push(`sentinel static-analysis: ${report.module}`);
@@ -5206,21 +5433,21 @@ function renderConsole(report) {
       `  ${report.findings.length} place(s) to look, listed by \`${SCRIPTS.json}\` and \`${SCRIPTS.html}\``
     );
   }
-  const caveats = report.rows.map((row) => ({ row, help: helpFor(row.metric) })).filter(
-    (entry) => Boolean(entry.help)
-  );
+  const caveats = caveatsOf(report);
   if (caveats.length > 0) {
     lines.push("", "  what these numbers do not say");
-    for (const { row, help } of caveats) {
+    for (const help of caveats) {
       lines.push(`    ${help.label}: ${help.caveat}`, `      source: ${help.source}`);
-      void row;
     }
   }
   return `${lines.join("\n")}
 `;
 }
 function renderJson(report) {
-  const rows = report.rows.map((row) => ({ ...row, help: helpFor(row.metric) ?? null }));
+  const rows = report.rows.map((row) => {
+    const help = helpFor(row.metric);
+    return { ...row, help: help ? { label: help.label, caveat: help.caveat } : null };
+  });
   return `${JSON.stringify({ ...report, rows }, null, 2)}
 `;
 }
@@ -5238,12 +5465,12 @@ function renderHtml(report) {
         <td class="num">${escape(figure(row))} <span class="unit">${escape(row.unit)}</span></td>
       </tr>`;
   }).join("\n");
-  const reserves = report.rows.map((row) => ({ row, help: helpFor(row.metric) })).filter((entry) => entry.help).map(
-    ({ row, help }) => `    <details>
-      <summary>${escape(help?.label ?? row.metric)}<span class="what">${prose(help?.what ?? "")}</span></summary>
-      <p class="read"><b>How to read it.</b> ${prose(help?.read ?? "")}</p>
-      <p><b>What it does not say.</b> ${prose(help?.caveat ?? "")}</p>
-      <p class="source">Source: ${prose(help?.source ?? "")}</p>
+  const reserves = caveatsOf(report).map(
+    (help) => `    <details>
+      <summary>${escape(help.label)}<span class="what">${prose(help.what)}</span></summary>
+      <p class="read"><b>How to read it.</b> ${prose(help.read)}</p>
+      <p><b>What it does not say.</b> ${prose(help.caveat)}</p>
+      <p class="source">Source: ${prose(help.source)}</p>
     </details>`
   ).join("\n");
   const settings = report.settings.map(
@@ -5418,6 +5645,10 @@ ${rest > 0 ? `    <p class="sub">The ${HTML_GROUP_LIMIT} longest are listed; ${r
     color: var(--moved); font-size: 0.78rem; font-weight: 500;
     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; }
+
   /* The collapsed reserves. Closed by default: the figures are what the page opens on. */
   details { border-bottom: 1px solid var(--rule); }
   details:last-of-type { border-bottom: 0; }
@@ -5494,6 +5725,13 @@ ${report.notes.length > 0 ? `
 ${report.notes.map((note) => `      <tr><td class="read">${escape(note)}</td></tr>`).join("\n")}
     </tbody></table>
   </section>
+` : ""}
+${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>
@@ -5525,7 +5763,7 @@ function resolveJscpd(cwd) {
 }
 
 // src/roles/static-analysis/adapters/jscpd/jscpd.adapter.ts
-var EXTENSIONS = extensionsOf(defaults.languages);
+var EXTENSIONS2 = extensionsOf(defaults.languages);
 var scripts = () => ({
   [SCRIPTS.console]: `sentinel --run --${TARGET}`,
   [SCRIPTS.json]: `sentinel --run --${TARGET} --output json`,
@@ -5588,17 +5826,17 @@ var JscpdAdapter = class extends BaseAdapter {
     return true;
   }
   plan(context) {
-    if (!hasSourceFiles(context.cwd, EXTENSIONS)) {
+    if (!hasSourceFiles(context.cwd, EXTENSIONS2)) {
       return {
         operations: [],
-        skipped: `no file ${this.runner} can read (looked for ${EXTENSIONS.join(", ")}).`
+        skipped: `no file ${this.runner} can read (looked for ${EXTENSIONS2.join(", ")}).`
       };
     }
     return {
       operations: [
         // `write` and not `merge-json`: this file is code, and the engine's in-place merge is for
         // JSON. A re-init therefore RESTORES the stub, so an existing one is left alone below.
-        ...existsSync14(join19(context.cwd, STATIC_CONFIG_FILE)) ? [] : [{ kind: "write", path: STATIC_CONFIG_FILE, contents: configStub() }],
+        ...existsSync14(join20(context.cwd, STATIC_CONFIG_FILE)) ? [] : [{ kind: "write", path: STATIC_CONFIG_FILE, contents: configStub() }],
         manifestOperation(context.cwd, scripts()),
         ...nxTargetOperations({ cwd: context.cwd, targets: targets() })
         // The report directory is ignored ONCE at the workspace root, by `--init`'s workspace prep,
@@ -5627,9 +5865,9 @@ var JscpdAdapter = class extends BaseAdapter {
       );
       return { ok: false, code: 1 };
     }
-    if (!hasSourceFiles(ctx.cwd, EXTENSIONS)) {
+    if (!hasSourceFiles(ctx.cwd, EXTENSIONS2)) {
       process.stderr.write(
-        `sentinel static-analysis(jscpd): no file to measure in this module (looked for ${EXTENSIONS.join(", ")}).
+        `sentinel static-analysis(jscpd): no file to measure in this module (looked for ${EXTENSIONS2.join(", ")}).
 `
       );
       return { ok: true, code: 0 };
@@ -5678,8 +5916,9 @@ var JscpdAdapter = class extends BaseAdapter {
       );
     }
     const complexity = scanComplexity(ctx.cwd, config);
-    const report = assembleReport(ctx, config, product, tests, dead, complexity);
-    if (emitting) emit(report, shape, ctx.cwd);
+    const graph = scanGraph(ctx.cwd, config);
+    const report = assembleReport(ctx, config, product, tests, dead, complexity, graph);
+    if (emitting) await emit(report, shape, ctx.cwd, graph);
     return { ok: true, code: 0, metrics: metricsOf(report) };
   }
   /** `--run`: measure and show it. */
@@ -5750,7 +5989,7 @@ var JscpdAdapter = class extends BaseAdapter {
     const declared = moduleScripts(ctx.cwd);
     const missing = Object.keys(scripts()).filter((name) => !(name in declared));
     const adopted = missing.length < Object.keys(scripts()).length;
-    const hasConfig = existsSync14(join19(ctx.cwd, STATIC_CONFIG_FILE));
+    const hasConfig = existsSync14(join20(ctx.cwd, STATIC_CONFIG_FILE));
     return {
       adopted,
       preset: adopted ? ctx.preset : null,
@@ -5783,6 +6022,10 @@ function measuredWith(config) {
     row("deadCode.minConfidence", String(config.deadCode.minConfidence)),
     row("deadCode.categories", config.deadCode.categories.join(", ")),
     row("entry", `${config.entry.length} patterns`),
+    // ⚠️ 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,
+    // because it is not a setting: see `graph/scan.ts` for why the role owns it.
+    row("graph.resolution", String(config.graph.resolution)),
     // Not a setting a module can move: it is McCabe's own published figure, and the row says so
     // rather than letting a reader take it for one of ours.
     {
@@ -5818,7 +6061,7 @@ function runDeadCode(jscpd, config, paths, cwd) {
   try {
     const ran = runTool(jscpd, args, cwd, "dead-code");
     if (ran.kind !== "ran") return ran;
-    const path = join19(rawReportDir, RAW_REPORT["dead-code"]);
+    const path = join20(rawReportDir, RAW_REPORT["dead-code"]);
     if (!existsSync14(path)) {
       process.stderr.write(
         `sentinel static-analysis(jscpd): the dead-code pass wrote no ${RAW_REPORT["dead-code"]}
@@ -5826,7 +6069,7 @@ function runDeadCode(jscpd, config, paths, cwd) {
       );
       return { kind: "failed", code: 1 };
     }
-    const parsed = safeParseDeadCode(readFileSync15(path, "utf8"));
+    const parsed = safeParseDeadCode(readFileSync16(path, "utf8"));
     const statistics = parsed?.statistics;
     if (!statistics) {
       process.stderr.write(
@@ -5853,8 +6096,8 @@ function runDuplication(jscpd, config, paths, scope, cwd) {
   try {
     const ran = runTool(jscpd, args, cwd, scope);
     if (ran.kind !== "ran") return ran;
-    const path = join19(rawReportDir, RAW_REPORT.duplication);
-    const parsed = existsSync14(path) ? safeParse(readFileSync15(path, "utf8")) : void 0;
+    const path = join20(rawReportDir, RAW_REPORT.duplication);
+    const parsed = existsSync14(path) ? safeParse(readFileSync16(path, "utf8")) : void 0;
     const total = parsed?.statistics?.total;
     if (!total) {
       process.stderr.write(
@@ -5887,7 +6130,7 @@ function safeParseDeadCode(text) {
     return void 0;
   }
 }
-function placesToLook(product, tests, dead, complexity) {
+function placesToLook(product, tests, dead, complexity, graph) {
   const at = (side) => `${side?.name ?? "(unknown)"}${side?.start === void 0 ? "" : `:${side.start}`}`;
   const clones = (outcome, metric) => outcome.kind === "figures" ? outcome.duplicates.map((entry) => ({
     metric,
@@ -5920,10 +6163,26 @@ function placesToLook(product, tests, dead, complexity) {
       ...finding.confidence === void 0 ? {} : { confidence: finding.confidence },
       ...finding.reasons?.length ? { reason: finding.reasons.join(", ") } : {},
       ...finding.message ? { message: finding.message } : {}
-    })) : []
+    })) : [],
+    // One finding per GROUP of mutually importing files, not per cycle path: see `graph/scan.ts`.
+    // The first file names the finding and the rest go in `other`, which is the shape the report
+    // already renders for a clone's two sides.
+    ...graph.cycles.map((cycle) => ({
+      metric: "cycles",
+      path: cycle.files[0] ?? "(unknown)",
+      other: cycle.files.slice(1).join(", "),
+      value: cycle.files.length
+    })),
+    // ⛔ Context, not defects. Every module has a most-imported file, and nothing here says the
+    // count is too high: the caveat on the metric says so in the reader's own words.
+    ...graph.mostImported.map((file) => ({
+      metric: "mostImported",
+      path: file.path,
+      value: file.importedBy
+    }))
   ];
 }
-function assembleReport(ctx, config, product, tests, dead, complexity) {
+function assembleReport(ctx, config, product, tests, dead, complexity, graph) {
   const share = (total) => Number((total.percentage ?? 0).toFixed(2));
   const rows = [
     { metric: "duplicatedLinesPercent", value: share(product.total), unit: "%" },
@@ -5976,6 +6235,32 @@ function assembleReport(ctx, config, product, tests, dead, complexity) {
   } else {
     notes.push("no function to measure, so no complexity figure is reported");
   }
+  if (graph.files > 1) {
+    rows.push(
+      { metric: "importEdges", value: graph.edges, unit: `between ${graph.files} files` },
+      {
+        metric: "graphDensity",
+        value: Number(graph.density.toFixed(4)),
+        unit: "of the possible edges"
+      },
+      {
+        metric: "cycles",
+        // ⛔ Zero is the expected value here, so the unit has to read correctly at zero as well as
+        // at one, which `1 groups, 2 files` did not. The file count only means something when
+        // there is a group, so it is absent when there is none.
+        value: graph.cycles.length,
+        unit: graph.cycles.length === 0 ? "none" : `${graph.cycles.length === 1 ? "group" : "groups"}, ${graph.filesInCycles} files`
+      },
+      { metric: "communities", value: graph.communities, unit: `of ${graph.files} files` }
+    );
+    if (graph.modularity === void 0) {
+      notes.push("no import between the files, so no modularity is reported");
+    } else {
+      rows.push({ metric: "modularity", value: Number(graph.modularity.toFixed(4)), unit: "" });
+    }
+  } else {
+    notes.push("fewer than two files, so no graph figure is reported");
+  }
   const byLanguage = Object.fromEntries(
     Object.entries(product.formats).map(([language, stats]) => [
       language,
@@ -5992,28 +6277,41 @@ function assembleReport(ctx, config, product, tests, dead, complexity) {
       "duplication",
       ...tests.kind === "figures" ? ["duplication (tests)"] : [],
       ...dead.kind === "figures" ? ["dead code"] : [],
-      ...complexity.functions > 0 ? ["complexity"] : []
+      ...complexity.functions > 0 ? ["complexity"] : [],
+      ...graph.files > 1 ? ["graph"] : []
     ],
     rows,
     notes,
     settings: measuredWith(config),
-    findings: placesToLook(product, tests, dead, complexity),
+    findings: placesToLook(product, tests, dead, complexity, graph),
     byLanguage
   };
 }
-function emit(report, shape, cwd) {
+async function emit(report, shape, cwd, graph) {
   if (shape === "console") {
     process.stdout.write(renderConsole(report));
     return;
   }
+  mkdirSync(join20(cwd, REPORT_DIR), { recursive: true });
+  const written = [];
+  if (shape === "html" && graph.files > 1) {
+    const picture = `${TARGET}-graph.svg`;
+    const path = join20(cwd, REPORT_DIR, picture);
+    await writeGraphPicture(graph.graph, graph.communityOf, path);
+    written.push(`${REPORT_DIR}/${picture}`);
+    report.picture = inlineable(readFileSync16(path, "utf8"));
+  }
   const name = shape === "json" ? "static-analysis.json" : "static-analysis.html";
   const body = shape === "json" ? renderJson(report) : renderHtml(report);
-  mkdirSync(join19(cwd, REPORT_DIR), { recursive: true });
-  writeFileSync4(join19(cwd, REPORT_DIR, name), body, "utf8");
+  writeFileSync4(join20(cwd, REPORT_DIR, name), body, "utf8");
+  written.unshift(`${REPORT_DIR}/${name}`);
   process.stdout.write(`${renderConsole(report)}
-  written: ${REPORT_DIR}/${name}
+  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,
@@ -6044,9 +6342,9 @@ function registerTest() {
 
 // src/roles/typescript/adapters/tsc/tsc.adapter.ts
 import { spawnSync as spawnSync6 } from "node:child_process";
-import { existsSync as existsSync15, readFileSync as readFileSync17 } from "node:fs";
+import { existsSync as existsSync15, readFileSync as readFileSync18 } from "node:fs";
 import { createRequire } from "node:module";
-import { join as join21 } from "node:path";
+import { join as join22 } from "node:path";
 
 // src/roles/typescript/presets/nest.json
 var nest_default2 = {
@@ -6231,8 +6529,8 @@ function readTsconfigAdoption(cwd) {
 }
 
 // src/roles/typescript/adapters/tsc/plan.ts
-import { readFileSync as readFileSync16 } from "node:fs";
-import { join as join20 } from "node:path";
+import { readFileSync as readFileSync17 } from "node:fs";
+import { join as join21 } from "node:path";
 
 // src/roles/typescript/typecheck-script.ts
 var SENTINEL_TYPECHECK_COMMAND = "sentinel --run --typescript";
@@ -6325,7 +6623,7 @@ function planAdoption(context) {
     };
   }
   const existing = parseJsonc(
-    readFileSync16(join20(context.cwd, target.path), "utf8"),
+    readFileSync17(join21(context.cwd, target.path), "utf8"),
     target.path
   );
   const extendsChain = composeExtends(existing.extends, preset);
@@ -6463,7 +6761,7 @@ var TscAdapter = class _TscAdapter extends BaseAdapter {
     let chain;
     try {
       const parsed = parseJsonc(
-        readFileSync17(join21(cwd, target.path), "utf8"),
+        readFileSync18(join22(cwd, target.path), "utf8"),
         target.path
       );
       chain = parsed.extends;
@@ -6476,7 +6774,7 @@ var TscAdapter = class _TscAdapter extends BaseAdapter {
     );
     if (preset === void 0) return void 0;
     try {
-      createRequire(join21(cwd, "noop.js")).resolve(preset);
+      createRequire(join22(cwd, "noop.js")).resolve(preset);
       return void 0;
     } catch {
       return preset;
@@ -6572,7 +6870,7 @@ var TscAdapter = class _TscAdapter extends BaseAdapter {
   referencedProjects(cwd, config) {
     try {
       const parsed = parseJsonc(
-        readFileSync17(join21(cwd, config), "utf8"),
+        readFileSync18(join22(cwd, config), "utf8"),
         config
       );
       const referenced = (parsed.references ?? []).map((reference) => reference.path).filter((path) => typeof path === "string" && path.length > 0);
@@ -6588,7 +6886,7 @@ var TscAdapter = class _TscAdapter extends BaseAdapter {
    * check.
    */
   typecheckTarget(cwd) {
-    if (existsSync15(join21(cwd, "tsconfig.json"))) return "tsconfig.json";
+    if (existsSync15(join22(cwd, "tsconfig.json"))) return "tsconfig.json";
     const target = resolveTsconfigTarget(cwd);
     return target.reason === "none" ? null : target.path;
   }
@@ -6794,7 +7092,7 @@ function replaceLines(current, replacements) {
 }
 
 // src/core/apply-plan.ts
-import { existsSync as existsSync16, readFileSync as readFileSync18, renameSync, rmSync as rmSync4, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync16, readFileSync as readFileSync19, renameSync, rmSync as rmSync4, writeFileSync as writeFileSync5 } from "node:fs";
 import { resolve as resolve3, sep } from "node:path";
 import { applyEdits, findNodeAtLocation, modify, parseTree } from "jsonc-parser";
 function resolveWithinRoot(cwd, relativePath) {
@@ -6806,7 +7104,7 @@ function resolveWithinRoot(cwd, relativePath) {
   return absolutePath;
 }
 function readIfExists(absolutePath) {
-  return existsSync16(absolutePath) ? readFileSync18(absolutePath, "utf8") : void 0;
+  return existsSync16(absolutePath) ? readFileSync19(absolutePath, "utf8") : void 0;
 }
 function* leaves(value, prefix = []) {
   for (const [key, keyValue] of Object.entries(value)) {
@@ -6924,8 +7222,8 @@ function applyPlan(cwd, plan3) {
 }
 
 // src/core/config/preset-evidence.ts
-import { existsSync as existsSync17, readdirSync as readdirSync3, readFileSync as readFileSync19 } from "node:fs";
-import { join as join22 } from "node:path";
+import { existsSync as existsSync17, readdirSync as readdirSync3, readFileSync as readFileSync20 } from "node:fs";
+import { join as join23 } from "node:path";
 var PATH_SIGNALS = [
   {
     preset: "nest",
@@ -6959,12 +7257,12 @@ function sourceImports(cwd, pattern) {
     }
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        if (!NOT_SCANNED.has(entry.name)) stack.push(join22(dir, entry.name));
+        if (!NOT_SCANNED.has(entry.name)) stack.push(join23(dir, entry.name));
         continue;
       }
       if (!SOURCE_FILE.test(entry.name)) continue;
       try {
-        if (pattern.test(readFileSync19(join22(dir, entry.name), "utf8"))) return true;
+        if (pattern.test(readFileSync20(join23(dir, entry.name), "utf8"))) return true;
       } catch {
         continue;
       }
@@ -6973,11 +7271,11 @@ function sourceImports(cwd, pattern) {
   return false;
 }
 function dependencyNames(cwd) {
-  const path = join22(cwd, "package.json");
+  const path = join23(cwd, "package.json");
   if (!existsSync17(path)) return [];
   try {
     const manifest = parseJsonc(
-      readFileSync19(path, "utf8"),
+      readFileSync20(path, "utf8"),
       path
     );
     return [
@@ -7000,7 +7298,7 @@ function reactTsconfigEvidence(cwd) {
   }
   for (const name of entries) {
     try {
-      const config = parseJsonc(readFileSync19(join22(cwd, name), "utf8"), name);
+      const config = parseJsonc(readFileSync20(join23(cwd, name), "utf8"), name);
       if (config.compilerOptions?.jsx !== void 0) return 'its tsconfig sets "jsx"';
       const extended = Array.isArray(config.extends) ? config.extends : config.extends === void 0 ? [] : [config.extends];
       if (extended.some((entry) => entry === REACT_TYPESCRIPT_PRESET)) {

package/dist/index.js

@@ -6,12 +6,12 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-S3LXWTKH.js";
+} from "./chunk-OKHGGXNC.js";
 import {
   BaseAdapter
 } from "./chunk-KLEXJFJ6.js";
 import "./chunk-YQRDKWSH.js";
-import "./chunk-UUPP5UQS.js";
+import "./chunk-AYEOGJQR.js";
 import "./chunk-O7REVMOC.js";
 import "./chunk-QXFCZON7.js";
 export {

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

@@ -13,6 +13,9 @@ type StaticDefaults = {
         minConfidence: number;
         categories: string[];
     };
+    graph: {
+        resolution: number;
+    };
     tools: {
         jscpd: Record<string, unknown>;
     };

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

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

package/docs/typescript-traces.md

@@ -1183,9 +1183,10 @@ $ sentinel --init --dry-run
     +   //   duplication.minTokens   50
     +   //   duplication.minLines    5
     +   //   duplication.kinds       exact
-    +   //   duplication.tests       2 patterns
+    +   //   duplication.tests       3 patterns
     +   //   deadCode.minConfidence  60
     +   //   deadCode.categories     unused-file, unused-export, unused-symbol, unused-import
+    +   //   graph.resolution        1
     +   //
     +   // A list shown as a count is not copyable, and replacing one means writing back what you keep,
     +   // so read the values in full with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hublo/sentinel",
-  "version": "1.5.0-alpha.16",
+  "version": "1.5.0-alpha.18",
   "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",
@@ -120,6 +120,14 @@
     "eslint-plugin-react-refresh": "0.4.19",
     "eslint-plugin-storybook": "10.3.5",
     "eslint-plugin-styled-components-a11y": "2.2.0",
+    "graphology": "0.26.0",
+    "graphology-communities-louvain": "2.0.2",
+    "graphology-components": "1.5.4",
+    "graphology-layout": "0.6.1",
+    "graphology-layout-forceatlas2": "0.10.1",
+    "graphology-metrics": "2.4.2",
+    "graphology-svg": "0.1.3",
+    "graphology-types": "0.24.8",
     "html-validate": "^11.16.0",
     "jscpd": "5.4.0",
     "jsdom": "^24.1.3",

package/dist/chunk-UUPP5UQS.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\": [\n    \"**/*.integration-spec.ts\",\n    \"**/*.steps.ts\",\n    \"src/client.tsx\",\n    \"src/start.ts\",\n    \"src/router.tsx\",\n    \"src/RouterContext.tsx\"\n  ],\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 *    ⭐ The four `src/` files are the FRONT bootstrap, and they are the most consequential thing\n *    measured on this pass. The tool recognises around fifty frameworks and TanStack Start is not\n *    one of them, so nothing in the repository imports these files: the framework finds them by\n *    convention at build time. Measured without them declared, `apps/front/console` reports\n *    `src/client.tsx`, `src/router.tsx` and `src/start.ts` among its 5 dead files, which are its\n *    hydration entry, its router factory and its Start config. `host-admin` reports `client.tsx`\n *    too and `career` reports `router.tsx` and `RouterContext.tsx`. Three of console's five\n *    findings were its own bootstrap, and the first team to see that stops trusting the tool on\n *    the spot. They exist in 2 to 3 front apps each.\n *\n *    ⛔ `scripts/**` is deliberately NOT here, although 8 modules have one and\n *    `apps/nest/microservices/contract` reports two `scripts/e2e-*.ts` as dead. No `package.json`\n *    script invokes them, so whether they run at all is a fact only the team holds. Declaring them\n *    would hide a finding that may well be true, and that is the opposite of this role's job.\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\n/** The target this role serves, which is also the npm script a module runs and the nx target. */\nexport const TARGET = 'static-analysis'\n\n/** The output shapes `--run` can produce. `console` writes nothing to disk. */\nexport const SHAPES = ['console', 'json', 'html'] as const\n\n/**\n * The npm scripts a module gets, one per shape.\n *\n * Here rather than in the adapter because the REPORT needs them too, to tell a reader of the\n * console summary where the detail is, and two spellings of one script name is drift nobody\n * notices until a developer types the one that does not exist.\n */\nexport const SCRIPTS = {\n  console: TARGET,\n  json: `${TARGET}:json`,\n  html: `${TARGET}:html`,\n} as const\n\n/**\n * What each language the role scans is called on disk.\n *\n * ⚠️ Two lists that MUST agree, and they were maintained separately: the role declares the\n * languages it asks the tool to scan, and the adapter declared the extensions it looks for when\n * deciding whether a module has anything to measure at all. A module that narrowed `languages`\n * would still be probed for the extensions it had removed, and a language added to the preset\n * would never reach the probe. Derived from one source now, with a test that every language maps.\n */\nconst EXTENSIONS_BY_LANGUAGE: Record<string, string[]> = {\n  javascript: ['.js', '.mjs', '.cjs'],\n  typescript: ['.ts'],\n  jsx: ['.jsx'],\n  tsx: ['.tsx'],\n  css: ['.css'],\n  scss: ['.scss'],\n}\n\n/** The file extensions of the languages given, for deciding whether a module has anything to read. */\nexport function extensionsOf(languages: readonly string[]): string[] {\n  return [...new Set(languages.flatMap((language) => EXTENSIONS_BY_LANGUAGE[language] ?? []))]\n}\n\n/** Every language the mapping knows, so a test can hold it against the preset. */\nexport const MAPPED_LANGUAGES = Object.keys(EXTENSIONS_BY_LANGUAGE)\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/**\n * Keys a module declares DIRECTLY rather than through `overrides`, and how each one combines.\n *\n * They are apart because the verb differs: these two are added to and merged, so a team cannot\n * lose what the role ships by declaring its own. Everything else replaces.\n */\nconst DECLARED: Record<string, string> = {\n  entry: 'added to the patterns the role ships, never replacing them',\n  journeys: \"merged by name with the role's\",\n}\n\n/**\n * ⛔ Not a module's to set, and the catalogue says so rather than leaving it absent: a key that is\n * simply missing from a list reads as an oversight, and someone will try it. Passing it is dropped\n * with a message, see `configs/define.ts`.\n */\nconst NOT_YOURS: Record<string, string> = {\n  tools: \"sentinel's own passthrough to the tool underneath; a module never names the vendor\",\n}\n\n/** A value as a reader compares it: short lists in full, long ones as a count. */\nfunction render(value: unknown): string {\n  if (Array.isArray(value)) {\n    const joined = value.join(', ')\n    return value.length <= 6 && joined.length <= 72 ? joined : `${value.length} patterns`\n  }\n  if (value && typeof value === 'object') return `${Object.keys(value).length} entries`\n  return String(value)\n}\n\n/** One documented key: its path, the role's value, and the note a reader needs. */\nexport interface OverridableSetting {\n  /** The dotted path a module writes, e.g. `duplication.minTokens`. */\n  key: string\n  /** The role's current value, rendered. */\n  value: string\n  /** How it combines, or why it is not available. */\n  note: string\n  /** Where it goes: directly in the config, inside `overrides`, or nowhere. */\n  where: 'declared' | 'overrides' | 'refused'\n}\n\n/**\n * Every setting a module can touch, DERIVED from the values rather than written beside them.\n *\n * Héla's ask, and the reason it is generated: a hand-written list is a second copy of the preset,\n * and the first setting somebody adds makes it a lie that nobody notices, because a stale comment\n * fails no test. Here a new key appears in the next module's config file on its own, with its real\n * value, and `tests/role-layout.test.ts` refuses a key that reaches none of the three groups.\n *\n * It is a snapshot: `--init` leaves an EXISTING config alone, by design, so a module that adopted\n * earlier keeps the catalogue of that day. The report is the live answer, since it prints the value\n * every figure was produced with.\n */\nexport function overridableSettings(from: StaticDefaults = defaults): OverridableSetting[] {\n  const rows: OverridableSetting[] = []\n\n  for (const [key, value] of Object.entries(from)) {\n    if (key in NOT_YOURS) {\n      rows.push({ key, value: render(value), note: NOT_YOURS[key] ?? '', where: 'refused' })\n      continue\n    }\n    if (key in DECLARED) {\n      rows.push({ key, value: render(value), note: DECLARED[key] ?? '', where: 'declared' })\n      continue\n    }\n    // A group is documented by its leaves, because `duplication` whole is not what anyone writes.\n    const leaves =\n      value && typeof value === 'object' && !Array.isArray(value)\n        ? Object.entries(value).map(([leaf, own]) => ({ key: `${key}.${leaf}`, own }))\n        : [{ key, own: value }]\n    for (const leaf of leaves) {\n      rows.push({ key: leaf.key, value: render(leaf.own), note: 'replaced', where: 'overrides' })\n    }\n  }\n\n  return rows\n}\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":"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","names":[]}