forgedock 1.28.0 → 1.29.1

package/scripts/repo-facts.test.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# repo-facts.test.sh — cases for scripts/repo-facts.sh (forge#4272).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/repo-facts.sh"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/repo-facts-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+eq() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got: $2 want: $3)"; fi }
+q() { printf '%s' "$OUT" | jq -c "$1"; }
+
+new_repo() {
+  rm -rf "${TMP:?}/$1"; mkdir -p "$TMP/$1"; cd "$TMP/$1" || exit 1
+  git init -q -b main; git config user.email t@example.com; git config user.name t; git config commit.gpgsign false
+}
+commit() { git add -A; git commit -qm "$1"; }
+lines() { i=0; : > "$1"; while [ $i -lt "$2" ]; do echo "l$i" >> "$1"; i=$((i+1)); done; }
+
+# ---- 1. pins, slow suites, package edge, boundary config, hotspot ----
+new_repo full
+mkdir -p packages/a packages/b .github/workflows src
+cat > package.json <<'EOF'
+{"name":"root","private":true,"packageManager":"pnpm@9.1.0","workspaces":["packages/*"],
+ "scripts":{"test":"vitest run","lint":"eslint .","test:e2e":"playwright test"}}
+EOF
+echo "20.11.1" > .nvmrc
+echo '{"name":"@x/a","dependencies":{"@x/b":"workspace:*","left-pad":"1.0.0"}}' > packages/a/package.json
+echo '{"name":"@x/b","scripts":{"test":"vitest run"}}' > packages/b/package.json
+echo "module.exports = { rules: { 'boundaries/element-types': ['error'] } };" > .eslintrc.js
+echo "module.exports = { rules: { semi: 'error' } };" > packages/b/.eslintrc.js
+cat > .github/workflows/ci.yml <<'EOF'
+on: push
+jobs:
+  db:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres
+    steps:
+      - run: pnpm run test
+  long:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - run: pytest tests/slow
+  quick:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - run: ruff check .
+EOF
+lines src/big.ts 2100; commit c1
+echo x >> src/big.ts; lines src/small.ts 10; commit c2
+OUT="$(bash "$S" --stdout)"; rc=$?
+eq "rc" "$rc" 0
+eq "version" "$(q '.version')" 1
+eq "pm pin" "$(q '.toolchain.pm')" '{"name":"pnpm","version":"9.1.0","source":"package.json packageManager"}'
+eq "node pin" "$(q '.toolchain.node')" '{"spec":"20.11.1","source":".nvmrc"}'
+eq "packages" "$(q '.layer_rules.packages')" '[{"name":"@x/a","dir":"packages/a"},{"name":"@x/b","dir":"packages/b"}]'
+eq "edge" "$(q '.layer_rules.edges')" '[{"from":"@x/a","to":"@x/b","kind":"dependencies","manifest":"packages/a/package.json"}]'
+eq "boundary configs" "$(q '.layer_rules.boundary_configs')" '[".eslintrc.js"]'
+eq "services job" "$(q '[.slow_suites[] | select(.command == "pnpm run test") | .why]')" '["CI job .github/workflows/ci.yml#jobs.db uses services"]'
+eq "timeout job" "$(q '[.slow_suites[] | select(.command == "pytest tests/slow") | .why]')" '["CI job .github/workflows/ci.yml#jobs.long sets timeout-minutes 45"]'
+eq "quick job not slow" "$(q '[.slow_suites[] | select(.command == "ruff check .")] | length')" 0
+eq "hotspot" "$(q '.hotspots')" '[{"path":"src/big.ts","lines":2101,"commits_90d":2,"hotspot":4202}]'
+
+# ---- 2. a cached test map is read: its e2e command is a slow suite ----
+mkdir -p .forge
+echo '{"version":1,"entries":[{"globs":["e2e/**"],"command":"pnpm exec playwright test","cwd":".","source":"package.json#scripts.test:e2e"}]}' > .forge/test-map.json
+OUT="$(bash "$S" --stdout)"
+eq "map e2e" "$(q '.slow_suites')" '[{"command":"pnpm exec playwright test","source":"package.json#scripts.test:e2e","why":"command names playwright"}]'
+
+# ---- 3. default output file, rerun stable ----
+P="$(bash "$S")"; eq "output path" "$P" ".forge/repo-facts.json"
+cp .forge/repo-facts.json "$TMP/first.json"; bash "$S" >/dev/null
+if cmp -s .forge/repo-facts.json "$TMP/first.json"; then ok; else bad "rerun not identical"; fi
+
+# ---- 4. a repo with none of these: empty sections, exit 0 ----
+new_repo bare
+echo hi > README.md; commit init
+OUT="$(bash "$S" --stdout)"; rc=$?
+eq "bare rc" "$rc" 0
+eq "bare" "$(q '[.toolchain.pm, .toolchain.node, .slow_suites, .layer_rules, .hotspots]')" '[null,null,[],{"packages":[],"edges":[],"boundary_configs":[]},[]]'
+new_repo empty
+OUT="$(bash "$S" --stdout)"; eq "no commits rc" "$?" 0
+eq "no commits" "$(q '.hotspots')" '[]'
+
+# ---- 4b. #4298: a big boundary config matching early (pipefail + grep -q SIGPIPE) and non-ASCII / spaced paths ----
+new_repo paths
+mkdir -p "packages/é b" "apps/ü"
+echo '{"name":"root","private":true,"workspaces":["packages/*"]}' > package.json
+echo '{"name":"@x/c"}' > "packages/é b/package.json"
+{ echo "export default [{ rules: { 'boundaries/element-types': ['error'] } }];"; i=0; while [ $i -lt 20000 ]; do echo "// padding line $i to overflow the pipe buffer ......................................"; i=$((i+1)); done; } > "apps/ü/eslint.config.js"
+commit init
+OUT="$(bash "$S" --stdout)"; eq "paths rc" "$?" 0
+eq "big boundary config in a non-ASCII dir" "$(q '.layer_rules.boundary_configs')" '["apps/ü/eslint.config.js"]'
+eq "spaced non-ASCII package dir" "$(q '.layer_rules.packages')" '[{"name":"@x/c","dir":"packages/é b"}]'
+
+# ---- 5. usage ----
+bash "$S" --repo-path "$TMP/missing" >/dev/null 2>&1; eq "bad repo path" "$?" 2
+bash "$S" --bogus >/dev/null 2>&1; eq "unknown option" "$?" 2
+
+echo "repo-facts.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/scripts/review-prepare.sh

