@hublo/sentinel 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -4,7 +4,7 @@
 
 `sentinel` is a standalone, semver-versioned package (published to a registry, consumed by a repo as a normal dependency) that unifies a repo's tooling, config, and quality checks into one place, so projects stop copying config files everywhere and stop carrying a pile of duplicated tooling dependencies.
 
-> Status: **scaffold / design**. This README is the design reference; tools are implemented one at a time on top of this foundation.
+> Status: **foundation + the TypeScript tool are shipped** (`@hublo/sentinel@0.1.0-alpha.x` on npm). The rest of this README is the design reference for the tools still to come, added one at a time on top of this foundation.
 
 ---
 
@@ -43,6 +43,8 @@ A large monorepo accumulates:
 
 sentinel writes **standard config files** into a project (each just `extends` a sentinel preset) and runs the checks. Your editor and the tools read those **normal files natively**, they never call sentinel at runtime, so nothing is coupled to it or brittle.
 
+> **Shipped today:** only the **TypeScript** tool, so `--update` writes the `tsconfig` stub, and `--run`/`--report`/`--status` work for `--typescript`. The `eslint.config.js` / `--lint` / `--test` snippets below illustrate the end state; those subpaths (`@hublo/sentinel/lint/*`, …) land with their tool ticket.
+
 **Step 1 — put a module on sentinel** (once per module, by a dev; the files are committed):
 
 ```bash
@@ -59,14 +61,17 @@ export default react
 ```
 
 ```jsonc
-// tsconfig.json — extends the preset; only project-specific paths/include stay local
+// tsconfig.json — COMPOSES the repo base with the sentinel preset (see "Composition
+// & precedence"); only project-specific paths/include stay local
 {
-  "extends": "@hublo/sentinel/typescript/react",
+  "extends": ["../../tsconfig.base.json", "@hublo/sentinel/tsconfig/react"],
   "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } },
   "include": ["src"]
 }
 ```
 
