@gotgenes/pi-permission-system 30.2.0 → 31.0.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [31.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.2.0...pi-permission-system-v31.0.0) (2026-09-02)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** **breaking:** gate a path named as a for or select loop operand ([6189d81](https://github.com/gotgenes/pi-packages/commit/6189d81dc48a26d572bacb91a1b2e7c062634ad9)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** **breaking:** gate a path named as a case subject ([dfd2f8d](https://github.com/gotgenes/pi-packages/commit/dfd2f8d682c39dcfe6a903cdeadde18b08a7cc60)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+
+### Documentation
+
+* **pi-permission-system:** commit the instrument behind the statement-operand measurement ([6a708b7](https://github.com/gotgenes/pi-packages/commit/6a708b716f038bf192875a0166ae6a6ab012c3d8)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** register the statement-operand measurement script ([e3e8799](https://github.com/gotgenes/pi-packages/commit/e3e879935c6f395d4b2387a6e30e0791bb8fb765)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+* **pi-permission-system:** correct the drift note in the operand measurement ([e300934](https://github.com/gotgenes/pi-packages/commit/e300934c0aad34b3bfd127695219250ca6f4613f)), closes [#839](https://github.com/gotgenes/pi-packages/issues/839)
+
 ## [30.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.1.0...pi-permission-system-v30.2.0) (2026-09-02)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "30.2.0",
+  "version": "31.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -91,6 +91,7 @@
     "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:statement-operands": "node scripts/measure-statement-operands.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/token-collection.ts

@@ -11,7 +11,7 @@ import {
 } from "#src/access-intent/bash/node-text";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import { redirectEffectForDestination } from "#src/access-intent/bash/redirect-analysis";
-import type { TokenEffect } from "#src/access-intent/effect";
+import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
 
 /**
  * A collected path-candidate token paired with the effect its position proved.
@@ -29,7 +29,8 @@ export interface PathToken {
 
 /**
  * Recursively visit the AST and collect resolved text of nodes that
- * represent command arguments or redirect destinations.
+ * represent command arguments, redirect destinations, or a statement's own
+ * path operands.
  *
  * Reads no text from `heredoc_body`, `heredoc_end`, or `comment` subtrees, but
  * still descends an execution host for the commands it hosts — an interpolating
@@ -46,6 +47,12 @@ export interface PathToken {
 export function collectPathCandidateTokens(node: TSNode): PathToken[] {
   if (node.type === "command") return collectCommandTokens(node);
   if (node.type === "file_redirect") return collectRedirectTokens(node);
+  if (node.type === "for_statement") {
+    return collectStatementOperandTokens(node, "after-in");
+  }
+  if (node.type === "case_statement") {
+    return collectStatementOperandTokens(node, "before-in");
+  }
   if (EXECUTION_HOST_TYPES.has(node.type)) {
     return collectHostedExecutionTokens(node);
   }
@@ -139,6 +146,70 @@ function collectHostedExecutionTokens(node: TSNode): PathToken[] {
   return tokens;
 }
 
+/**
+ * Which side of a statement's `in` keyword carries its path operands.
+ *
+ * A `for`/`select` word list follows `in`; a `case` subject precedes it.
+ */
+type OperandSide = "before-in" | "after-in";
+
+/**
+ * Collect the tokens of a statement that names its own path operands, rather
+ * than reaching them through a command.
+ *
+ * A path in a `for`/`select` word list or a `case` subject is a child of the
+ * statement node, so the command and redirect collectors never see it and the
+ * loop body cannot recover it — `for f in /etc/shadow; do cat $f; done` carries
+ * the literal only here, and ADR 0009 declines to resolve the body's `$f`
+ * (#839).
+ *
+ * The two statements ask one question with one parameter — which side of the
+ * anonymous `in` keyword is the operand side — so the walk is named here once
+ * rather than spelled twice, as `COMMAND_PREFIX_TYPES` is for the two command
+ * walkers.
+ *
+ * Three properties carry the design:
+ *
+ * 1. A non-operand child falls through to the ordinary recursion, not to
+ *    nothing. That is what keeps the `do_group` reaching the loop body's
+ *    commands; searching it for hosted executions alone would silently drop
+ *    every ordinary body command.
+ * 2. An operand-side child outside {@link ARG_NODE_TYPES} falls through the
+ *    same way, so a bare substitution in the word list is descended for its
+ *    command as before and its operands keep that command's own attribution
+ *    (#807) instead of the statement's.
+ * 3. An operand-side argument node is read *and* searched for hosted
+ *    executions, since a `concatenation` can be both — the pairing
+ *    {@link collectRedirectTokens} already performs on a destination.
+ *
+ * The token carries {@link UNPROVEN_EFFECT}: no command word owns it and no
+ * redirect operator names it, so neither proof source can speak and the gates
+ * consult both directional surfaces.
+ */
+function collectStatementOperandTokens(
+  node: TSNode,
+  operandSide: OperandSide,
+): PathToken[] {
+  const tokens: PathToken[] = [];
+  let seenIn = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (!child.isNamed) {
+      if (child.type === "in") seenIn = true;
+      continue;
+    }
+    const side: OperandSide = seenIn ? "after-in" : "before-in";
+    if (side !== operandSide || !ARG_NODE_TYPES.has(child.type)) {
+      tokens.push(...collectPathCandidateTokens(child));
+      continue;
+    }
+    tokens.push({ token: resolveNodeText(child), effect: UNPROVEN_EFFECT });
+    tokens.push(...collectHostedExecutionTokens(child));
+  }
+  return tokens;
+}
+
 /**
  * Extract the command name from a `command` node.
  * Returns the basename (e.g. `/usr/bin/sed` → `sed`), or undefined