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

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 declare function registerAdapters(): void;
 
 /**
- * The domain vocabulary: the fixed sets of verbs, targets, and flavours, and the
+ * The domain vocabulary: the fixed sets of verbs, targets, and presets, and the
  * types derived from them. This is the model, and the extension point: adding a
- * verb / target / flavour is a one-line edit to a list here, and because the types
+ * verb / target / preset is a one-line edit to a list here, and because the types
  * are DERIVED (`(typeof LIST)[number]`), the compiler forces every switch/handler
  * to cover the new member.
  *
@@ -21,9 +21,15 @@ type Verb = (typeof VERBS)[number];
 /** Targets: the kind of check. The CLI `--<target>` flags map 1:1 to these. */
 declare const TARGETS: readonly ["lint", "format", "typescript", "build", "test", "static-analysis", "runtime-analysis", "arch"];
 type Target = (typeof TARGETS)[number];
-/** Flavours: the stack preset a project resolves to (strict by default). */
-declare const FLAVOURS: readonly ["react", "nest", "svelte", "node"];
-type Flavour = (typeof FLAVOURS)[number];
+/** Presets: the stack preset a project resolves to (strict by default). */
+declare const PRESET_NAMES: readonly ["react", "nest", "svelte", "node"];
+type PresetName = (typeof PRESET_NAMES)[number];
+/**
+ * @deprecated Renamed to `PresetName`. Kept so an existing `import type { Flavour }` keeps
+ * compiling: the CLI kept `--flavour` working for the same reason, and breaking the type
+ * while sparing the flag would be an odd place to draw the line.
+ */
+type Flavour = PresetName;
 
 /**
  * The adapter contract, as PURE types (no runtime). Every tool (eslint, biome,
@@ -38,15 +44,15 @@ type Flavour = (typeof FLAVOURS)[number];
 /**
  * Normalized context for `--init`, built and guaranteed by the engine. The
  * adapter TRUSTS this shape (no re-validation): `cwd` is the absolute module root,
- * `flavour` is resolved (explicit `--flavour`, else detected). The adapter may READ
+ * `preset` is resolved (explicit `--preset`, else detected). The adapter may READ
  * the module through bounded resolvers to plan, but never writes, the engine
  * applies the returned plan.
  */
 interface UpdateContext {
     /** Absolute path to the module root. */
     cwd: string;
-    /** The resolved, validated flavour. */
-    flavour: Flavour;
+    /** The resolved, validated preset. */
+    preset: PresetName;
 }
 /** Resolved context for a single `--run`/`--report` against one module. */
 interface RunContext {
@@ -54,8 +60,8 @@ interface RunContext {
     module: string;
     /** Absolute path to the module root. */
     cwd: string;
-    /** The resolved flavour (explicit `--flavour`, else detected). Guaranteed set. */
-    flavour: Flavour;
+    /** The resolved preset (explicit `--preset`, else detected). Guaranteed set. */
+    preset: PresetName;
     /** CI mode: adapters must exit non-zero on failure. */
     ci: boolean;
     /** Apply auto-fixes where the tool supports it. */
@@ -66,6 +72,22 @@ interface RunContext {
      * cap. Undefined lets the adapter use its default.
      */
     maxDiagnostics?: number;
+    /**
+     * Extra options for the underlying tool, taken verbatim from after `--` on the command
+     * line. Empty for a normal run.
+     *
+     * This is the "what would turning this on cost?" seam. A preset defers rules
+     * (`noImplicitAny`, `noUnusedLocals`, …) and `--inspect` reports them as deferred, which
+     * is honest but answers a question nobody asked: what a developer wants to know is how
+     * much debt is behind the deferral. Rather than sentinel modelling that question one flag
+     * at a time, `--run` forwards the tool's own options, so any question the tool can already
+     * answer is one command away.
+     *
+     * An adapter that honours these MUST make the result impossible to mistake for a standard
+     * check: these options can weaken a run as easily as strengthen it, and `--run` is what CI
+     * calls. The engine echoes them on stderr and carries them in the `--json` envelope.
+     */
+    toolArgs?: readonly string[];
 }
 /**
  * A single, DECLARATIVE file operation an `--init` wants to happen. Adapters
@@ -74,7 +96,7 @@ interface RunContext {
  *
  * The split matters: an adapter says WHAT and WHY (tool meaning); the engine does
  * the read/merge/write mechanics (format-agnostic plumbing). So an adapter stays
- * a pure function of the flavour, with no coupling to where files live.
+ * a pure function of the preset, with no coupling to where files live.
  */
 type FileOperation = 
 /** Create or replace a file the adapter fully owns (the thin stub). */
@@ -152,7 +174,7 @@ interface UpdatePlan {
     operations: FileOperation[];
     notes?: string[];
     /**
-     * Set when the adapter CANNOT set this module up at all (no preset for the flavour,
+     * Set when the adapter CANNOT set this module up at all (no preset for the preset,
      * a config chain it does not handle, …). The engine reports it as a FAILURE with a
      * non-zero exit, never as a silent success: `--init` that writes nothing must not
      * look like adoption to a person reading a log or to a script reading `$?`. Carries
@@ -171,7 +193,7 @@ interface AdapterResult {
 }
 /**
  * Adoption + conformity of one module for one target, for `--status`. Read from the
- * module's COMMITTED config (no tool run, no flavour guessing), so a workspace-wide
+ * module's COMMITTED config (no tool run, no preset guessing), so a workspace-wide
  * scan is a cheap coverage + drift dashboard.
  */
 interface StatusReport {
@@ -185,7 +207,7 @@ interface StatusReport {
     drift: string[];
 }
 /**
- * One tool implementation for one target (and, optionally, a subset of flavours,
+ * One tool implementation for one target (and, optionally, a subset of presets,
  * see `appliesTo`). The CLI verbs map onto these: `--run` -> run, `--inspect` ->
  * inspect, `--init` -> plan(+write), `--report` -> report, `--status` -> status.
  */
@@ -195,22 +217,22 @@ interface Adapter {
     /** The runner name, selectable via `--runner` (e.g. 'eslint'). */
     readonly runner: string;
     /**
-     * Whether this adapter handles the given flavour. Resolution filters candidates
+     * Whether this adapter handles the given preset. Resolution filters candidates
      * by this, so a React-only adapter is never picked for a Nest project, and two
-     * adapters can share a (target, runner) if they specialise different flavours.
+     * adapters can share a (target, runner) if they specialise different presets.
      */
-    appliesTo(flavour: Flavour): boolean;
+    appliesTo(preset: PresetName): boolean;
     /**
-     * The flavour this module has COMMITTED to, read from its own config, or undefined when
+     * The preset this module has COMMITTED to, read from its own config, or undefined when
      * it has not adopted a preset yet. Optional: an adapter implements it only when its tool's
-     * config states the flavour unambiguously.
+     * config states the preset unambiguously.
      *
      * The engine prefers this over dependency detection, because in a monorepo dependencies are
      * hoisted to the root: `host-admin` declares no `react`, so detection honestly answers
      * `node` while the committed `extends` says `.../tsconfig/react`. Reporting the detected
      * value there would show every adopted module as `node`, which is simply untrue.
      */
-    declaredFlavour?(cwd: string): Flavour | undefined;
+    declaredPreset?(cwd: string): PresetName | undefined;
     /**
      * Plan what `--init` should write, as declarative operations (see
      * `FileOperation`). Given a normalized `UpdateContext`, the adapter may READ the
@@ -246,7 +268,7 @@ interface Adapter {
 declare abstract class BaseAdapter implements Adapter {
     abstract readonly target: Target;
     abstract readonly runner: string;
-    abstract appliesTo(flavour: Flavour): boolean;
+    abstract appliesTo(preset: PresetName): boolean;
     abstract plan(context: UpdateContext): UpdatePlan | Promise<UpdatePlan>;
     abstract run(ctx: RunContext): Promise<AdapterResult>;
     inspect(_ctx: RunContext): Promise<unknown>;
@@ -256,11 +278,11 @@ declare abstract class BaseAdapter implements Adapter {
 
 /**
  * Framework detection from a module's package.json dependencies. DETERMINISTIC:
- * a dependency maps to exactly one flavour, and a module with no framework
+ * a dependency maps to exactly one preset, and a module with no framework
  * dependency is a plain TypeScript library (`node`). This is not the old silent
  * guessing (there is no "assume react" fallback); `node` is a real preset.
  *
- * Reusable across tools: every tool's `--init` needs the module's flavour to
+ * Reusable across tools: every tool's `--init` needs the module's preset to
  * pick its preset, so this lives in core, not in the TypeScript role.
  */
 
@@ -269,8 +291,8 @@ interface PackageDependencies {
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
 }
-/** The flavour for a module, from its dependencies. `node` when no framework. */
-declare function detectFramework(packageJson: PackageDependencies): Flavour;
+/** The preset for a module, from its dependencies. `node` when no framework. */
+declare function detectFramework(packageJson: PackageDependencies): PresetName;
 
 interface DispatchOptions {
     /** Always `init` (dispatch is the write path); other verbs route through `analyse`. */
@@ -278,8 +300,8 @@ interface DispatchOptions {
     target: Target;
     runner?: string;
     cwd: string;
-    /** Declared flavour (`--flavour`), else resolved by `detectFramework` from deps. */
-    flavour?: Flavour;
+    /** Declared preset (`--preset`), else resolved by `detectFramework` from deps. */
+    preset?: PresetName;
     /** `--dry-run`: preview the plan instead of writing anything. */
     dryRun?: boolean;
     /** `--json`: emit the dry-run preview as machine-readable JSON. */
@@ -289,18 +311,18 @@ declare function dispatch(opts: DispatchOptions): Promise<number>;
 
 /**
  * Adapter registry. Tool branches register their adapters here; the CLI resolves
- * an adapter by (target, flavour, runner). A default runner per target keeps the
+ * an adapter by (target, preset, runner). A default runner per target keeps the
  * common invocation tool-agnostic (`sentinel --lint`), while `--runner` overrides
- * it. Resolution is flavour-aware: candidates are filtered by `appliesTo(flavour)`,
+ * it. Resolution is preset-aware: candidates are filtered by `appliesTo(preset)`,
  * so a React-only adapter is never picked for a Nest project, and two adapters can
- * share a (target, runner) if they specialise different flavours.
+ * share a (target, runner) if they specialise different presets.
  */
 
 /**
  * Register a tool adapter (called from each role's registration, wired into the
  * bootstrap in `src/adapters.ts`). No (target, runner) uniqueness guard here: two
- * adapters may share one for different flavours; a genuine clash (same target,
- * runner AND flavour) is caught at resolve time, where the flavour is known.
+ * adapters may share one for different presets; a genuine clash (same target,
+ * runner AND preset) is caught at resolve time, where the preset is known.
  */
 declare function register(adapter: Adapter): void;
 /** Set the default runner for a target. */
@@ -309,13 +331,13 @@ declare function setDefaultRunner(target: Target, runner: string): void;
 declare function all(): readonly Adapter[];
 /**
  * Resolve one adapter by target, honouring an explicit `--runner` or the target's
- * default. When a `flavour` is known it also filters by `appliesTo`, so a
+ * default. When a `preset` is known it also filters by `appliesTo`, so a
  * React-only adapter is never picked for Nest; when it is absent (sentinel does
  * not detect it), every adapter for the target is a candidate. Throws with an
  * actionable message for each failure mode: no adapter for the target (yet), none
- * that handles the flavour, an ambiguous choice, an unknown runner, or two
- * adapters claiming the same (target, runner, flavour).
+ * that handles the preset, an ambiguous choice, an unknown runner, or two
+ * adapters claiming the same (target, runner, preset).
  */
-declare function resolve(target: Target, flavour?: Flavour, runner?: string): Adapter;
+declare function resolve(target: Target, preset?: PresetName, runner?: string): Adapter;
 
-export { type Adapter, type AdapterResult, BaseAdapter, type DispatchOptions, type FileOperation, type Flavour, type PackageDependencies, type RunContext, type Target, type UpdateContext, type UpdatePlan, type Verb, all, detectFramework, dispatch, register, registerAdapters, resolve, setDefaultRunner };
+export { type Adapter, type AdapterResult, BaseAdapter, type DispatchOptions, type FileOperation, type Flavour, type PackageDependencies, type PresetName, type RunContext, type Target, type UpdateContext, type UpdatePlan, type Verb, all, detectFramework, dispatch, register, registerAdapters, resolve, setDefaultRunner };

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   registerAdapters,
   resolve,
   setDefaultRunner
-} from "./chunk-EZCRU6XE.js";
+} from "./chunk-FLLX5MN3.js";
 export {
   BaseAdapter,
   all,