@hublo/sentinel 1.3.0 → 1.4.0-alpha.2

package/docs/typescript-traces.md

@@ -0,0 +1,798 @@
+# sentinel CLI — command & scenario traces
+
+Version `1.1.0-alpha.3` · live runs against the committed mock monorepo and fixtures (colour stripped, exit codes shown).
+Generated by `scripts/gen-traces.sh`; do not edit by hand.
+
+> A check composes **verb × type × location**. Verbs: `--run --inspect --report --status --init  (--migrate: planned)`.
+> Types: `--typescript` today; `--lint --format --build --test ...` planned. Location: a module dir → that module; the root → `--module`, `--ci`, or all.
+
+---
+
+## 1. Read verbs across the workspace
+
+Four mock modules cover each preset: `react-app`, `bff-admin` (nest), `svelte-app`, `utils` (node).
+
+**--report --typescript**
+
+```console
+$ sentinel --report --typescript
+sentinel: --report is deprecated, use --run --json (it still works)
+  ✓ svelte-app (svelte) typescript — errors=0 implicitAny=0
+  ✓ bff-admin (nest) typescript — errors=0 implicitAny=deferred
+  ✓ react-app (react) typescript — errors=0 implicitAny=deferred
+  ✓ utils (node) typescript — errors=0 implicitAny=deferred
+  4 module(s) [all] in <n>ms
+# exit: 0
+```
+
+**--report --typescript --json** (stdout only, the JSON envelope)
+
+```json
+$ sentinel --report --typescript --json 2>/dev/null
+{
+  "schemaVersion": 2,
+  "executed": [
+    "typescript"
+  ],
+  "skipped": [],
+  "results": [
+    {
+      "project": "svelte-app",
+      "target": "typescript",
+      "flavour": "svelte",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": 0,
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "bff-admin",
+      "target": "typescript",
+      "flavour": "nest",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "react-app",
+      "target": "typescript",
+      "flavour": "react",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "utils",
+      "target": "typescript",
+      "flavour": "node",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    }
+  ]
+}
+```
+
+**--inspect --typescript**
+
+```console
+$ sentinel --inspect --typescript
+  · svelte-app (svelte) typescript — not adopted
+  · bff-admin (nest) typescript — not adopted
+  · react-app (react) typescript — not adopted
+  · utils (node) typescript — not adopted
+  coverage: 0/4 adopted · 0/0 conformant
+  4 module(s) [all] in <n>ms
+# exit: 0
+```
+
+**--status --typescript**
+
+```console
+$ sentinel --status --typescript
+sentinel: --status is deprecated, use --inspect (it still works)
+  · svelte-app (svelte) typescript — not adopted
+  · bff-admin (nest) typescript — not adopted
+  · react-app (react) typescript — not adopted
+  · utils (node) typescript — not adopted
+  coverage: 0/4 adopted · 0/0 conformant
+  4 module(s) [all] in <n>ms
+# exit: 0
+```
+
+**--status --typescript --json** (stdout only, the JSON envelope)
+
+```json
+$ sentinel --status --typescript --json 2>/dev/null
+{
+  "schemaVersion": 2,
+  "executed": [
+    "typescript"
+  ],
+  "skipped": [],
+  "results": [
+    {
+      "project": "svelte-app",
+      "target": "typescript",
+      "flavour": "svelte",
+      "ok": true,
+      "status": "ok",
+      "adopted": false,
+      "preset": null,
+      "conformant": false,
+      "drift": []
+    },
+    {
+      "project": "bff-admin",
+      "target": "typescript",
+      "flavour": "nest",
+      "ok": true,
+      "status": "ok",
+      "adopted": false,
+      "preset": null,
+      "conformant": false,
+      "drift": []
+    },
+    {
+      "project": "react-app",
+      "target": "typescript",
+      "flavour": "react",
+      "ok": true,
+      "status": "ok",
+      "adopted": false,
+      "preset": null,
+      "conformant": false,
+      "drift": []
+    },
+    {
+      "project": "utils",
+      "target": "typescript",
+      "flavour": "node",
+      "ok": true,
+      "status": "ok",
+      "adopted": false,
+      "preset": null,
+      "conformant": false,
+      "drift": []
+    }
+  ],
+  "coverage": {
+    "total": 4,
+    "adopted": 0,
+    "conformant": 0,
+    "drifted": 0
+  }
+}
+```
+
+**--run --typescript --module bff-admin (real tsc)**
+
+```console
+$ sentinel --run --typescript --module bff-admin
+sentinel typescript: phase 1 (non-breaking) — deferred: noImplicitAny, noUnusedLocals, noUnusedParameters. Enabled centrally in a later wave; run `sentinel --inspect --typescript` for the list, or `sentinel --run --typescript -- --noImplicitAny` to measure what one would cost today.
+  ✓ bff-admin (nest) typescript
+  1 module(s) [named-module] in <n>ms
+# exit: 0
+```
+
+## 2. Location: root vs one module vs inside a module
+
+**from ROOT, one module**
+
+```console
+$ sentinel --report --typescript --module react-app
+sentinel: --report is deprecated, use --run --json (it still works)
+  ✓ react-app (react) typescript — errors=0 implicitAny=deferred
+  1 module(s) [named-module] in <n>ms
+# exit: 0
+```
+
+**from INSIDE a module dir**
+
+```console
+$ sentinel --report --typescript
+sentinel: --report is deprecated, use --run --json (it still works)
+  ✓ bff-admin (nest) typescript — errors=0 implicitAny=deferred
+  1 module(s) [cwd-module] in <n>ms
+# exit: 0
+```
+
+**no type = all types (only typescript wired)** (stdout only, the JSON envelope)
+
+```json
+$ sentinel --report --json 2>/dev/null
+{
+  "schemaVersion": 2,
+  "executed": [
+    "lint",
+    "typescript"
+  ],
+  "skipped": [
+    "format",
+    "build",
+    "test",
+    "static-analysis",
+    "runtime-analysis",
+    "arch"
+  ],
+  "results": [
+    {
+      "project": "svelte-app",
+      "target": "lint",
+      "flavour": "svelte",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "svelte-app",
+      "target": "typescript",
+      "flavour": "svelte",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": 0,
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "bff-admin",
+      "target": "lint",
+      "flavour": "nest",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "bff-admin",
+      "target": "typescript",
+      "flavour": "nest",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "react-app",
+      "target": "lint",
+      "flavour": "react",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "react-app",
+      "target": "typescript",
+      "flavour": "react",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "utils",
+      "target": "lint",
+      "flavour": "node",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "utils",
+      "target": "typescript",
+      "flavour": "node",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    }
+  ]
+}
+```
+
+## 3. Options
+
+**--preset overrides detection**
+
+```console
+$ sentinel --inspect --typescript --module utils --preset react
+  ✓ utils (react) typescript — configFile=tsconfig.json configState=extends-base preset=null adopted=false phase=1 deferred=3
+      deferred (phase 1, non-breaking):
+        • noImplicitAny — phase 2: the implicit-any migration (TS70xx)
+        • noUnusedLocals — phase 2: unused-local cleanup (TS6133)
+        • noUnusedParameters — phase 2: unused-parameter cleanup (TS6133)
+  1 module(s) [named-module] in <n>ms
+# exit: 0
+```
+
+**--all --json (executed vs skipped)** (stdout only, the JSON envelope)
+
+```json
+$ sentinel --report --all --json 2>/dev/null
+{
+  "schemaVersion": 2,
+  "executed": [
+    "lint",
+    "typescript"
+  ],
+  "skipped": [
+    "format",
+    "build",
+    "test",
+    "static-analysis",
+    "runtime-analysis",
+    "arch"
+  ],
+  "results": [
+    {
+      "project": "svelte-app",
+      "target": "lint",
+      "flavour": "svelte",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "svelte-app",
+      "target": "typescript",
+      "flavour": "svelte",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": 0,
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "bff-admin",
+      "target": "lint",
+      "flavour": "nest",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "bff-admin",
+      "target": "typescript",
+      "flavour": "nest",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "react-app",
+      "target": "lint",
+      "flavour": "react",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "react-app",
+      "target": "typescript",
+      "flavour": "react",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    },
+    {
+      "project": "utils",
+      "target": "lint",
+      "flavour": "node",
+      "ok": true,
+      "status": "ok",
+      "adopted": false
+    },
+    {
+      "project": "utils",
+      "target": "typescript",
+      "flavour": "node",
+      "ok": true,
+      "status": "ok",
+      "errors": 0,
+      "implicitAny": "deferred",
+      "diagnostics": [],
+      "diagnosticsTruncated": false
+    }
+  ]
+}
+```
+
+**--report --json on a module with 2 errors (structured diagnostics)** (stdout only, the JSON envelope)
+
+```json
+$ sentinel --report --typescript --module bff-admin --json 2>/dev/null
+{
+  "schemaVersion": 2,
+  "executed": [
+    "typescript"
+  ],
+  "skipped": [],
+  "results": [
+    {
+      "project": "bff-admin",
+      "target": "typescript",
+      "flavour": "nest",
+      "ok": false,
+      "status": "failed",
+      "errors": 2,
+      "implicitAny": "deferred",
+      "diagnostics": [
+        {
+          "file": "src/__probe__.ts",
+          "line": 1,
+          "col": 7,
+          "code": "TS2322",
+          "message": "Type 'string' is not assignable to type 'number'."
+        },
+        {
+          "file": "src/__probe__.ts",
+          "line": 2,
+          "col": 7,
+          "code": "TS2322",
+          "message": "Type 'number' is not assignable to type 'string'."
+        }
+      ],
+      "diagnosticsTruncated": false
+    }
+  ]
+}
+```
+
+**--max-diagnostics 1 (cap; full count kept, truncated flagged)** (stdout only, the JSON envelope)
+
+```json
+$ sentinel --report --typescript --module bff-admin --json --max-diagnostics 1 2>/dev/null
+{
+  "schemaVersion": 2,
+  "executed": [
+    "typescript"
+  ],
+  "skipped": [],
+  "results": [
+    {
+      "project": "bff-admin",
+      "target": "typescript",
+      "flavour": "nest",
+      "ok": false,
+      "status": "failed",
+      "errors": 2,
+      "implicitAny": "deferred",
+      "diagnostics": [
+        {
+          "file": "src/__probe__.ts",
+          "line": 1,
+          "col": 7,
+          "code": "TS2322",
+          "message": "Type 'string' is not assignable to type 'number'."
+        }
+      ],
+      "diagnosticsTruncated": true
+    }
+  ]
+}
+```
+
+## 4. Configuration results: what `--init` writes
+
+### 4a. Pattern B (React app, tsconfig.app.json extends the base, carries drift)
+
+_before: tsconfig.app.json_
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "strict": true, "jsx": "react-jsx", "paths": { "@/*": ["./src/*"] } }
+}
+```
+
+**dry-run plan**
+
+```console
+$ sentinel --init --typescript --dry-run
+  dry run: no files written
+  stripped preset-owned compilerOptions: strict, jsx
+  run `pnpm install` to fetch @hublo/sentinel (added to the module devDependencies) so `extends` and the typecheck script resolve
+
+  update tsconfig.app.json
+      {
+    -   "extends": "../../tsconfig.base.json",
+    -   "compilerOptions": { "strict": true, "jsx": "react-jsx", "paths": { "@/*": ["./src/*"] } }
+    +   "extends": [
+    +     "../../tsconfig.base.json",
+    +     "@hublo/sentinel/tsconfig/react"
+    +   ],
+    +   "compilerOptions": {
+    +     "paths": {
+    +       "@/*": [
+    +         "./src/*"
+    +       ]
+    +     }
+    +   }
+      }
+
+  update package.json
+    - { "name": "app", "dependencies": { "react": "^19" } }
+    + {
+    +   "name": "app",
+    +   "dependencies": {
+    +     "react": "^19"
+    +   },
+    +   "scripts": {
+    +     "typecheck": "sentinel --run --typescript"
+    +   },
+    +   "devDependencies": {
+    +     "@hublo/sentinel": "1.1.0-alpha.3"
+    +   }
+    + }
+# exit: 0
+```
+
+_after: base kept, preset appended, preset-owned keys stripped, paths kept_
+
+```json
+{
+  "extends": [
+    "../../tsconfig.base.json",
+    "@hublo/sentinel/tsconfig/react"
+  ],
+  "compilerOptions": {
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    }
+  }
+}
+```
+
+### 4b. No tsconfig (detected node): creates one
+
+_after: created tsconfig.json_
+
+```json
+{
+  "extends": "@hublo/sentinel/tsconfig/node",
+  "include": [
+    "src"
+  ]
+}
+```
+
+### 4c. project.json only, no package.json: scaffolds a package.json
+
+_after: scaffolded package.json_
+
+```json
+{
+  "name": "projonly",
+  "private": true,
+  "scripts": {
+    "typecheck": "sentinel --run --typescript"
+  },
+  "devDependencies": {
+    "@hublo/sentinel": "1.1.0-alpha.3"
+  }
+}
+```
+
+## 5. Edge cases (clear message + non-zero exit, never a crash or silent pass)
+
+**no verb**
+
+```console
+$ sentinel 
+Missing a verb. Supported: --run, --inspect, --init, --migrate, --report, --status.
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
+**two verbs**
+
+```console
+$ sentinel --run --report
+Pick exactly one verb: got --run, --report.
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
+**unknown flag**
+
+```console
+$ sentinel --run --lnt
+error: unknown option '--lnt'
+(Did you mean --lint?)
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
+**explicit unsupported target**
+
+```console
+$ sentinel --run --typescript --lint --module bff-admin
+sentinel lint(oxlint): no .oxlintrc.json in this module; run `sentinel --init --lint` to adopt.
+sentinel typescript: phase 1 (non-breaking) — deferred: noImplicitAny, noUnusedLocals, noUnusedParameters. Enabled centrally in a later wave; run `sentinel --inspect --typescript` for the list, or `sentinel --run --typescript -- --noImplicitAny` to measure what one would cost today.
+  ✓ bff-admin (nest) lint
+  ✓ bff-admin (nest) typescript
+  1 module(s) [named-module] in <n>ms
+# exit: 0
+```
+
+**--all with a target**
+
+```console
+$ sentinel --report --all --typescript
+--all runs every target; drop the specific one(s): --typescript.
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
+**--dry-run without --init**
+
+```console
+$ sentinel --run --typescript --dry-run --module bff-admin
+--dry-run only applies to --init (the read verbs never write).
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
+**unknown --preset**
+
+```console
+$ sentinel --init --typescript --preset reactt
+sentinel: unknown --preset "reactt". Supported: react, nest, svelte, node.
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
+**unknown --module**
+
+```console
+$ sentinel --report --typescript --module nope
+
+sentinel: module "nope" not found in the workspace.
+# exit: 1
+```
+
+**preset with no preset yet (writes nothing, so it FAILS rather than looking adopted)**
+
+```console
+$ sentinel --init --typescript --preset svelte
+sentinel (typescript): sentinel does not ship a TypeScript preset named "svelte" yet (shipped: nest, node, react). Nothing was written; this module cannot adopt the TypeScript preset until that preset ships.
+# exit: 1
+```
+
+**bad --max-diagnostics**
+
+```console
+$ sentinel --report --typescript --max-diagnostics 3.9 --module bff-admin
+--max-diagnostics must be a non-negative integer (0 = no cap); got "3.9".
+(run "sentinel --help" for usage)
+# exit: 1
+```
+
+**--init implicit-all (no flood)**
+
+```console
+$ sentinel --init --dry-run
+  dry run: no files written
+  wrote .oxlintrc.json extending ./node_modules/@hublo/sentinel/oxlint/nest.json (@hublo/sentinel@1.1.0-alpha.3)
+  2 rule(s) not enforced by this preset (1 no-barrel-files, 1 core). Run --inspect --lint for each rule and why.
+  run `pnpm install`, then `pnpm run lint`
+
+  create .oxlintrc.json
+    + {
+    +   "extends": [
+    +     "./node_modules/@hublo/sentinel/oxlint/nest.json"
+    +   ]
+    + }
+
+  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": "1.1.0-alpha.3"
+    +   }
+    + }
+
+  update project.json
+    - { "name": "bff-admin", "root": "apps/bff-admin", "projectType": "application", "sourceRoot": "apps/bff-admin/src" }
+    + {
+    +   "name": "bff-admin",
+    +   "root": "apps/bff-admin",
+    +   "projectType": "application",
+    +   "sourceRoot": "apps/bff-admin/src",
+    +   "targets": {
+    +     "lint": {
+    +       "executor": "nx:run-commands",
+    +       "cache": true,
+    +       "inputs": [
+    +         "default",
+    +         "{projectRoot}/.oxlintrc.json"
+    +       ],
+    +       "options": {
+    +         "cwd": "{projectRoot}",
+    +         "command": "pnpm run lint"
+    +       }
+    +     }
+    +   }
+    + }
+  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/tsconfig/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": "1.1.0-alpha.3"
+    +   }
+    + }
+# exit: 0
+```
+
+**no module and no workspace root**
+
+```console
+$ sentinel --run --typescript
+
+sentinel: Run sentinel from a module directory or the workspace root (found neither package.json/project.json nor nx.json here).
+# exit: 1
+```
+
+**ambiguous preset (Sails + React)**
+
+```console
+$ sentinel --report --typescript
+sentinel: --report is deprecated, use --run --json (it still works)
+sentinel: mixed: preset is ambiguous, detected "react" (from react), also found sails. Pass --preset to be explicit.
+  ✓ mixed (react) typescript — errors=0 implicitAny=deferred
+  1 module(s) [cwd-module] in <n>ms
+# exit: 0
+```
+
+---
+_Generated. Regenerate with `pnpm build && bash scripts/gen-traces.sh`._