@komarspn/pi-permission-system 16.0.2

package/test/handlers/gates/bash-program.test.ts

@@ -0,0 +1,410 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock node:fs so realpathSync (used by canonicalizePath) is controllable.
+// Default is identity so all existing lexical tests are unaffected.
+const realpathSync = vi.hoisted(() =>
+  vi.fn<(path: string) => string>((p) => p),
+);
+vi.mock("node:fs", () => ({
+  realpathSync,
+  default: { realpathSync },
+}));
+
+import { BashProgram } from "#src/handlers/gates/bash-program";
+
+describe("BashProgram", () => {
+  describe("pathRuleCandidates", () => {
+    const cwd = "/projects/my-app";
+
+    it("adds absolute and relative policy values for relative tokens", async () => {
+      const program = await BashProgram.parse("cat src/foo.ts");
+      expect(program.pathRuleCandidates(cwd)).toEqual([
+        {
+          token: "src/foo.ts",
+          policyValues: ["/projects/my-app/src/foo.ts", "src/foo.ts"],
+        },
+      ]);
+    });
+
+    it("returns the literal token only when no cwd is provided", async () => {
+      const program = await BashProgram.parse("cat src/foo.ts");
+      expect(program.pathRuleCandidates()).toEqual([
+        { token: "src/foo.ts", policyValues: ["src/foo.ts"] },
+      ]);
+    });
+
+    it("resolves tokens after literal cd against the effective directory", async () => {
+      const program = await BashProgram.parse("cd nested && cat src/file.txt");
+      const fileCandidate = program
+        .pathRuleCandidates(cwd)
+        .find((candidate) => candidate.token === "src/file.txt");
+      expect(fileCandidate).toEqual({
+        token: "src/file.txt",
+        policyValues: [
+          "/projects/my-app/nested/src/file.txt",
+          "nested/src/file.txt",
+          "src/file.txt",
+        ],
+      });
+    });
+
+    it("does not absolute-allow relative tokens after unknown cd", async () => {
+      const program = await BashProgram.parse('cd "$DIR" && cat src/foo.ts');
+      const fileCandidate = program
+        .pathRuleCandidates(cwd)
+        .find((candidate) => candidate.token === "src/foo.ts");
+      expect(fileCandidate).toEqual({
+        token: "src/foo.ts",
+        policyValues: ["src/foo.ts"],
+      });
+    });
+  });
+
+  describe("externalPaths", () => {
+    const cwd = "/projects/my-app";
+
+    beforeEach(() => {
+      realpathSync.mockReset();
+      realpathSync.mockImplementation((p: string) => p);
+    });
+
+    it("returns absolute paths resolving outside cwd", async () => {
+      const program = await BashProgram.parse("cat /etc/hosts");
+      // Subset matcher: the path is normalized before comparison.
+      expect(program.externalPaths(cwd)).toContain("/etc/hosts");
+    });
+
+    it("excludes paths within cwd", async () => {
+      const program = await BashProgram.parse("cat src/index.ts");
+      expect(program.externalPaths(cwd)).toHaveLength(0);
+    });
+
+    describe("effective working directory projection", () => {
+      it("folds a sequence of current-shell cd commands", async () => {
+        // cd a → cwd/a, cd b → cwd/a/b; ../c resolves to cwd/a/c (inside).
+        const program = await BashProgram.parse("cd a && cd b && cat ../c");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("catches an escape masked by a later cd that the single-base model missed", async () => {
+        // Effective dir after `cd nested/deep && cd ..` is cwd/nested, so
+        // ../../etc/passwd escapes to /projects/etc/passwd.
+        const program = await BashProgram.parse(
+          "cd nested/deep && cd .. && cat ../../etc/passwd",
+        );
+        expect(program.externalPaths(cwd)).toContain("/projects/etc/passwd");
+      });
+
+      it("folds a cd that is not the first command", async () => {
+        // The single-base model ignored a cd that was not first; now `cd a`
+        // folds, so ../b resolves to cwd/b (inside) and is not flagged.
+        const program = await BashProgram.parse("mkdir d && cd a && cat ../b");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("does not fold a backgrounded cd", async () => {
+        // `cd a &` runs in a subshell, so it must not update the running
+        // directory; ../b resolves against cwd and escapes.
+        const program = await BashProgram.parse("cd a & cat ../b");
+        expect(program.externalPaths(cwd)).toContain("/projects/b");
+      });
+
+      it("does not fold a cd inside a pipeline", async () => {
+        // Pipeline members run in subshells; the cd must not leak.
+        const program = await BashProgram.parse("cd nested | cat ../b");
+        expect(program.externalPaths(cwd)).toContain("/projects/b");
+      });
+
+      it("folds a cd inside a subshell for paths within that subshell", async () => {
+        // Inside the subshell the effective dir is cwd/sub, so ../x → cwd/x.
+        const program = await BashProgram.parse("( cd sub && cat ../x )");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("does not leak a subshell cd to following commands", async () => {
+        // The subshell cd resets on exit, so ../y resolves against cwd.
+        const program = await BashProgram.parse("( cd sub ) && cat ../y");
+        expect(program.externalPaths(cwd)).toContain("/projects/y");
+      });
+
+      it("persists a cd inside a brace group to later commands in the group", async () => {
+        // Brace groups run in the current shell, so cd sub persists to cat ../x.
+        const program = await BashProgram.parse("{ cd sub; cat ../x; }");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("persists a brace-group cd to following sibling commands", async () => {
+        const program = await BashProgram.parse("{ cd sub; } && cat ../x");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("conservatively flags a relative path inside a command substitution", async () => {
+        // Interior cd folding inside substitutions is deferred: the interior
+        // inherits the enclosing base (cwd), so ../r is flagged rather than
+        // resolved against cwd/q. Conservative — never misses an escape.
+        const program = await BashProgram.parse("echo $(cd q && cat ../r)");
+        expect(program.externalPaths(cwd)).toContain("/projects/r");
+      });
+
+      it("flags relative paths conservatively after a non-literal cd", async () => {
+        // cd "$DIR" makes the effective dir unknowable; ../x could be anywhere,
+        // so it is flagged (least-privilege).
+        const program = await BashProgram.parse('cd "$DIR" && cat ../x');
+        expect(program.externalPaths(cwd)).toContain("/projects/x");
+      });
+
+      it("flags even a within-cwd relative path after a non-literal cd", async () => {
+        // Conservative cost: src/../within.txt resolves inside cwd but is still
+        // flagged because the effective dir is unknown.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cat src/../within.txt',
+        );
+        expect(program.externalPaths(cwd)).toContain(
+          "/projects/my-app/within.txt",
+        );
+      });
+
+      it("still resolves an absolute path normally after a non-literal cd", async () => {
+        // Absolute paths are base-independent; one inside cwd is not flagged
+        // even when the effective dir is unknown.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cat /projects/my-app/x.txt',
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("treats `cd -` as an unknown effective directory", async () => {
+        const program = await BashProgram.parse("cd - && cat ../x");
+        expect(program.externalPaths(cwd)).toContain("/projects/x");
+      });
+
+      it("recovers a known base when a later cd is absolute", async () => {
+        // cd "$DIR" → unknown, then cd /projects/my-app/src → known again, so
+        // ../x resolves to cwd and is not flagged.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cd /projects/my-app/src && cat ../x',
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("folds a leading current-shell cd across a redirect-then-pipe", async () => {
+        // tree-sitter-bash groups `cd a && pnpm x 2>&1 | tail` as
+        // `(cd a && pnpm x 2>&1) | tail`, burying the current-shell `cd a`
+        // inside a `pipeline` node. Bash precedence (`|` binds tighter than
+        // `&&`) makes `cd a` current-shell, so the fold must persist past the
+        // pipeline: ../b resolves against cwd/a (inside), not cwd (#454).
+        const program = await BashProgram.parse(
+          "cd a && pnpm x 2>&1 | tail ; cat ../b",
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("persists the fold past a redirect-then-pipe to a later cd", async () => {
+        // The issue reproduction: the fold from `cd a/b` survives the
+        // redirect-then-pipe, so the trailing `cd .. && cd ..` lands back at
+        // cwd instead of escaping one level above.
+        const program = await BashProgram.parse(
+          "cd a/b && pnpm x 2>&1 | tail ; cd .. && cd ..",
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("does not fold the terminal piped command of the first stage", async () => {
+        // Fail-closed: `cd b` is the terminal command of the first stage, i.e.
+        // the real pipe stage (a subshell), so it must NOT fold. With the
+        // correct base cwd/a, ../../x escapes to /projects/x. If `cd b` were
+        // wrongly folded, the base would be cwd/a/b and ../../x would stay
+        // inside — a fail-open regression this test pins.
+        const program = await BashProgram.parse(
+          "cd a && cd b 2>&1 | tail ; cat ../../x",
+        );
+        expect(program.externalPaths(cwd)).toContain("/projects/x");
+      });
+
+      it("resolves a downstream pipe stage against the folded base", async () => {
+        // The stage after the `|` runs in a subshell that inherits the folded
+        // cwd/a, so ../foo resolves inside cwd rather than escaping against the
+        // pre-cd base.
+        const program = await BashProgram.parse(
+          "cd a && pnpm x 2>&1 | cat ../foo",
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+    });
+
+    it("flags an absolute in-cwd path that resolves externally via a symlink, returning the typed form", async () => {
+      // The strict classifier only processes absolute tokens, so the escape
+      // surface is `cat /cwd/link/hosts` (absolute) where `link -> /etc`.
+      // The boundary decision still uses the canonical form (so the path is
+      // flagged), but the returned value is the typed/lexical form so config
+      // patterns match the path as the user wrote it (#418).
+      realpathSync.mockImplementation((p: string) => {
+        if (p === "/projects/my-app/link/hosts") return "/etc/hosts";
+        return p;
+      });
+      const program = await BashProgram.parse(
+        "cat /projects/my-app/link/hosts",
+      );
+      const external = program.externalPaths(cwd);
+      expect(external).toContain("/projects/my-app/link/hosts");
+      expect(external).not.toContain("/etc/hosts");
+    });
+
+    it("does not flag a token that resolves within a symlinked cwd", async () => {
+      // Simulates /tmp -> /private/tmp on macOS; cwd is the canonical form.
+      const symlinkCwd = "/private/tmp";
+      realpathSync.mockImplementation((p: string) => {
+        if (p === "/tmp") return "/private/tmp";
+        if (p.startsWith("/tmp/")) return "/private/tmp" + p.slice(4);
+        return p;
+      });
+      const program = await BashProgram.parse("cat /tmp/workspace/file.ts");
+      expect(program.externalPaths(symlinkCwd)).toHaveLength(0);
+    });
+  });
+
+  describe("commands", () => {
+    it("returns a single-element list for a lone command", async () => {
+      const program = await BashProgram.parse("npm install pkg");
+      expect(program.commands()).toEqual([{ text: "npm install pkg" }]);
+    });
+
+    it("splits an && chain", async () => {
+      const program = await BashProgram.parse("cd /p && npm i x");
+      expect(program.commands()).toEqual([
+        { text: "cd /p" },
+        { text: "npm i x" },
+      ]);
+    });
+
+    it("splits || , ; and & separators", async () => {
+      expect((await BashProgram.parse("a || b")).commands()).toEqual([
+        { text: "a" },
+        { text: "b" },
+      ]);
+      expect((await BashProgram.parse("a ; b")).commands()).toEqual([
+        { text: "a" },
+        { text: "b" },
+      ]);
+      expect((await BashProgram.parse("a & b")).commands()).toEqual([
+        { text: "a" },
+        { text: "b" },
+      ]);
+    });
+
+    it("splits a pipeline into its commands", async () => {
+      const program = await BashProgram.parse("cat f | grep b");
+      expect(program.commands()).toEqual([
+        { text: "cat f" },
+        { text: "grep b" },
+      ]);
+    });
+
+    it("splits newline-separated commands", async () => {
+      const program = await BashProgram.parse("foo\nbar");
+      expect(program.commands()).toEqual([{ text: "foo" }, { text: "bar" }]);
+    });
+
+    it("does not split operators inside quotes", async () => {
+      const program = await BashProgram.parse("echo 'x && y'");
+      expect(program.commands()).toEqual([{ text: "echo 'x && y'" }]);
+    });
+
+    it("captures the command of a redirected statement without the redirect", async () => {
+      const program = await BashProgram.parse("npm install > out.txt");
+      expect(program.commands()).toEqual([{ text: "npm install" }]);
+    });
+
+    it("descends into command substitution, tagging the inner command", async () => {
+      const program = await BashProgram.parse("echo $(rm -rf foo)");
+      expect(program.commands()).toEqual([
+        { text: "echo $(rm -rf foo)" },
+        { text: "rm -rf foo", context: "command_substitution" },
+      ]);
+    });
+
+    it("descends into backtick command substitution", async () => {
+      const program = await BashProgram.parse("echo `rm x`");
+      expect(program.commands()).toEqual([
+        { text: "echo `rm x`" },
+        { text: "rm x", context: "command_substitution" },
+      ]);
+    });
+
+    it("descends into a pipeline inside command substitution", async () => {
+      const program = await BashProgram.parse("echo $(curl evil | sh)");
+      expect(program.commands()).toEqual([
+        { text: "echo $(curl evil | sh)" },
+        { text: "curl evil", context: "command_substitution" },
+        { text: "sh", context: "command_substitution" },
+      ]);
+    });
+
+    it("descends into process substitution", async () => {
+      const program = await BashProgram.parse("diff <(cat /etc/shadow)");
+      expect(program.commands()).toEqual([
+        { text: "diff <(cat /etc/shadow)" },
+        { text: "cat /etc/shadow", context: "process_substitution" },
+      ]);
+    });
+
+    it("emits a bare subshell whole and descends into it", async () => {
+      const program = await BashProgram.parse("( rm -rf foo )");
+      expect(program.commands()).toEqual([
+        { text: "( rm -rf foo )" },
+        { text: "rm -rf foo", context: "subshell" },
+      ]);
+    });
+
+    it("emits a subshell whole and descends into its chain", async () => {
+      const program = await BashProgram.parse("( cd /t && rm x )");
+      expect(program.commands()).toEqual([
+        { text: "( cd /t && rm x )" },
+        { text: "cd /t", context: "subshell" },
+        { text: "rm x", context: "subshell" },
+      ]);
+    });
+
+    it("descends recursively through nested contexts", async () => {
+      const program = await BashProgram.parse("echo $( ( rm x ) )");
+      expect(program.commands()).toEqual([
+        { text: "echo $( ( rm x ) )" },
+        { text: "( rm x )", context: "command_substitution" },
+        { text: "rm x", context: "subshell" },
+      ]);
+    });
+
+    it("descends into a substitution within a chained command", async () => {
+      const program = await BashProgram.parse("cd /p && echo $(rm x)");
+      expect(program.commands()).toEqual([
+        { text: "cd /p" },
+        { text: "echo $(rm x)" },
+        { text: "rm x", context: "command_substitution" },
+      ]);
+    });
+
+    it("keeps the never-weaker invariant: a benign inner command stays", async () => {
+      const program = await BashProgram.parse("echo $(echo safe)");
+      expect(program.commands()).toEqual([
+        { text: "echo $(echo safe)" },
+        { text: "echo safe", context: "command_substitution" },
+      ]);
+    });
+
+    it("returns an empty list for an empty or whitespace command", async () => {
+      expect((await BashProgram.parse("")).commands()).toEqual([]);
+      expect((await BashProgram.parse("   ")).commands()).toEqual([]);
+    });
+  });
+
+  it("derives both slices from a single parse", async () => {
+    const program = await BashProgram.parse("cat .env /etc/hosts");
+    expect(program.pathRuleCandidates().map(({ token }) => token)).toEqual([
+      ".env",
+      "/etc/hosts",
+    ]);
+    const external = program.externalPaths("/projects/my-app");
+    expect(external).toContain("/etc/hosts");
+    expect(external).not.toContain(".env");
+  });
+});

package/test/handlers/gates/bash-token-classification.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from "vitest";
+
+import {
+  classifyTokenAsPathCandidate,
+  classifyTokenAsRuleCandidate,
+} from "#src/handlers/gates/bash-token-classification";
+
+// ── Shared rejection behaviour ─────────────────────────────────────────────
+//
+// Both classifiers delegate to the private `rejectNonPathToken` predicate for
+// the seven shared rejection cases tested below.  Testing via both exports
+// pins that predicate through each caller.
+
+describe("classifyTokenAsPathCandidate", () => {
+  describe("shared rejection: rejectNonPathToken", () => {
+    test("empty string → null", () => {
+      expect(classifyTokenAsPathCandidate("")).toBeNull();
+    });
+
+    test("flag (leading dash) → null", () => {
+      expect(classifyTokenAsPathCandidate("-r")).toBeNull();
+      expect(classifyTokenAsPathCandidate("--recursive")).toBeNull();
+    });
+
+    test("env assignment (= before any /) → null", () => {
+      expect(classifyTokenAsPathCandidate("FOO=/bar")).toBeNull();
+      expect(classifyTokenAsPathCandidate("HOME=/home/user")).toBeNull();
+    });
+
+    test("env-like token where = comes after / is NOT rejected as assignment", () => {
+      // /foo=bar: slashIndex (0) < eqIndex (4) → not an assignment → continues
+      // Starts with /, so path candidate accepts it.
+      expect(classifyTokenAsPathCandidate("/foo=bar")).toBe("/foo=bar");
+    });
+
+    test("URL → null", () => {
+      expect(classifyTokenAsPathCandidate("https://example.com")).toBeNull();
+      expect(classifyTokenAsPathCandidate("http://localhost:3000")).toBeNull();
+      expect(classifyTokenAsPathCandidate("file:///tmp/foo")).toBeNull();
+      expect(
+        classifyTokenAsPathCandidate("git+ssh://github.com/a/b"),
+      ).toBeNull();
+    });
+
+    test("@scope/package → null", () => {
+      expect(classifyTokenAsPathCandidate("@foo/bar")).toBeNull();
+      expect(classifyTokenAsPathCandidate("@scope/pkg")).toBeNull();
+    });
+
+    test("@/ prefix is NOT rejected (it looks like an absolute-rooted scoped path)", () => {
+      // @/ passes the @ guard; then for path candidate it doesn't start with /
+      // or ~/, and doesn't contain .., so it returns null anyway from the
+      // acceptance gate — but the rejection is not due to the @ guard.
+      // This test documents that @/ is not rejected by the shared rejection.
+      // The path classifier then rejects it for not matching any acceptance shape.
+      expect(classifyTokenAsPathCandidate("@/foo/bar")).toBeNull();
+    });
+
+    test("bare-slash token → null", () => {
+      expect(classifyTokenAsPathCandidate("/")).toBeNull();
+      expect(classifyTokenAsPathCandidate("//")).toBeNull();
+      expect(classifyTokenAsPathCandidate("///")).toBeNull();
+    });
+
+    test("regex metacharacters → null", () => {
+      // REGEX_METACHAR_PATTERN: .*, .+, \|, \(, \), [...], ^/
+      expect(classifyTokenAsPathCandidate("foo.*")).toBeNull();
+      expect(classifyTokenAsPathCandidate("bar.+")).toBeNull();
+      expect(classifyTokenAsPathCandidate("a\\|b")).toBeNull();
+      expect(classifyTokenAsPathCandidate("\\(group\\)")).toBeNull();
+      expect(classifyTokenAsPathCandidate("[abc]")).toBeNull();
+      expect(classifyTokenAsPathCandidate("^/start")).toBeNull();
+    });
+  });
+
+  describe("path-candidate acceptance gate", () => {
+    test("absolute path (starts with /) → returned as-is", () => {
+      expect(classifyTokenAsPathCandidate("/etc/hosts")).toBe("/etc/hosts");
+      expect(classifyTokenAsPathCandidate("/tmp")).toBe("/tmp");
+      expect(classifyTokenAsPathCandidate("/home/user/file.txt")).toBe(
+        "/home/user/file.txt",
+      );
+    });
+
+    test("home-relative path (starts with ~/) → returned as-is", () => {
+      expect(classifyTokenAsPathCandidate("~/Documents")).toBe("~/Documents");
+      expect(classifyTokenAsPathCandidate("~/.ssh/config")).toBe(
+        "~/.ssh/config",
+      );
+    });
+
+    test("parent-traversal (contains ..) → returned as-is", () => {
+      expect(classifyTokenAsPathCandidate("../../etc/passwd")).toBe(
+        "../../etc/passwd",
+      );
+      expect(classifyTokenAsPathCandidate("../foo")).toBe("../foo");
+      expect(classifyTokenAsPathCandidate("..")).toBe("..");
+    });
+
+    test("plain word with no path shape → null", () => {
+      expect(classifyTokenAsPathCandidate("hello")).toBeNull();
+      expect(classifyTokenAsPathCandidate("myfile.txt")).toBeNull();
+    });
+
+    test("dot-file (starts with .) → null (strict path gate)", () => {
+      // Path candidate does NOT accept dot-files; rule candidate does.
+      expect(classifyTokenAsPathCandidate(".env")).toBeNull();
+      expect(classifyTokenAsPathCandidate(".gitignore")).toBeNull();
+    });
+
+    test("relative path with / but no leading / or ~/ → null (strict path gate)", () => {
+      // Path candidate does NOT accept bare relative paths; rule candidate does.
+      expect(classifyTokenAsPathCandidate("src/foo.ts")).toBeNull();
+      expect(classifyTokenAsPathCandidate("./build")).toBeNull();
+    });
+  });
+});
+
+describe("classifyTokenAsRuleCandidate", () => {
+  describe("shared rejection: rejectNonPathToken", () => {
+    test("empty string → null", () => {
+      expect(classifyTokenAsRuleCandidate("")).toBeNull();
+    });
+
+    test("flag (leading dash) → null", () => {
+      expect(classifyTokenAsRuleCandidate("-r")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("--recursive")).toBeNull();
+    });
+
+    test("env assignment (= before any /) → null", () => {
+      expect(classifyTokenAsRuleCandidate("FOO=/bar")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("HOME=/home/user")).toBeNull();
+    });
+
+    test("env-like token where = comes after / is NOT rejected as assignment", () => {
+      // /foo=bar: slashIndex (0) < eqIndex (4) → not an assignment → continues.
+      // Contains /, so rule candidate accepts it.
+      expect(classifyTokenAsRuleCandidate("/foo=bar")).toBe("/foo=bar");
+    });
+
+    test("URL → null", () => {
+      expect(classifyTokenAsRuleCandidate("https://example.com")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("http://localhost:3000")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("file:///tmp/foo")).toBeNull();
+    });
+
+    test("@scope/package → null", () => {
+      expect(classifyTokenAsRuleCandidate("@foo/bar")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("@scope/pkg")).toBeNull();
+    });
+
+    test("bare-slash token → null", () => {
+      expect(classifyTokenAsRuleCandidate("/")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("//")).toBeNull();
+    });
+
+    test("regex metacharacters → null", () => {
+      expect(classifyTokenAsRuleCandidate("foo.*")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("bar.+")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("a\\|b")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("[abc]")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("^/start")).toBeNull();
+    });
+  });
+
+  describe("rule-candidate acceptance gate (broader than path)", () => {
+    test("absolute path (starts with /) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("/etc/hosts")).toBe("/etc/hosts");
+    });
+
+    test("home-relative path (starts with ~/) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("~/Documents")).toBe("~/Documents");
+    });
+
+    test("parent-traversal (contains ..) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("../foo")).toBe("../foo");
+      expect(classifyTokenAsRuleCandidate("..")).toBe("..");
+    });
+
+    test("dot-file (starts with .) → returned as-is", () => {
+      // Rule candidate accepts dot-files; path candidate does not.
+      expect(classifyTokenAsRuleCandidate(".env")).toBe(".env");
+      expect(classifyTokenAsRuleCandidate(".gitignore")).toBe(".gitignore");
+    });
+
+    test("current-dir relative (starts with ./) → returned as-is", () => {
+      expect(classifyTokenAsRuleCandidate("./src")).toBe("./src");
+      expect(classifyTokenAsRuleCandidate("./build/output.js")).toBe(
+        "./build/output.js",
+      );
+    });
+
+    test("relative path containing / → returned as-is", () => {
+      // Rule candidate accepts any token with / (not already rejected).
+      expect(classifyTokenAsRuleCandidate("src/foo.ts")).toBe("src/foo.ts");
+      expect(classifyTokenAsRuleCandidate("packages/pi-foo/index.ts")).toBe(
+        "packages/pi-foo/index.ts",
+      );
+    });
+
+    test("plain word with no path shape → null", () => {
+      expect(classifyTokenAsRuleCandidate("hello")).toBeNull();
+      expect(classifyTokenAsRuleCandidate("myfile.txt")).toBeNull();
+    });
+  });
+
+  describe("rule-vs-path divergence", () => {
+    const dotFiles = [".env", ".gitignore", ".eslintrc"];
+    const relPaths = ["src/index.ts", "lib/utils.js", "config/settings.json"];
+
+    for (const tok of dotFiles) {
+      test(`dot-file "${tok}": rule accepts, path rejects`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBe(tok);
+        expect(classifyTokenAsPathCandidate(tok)).toBeNull();
+      });
+    }
+
+    for (const tok of relPaths) {
+      test(`relative path "${tok}": rule accepts, path rejects`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBe(tok);
+        expect(classifyTokenAsPathCandidate(tok)).toBeNull();
+      });
+    }
+
+    const sharedAccepted = ["/etc/hosts", "~/docs", "../sibling"];
+    for (const tok of sharedAccepted) {
+      test(`"${tok}": both classifiers accept`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBe(tok);
+        expect(classifyTokenAsPathCandidate(tok)).toBe(tok);
+      });
+    }
+
+    const sharedRejected = ["hello", "--flag", "FOO=/bar", "https://x.com"];
+    for (const tok of sharedRejected) {
+      test(`"${tok}": both classifiers reject`, () => {
+        expect(classifyTokenAsRuleCandidate(tok)).toBeNull();
+        expect(classifyTokenAsPathCandidate(tok)).toBeNull();
+      });
+    }
+  });
+});