@hublo/sentinel 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -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
@@ -99,6 +101,18 @@ 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.
+
 ## Architecture: `target → runner → flavour`
 
 Every check is described by three layers:
@@ -244,6 +258,7 @@ sentinel <verb> [type] [options]
 VERBS      --run       execute the target's tool
            --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)
 
 TYPES      --lint  --format  --typescript  --build  --test
@@ -259,17 +274,33 @@ OPTIONS    --module <name>    from the root: scope to one module
            --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 --report --ci                             # from root  → affected (CI)
+           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` 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).
+`--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).
+
+**`--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
 
@@ -293,8 +324,7 @@ 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. Shipped today:

package/dist/bin/sentinel.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
-  detectFramework,
+  availableTargets,
+  describeFramework,
   dispatch,
   palette,
   readNxProjectName,
@@ -9,7 +10,7 @@ import {
   registerAdapters,
   resolve,
   resolveBin
-} from "../chunk-G7NVAZSZ.js";
+} from "../chunk-NQ7GNHFT.js";
 
 // bin/sentinel.ts
 import { program } from "commander";
@@ -105,7 +106,7 @@ function resolveContext(cwd2, opts2) {
 }
 
 // src/core/domain.ts
-var VERBS = ["run", "inspect", "update", "report"];
+var VERBS = ["run", "inspect", "update", "report", "status"];
 var TARGETS = [
   "lint",
   "format",
@@ -124,19 +125,45 @@ async function analyse(params) {
   let worstCode = 0;
   let done = 0;
   for (const module of params.modules) {
-    const flavour2 = params.flavour ?? detectFramework(readProjectPackageJson(module.root));
+    let flavour2;
+    if (params.flavour) {
+      flavour2 = params.flavour;
+    } else {
+      const detection = describeFramework(readProjectPackageJson(module.root));
+      flavour2 = detection.flavour;
+      if (detection.ambiguous) {
+        const warn = palette(process.stderr);
+        process.stderr.write(
+          warn.warn(
+            `sentinel: ${module.name}: flavour is ambiguous, detected "${flavour2}" (from ${detection.source}), also found ${detection.conflicts.join(", ")}. Pass --flavour to be explicit.`
+          ) + "\n"
+        );
+      }
+    }
     const ctx = {
       module: module.name,
       cwd: module.root,
       flavour: flavour2,
       ci: params.ci,
-      fix: params.fix
+      fix: params.fix,
+      maxDiagnostics: params.maxDiagnostics
     };
     for (const target of params.targets) {
       let adapter;
       try {
         adapter = resolve(target, flavour2, params.runner);
-      } catch {
+      } catch (error) {
+        if (params.targetsExplicit) {
+          const reason = error instanceof Error ? error.message : String(error);
+          results.push({
+            project: module.name,
+            target,
+            flavour: flavour2,
+            ok: false,
+            status: "unsupported",
+            data: { reason }
+          });
+        }
         continue;
       }
       try {
@@ -150,7 +177,14 @@ async function analyse(params) {
             );
           }
           const result = await adapter.run(ctx);
-          results.push({ project: module.name, target, flavour: flavour2, ok: result.ok, data: {} });
+          results.push({
+            project: module.name,
+            target,
+            flavour: flavour2,
+            ok: result.ok,
+            status: result.ok ? "ok" : "failed",
+            data: {}
+          });
           worstCode = Math.max(worstCode, result.code);
         } else if (params.verb === "report") {
           const result = await adapter.report(ctx);
@@ -159,16 +193,43 @@ async function analyse(params) {
             target,
             flavour: flavour2,
             ok: result.ok,
+            status: result.ok ? "ok" : "failed",
             data: result.metrics ?? {}
           });
           worstCode = Math.max(worstCode, result.code);
-        } else {
+        } else if (params.verb === "inspect") {
           const config = await adapter.inspect(ctx);
-          results.push({ project: module.name, target, flavour: flavour2, ok: true, data: config });
+          results.push({
+            project: module.name,
+            target,
+            flavour: flavour2,
+            ok: true,
+            status: "ok",
+            data: config
+          });
+        } else {
+          const status = await adapter.status(ctx);
+          const ok = !status.adopted || status.conformant;
+          results.push({
+            project: module.name,
+            target,
+            flavour: flavour2,
+            ok,
+            status: ok ? "ok" : "failed",
+            data: status
+          });
+          if (!ok) worstCode = Math.max(worstCode, 1);
         }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        results.push({ project: module.name, target, flavour: flavour2, ok: false, data: { error: message } });
+        results.push({
+          project: module.name,
+          target,
+          flavour: flavour2,
+          ok: false,
+          status: "failed",
+          data: { error: message }
+        });
         worstCode = Math.max(worstCode, 1);
       }
     }
@@ -177,16 +238,34 @@ async function analyse(params) {
   return { results, worstCode };
 }
 function generateSummary(result) {
-  const { project, target, flavour: flavour2, ok, data } = result;
+  const { project, target, flavour: flavour2, ok, status, data } = result;
   const details = data && typeof data === "object" ? data : { value: data };
-  return { project, target, flavour: flavour2, ok, ...details };
+  return { project, target, flavour: flavour2, ok, status, ...details };
 }
-function generateSummaries(results) {
-  return { schemaVersion: 1, results: results.map(generateSummary) };
+function generateSummaries(results, requestedTargets) {
+  const available = new Set(availableTargets());
+  return {
+    schemaVersion: 2,
+    executed: requestedTargets.filter((t) => available.has(t)),
+    skipped: requestedTargets.filter((t) => !available.has(t)),
+    results: results.map(generateSummary)
+  };
 }
 
 // src/core/render.ts
-var HEAD_KEYS = /* @__PURE__ */ new Set(["project", "module", "target", "flavour", "ok"]);
+var HEAD_KEYS = /* @__PURE__ */ new Set([
+  "project",
+  "module",
+  "target",
+  "flavour",
+  "ok",
+  "status",
+  "reason",
+  // The structured diagnostics are for `--json` consumers; the human row stays the concise
+  // `errors=N` line rather than dumping every diagnostic inline.
+  "diagnostics",
+  "diagnosticsTruncated"
+]);
 function isDeferredRules(value) {
   return Array.isArray(value) && value.every((entry) => typeof entry === "object" && entry !== null && "rule" in entry);
 }
@@ -194,9 +273,16 @@ function renderValue(key, value, p) {
   if ((key === "errors" || key === "implicitAny") && typeof value === "number") {
     return value > 0 ? p.fail(String(value)) : p.ok(String(value));
   }
+  if (key === "implicitAny" && value === "deferred") return p.warn("deferred");
   return typeof value === "string" ? value : JSON.stringify(value);
 }
+function renderUnsupportedRow(item, p) {
+  const reason = typeof item.reason === "string" ? ` ${p.dim(`(${item.reason})`)}` : "";
+  const head = `  ${p.dim("\xB7")} ${p.strong(String(item.project))} ${p.dim(`(${item.flavour})`)} ${item.target}`;
+  return `${head} ${p.dim("\u2014")} ${p.warn("unsupported")}${reason}`;
+}
 function renderSummary(item, p) {
+  if (item.status === "unsupported") return renderUnsupportedRow(item, p);
   const ok = item.ok === true;
   const mark = ok ? p.ok("\u2713") : p.fail("\u2717");
   const head = `  ${mark} ${p.strong(String(item.project))} ${p.dim(`(${item.flavour})`)} ${item.target}`;
@@ -212,22 +298,82 @@ function renderSummary(item, p) {
   }
   return lines.join("\n");
 }
+function statusCoverage(items) {
+  const relevant = items.filter((i) => i.status !== "unsupported");
+  const adopted = relevant.filter((i) => i.adopted === true);
+  const conformant = adopted.filter((i) => i.conformant === true);
+  return {
+    total: relevant.length,
+    adopted: adopted.length,
+    conformant: conformant.length,
+    drifted: adopted.length - conformant.length
+  };
+}
+function presetShort(preset) {
+  return typeof preset === "string" ? preset.replace("@hublo/sentinel/tsconfig/", "") : "?";
+}
+function renderStatusRow(item, p) {
+  if (item.status === "unsupported") return renderUnsupportedRow(item, p);
+  const adopted = item.adopted === true;
+  const conformant = item.conformant === true;
+  const mark = !adopted ? p.dim("\xB7") : conformant ? p.ok("\u2713") : p.fail("\u2717");
+  const head = `  ${mark} ${p.strong(String(item.project))} ${p.dim(`(${item.flavour})`)} ${item.target}`;
+  if (!adopted) return `${head} ${p.dim("\u2014 not adopted")}`;
+  if (conformant) {
+    return `${head} ${p.dim("\u2014")} ${p.ok("adopted")} ${p.dim(`(${presetShort(item.preset)}) conformant`)}`;
+  }
+  const drift = Array.isArray(item.drift) ? item.drift.join(", ") : "";
+  return `${head} ${p.dim("\u2014")} ${p.ok("adopted")} ${p.dim(`(${presetShort(item.preset)})`)} ${p.fail(`drift: ${drift}`)}`;
+}
+function renderStatusSummary(items, p) {
+  const c = statusCoverage(items);
+  const drift = c.drifted > 0 ? p.fail(` \xB7 ${c.drifted} drifted`) : "";
+  return `  ${p.strong("coverage:")} ${c.adopted}/${c.total} adopted ${p.dim("\xB7")} ${c.conformant}/${c.adopted} conformant${drift}`;
+}
+
+// src/shared/node-version.ts
+var MIN_NODE = "20.12.0";
+function parts(version) {
+  const [major = 0, minor = 0, patch = 0] = version.replace(/^v/, "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+  return [major, minor, patch];
+}
+function checkNodeVersion(current, min = MIN_NODE) {
+  const [cMajor, cMinor, cPatch] = parts(current);
+  const [mMajor, mMinor, mPatch] = parts(min);
+  const ok = cMajor > mMajor || cMajor === mMajor && cMinor > mMinor || cMajor === mMajor && cMinor === mMinor && cPatch >= mPatch;
+  if (ok) return { ok: true };
+  return {
+    ok: false,
+    message: `sentinel requires Node >= ${min}, but you are on ${current}. Switch with fnm/nvm (e.g. \`fnm use ${mMajor}\`) and re-run.`
+  };
+}
 
 // bin/sentinel.ts
