@cad0p/pi-steering 0.1.0

package/src/plugins/git/cwd-extensions.test.ts

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Tests for the git plugin's cwd tracker extension
+ * (`./cwd-extensions.ts`).
+ *
+ * These tests walk scripts against a MANUALLY composed cwd tracker -
+ * the core `cwdTracker` with the plugin's `gitCwdExtensions` appended
+ * under basename `git`. This mirrors exactly what the plugin merger
+ * produces at runtime, without pulling the merger into every test.
+ * See `./integration.test.ts` for end-to-end behavior through the
+ * evaluator.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  type CommandRef,
+  cwdTracker,
+  extractAllCommandsFromAST,
+  getBasename,
+  getCommandArgs,
+  type Modifier,
+  parse as parseBash,
+  type Tracker,
+  walk,
+} from "@cad0p/unbash-walker";
+import { gitCwdExtensions } from "./cwd-extensions.ts";
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a cwd tracker with the plugin's extensions appended to the
+ * core `git` basename slot. The same shape the plugin merger produces
+ * at runtime via `composeTracker`.
+ */
+function composeCwdWithExtensions(): Tracker<string> {
+  const existing = cwdTracker.modifiers["git"];
+  const existingList: Modifier<string>[] = Array.isArray(existing)
+    ? ([...existing] as Modifier<string>[])
+    : existing !== undefined
+      ? [existing as Modifier<string>]
+      : [];
+  return {
+    ...cwdTracker,
+    modifiers: {
+      ...cwdTracker.modifiers,
+      git: [
+        ...existingList,
+        ...(gitCwdExtensions as readonly Modifier<string>[]),
+      ],
+    },
+  };
+}
+
+interface WalkedCommand {
+  ref: CommandRef;
+  text: string;
+  cwd: string;
+}
+
+function walkCwd(script: string, initialCwd = "/initial"): WalkedCommand[] {
+  const tracker = composeCwdWithExtensions();
+  const ast = parseBash(script);
+  const refs = extractAllCommandsFromAST(ast, script);
+  const result = walk(ast, { cwd: initialCwd }, { cwd: tracker }, refs);
+  return refs.map((ref) => {
+    const snap = result.get(ref);
+    return {
+      ref,
+      text: `${getBasename(ref)} ${getCommandArgs(ref).join(" ")}`.trim(),
+      cwd: (snap?.cwd as string | undefined) ?? "<missing>",
+    };
+  });
+}
+
+function cwdOf(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.cwd;
+}
+
+// ---------------------------------------------------------------------------
+// --git-dir=
+// ---------------------------------------------------------------------------
+
+describe("gitCwdExtensions: --git-dir=PATH", () => {
+  it("absolute path replaces the effective cwd", () => {
+    const walked = walkCwd("git --git-dir=/b status");
+    assert.equal(cwdOf(walked, "git --git-dir"), "/b");
+  });
+
+  it("relative path joins against the current cwd", () => {
+    const walked = walkCwd("git --git-dir=subrepo status", "/work");
+    assert.equal(cwdOf(walked, "git --git-dir"), "/work/subrepo");
+  });
+
+  it("per-command semantics - does not propagate to the next command", () => {
+    // Per-command scope: the modifier applies to THIS command only.
+    // The next sibling command sees the pre-modifier cwd.
+    const walked = walkCwd("git --git-dir=/b status && git log", "/initial");
+    assert.equal(cwdOf(walked, "git --git-dir"), "/b");
+    assert.equal(cwdOf(walked, "git log"), "/initial");
+  });
+
+  it("non-static target collapses cwd to unknown", () => {
+    // `--git-dir=$V` - the overall Word is non-static via
+    // SimpleExpansion. Extension returns undefined; walker emits
+    // the cwd tracker's `"unknown"` sentinel.
+    const walked = walkCwd("git --git-dir=$V status");
+    assert.equal(cwdOf(walked, "git --git-dir"), "unknown");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// --work-tree=
+// ---------------------------------------------------------------------------
+
+describe("gitCwdExtensions: --work-tree=PATH", () => {
+  it("absolute path replaces the effective cwd", () => {
+    const walked = walkCwd("git --work-tree=/c status");
+    assert.equal(cwdOf(walked, "git --work-tree"), "/c");
+  });
+
+  it("relative path joins against the current cwd", () => {
+    const walked = walkCwd("git --work-tree=tree status", "/repo");
+    assert.equal(cwdOf(walked, "git --work-tree"), "/repo/tree");
+  });
+
+  it("`git --work-tree=$V status` collapses cwd to unknown", () => {
+    const walked = walkCwd("git --work-tree=$V status");
+    assert.equal(cwdOf(walked, "git --work-tree"), "unknown");
+  });
+
+  it("`--work-tree=/t` is per-command (doesn't propagate)", () => {
+    const walked = walkCwd("git --work-tree=/t status && git log", "/initial");
+    assert.equal(cwdOf(walked, "git --work-tree"), "/t");
+    assert.equal(cwdOf(walked, "git log"), "/initial");
+  });
+
+  it("multiple --git-dir= / --work-tree= flags compose (last absolute wins)", () => {
+    const walked = walkCwd("git --git-dir=/a --work-tree=/b status");
+    assert.equal(cwdOf(walked, "git --git-dir"), "/b");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Composition with the core `-C` modifier
+// ---------------------------------------------------------------------------
+
+describe("gitCwdExtensions: composition with core -C", () => {
+  // Pins the "extension wins" precedence. The walker runs per-command
+  // modifiers left-to-right; the plugin merger registers the extension
+  // AFTER the core modifier, so the extension's value is applied last.
+  // This matches git's documented precedence for --git-dir / --work-tree
+  // over -C.
+  it("`git -C /a --git-dir=/b status` -> /b (extension wins on absolute)", () => {
+    const walked = walkCwd("git -C /a --git-dir=/b status");
+    assert.equal(cwdOf(walked, "git -C"), "/b");
+  });
+
+  it("`git --git-dir=/b -C /a status` -> /b (same verdict regardless of source order)", () => {
+    // Token order in the source doesn't change the modifier
+    // composition order - that's determined by registration in the
+    // plugin merger. Both orders produce the same final cwd here.
+    const walked = walkCwd("git --git-dir=/b -C /a status");
+    assert.equal(cwdOf(walked, "git --git-dir"), "/b");
+  });
+
+  it("`git -C /a --git-dir=b status` -> /a/b (extension joins relative against -C result)", () => {
+    // The extension's modifier runs SECOND with the core modifier's
+    // output (/a) as its running cwd. A relative --git-dir joins
+    // against that, producing /a/b.
+    const walked = walkCwd("git -C /a --git-dir=b status");
+    assert.equal(cwdOf(walked, "git -C"), "/a/b");
+  });
+
+  it("`git -C /a status` (no extension flag) still routes through the core -C", () => {
+    // Regression guard: adding the extension must not disturb
+    // bare `-C` behavior.
+    const walked = walkCwd("git -C /a status");
+    assert.equal(cwdOf(walked, "git -C"), "/a");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Non-interference
+// ---------------------------------------------------------------------------
+
+describe("gitCwdExtensions: non-interference", () => {
+  it("`git status` (no cwd flags) preserves the current cwd", () => {
+    const walked = walkCwd("git status", "/work");
+    assert.equal(cwdOf(walked, "git status"), "/work");
+  });
+
+  it("`git log --grep='--git-dir=foo'` does NOT match inside a quoted arg", () => {
+    // The grep value is a SINGLE token whose text starts with
+    // `--grep=`, not `--git-dir=`. Regression guard against the
+    // naive scan-all-args trap.
+    const walked = walkCwd("git log --grep='--git-dir=foo'", "/initial");
+    assert.equal(cwdOf(walked, "git log"), "/initial");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Accepted false-positives
+// ---------------------------------------------------------------------------
+
+describe("cwd extensions: accepted false-positives", () => {
+  it("`git log --git-dir=/repo` over-matches (post-subcommand flag)", () => {
+    // Documented accepted false-positive: we scan all args; real git
+    // treats post-subcommand --git-dir= as a pathspec. Over-match rate
+    // is low; stopping at subcommand would break -C composition.
+    const walked = walkCwd("git log --git-dir=/repo", "/start");
+    assert.equal(cwdOf(walked, "git log"), "/repo");
+  });
+
+  it("`git diff -- --git-dir=/x` over-matches (after `--` should be pathspec)", () => {
+    const walked = walkCwd("git diff -- --git-dir=/x", "/start");
+    assert.equal(cwdOf(walked, "git diff"), "/x");
+  });
+});

package/src/plugins/git/cwd-extensions.ts

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * `cwd` tracker extensions for the git plugin.
+ *
+ * The built-in `cwdTracker` (in unbash-walker) handles `git -C DIR
+ * subcmd`. Two narrower git flags - `--git-dir=/path` and
+ * `--work-tree=/path` - express the same "run this command as if the
+ * working directory were /path" intent, but weren't modelled in the
+ * walker's core to keep its git knowledge minimal. Parsing them lives
+ * in the git plugin as a tracker extension: registered under
+ * `trackerExtensions.cwd.git`, the modifier layers on top of the core
+ * cwd tracker's own `git` per-command modifier.
+ *
+ * Scope is `per-command` - consistent with `-C` and git's own runtime
+ * behavior: these flags affect only the command they're attached to.
+ *
+ * Composition with `-C`:
+ *
+ *   `git -C /a --git-dir=/b status`
+ *
+ * The plugin-merger appends this extension's modifier AFTER the core
+ * `-C` modifier under the same basename. The walker then runs BOTH
+ * modifiers left-to-right against the same arg list, each layering
+ * its own contribution on top of the running recorded value:
+ *
+ *   1. Core `-C /a` modifier (scans pre-subcommand flags only):
+ *        running cwd "/initial" -> "/a"
+ *   2. This `--git-dir=/b` modifier (scans all args for the two
+ *      specific flag forms):
+ *        running cwd "/a"        -> "/b"
+ *
+ * The LATER modifier wins on absolute paths; for relative paths it
+ * joins against the running value from the previous step. Test
+ * expectation for `git -C /a --git-dir=b status` is `/a/b`.
+ *
+ * Order in the source matters too:
+ *
+ *   - `git --git-dir=/b -C /a status` -> `/b` (core `-C` runs on
+ *     the pre-sequential value `/initial`, producing `/a`; then
+ *     this modifier runs against the same args, overriding to
+ *     `/b`).
+ *   - `git -C /a --git-dir=/b status` -> `/b` (same left-to-right
+ *     modifier order; the core scanner produces `/a`, this one
+ *     overrides to `/b`).
+ *
+ * In both cases the `--git-dir=` / `--work-tree=` flags win, matching
+ * git's documented precedence.
+ *
+ * Known limitations:
+ *
+ *   - `--git-dir` without an `=` (space-separated form:
+ *     `git --git-dir /path ...`) is NOT handled. Both git and shell
+ *     tokenize this as two words; walker modifiers today only see the
+ *     single `--git-dir` token. Wiring a two-token form is possible
+ *     but agents overwhelmingly emit the `=` form; follow-up.
+ *   - Non-static targets (`--git-dir=$VAR`) return `undefined`,
+ *     collapsing the per-command cwd to `"unknown"`. Predicates then
+ *     apply `onUnknown`.
+ *   - `--work-tree` without `--git-dir` is semantically incomplete in
+ *     real git (the gitdir still points at the default), but for cwd
+ *     tracking purposes we treat them identically - they both mean
+ *     "the command's effective cwd is this path". If a rule author
+ *     needs the distinction (e.g. a repo-path vs tree-path
+ *     predicate), they can split it in their own plugin.
+ *
+ * Known accepted false-positives:
+ *
+ *   - `git log --git-dir=/repo` -> cwd recorded as /repo. Real git
+ *     treats post-subcommand `--git-dir=` as a pathspec, not a
+ *     global flag. Over-match rate is low in practice (agents emit
+ *     `git --git-dir=/x log`, not the inverse), and stopping the
+ *     scan at the first non-flag token would break composition with
+ *     the core `-C` modifier which iterates the same args list.
+ *     Accepted as a Phase-4 corner.
+ *   - `git diff -- --git-dir=/x` -> cwd recorded as /x. Arguments
+ *     after `--` are always pathspecs in real git. Same mitigation
+ *     rationale as above; stopping the scan at `--` would still
+ *     need to run after the core `-C` scanner has finished, not
+ *     before, to avoid the composition breakage.
+ */
+
+import * as path from "node:path";
+import type { Word } from "unbash";
+import { isStaticallyResolvable, type Modifier } from "@cad0p/unbash-walker";
+
+/** Regex matched against each `git`-command argument token. */
+const GIT_DIR_RE = /^--git-dir=(.+)$/;
+const WORK_TREE_RE = /^--work-tree=(.+)$/;
+
+/**
+ * Read a word's static value. Falls back to `text` when `value`
+ * isn't materialised (pure literal fast path in unbash).
+ */
+function wordValue(w: Word | undefined): string | undefined {
+  return w?.value ?? w?.text;
+}
+
+/**
+ * Scan git's pre-subcommand flags for `--git-dir=DIR` / `--work-tree=DIR`
+ * and layer the target on top of the current cwd.
+ *
+ * Stops at the first non-flag token (the subcommand) - identical shape
+ * to the core `-C` scanner. Multiple occurrences compose left-to-right
+ * (an absolute path replaces, a relative path joins to the running
+ * cwd). If we encounter a target we can't statically resolve, we bail
+ * returning `undefined`; the walker translates that to the cwd
+ * tracker's `"unknown"` sentinel.
+ */
+const gitCwdExtension: Modifier<string> = {
+  scope: "per-command",
+  apply: (args, current) => {
+    let cwd = current;
+    // Scan ALL args (not just pre-subcommand): we match only the two
+    // specific flag forms `--git-dir=X` / `--work-tree=X`, so there's
+    // no ambiguity with subcommand arguments. `git log
+    // --grep="--git-dir=foo"` is safe because the quoted string is a
+    // SINGLE argument whose text starts with `--grep`, not
+    // `--git-dir`, so the regex doesn't match.
+    //
+    // A stop-at-non-flag scan (mirroring the core `-C` modifier)
+    // would break composition with `-C`: the walker runs this
+    // modifier AGAINST THE SAME args the core `-C` modifier saw, not
+    // a reduced arg list. On `git -C /a --git-dir=/b status`, the
+    // args are still `[-C, /a, --git-dir=/b, status]`; a stop-at-
+    // non-flag scan would terminate at `/a` (the value of `-C`,
+    // which doesn't start with `-`) and miss the `--git-dir=` flag.
+    for (const w of args) {
+      const tok = wordValue(w);
+      if (tok === undefined) continue;
+
+      const gitDirMatch = tok.match(GIT_DIR_RE);
+      const workTreeMatch = tok.match(WORK_TREE_RE);
+      const match = gitDirMatch ?? workTreeMatch;
+      if (!match) continue;
+
+      // `--git-dir=$VAR` / `--work-tree=$(...)` - the captured
+      // piece is there in the raw text, but the overall Word is
+      // non-static. Refuse to invent a value.
+      if (!isStaticallyResolvable(w)) return undefined;
+
+      const target = match[1];
+      if (target === undefined || target.length === 0) continue;
+      cwd = path.isAbsolute(target) ? target : path.join(cwd, target);
+    }
+    return cwd;
+  },
+};
+
+/**
+ * Modifiers the git plugin registers under `cwd.git`. Exposed as an
+ * array so the plugin merger sees each entry distinctly; the runtime
+ * could today also accept a single modifier, but the array form
+ * leaves room for future git-specific cwd tweaks without changing
+ * the plugin manifest.
+ */
+export const gitCwdExtensions: readonly Modifier<unknown>[] = [
+  gitCwdExtension as Modifier<unknown>,
+];