@hublo/sentinel 0.1.0-alpha.8 → 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:
@@ -260,6 +274,7 @@ 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
@@ -309,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-UG74KTIU.js";
+} from "../chunk-NQ7GNHFT.js";
 
 // bin/sentinel.ts
 import { program } from "commander";
@@ -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,21 +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 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, data: status });
+          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);
       }
     }
@@ -182,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);
 }
@@ -199,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}`;
@@ -218,10 +299,11 @@ function renderSummary(item, p) {
   return lines.join("\n");
 }
 function statusCoverage(items) {
-  const adopted = items.filter((i) => i.adopted === true);
+  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: items.length,
+    total: relevant.length,
     adopted: adopted.length,
     conformant: conformant.length,
     drifted: adopted.length - conformant.length
@@ -231,6 +313,7 @@ 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");
@@ -248,7 +331,31 @@ function renderStatusSummary(items, p) {
   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",
   [
@@ -262,7 +369,11 @@ program.name("sentinel").description("One CLI that guards code health: presets,
 ).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",
   [
     "",
@@ -273,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());
@@ -310,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).");
 }
@@ -317,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,
@@ -324,12 +457,14 @@ 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") {
     const payload = verb === "status" ? { ...summary, coverage: statusCoverage(summary.results) } : summary;
     process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
@@ -345,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() {
@@ -355,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)
       });
@@ -375,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)}