@gotgenes/pi-permission-system 27.1.2 → 27.1.3

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [27.1.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.2...pi-permission-system-v27.1.3) (2026-08-29)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate commands hosted by declarations, test commands, and assignments ([dfde822](https://github.com/gotgenes/pi-packages/commit/dfde8227d3bf11de5258dcbe376dd0b8b75045e0)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** gate commands inside a for loop's body and word list ([6e96464](https://github.com/gotgenes/pi-packages/commit/6e9646486db849afdf80819150a203d293b3847c)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** gate commands inside control-flow bodies and function definitions ([3a2f232](https://github.com/gotgenes/pi-packages/commit/3a2f232d9c12588ea1feacf41cade0e56e66a44b)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** project a command-name substitution's path operands ([9807d44](https://github.com/gotgenes/pi-packages/commit/9807d444b6d81526b01bc542cd4a829a1b2640c3)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+
+
+### Documentation
+
+* **pi-permission-system:** bound the path-slice claim on behavior, not diff footprint ([91ef5c9](https://github.com/gotgenes/pi-packages/commit/91ef5c9f2d0578fb64fe317bcddd3ec7d9418d4c)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** commit the instrument behind Step 4's measurement ([e634c2c](https://github.com/gotgenes/pi-packages/commit/e634c2cf068340cc0deae86648330e44c2741f06)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+
 ## [27.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.1...pi-permission-system-v27.1.2) (2026-08-29)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "27.1.2",
+  "version": "27.1.3",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -90,6 +90,7 @@
     "test:watch": "vitest",
     "verify:public-types": "bash scripts/verify-public-types.sh",
     "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
+    "measure:statement-descent": "node scripts/measure-statement-descent.mjs",
     "measure:wrapper-transparency": "node scripts/measure-wrapper-transparency.mjs",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"

package/src/access-intent/bash/command-enumeration.ts

@@ -1,6 +1,6 @@
 import {
   EXECUTION_HOST_TYPES,
-  forEachNestedExecution,
+  forEachExecutionIn,
 } from "#src/access-intent/bash/nested-execution";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import { redirectMayWriteFile } from "#src/access-intent/bash/redirect-analysis";
@@ -79,7 +79,7 @@ interface UnitScope {
 /** A top-level command in the current shell, writing no file. */
 const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
 
-// ── Command enumeration ──────────────────────────────────────────────────────
+// ── Node-type vocabulary ─────────────────────────────────────────────────────
 
 /**
  * Container node types descended into with the enclosing scope unchanged.
@@ -89,6 +89,39 @@ const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
  */
 const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
 
+/**
+ * Compound statements: emitted whole, then descended for their statements.
+ *
+ * The whole emit is what keeps the #306 never-weaker invariant — the commands
+ * found inside are additional units, never a replacement.
+ *
+ * `select` parses as `for_statement` and `until` as `while_statement`, so each
+ * pair is one entry.
+ */
+const COMPOUND_STATEMENT_TYPES = new Set([
+  "if_statement",
+  "while_statement",
+  "for_statement",
+  "c_style_for_statement",
+  "case_statement",
+  "function_definition",
+  "compound_statement",
+  "negated_command",
+]);
+
+/**
+ * Syntactic groupings inside a compound statement: descended, never emitted.
+ *
+ * None of these is something anybody runs — a `do_group` is the loop body's
+ * punctuation — so emitting one would produce a `do rm $f; done` unit.
+ */
+const STATEMENT_GROUP_TYPES = new Set([
+  "do_group",
+  "case_item",
+  "elif_clause",
+  "else_clause",
+]);
+
 /**
  * Named node types abandoned during command enumeration: they are neither
  * commands nor able to host one, so nothing in their subtree ever runs.
@@ -104,6 +137,33 @@ const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
  */
 const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
 
+/**
+ * Every node type the enumerator recognizes as a statement.
+ *
+ * This is the enumerator's third question, beside "is this a command?" and
+ * "can this host one?": "is this a *statement*, so that descending an enclosing
+ * compound reaches it?" A compound statement's named children are a mix —
+ * `for_statement` carries its loop variable and word list, `case_statement` its
+ * subject, `function_definition` its name — and descending all of them emits
+ * operand words as bash command units, naming `a` as the offending *command* in
+ * a prompt. Membership is what {@link descendStatementChildren} filters on.
+ */
+const STATEMENT_TYPES = new Set([
+  "command",
+  "redirected_statement",
+  "subshell",
+  "declaration_command",
+  "variable_assignment",
+  "test_command",
+  "unset_command",
+  "ERROR",
+  ...COMMAND_ENUM_DESCEND,
+  ...COMPOUND_STATEMENT_TYPES,
+  ...STATEMENT_GROUP_TYPES,
+]);
+
+// ── Command enumeration ──────────────────────────────────────────────
+
 /**
  * Enumerate the command units of a bash program, in source order.
  *
@@ -114,10 +174,14 @@ const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
  * subshells (`( … )`) — emitting each inner command as its own unit *in
  * addition to* the enclosing command, since those inner commands really execute
  * (#306).
- * Control-flow bodies and `{ … }` brace groups are emitted whole without
- * descending (deferred).
+ * A compound statement (control flow, a function definition, a `{ … }` brace
+ * group) is emitted whole and then descended for the statements it contains,
+ * while its operand words — a loop variable, a word list, a `case` subject, a
+ * function's own name — are not commands and are left unemitted. An `ERROR`
+ * node is the one exception: its recovered structure is invented rather than
+ * observed, so the unparsed blob is emitted whole and never descended (#742).
  *
- * The enclosing command/subshell is always still emitted whole, so adding the
+ * The enclosing command/statement is always still emitted whole, so adding the
  * nested units can only ever produce a more-restrictive decision, never weaker.
  *
  * Each emitted command unit has any leading `variable_assignment` prefix
@@ -172,9 +236,33 @@ function collectCommandsInto(
     return;
   }
 
+  if (COMPOUND_STATEMENT_TYPES.has(node.type)) {
+    out.push(makeUnit(node.text, scope)); // never-weaker whole emit
+    descendStatementChildren(node, scope, out);
+    return;
+  }
+
+  if (STATEMENT_GROUP_TYPES.has(node.type)) {
+    descendStatementChildren(node, scope, out);
+    return;
+  }
+
+  if (node.type === "ERROR") {
+    // Tree-sitter's error recovery *invents* structure, so the node types
+    // inside an ERROR subtree are not evidence that anything runs: descending
+    // one turns backtick-quoted prose in an unterminated heredoc into command
+    // units. Emit the unparsed blob whole and stop (#742).
+    out.push(makeUnit(node.text, scope));
+    return;
+  }
+
   // Any other named statement (compound_statement `{ … }`, if/while/for/case,
   // function_definition): emit whole, do not descend — deferred (#306).
+  // A declaration, assignment, test, or `unset` still hosts executions that
+  // really run (`local x=$(rm y)`, `[[ $(rm x) ]]`), so those are enumerated
+  // in addition to the statement (#742).
   out.push(makeUnit(node.text, scope));
+  collectHostedCommands(node, out);
 }
 
 /** The wrapper facts a `command` node's words establish about its unit. */
@@ -291,6 +379,35 @@ function descendCommandChildren(
   }
 }
 
+/**
+ * Descend a compound statement's children, enumerating only the ones that are
+ * themselves statements.
+ *
+ * The filter is the whole difference from {@link descendCommandChildren}, whose
+ * container types (`program` / `list` / `pipeline` / `redirected_statement` /
+ * `subshell`) have nothing but statement children. Here the children are a mix,
+ * and a non-statement one is an operand word rather than something that runs.
+ *
+ * A non-statement child is not abandoned, though: `for f in $(rm x)` hosts a
+ * real execution in its word list, which is what the second branch reaches.
+ *
+ * The scope is relayed unchanged — a compound statement's body runs in the
+ * current shell, so a write established by an enclosing `redirected_statement`
+ * covers every unit beneath it (#803).
+ */
+function descendStatementChildren(
+  node: TSNode,
+  scope: UnitScope,
+  out: BashCommand[],
+): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child?.isNamed) continue;
+    if (STATEMENT_TYPES.has(child.type)) collectCommandsInto(child, scope, out);
+    else collectHostedCommands(child, out);
+  }
+}
+
 /**
  * Enumerate the commands of every nested execution context in a subtree, each
  * tagged with the context it was found in.
@@ -298,9 +415,12 @@ function descendCommandChildren(
  * The traversal itself lives in `nested-execution.ts` so the bash path surface
  * shares one definition of what counts as a nested execution (#741); this
  * function supplies the command-surface interpretation of each one found.
+ *
+ * `node` may be a context outright or merely host one, so the traversal is the
+ * root-inclusive `forEachExecutionIn`.
  */
 function collectHostedCommands(node: TSNode, out: BashCommand[]): void {
-  forEachNestedExecution(node, (contextNode, context) => {
+  forEachExecutionIn(node, (contextNode, context) => {
     // A nested execution starts fresh: an enclosing statement's redirect is
     // that statement's, not the substitution's, exactly as #807 attributes a
     // nested command's path tokens to its own command.

package/src/access-intent/bash/nested-execution.ts

@@ -47,6 +47,24 @@ export const EXECUTION_HOST_TYPES: ReadonlySet<string> = new Set([
   "heredoc_body",
 ]);
 
+/**
+ * Visit every execution context `node` *is or contains*, in source order.
+ *
+ * The root-inclusive question, and the one nearly every consumer asks: a node
+ * handed in can be a substitution outright (`> $(cmd)`) or merely host one
+ * (`> ${DIR}/$(cmd)`), and both really execute. {@link forEachNestedExecution}
+ * answers the strictly-within question instead, which is what a visitor needs
+ * once it has already decided to treat a context's interior itself.
+ */
+export function forEachExecutionIn(
+  node: TSNode,
+  visit: (contextNode: TSNode, context: BashCommandContext) => void,
+): void {
+  const context = NESTED_EXECUTION_CONTEXTS.get(node.type);
+  if (context) visit(node, context);
+  else forEachNestedExecution(node, visit);
+}
+
 /**
  * Visit every nested execution context in `node`'s subtree, in source order.
  *
@@ -58,6 +76,10 @@ export const EXECUTION_HOST_TYPES: ReadonlySet<string> = new Set([
  * A substitution can nest under `command_name` (when the whole command is
  * `$(…)`), under an argument, inside a redirect destination, or inside an
  * interpolating heredoc body, so the entire subtree is searched.
+ *
+ * `node` itself is never visited, however it is typed — use
+ * {@link forEachExecutionIn} when it may *be* a context rather than merely
+ * contain one.
  */
 export function forEachNestedExecution(
   node: TSNode,

package/src/access-intent/bash/token-collection.ts

@@ -2,8 +2,7 @@ import { basename } from "node:path";
 import { proveCommandEffect } from "#src/access-intent/bash/command-effects";
 import {
   EXECUTION_HOST_TYPES,
-  forEachNestedExecution,
-  NESTED_EXECUTION_CONTEXTS,
+  forEachExecutionIn,
 } from "#src/access-intent/bash/nested-execution";
 import {
   ARG_NODE_TYPES,
@@ -129,15 +128,12 @@ export function collectRedirectTokens(node: TSNode): PathToken[] {
  * its prose stays out of the path surface entirely.
  *
  * `node` may be a context outright (`> $(cmd)`) or merely contain one
- * (`> ${DIR}/$(cmd)`); `forEachNestedExecution` searches strictly within a
- * subtree, so the first case is checked here.
+ * (`> ${DIR}/$(cmd)`), so the traversal is the root-inclusive
+ * `forEachExecutionIn`.
  */
 function collectHostedExecutionTokens(node: TSNode): PathToken[] {
-  if (NESTED_EXECUTION_CONTEXTS.has(node.type)) {
-    return collectPathCandidateTokens(node);
-  }
   const tokens: PathToken[] = [];
-  forEachNestedExecution(node, (contextNode) => {
+  forEachExecutionIn(node, (contextNode) => {
     tokens.push(...collectPathCandidateTokens(contextNode));
   });
   return tokens;
@@ -201,6 +197,23 @@ function commandArgumentWords(node: TSNode): string[] {
   return words;
 }
 
+/**
+ * The children of a `command` node that supply no operand text of their own:
+ * its head word, and any env-var prefix assignment.
+ *
+ * Both are skipped as operands — the head word is not an argument, and a prefix
+ * assignment's value is assigned rather than accessed — but either can *host* a
+ * substitution that really runs (`$(cat /etc/shadow)`,
+ * `FOO=$(cat /etc/shadow) echo hi`), whose own operands are candidates like any
+ * other position (ADR 0009's positional invariance). The two walkers below are
+ * different state machines and so each carry their own skip, which is why the
+ * question is named here once rather than spelled twice (#742).
+ */
+const COMMAND_PREFIX_TYPES: ReadonlySet<string> = new Set([
+  "command_name",
+  "variable_assignment",
+]);
+
 /**
  * A long or short option carrying its value inline: one or two leading dashes,
  * a name containing no `=` or whitespace, then `=` and a non-empty value.
@@ -527,9 +540,11 @@ function collectPatternCommandTokens(
     const child = node.child(i);
     if (!child) continue;
 
-    // Skip command_name and variable_assignment nodes.
-    if (child.type === "command_name" || child.type === "variable_assignment")
+    if (COMMAND_PREFIX_TYPES.has(child.type)) {
+      // Supplies no operand of its own, but may host one that really runs.
+      tokens.push(...collectHostedExecutionTokens(child));
       continue;
+    }
 
     const isArgNode = ARG_NODE_TYPES.has(child.type);
     const text = resolveNodeText(child);
@@ -682,12 +697,12 @@ function collectGenericCommandTokens(
     const child = node.child(i);
     if (!child) continue;
 
-    if (child.type === "command_name") {
-      seenCommandName = true;
+    if (COMMAND_PREFIX_TYPES.has(child.type)) {
+      // Supplies no operand of its own, but may host one that really runs.
+      if (child.type === "command_name") seenCommandName = true;
+      tokens.push(...collectHostedExecutionTokens(child));
       continue;
     }
-    // Skip variable_assignment nodes (FOO=/bar)
-    if (child.type === "variable_assignment") continue;
 
     // If there was no explicit command_name node, the first word-like
     // child is the command name itself — skip it.