+> A module can extend the preset alone (`"extends": "@hublo/sentinel/tsconfig/react"`) when there is no repo base. Compose with the base when the repo owns structure (a monorepo `paths` map) the preset should not, see "Composition & precedence".
+
 And the app's `package.json` scripts route every check through the one CLI (run from the app dir, sentinel scopes to it):
 
 ```jsonc
@@ -96,6 +101,23 @@ And the app's `package.json` scripts route every check through the one CLI (run
 
 The per-tool knowledge (eslint → `eslint.config.js`, tsc → `tsconfig`, …) lives **inside sentinel as an adapter**, swappable centrally, but never a runtime dependency of the project.
 
+## Requirements & installing
+
+**Node.** sentinel needs **Node >= 20.12** (its coloured output uses `util.styleText`, added in 20.12). It fails fast with a clear message on an older runtime rather than crashing. If a project runs on an older Node (e.g. a legacy app on Node 10), run sentinel with a modern Node via `fnm`/`nvm`; you do not need to change the project's own Node.
+
+**Try it without installing.** A one-off run needs no auth and touches nothing:
+
+```bash
+pnpm dlx @hublo/sentinel@<exact-version> --inspect --typescript --module <name>
+```
+
+**Installing a pre-release (`minimumReleaseAge`).** The monorepo enforces a 3-day `minimumReleaseAge` supply-chain gate (a freshly published version cannot be installed until it has aged 3 days). A brand-new `alpha` therefore cannot be added yet, so while testing pre-releases you either exclude the package (`pnpm-workspace.yaml` → `minimumReleaseAgeExclude`) or install with `--config.minimumReleaseAge=0`. This is a deliberate protection, not a bug: **always pin the exact version** (`@hublo/sentinel@0.1.0-alpha.9`) rather than `@latest`, so a run is reproducible and the gate stays meaningful.
+
+## Docs & cheat sheets
+
+- [`docs/typescript-adoption.md`](docs/typescript-adoption.md) — the adoption cheat sheet: the two adoption steps, the command model (verb x type x location), options, reading a report, and troubleshooting.
+- [`docs/typescript-traces.md`](docs/typescript-traces.md) — a **generated, versioned** reference of live command + output traces (every verb, option, config result and edge case) against the mock monorepo. Regenerate after CLI changes with `pnpm docs:traces`.
+
 ## Architecture: `target → runner → flavour`
 
 Every check is described by three layers:
@@ -104,12 +126,12 @@ Every check is described by three layers:
 | -------------------- | --------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
 | **target** (role)    | `--lint`, `--typescript`, … | the _kind_ of check, stable                 | `lint` `format` `typescript` `build` `test` `static-analysis` `runtime-analysis`       |
 | **runner** (adapter) | `--runner=<tool>`           | the _tool_ behind the target, swappable     | lint: `eslint`/`biome`/`oxlint` · types: `tsc`/`tsgo` · build: `vite` · test: `vitest` |
-| **flavour** (preset) | declared                    | the _variant_ per stack (strict by default) | `react` `nest` `svelte` `node`                                                         |
+| **flavour** (preset) | detected / `--flavour`      | the _variant_ per stack (strict by default) | `react` `nest` `node` (svelte declared, preset deferred)                               |
 
 A run is `target × runner × flavour`, e.g. `sentinel --run --lint --runner=eslint` from the `host-admin` dir.
 
 - `--runner` is an **optional override on a central default**. `sentinel --lint` uses the configured default runner, so swapping a tool globally is a one-place change; `--runner=biome` overrides for a single run (great for benchmarking eslint vs biome vs oxlint, and for gradual migration).
-- The **flavour is declared, never detected.** Once a project is on sentinel, its committed config already says which preset (`extends '@hublo/sentinel/lint/react'`), so `--run`/`--report` don't need a flag, the tool reads that config. `--update`/`--inspect` take it explicitly with `--flavour` (the first `--update` is where you declare it). sentinel never guesses the stack, so a Nest app can't be silently treated as React.
+- The **flavour is detected** from the module's dependencies (deterministic: a framework dep → its flavour, else `node`), and **`--flavour` overrides it**. Detection can be wrong where deps are hoisted at the repo root (it returns `node`), so pass `--flavour` for `--update` (that is where the preset is chosen). `--run`/`--report` don't depend on it, they run the tool on the committed config.
 
 ### Adapters & the engine (ports & adapters)
 
@@ -174,30 +196,115 @@ The rules live in `sentinel`. Each module keeps a **thin, generated stub** per t
 - **Per-module install** — `@hublo/sentinel` is added per module, so adoption is **gradual** (migrate lot by lot; a module can adopt sentinel while its neighbour still uses the old config). Root configs are removed only once the **last** module has migrated.
 - **Runner binaries** (`eslint`, `typescript`, `vite`, `vitest`, …) are **peer dependencies** so they install once and stay resolvable by the editor + nx, while sentinel still dictates their versions.
 
+## Composition & precedence
+
+A repo often has a base config that is **structural**, not just tooling, e.g. a
+monorepo `tsconfig.base.json` carrying the workspace `paths` map. sentinel does **not**
+replace it; it **composes** with it, so the structure survives and sentinel owns the
+standards:
+
+```jsonc
+"extends": ["../../tsconfig.base.json", "@hublo/sentinel/tsconfig/react"]
+```
+
+**Precedence — sentinel wins.** With array `extends` (TS 5.0), entries merge in order
+and the **last one wins**; the module's own `compilerOptions` win over both. So it is
+always **base → sentinel → module-local**. sentinel is listed **last on purpose**:
+it is a **reference** (a source of truth), not a suggestion the base can silently
+veto. For any option sentinel declares, sentinel's value is the effective one.
+
+For a module composing the base, the resolved config (`tsc --showConfig`) looks like:
+
+| Option                        | Effective value      | Owner                                      |
+| ----------------------------- | -------------------- | ------------------------------------------ |
+| `strict`, `jsx`, decorators   | preset's             | **sentinel** (quality + framework)         |
+| `module` / `moduleResolution` | `esnext` / `bundler` | **sentinel**                               |
+| `target` / `lib` / `paths`    | the repo's           | **base** (environment; sentinel won't set) |
+| `noImplicitAny`               | **off** (phase 1)    | **base**, the preset defers it (see below) |
+
+- **sentinel owns quality + framework semantics** (`strict`, `jsx`, decorators, module
+  system). The base can never quietly undo those, which is what makes sentinel a
+  reliable reference.
+- **the base owns the environment** (`paths`, `target`, `lib`, project references).
+  sentinel does **not** set these, `extends` REPLACES arrays rather than merging, so
+  overriding `lib`/`target` would drop the repo's DOM libs or flip class-field emit.
+
+**Least astonishment / phased strictness.** So a reference doesn't turn every rule on
+the instant a module adopts it, sentinel **phases** the rules that would surface new
+errors (`noImplicitAny`, `noUnusedLocals`, `noUnusedParameters`). They are kept
+**commented** in the preset (visible, never silently dropped) and announced by a
+runtime **warning**. `strict` stays on (so a standalone consumer still gets
+`noImplicitAny`), but a repo base that relaxes `noImplicitAny` keeps it off until that
+relaxation is removed. First adoption is therefore a **non-breaking lateral move**;
+the rules are enabled **centrally** in a later wave.
+
+**Removing the base is two decoupled moves, and neither loses quality:**
+
+1. **Compose** (`extends: [base, preset]`). Quality flips to sentinel **immediately**,
+   because it wins. The base's own tooling options are still present but now **dead
+   config** (overridden).
+2. **Slim the base later** to structure only (`paths` + references). This moves nothing
+   quality-wise, sentinel already won in step 1, so it is safe. The base is never fully
+   removed while it still owns `paths`.
+
+**The discipline this demands:** sentinel must **explicitly declare every quality
+option it means to own.** An option sentinel forgets to set falls through to the base,
+a silent gap in the reference. (Be deliberate with array/replace options like `types`:
+setting them **overrides** the base's rather than merging, so only own them when you
+mean to.)
+
 ## CLI
 
+A command **composes** three axes: **verb + type + location**.
+
 ```
