@cad0p/pi-steering 0.1.0

package/src/plugins/git/branch-tracker.test.ts

@@ -0,0 +1,281 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Tests for the git plugin's branch tracker (`./branch-tracker.ts`).
+ *
+ * These tests exercise the tracker directly via `walk()` from
+ * unbash-walker, with small hand-crafted bash scripts. They pin the
+ * modifier's semantics independently of the evaluator / predicate
+ * wiring. Evaluator-level behaviour is covered by `./integration.test.ts`.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  type CommandRef,
+  extractAllCommandsFromAST,
+  getBasename,
+  getCommandArgs,
+  parse as parseBash,
+  walk,
+} from "@cad0p/unbash-walker";
+import { branchTracker } from "./branch-tracker.ts";
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+interface WalkedCommand {
+  ref: CommandRef;
+  text: string;
+  branch: string;
+}
+
+/**
+ * Walk `script` with only the branch tracker and return one entry per
+ * extracted command ref with its stringified form and snapshot branch.
+ *
+ * `initialBranch` seeds the tracker's starting value so tests can pin
+ * both "checkout advances" and "other subcommands preserve" shapes.
+ */
+function walkBranches(script: string, initialBranch: string): WalkedCommand[] {
+  const ast = parseBash(script);
+  const refs = extractAllCommandsFromAST(ast, script);
+  const result = walk(
+    ast,
+    { branch: initialBranch },
+    { branch: branchTracker },
+    refs,
+  );
+  return refs.map((ref) => {
+    const snap = result.get(ref);
+    return {
+      ref,
+      text: `${getBasename(ref)} ${getCommandArgs(ref).join(" ")}`.trim(),
+      branch: (snap?.branch as string | undefined) ?? "<missing>",
+    };
+  });
+}
+
+/** Find the recorded branch for the first command whose text starts with `prefix`. */
+function branchOf(walked: WalkedCommand[], prefix: string): string {
+  const hit = walked.find((w) => w.text.startsWith(prefix));
+  if (!hit) {
+    throw new Error(
+      `no command starting with "${prefix}" in walked set: ` +
+        walked.map((w) => w.text).join(" | "),
+    );
+  }
+  return hit.branch;
+}
+
+// ---------------------------------------------------------------------------
+// Sequential subcommand advancement
+// ---------------------------------------------------------------------------
+
+describe("branchTracker: checkout / switch advance the branch", () => {
+  it("`git checkout feat` advances to feat for subsequent commands", () => {
+    const walked = walkBranches("git checkout feat && git status", "main");
+    // The checkout ITSELF is recorded with the pre-checkout branch -
+    // same convention as cd in cwdTracker: a sequential modifier's
+    // effect only propagates to SUBSEQUENT siblings.
+    assert.equal(branchOf(walked, "git checkout"), "main");
+    assert.equal(branchOf(walked, "git status"), "feat");
+  });
+
+  it("`git switch main` advances to main", () => {
+    const walked = walkBranches("git switch main && git status", "feat");
+    assert.equal(branchOf(walked, "git status"), "main");
+  });
+
+  it("`git checkout -b new-branch` advances to new-branch", () => {
+    const walked = walkBranches(
+      "git checkout -b new-branch && git push",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git push"), "new-branch");
+  });
+
+  it("`git switch -c other-branch` advances to other-branch", () => {
+    const walked = walkBranches(
+      "git switch -c other-branch && git commit",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git commit"), "other-branch");
+  });
+
+  it("chained checkouts - final state wins", () => {
+    const walked = walkBranches(
+      "git checkout A && git checkout B && git status",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git status"), "B");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Non-advancing subcommands
+// ---------------------------------------------------------------------------
+
+describe("branchTracker: non-checkout subcommands preserve branch", () => {
+  it("`git commit` does not change the branch", () => {
+    const walked = walkBranches(
+      "git status && git commit -m 'x' && git log",
+      "feat",
+    );
+    assert.equal(branchOf(walked, "git status"), "feat");
+    assert.equal(branchOf(walked, "git commit"), "feat");
+    assert.equal(branchOf(walked, "git log"), "feat");
+  });
+
+  it("`git` with no subcommand does not change the branch", () => {
+    const walked = walkBranches("git && git commit", "feat");
+    assert.equal(branchOf(walked, "git commit"), "feat");
+  });
+
+  it('`git commit -m "$MSG"` (non-static args) does not collapse to unknown', () => {
+    // Regression guard: the modifier must return `current` (not
+    // `undefined`) when the subcommand isn't a branch change. A
+    // naive `isStaticallyResolvable(args[1])` check on `-m` would
+    // work, but a non-static later arg must not poison the state.
+    const walked = walkBranches('git commit -m "$MSG" && git push', "feat");
+    assert.equal(branchOf(walked, "git push"), "feat");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Unknown collapse on dynamic targets
+// ---------------------------------------------------------------------------
+
+describe("branchTracker: non-static targets collapse to unknown", () => {
+  it("`git checkout $VAR` produces unknown for subsequent commands", () => {
+    const walked = walkBranches("git checkout $VAR && git status", "main");
+    assert.equal(branchOf(walked, "git status"), "unknown");
+  });
+
+  it("`git checkout -b $NEW` produces unknown", () => {
+    const walked = walkBranches("git checkout -b $NEW && git status", "main");
+    assert.equal(branchOf(walked, "git status"), "unknown");
+  });
+
+  it('`git switch "$BR"` (double-quoted with expansion) produces unknown', () => {
+    const walked = walkBranches('git switch "$BR" && git log', "main");
+    assert.equal(branchOf(walked, "git log"), "unknown");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Subshell isolation
+// ---------------------------------------------------------------------------
+
+describe("branchTracker: subshell isolation", () => {
+  it("`(git checkout A)` does not escape the subshell", () => {
+    const walked = walkBranches("(git checkout A) && git status", "main");
+    // `git status` runs after the subshell in the OUTER scope - branch
+    // should still be the pre-subshell value.
+    assert.equal(branchOf(walked, "git status"), "main");
+  });
+
+  it("subshell body sees the outer branch value", () => {
+    const walked = walkBranches(
+      "git checkout feat && (git log && git status)",
+      "main",
+    );
+    // Both commands inside the subshell see `feat` (the propagated
+    // outer value at the point the subshell starts).
+    assert.equal(branchOf(walked, "git log"), "feat");
+    assert.equal(branchOf(walked, "git status"), "feat");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Pre-subcommand flags
+// ---------------------------------------------------------------------------
+
+describe("branchTracker: pre-subcommand flags", () => {
+  it("`git -C /other checkout feat && git commit` advances branch to feat", () => {
+    const walked = walkBranches(
+      "git -C /other checkout feat && git commit -m 'x'",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git commit"), "feat");
+  });
+
+  it("`git -c key=val checkout feat` advances (-c consumes next arg)", () => {
+    const walked = walkBranches(
+      "git -c color.ui=never checkout feat && git commit",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git commit"), "feat");
+  });
+
+  it("`git --no-pager checkout feat` advances (long flag without value)", () => {
+    const walked = walkBranches(
+      "git --no-pager checkout feat && git commit",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git commit"), "feat");
+  });
+
+  it("`git --git-dir=/g checkout feat` advances (long flag with =value)", () => {
+    const walked = walkBranches(
+      "git --git-dir=/g checkout feat && git commit",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git commit"), "feat");
+  });
+
+  it("`git -C /other checkout -b new-branch` advances via -b path", () => {
+    const walked = walkBranches(
+      "git -C /other checkout -b new-branch && git commit",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git commit"), "new-branch");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Pathological cases (documented corners)
+// ---------------------------------------------------------------------------
+
+describe("branchTracker: pathological cases (documented corners)", () => {
+  it("`git checkout --help` leaves branch unchanged", () => {
+    const walked = walkBranches("git checkout --help && git status", "main");
+    assert.equal(branchOf(walked, "git status"), "main");
+  });
+
+  it("`git checkout .` sets branch to `.` (documented false-positive - path reset)", () => {
+    // Real git interprets `.` as "reset path", not a branch. Our tracker
+    // treats the first static arg after checkout as the branch name,
+    // which is wrong in this corner. Documented accepted false-positive.
+    const walked = walkBranches("git checkout . && git status", "main");
+    assert.equal(branchOf(walked, "git status"), ".");
+  });
+
+  it("`git checkout -- file.txt` sets branch to `--` (documented false-positive)", () => {
+    const walked = walkBranches(
+      "git checkout -- file.txt && git status",
+      "main",
+    );
+    assert.equal(branchOf(walked, "git status"), "--");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Motivating case: `git checkout A && git commit`
+// ---------------------------------------------------------------------------
+
+describe("branchTracker: the ADR's motivating case", () => {
+  it("`git checkout main && git commit` reports branch=main on the commit", () => {
+    // This is the KEY test. A session-level "current branch" check
+    // would see the PRE-checkout branch and miss this case. The
+    // walker-backed tracker folds the checkout into the commit's
+    // branch snapshot, so a `when.branch: /^main$/` predicate fires.
+    const walked = walkBranches(
+      "git checkout main && git commit -m 'x'",
+      "feat",
+    );
+    assert.equal(branchOf(walked, "git commit"), "main");
+  });
+});

package/src/plugins/git/branch-tracker.ts

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * `branch` tracker for the git plugin.
+ *
+ * Models the effective git branch AT EACH extracted command within a
+ * single `tool_call`. The motivating case is the ADR's
+ * `git checkout A && git commit` example: a session-level
+ * "current branch" query would miss the mid-command checkout and allow
+ * the commit on what looks like a non-protected branch. A walker-backed
+ * tracker folds the `git checkout` delta into the branch value seen by
+ * the subsequent `git commit`, so a rule gated on
+ * `when: { branch: /^main$/ }` correctly fires if the chain ends up on
+ * `main`.
+ *
+ * Semantics:
+ *   - `git checkout X`  - sequential; branch becomes `X` for the rest
+ *     of this scope.
+ *   - `git switch X`    - sequential; same as above.
+ *   - `git checkout -b NEW` / `git switch -c NEW` - sequential; branch
+ *     becomes `NEW`. The `-b` / `-c` token is consumed; the following
+ *     argument is the new branch name.
+ *   - Anything else under `git` (including `git commit`, `git status`,
+ *     `git checkout -- FILE`) leaves the branch unchanged. Returning
+ *     `current` (not `undefined`) is important: a `git commit` that
+ *     happens to carry a non-static arg (e.g. `-m "$MSG"`) must NOT
+ *     collapse branch state to `unknown`.
+ *   - Non-static branch names (`git checkout $BR`, `git checkout "$BR"`)
+ *     return `undefined`, which the walker translates to the tracker's
+ *     `unknown` sentinel. Predicates then apply their `onUnknown`
+ *     policy (default `"block"` - see the `branch` predicate handler).
+ *
+ * Subshells: `isolated` - a `(git checkout X)` inside parens cannot
+ * change the enclosing shell's branch (real git semantics - the
+ * subshell has no effect on the parent's working tree state for this
+ * dimension).
+ *
+ * The tracker distinguishes two "I don't know the branch" states so
+ * predicates can apply the correct policy:
+ *
+ *   - `initial: NO_CHECKOUT_IN_CHAIN` - no branch-changing modifier
+ *     has fired in this ref's scope. The plugin cannot synchronously
+ *     know the session's current branch at construction time; the
+ *     `branch` predicate handler shells out via `ctx.exec("git",
+ *     ["branch", "--show-current"])` to learn it. (A session-start
+ *     prefetch is a reasonable future optimization but out of scope
+ *     here.)
+ *   - `unknown: "unknown"` - a modifier FIRED but couldn't resolve
+ *     statically (e.g. `git checkout $VAR`). The predicate must NOT
+ *     shell out in this case: `git branch --show-current` would
+ *     return the PRE-checkout branch and silently defeat the
+ *     walker's tracking. Predicates apply their `onUnknown` policy
+ *     instead (default `"block"` -> fail-closed).
+ *
+ * The `NO_CHECKOUT_IN_CHAIN` sentinel is chosen to be a string that
+ * cannot occur as a real git branch name (git refuses refs containing
+ * `:`). Exported so tests and plugin authors can reference it; it
+ * should never be constructed ad-hoc.
+ *
+ * ## Note for plugin authors
+ *
+ * This tracker is a canonical example of the strict Tracker contract -
+ * unresolvable modifier targets return `undefined`, NOT `current`. The
+ * built-in `cwdTracker.cd` modifier is a documented Phase-1 exception;
+ * do not copy its "return current" shortcut in new trackers.
+ */
+
+import {
+  isStaticallyResolvable,
+  type Modifier,
+  type Tracker,
+} from "@cad0p/unbash-walker";
+
+/**
+ * Sentinel value for `branchTracker.initial` - marks "no branch-
+ * changing modifier has fired in this ref's scope yet". Distinct
+ * from the `"unknown"` sentinel (which marks "a modifier DID fire
+ * but couldn't resolve statically"). See the file JSDoc for why the
+ * distinction matters to the `branch` predicate's exec fallback
+ * decision. The colon is chosen because git rejects it in branch
+ * names, so this value cannot collide with a real branch.
+ */
+export const NO_CHECKOUT_IN_CHAIN = "pi-steering:no-checkout-in-chain";
+
+/** Branch-changing git subcommands. */
+const CHECKOUT_SUBCOMMANDS = new Set(["checkout", "switch"]);
+
+/** `git checkout -b NEW` / `git switch -c NEW` - new-branch flags. */
+const NEW_BRANCH_FLAGS = new Set(["-b", "-c"]);
+
+/**
+ * Sequential modifier that applies to every `git`-basename command.
+ *
+ * Returns the new branch for `checkout` / `switch` invocations;
+ * returns `current` unchanged for every other git subcommand (so
+ * `git commit -m "x"` does NOT collapse the branch to `unknown`);
+ * returns `undefined` when the target branch name can't be resolved
+ * statically.
+ *
+ * Pre-subcommand flags are skipped before we look at the subcommand
+ * token. Git accepts `git -C PATH`, `git -c KEY=VAL`, `git --no-pager`,
+ * `git --git-dir=/x`, `git --work-tree=/y`, `git --paginate`, etc.
+ * before the subcommand. Without this skip, `git -C /other checkout
+ * feat` would look at the `-C` flag as the subcommand, miss the
+ * checkout, and silently bypass `no-main-commit`. This mirrors the
+ * `applyGitCwd` flag scanner in `unbash-walker/src/trackers/cwd.ts`:
+ * only `-C <path>` and `-c <key=value>` consume an additional token;
+ * every other flag form (short cluster, long with or without attached
+ * value) is a single token.
+ */
+const gitBranchModifier: Modifier<string> = {
+  scope: "sequential",
+  apply: (args, current) => {
+    // Scan past pre-subcommand flags to find the real subcommand.
+    // Known value-consuming flags: `-C <path>`, `-c <key=val>`.
+    // Others (`--no-pager`, `--git-dir=/x`, `--work-tree=/y`,
+    // `--paginate`, `-p`, etc.) are single tokens.
+    let i = 0;
+    while (i < args.length) {
+      const tokWord = args[i];
+      const tok = tokWord?.value ?? tokWord?.text ?? "";
+      if (!tok.startsWith("-")) break; // found the subcommand
+      if (tok === "-C" || tok === "-c") {
+        i += 2;
+        continue;
+      }
+      i++; // --long-flag, --long=value, or -shortcluster
+    }
+
+    // No subcommand - e.g. bare `git` or `git --help`. Branch unchanged.
+    const subcmdWord = args[i];
+    if (!subcmdWord) return current;
+    const subcmd = subcmdWord.value ?? subcmdWord.text;
+    if (!subcmd || !CHECKOUT_SUBCOMMANDS.has(subcmd)) return current;
+
+    // `git checkout` / `git switch` with no further args: also a
+    // help / error case. Leave branch alone.
+    const firstArgWord = args[i + 1];
+    if (!firstArgWord) return current;
+    const firstArg = firstArgWord.value ?? firstArgWord.text;
+    if (firstArg === undefined) return current;
+
+    // `git checkout --help` / `git checkout -h` - help request, not a
+    // branch change. Every other unrecognised flag form (e.g. `--`, `.`,
+    // `--force`) still flows through the default branch-name path and
+    // is accepted as a documented false-positive (see test cases).
+    if (firstArg === "--help" || firstArg === "-h") return current;
+
+    // `git checkout -b NEW` / `git switch -c NEW` - the branch
+    // argument is at position i + 2.
+    if (NEW_BRANCH_FLAGS.has(firstArg)) {
+      const newBranchWord = args[i + 2];
+      if (!newBranchWord) return current;
+      if (!isStaticallyResolvable(newBranchWord)) return undefined;
+      const newBranch = newBranchWord.value ?? newBranchWord.text;
+      return newBranch === undefined ? current : newBranch;
+    }
+
+    // Plain `git checkout X` / `git switch X`. Note: `git checkout --
+    // FILE` (restore path) is NOT a branch change, but the first arg
+    // `--` happens to be statically resolvable AND `!= undefined`.
+    // That's a false-positive corner we accept for Phase 4 - agents
+    // rarely emit the `--` separator form, and the alternative
+    // (hard-coding a `--` check) brittles against other pathspec
+    // conventions. Follow-up if it bites.
+    if (!isStaticallyResolvable(firstArgWord)) return undefined;
+    return firstArg;
+  },
+};
+
+/**
+ * The branch tracker.
+ *
+ * Registered by the git plugin under `trackers.branch`. Walker-merged
+ * with any future plugin wanting to extend branch semantics (though
+ * the tracker name `branch` is expected to stay owned by the git
+ * plugin - name collisions are a hard error per the plugin-merger).
+ */
+export const branchTracker: Tracker<string> = {
+  initial: NO_CHECKOUT_IN_CHAIN,
+  unknown: "unknown",
+  modifiers: {
+    git: gitBranchModifier,
+  },
+  subshellSemantics: "isolated",
+};