@hublo/sentinel 1.2.0-alpha.1 → 1.2.0-alpha.11

package/README.md

@@ -151,7 +151,7 @@ pnpm dlx @hublo/sentinel@<exact-version> --inspect --typescript --module <name>
 - [`docs/using-sentinel.md`](docs/using-sentinel.md) — every verb for every role, scoping a run to some files, what a fully adopted module looks like, and how versions move between modules.
 - [`docs/lint-adoption.md`](docs/lint-adoption.md) — migrating a module from ESLint to Oxlint: the two steps, what `--init` writes and removes, the two react tiers, and the failures worth recognising.
 - [`docs/format-adoption.md`](docs/format-adoption.md) — migrating a module from Prettier to oxfmt: why this config is materialized rather than a stub, how a module keeps its own formatting, and what did not survive the move.
-- [`docs/build-adoption.md`](docs/build-adoption.md) — moving a React app's Vite toolchain into sentinel: what the config becomes, what sentinel owns versus what stays the app's, why overriding merges instead of spreading, and why an existing config is not rewritten.
+- [`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/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`.
 
@@ -161,7 +161,7 @@ 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` `test` `static-analysis` `runtime-analysis`                                                                             |
+| **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) |
 

package/dist/bin/sentinel.d.ts

@@ -1 +1,6 @@
 #!/usr/bin/env node
+import '@tailwindcss/vite';
+import '@vitejs/plugin-react';
+import 'nitro/vite';
+import 'vite-plugin-svgr';
+import 'vite';

package/dist/bin/sentinel.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  LONG_RUNNING_TARGETS,
   PRESET_NAMES,
   PresetUnsupportedError,
   SWEEPABLE_TARGETS,
@@ -7,28 +8,28 @@ import {
   VERBS,
   WORKSPACE_ROOT_MARKER,
   availableTargets,
+  buildConfigFile,
   declaredPresetFor,
   describeFramework,
   dispatch,
   ensureWorkspacePrep,
   findWorkspaceRoot,
   inspectWorkspacePrep,
+  moduleName,
   palette,
-  readNxProjectName,
   readOwnVersion,
   readProjectPackageJson,
   registerAdapters,
   resolve,
   resolveBin
-} from "../chunk-FLJ2QNFF.js";
-import "../chunk-XVDOQ3G3.js";
+} from "../chunk-6VOQDDZD.js";
 
 // bin/sentinel.ts
 import { program } from "commander";
 
 // src/core/context.ts
 import { existsSync } from "fs";
-import { basename, join as join2 } from "path";
+import { join as join2 } from "path";
 
 // src/core/discover-modules.ts
 import { execFileSync } from "child_process";
@@ -96,7 +97,7 @@ function resolveContext(cwd2, opts2) {
     if (opts2.ci) {
       throw new Error("--ci selects the affected set from the workspace root; run it there.");
     }
-    const name = readNxProjectName(cwd2) ?? basename(cwd2);
+    const name = moduleName(cwd2);
     return { modules: [{ name, root: cwd2 }], scope: "cwd-module" };
   }
   if (atRoot) {
@@ -113,6 +114,30 @@ function resolveContext(cwd2, opts2) {
   );
 }
 
+// src/roles/build/declined.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join3 } from "path";
+var DEPRECATED_NX_BUILDER = "@nx/webpack:webpack";
+function buildsWithDeprecatedExecutor(cwd2) {
+  const projectJson = join3(cwd2, "project.json");
+  if (!existsSync2(projectJson)) return false;
+  try {
+    const project = JSON.parse(readFileSync2(projectJson, "utf8"));
+    return project.targets?.build?.executor === DEPRECATED_NX_BUILDER;
+  } catch {
+    return false;
+  }
+}
+function explainDecline(cwd2) {
+  if (buildConfigFile(cwd2) !== void 0) {
+    return ` This module HAS a Vite config, so detection is the likely problem: the build toolchain is declared at the workspace root, which makes a front app detect as "node". Pass --preset to say what it is.`;
+  }
+  if (buildsWithDeprecatedExecutor(cwd2)) {
+    return ` This module still builds through ${DEPRECATED_NX_BUILDER}, which Nx v24 removes. It has no Vite config yet, so there is nothing for --build to adopt: add one that imports @hublo/sentinel/build/nest, then run this again. See docs/build-adoption.md.`;
+  }
+  return ` This module has neither a Vite config nor an Nx build target, so it builds nothing and --build is out of scope for it. Nothing was written, and nothing is wrong.`;
+}
+
 // src/cli/run-init.ts
 function asMessage(error) {
   return error instanceof Error ? error.message : String(error);
@@ -151,9 +176,10 @@ async function runInit(ctx) {
     } catch (error) {
       if (error instanceof PresetUnsupportedError) {
         if (ctx.targetsExplicit) {
+          const hint = type === "build" ? explainDecline(module.root) : ` Pass --preset if it was detected wrongly (hoisted dependencies make detection fall back to "node").`;
           process.stderr.write(
             `
-sentinel (${type}): this module's preset is "${error.preset}", and --${type} has no adapter for it. Pass --preset if it was detected wrongly (hoisted dependencies make detection fall back to "node").
+sentinel (${type}): this module's preset is "${error.preset}", and --${type} has no adapter for it.${hint}
 `
           );
           worst = Math.max(worst, 1);
@@ -463,6 +489,15 @@ async function runVerb(ctx) {
   const { modules, scope } = resolveContext(ctx.cwd, { module: ctx.module, ci: ctx.ci });
   const out = palette(process.stdout);
   const err = palette(process.stderr);
+  const longRunning = ctx.targets.filter((target) => LONG_RUNNING_TARGETS.includes(target));
+  if (longRunning.length > 0 && modules.length > 1) {
+    process.stderr.write(
+      err.fail(
+        `sentinel: ${longRunning.map((t) => `--${t}`).join(", ")} starts a server that does not return, so it runs against ONE module. This resolved to ${modules.length} [${scope}]. Run it from inside the module's directory, or pass --module <name>.`
+      ) + "\n"
+    );
+    return 1;
+  }
   const shaped = ctx.verb === "run" && ctx.json ? "report" : ctx.verb;
   const replacement = {
     report: "--run --json",
@@ -579,6 +614,17 @@ 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);
+var TARGET_HELP = {
+  lint: "linting",
+  format: "formatting",
+  typescript: "type checking",
+  build: "build",
+  dev: "dev server (long-running: never swept by an unqualified --run)",
+  test: "tests",
+  "static-analysis": "cycles, complexity, duplication, centrality",
+  "runtime-analysis": "bundle, Lighthouse, web vitals",
+  arch: "architecture boundaries"
+};
 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",
   [
@@ -589,7 +635,7 @@ 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", "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(
+).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(
   "--module <name>",
   "from the workspace root: scope to one module (omit = all; inside a module dir, drop this)"
 ).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(
@@ -621,7 +667,10 @@ 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(cliArgv);
+});
+for (const target of TARGETS) program.option(`--${target}`, TARGET_HELP[target]);
+program.option("--all", "every target");
+program.parse(cliArgv);
 var opts = program.opts();
 function toCamel(flag) {
   return flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());