+var nodeCheck = checkNodeVersion(process.versions.node);
+if (!nodeCheck.ok) {
+  process.stderr.write(`${nodeCheck.message}
+`);
+  process.exit(1);
+}
+registerAdapters();
 program.name("sentinel").description("One CLI that guards code health: presets, analysis, and arch checks.").version(readOwnVersion()).configureHelp({ sortOptions: false }).showSuggestionAfterError(true).showHelpAfterError('(run "sentinel --help" for usage)').addHelpText(
   "before",
   [
     "A check composes: verb + type + location.",
-    "  verb    what to do:   --run  --inspect  --report  --update",
+    "  verb    what to do:   --run  --inspect  --report  --status  --update",
     "  type    which check:  --lint --typescript ...  (omit = all types; or --all)",
     "  where   run from a MODULE dir \u2192 that module; from the ROOT \u2192 --module <name>,",
     "          --ci (affected), or all modules. --update targets one module only.",
     ""
   ].join("\n")
-).option("--run", "execute the target tool").option("--inspect", "show the resolved configuration").option("--update", "generate/apply the config stubs").option("--report", "metrics and health report").option("--lint", "linting").option("--format", "formatting").option("--typescript", "type checking").option("--build", "build").option("--test", "tests").option("--static-analysis", "cycles, complexity, duplication, centrality").option("--runtime-analysis", "bundle, Lighthouse, web vitals").option("--arch", "architecture boundaries").option("--all", "every target").option(
+).option("--run", "execute the target tool").option("--inspect", "show the resolved configuration").option("--update", "generate/apply the config stubs").option("--report", "metrics and health report").option("--status", "adoption + conformity across modules (coverage + drift)").option("--lint", "linting").option("--format", "formatting").option("--typescript", "type checking").option("--build", "build").option("--test", "tests").option("--static-analysis", "cycles, complexity, duplication, centrality").option("--runtime-analysis", "bundle, Lighthouse, web vitals").option("--arch", "architecture boundaries").option("--all", "every target").option(
   "--module <name>",
   "from the workspace root: scope to one module (omit = all; inside a module dir, drop this)"
-).option("--flavour <name>", `override the detected stack preset (${FLAVOURS.join(", ")})`).option("--runner <tool>", "override the default runner (e.g. eslint, biome)").option("--ci", "CI mode: from the root, only the affected modules; non-zero exit on failure").option("--fix", "auto-fix where applicable").option("--dry-run", "preview the changes without writing (--update)").option("--json", "machine-readable JSON output (report/inspect/--dry-run)").addHelpText(
+).option("--flavour <name>", `override the detected stack preset (${FLAVOURS.join(", ")})`).option("--runner <tool>", "override the default runner (e.g. eslint, biome)").option("--ci", "CI mode: from the root, only the affected modules; non-zero exit on failure").option("--fix", "auto-fix where applicable").option("--dry-run", "preview the changes without writing (--update)").option("--json", "machine-readable JSON output (report/inspect/--dry-run)").option(
+  "--max-diagnostics <n>",
+  "cap the diagnostics embedded per module in --report (0 = no cap)",
+  "100"
+).addHelpText(
   "after",
   [
     "",
@@ -238,7 +384,15 @@ program.name("sentinel").description("One CLI that guards code health: presets,
     "  sentinel --report --ci                             # from root \u2192 affected only",
     "  sentinel --update --typescript --flavour react     # write stubs for the current module"
   ].join("\n")
-).parse();
+).addHelpText("after", () => {
+  const available = availableTargets();
+  const planned = TARGETS.filter((t) => !available.includes(t));
+  return [
+    "",
+    `Available now: ${available.length ? available.map((t) => `--${t}`).join(", ") : "(none yet)"}`,
+    planned.length ? `Planned (ship in later tickets): ${planned.map((t) => `--${t}`).join(", ")}` : ""
+  ].filter(Boolean).join("\n");
+}).parse();
 var opts = program.opts();
 function toCamel(flag) {
   return flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -275,6 +429,13 @@ if (opts.all && namedTargets.length > 0) {
   );
 }
 var targets = opts.all || namedTargets.length === 0 ? [...TARGETS] : namedTargets;
