@hublo/sentinel 1.5.0 → 1.5.1-alpha.0

package/docs/typescript-traces.md

@@ -1298,10 +1298,259 @@ $ sentinel --init --dry-run
     +     }
     +   }
     + }
+  dry run: the lint autofix runs on adoption and can rewrite source, as moving to another linter does; add --rehearse to name the files (it runs the pass in a throwaway copy, as long as the real one)
+  dry run: the format autofix runs on adoption and can rewrite source, as moving to another formatter does; add --rehearse to name the files (it runs the pass in a throwaway copy, as long as the real one)
   dry run: would ignore static-analysis-report/ in the root .gitignore
 # exit: 0
 ```
 
+**--init --dry-run --rehearse (runs the autofixes in a copy, names what they rewrite)**
+
+```console
+$ sentinel --init --dry-run --rehearse
+  dry run: no files written
+  wrote .oxlintrc.json extending ./node_modules/@hublo/sentinel/lint/nest.json (@hublo/sentinel@<version>)
+  20 rule(s) not enforced by this preset (17 jest, 1 no-barrel-files, 1 core, 1 vitest). Run --inspect --lint for each rule and why.
+  run `pnpm install`, then `pnpm run lint`
+
+  create .oxlintrc.json
+    + {
+    +   "extends": [
+    +     "./node_modules/@hublo/sentinel/lint/nest.json"
+    +   ],
+    +   "ignorePatterns": [
+    +     "**/dist/**",
+    +     "**/node_modules/**",
+    +     "coverage/**",
+    +     "**/jest.*.{ts,js,cjs,mjs}",
+    +     "**/eslint.config.{js,cjs,mjs}",
+    +     "**/*.timestamp*",
+    +     "**/*.d.ts"
+    +   ]
+    + }
+
+  update package.json
+    - { "name": "bff-admin", "dependencies": { "@nestjs/core": "^10" } }
+    + {
+    +   "name": "bff-admin",
+    +   "dependencies": {
+    +     "@nestjs/core": "^10"
+    +   },
+    +   "scripts": {
+    +     "lint": "sentinel --run --lint"
+    +   },
+    +   "devDependencies": {
+    +     "@hublo/sentinel": "<version>"
+    +   },
+    +   "nx": {
+    +     "targets": {
+    +       "lint": {
+    +         "cache": true,
+    +         "inputs": [
+    +           "default",
+    +           "^default",
+    +           "{projectRoot}/.oxlintrc.json"
+    +         ]
+    +       }
+    +     }
+    +   }
+    + }
+  dry run: no files written
+  run `pnpm install` to fetch @hublo/sentinel (added to the module devDependencies) so `extends` and the typecheck script resolve
+
+  update tsconfig.json
+    - { "extends": "../../tsconfig.base.json", "include": ["src"] }
+    + { "extends": [
+    +     "../../tsconfig.base.json",
+    +     "@hublo/sentinel/typescript/nest"
+    +   ], "include": ["src"] }
+
+  update package.json
+    - { "name": "bff-admin", "dependencies": { "@nestjs/core": "^10" } }
+    + {
+    +   "name": "bff-admin",
+    +   "dependencies": {
+    +     "@nestjs/core": "^10"
+    +   },
+    +   "scripts": {
+    +     "typecheck": "sentinel --run --typescript"
+    +   },
+    +   "devDependencies": {
+    +     "@hublo/sentinel": "<version>"
+    +   },
+    +   "nx": {
+    +     "targets": {
+    +       "typecheck": {
+    +         "cache": true,
+    +         "inputs": [
+    +           "default",
+    +           "^default",
+    +           "{projectRoot}/tsconfig.json"
+    +         ]
+    +       }
+    +     }
+    +   }
+    + }
+  build: no Vite config in this module, so there is nothing to point at sentinel. This role moves an existing config's imports; it does not introduce a bundler. If this module builds another way (38 services here build through `@nx/webpack`), the build role does not apply to it.
+  test: this module has no test and no jest leftovers, so there is nothing to do here.
+  dry run: no files written
+  added the three `static-analysis` scripts and static-analysis.config.mjs; declare this module's entry points there, everything else comes from the role
+
+  create static-analysis.config.mjs
+    + import { defineStaticAnalysis } from '@hublo/sentinel/static-analysis'
+    + 
+    + export default defineStaticAnalysis({
+    +   root: import.meta.dirname,
+    + 
+    +   // Files that RUN although nothing imports them: they are where reachability starts. Added to
+    +   // the patterns sentinel ships, never replacing them.
+    +   entry: [],
+    + 
+    +   // ---------------------------------------------------------------------------------------------
+    +   // What this module can move, with the role's value today. A setting you leave out keeps that
+    +   // value; a setting you write REPLACES it, including inside a list. Anything you set is printed
+    +   // under "measured with" in the report and marked `(module)`, because two modules measured with
+    +   // different settings can no longer be compared.
+    +   //
+    +   //   ignore                  19 patterns
+    +   //   languages               javascript, typescript, jsx, tsx, css, scss
+    +   //   duplication.minTokens   50
+    +   //   duplication.minLines    5
+    +   //   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:
+    +   //
+    +   //   pnpm exec sentinel --inspect --static-analysis --json
+    +   //
+    +   //   duplication.kinds: only `exact` is supported: any other kind overlaps it and double-counts
+    +   //   tools: sentinel's own passthrough to the tool underneath; a module never names the vendor
+    +   //
+    +   // overrides: {
+    +   //   duplication: { minTokens: 100 },
+    +   // },
+    + })
+
+  update package.json
+    - { "name": "bff-admin", "dependencies": { "@nestjs/core": "^10" } }
+    + {
+    +   "name": "bff-admin",
+    +   "dependencies": {
+    +     "@nestjs/core": "^10"
+    +   },
+    +   "scripts": {
+    +     "static-analysis": "sentinel --run --static-analysis",
+    +     "static-analysis:json": "sentinel --run --static-analysis --output json",
+    +     "static-analysis:html": "sentinel --run --static-analysis --output html"
+    +   },
+    +   "devDependencies": {
+    +     "@hublo/sentinel": "<version>"
+    +   },
+    +   "nx": {
+    +     "targets": {
+    +       "static-analysis": {
+    +         "cache": true,
+    +         "inputs": [
+    +           "default",
+    +           "{projectRoot}/static-analysis.config.mjs"
+    +         ]
+    +       }
+    +     }
+    +   }
+    + }
+  dry run: no files written
+  materialized the nest format preset into .oxfmtrc.json (@hublo/sentinel@<version>). oxfmt has no `extends`, so the values live here; `sentinel --status --format` reports modules left behind by a preset change
+
+  create .oxfmtrc.json
+    + {
+    +   "$sentinel": {
+    +     "preset": "nest",
+    +     "version": "<version>",
+    +     "local": []
+    +   },
+    +   "printWidth": 80,
+    +   "semi": false,
+    +   "singleQuote": true,
+    +   "trailingComma": "all",
+    +   "sortPackageJson": false,
+    +   "sortImports": {
+    +     "customGroups": [
+    +       {
+    +         "groupName": "workspace",
+    +         "elementNamePattern": [
+    +           "@hublo/**",
+    +           "@shared/**",
+    +           "@front/**",
+    +           "@network/**"
+    +         ]
+    +       }
+    +     ],
+    +     "groups": [
+    +       "builtin",
+    +       "external",
+    +       "workspace",
+    +       [
+    +         "parent",
+    +         "index"
+    +       ],
+    +       "sibling"
+    +     ],
+    +     "newlinesBetween": true,
+    +     "order": "asc",
+    +     "ignoreCase": false
+    +   },
+    +   "ignorePatterns": [
+    +     "**/*.toml"
+    +   ]
+    + }
+
+  update package.json
+    - { "name": "bff-admin", "dependencies": { "@nestjs/core": "^10" } }
+    + {
+    +   "name": "bff-admin",
+    +   "dependencies": {
+    +     "@nestjs/core": "^10"
+    +   },
+    +   "scripts": {
+    +     "format": "sentinel --run --format",
+    +     "format:fix": "sentinel --run --format --fix"
+    +   },
+    +   "devDependencies": {
+    +     "@hublo/sentinel": "<version>"
+    +   },
+    +   "nx": {
+    +     "targets": {
+    +       "format": {
+    +         "cache": true,
+    +         "inputs": [
+    +           "default",
+    +           "{projectRoot}/.oxfmtrc.json"
+    +         ]
+    +       },
+    +       "format:fix": {
+    +         "cache": false
+    +       }
+    +     }
+    +   }
+    + }
+  dry run: the lint autofix cannot be rehearsed yet: its preset is not installed in this module, which is expected before the first `pnpm install`. After it, this dry-run names what it rewrites
+  dry run: the format autofix would rewrite 1 file beyond the ones above: project.json
+  dry run: would ignore static-analysis-report/ in the root .gitignore
+# exit: 0
+```
+
+**--rehearse without --dry-run**
+
+```console
+$ sentinel --init --rehearse
+--rehearse only applies to --init --dry-run: the real --init runs the autofix passes themselves.
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
 **no module and no workspace root**
 
 ```console

package/docs/using-sentinel.md

@@ -34,7 +34,15 @@ everywhere (`--run --json` and `--inspect` answer them), and `--migrate` is refu
 | `--static-analysis` | the config stub + three scripts + nx metadata, and ignores the report directory at the repository root    | measures and reports; never exits non-zero on a finding        | runner, config file, resolved settings, what this module moved   |
 
 `--json` works for every verb, and stdout carries **only** the envelope, so `| jq` always
-parses. `--dry-run` applies to `--init` and writes nothing.
+parses. `--dry-run` applies to `--init` and writes nothing. Besides the config diffs, it says
+that the lint autofix and the formatter run on adoption and can rewrite source, which is what
+moving to another linter or formatter does. It does not run them: on a large module that costs
+what the real pass costs (260 s measured on `network`).
+
+`--init --dry-run --rehearse` runs them, and names the source files they would rewrite
+(`rewrites` in `--json`, absent without `--rehearse`): both run in a throwaway copy of the
+module, outside the workspace, and what changed is read back. `--rehearse` without `--dry-run`
+is refused, because a real `--init` runs the passes itself.
 
 `--output <shape>` is different, and only a role that WRITES a report reads it: `console` is the
 default and writes no file, `html` is the page you open and send, `json` is for CI and for a

package/package.json

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