@@ -87,15 +87,23 @@ case "$MERGE_ISSUE" in *[!0-9]*) MERGE_ISSUE="" ;; esac
 [ "$THOROUGH" = "true" ] || THOROUGH="false"
 
 # --- trusted helper resolution (install roots only; never cwd) ---
+# shellcheck source=/dev/null  # the resolver lib is found at runtime in the trusted install root
 type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; _SELF_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd -P)"; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" "${CLAUDE_PLUGIN_ROOT:-}" "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/* "$_SELF_ROOT"; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
 
 ROSTER_SCRIPT=$(forge_resolve review-roster.sh)
 TRUSTED_SCRIPT=$(forge_resolve trusted-comments.sh)
+# shellcheck disable=SC2034  # read by lib/review-delta-mode.sh (sourced below)
 REVIEW_DELTA_SCRIPT=$(forge_resolve review-delta.sh)
 CODE_INDEX_SCRIPT=$(forge_resolve code-index.sh)
-_l=$(forge_resolve lib/pr-issue-number.sh); if [ -n "$_l" ]; then . "$_l"; else pr_issue_number() { return 0; }; fi
-_l=$(forge_resolve lib/review-template-resolve.sh); if [ -n "$_l" ]; then . "$_l"; else review_template_resolve() { TEMPLATE_BASE=""; TEMPLATE_SOURCE="none"; MONOLITHIC_CATALOG=""; }; fi
-_l=$(forge_resolve lib/review-delta-mode.sh); if [ -n "$_l" ]; then . "$_l"; else review_delta_mode() { echo "FULL - 0"; }; carry_verified_from() { :; }; fi
+_l=$(forge_resolve lib/pr-issue-number.sh)
+# shellcheck source=/dev/null  # resolved at runtime from the trusted install root
+if [ -n "$_l" ]; then . "$_l"; else pr_issue_number() { return 0; }; fi
+_l=$(forge_resolve lib/review-template-resolve.sh)
+# shellcheck source=/dev/null  # resolved at runtime from the trusted install root
+if [ -n "$_l" ]; then . "$_l"; else review_template_resolve() { TEMPLATE_BASE=""; TEMPLATE_SOURCE="none"; MONOLITHIC_CATALOG=""; }; fi
+_l=$(forge_resolve lib/review-delta-mode.sh)
+# shellcheck source=/dev/null disable=SC2329  # resolved at runtime; the fallback stubs mirror the lib's API
+if [ -n "$_l" ]; then . "$_l"; else review_delta_mode() { echo "FULL - 0"; }; carry_verified_from() { :; }; fi
 
 # --- state, scratch and the ref-restore guard ---
 BLOCKERS=""
