@cad0p/pi-steering 0.1.0

package/src/internal/watch-matcher.ts

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Shared observer-watch filter contract. Single source of truth for
+ * "does this observer's `watch` accept this tool_result event?"
+ *
+ * Used by BOTH:
+ *
+ *   - the observer-dispatcher (production fire path — decides which
+ *     observers see a concrete tool_result).
+ *   - the evaluator's `when.happened` tool_call-scope speculative-
+ *     allow (synthesizes a minimal successful bash event representing
+ *     "this prior `&&` ref is about to run and succeed", then asks
+ *     the same question).
+ *
+ * Co-locating the contract here retires a structural fragility PR #4
+ * reviewers caught three times: the speculative-allow path used to
+ * hand-roll a SUBSET of the watch filter (command-pattern only, then
+ * patched to also check toolName + exitCode). Each new `watch` field
+ * the dispatcher grew would create a fresh drift opportunity.
+ *
+ * Keeping both callers on this one function guarantees the two paths
+ * agree by construction. If the speculative-allow path wants to
+ * impose a STRICTER gate on top (e.g. "observer must declare
+ * `inputMatches.command`" — an authoring requirement to keep
+ * speculative-allow safe), it layers that gate before delegating to
+ * {@link matchesWatch} rather than re-implementing the filter body.
+ *
+ * Merge-observers helper lives in {@link ./merge-observers.ts} for the
+ * same single-source-of-truth reason. This file is its sibling on the
+ * watch-filter axis.
+ */
+
+import {
+  expandWrapperCommands,
+  extractAllCommandsFromAST,
+  parse as parseBash,
+} from "@cad0p/unbash-walker";
+import { matchesPattern } from "../evaluator-internals/predicates.ts";
+import type { ObserverWatch, Pattern, ToolResultEvent } from "../schema.ts";
+import { refToText } from "./ref-text.ts";
+
+/**
+ * True if the observer's `watch` filter accepts this event. No watch
+ * → matches everything. Semantics per ADR "Observer schema":
+ *
+ *   - `toolName` — exact match against `event.toolName`.
+ *   - `inputMatches` — every declared key's Pattern must match against
+ *     `event.input[key]` if that key exists AND the value is a string.
+ *     Keys absent from the event's input (or non-string values) make
+ *     the whole filter fail — documented fail-closed choice: subset
+ *     checks don't silently pass when the expected field isn't present.
+ *   - `exitCode` — `"success"` → 0, `"failure"` → non-zero,
+ *     `"any"`/omitted → pass, numeric → exact match. `exitCode` is
+ *     sourced from the event's `exitCode` field (bash only via pi's
+ *     `details.exitCode` after projection to the schema shape); other
+ *     tool results leave it `undefined` and satisfy everything except
+ *     a numeric `exitCode:` (treated as "no match" — bash-specific
+ *     filter).
+ *
+ * Wrapper-aware command matching (ADR §12): when `inputMatches.command`
+ * is set AND the event is a bash event, the pattern matches if EITHER
+ * the raw outer `event.input.command` OR any extracted command ref
+ * text matches. So `sh -c 'brazil ws sync'` with pattern
+ * `/^brazil\s+ws\s+sync$/` fires the observer — the outer raw command
+ * starts with `sh`, but the walker-extracted ref `brazil ws sync` does
+ * hit the anchored pattern.
+ *
+ * Performance: when multiple observers share the same event (the
+ * production dispatch path), pass a memoizing `refTextsProvider` to
+ * parse the bash command once across observers. Standalone callers
+ * (e.g. `testObserver` evaluating one observer in isolation, or the
+ * evaluator's speculative-allow synthesizing one event per prior
+ * `&&` ref) can omit it — the default provider parses on demand.
+ */
+export function matchesWatch(
+  watch: ObserverWatch | undefined,
+  event: ToolResultEvent,
+  refTextsProvider?: () => readonly string[] | null,
+): boolean {
+  if (!watch) return true;
+
+  if (watch.toolName !== undefined && watch.toolName !== event.toolName) {
+    return false;
+  }
+
+  if (watch.inputMatches) {
+    const rawInput = event.input;
+    const input: Record<string, unknown> =
+      typeof rawInput === "object" && rawInput !== null
+        ? (rawInput as Record<string, unknown>)
+        : {};
+    const getRefTexts =
+      refTextsProvider ?? (() => extractRefTextsForBash(event));
+    for (const [key, pat] of Object.entries(watch.inputMatches)) {
+      const value = input[key];
+      if (typeof value !== "string") return false;
+      if (!matchesInputField(key, pat, value, event, getRefTexts)) {
+        return false;
+      }
+    }
+  }
+
+  if (watch.exitCode !== undefined && watch.exitCode !== "any") {
+    if (!matchesExitCode(event.exitCode, watch.exitCode)) return false;
+  }
+  return true;
+}
+
+/**
+ * Match a single `inputMatches` key/value against the event. `command`
+ * on a bash event is wrapper-aware per ADR §12 — the raw outer command
+ * OR any extracted ref text matches. All other keys (and `command` on
+ * non-bash events) keep the straight raw-string match the v0.0 engine
+ * shipped with.
+ *
+ * Share the evaluator's regex cache (module-scoped in `predicates.ts`)
+ * so observer `inputMatches` reuse the same compiled `RegExp` as
+ * equivalent rule patterns.
+ */
+function matchesInputField(
+  key: string,
+  pat: Pattern,
+  value: string,
+  event: ToolResultEvent,
+  getRefTexts: () => readonly string[] | null,
+): boolean {
+  if (matchesPattern(pat, value)) return true;
+
+  // Wrapper-aware fallback: only for `command` on bash events. Other
+  // fields (path, content, …) don't have wrapper analogues — a
+  // file-path pattern has nothing to do with bash AST refs, so
+  // leaving them on the raw-string path is both correct and a perf
+  // guard against needless parsing on non-bash events.
+  if (key !== "command" || event.toolName !== "bash") return false;
+
+  const refTexts = getRefTexts();
+  if (refTexts === null) return false;
+  for (const text of refTexts) {
+    if (matchesPattern(pat, text)) return true;
+  }
+  return false;
+}
+
+/**
+ * Extract per-ref flattened text (basename + args joined with spaces)
+ * from a bash tool_result's outer command, mirroring the evaluator's
+ * `prepareBashState` text projection so observer watch patterns match
+ * the same strings rule patterns see for the same command.
+ *
+ * Returns `null` when the event isn't a bash tool_result, the raw
+ * command is missing/non-string, or the walker throws while parsing
+ * (hard-to-parse command — fall back to raw-only matching without
+ * blowing up dispatch). Unlike the evaluator we don't walk trackers:
+ * observers don't receive `walkerState`, so the parse+extract+expand
+ * stages suffice.
+ *
+ * Exported so the production dispatcher can memoize the parse across
+ * observers on the same event (see `dispatchEventInner`'s
+ * `getRefTexts` cache). Chain-aware speculative-allow already
+ * synthesizes one event per prior ref and doesn't need memoization —
+ * it calls {@link matchesWatch} without a provider.
+ */
+export function extractRefTextsForBash(
+  event: ToolResultEvent,
+): readonly string[] | null {
+  if (event.toolName !== "bash") return null;
+  const input =
+    typeof event.input === "object" && event.input !== null
+      ? (event.input as { command?: unknown })
+      : undefined;
+  const command = input?.command;
+  if (typeof command !== "string" || command.length === 0) return null;
+  try {
+    const script = parseBash(command);
+    const extracted = extractAllCommandsFromAST(script, command);
+    const { commands: refs } = expandWrapperCommands(extracted);
+    return refs.map(refToText);
+  } catch {
+    // Don't let a parse error take down dispatch — a malformed
+    // command still deserves a raw-match chance. Returning null
+    // (as opposed to []) skips ref matching entirely for this event.
+    return null;
+  }
+}
+
+function matchesExitCode(
+  code: number | undefined,
+  filter: number | "success" | "failure",
+): boolean {
+  if (typeof filter === "number") {
+    // Numeric filter requires a concrete code; no-code events (non-bash)
+    // never match a numeric filter.
+    return code === filter;
+  }
+  if (filter === "success") return code === 0;
+  if (filter === "failure") return code !== undefined && code !== 0;
+  return true;
+}

