@cad0p/pi-steering 0.1.0

package/dist/evaluator-internals/override.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+/**
+ * Inline override-comment detection for the v2 evaluator.
+ *
+ * Ported verbatim from the v1 evaluator's `extractOverride` (see
+ * `../../evaluator.ts`). Syntax and behaviour match exactly so the
+ * extension runtime can swap from v1 to v2 without users rewriting
+ * their override comments. See the v1 evaluator's JSDoc for the full
+ * syntax grammar.
+ *
+ * Exposed as a standalone module so the evaluator and its tests can
+ * assert override detection independently of the rest of the pipeline.
+ */
+/**
+ * Global-flag regex matching every override comment in a text blob.
+ *
+ *   leader:  `#`, `//`, `/*`, `<!--`, `--`, `%%`, `;;`
+ *   key:     `steering-override:`
+ *   name:    `[A-Za-z0-9_-]+`
+ *   sep:     `—` (em dash), `–` (en dash), or `-` (hyphen)
+ *   reason:  anything up to `*\u002f`, `-->`, or end of line
+ */
+const OVERRIDE_RE = /(?:#|\/\/|\/\*|<!--|--|%%|;;)\s*steering-override:\s*([A-Za-z0-9_-]+)\s*[\u2014\u2013-]\s*(.*?)(?:\*\/|-->|$)/gm;
+/**
+ * Shorter marker-only regex used to detect when the lazy reason capture
+ * in {@link OVERRIDE_RE} swallowed a subsequent override marker. When the
+ * scanner finds one, it trims the reason at the marker and rewinds so
+ * the next iteration parses the subsequent override cleanly.
+ */
+const OVERRIDE_MARKER_RE = /(?:#|\/\/|\/\*|<!--|--|%%|;;)\s*steering-override:/;
+/**
+ * Extract an inline override-comment's reason that targets a specific
+ * rule name. Returns the trimmed reason, or null when no override
+ * addressed to `ruleName` is present (empty reasons are treated as
+ * "no override" — users must supply an explicit justification).
+ *
+ * Behaviour parity with v1 `extractOverride`:
+ *
+ *   - case-sensitive rule-name match,
+ *   - supports stacked overrides on one line (e.g.
+ *     `cmd # steering-override: a — r1 # steering-override: b — r2`),
+ *   - first-match-wins across the scanned comments,
+ *   - all leader styles from v1 accepted.
+ *
+ * The v1 implementation is the authoritative reference for edge cases
+ * — see `evaluator.ts` in this package's v1 tree.
+ */
+export function extractOverride(text, ruleName) {
+    // Reset `lastIndex` — the regex is module-scoped and shared across
+    // calls. Without the reset two back-to-back calls with different
+    // texts would pick up mid-string from the previous scan.
+    OVERRIDE_RE.lastIndex = 0;
+    let m = OVERRIDE_RE.exec(text);
+    while (m !== null) {
+        let reason = m[2] ?? "";
+        // Compute where the reason capture started in the source so we
+        // can rewind the scanner if we trim a trailing next-override
+        // marker out of the lazy capture.
+        const reasonStart = (m.index ?? 0) + m[0].length - reason.length;
+        const nextIdx = reason.search(OVERRIDE_MARKER_RE);
+        if (nextIdx !== -1) {
+            reason = reason.slice(0, nextIdx);
+            OVERRIDE_RE.lastIndex = reasonStart + nextIdx;
+        }
+        if (m[1] !== ruleName) {
+            m = OVERRIDE_RE.exec(text);
+            continue;
+        }
+        reason = reason.trim();
+        if (reason === "") {
+            m = OVERRIDE_RE.exec(text);
+            continue;
+        }
+        return reason;
+    }
+    return null;
+}
+//# sourceMappingURL=override.js.map

package/dist/evaluator-internals/override.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"override.js","sourceRoot":"","sources":["../../src/evaluator-internals/override.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,uBAAuB;AAEvB;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,GACf,iHAAiH,CAAC;AAEpH;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,oDAAoD,CAAC;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,QAAgB;IAC5D,mEAAmE;IACnE,iEAAiE;IACjE,yDAAyD;IACzD,WAAW,CAAC,SAAS,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QAClB,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxB,+DAA+D;QAC/D,6DAA6D;QAC7D,kCAAkC;QAClC,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QACjE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAClD,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;YACnB,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YAClC,WAAW,CAAC,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;YACtB,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QACvB,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAClB,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/evaluator-internals/predicates.d.ts

@@ -0,0 +1,152 @@
+import type { Pattern, PredicateContext, PredicateFn, PredicateHandler, ReservedPredicateKey, TopLevelWhenClause } from "../schema.ts";
+/**
+ * Runtime list of predicate keys that plugins are NOT allowed to
+ * register. Mirrors the type-level {@link ReservedPredicateKey} from
+ * `schema.ts`. Adding a new modifier to {@link PredicateModifiers} OR a
+ * new operator field requires updating both this list and the matching
+ * type union; the {@link reservedPredicateKeysCoverReservedTypes}
+ * sync-pinning test in `evaluator.test.ts` fails when the two drift.
+ *
+ * The engine (in the plugin merger) throws at plugin-registration time
+ * if a plugin attempts a reserved key, with a concrete error message
+ * pointing the plugin author at the collision and suggesting an
+ * alternative name.
+ */
+export declare const RESERVED_PREDICATE_KEYS: readonly ["not", "onUnknown"];
+/**
+ * Whether a string key is reserved (cannot be used as a plugin
+ * predicate name). Used by the plugin merger and by
+ * {@link validateWhenClauseShape} when computing the leaf-key set of
+ * a `not:` block.
+ */
+export declare function isReservedPredicateKey(key: string): key is ReservedPredicateKey;
+/**
+ * Throws if a `when:` or `not:` block contains no predicate-leaf keys
+ * after stripping modifier keys.
+ *
+ * Catches three foot-guns at config-resolve time so the engine never
+ * has to silently skip a malformed clause:
+ *   - `when: {}` — zero keys.
+ *   - `not: { onUnknown: "block" }` — one key, but it's a modifier; no
+ *     leaves means the block has nothing to evaluate.
+ *   - `when: { not: { not: ... } }` — nested `not:` inside a not-block,
+ *     authored via JSON load or `as any` escape hatch (the type-level
+ *     ban via {@link TopLevelWhenClauseNoRecurse} catches authoring-
+ *     time mistakes; the same recursion catches the JSON / `as any`
+ *     escape hatch).
+ *
+ * The `not:` operator field itself counts as a leaf at the outer
+ * `when:` level (it produces a verdict via Kleene composition of the
+ * inner not-block); only modifier keys are stripped. Built-in
+ * non-registry keys (`condition`, `happened`, `cwd`) count as leaves;
+ * plugin-registered predicates count as leaves regardless of whether
+ * the plugin is currently loaded — the unknown-predicate check fires
+ * later via {@link UnknownPredicateError}.
+ *
+ * Recurses into the `not:` block to enforce the same shape there.
+ *
+ * `path` describes the call site for error messages, e.g.
+ * `'rule "no-main-commit".when'` or `'rule "no-git-worktree".when.not'`.
+ */
+export declare function validateWhenClauseShape(block: TopLevelWhenClause<string> | undefined, path: string): void;
+/**
+ * Modifier-only subset of {@link RESERVED_PREDICATE_KEYS} — used by
+ * {@link validateWhenClauseShape} to strip modifiers when counting
+ * leaves. Operator fields (currently `"not"`) are NOT modifiers; they
+ * produce verdicts and count as leaves.
+ *
+ * Type-level coverage assertion (mirrors the
+ * {@link _RESERVED_PREDICATE_KEYS_COVERS_TYPE} pattern): the
+ * `satisfies readonly (keyof PredicateModifiers)[]` clause pins each
+ * entry to a real modifier key, AND the
+ * {@link _MODIFIER_KEYS_COVERS_TYPE} constant fails compilation if a
+ * future modifier (e.g. a hypothetical v0.2 `priority?: number`) is
+ * added to {@link PredicateModifiers} without updating this list.
+ * Without the lockstep check, the new modifier would be counted as a
+ * leaf by {@link validateWhenClauseShape}, masking empty-clause
+ * configs that are now "only modifiers, no real leaves."
+ */
+export declare const MODIFIER_KEYS: readonly ["onUnknown"];
+/**
+ * Match a string against a {@link Pattern} (string source or RegExp).
+ * Patterns are compiled once and cached; RegExps pass through.
+ */
+export declare function matchesPattern(pattern: Pattern, target: string): boolean;
+/**
+ * Evaluate a rule-level predicate (`pattern`, `requires`, `unless`).
+ *
+ * Accepts the same union v1's `Rule` supported plus {@link PredicateFn}:
+ *   - `string` / `RegExp` → pattern match against `target`.
+ *   - `function`          → call with `ctx`, coerce result to boolean.
+ */
+export declare function matchesPatternOrFn(value: Pattern | PredicateFn, target: string, ctx: PredicateContext): Promise<boolean>;
+/**
+ * Thrown when a {@link TopLevelWhenClause} references a predicate name that no
+ * plugin has registered. The error message includes the offending key
+ * so the source of the typo / missing plugin is clear at the site of
+ * the rule.
+ *
+ * Schema-level typo detection doesn't cover this because the
+ * `TopLevelWhenClause` mapped-type's index signature is deliberately
+ * loose (`unknown`) — per
+ * the ADR, plugin predicates can accept arbitrary arg shapes. The
+ * trade-off is that we surface the error at evaluation time instead of
+ * load time; the key-scoped message keeps that tolerable.
+ */
+export declare class UnknownPredicateError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * Walker state consumed by `when` evaluation. Today just the per-ref
+ * cwd; the shape is open for future built-ins (e.g. branch) to pull
+ * their own fields from the same snapshot.
+ *
+ * @internal — not a plugin-author surface. Plugin predicates consume
+ * `ctx.walkerState` (the public `Readonly<Record<string, unknown>>`
+ * on {@link PredicateContext}) instead.
+ */
+interface WhenWalkerState {
+    readonly cwd: string;
+}
+/**
+ * Evaluate a {@link TopLevelWhenClause}: returns true if every predicate in the
+ * clause "matches" for the given context. An empty / undefined clause
+ * trivially matches (rule fires regardless of `when`).
+ *
+ * Dispatch table:
+ *   - `cwd`        — built-in (walker-tied), consumes `state.cwd`. Returns
+ *                    trinary; outer leaf-level `onUnknown:` modifier on
+ *                    the spread form projects to a definite boolean via
+ *                    {@link projectVerdict} (default `"block"` =
+ *                    fail-CLOSED).
+ *   - `happened`   — built-in (session-entry-scoped), consumes
+ *                    `ctx.findEntries` + `ctx.agentLoopIndex`. Boolean.
+ *   - `not`        — nested `not:` block; dispatched to
+ *                    {@link evaluateNotBlock} which composes leaves with
+ *                    Kleene 3-valued AND and applies the block-level
+ *                    `onUnknown:` policy without the not-flip on unknown
+ *                    leaves.
+ *   - `condition`  — {@link PredicateFn}; call with ctx. Throws caught
+ *                    and treated as `"unknown"`. Outer-level
+ *                    `condition:` is bare-`PredicateFn`-typed (no
+ *                    spread shape), so the projection always uses the
+ *                    default `"block"` policy and a throwing condition
+ *                    fires the rule fail-CLOSED. Mirrors the inner
+ *                    not-block exception treatment + the
+ *                    plugin-handler contract in
+ *                    {@link evaluateLeafTrinary}.
+ *   - anything else — `predicates[key]`; trinary handler with
+ *                    leaf-level `onUnknown:` modifier projection. Throws
+ *                    treated as `"unknown"` per spec.
+ *
+ * Reserved keys (`onUnknown`, future modifiers) are skipped here too —
+ * they're meaningful as siblings to leaves at the outer level (per
+ * spread form `{ pattern, onUnknown }` placement) but the engine
+ * doesn't iterate them as standalone keys; the leaf adapter consumes
+ * them inline. A bare `onUnknown:` at the outer level (without a
+ * containing leaf) is type-banned but skipped here defensively.
+ */
+export declare function evaluateWhen(when: TopLevelWhenClause<string> | undefined, state: WhenWalkerState, ctx: PredicateContext, predicates: Record<string, PredicateHandler>, ruleName: string, source: string): Promise<boolean>;
+export {};
+//# sourceMappingURL=predicates.d.ts.map

package/dist/evaluator-internals/predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicates.d.ts","sourceRoot":"","sources":["../../src/evaluator-internals/predicates.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,OAAO,EACP,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAGhB,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,cAAc,CAAC;AAQtB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,+BAKgB,CAAC;AAkBrD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,GACV,GAAG,IAAI,oBAAoB,CAE7B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,SAAS,EAC7C,IAAI,EAAE,MAAM,GACX,IAAI,CAsDN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,wBAEgC,CAAC;AA6C3D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGxE;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,GAAG,WAAW,EAC5B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,OAAO,CAAC,CAMlB;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBACT,GAAG,EAAE,MAAM;CASxB;AA0VD;;;;;;;;GAQG;AACH,UAAU,eAAe;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AA0OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,SAAS,EAC5C,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,gBAAgB,EACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CA+FlB"}