@@ -105,12 +113,14 @@ mkdir -p "$OUT_DIR" 2>/dev/null || { echo "review-prepare: cannot create $OUT_DI
 TMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/review-prepare.XXXXXX") || exit 2
 ORIG_REF=""; CHECKED_OUT=""
 # restore_ref: put the checkout back exactly where it was. -f so a dirty review checkout can never wedge the restore.
+# shellcheck disable=SC2329  # called from cleanup (EXIT trap) and the checkout paths
 restore_ref() {
     if [ -n "$CHECKED_OUT" ] && [ -n "$ORIG_REF" ]; then
         git checkout -f "$ORIG_REF" >/dev/null 2>&1 || echo "review-prepare: WARNING could not restore $ORIG_REF" >&2
     fi
     CHECKED_OUT=""
 }
+# shellcheck disable=SC2329  # invoked by the EXIT trap
 cleanup() { restore_ref; rm -rf "$TMP_DIR"; }
 trap cleanup EXIT
 
@@ -144,6 +154,7 @@ if [ -z "$BLOCKERS" ]; then
         # Pinned (forge#3935): same-repo PRs only (a fork's branch name resolves to origin's own branch), and the fetched tip must equal REVIEW_SHA; the diff is taken against REVIEW_SHA, never the branch name.
         if { [ "$NO_DELTA" = "true" ] || [ "$IS_MILESTONE_TO_STAGING" = "true" ]; } && [ -n "$BASE" ] && [ -n "$HEAD" ] && [ "$(printf '%s' "$PR_INFO" | jq -r .isCrossRepository 2>/dev/null)" = "false" ] && printf '%s' "$REVIEW_SHA" | grep -qE '^[0-9a-f]{40}$' \
            && git fetch -q origin "$BASE" "$HEAD" 2>/dev/null && [ "$(git rev-parse -q --verify "refs/remotes/origin/${HEAD}^{commit}" 2>/dev/null)" = "$REVIEW_SHA" ]; then
+            # shellcheck disable=SC2015  # either assignment failing resets both, by design
             FILES=$(git diff --name-only "origin/${BASE}...${REVIEW_SHA}" 2>/dev/null) && DIFF=$(git diff "origin/${BASE}...${REVIEW_SHA}" 2>/dev/null) || { FILES=""; DIFF=""; }
         fi
         [ -n "$FILES" ] || block "gh pr diff failed"
@@ -420,7 +431,9 @@ canonical_roster() { local out="" a d; for a in $1; do d=$(agent_domain "$a"); c
 SELECTED_AGENTS=$(canonical_roster "$SELECTED_AGENTS")
 
 # --- Phase 3C: review mode (FULL | DELTA | BASE_SYNC_ONLY) ---
+# shellcheck disable=SC2034  # both read by lib/review-delta-mode.sh
 BASE_BRANCH="$BASE"
+# shellcheck disable=SC2034
 COMMENTS_JSON=$(gh api --paginate "repos/${REPO}/issues/${PR_NUMBER}/comments" 2>/dev/null || echo "")
 delta_roster() {
     local rounds="${1}" full="${2}" files="${3}" out="security" root
@@ -473,11 +486,20 @@ if [ "$REVIEW_MODE" != "BASE_SYNC_ONLY" ]; then
         _ito="${REVIEW_PREPARE_INDEX_TIMEOUT:-120}"; case "$_ito" in ''|*[!0-9]*|0) _ito=120 ;; esac
         _tbin=$(command -v timeout || command -v gtimeout || true)
         echo "review-prepare: building code index (limit ${_ito}s)" >&2
-        if [ -n "$_tbin" ]; then "$_tbin" "$_ito" bash "$CODE_INDEX_SCRIPT" --repo-path "$REPO_PATH" >/dev/null 2>&1; _irc=$?
-        else bash "$CODE_INDEX_SCRIPT" --repo-path "$REPO_PATH" >/dev/null 2>&1; _irc=$?; fi
+        # forge#4235: keep the build's stderr so a failure is diagnosable (its tail is echoed below); stdout stays discarded.
+        _ierr=$(mktemp "$OUT_DIR/.code-index-err-XXXXXX" 2>/dev/null) || _ierr=/dev/null
+        if [ -n "$_tbin" ]; then "$_tbin" "$_ito" bash "$CODE_INDEX_SCRIPT" --repo-path "$REPO_PATH" >/dev/null 2>"$_ierr"; _irc=$?
+        else bash "$CODE_INDEX_SCRIPT" --repo-path "$REPO_PATH" >/dev/null 2>"$_ierr"; _irc=$?; fi
         if [ "$_irc" -eq 0 ]; then INDEX_OK=1
         elif [ "$_irc" -eq 124 ]; then echo "review-prepare: code index timed out after ${_ito}s — skipping index slices (agents grep instead)" >&2
-        else echo "review-prepare: code index failed (exit $_irc) — skipping index slices (agents grep instead)" >&2; fi
+        else
+            echo "review-prepare: code index failed (exit $_irc) — skipping index slices (agents grep instead)" >&2
+            # forge#4316: the tail can name repo files; show the repo root as <repo>, strip control chars, cap each line
+            [ -s "$_ierr" ] && tail -n 20 "$_ierr" | tr -d '\000-\010\013-\037\177' \
+                | awk -v r="$REPO_PATH" '{ l = $0; if (r != "") { o = ""; while ((i = index(l, r)) > 0) { o = o substr(l, 1, i - 1) "<repo>"; l = substr(l, i + length(r)) } l = o l } print substr(l, 1, 200) }' \
+                | sed 's/^/review-prepare: code-index: /' >&2
+        fi
+        [ "$_ierr" = /dev/null ] || rm -f "$_ierr"
     fi
     build_index_slice() {
         local domain="${1}" files

package/scripts/review-prepare.test.sh

@@ -109,7 +109,9 @@ setup feat/x staging "README.md" "$DIFF_PLAIN"; printf 'CONFLICTING|DIRTY\n' > "
 prep "$ROOT"; eq "conflicting" .merge_health.mergeable CONFLICTING; eq "conflicting state" .merge_health.state DIRTY; eq "no retry on CONFLICTING" .merge_health.retries 0
 setup feat/x staging "README.md" "$DIFF_PLAIN"; printf 'UNKNOWN|UNKNOWN\n' > "$FIX/merge.seq"
 prep "$ROOT"; eq "unknown stays unknown after 3 retries" .merge_health.retries 3; eq "still UNKNOWN" .merge_health.mergeable UNKNOWN
-setup feat/x staging "README.md" "$DIFF_PLAIN"; printf 'garbage|$(rm -rf)\n' > "$FIX/merge.seq"
+setup feat/x staging "README.md" "$DIFF_PLAIN"
+# shellcheck disable=SC2016  # the literal $(rm -rf) is the hostile payload under test
+printf 'garbage|$(rm -rf)\n' > "$FIX/merge.seq"
 prep "$ROOT"; eq "garbage state normalized" .merge_health.state UNKNOWN
 setup feat/x staging "README.md" "$DIFF_PLAIN"; echo 0 > "$FIX/prior"
 prep "$ROOT"; eq "first-time contributor" .pr.first_time_contributor true
@@ -234,6 +236,7 @@ CFG_OVERRIDE="$WORK/emptyroot.yaml" prep "$WORK/root-notpl"
 rc_is "no template source" 3; eq "templates none" .templates.source none
 
 # --- 8. issue number extraction and trusted contract ---
+# shellcheck source=/dev/null
 . "$ROOT/scripts/lib/pr-issue-number.sh"
 chk() { local got; got=$(pr_issue_number_of "$2"); if [ "$got" = "$3" ]; then ok; else bad "$1: got '$got', want '$3'"; fi; }
 chk "Closes" "Closes #12" 12
@@ -271,6 +274,7 @@ setup feat/x staging "README.md" "$DIFF_PLAIN" "00000000000000000000000000000000
 prep "$ROOT" --checkout-pr
 rc_is "unknown sha cannot be checked out" 3
 if [ "$(git -C "$REPO_DIR" symbolic-ref --short HEAD 2>/dev/null)" = "main" ]; then ok; else bad "failed checkout moved HEAD"; fi
+# shellcheck disable=SC2016  # matches the literal $ORIG_REF in the script source
 if grep -q 'checkout -f "\$ORIG_REF"' "$ROOT/scripts/review-prepare.sh"; then ok; else bad "restore_ref must use git checkout -f"; fi
 
 # --- 10. fail closed on gh and bad arguments ---
@@ -317,8 +321,24 @@ eq "a hostile cwd roster script is never used" '.roster.agents | index("evil") !
 # --- code index build is bounded and visible (forge#4126) ---
 setup feat/x staging "services/api/auth.py" "$DIFF_AUTH_BILL"
 prep "$ROOT"
-eq "real index fills the auth slice" '.index_slices.auth | startswith("Domain files (auth):")' true
+_f0=$fail; eq "real index fills the auth slice" '.index_slices.auth | startswith("Domain files (auth):")' true
+# forge#4235: on failure show review-prepare's stderr (it carries the index build's exit code and stderr tail)
+[ "$fail" -eq "$_f0" ] || sed 's/^/  stderr: /' "$WORK/stderr"
 if grep -q "review-prepare: building code index" "$WORK/stderr"; then ok; else bad "index build must print a progress line on stderr"; fi
+# a failing build reports its exit code and stderr tail, and the slices fall back to grep
+mkroot "$WORK/root-failindex" "" "" templates
+# forge#4316: a line naming a repo file, carrying an ESC and over 200 chars is echoed sanitised and capped
+# shellcheck disable=SC2016 # $2 is the fake index script's own argument
+printf '#!/usr/bin/env bash\necho "index-boom-marker" >&2\nprintf "parse error in %%s/secret/file.py \\033[31m%%0300d\\n" "$2" 0 >&2\nexit 3\n' > "$WORK/root-failindex/scripts/code-index.sh"
+prep "$WORK/root-failindex"
+rc_is "failing index build" 0
+if grep -q "code index failed (exit 3)" "$WORK/stderr"; then ok; else bad "index failure must report the build's exit code on stderr"; fi
+if grep -q "review-prepare: code-index: index-boom-marker" "$WORK/stderr"; then ok; else bad "index failure must echo the build's stderr tail: $(head -c 300 "$WORK/stderr")"; fi
+_ix=$(grep "review-prepare: code-index: parse error" "$WORK/stderr")
+case "$_ix" in "review-prepare: code-index: parse error in <repo>/secret/file.py [31m0"*) ok ;; *) bad "index stderr must show the repo root as <repo> without control chars: $(printf '%s' "$_ix" | head -c 120 | od -c | head -3)" ;; esac
+if [ "${#_ix}" -le $((28 + 200)) ]; then ok; else bad "index stderr line must be capped at 200 chars, got ${#_ix}"; fi
+eq "failed index falls back to grep slices" .index_slices.auth "Code index not available — agent will use grep exploration"
+if ls "$WORK/out"/.code-index-err-* >/dev/null 2>&1; then bad "index stderr temp file must be removed"; else ok; fi
 if command -v timeout >/dev/null 2>&1 || command -v gtimeout >/dev/null 2>&1; then
     mkroot "$WORK/root-slowindex" "" "" templates
     printf '#!/usr/bin/env bash\nsleep 30\n' > "$WORK/root-slowindex/scripts/code-index.sh"

package/scripts/test-map.sh

@@ -0,0 +1,317 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# test-map.sh — deterministic `file glob → check command` map for a repo (forge#4272). No LLM, no network, runs none of
+# the repo's commands: git + jq + awk only (no yq). Codebase-agnostic: node, python, go, make and CI workflow steps.
+#
+# Usage: test-map.sh [--repo-path DIR] [--output FILE | --stdout]
+#   default output <repo>/.forge/test-map.json, rewritten on every run (a regenerable cache; deleting it restores the
+#   pre-PR step's `learned.test_commands` behaviour).
+# Output: {"version":1,"entries":[{"globs":[...],"command","cwd","source"}]}, sorted by source then command; entries
+#   with the same (command, cwd) are merged (globs unioned, first source kept).
+# Sources:
+#   package.json (root + every tracked one outside node_modules): scripts test/lint/typecheck/type-check/check →
+#     `<pm> run <script>` in the package dir (pm from the root lockfile), JS/TS globs under that dir
+#   pytest (pyproject [tool.pytest*], pytest.ini, setup.cfg [tool:pytest], conftest.py) and ruff config → `pytest`,
+#     `ruff check .` (through `uv run` / `poetry run` when that lockfile exists), `**/*.py`
+#   go.mod (dir D) → `go test ./...`, `go vet ./...` in D, `D/**/*.go`, `D/go.mod`, `D/go.sum`
+#   Makefile / GNUmakefile targets test/lint/check/typecheck/vet → `make <target>`, `**`
+#   .github/workflows/*.yml|*.yaml `run:` steps (one command per line of a `|` block, a `>` block is one command).
+#     The engine runs these commands before a PR, so a step is mapped only when its whole
+#     command is an allowlisted check (forge#4300): `<pm> test`, `<pm> run <package.json check script>` (also `test:*`
+#     style names, `pnpm -r`, `npm --prefix DIR`), `make <check target>`, `go test|vet|build`, `cargo test|clippy|check`,
+#     gradle/maven with check tasks/goals only, `[bundle exec] rspec`, `python manage.py test`, `python -m unittest`,
+#     `tox`/`nox` (not a publish/release/deploy/upload env), `deno|bun test`, `bash|sh <path>.test.sh` or a known
+#     test/lint/typecheck tool (forge#4315); everything else is dropped, and job and step names are never consulted. One leading `cd DIR &&` / `pushd DIR &&` becomes the entry cwd; any other chaining,
+#     substitution, `${{ }}`, `$GITHUB_*`, redirect or `<(...)`/`>(...)`, a non-check make target, or a fixer form
+#     (`--fix`, `--write`, `-w`, `black`/`ruff format`/`gofmt`/`prettier` without their check flag) drops the step (forge#4316). Globs from the tool (python/go/shell/js, under the cwd), else the
+#     workflow's `paths:` filter, else `DIR/**` for a cwd; a workflow entry never gets a bare `**`.
+# Exit: 0 ok | 2 usage or bad repo path. bash 3.2 portable.
+set -uo pipefail
+
+die() { echo "test-map: $*" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || die "jq is required"
+REPO="."; OUT=""; STDOUT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo-path) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: test-map.sh [--repo-path DIR] [--output FILE | --stdout]"; REPO="$2"; shift 2 ;;
+    --output) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: test-map.sh [--repo-path DIR] [--output FILE | --stdout]"; OUT="$2"; shift 2 ;;
+    --stdout) STDOUT=1; shift ;;
+    *) die "unknown option: $1" ;;
+  esac
+done
+[ -d "$REPO" ] || die "repo path not found: $REPO"
+case "$OUT" in ""|/*) ;; *) OUT="$PWD/$OUT" ;; esac
+cd "$REPO" || die "cannot enter $REPO"
+
+T=$(mktemp -d "${TMPDIR:-/tmp}/test-map.XXXXXX") || die "mktemp failed"
+trap 'rm -rf "$T"' EXIT
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  # -z and quotepath=off (#4298): non-ASCII and spaced paths come out verbatim, never C-quoted
+  git -c core.quotepath=off ls-files -z --cached --others --exclude-standard | tr '\0' '\n' > "$T/files"
+else
+  find . -type f -not -path './.git/*' | sed 's|^\./||' | sort > "$T/files"
+fi
+: > "$T/rows"
+# row: source TAB cwd TAB command TAB globs separated by US (\037, #4298: a glob may contain spaces)
+US="$(printf '\037')"
+row() { printf '%s\t%s\t%s\t%s\n' "$1" "$2" "$3" "$4" >> "$T/rows"; }
+JS_EXT="js jsx ts tsx mjs cjs"
+# check recognisers shared by package.json scripts / Makefile targets and the workflow allowlist (forge#4300)
+PKG_SCRIPTS="test|lint|typecheck|type-check|check|tsc"
+MAKE_TARGETS="test|lint|check|typecheck|vet"
+# forge#4315: `test:unit`, `lint:css` ... are the same check under a sub-name
+# (#4314: only a closed set of suffixes; fixers `lint:fix`, watchers, e2e/integration (need services), deploy-ish and
+# snapshot-updating scripts never run pre-PR.) $2 (optional) is the script's command: `format` is a check only when
+# that command is a check form.
+PKG_DENY='fix|watch|write|update|dev|serve|start|e2e|integration|deploy|release|publish|snapshot|-u'
+PKG_SUFFIXES="unit ci node types type ts js static check"
+pkg_check_script() {
+  [ -n "${1:-}" ] || return 1
+  case "$1" in *[!A-Za-z0-9:_.-]*) return 1 ;; esac
+  b=${1%%:*}
+  case "|$PKG_SCRIPTS|" in *"|$b|"*) ;; *) return 1 ;; esac
+  [ "$b" = "$1" ] && return 0
+  printf '%s' "$1" | grep -qiE "$PKG_DENY" && return 1
+  rest=${1#*:}; [ -n "$rest" ] || return 1
+  oldifs=$IFS; IFS=:; set -f
+  for seg in $rest; do
+    ok=0
+    case " $PKG_SUFFIXES " in *" $seg "*) [ -n "$seg" ] && ok=1 ;; esac
+    if [ "$ok" = 0 ] && [ "$seg" = format ]; then
+      case " ${2:-} " in *" --check "*|*" -c "*|*" --list-different "*|*" -l "*) ok=1 ;; esac
+    fi
+    [ "$ok" = 1 ] || { IFS=$oldifs; set +f; return 1; }
+  done
+  IFS=$oldifs; set +f
+  return 0
+}
+make_check_target() { case "|$MAKE_TARGETS|" in *"|$1|"*) [ -n "$1" ] ;; *) return 1 ;; esac; }
+has_word() { k=$1; shift; for w in "$@"; do [ "$w" = "$k" ] && return 0; done; return 1; }
+safe_dir() { case "$1" in ""|/*|*[!A-Za-z0-9._/-]*|..|../*|*/..|*/../*) return 1 ;; esac; return 0; }
+# globs for the extensions in $2 under dir $1 ("." = repo root)
+ext_globs() {
+  g=""; pre=""; [ "$1" = "." ] || pre="$1/"
+  for e in $2; do g="$g$US${pre}**/*.$e"; done
+  printf '%s' "${g#"$US"}"
+}
+
+# ---- package.json scripts ----
+PM=npm
+[ -f yarn.lock ] && PM=yarn
+[ -f pnpm-lock.yaml ] && PM=pnpm
+grep -E '(^|/)package\.json$' "$T/files" | grep -v -E '(^|/)node_modules/' | sort | while IFS= read -r pj; do
+  [ -f "$pj" ] || continue
+  d=$(dirname "$pj")
+  globs="$(ext_globs "$d" "$JS_EXT")$US$pj"
+  tag=""
+  if [ -n "$(ls "$d"/vitest.config.* "$d"/jest.config.* 2>/dev/null)" ] || jq -e 'has("jest")' "$pj" >/dev/null 2>&1; then tag=" (vitest/jest config)"; fi
+  jq -r '(.scripts // {}) | to_entries[] | select(.value | type == "string") | .key + "\t" + .value' "$pj" 2>/dev/null | while IFS="$(printf '\t')" read -r s sv; do
+    case "$s" in
+      test) row "$pj#scripts.$s$tag" "$d" "$PM run $s" "$globs" ;;
+      *) pkg_check_script "$s" "$sv" && row "$pj#scripts.$s" "$d" "$PM run $s" "$globs" ;;
+    esac
+  done
+done
+
+# ---- python ----
+RUN=""
+[ -f poetry.lock ] && RUN="poetry run "
+[ -f uv.lock ] && RUN="uv run "
+PY_SRC=""
+if [ -f pyproject.toml ] && grep -qE '^\[tool\.pytest' pyproject.toml; then PY_SRC="pyproject.toml#tool.pytest"
+elif [ -f pytest.ini ]; then PY_SRC="pytest.ini"
+elif [ -f setup.cfg ] && grep -qE '^\[tool:pytest\]' setup.cfg; then PY_SRC="setup.cfg#tool:pytest"
+elif grep -qE '(^|/)conftest\.py$' "$T/files"; then PY_SRC="conftest.py"; fi
+[ -n "$PY_SRC" ] && row "$PY_SRC" "." "${RUN}pytest" "**/*.py$US**/conftest.py"
+RUFF_SRC=""
+if [ -f pyproject.toml ] && grep -qE '^\[tool\.ruff' pyproject.toml; then RUFF_SRC="pyproject.toml#tool.ruff"
+elif [ -f ruff.toml ]; then RUFF_SRC="ruff.toml"
+elif [ -f .ruff.toml ]; then RUFF_SRC=".ruff.toml"; fi
+[ -n "$RUFF_SRC" ] && row "$RUFF_SRC" "." "${RUN}ruff check ." "**/*.py"
+
+# ---- go ----
+grep -E '(^|/)go\.mod$' "$T/files" | grep -v -E '(^|/)vendor/' | sort | while IFS= read -r gm; do
+  d=$(dirname "$gm"); pre=""; [ "$d" = "." ] || pre="$d/"
+  globs="${pre}**/*.go$US${pre}go.mod$US${pre}go.sum"
+  row "$gm" "$d" "go test ./..." "$globs"
+  row "$gm" "$d" "go vet ./..." "$globs"
+done
+
+# ---- Makefile ----
+for mf in Makefile GNUmakefile; do
+  [ -f "$mf" ] || continue
+  grep -oE "^($MAKE_TARGETS)[[:space:]]*:" "$mf" | sed -E 's/[[:space:]]*:$//' | sort -u | while IFS= read -r t; do
+    row "$mf#$t" "." "make $t" "**"
+  done
+done
+
+# ---- CI workflow run: steps ----
+# Emits: job US command (US = \037), one per command line; and P TAB path for each `paths:` filter item
+# before `jobs:`. A block ends at the first non-blank line not indented past the `run` key (sibling keys such as env:).
+wf_extract() {
+  awk '
+    function indent(s) { match(s, /^ */); return RLENGTH }
+    function unq(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); if (s ~ /^".*"$/ || s ~ /^\x27.*\x27$/) s = substr(s, 2, length(s) - 2); return s }
+    function emit(c) { c = unq(c); if (c != "") print job "\037" c }
+    BEGIN { injobs = 0; jind = -1; block = 0; inpaths = 0; job = "" }
+    {
+      line = $0; sub(/\r$/, "", line)
+      if (block) {
+        if (line ~ /^[ \t]*$/) next
+        if (indent(line) > bind) {
+          l = line; sub(/^ +/, "", l)
+          if (fold) { pend = (pend == "" ? l : pend " " l); next }
+          if (pend != "") { l = pend " " l; pend = "" }
+          if (l ~ /\\$/) { pend = substr(l, 1, length(l) - 1); sub(/[ \t]+$/, "", pend); next }
+          emit(l); next
+        }
+        if (pend != "") { emit(pend); pend = "" }
+        block = 0
+      }
+      if (line ~ /^jobs:[ \t]*$/) { injobs = 1; inpaths = 0; next }
+      if (!injobs) {
+        if (line ~ /^[ \t]*paths:[ \t]*$/) { inpaths = 1; pind = indent(line); next }
+        if (inpaths) {
+          if (line ~ /^[ \t]*-[ \t]/ && indent(line) >= pind) { p = line; sub(/^[ \t]*-[ \t]*/, "", p); sub(/[ \t]+#.*$/, "", p); print "P\t" unq(p); next }
+          if (line !~ /^[ \t]*$/ && line !~ /^[ \t]*#/) inpaths = 0
+        }
+        next
+      }
+      if (line ~ /^[^ \t#]/) { injobs = 0; next }
+      if (line ~ /^ +[A-Za-z0-9_-]+:[ \t]*$/ && (jind < 0 || indent(line) == jind)) { jind = indent(line); job = line; sub(/^ +/, "", job); sub(/:.*$/, "", job); next }
+      if (line ~ /^[ \t]*(-[ \t]+)?run:/) {
+        rest = line; sub(/^[ \t]*(-[ \t]+)?run:[ \t]*/, "", rest); sub(/[ \t]+#.*$/, "", rest)
+        # bind = the column of the `run` key: step keys after it (env:, shell:) sit there and end the block
+        if (rest ~ /^[|>][-+0-9]*$/) { block = 1; pend = ""; fold = (rest ~ /^>/); bind = match(line, /run:/) - 1; next }
+        emit(rest)
+      }
+    }
+    END { if (block && pend != "") emit(pend) }
+  ' "$1"
+}
+# forge#4300: allowlist. 0 when the whole command $1 is a recognised check; sets CK_CWD (one leading `cd|pushd DIR &&`,
+# else ".") and CK_CMD (the command without that prefix). Names never matter: a mutating command is dropped whatever its
+# step is called, and a check is mapped whatever it is called.
+check_cmd() {
+  c=$1; CK_CWD=.; CK_CMD=
+  # shellcheck disable=SC2016 # literal ${{ and $( patterns
+  # forge#4316: runner-file writes, redirects and process substitution are CI plumbing, never a local check
+  case "$c" in *'${{'*|*'`'*|*'$('*|*'$GITHUB_'*|*'<'*|*'>'*) return 1 ;; esac
+  case "$c" in
+    "cd "*" && "*|"pushd "*" && "*)
+      d=${c#* }; d=${d%%" && "*}; c=${c#*" && "}
+      case "$d" in ""|/*|*[!A-Za-z0-9._/-]*|..|../*|*/..|*/../*) return 1 ;; esac
+      d=${d%/}; [ -n "$d" ] && [ "$d" != . ] && CK_CWD=$d ;;
+  esac
+  c=${c%" && popd"}
+  case "$c" in *';'*|*'|'*|*'&'*) return 1 ;; esac
+  CK_CMD=$c
+  set -f
+  # shellcheck disable=SC2086 # split into words on purpose; set -f stops glob expansion
+  set -- $c
+  set +f
+  while [ $# -gt 0 ]; do case "$1" in [A-Za-z_]*=*) shift ;; *) break ;; esac; done
+  case "${1:-} ${2:-}" in
+    "uv run"|"poetry run"|"pnpm exec"|"yarn exec"|"python -m"|"python3 -m"|"bundle exec") shift 2 ;;
+    "npx "*|"bunx "*) shift ;;
+  esac
+  # forge#4316: a fixer rewrites the tree; only its read-only check form is a check
+  for w in "$@"; do case "$w" in --fix|--fix=*|--write|-w) return 1 ;; esac; done
+  case "${1:-} ${2:-}" in
+    "black "*|"ruff format") has_word --check "$@" || return 1 ;;
+    "gofmt "*) has_word -l "$@" || has_word -d "$@" || return 1 ;;
+    "prettier "*) has_word --check "$@" || has_word -c "$@" || has_word --list-different "$@" || has_word -l "$@" || return 1 ;;
+  esac
+  case "${1:-}" in
+    npm|pnpm|yarn|bun)
+      pm=$1; shift
+      case "$pm ${1:-}" in # forge#4315: pnpm -r test, npm --prefix DIR test
+        "pnpm -r"|"pnpm --recursive") shift ;;
+        "npm --prefix") [ $# -ge 2 ] && safe_dir "$2" || return 1; shift 2 ;;
+      esac
+      [ "${1:-}" = test ] && return 0
+      [ "${1:-}" = run ] && pkg_check_script "${2:-}" && return 0
+      case "$pm" in yarn|pnpm) pkg_check_script "${1:-}" && return 0 ;; esac
+      return 1 ;;
+    cargo) case "${2:-}" in test|clippy|check) return 0 ;; esac; return 1 ;;
+    ./gradlew|gradlew|gradle|./mvnw|mvnw|mvn)
+      # every non-flag word is a check task/goal (`:mod:test` qualified for gradle); publish/deploy/install never pass
+      case "$1" in *mvn*) goals="test|verify|validate" ;; *) goals="test|check|lint" ;; esac
+      shift; nt=0
+      for w in "$@"; do
+        case "$w" in -*) continue ;; esac
+        t=${w##*:}
+        case "|$goals|" in *"|$t|"*) [ -n "$t" ] && nt=$((nt+1)) ;; *) return 1 ;; esac
+      done
+      [ "$nt" -gt 0 ]; return ;;
+    rspec|unittest) return 0 ;;
+    python|python3) [ "${2:-}" = manage.py ] && [ "${3:-}" = test ]; return ;;
+    tox|nox)
+      shift; prev=""
+      for w in "$@"; do
+        case "$prev" in -e|-s|--env|--session|--sessions) case ",$w," in *publish*|*release*|*deploy*|*upload*) return 1 ;; esac ;; esac
+        case "$w" in -e*|-s*) case "${w#-?}" in *publish*|*release*|*deploy*|*upload*) return 1 ;; esac ;; esac
+        prev=$w
+      done
+      return 0 ;;
+    deno) [ "${2:-}" = test ]; return ;;
+    bash|sh) case "${2:-}" in *.test.sh) safe_dir "$2"; return ;; esac; return 1 ;;
+    make)
+      # forge#4316: every target must be a check (`make test deploy` is dropped); VAR=value and flags are not targets
+      shift; nt=0
+      for w in "$@"; do case "$w" in -*|*=*) continue ;; esac; make_check_target "$w" || return 1; nt=$((nt+1)); done
+      [ "$nt" -gt 0 ]; return ;;
+    go) case "${2:-}" in test|vet|build) return 0 ;; esac; return 1 ;;
+    node) [ "${2:-}" = --test ]; return ;;
+    eslint|tsc|prettier|vitest|jest|pytest|ruff|flake8|pylint|mypy|black|golangci-lint|gofmt|staticcheck|shellcheck) return 0 ;;
+  esac
+  return 1
+}
+tool_globs() {
+  c=" $1 "
+  case "$c" in
+    *\ cargo\ *) printf '%s' "**/*.rs$US**/Cargo.toml${US}Cargo.lock"; return ;;
+    *gradlew\ *|*\ gradle\ *|*mvnw\ *|*\ mvn\ *) printf '%s' "$(ext_globs . "java kt kts gradle groovy scala")$US**/pom.xml"; return ;;
+    *[\ /]rspec\ *) printf '**/*.rb'; return ;;
+    *\ manage.py\ test\ *|*\ unittest\ *|*\ tox\ *|*\ nox\ *) printf '**/*.py'; return ;;
+    *\ npm\ --prefix\ *) d=${1#*--prefix }; d=${d%% *}; ext_globs "$d" "$JS_EXT"; return ;;
+    *\ deno\ *|*\ bun\ *|*\ bunx\ *) ext_globs . "$JS_EXT"; return ;;
+    *[\ /]ruff\ *|*[\ /]flake8\ *|*[\ /]pylint\ *|*[\ /]mypy\ *|*[\ /]black\ *|*[\ /]pytest\ *) printf '**/*.py'; return ;;
+    *[\ /]golangci-lint\ *|*[\ /]gofmt\ *|*[\ /]staticcheck\ *|*\ go\ *) printf '**/*.go'; return ;;
+    *[\ /]shellcheck\ *|*\ bash\ *.sh\ *|*\ sh\ *.sh\ *) printf '**/*.sh'; return ;;
+    *[\ /]eslint\ *|*[\ /]tsc\ *|*[\ /]prettier\ *|*[\ /]vitest\ *|*[\ /]jest\ *|*\ node\ --test*|*\ npm\ *|*\ pnpm\ *|*\ yarn\ *|*\ npx\ *) ext_globs . "$JS_EXT"; return ;;
+  esac
+  printf ''
+}
+grep -E '^\.github/workflows/[^/]+\.(yml|yaml)$' "$T/files" | sort | while IFS= read -r wf; do
+  [ -f "$wf" ] || continue
+  wf_extract "$wf" > "$T/wf"
+  paths=$(awk -F'\t' '$1 == "P" { printf "%s\037", $2 }' "$T/wf"); paths=${paths%"$US"}
+  awk -F'\t' '$1 != "P"' "$T/wf" | while IFS="$US" read -r job cmd; do
+    check_cmd "$cmd" || continue
+    g=$(tool_globs "$CK_CMD")
+    [ -n "$g" ] && [ "$CK_CWD" != . ] && g="$CK_CWD/${g//$US/$US$CK_CWD/}"
+    [ -n "$g" ] || g="$paths"
+    [ -n "$g" ] || { [ "$CK_CWD" != . ] && g="$CK_CWD/**"; }
+    [ -n "$g" ] || continue
+    row "$wf#jobs.$job" "$CK_CWD" "$CK_CMD" "$g"
+  done
+done
+
+MAP=$(jq -R -s -c '
+  [split("\n")[] | select(length > 0) | split("\t") | {source: .[0], cwd: .[1], command: .[2], globs: (.[3] | split("\u001f") | map(select(length > 0)))}]
+  | sort_by(.source, .command)
+  | reduce .[] as $e ({order: [], by: {}};
+      ([$e.command, $e.cwd] | tojson) as $k
+      | if .by[$k] then .by[$k].globs += ($e.globs - .by[$k].globs)
+        else .order += [$k] | .by[$k] = {globs: $e.globs, command: $e.command, cwd: $e.cwd, source: $e.source} end)
+  | {version: 1, entries: [.by[.order[]]]}' < "$T/rows") || die "jq failed"
+
+if [ "$STDOUT" = 1 ]; then printf '%s\n' "$MAP"; exit 0; fi
+[ -n "$OUT" ] || OUT=".forge/test-map.json"
+mkdir -p "$(dirname "$OUT")" || die "cannot create $(dirname "$OUT")"
+printf '%s\n' "$MAP" > "$OUT.tmp.$$" || die "cannot write $OUT"
+mv "$OUT.tmp.$$" "$OUT" || die "cannot write $OUT"
+echo "$OUT"