package/src/jsdoc-propagation.test.ts

@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Regression fence: verifies that JSDoc declared on
+ * `PiSteeringPredicates.<key>` (in a plugin's `declare global { ... }`
+ * block) propagates onto the synthesized fields of
+ * {@link TopLevelWhenClause} and {@link TopLevelWhenClauseNoRecurse},
+ * surfacing on hover for plugin-predicate authors.
+ *
+ * Hover resolution drives `LanguageService.getQuickInfoAtPosition` —
+ * the same code tsserver runs for IDE hover tooltips — so the
+ * assertion text is exactly what the user sees.
+ *
+ * Background: TypeScript's checker
+ * (`resolveMappedTypeMembers` in `src/compiler/checker.ts`) only
+ * links property declarations through a mapped type when the
+ * constraint AST is literally `keyof T` and the optional `as` clause
+ * is a Filter (returns `K | never`, assignable to `K`). The
+ * pre-computed alias `[K in PluginPredicateKey]` produces the same
+ * keyset but uses a `TypeReference` AST in place of `KeyOfKeyword` —
+ * `isMappedTypeWithKeyofConstraintDeclaration` returns false, the
+ * `modifiersProp.declarations` link is dropped, and JSDoc on the
+ * underlying interface member is no longer reachable from the
+ * synthesized symbol.
+ *
+ * Built-in non-registry leaves (`cwd:`, `happened:`, `condition:`)
+ * don't share this regression vector — their JSDoc propagates through
+ * the trivial `interface property → property symbol` path on
+ * `BuiltInWhenLeavesOuter` / `BuiltInWhenLeavesInner` and the
+ * homomorphism check doesn't apply.
+ */
+
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+
+import * as ts from "typescript";
+
+// Imported solely so the file-level JSDoc `@link` references resolve
+// on hover; these are the types whose hover-propagation behavior the
+// fences below pin.
+import type {
+  TopLevelWhenClause,
+  TopLevelWhenClauseNoRecurse,
+} from "./schema.ts";
+
+void (0 as unknown as TopLevelWhenClause | TopLevelWhenClauseNoRecurse);
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_GIT_PATH = path.resolve(HERE, "plugins/git/index.ts");
+const SCHEMA_PATH = path.resolve(HERE, "schema.ts");
+const INDEX_PATH = path.resolve(HERE, "index.ts");
+
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ES2022,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  allowImportingTsExtensions: true,
+  skipLibCheck: true,
+  strict: true,
+  exactOptionalPropertyTypes: true,
+  noEmit: true,
+  types: [],
+};
+
+/**
+ * Resolve hover-time JSDoc at the position of `propName:` inside the
+ * object literal whose source location follows `anchor`. Drives
+ * `LanguageService.getQuickInfoAtPosition` — the same code tsserver
+ * runs for IDE hover tooltips, so the returned text matches what the
+ * user sees on hover.
+ */
+function hoverDocsAt(
+  scratchDir: string,
+  source: string,
+  propName: string,
+  anchor: string,
+): string {
+  mkdirSync(scratchDir, { recursive: true });
+  const scratchFile = path.join(scratchDir, "probe.ts");
+  writeFileSync(scratchFile, source);
+
+  const host: ts.LanguageServiceHost = {
+    getScriptFileNames: () => [scratchFile],
+    getScriptVersion: () => "1",
+    getScriptSnapshot: (name) => {
+      try {
+        return ts.ScriptSnapshot.fromString(ts.sys.readFile(name) ?? "");
+      } catch {
+        return undefined;
+      }
+    },
+    getCurrentDirectory: () => scratchDir,
+    getCompilationSettings: () => COMPILER_OPTIONS,
+    getDefaultLibFileName: (opts) => ts.getDefaultLibFilePath(opts),
+    fileExists: ts.sys.fileExists,
+    readFile: ts.sys.readFile,
+    readDirectory: ts.sys.readDirectory,
+    directoryExists: ts.sys.directoryExists,
+    getDirectories: ts.sys.getDirectories,
+  };
+  const ls = ts.createLanguageService(host, ts.createDocumentRegistry());
+  const anchorIdx = source.indexOf(anchor);
+  assert(
+    anchorIdx >= 0,
+    `anchor ${JSON.stringify(anchor)} not found in source`,
+  );
+  const propIdx = source.indexOf(`${propName}:`, anchorIdx);
+  assert(
+    propIdx >= 0,
+    `prop ${JSON.stringify(propName)} not found after anchor`,
+  );
+  const qi = ls.getQuickInfoAtPosition(scratchFile, propIdx + 1);
+  assert(qi, "expected quickInfo to resolve at probe position");
+  return ts.displayPartsToString(qi.documentation ?? []);
+}
+
+function withScratch(suffix: string, fn: (scratchDir: string) => void): void {
+  const scratchDir = path.join(
+    os.tmpdir(),
+    `jsdoc-propagation-${suffix}-${process.pid}-${Date.now()}`,
+  );
+  try {
+    fn(scratchDir);
+  } finally {
+    rmSync(scratchDir, { recursive: true, force: true });
+  }
+}
+
+const IMPORT_HEADER = [
+  `import "${PLUGIN_GIT_PATH.replace(/\\/g, "\\\\")}";`,
+  `import type { Rule } from "${SCHEMA_PATH.replace(/\\/g, "\\\\")}";`,
+  "",
+].join("\n");
+
+const RULE_BOILERPLATE = [
+  '\tname: "x",',
+  '\ttool: "bash",',
+  '\tfield: "command",',
+  '\tpattern: "^x",',
+  '\treason: "x",',
+].join("\n");
+
+/**
+ * One row per plugin-augmented predicate key in `PiSteeringPredicates`.
+ * `value` is the bare-form RHS used inside `when: { ... }`; `contains`
+ * is a sentinel substring of the source-declared JSDoc on
+ * `plugins/git/index.ts`'s `interface PiSteeringPredicates`.
+ */
+const PREDICATE_CASES = [
+  { key: "branch", value: "/main/", contains: "current git branch" },
+  { key: "upstream", value: "/origin/", contains: "configured" },
+  { key: "remote", value: "/github/", contains: "remote.origin.url" },
+  { key: "isClean", value: "false", contains: "git status" },
+  { key: "hasStagedChanges", value: "true", contains: "git diff --cached" },
+  { key: "commitsAhead", value: "1", contains: "commits ahead" },
+] as const;
+
+describe("JSDoc propagation through TopLevelWhenClause mapped type", () => {
+  for (const { key, value, contains } of PREDICATE_CASES) {
+    it(`surfaces JSDoc on when.${key} via Rule annotation`, () => {
+      withScratch(`outer-${key}`, (scratchDir) => {
+        const source =
+          IMPORT_HEADER +
+          "const r: Rule = {\n" +
+          RULE_BOILERPLATE +
+          "\n" +
+          `\twhen: { ${key}: ${value} },\n` +
+          "};\n" +
+          "void r;\n";
+        const docs = hoverDocsAt(scratchDir, source, key, "when: {");
+        assert(
+          docs.includes(`when.${key}`),
+          `expected JSDoc to include 'when.${key}'; got: ${JSON.stringify(docs)}`,
+        );
+        assert(
+          docs.includes(contains),
+          `expected JSDoc to include ${JSON.stringify(contains)}; got: ${JSON.stringify(docs)}`,
+        );
+      });
+    });
+
+    it(`surfaces JSDoc on when.not.${key} via TopLevelWhenClauseNoRecurse`, () => {
+      withScratch(`inner-${key}`, (scratchDir) => {
+        const source =
+          IMPORT_HEADER +
+          "const r: Rule = {\n" +
+          RULE_BOILERPLATE +
+          "\n" +
+          `\twhen: { not: { ${key}: ${value} } },\n` +
+          "};\n" +
+          "void r;\n";
+        const docs = hoverDocsAt(scratchDir, source, key, "not: {");
+        assert(
+          docs.includes(`when.${key}`),
+          `expected nested JSDoc to include 'when.${key}'; got: ${JSON.stringify(docs)}`,
+        );
+        assert(
+          docs.includes(contains),
+          `expected nested JSDoc to include ${JSON.stringify(contains)}; got: ${JSON.stringify(docs)}`,
+        );
+      });
+    });
+  }
+
+  it("inline defineConfig drops JSDoc — known limitation; factor rules out for hover-rich authoring", () => {
+    // `defineConfig({ rules: [{ ...inline... }] })` narrows the
+    // rule literal via its `const R extends readonly Rule[]`
+    // signature, bypassing the homomorphic mapped-type linkage.
+    // The canonical hover-rich pattern is to factor rules out into
+    // `as const satisfies Rule` (or `: Rule`) bindings — see the
+    // next test and `defineConfig`'s JSDoc.
+    withScratch("inline-defineconfig", (scratchDir) => {
+      const source = [
+        `import { defineConfig } from "${INDEX_PATH.replace(/\\/g, "\\\\")}";`,
+        `import "${PLUGIN_GIT_PATH.replace(/\\/g, "\\\\")}";`,
+        "",
+        "export default defineConfig({",
+        "\trules: [",
+        "\t\t{",
+        '\t\t\tname: "inline",',
+        '\t\t\ttool: "bash",',
+        '\t\t\tfield: "command",',
+        '\t\t\tpattern: "^x",',
+        '\t\t\treason: "x",',
+        "\t\t\twhen: { isClean: false },",
+        "\t\t},",
+        "\t],",
+        "});",
+        "",
+      ].join("\n");
+      const docs = hoverDocsAt(scratchDir, source, "isClean", 'name: "inline"');
+      assert.equal(
+        docs,
+        "",
+        `inline-defineConfig path now SURFACES JSDoc — gap closed, update the docs (defineConfig JSDoc + examples README) to remove the factor-out recommendation. Got: ${JSON.stringify(docs)}`,
+      );
+    });
+  });
+
+  it("factored-out `as const satisfies Rule` preserves JSDoc through defineConfig", () => {
+    // The canonical hover-rich pattern documented in
+    // `defineConfig`'s JSDoc and `examples/dynamic-reason-runtime-
+    // cwd/steering.ts`. The factored-out binding annotates the
+    // literal with `Rule` (via `satisfies`), restoring the
+    // homomorphic mapped-type linkage that surfaces source JSDoc.
+    withScratch("factored-out", (scratchDir) => {
+      const source = [
+        `import { defineConfig, type Rule } from "${INDEX_PATH.replace(/\\/g, "\\\\")}";`,
+        `import "${PLUGIN_GIT_PATH.replace(/\\/g, "\\\\")}";`,
+        "",
+        "const myRule = {",
+        '\tname: "factored",',
+        '\ttool: "bash",',
+        '\tfield: "command",',
+        '\tpattern: "^x",',
+        '\treason: "x",',
+        "\twhen: { isClean: false },",
+        "} as const satisfies Rule;",
+        "",
+        "export default defineConfig({",
+        "\trules: [myRule],",
+        "});",
+        "",
+      ].join("\n");
+      const docs = hoverDocsAt(scratchDir, source, "isClean", "myRule");
+      assert(
+        docs.includes("git status"),
+        `factored-out pattern should preserve JSDoc; got: ${JSON.stringify(docs)}`,
+      );
+    });
+  });
+});