-sentinel <verb> <target> [options]
+sentinel <verb> [type] [options]
 
 VERBS      --run       execute the target's tool
-           --inspect   show the resolved configuration
-           --update    generate/apply the config stubs
+           --inspect   show the resolved configuration (incl. deferred rules)
            --report    metrics and health
+           --status    adoption + conformity (coverage + drift), read from configs
+           --update    generate/apply the config stubs (writes; one module only)
 
-TARGETS    --lint  --format  --typescript  --build  --test
-           --static-analysis  --runtime-analysis  --arch  --all
+TYPES      --lint  --format  --typescript  --build  --test
+           --static-analysis  --runtime-analysis  --arch
+           (omit a type → ALL types; or --all)
 
-OPTIONS    --module <name>    scope to a module (planned; run sentinel from the module dir for now)
-           --flavour <name>   stack preset, declared not detected (react, nest, ...)
+LOCATION   in a MODULE dir      → that module (do NOT pass --module)
+           at the workspace ROOT → --module <name> (one) · --ci (affected) · else all
+
+OPTIONS    --module <name>    from the root: scope to one module
+           --flavour <name>   override the detected stack preset (react, nest, ...)
            --runner <tool>    override the default runner
-           --ci               non-zero exit on failure
+           --ci               from the root: affected only; non-zero exit on failure
            --fix              auto-fix where applicable
+           --dry-run          preview a --update without writing
+           --json             machine-readable output (report / inspect / status / --dry-run)
+
+EXAMPLES   sentinel --run --typescript                        # in a module → that module
+           sentinel --report --typescript --module bff-admin  # from root  → one module
+           sentinel --report                                  # from root  → all types, all modules
+           sentinel --status --typescript                     # from root  → adoption coverage
+           sentinel --status --ci                             # from root  → fail CI on drift
+           sentinel --update --typescript --flavour react     # write stubs for the current module
+```
+
+`--run`/`--inspect`/`--report`/`--status` share one context rule (developer from a
+module, or from the root for a name / affected / all); `--update` writes, so it targets
+one module only (adopting every module at once is refused, adopt gradually).
 
-EXAMPLES   (run from the app directory)
-           sentinel --run --typescript
-           sentinel --update --lint --flavour react
-           sentinel --run --lint --runner=oxlint
-           sentinel --report --all --ci
+**`--status` — adoption + conformity.** A cheap, workspace-wide read (no tool run, no
+flavour guessing): for each module it reads the committed `tsconfig` `extends` chain and
+reports whether it is **adopted** (extends a sentinel preset), which preset, and whether
+it is **conformant** (drift-free, a re-`update` would change nothing), plus a coverage
+footer. This is the **drift guard** as a command, `--status --ci` exits non-zero when an
+adopted module has drifted.
+
+```
+  ✓ host-admin (react) typescript — adopted (react) conformant
+  ✗ some-bff   (nest)  typescript — adopted (nest) drift: strict, target
+  · legacy-app (node)  typescript — not adopted
+  coverage: 12/40 adopted · 11/12 conformant · 1 drifted
 ```
 
 ## Repository layout
@@ -222,11 +329,12 @@ src/
     runners/                 # one runner per sub-tool (duplication, complexity, ...)
   shared/                    # reusable utils (package-json, deep-merge, text)
 tests/                       # unit tests + tests/e2e (runs the built dist binary)
-.changeset/                  # release notes
-.github/workflows/           # ci.yml (PR checks) + release.yml (changesets publish)
+.github/workflows/           # ci.yml (PR checks) + publish.yml (manual, version-input publish)
 ```
 
-Subpath exports (in `package.json`) expose presets to consumers, e.g. `@hublo/sentinel/lint/react`, `@hublo/sentinel/typescript/nest`.
+Subpath exports (in `package.json`) expose presets to consumers. Shipped today:
+`@hublo/sentinel/tsconfig/react` · `.../tsconfig/nest` · `.../tsconfig/node`. Other
+subpaths (e.g. `.../lint/react`) land with their tool ticket.
 
 ## FAQ
 
@@ -252,8 +360,8 @@ nx is a **task runner**: it just runs the target's script. So `project.json` bar
 
 This scaffold is the foundation; each tool is added one at a time on top of it:
 
-1. **Foundation** — repo, exports, CLI skeleton, adapter contract, changesets, CI/release. _(this scaffold)_
-2. **TypeScript** (`--typescript`, CI gate) — runner `tsc`, later `tsgo`.
+1. **Foundation** — repo, exports, CLI skeleton, adapter contract, changesets, CI/release. **✅ shipped**
+2. **TypeScript** (`--typescript`) — runner `tsc` (later `tsgo`): presets react/nest/node, `--run`/`--inspect`/`--report`/`--update`, the composable grid, phased (non-breaking) strictness. **✅ shipped in `0.1.0-alpha.x`**
 3. **Lint** (`--lint`) — benchmark `eslint` vs `biome` vs `oxlint`.
 4. **Build** (`--build`) — `vite`.
 5. **Test** (`--test`) — `vitest`, plus a11y / w3c setups.