@hublo/sentinel 1.5.0-alpha.36 → 1.5.0-alpha.37

package/README.md

@@ -171,20 +171,21 @@ throwaway run wants. Once a module has adopted, nothing is fetched any more: the
 - [`docs/build-adoption.md`](docs/build-adoption.md) — moving a React app's Vite toolchain into sentinel: adoption changes the config's IMPORTS and nothing else, what sentinel owns versus what stays the app's, and why reading nothing is what makes losing nothing a guarantee.
 - [`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/test-adoption.md`](docs/test-adoption.md) — migrating a module from jest to Vitest: the two steps, what the migration rewrites and what it refuses BY NAME, how the baseline gate proves nothing was lost, and the failures worth recognising.
-- [`docs/static-analysis-adoption.md`](docs/static-analysis-adoption.md) — running the static analysis role on a module: the two steps, the three output shapes, how to read each row and where its threshold comes from, declaring an entry point, and the two limits worth knowing before trusting a number.
+- [`docs/static-analysis-adoption.md`](docs/static-analysis-adoption.md) — running the static analysis role on a module: the two steps, the four output shapes, how to read each row and where its threshold comes from, declaring an entry point, and the two limits worth knowing before trusting a number.
 - [`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 → preset`
 
 Every check is described by three layers:
 
-| Layer                | Flag                        | What it is                                  | Examples                                                                                                                                                     |
-| -------------------- | --------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **target** (role)    | `--lint`, `--typescript`, … | the _kind_ of check, stable                 | `lint` `format` `typescript` `build` `dev` `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`                                                                       |
-| **preset** (preset)  | detected / `--preset`       | the _variant_ per stack (strict by default) | `react` `nest` `node` `svelte` (svelte: lint + format; no tsconfig preset yet, so the TypeScript role stands aside on those modules and the other two adopt) |
+| Layer                | Flag                        | What it is                                         | Examples                                                                                                                                                     |
+| -------------------- | --------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **target** (role)    | `--lint`, `--typescript`, … | the _kind_ of check, stable                        | `lint` `format` `typescript` `build` `dev` `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`                                                                       |
+| **shape** (output)   | `--output=<shape>`          | what a reporting role WRITES, not what it measures | `console` (default, writes nothing) `html` `json` `markdown`; roles that do not report ignore it                                                             |
+| **preset** (preset)  | detected / `--preset`       | the _variant_ per stack (strict by default)        | `react` `nest` `node` `svelte` (svelte: lint + format; no tsconfig preset yet, so the TypeScript role stands aside on those modules and the other two adopt) |
 
-A run is `target × runner × preset`, e.g. `sentinel --run --lint --runner=eslint` from the `host-admin` dir.
+A run is `target × runner × preset`, e.g. `sentinel --run --lint --runner=eslint` from the `host-admin` dir. The shape is not part of that identity: it decides what the run WRITES, not what it does.
 
 - `--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 **preset is detected** from the module's dependencies (deterministic: a framework dep → its preset, else `node`), and **`--preset` overrides it**. Detection can be wrong where deps are hoisted at the repo root (it returns `node`), so pass `--preset` for `--init` (that is where the preset is chosen). `--run`/`--report` don't depend on it, they run the tool on the committed config.

package/dist/bin/sentinel.js

@@ -15,7 +15,7 @@ import {
   palette,
   registerAdapters,
   resolve
-} from "../chunk-5HM2TYYC.js";
+} from "../chunk-HLRY2VHZ.js";
 import {
   resolveContext
 } from "../chunk-43HQ6BVJ.js";

package/dist/{chunk-5HM2TYYC.js → chunk-HLRY2VHZ.js}

@@ -5692,10 +5692,19 @@ async function loadStaticConfig(cwd) {
     return {
       config: defineStaticAnalysis(),
       from: null,
-      unreadable: `${STATIC_CONFIG_FILE}: ${error instanceof Error ? error.message : String(error)}`
+      unreadable: `${STATIC_CONFIG_FILE}: ${explainUnreadableConfig(error)}`
     };
   }
 }
+function explainUnreadableConfig(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error.code;
+  if (code !== "ERR_PACKAGE_PATH_NOT_EXPORTED" || !message.includes("@hublo/sentinel")) {
+    return message;
+  }
+  return `${message}
+  The @hublo/sentinel installed in this module does not ship the static-analysis role yet. Bump it to a release that does, then run this again. Until then the role runs on its defaults and this file is ignored, which is why it is reported rather than silently skipped.`;
+}
 function adopt(exported) {
   if (exported === null || typeof exported !== "object") return defineStaticAnalysis();
   if (Array.isArray(exported.moved)) {

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-5HM2TYYC.js";
+} from "./chunk-HLRY2VHZ.js";
 import {
   BaseAdapter
 } from "./chunk-43HQ6BVJ.js";

package/docs/using-sentinel.md

@@ -36,6 +36,12 @@ everywhere (`--run --json` and `--inspect` answer them), and `--migrate` is refu
 `--json` works for every verb, and stdout carries **only** the envelope, so `| jq` always
 parses. `--dry-run` applies to `--init` and writes nothing.
 
+`--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
+script, `markdown` is the six lines a workflow posts on a pull request. Today `--static-analysis`
+is the role that has them. ⚠️ `--output html` pays a graph layout the other three skip, which is
+fine for a page somebody opens and wrong for a commit hook.
+
 **`--validate` is a verb of its own**, and the proof of a migration lives there rather than on
 `--init` or `--run`. Run before a migration it records what the module does today; run after, it
 compares by test NAME and refuses a run that lost one or invented one. What separates it from

package/package.json

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