@aliou/pi-guardrails 0.11.1 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-guardrails",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "license": "MIT",
   "type": "module",
   "private": false,

package/src/hooks/policies.ts

@@ -10,7 +10,7 @@ import {
   compileFilePatterns,
   normalizeFilePath,
 } from "../utils/matching";
-import { expandHomePath } from "../utils/path";
+import { expandHomePath, maybePathLike } from "../utils/path";
 import { walkCommands, wordToString } from "../utils/shell-utils";
 import { pendingWarnings } from "../utils/warnings";
 
@@ -108,16 +108,6 @@ function compileRules(rules: PolicyRule[]): CompiledRule[] {
   return compiled;
 }
 
-function maybePathLike(token: string): boolean {
-  return (
-    token.includes("/") ||
-    token.includes(".") ||
-    token.startsWith("~") ||
-    token.startsWith("./") ||
-    token.startsWith("../")
-  );
-}
-
 function normalizeTargetForPolicy(filePath: string, cwd: string): string {
   if (filePath === "~" || filePath.startsWith("~/")) {
     return normalizeFilePath(filePath);

package/src/utils/bash-paths.test.ts

@@ -6,6 +6,56 @@ const CWD = "/work/project";
 const HOME = homedir();
 
 describe("extractBashPathCandidates", () => {
+  describe("when a command has regular expression arguments", () => {
+    it("ignores sed expressions and extracts file operands", async () => {
+      const result = await extractBashPathCandidates(
+        "sed 's/abc/{2,3}/g' ./file",
+        CWD,
+      );
+      expect(result).toEqual(["/work/project/file"]);
+    });
+
+    it("ignores grep patterns and extracts file operands", async () => {
+      const result = await extractBashPathCandidates(
+        "grep '/api/v1' ./src",
+        CWD,
+      );
+      expect(result).toEqual(["/work/project/src"]);
+    });
+
+    it("ignores ripgrep patterns and extracts search roots", async () => {
+      const result = await extractBashPathCandidates("rg '/api/v1' ./src", CWD);
+      expect(result).toEqual(["/work/project/src"]);
+    });
+
+    it("ignores jq filters and extracts file operands", async () => {
+      const result = await extractBashPathCandidates(
+        "jq '.path | test(\"^/tmp/\")' ./data.json",
+        CWD,
+      );
+      expect(result).toEqual(["/work/project/data.json"]);
+    });
+
+    it("ignores interpreter inline code", async () => {
+      const result = await extractBashPathCandidates(
+        "python3 -c 'open(\"/etc/passwd\").read()'",
+        CWD,
+      );
+      expect(result).toEqual([]);
+    });
+  });
+
+  // Regression: github issue #32 — awk regex patterns should not be
+  // treated as file paths.
+  it("does not extract awk regex patterns as paths", async () => {
+    const result = await extractBashPathCandidates(
+      "awk '/aaa/{flag=1} flag{print}' test.txt",
+      CWD,
+    );
+    // The awk program should NOT be treated as a path
+    expect(result).toEqual([]);
+  });
+
   describe("when command has path arguments", () => {
     it("extracts a single absolute path", async () => {
       expect(await extractBashPathCandidates("cat /etc/hosts", CWD)).toEqual([

package/src/utils/bash-paths.ts

@@ -1,25 +1,10 @@
 import { resolve } from "node:path";
 import { parse } from "@aliou/sh";
+import { classifyCommandArgs } from "./command-args";
 import { expandGlob, hasGlobChars } from "./glob-expander";
-import { expandHomePath } from "./path";
+import { expandHomePath, maybePathLike } from "./path";
 import { walkCommands, wordToString } from "./shell-utils";
 
-/**
- * Heuristic: is this token likely a filesystem path?
- * Intentionally conservative — only structural signals.
- * Known false positives: "application/json", URL paths. These cause
- * spurious prompts in ask mode but are safe (better to over-prompt than miss).
- * Known false negatives: bare filenames without path separators (e.g. "README.md").
- * These are usually cwd-relative and would pass the boundary check anyway.
- */
-function maybePathLike(token: string): boolean {
-  if (token.includes("/")) return true;
-  if (token.includes("\\")) return true;
-  if (/^[A-Za-z]:[\\/]/.test(token)) return true;
-  if (token.startsWith("~")) return true;
-  return false;
-}
-
 async function expandCandidate(
   candidate: string,
   cwd: string,
@@ -64,8 +49,11 @@ export async function extractBashPathCandidates(
 
     walkCommands(ast, (cmd) => {
       const words = (cmd.words ?? []).map(wordToString);
-      for (let i = 1; i < words.length; i++) {
-        pending.push(addCandidate(words[i] as string));
+      const commandName = words[0];
+      if (commandName) {
+        for (const arg of classifyCommandArgs(commandName, words.slice(1))) {
+          pending.push(addCandidate(arg.token, arg.forcePath));
+        }
       }
       for (const redir of cmd.redirects ?? []) {
         pending.push(addCandidate(wordToString(redir.target), true));

package/src/utils/command-args.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { classifyCommandArgs } from "./command-args";
+
+const tokens = (command: string, args: string[]) =>
+  classifyCommandArgs(command, args).map((arg) => arg.token);
+
+describe("classifyCommandArgs", () => {
+  it("keeps unknown command arguments unchanged", () => {
+    expect(tokens("cat", ["/etc/hosts", "./file"])).toEqual([
+      "/etc/hosts",
+      "./file",
+    ]);
+  });
+
+  it("ignores awk inline program and keeps file operands", () => {
+    expect(tokens("awk", ["/aaa/{print}", "./input"])).toEqual(["./input"]);
+  });
+
+  it("keeps awk -f program files", () => {
+    expect(tokens("awk", ["-f", "./prog.awk", "./input"])).toEqual([
+      "./prog.awk",
+      "./input",
+    ]);
+  });
+
+  it("ignores sed inline scripts and keeps file operands", () => {
+    expect(tokens("sed", ["s#/old#/new#g", "./file"])).toEqual(["./file"]);
+  });
+
+  it("keeps sed -f script files", () => {
+    expect(tokens("sed", ["-f", "./script.sed", "./file"])).toEqual([
+      "./script.sed",
+      "./file",
+    ]);
+  });
+
+  it("ignores grep patterns and keeps file operands", () => {
+    expect(tokens("grep", ["/api/v1", "./src"])).toEqual(["./src"]);
+  });
+
+  it("keeps grep pattern files", () => {
+    expect(tokens("grep", ["-f", "./patterns", "./src"])).toEqual([
+      "./patterns",
+      "./src",
+    ]);
+  });
+
+  it("keeps find roots and ignores expression patterns", () => {
+    expect(tokens("find", ["./src", "-regex", ".*/test/.*"])).toEqual([
+      "./src",
+    ]);
+  });
+
+  it("ignores jq filters and keeps file operands", () => {
+    expect(tokens("jq", ['.path | test("^/tmp/")', "./data.json"])).toEqual([
+      "./data.json",
+    ]);
+  });
+
+  it("keeps jq -f filter files", () => {
+    expect(tokens("jq", ["-f", "./filter.jq", "./data.json"])).toEqual([
+      "./filter.jq",
+      "./data.json",
+    ]);
+  });
+
+  it("ignores interpreter inline code", () => {
+    expect(tokens("python3", ["-c", 'open("/etc/passwd")'])).toEqual([]);
+  });
+
+  it("keeps interpreter script operands", () => {
+    expect(tokens("python3", ["./script.py", "./data.json"])).toEqual([
+      "./script.py",
+      "./data.json",
+    ]);
+  });
+
+  it("ignores delimiter args", () => {
+    expect(tokens("cut", ["-d", "/", "./file"])).toEqual(["./file"]);
+    expect(tokens("sort", ["-t", "/", "./file"])).toEqual(["./file"]);
+    expect(tokens("tr", ["/", ":"])).toEqual([]);
+  });
+});

package/src/utils/command-args.ts

@@ -0,0 +1,226 @@
+import { basename } from "node:path";
+
+export type ClassifiedArg = { token: string; forcePath?: boolean };
+
+function normalizeCommandName(command: string): string {
+  return basename(command).toLowerCase();
+}
+
+function isOption(arg: string): boolean {
+  return arg.startsWith("-") && arg !== "-" && arg !== "--";
+}
+
+export function classifyCommandArgs(
+  command: string,
+  args: string[],
+): ClassifiedArg[] {
+  const cmd = normalizeCommandName(command);
+
+  if (cmd === "awk" || cmd === "gawk" || cmd === "mawk" || cmd === "nawk") {
+    return classifyAwkArgs(args);
+  }
+  if (cmd === "sed" || cmd === "gsed") return classifySedArgs(args);
+  if (["grep", "egrep", "fgrep", "rg", "ripgrep", "ag", "ack"].includes(cmd)) {
+    return classifyGrepLikeArgs(args);
+  }
+  if (cmd === "find" || cmd === "gfind") return classifyFindArgs(args);
+  if (cmd === "jq" || cmd === "yq") return classifyFilterCommandArgs(args);
+  if (
+    ["python", "python2", "python3", "node", "ruby", "perl", "php"].includes(
+      cmd,
+    )
+  ) {
+    return classifyInterpreterArgs(cmd, args);
+  }
+  if (cmd === "cut")
+    return skipOptionValues(args, new Set(["-d", "--delimiter"]));
+  if (cmd === "sort")
+    return skipOptionValues(args, new Set(["-t", "--field-separator"]));
+  if (cmd === "tr") return [];
+
+  return args.map((token) => ({ token }));
+}
+
+function classifyAwkArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let sawProgram = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "--") continue;
+    if (arg === "-f") {
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      sawProgram = true;
+      continue;
+    }
+    if (arg === "-v" || arg === "-F") {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-f") && arg.length > 2) {
+      out.push({ token: arg.slice(2) });
+      sawProgram = true;
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!sawProgram) {
+      sawProgram = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifySedArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let hasExplicitScript = false;
+  let skippedImplicitScript = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-e" || arg === "--expression") {
+      hasExplicitScript = true;
+      i++;
+      continue;
+    }
+    if (arg === "-f" || arg === "--file") {
+      hasExplicitScript = true;
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      continue;
+    }
+    if (arg.startsWith("-e") && arg.length > 2) {
+      hasExplicitScript = true;
+      continue;
+    }
+    if (arg.startsWith("-f") && arg.length > 2) {
+      hasExplicitScript = true;
+      out.push({ token: arg.slice(2) });
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!hasExplicitScript && !skippedImplicitScript) {
+      skippedImplicitScript = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifyGrepLikeArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let patternProvided = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-e" || arg === "--regexp") {
+      patternProvided = true;
+      i++;
+      continue;
+    }
+    if (arg === "-f" || arg === "--file") {
+      patternProvided = true;
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      continue;
+    }
+    if (["-g", "--glob", "-t", "-T", "--type", "--type-not"].includes(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-e") && arg.length > 2) {
+      patternProvided = true;
+      continue;
+    }
+    if (arg.startsWith("-f") && arg.length > 2) {
+      patternProvided = true;
+      out.push({ token: arg.slice(2) });
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!patternProvided) {
+      patternProvided = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifyFindArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let inExpression = false;
+  const patternOptions = new Set([
+    "-name",
+    "-iname",
+    "-path",
+    "-ipath",
+    "-regex",
+    "-iregex",
+    "-wholename",
+    "-iwholename",
+  ]);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (!inExpression && !arg.startsWith("-") && arg !== "(" && arg !== "!") {
+      out.push({ token: arg });
+      continue;
+    }
+    inExpression = true;
+    if (patternOptions.has(arg)) i++;
+  }
+  return out;
+}
+
+function classifyFilterCommandArgs(args: string[]): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  let sawFilter = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-f" || arg === "--from-file") {
+      if (args[i + 1]) out.push({ token: args[++i] as string });
+      sawFilter = true;
+      continue;
+    }
+    if (isOption(arg)) continue;
+    if (!sawFilter) {
+      sawFilter = true;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function classifyInterpreterArgs(cmd: string, args: string[]): ClassifiedArg[] {
+  const codeFlags =
+    cmd === "python" || cmd.startsWith("python")
+      ? new Set(["-c"])
+      : cmd === "php"
+        ? new Set(["-r"])
+        : new Set(["-e"]);
+  const out: ClassifiedArg[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (codeFlags.has(arg)) {
+      i++;
+      continue;
+    }
+    if (isOption(arg)) continue;
+    out.push({ token: arg });
+  }
+  return out;
+}
+
+function skipOptionValues(
+  args: string[],
+  optionsWithValues: Set<string>,
+): ClassifiedArg[] {
+  const out: ClassifiedArg[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (optionsWithValues.has(arg)) {
+      i++;
+      continue;
+    }
+    out.push({ token: arg });
+  }
+  return out;
+}

package/src/utils/path.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   expandHomePath,
   isWithinBoundary,
+  maybePathLike,
   normalizeForDisplay,
   resolveFromCwd,
   toStorageForm,
@@ -175,3 +176,118 @@ describe("toStorageForm", () => {
     expect(toStorageForm(absPath, isDirectory)).toBe(expected);
   });
 });
+
+describe("maybePathLike", () => {
+  it.each([
+    // --- True cases: structural path signals ---
+    {
+      desc: "absolute Unix path",
+      input: "/etc/hosts",
+      expected: true,
+    },
+    {
+      desc: "relative path with /",
+      input: "src/index.ts",
+      expected: true,
+    },
+    {
+      desc: "./ prefix",
+      input: "./foo",
+      expected: true,
+    },
+    {
+      desc: "../ prefix",
+      input: "../bar",
+      expected: true,
+    },
+    {
+      desc: "backslash path (Windows)",
+      input: "foo\\bar",
+      expected: true,
+    },
+    {
+      desc: "Windows drive letter",
+      input: "C:\\tmp",
+      expected: true,
+    },
+    {
+      desc: "Windows drive with forward slash",
+      input: "C:/tmp",
+      expected: true,
+    },
+    {
+      desc: "tilde home path",
+      input: "~/code",
+      expected: true,
+    },
+    {
+      desc: "MIME type (has / — safe false positive)",
+      input: "application/json",
+      expected: true,
+    },
+    {
+      desc: "regular expression with braces (has / — safe false positive)",
+      input: "/abc/{2,3}",
+      expected: true,
+    },
+    // --- False cases: non-path tokens ---
+    {
+      desc: "empty string",
+      input: "",
+      expected: false,
+    },
+    {
+      desc: "simple command name",
+      input: "rm",
+      expected: false,
+    },
+    {
+      desc: "flag",
+      input: "--force",
+      expected: false,
+    },
+    {
+      desc: "short flag",
+      input: "-rf",
+      expected: false,
+    },
+    {
+      desc: "bare word",
+      input: "build",
+      expected: false,
+    },
+    {
+      desc: "bare tilde (no slash)",
+      input: "~",
+      expected: false,
+    },
+    {
+      desc: "version number",
+      input: "3.14",
+      expected: false,
+    },
+    {
+      desc: "domain name",
+      input: "example.com",
+      expected: false,
+    },
+    {
+      desc: "bare filename with extension",
+      input: "README.md",
+      expected: false,
+    },
+    {
+      desc: "dotfile without slash",
+      input: ".env",
+      expected: false,
+    },
+  ])("when $desc, returns $expected", ({ input, expected }) => {
+    expect(maybePathLike(input)).toBe(expected);
+  });
+
+  // maybePathLike is command-agnostic. Command-specific regex/code args are
+  // filtered by extractBashPathCandidates before this fallback heuristic runs.
+  it("treats awk-looking regex text as path-like without command context", () => {
+    expect(maybePathLike("/aaa/{flag=1} flag{print}")).toBe(true);
+  });
+});

package/src/utils/path.ts

@@ -72,3 +72,26 @@ export function toStorageForm(absPath: string, isDirectory: boolean): string {
   if (!isDirectory && stored.endsWith("/")) stored = stored.slice(0, -1);
   return stored;
 }
+
+/**
+ * Heuristic: is this token likely a filesystem path?
+ *
+ * Checks for structural path signals: separators (/ \), drive letters
+ * (C:\), home prefix (~), and relative path prefixes (./ ../).
+ *
+ * False positives (MIME types, version strings, domains) are safe —
+ * they just get checked against policies and miss.
+ *
+ * Known false negatives: bare filenames without separators or dots
+ * (Makefile, LICENSE, README). These are cwd-relative and would
+ * pass the boundary check anyway.
+ */
+export function maybePathLike(token: string): boolean {
+  if (!token) return false;
+
+  if (token.includes("/")) return true;
+  if (token.includes("\\")) return true;
+  if (/^[A-Za-z]:[\\/]/.test(token)) return true;
+  if (/^(?:~|\.{1,2})[\\/]/.test(token)) return true;
+  return false;
+}