+var targetsExplicit = !(opts.all || namedTargets.length === 0);
+var maxDiagnostics = Number(opts.maxDiagnostics);
+if (!Number.isInteger(maxDiagnostics) || maxDiagnostics < 0) {
+  program.error(
+    `--max-diagnostics must be a non-negative integer (0 = no cap); got ${JSON.stringify(opts.maxDiagnostics)}.`
+  );
+}
 if (opts.dryRun && verb !== "update") {
   program.error("--dry-run only applies to --update (the read verbs never write).");
 }
@@ -282,6 +443,13 @@ async function runVerb() {
   const { modules, scope } = resolveContext(cwd, { module: opts.module, ci: Boolean(opts.ci) });
   const out = palette(process.stdout);
   const err = palette(process.stderr);
+  if (opts.json && verb === "run") {
+    process.stderr.write(
+      err.warn(
+        "note: --json is ignored for --run (it streams the tool output); use --report --json for a machine envelope."
+      ) + "\n"
+    );
+  }
   const started = Date.now();
   const { results, worstCode } = await analyse({
     verb,
@@ -289,14 +457,20 @@ async function runVerb() {
     modules,
     runner: opts.runner,
     flavour,
+    targetsExplicit,
+    maxDiagnostics,
     ci: Boolean(opts.ci),
     fix: Boolean(opts.fix),
     onProgress: (done, total, name) => process.stderr.write(err.dim(`  [${done}/${total}] ${name}
 `))
   });
-  const summary = generateSummaries(results);
+  const summary = generateSummaries(results, targets);
   if (opts.json && verb !== "run") {
-    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+    const payload = verb === "status" ? { ...summary, coverage: statusCoverage(summary.results) } : summary;
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  } else if (verb === "status") {
+    for (const item of summary.results) process.stdout.write(renderStatusRow(item, out) + "\n");
+    process.stdout.write(renderStatusSummary(summary.results, out) + "\n");
   } else {
     for (const item of summary.results) {
       process.stdout.write(renderSummary(item, out) + "\n");
@@ -306,6 +480,15 @@ async function runVerb() {
     err.dim(`  ${modules.length} module(s) [${scope}] in ${Date.now() - started}ms
 `)
   );
+  if (targetsExplicit && summary.skipped.length > 0) {
+    const avail = availableTargets();
+    process.stderr.write(
+      err.fail(
+        `sentinel: target(s) not available yet: ${summary.skipped.map((t) => `--${t}`).join(", ")}. Available now: ${avail.length ? avail.map((t) => `--${t}`).join(", ") : "(none yet)"}.`
+      ) + "\n"
+    );
+    return 1;
+  }
   return verb === "run" || opts.ci ? worstCode : 0;
 }
 async function runUpdate() {
@@ -316,18 +499,25 @@ async function runUpdate() {
       "--update writes files: target one module (run from its directory, or pass --module). Adopting every module at once is intentionally not allowed \u2014 adopt gradually."
     );
   }
+  const available = availableTargets();
+  if (targetsExplicit) {
+    const unwired = targets.filter((type) => !available.includes(type));
+    if (unwired.length > 0) {
+      program.error(
+        `target(s) not available yet: ${unwired.map((t) => `--${t}`).join(", ")}. Available now: ${available.map((t) => `--${t}`).join(", ") || "(none yet)"}.`
+      );
+    }
+  }
+  const toRun = targets.filter((type) => available.includes(type));
   let worst = 0;
-  for (const type of targets) {
+  for (const type of toRun) {
     try {
       const code = await dispatch({
         verb,
         target: type,
         runner: opts.runner,
-        module: module.name,
         cwd: module.root,
         flavour,
-        ci: Boolean(opts.ci),
-        fix: Boolean(opts.fix),
         dryRun: Boolean(opts.dryRun),
         json: Boolean(opts.json)
       });
@@ -336,13 +526,11 @@ async function runUpdate() {
       process.stderr.write(`
 sentinel (${type}): ${asMessage(err)}
 `);
-      if (targets.length === 1) return 1;
       worst = Math.max(worst, 1);
     }
   }
   return worst;
 }
-registerAdapters();
 (verb === "update" ? runUpdate() : runVerb()).then((code) => process.exit(code)).catch((err) => {
   process.stderr.write(`
 sentinel: ${asMessage(err)}