@cad0p/pi-steering 0.1.0

package/src/index.ts

@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+//
+// pi-steering — deterministic steering hooks for pi agents.
+// Inspired by @samfp/pi-steering-hooks (schema, override-comment,
+// defaults). AST backend + command-level effective-cwd via
+// unbash-walker. This file is the thin wiring layer between pi's
+// extension API and the engine (loader + plugin-merger + evaluator
+// + observer-dispatcher).
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { EvaluatorHost } from "./evaluator.ts";
+import { buildSessionRuntime } from "./internal/session-runtime.ts";
+
+/**
+ * Pi extension factory. Wires the steering engine onto pi's
+ * lifecycle events.
+ *
+ * Strict-mode contract: see {@link SteeringConfig.failOnWarnings}.
+ *
+ * Lifecycle wiring:
+ *
+ *   - factory time      — eager load via {@link buildSessionRuntime};
+ *                         throws on diagnostic per the strict-mode
+ *                         contract.
+ *   - `agent_start`     — bump the internal `agentLoopIndex` counter
+ *                         so tool_call / tool_result handlers can
+ *                         forward it into the evaluator + dispatcher.
+ *                         One agent loop = one user prompt + all the
+ *                         tool calls it spawns.
+ *   - `session_start`   — emit a `console.warn` if the resumed
+ *                         session's `ctx.cwd` differs from the launch
+ *                         cwd captured at factory time (cross-project
+ *                         resume). The engine continues evaluating
+ *                         with launch-cwd rules.
+ *   - `tool_call` / `tool_result` route through the evaluator and
+ *     dispatcher (see {@link buildSessionRuntime}).
+ *
+ * Exported as the default export per pi's extension convention.
+ */
+export default async function register(pi: ExtensionAPI): Promise<void> {
+  let agentLoopIndex = 0;
+
+  const host: EvaluatorHost = {
+    exec: pi.exec,
+    appendEntry: pi.appendEntry,
+  };
+
+  const launchCwd = process.cwd();
+
+  const { evaluator, dispatcher } = await buildSessionRuntime(launchCwd, host);
+
+  pi.on("agent_start", () => {
+    agentLoopIndex += 1;
+  });
+
+  pi.on("session_start", (_event, ctx: ExtensionContext) => {
+    if (ctx.cwd !== launchCwd) {
+      console.warn(
+        `[pi-steering] session cwd (${ctx.cwd}) differs from launch cwd ` +
+          `(${launchCwd}). Steering rules loaded from launch cwd; ` +
+          `session-cwd rules NOT applied. To use session-cwd rules, ` +
+          `exit pi and re-launch from ${ctx.cwd}.`,
+      );
+    }
+  });
+
+  pi.on("tool_call", (event, ctx) =>
+    evaluator.evaluate(event, ctx, agentLoopIndex),
+  );
+
+  pi.on("tool_result", (event, ctx) =>
+    dispatcher.dispatch(event, ctx, agentLoopIndex),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public surface — the engine.
+//
+// Consumers embedding the engine (building their own extensions, a CLI
+// that lints commands, a test harness, …) import these from the
+// package root.
+// ---------------------------------------------------------------------------
+
+// Walker types re-exported for plugin authors. Forward-compatible with
+// future unbash-walker extraction — imports from this package won't
+// break.
+export type {
+  Command,
+  CommandRef,
+  EnvState,
+  Modifier,
+  Node,
+  Script,
+  SubshellSemantics,
+  Tracker,
+  WalkResult,
+  Word,
+  WordPart,
+} from "@cad0p/unbash-walker";
+// Walker functions re-exported for plugin authors writing custom
+// predicates and trackers. Forward-compatible with future
+// unbash-walker extraction.
+export {
+  cwdTracker,
+  envTracker,
+  expandWrapperCommands,
+  extractAllCommandsFromAST,
+  formatCommand,
+  getBasename,
+  getCommandArgs,
+  getCommandName,
+  isStaticallyResolvable,
+  parse,
+  resolveWord,
+  walk,
+} from "@cad0p/unbash-walker";
+// JSON compat — convert v1 JSON configs to v2 TS configs.
+export { FromJSONError, fromJSON } from "./compat.ts";
+// Defaults — bundled rule and plugin starter set.
+export { DEFAULT_PLUGINS, DEFAULT_RULES } from "./defaults.ts";
+export type { DefineConfigInput } from "./define-config.ts";
+// Config helper (preferred entry point).
+export { defineConfig } from "./define-config.ts";
+// Predicate helper.
+export { definePredicate } from "./define-predicate.ts";
+// Auto-tag key for session-entry writes. Exposed so plugin authors
+// inspecting raw session entries via `findEntries` can reference the
+// constant instead of hardcoding the string.
+export { AGENT_LOOP_INDEX_KEY } from "./evaluator-internals/context.ts";
+// Reason-text helper for custom predicates that read runtime
+// `ctx.cwd` (shell-exec or filesystem queries) rather than
+// walker-tracked state.
+//
+// `walkerUnknownCwdReason`: composable agent-facing reason text
+// for ReasonFns to call on the walker-unknown branch of those
+// runtime-cwd predicates (typical handler shape:
+// `if (ctx.walkerState?.cwd === "unknown") return "unknown";`,
+// then the engine projects via `onUnknown:` policy).
+export { walkerUnknownCwdReason } from "./helpers/walker-unknown-cwd-reason.ts";
+// Loader — walk-up config discovery + merge.
+export { buildConfig, loadConfigs, loadSteeringConfig } from "./loader.ts";
+// Schema types — the public authoring surface.
+export type {
+  AnyPredicateHandler,
+  BaseRule,
+  BashRule,
+  BuiltInWhenLeaves,
+  BuiltInWhenLeavesInner,
+  BuiltInWhenLeavesOuter,
+  DefaultSpreadBase,
+  EditRule,
+  ExecOpts,
+  ExecResult,
+  InnerValue,
+  Observer,
+  ObserverContext,
+  ObserverWatch,
+  OperatorField,
+  OuterValue,
+  Pattern,
+  Patterns,
+  Plugin,
+  PluginPredicateKey,
+  PredicateContext,
+  PredicateFn,
+  PredicateHandler,
+  PredicateModifiers,
+  PredicateShape,
+  PredicateToolInput,
+  PredicateVerdict,
+  ReasonFn,
+  ReservedPredicateKey,
+  Rule,
+  SteeringConfig,
+  SteeringDiagnostic,
+  SteeringDiagnosticKind,
+  ToolResultEvent,
+  TopLevelWhenClause,
+  TopLevelWhenClauseNoRecurse,
+  WhenClause,
+  WhenWalkerState,
+  WriteRule,
+} from "./schema.ts";
+export type {
+  BashShorthand,
+  CreateRecordingHostOptions,
+  EditShorthand,
+  ExpectBlocksOptions,
+  Harness,
+  LoadHarnessOptions,
+  MatrixCase,
+  MatrixCaseResult,
+  MatrixResult,
+  MockContextOptions,
+  MockEntry,
+  MockObserverContextOptions,
+  PriorEntryOptions,
+  RecordedExecCall,
+  RecordedSessionEntry,
+  RecordingHost,
+  ToolCallShorthand,
+  ToolResultShorthand,
+  WriteShorthand,
+} from "./testing/index.ts";
+// Testing primitives — re-exported at the root for discoverability.
+// The canonical import path is `@cad0p/pi-steering/testing`;
+// this root re-export means a test file that already imports
+// `defineConfig` from the root doesn't need a second import line for
+// `loadHarness`. See `./testing/index.ts` for the API docs.
+export {
+  createRecordingHost,
+  expectAllows,
+  expectBlocks,
+  expectRuleFires,
+  formatMatrix,
+  getAppendedEntries,
+  loadHarness,
+  mockContext,
+  mockExtensionContext,
+  mockObserverContext,
+  priorEntry,
+  runMatrix,
+  testObserver,
+  testPredicate,
+} from "./testing/index.ts";

package/src/internal/drop-unused-observers.test.ts

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Observer, Rule } from "../schema.ts";
+import { dropUnusedObservers } from "./drop-unused-observers.ts";
+
+/** Minimal Observer for tests. */
+function mkObserver(name: string, writes?: readonly string[]): Observer {
+  const base = {
+    name,
+    watch: { toolName: "bash" as const },
+    onResult: () => {},
+  } satisfies Observer;
+  return writes === undefined ? base : { ...base, writes };
+}
+
+/** Minimal Rule with a specific `happened` shape. */
+function mkRuleWithHappened(name: string, event: string, since?: string): Rule {
+  return {
+    name,
+    tool: "bash",
+    field: "command",
+    pattern: /^x/,
+    when: {
+      happened: since
+        ? { event, in: "agent_loop", since }
+        : { event, in: "agent_loop" },
+    },
+    reason: "test",
+  };
+}
+
+/** Rule with no happened at all. */
+function mkRuleNoHappened(name: string): Rule {
+  return {
+    name,
+    tool: "bash",
+    field: "command",
+    pattern: /^x/,
+    reason: "test",
+  };
+}
+
+describe("dropUnusedObservers", () => {
+  it("keeps observer whose write is consumed by a rule's happened.event", () => {
+    const observers = [mkObserver("a", ["X"])];
+    const rules = [mkRuleWithHappened("r1", "X")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.equal(kept.length, 1);
+    assert.equal(kept[0]?.name, "a");
+    assert.equal(dropped.length, 0);
+  });
+
+  it("drops observer whose writes are not consumed", () => {
+    const observers = [mkObserver("a", ["X"])];
+    const rules = [mkRuleNoHappened("r1")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.equal(kept.length, 0);
+    assert.equal(dropped.length, 1);
+    assert.equal(dropped[0]?.name, "a");
+    assert.deepEqual(dropped[0]?.writes, ["X"]);
+    assert.equal(dropped[0]?.reason, "unused-writes");
+  });
+
+  it("keeps observer when at least one of its writes is consumed", () => {
+    const observers = [mkObserver("a", ["X", "Y"])];
+    const rules = [mkRuleWithHappened("r1", "X")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.equal(kept.length, 1);
+    assert.equal(dropped.length, 0);
+  });
+
+  it("keeps observer with `writes: undefined` (conservative)", () => {
+    const observers = [mkObserver("a", undefined)];
+    const rules = [mkRuleNoHappened("r1")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.equal(kept.length, 1);
+    assert.equal(dropped.length, 0);
+  });
+
+  it("keeps observer with empty `writes: []` (conservative parity)", () => {
+    const observers = [mkObserver("a", [])];
+    const rules = [mkRuleNoHappened("r1")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.equal(kept.length, 1);
+    assert.equal(dropped.length, 0);
+  });
+
+  it("keeps observer whose write is consumed only by happened.since", () => {
+    const observers = [mkObserver("a", ["X"])];
+    const rules = [mkRuleWithHappened("r1", "Y", /* since */ "X")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.equal(kept.length, 1);
+    assert.equal(dropped.length, 0);
+  });
+
+  it("partitions a mixed observer set correctly", () => {
+    const observers = [
+      mkObserver("consumed", ["X"]),
+      mkObserver("unused", ["Z"]),
+      mkObserver("undeclared"),
+    ];
+    const rules = [mkRuleWithHappened("r1", "X")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.deepEqual(kept.map((o) => o.name).sort(), [
+      "consumed",
+      "undeclared",
+    ]);
+    assert.deepEqual(
+      dropped.map((d) => d.name),
+      ["unused"],
+    );
+  });
+
+  it("drops everything when no rule uses `when.happened`", () => {
+    const observers = [mkObserver("a", ["X"]), mkObserver("b", ["Y", "Z"])];
+    const rules = [mkRuleNoHappened("r1"), mkRuleNoHappened("r2")];
+    const { kept, dropped } = dropUnusedObservers(observers, rules);
+    assert.equal(kept.length, 0);
+    assert.equal(dropped.length, 2);
+  });
+
+  it("returns empty arrays for empty inputs", () => {
+    const { kept, dropped } = dropUnusedObservers([], []);
+    assert.equal(kept.length, 0);
+    assert.equal(dropped.length, 0);
+  });
+
+  it("honors caller-applied rule filtering (disabledRules)", () => {
+    // Caller is responsible for filtering disabled rules before
+    // passing to this helper — demonstrate that a rule NOT in the
+    // input list does NOT cause its observer writes to stay alive.
+    const observers = [mkObserver("a", ["X"])];
+    const rulesAfterDisable: Rule[] = []; // r1 (consumer) disabled → filtered out
+    const { kept, dropped } = dropUnusedObservers(observers, rulesAfterDisable);
+    assert.equal(kept.length, 0);
+    assert.equal(dropped.length, 1);
+  });
+});

package/src/internal/drop-unused-observers.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Observer-drop optimization.
+ *
+ * At config-build time, observers whose declared `writes: [...]` are
+ * entirely unconsumed by any rule's `happened.event` / `happened.since`
+ * can be dropped: they'd only fire on `tool_result` and write entries
+ * no rule ever reads. Dropping them skips both the write (cheaper
+ * session JSONL) and the speculative-synthesis contribution (no chain
+ * entries for events nobody consults).
+ *
+ * Observers with `writes === undefined` or `writes: []` are kept
+ * unconditionally — without a declaration we can't prove they're
+ * unused, and `[]` is conservative parity with undeclared. Plugin
+ * authors are encouraged to declare `writes` both for this
+ * optimization and for `defineConfig`'s compile-time type inference.
+ *
+ * Pure function — no logging. Callers (session-runtime, testing)
+ * log on drop so tests can inspect `dropped` directly without
+ * intercepting stdout.
+ */
+
+import type { Observer, Rule } from "../schema.ts";
+
+/** An observer dropped by {@link dropUnusedObservers}. */
+export interface DroppedObserver {
+  readonly name: string;
+  readonly writes: readonly string[];
+  readonly reason: "unused-writes";
+}
+
+/**
+ * Partition `observers` into kept and dropped based on whether each
+ * observer's declared writes are consumed by any rule.
+ *
+ * @param observers - Observers to filter (any origin — plugin-merged
+ *   or user-authored).
+ * @param rules - Full rule set whose `happened.event` / `happened.since`
+ *   references determine consumption. Disabled rules should already
+ *   be filtered out by the caller — this helper honors whatever's
+ *   passed in.
+ */
+export function dropUnusedObservers(
+  observers: readonly Observer[],
+  rules: readonly Rule[],
+): { kept: readonly Observer[]; dropped: readonly DroppedObserver[] } {
+  const consumed = collectConsumedEvents(rules);
+  const kept: Observer[] = [];
+  const dropped: DroppedObserver[] = [];
+  for (const o of observers) {
+    if (o.writes === undefined || o.writes.length === 0) {
+      kept.push(o);
+      continue;
+    }
+    if (o.writes.some((w) => consumed.has(w))) {
+      kept.push(o);
+      continue;
+    }
+    dropped.push({
+      name: o.name,
+      writes: o.writes,
+      reason: "unused-writes",
+    });
+  }
+  return { kept, dropped };
+}
+
+/** Collect every event referenced by any rule's `happened.event` /
+ *  `happened.since`. Rules without `when.happened` contribute nothing. */
+function collectConsumedEvents(rules: readonly Rule[]): Set<string> {
+  const consumed = new Set<string>();
+  for (const rule of rules) {
+    const h = rule.when?.happened;
+    if (h === undefined) continue;
+    if (typeof h.event === "string") consumed.add(h.event);
+    if (typeof h.since === "string") consumed.add(h.since);
+  }
+  return consumed;
+}

package/src/internal/finalize-plugin-state.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Late-stage plugin-state finalization shared by `buildSessionRuntime`,
+ * `loadHarness`, and the CLI `list` path. Centralizes the
+ * `dropUnusedObservers` + breadcrumb pass so all three stay byte-equal
+ * in their breadcrumb output and observer-drop semantics.
+ *
+ * Drops observers whose declared `writes` are unconsumed across both
+ * plugin-merged and user-authored streams, using the union of all
+ * rule `happened` references. Emits an `info`-level breadcrumb per
+ * dropped observer so plugin authors debugging "why isn't my
+ * observer firing?" have a trail to follow without it bubbling up as
+ * a diagnostic the user has to action.
+ *
+ * Callers must pre-filter `config.disabledRules` out of `userRules`
+ * — see {@link dropUnusedObservers}'s contract.
+ */
+
+import type { Observer, Rule } from "../schema.ts";
+import { dropUnusedObservers } from "./drop-unused-observers.ts";
+
+export function finalizePluginState(
+  userRules: readonly Rule[],
+  pluginRules: readonly Rule[],
+  userObservers: readonly Observer[],
+  pluginObservers: readonly Observer[],
+): {
+  pluginKept: readonly Observer[];
+  userKept: readonly Observer[];
+} {
+  const allRules = [...userRules, ...pluginRules];
+  const pluginDrop = dropUnusedObservers(pluginObservers, allRules);
+  const userDrop = dropUnusedObservers(userObservers, allRules);
+  for (const d of [...pluginDrop.dropped, ...userDrop.dropped]) {
+    console.info(
+      `[pi-steering] observer '${d.name}' dropped; its writes ` +
+        `(${d.writes.join(", ")}) are not consumed by any rule`,
+    );
+  }
+  return { pluginKept: pluginDrop.kept, userKept: userDrop.kept };
+}

package/src/internal/merge-observers.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Shared observer-merge helper used by both the evaluator's reverse
+ * index (`when.happened` with `in: "tool_call"`) and the observer-dispatcher's
+ * fire list.
+ *
+ * Both callers need the same answer to the question "what observers
+ * does this config have, after resolving plugins and applying user
+ * overrides?" Keeping a single implementation here prevents silent
+ * drift — if the dispatcher drops a plugin observer because a user
+ * observer shadows it by name, the evaluator's reverse-index must do
+ * the same, or tool_call-scope speculative allow can grant on a watch
+ * pattern that will never actually fire.
+ *
+ * Merge semantics (must match `buildObserverDispatcher`):
+ *   1. User observers come first (user-wins on name collision).
+ *   2. Plugin observers fill in any names not already seen.
+ *
+ * The order mirrors the rule-list "user overrides plugin by declaring
+ * their own" pattern documented on `buildObserverDispatcher`.
+ */
+
+import type { Observer } from "../schema.ts";
+
+/**
+ * Merge user-level and plugin-level observers into a single list with
+ * first-registered dedup by `name`. User observers always precede
+ * plugin observers of the same name.
+ *
+ * Returns a fresh array; neither input is mutated.
+ */
+export function mergeObserversUserFirst(
+  userObservers: readonly Observer[],
+  pluginObservers: readonly Observer[],
+): Observer[] {
+  const merged: Observer[] = [];
+  const seen = new Set<string>();
+  for (const o of userObservers) {
+    if (seen.has(o.name)) continue;
+    seen.add(o.name);
+    merged.push(o);
+  }
+  for (const o of pluginObservers) {
+    if (seen.has(o.name)) continue;
+    seen.add(o.name);
+    merged.push(o);
+  }
+  return merged;
+}

package/src/internal/pattern-utils.test.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isPattern } from "./pattern-utils.ts";
+
+describe("isPattern", () => {
+  it("narrows strings to Pattern", () => {
+    assert.equal(isPattern("hello"), true);
+    assert.equal(isPattern(""), true);
+  });
+
+  it("narrows RegExp to Pattern", () => {
+    assert.equal(isPattern(/foo/), true);
+    assert.equal(isPattern(/(?:)/), true);
+    assert.equal(isPattern(/^bar$/i), true);
+  });
+
+  it("rejects primitives that aren't string", () => {
+    assert.equal(isPattern(123), false);
+    assert.equal(isPattern(true), false);
+    assert.equal(isPattern(false), false);
+    assert.equal(isPattern(null), false);
+    assert.equal(isPattern(undefined), false);
+    assert.equal(isPattern(Symbol("foo")), false);
+  });
+
+  it("rejects objects + arrays", () => {
+    assert.equal(isPattern({}), false);
+    assert.equal(isPattern({ pattern: "x" }), false);
+    assert.equal(isPattern([]), false);
+    assert.equal(isPattern(["foo"]), false);
+    assert.equal(isPattern([/foo/]), false);
+  });
+
+  it("narrows correctly through Array.every (compile-time check)", () => {
+    // This is the exact use site that motivated the type predicate:
+    // `arr.every(isPattern)` MUST narrow `unknown[]` to `Pattern[]`
+    // at the type level. The runtime assertion below is incidental;
+    // the real test is that this file typechecks.
+    const arr: unknown[] = ["foo", /bar/];
+    if (arr.every(isPattern)) {
+      // Inside this branch, `arr` is Pattern[]; the .some call
+      // would be a type error if narrowing weren't working.
+      const someResult: boolean = arr.some(
+        (p) => typeof p === "string" || p instanceof RegExp,
+      );
+      assert.equal(someResult, true);
+    }
+  });
+});

package/src/internal/pattern-utils.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Shared pattern utilities reused across the engine and the gitPlugin's
+ * predicate handlers. Lives in `internal/` because both the engine
+ * (`evaluator-internals/predicates.ts`) and the gitPlugin
+ * (`plugins/git/predicates.ts`) need the same `Pattern` narrowing
+ * helper, and the engine cannot import from a plugin without inverting
+ * the dependency graph.
+ *
+ * The two normalization sites stay independent (the engine's
+ * `evaluateCwd` keeps its inline fast-path optimization for the
+ * single-pattern shorthand; the gitPlugin's `unwrapPatternArg`
+ * normalizes once and shares the result across `branch` / `upstream`
+ * / `remote`); only the type predicate is shared.
+ */
+
+import type { Pattern } from "../schema.ts";
+
+/**
+ * Type predicate for {@link Pattern} (`string | RegExp`). Used by the
+ * pattern-valued predicates (`cwd`, `branch`, `upstream`, `remote`) to
+ * narrow `unknown[]` array elements to `Pattern[]` for safe iteration:
+ *
+ *     if (Array.isArray(value) && value.every(isPattern)) {
+ *         // value is Pattern[] here
+ *         return value.some(p => matchesPattern(p, target));
+ *     }
+ *
+ * Without the `v is Pattern` type predicate, the same expression
+ * (`value.every(v => typeof v === "string" || v instanceof RegExp)`)
+ * does NOT narrow `value` from `unknown[]` to `Pattern[]` — TypeScript
+ * needs the explicit type-predicate signature for the narrowing to
+ * propagate through `Array.isArray` + `.every`.
+ */
+export const isPattern = (v: unknown): v is Pattern =>
+  typeof v === "string" || v instanceof RegExp;

package/src/internal/ref-text.test.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+//
+// Unit tests for refToText. The function is a thin wrapper around
+// unbash-walker's getBasename / getCommandArgs; these tests pin the
+// exact rendered shape observer-watch patterns see so a future
+// refactor that accidentally changes spacing (e.g. drops the trim)
+// doesn't silently break every `watch.inputMatches.command` in the
+// wild.
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { extractAllCommandsFromAST, parse } from "@cad0p/unbash-walker";
+import { refToText } from "./ref-text.ts";
+
+function refsFor(command: string) {
+  const script = parse(command);
+  return extractAllCommandsFromAST(script, command);
+}
+
+describe("refToText", () => {
+  it("renders bare command with no args", () => {
+    const [ref] = refsFor("alpha");
+    assert.equal(refToText(ref!), "alpha");
+  });
+
+  it("renders command with single arg", () => {
+    const [ref] = refsFor("git push");
+    assert.equal(refToText(ref!), "git push");
+  });
+
+  it("renders command with multiple args, space-joined", () => {
+    const [ref] = refsFor("git push origin main --force");
+    assert.equal(refToText(ref!), "git push origin main --force");
+  });
+
+  it("trims trailing space from empty args list", () => {
+    const [ref] = refsFor("noop");
+    assert.equal(
+      refToText(ref!),
+      "noop",
+      "no trailing space when args is empty",
+    );
+  });
+
+  it("basename strips path prefix", () => {
+    const [ref] = refsFor("/usr/local/bin/cr --all");
+    assert.equal(
+      refToText(ref!),
+      "cr --all",
+      "rendered command uses basename, not absolute path",
+    );
+  });
+});