@hublo/sentinel 1.1.0-alpha.2 → 1.1.0-alpha.4

package/dist/bin/sentinel.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import {
-  FLAVOURS,
+  PRESET_NAMES,
   TARGETS,
   VERBS,
   availableTargets,
@@ -14,7 +14,7 @@ import {
   registerAdapters,
   resolve,
   resolveBin
-} from "../chunk-EZCRU6XE.js";
+} from "../chunk-FLLX5MN3.js";
 
 // bin/sentinel.ts
 import { program } from "commander";
@@ -115,17 +115,17 @@ async function analyse(params) {
   let worstCode = 0;
   let done = 0;
   for (const module of params.modules) {
-    let flavour2;
-    if (params.flavour) {
-      flavour2 = params.flavour;
+    let preset2;
+    if (params.preset) {
+      preset2 = params.preset;
     } else {
       const detection = describeFramework(readProjectPackageJson(module.root));
-      flavour2 = detection.flavour;
+      preset2 = detection.preset;
       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.`
+            `sentinel: ${module.name}: preset is ambiguous, detected "${preset2}" (from ${detection.source}), also found ${detection.conflicts.join(", ")}. Pass --preset to be explicit.`
           ) + "\n"
         );
       }
@@ -133,14 +133,14 @@ async function analyse(params) {
     for (const target of params.targets) {
       let adapter;
       try {
-        adapter = resolve(target, flavour2, params.runner);
+        adapter = resolve(target, preset2, params.runner);
       } catch (error) {
         if (params.targetsExplicit) {
           const reason = error instanceof Error ? error.message : String(error);
           results.push({
             project: module.name,
             target,
-            flavour: flavour2,
+            flavour: preset2,
             ok: false,
             status: "unsupported",
             data: { reason }
@@ -148,14 +148,15 @@ async function analyse(params) {
         }
         continue;
       }
-      const effectiveFlavour = params.flavour ?? adapter.declaredFlavour?.(module.root) ?? flavour2;
+      const effectiveFlavour = params.preset ?? adapter.declaredPreset?.(module.root) ?? preset2;
       const ctx = {
         module: module.name,
         cwd: module.root,
-        flavour: effectiveFlavour,
+        preset: effectiveFlavour,
         ci: params.ci,
         fix: params.fix,
-        maxDiagnostics: params.maxDiagnostics
+        maxDiagnostics: params.maxDiagnostics,
+        toolArgs: params.toolArgs
       };
       try {
         if (params.verb === "run") {
@@ -189,15 +190,20 @@ async function analyse(params) {
           });
           worstCode = Math.max(worstCode, result.code);
         } else if (params.verb === "inspect") {
-          const config = await adapter.inspect(ctx);
+          const [config, adoption] = await Promise.all([adapter.inspect(ctx), adapter.status(ctx)]);
+          const ok = !adoption.adopted || adoption.conformant;
           results.push({
             project: module.name,
             target,
             flavour: effectiveFlavour,
-            ok: true,
-            status: "ok",
-            data: config
+            ok,
+            status: ok ? "ok" : "failed",
+            // `inspect` is typed as `unknown` (each role shapes its own detail), so the
+            // merge is guarded rather than assumed: a role returning a non-object still
+            // gets its adoption fields instead of throwing here.
+            data: config && typeof config === "object" ? { ...config, ...adoption } : { ...adoption }
           });
+          if (!ok) worstCode = Math.max(worstCode, 1);
         } else {
           const status = await adapter.status(ctx);
           const ok = !status.adopted || status.conformant;
@@ -229,9 +235,9 @@ async function analyse(params) {
   return { results, worstCode };
 }
 function generateSummary(result) {
-  const { project, target, flavour: flavour2, ok, status, data } = result;
+  const { project, target, flavour, ok, status, data } = result;
   const details = data && typeof data === "object" ? data : { value: data };
-  return { project, target, flavour: flavour2, ok, status, ...details };
+  return { project, target, flavour, ok, status, ...details };
 }
 function generateSummaries(results, requestedTargets) {
   const available = new Set(availableTargets());
@@ -257,9 +263,14 @@ var HEAD_KEYS = /* @__PURE__ */ new Set([
   "diagnostics",
   "diagnosticsTruncated"
 ]);
-function isDeferredRules(value) {
+function isRuleList(value) {
   return Array.isArray(value) && value.every((entry) => typeof entry === "object" && entry !== null && "rule" in entry);
 }
+var RULE_BLOCKS = [
+  { key: "deferred", label: "deferred (phase 1, non-breaking):" },
+  { key: "disabled", label: "not enforced, by decision:" },
+  { key: "downgraded", label: "reported, but not blocking:" }
+];
 function renderValue(key, value, p) {
   if ((key === "errors" || key === "implicitAny") && typeof value === "number") {
     return value > 0 ? p.fail(String(value)) : p.ok(String(value));
@@ -277,14 +288,26 @@ function renderSummary(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}`;
-  const entries = Object.entries(item).filter(([key]) => !HEAD_KEYS.has(key));
-  const deferred = entries.find(([key]) => key === "deferred")?.[1];
-  const inline = entries.filter(([key]) => key !== "deferred").map(([key, value]) => `${p.dim(`${key}=`)}${renderValue(key, value, p)}`).join(" ");
+  const unadopted = item.adopted === false;
+  const entries = Object.entries(item).filter(
+    ([key]) => !HEAD_KEYS.has(key) && !(unadopted && (key === "conformant" || key === "drift"))
+  );
+  const blocks = RULE_BLOCKS.map((block) => ({
+    ...block,
+    rules: entries.find(([key]) => key === block.key)?.[1]
+  })).filter((block) => isRuleList(block.rules));
+  const blockKeys = new Set(blocks.map((block) => block.key));
+  const inline = entries.map(([key, value]) => [
+    key,
+    blockKeys.has(key) && isRuleList(value) ? value.length : value
+  ]).map(([key, value]) => `${p.dim(`${key}=`)}${renderValue(key, value, p)}`).join(" ");
   const lines = [inline ? `${head} ${p.dim("\u2014")} ${inline}` : head];
-  if (isDeferredRules(deferred) && deferred.length > 0) {
-    lines.push(`      ${p.warn("deferred (phase 1, non-breaking):")}`);
-    for (const { rule, phase, reason } of deferred) {
-      lines.push(`        ${p.warn("\u2022")} ${p.strong(rule)} ${p.dim(`\u2014 phase ${phase}: ${reason}`)}`);
+  for (const { label, rules } of blocks) {
+    if (rules.length === 0) continue;
+    lines.push(`      ${p.warn(label)}`);
+    for (const { rule, phase, reason } of rules) {
+      const detail = phase === void 0 ? reason : `phase ${phase}: ${reason}`;
+      lines.push(`        ${p.warn("\u2022")} ${p.strong(rule)} ${p.dim(`\u2014 ${detail}`)}`);
     }
   }
   return lines.join("\n");
@@ -300,8 +323,8 @@ function statusCoverage(items) {
     drifted: adopted.length - conformant.length
   };
 }
-function presetShort(preset) {
-  return typeof preset === "string" ? preset.replace("@hublo/sentinel/tsconfig/", "") : "?";
+function presetShort(preset2) {
+  return typeof preset2 === "string" ? preset2.replace("@hublo/sentinel/tsconfig/", "") : "?";
 }
 function renderStatusRow(item, p) {
   if (item.status === "unsupported") return renderUnsupportedRow(item, p);
@@ -414,6 +437,9 @@ if (!nodeCheck.ok) {
   process.exit(1);
 }
 registerAdapters();
+var separator = process.argv.indexOf("--");
+var toolArgs = separator === -1 ? [] : process.argv.slice(separator + 1);
+var cliArgv = separator === -1 ? process.argv : process.argv.slice(0, separator);
 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",
   [
@@ -424,23 +450,28 @@ program.name("sentinel").description("One CLI that guards code health: presets,
     "          --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("--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(
+).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", "deprecated: use --run --json").option("--status", "deprecated: use --inspect").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 (--init)").option("--json", "machine-readable JSON output (report/inspect/--dry-run)").option(
+).option("--preset <name>", `the stack preset to apply (${PRESET_NAMES.join(", ")})`).option("--flavour <name>", "deprecated: use --preset").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 output, for every verb").option(
   "--max-diagnostics <n>",
   "cap the diagnostics embedded per module in --report (0 = no cap)",
   "100"
+).addHelpText(
+  "after",
+  "\n  -- <tool options>      --run only, one type: pass the rest to the tool itself\n                         e.g. -- --noImplicitAny (tsc), -- --deny-warnings (oxlint)"
 ).addHelpText(
   "after",
   [
     "",
     "Examples:",
     "  sentinel --run --typescript                        # in a module \u2192 that module",
-    "  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 --init --typescript --flavour react       # set up the current module + workspace"
+    "  sentinel --run --typescript --module bff-admin     # from root \u2192 one module",
+    "  sentinel --run --json                              # from root \u2192 all types, machine output",
+    "  sentinel --run --ci                                # from root \u2192 affected only",
+    "  sentinel --inspect --typescript                    # from root \u2192 adoption + what is deferred",
+    "  sentinel --init --typescript --preset react       # set up the current module + workspace",
+    "  sentinel --run --typescript -- --noImplicitAny     # ask the tool a question of your own"
   ].join("\n")
 ).addHelpText("after", () => {
   const available = availableTargets();
@@ -450,7 +481,7 @@ program.name("sentinel").description("One CLI that guards code health: presets,
     `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();
+}).parse(cliArgv);
 var opts = program.opts();
 function toCamel(flag) {
   return flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -467,9 +498,9 @@ function pickOne(kind, keys) {
 }
 function parseFlavour(value) {
   if (value === void 0) return void 0;
-  if (typeof value !== "string" || !FLAVOURS.includes(value)) {
+  if (typeof value !== "string" || !PRESET_NAMES.includes(value)) {
     return program.error(
-      `sentinel: unknown --flavour ${JSON.stringify(value)}. Supported: ${FLAVOURS.join(", ")}.`
+      `sentinel: unknown --preset ${JSON.stringify(value)}. Supported: ${PRESET_NAMES.join(", ")}.`
     );
   }
   return value;
@@ -479,7 +510,16 @@ function asMessage(err) {
 }
 var verb = pickOne("verb", VERBS);
 var cwd = process.cwd();
-var flavour = parseFlavour(opts.flavour);
+if (opts.preset !== void 0 && opts.flavour !== void 0) {
+  program.error("--preset and --flavour are the same option; pass only --preset.");
+}
+if (opts.flavour !== void 0) {
+  process.stderr.write(
+    `${palette(process.stderr).warn("sentinel: --flavour is deprecated, use --preset")} (it still works)
+`
+  );
+}
+var preset = parseFlavour(opts.preset ?? opts.flavour);
 var namedTargets = TARGETS.filter((t) => opts[toCamel(t)]);
 if (opts.all && namedTargets.length > 0) {
   program.error(
@@ -497,28 +537,52 @@ if (!Number.isInteger(maxDiagnostics) || maxDiagnostics < 0) {
 if (opts.dryRun && verb !== "init") {
   program.error("--dry-run only applies to --init (the read verbs never write).");
 }
+if (toolArgs.length > 0) {
+  if (verb !== "run") {
+    program.error(
+      `options after \`--\` are passed to the tool, so they only apply to --run; --${verb} does not run one (--inspect reads the committed config, --init writes it). Try: sentinel --run --<target> -- ${toolArgs.join(" ")}`
+    );
+  }
+  if (targets.length !== 1) {
+    program.error(
+      `options after \`--\` go to ONE tool, so name one target. You asked for ${targets.length === TARGETS.length ? "all targets" : targets.map((t) => `--${t}`).join(", ")}, and \`${toolArgs.join(" ")}\` cannot be meaningful to every one of them. Try: sentinel --run --typescript -- ${toolArgs.join(" ")}`
+    );
+  }
+}
 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") {
+  const shaped = verb === "run" && opts.json ? "report" : verb;
+  const replacement = {
+    report: "--run --json",
+    status: "--inspect"
+  };
+  const instead = replacement[verb];
+  if (instead) {
+    process.stderr.write(
+      err.warn(`sentinel: --${verb} is deprecated, use ${instead}`) + " (it still works)\n"
+    );
+  }
+  if (toolArgs.length > 0) {
     process.stderr.write(
       err.warn(
-        "note: --json is ignored for --run (it streams the tool output); use --report --json for a machine envelope."
+        `sentinel: NOT the standard check \u2014 passing ${toolArgs.join(" ")} to the ${targets[0]} tool.`
       ) + "\n"
     );
   }
   const started = Date.now();
   const { results, worstCode } = await analyse({
-    verb,
+    verb: shaped,
     targets,
     modules,
     runner: opts.runner,
-    flavour,
+    preset,
     targetsExplicit,
     maxDiagnostics,
     ci: Boolean(opts.ci),
     fix: Boolean(opts.fix),
+    toolArgs,
     // Per-module progress is a HUMAN affordance: it tells someone staring at a slow sweep
     // that it is alive. On this monorepo's 441 projects it is 441 lines that bury the four
     // that matter, and it is pure noise in a captured log. So emit it only for an
@@ -528,10 +592,11 @@ async function runVerb() {
 `)) : void 0
   });
   const summary = generateSummaries(results, targets);
-  if (opts.json && verb !== "run") {
-    const payload = verb === "status" ? { ...summary, coverage: statusCoverage(summary.results) } : summary;
+  if (opts.json) {
+    const base = verb === "status" || verb === "inspect" ? { ...summary, coverage: statusCoverage(summary.results) } : summary;
+    const payload = toolArgs.length > 0 ? { ...base, toolArgs } : base;
     process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-  } else if (verb === "status") {
+  } else if (verb === "status" || verb === "inspect" && modules.length > 1) {
     for (const item of summary.results) process.stdout.write(renderStatusRow(item, out) + "\n");
     process.stdout.write(renderStatusSummary(summary.results, out) + "\n");
   } else {
@@ -580,7 +645,7 @@ async function runInit() {
         target: type,
         runner: opts.runner,
         cwd: module.root,
-        flavour,
+        preset,
         dryRun: Boolean(opts.dryRun),
         json: Boolean(opts.json)
       });
@@ -608,18 +673,24 @@ sentinel (${type}): ${asMessage(err)}
   }
   return worst;
 }
+async function exitWithoutTruncating(code) {
+  process.exitCode = code;
+  const stream = process.stdout;
+  if (stream.write("")) return;
+  await new Promise((resolve2) => stream.once("drain", () => resolve2()));
+}
 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);
+  await exitWithoutTruncating(exitCode);
 }
 main().catch((error) => {
   process.stderr.write(`
 sentinel: ${asMessage(error)}
 `);
-  process.exit(1);
+  void exitWithoutTruncating(1);
 });
 //# sourceMappingURL=sentinel.js.map