@hublo/sentinel 0.1.0-alpha.8 → 1.0.0

package/dist/bin/sentinel.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 import {
-  detectFramework,
+  availableTargets,
+  describeFramework,
   dispatch,
   palette,
   readNxProjectName,
+  readOwnPackage,
   readOwnVersion,
   readProjectPackageJson,
   registerAdapters,
   resolve,
   resolveBin
-} from "../chunk-UG74KTIU.js";
+} from "../chunk-HKGCWPRT.js";
 
 // bin/sentinel.ts
 import { program } from "commander";
@@ -105,7 +107,7 @@ function resolveContext(cwd2, opts2) {
 }
 
 // src/core/domain.ts
-var VERBS = ["run", "inspect", "update", "report", "status"];
+var VERBS = ["run", "inspect", "init", "migrate", "report", "status"];
 var TARGETS = [
   "lint",
   "format",
@@ -124,19 +126,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 +178,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 +194,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 +239,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 +274,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 +300,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 +314,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,21 +332,116 @@ function renderStatusSummary(items, p) {
   return `  ${p.strong("coverage:")} ${c.adopted}/${c.total} adopted ${p.dim("\xB7")} ${c.conformant}/${c.adopted} conformant${drift}`;
 }
 
+// src/core/workspace-prep.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { dirname, join as join3 } from "path";
+var OVERRIDE_KEY = "i18next>typescript";
+var NATIVE_TS_ALIAS = "@typescript/native";
+var WORKSPACE_YAML = "pnpm-workspace.yaml";
+var RELEASE_AGE_KEY = "minimumReleaseAgeExclude";
+var LIST_ITEM = /^(\s*)-\s+(.*?)\s*$/;
+function findWorkspaceRoot(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    if (existsSync2(join3(dir, WORKSPACE_ROOT_MARKER))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+function declaredNativeTs(pkg) {
+  const spec = pkg.dependencies?.[NATIVE_TS_ALIAS] ?? pkg.devDependencies?.[NATIVE_TS_ALIAS];
+  if (!spec) return void 0;
+  const version = spec.slice(spec.lastIndexOf("@") + 1).replace(/^[\^~>=<\s]+/, "");
+  return version || void 0;
+}
+function ensureI18nextSingleton(root, dryRun) {
+  const pkgPath = join3(root, "package.json");
+  if (!existsSync2(pkgPath)) return void 0;
+  const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
+  const want = declaredNativeTs(pkg);
+  if (!want) return void 0;
+  const have = pkg.pnpm?.overrides?.[OVERRIDE_KEY];
+  if (have === want) return void 0;
+  if (dryRun) return `would pin ${OVERRIDE_KEY} to ${want} (i18next singleton)`;
+  pkg.pnpm ??= {};
+  pkg.pnpm.overrides ??= {};
+  pkg.pnpm.overrides[OVERRIDE_KEY] = want;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  return `pinned ${OVERRIDE_KEY} to ${want} in package.json (i18next singleton)`;
+}
+function ensureReleaseAgeAllowList(root, dryRun) {
+  const yamlPath = join3(root, WORKSPACE_YAML);
+  if (!existsSync2(yamlPath)) return void 0;
+  const own = readOwnPackage().name;
+  const lines = readFileSync2(yamlPath, "utf8").split("\n");
+  const keyIdx = lines.findIndex((line) => line.replace(/\s+$/, "") === `${RELEASE_AGE_KEY}:`);
+  if (keyIdx === -1) return void 0;
+  let lastItemIdx = keyIdx;
+  let indent = "  ";
+  for (let i = keyIdx + 1; i < lines.length; i++) {
+    const match = lines[i]?.match(LIST_ITEM);
+    if (!match) break;
+    indent = match[1] ?? indent;
+    lastItemIdx = i;
+    if ((match[2] ?? "").replace(/^['"]|['"]$/g, "") === own) return void 0;
+  }
+  if (dryRun) return `would allow-list ${own} under ${RELEASE_AGE_KEY}`;
+  lines.splice(lastItemIdx + 1, 0, `${indent}- '${own}'`);
+  writeFileSync(yamlPath, lines.join("\n"));
+  return `allow-listed ${own} under ${RELEASE_AGE_KEY} in ${WORKSPACE_YAML}`;
+}
+function ensureWorkspacePrep(opts2) {
+  const dryRun = Boolean(opts2.dryRun);
+  return [
+    ensureI18nextSingleton(opts2.root, dryRun),
+    ensureReleaseAgeAllowList(opts2.root, dryRun)
+  ].filter((message) => message !== void 0);
+}
+
+// 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  --status  --update",
+    "  verb    what to do:   --run  --inspect  --report  --status  --init  (--migrate: planned)",
     "  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.",
+    "          --ci (affected), or all modules. --init 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("--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(
+).option("--run", "execute the target tool").option("--inspect", "show the resolved configuration").option("--init", "set up a module: write its config stubs + the workspace prep it needs").option("--migrate", "planned: change an already-initialized setup (not available yet)").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 (--init)").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",
   [
     "",
@@ -271,9 +450,17 @@ program.name("sentinel").description("One CLI that guards code health: presets,
     "  sentinel --report --typescript --module bff-admin  # from root \u2192 one module",
     "  sentinel --report                                  # from root \u2192 all types, all modules",
     "  sentinel --report --ci                             # from root \u2192 affected only",
-    "  sentinel --update --typescript --flavour react     # write stubs for the current module"
+    "  sentinel --init --typescript --flavour react       # set up the current module + workspace"
   ].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,13 +497,27 @@ if (opts.all && namedTargets.length > 0) {
   );
 }
 var targets = opts.all || namedTargets.length === 0 ? [...TARGETS] : namedTargets;
-if (opts.dryRun && verb !== "update") {
-  program.error("--dry-run only applies to --update (the read verbs never write).");
+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 !== "init") {
+  program.error("--dry-run only applies to --init (the read verbs never write).");
 }
 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 +525,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,28 +548,44 @@ 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() {
+async function runInit() {
   const { modules, scope } = resolveContext(cwd, { module: opts.module, ci: false });
   const [module] = modules;
   if (scope === "all" || scope === "affected" || !module) {
     program.error(
-      "--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."
+      "--init 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,16 +594,36 @@ async function runUpdate() {
       process.stderr.write(`
 sentinel (${type}): ${asMessage(err)}
 `);
-      if (targets.length === 1) return 1;
       worst = Math.max(worst, 1);
     }
   }
+  if (worst === 0) {
+    const root = findWorkspaceRoot(module.root);
+    if (root) {
+      const changes = ensureWorkspacePrep({ root, dryRun: Boolean(opts.dryRun) });
+      const prefix = opts.dryRun ? "  dry run: " : "  ";
+      for (const change of changes) process.stderr.write(`${prefix}${change}
+`);
+      if (changes.length > 0 && !opts.dryRun) {
+        process.stderr.write(
+          palette(process.stderr).dim("  run `pnpm install` to apply the workspace changes\n")
+        );
+      }
+    }
+  }
   return worst;
 }
-registerAdapters();
-(verb === "update" ? runUpdate() : runVerb()).then((code) => process.exit(code)).catch((err) => {
+async function main() {
+  if (verb === "migrate") {
+    program.error("--migrate is planned and not available yet; use --init to set a module up.");
+  }
+  const runSelectedVerb = verb === "init" ? runInit : runVerb;
+  const exitCode = await runSelectedVerb();
+  process.exit(exitCode);
+}
+main().catch((error) => {
   process.stderr.write(`
-sentinel: ${asMessage(err)}
+sentinel: ${asMessage(error)}
 `);
   process.exit(1);
 });