forgedock 1.30.0 → 1.31.0

package/scripts/review-staging-pre.test.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# review-staging-pre.test.sh — cases for scripts/review-staging-pre.sh (forge#4358): bundle PR set, open review-finding gate,
+# 0B.1 scope. Since #4359 the script is the only copy of these blocks (the spec calls `forgedock review-staging`).
+# gh is a PATH stub reading per-case fixtures; git runs against a throwaway repo with a local bare "origin".
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PRE="$ROOT/scripts/review-staging-pre.sh"
+PASS=0; FAILN=0
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+command -v jq >/dev/null 2>&1 || { echo "review-staging-pre.test.sh: jq missing, skipped"; exit 0; }
+command -v git >/dev/null 2>&1 || { echo "review-staging-pre.test.sh: git missing, skipped"; exit 0; }
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+export FORGEDOCK_HOME="$ROOT"   # resolve helpers from this checkout, not an ambient install
+
+# (1) the blocks live only here: present in the script, absent from the spec
+for b in bundle-pr-set bundle-pr-kind bundle-delta-credit bundle-scope-loop; do
+  grep -qx "# BEGIN $b" "$PRE" && grep -qx "# END $b" "$PRE" && ok || bad "block $b missing from review-staging-pre.sh"
+  grep -qx "# BEGIN $b" "$ROOT/commands/review-pr-staging.md" && bad "block $b still copied into commands/review-pr-staging.md" || ok
+done
+
+# (2) usage errors
+bash "$PRE" bogus --repo o/r --pr 1 >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "unknown subcommand must exit 2"
+bash "$PRE" gate --repo o/r --pr x --prs-file /dev/null >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "non-numeric --pr must exit 2"
+bash "$PRE" gate --repo o/r --pr 9 --prs-file "$TMP/none" >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "unreadable --prs-file must exit 2 (never an empty bundle)"
+bash "$PRE" scope --repo o/r --pr 9 --default main --staging staging --prs-file /dev/null --sd "$TMP/sd" --bogus 1 >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "unknown flag must exit 2"
+
+# gh stub: fixtures in $FIX; posted comment bodies are appended to $FIX/posted
+mkdir -p "$TMP/bin"
+cat > "$TMP/bin/gh" <<'STUB'
+#!/usr/bin/env bash
+F="$FIX"; a="$*"
+# fail-labels / fail-issues: the degraded-label / review-finding read fails (rate limit, 5xx, expired auth)
+case "$a" in "pr view"*"--json labels"*) [ -f "$F/fail-labels" ] && exit 1 ;; "issue list"*) [ -f "$F/fail-issues" ] && exit 1 ;; esac
+case "$1 $2" in
+  "pr comment") while [ $# -gt 0 ]; do [ "$1" = --body ] && { printf '%s\n@@\n' "$2" >> "$F/posted"; }; shift; done; exit 0 ;;
+  "pr diff") [ -f "$F/files-$3" ] && { cat "$F/files-$3"; exit 0; }; exit 1 ;;
+  "pr view")
+    case "$a" in *"--json labels"*) [ -f "$F/degraded-$3" ] && echo true || echo false; exit 0 ;; esac
+    [ -f "$F/pr-$3.json" ] && { cat "$F/pr-$3.json"; exit 0; }; exit 1 ;;
+  "issue list")
+    n=$(printf '%s' "$a" | sed -n 's/.*--search PR #\([0-9]*\).*/\1/p')
+    [ -f "$F/findings-$n.json" ] && cat "$F/findings-$n.json" || echo '[]'; exit 0 ;;
+esac
+if [ "$1" = api ]; then
+  case "$a" in
+    *"/comments"*) n=$(printf '%s' "$a" | sed -n 's#.*issues/\([0-9]*\)/comments.*#\1#p'); [ -f "$F/comments-$n.json" ] && cat "$F/comments-$n.json" || echo '[]'; exit 0 ;;
+    *"repos/o/r/issues/"*) n=$(printf '%s' "$a" | sed -n 's#.*repos/o/r/issues/\([0-9]*\).*#\1#p'); [ -f "$F/issue-$n" ] && echo issue || echo pr; exit 0 ;;
+  esac
+fi
+echo "gh stub: unhandled: $a" >&2; exit 1
+STUB
+chmod +x "$TMP/bin/gh"
+export PATH="$TMP/bin:$PATH"
+newfix() { FIX="$TMP/fix.$1"; rm -rf "$FIX"; mkdir -p "$FIX"; export FIX; }
+
+# throwaway repo: main, then staging = merge of PR #5 (feature commit) + a direct commit citing issue #77
+G() { git -C "$TMP/work" -c user.email=t@t -c user.name=t -c commit.gpgsign=false "$@"; }
+git init -q --bare "$TMP/origin.git"
+git init -q "$TMP/work"; G checkout -q -b main
+echo base > "$TMP/work/base.txt"; G add -A; G commit -qm base; G remote add origin "$TMP/origin.git"; G push -q origin main
+G checkout -q -b staging; G checkout -q -b feat
+echo a > "$TMP/work/a.js"; G add -A; G commit -qm "feat: a"; FEAT=$(G rev-parse HEAD)
+G checkout -q staging; G merge -q --no-ff feat -m "Merge pull request #5 from o/feat"; MERGE=$(G rev-parse HEAD)
+mkdir -p "$TMP/work/.github/workflows"; echo b > "$TMP/work/b.js"; echo x > "$TMP/work/.github/workflows/ci.yml"
+G add -A; G commit -qm "fix: thing (#77)"; DIRECT=$(G rev-parse HEAD); G push -q origin staging
+run() { (cd "$TMP/work" && bash "$PRE" "$@"); }
+
+# (3) bundle: the merge-subject PR is kept, the issue cited in a subject is skipped, the list is persisted
+newfix bundle; : > "$FIX/issue-77"
+OUT=$(run bundle --repo o/r --default main --staging staging --pr 9 --sd "$TMP/sd" 2>&1); RC=$?
+[ "$RC" -eq 0 ] && ok || bad "bundle must exit 0 (got $RC: $OUT)"
+[ "$(cat "$TMP/sd/9_bundle-prs.txt" 2>/dev/null)" = 5 ] && ok || bad "bundle must persist exactly PR 5 (got '$(cat "$TMP/sd/9_bundle-prs.txt" 2>/dev/null)')"
+case "$OUT" in *"skipped): 77"*) ok ;; *) bad "bundle must report the skipped issue 77 (got '$OUT')" ;; esac
+
+# (4) gate
+printf '5\n' > "$TMP/prs"
+newfix clean; OUT=$(run gate --repo o/r --pr 9 --prs-file "$TMP/prs" 2>&1); RC=$?
+[ "$RC" -eq 0 ] && ok || bad "clean gate must exit 0 (got $RC)"
+case "$OUT" in *"RESULT: PASS"*) ok ;; *) bad "clean gate must print RESULT: PASS" ;; esac
+grep -qx '<!-- FORGE:GATE_PASS:TYPE=open-review-finding -->' "$FIX/posted" && head -1 "$FIX/posted" | grep -qx '<!-- FORGE:GATE_PASS -->' && ok || bad "clean gate must post the unchanged GATE_PASS body"
+newfix degraded; : > "$FIX/degraded-5"
+run gate --repo o/r --pr 9 --prs-file "$TMP/prs" >/dev/null 2>&1; RC=$?
+[ "$RC" -eq 1 ] && grep -q 'FORGE:GATE_FAILURE:TYPE=review-panel-integrity' "$FIX/posted" && ok || bad "degraded panel must block with review-panel-integrity (rc $RC)"
+newfix finding; jq -n '[{number:41,title:"bug (PR #5)",body:"x"}]' > "$FIX/findings-5.json"
+OUT=$(run gate --repo o/r --pr 9 --prs-file "$TMP/prs" 2>&1); RC=$?
+[ "$RC" -eq 1 ] && ok || bad "an open finding must block (rc $RC)"
+case "$OUT" in *"RESULT: BLOCK DEPLOY"*) ok ;; *) bad "blocked gate must print RESULT: BLOCK DEPLOY" ;; esac
+grep -q 'FORGE:GATE_FAILURE:TYPE=open-review-finding|FINDINGS=1' "$FIX/posted" && ok || bad "blocked gate must post the GATE_FAILURE marker with FINDINGS=1"
+newfix unanchored; jq -n '[{number:41,title:"bug (PR #55)",body:"x"}]' > "$FIX/findings-5.json"
+run gate --repo o/r --pr 9 --prs-file "$TMP/prs" >/dev/null 2>&1; [ $? -eq 0 ] && ok || bad "a finding for another PR (#55) must not block #5"
+newfix override; jq -n '[{number:41,title:"bug (PR #5)",body:"x"}]' > "$FIX/findings-5.json"
+jq -n '[{body:"OVERRIDE: shipping with open findings — known",author_association:"OWNER",user:{type:"User",login:"o"}}]' > "$FIX/comments-9.json"
+OUT=$(run gate --repo o/r --pr 9 --prs-file "$TMP/prs" 2>&1); RC=$?
+[ "$RC" -eq 0 ] && case "$OUT" in *"RESULT: PASS"*) true ;; *) false ;; esac && ok || bad "a trusted override must pass (rc $RC)"
+newfix untrusted; jq -n '[{number:41,title:"bug (PR #5)",body:"x"}]' > "$FIX/findings-5.json"
+jq -n '[{body:"OVERRIDE: shipping with open findings — x",author_association:"NONE",user:{type:"User",login:"z"}}]' > "$FIX/comments-9.json"
+run gate --repo o/r --pr 9 --prs-file "$TMP/prs" >/dev/null 2>&1; [ $? -eq 1 ] && ok || bad "an untrusted override must not pass"
+# forge#4470: the gate fails closed. A failed gh read or an empty bundle never posts GATE_PASS.
+printf '101\n102\n' > "$TMP/prs2"
+newfix ghfail; : > "$FIX/fail-labels"; : > "$FIX/fail-issues"
+OUT=$(run gate --repo o/r --pr 9 --prs-file "$TMP/prs2" 2>&1); RC=$?
+[ "$RC" -eq 1 ] && ok || bad "gh read failure blocks: gate must exit 1 when every gh read fails (rc $RC)"
+case "$OUT" in *"RESULT: BLOCK DEPLOY"*) ok ;; *) bad "gh read failure blocks: must print RESULT: BLOCK DEPLOY (got '$OUT')" ;; esac
+! grep -q 'FORGE:GATE_PASS' "$FIX/posted" 2>/dev/null && ok || bad "gh read failure blocks: must not post GATE_PASS"
+grep -q 'FORGE:GATE_FAILURE:TYPE=gate-read-failure' "$FIX/posted" 2>/dev/null && ok || bad "gh read failure blocks: must post TYPE=gate-read-failure"
+newfix issuefail; : > "$FIX/fail-issues"
+run gate --repo o/r --pr 9 --prs-file "$TMP/prs" >/dev/null 2>&1; RC=$?
+[ "$RC" -eq 1 ] && ! grep -q 'FORGE:GATE_PASS' "$FIX/posted" 2>/dev/null && ok || bad "a failed review-finding read alone must block without GATE_PASS (rc $RC)"
+newfix labelfail; : > "$FIX/fail-labels"
+run gate --repo o/r --pr 9 --prs-file "$TMP/prs" >/dev/null 2>&1; RC=$?
+[ "$RC" -eq 1 ] && ! grep -q 'FORGE:GATE_PASS' "$FIX/posted" 2>/dev/null && ok || bad "a failed degraded-label read alone must block without GATE_PASS (rc $RC)"
+newfix readfailoverride; : > "$FIX/fail-issues"
+jq -n '[{body:"OVERRIDE: shipping with open findings — known",author_association:"OWNER",user:{type:"User",login:"o"}}]' > "$FIX/comments-9.json"
+run gate --repo o/r --pr 9 --prs-file "$TMP/prs" >/dev/null 2>&1; [ $? -eq 1 ] && ok || bad "a trusted override must not waive a read failure"
+newfix emptyprs; : > "$TMP/prs-empty"
+OUT=$(run gate --repo o/r --pr 9 --prs-file "$TMP/prs-empty" 2>&1); RC=$?
+[ "$RC" -eq 1 ] && ! grep -q 'FORGE:GATE_PASS' "$FIX/posted" 2>/dev/null && ok || bad "an empty prs-file must block without GATE_PASS (rc $RC: $OUT)"
+newfix emptybundle
+run bundle --repo o/r --default staging --staging staging --pr 8 --sd "$TMP/sd" >/dev/null 2>&1; RC=$?
+[ "$RC" -ne 0 ] && ok || bad "an empty bundle PR set must exit non-zero"
+newfix fetchfail
+run bundle --repo o/r --default main --staging no-such-branch --pr 8 --sd "$TMP/sd" >/dev/null 2>&1; RC=$?
+[ "$RC" -ne 0 ] && ok || bad "a failed git fetch must exit non-zero"
+
+# (5) scope: PR 5 reviewed at its final head -> scoped; the direct commit and its files are unreviewed
+newfix scope; H7=${FEAT:0:7}
+jq -n --arg h "$FEAT" --arg m "$MERGE" '{headRefOid:$h,mergeCommit:{oid:$m},commits:[{oid:$h}],state:"MERGED",baseRefName:"staging",labels:[]}' > "$FIX/pr-5.json"
+printf 'a.js\n' > "$FIX/files-5"
+jq -n --arg r "<!-- FORGE:REVIEW_ROUTE mode=single-pr spec=review-pr.md sha=$H7 -->" \
+  --arg g "$(printf '<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: %s\n\n<!-- REVIEW-FINDINGS-START -->\n<!-- REVIEW-FINDINGS-END -->' "$FEAT")" \
+  '[{body:$r,author_association:"NONE",user:{type:"Bot",login:"b"}},{body:$g,author_association:"NONE",user:{type:"Bot",login:"b"}}]' > "$FIX/comments-5.json"
+OUT=$(run scope --repo o/r --default main --staging staging --pr 9 --prs-file "$TMP/prs" --sd "$TMP/sd" 2>&1); RC=$?
+[ "$RC" -eq 0 ] && ok || bad "scope must exit 0 (got $RC: $OUT)"
+J="$TMP/sd/9_scope.json"
+[ "$(jq -r .scope_mode "$J" 2>/dev/null)" = scoped ] && ok || bad "a reviewed bundle must be scoped (got $(jq -c . "$J" 2>/dev/null); $OUT)"
+[ "$(jq -r '.unreviewed_commits | join(" ")' "$J" 2>/dev/null)" = "$DIRECT" ] && ok || bad "only the direct commit is unreviewed (got $(jq -c .unreviewed_commits "$J" 2>/dev/null))"
+jq -e '.unreviewed_files | index("b.js")' "$J" >/dev/null 2>&1 && ! jq -e '.unreviewed_files | index("a.js")' "$J" >/dev/null 2>&1 && ok || bad "unreviewed files must hold b.js and not a.js"
+jq -e '.deploy_wiring_files | index(".github/workflows/ci.yml")' "$J" >/dev/null 2>&1 && ok || bad "workflow files are deploy wiring"
+jq -e '.reviewed_pr_count == 1' "$J" >/dev/null 2>&1 && ok || bad "reviewed_pr_count must be 1"
+grep -q '^SCOPE_MODE=scoped$' "$TMP/sd/9_scope.env" && grep -q '^5 a.js$' "$TMP/sd/9_bundle-pr-files.txt" && ok || bad "scope.env and bundle-pr-files.txt keep the spec's format"
+case "$OUT" in *"SCOPE_MODE=scoped reviewed_prs=1"*) ok ;; *) bad "scope must print the one-line summary" ;; esac
+newfix scopefail
+run scope --repo o/r --default main --staging staging --pr 9 --prs-file "$TMP/prs" --sd "$TMP/sd" >/dev/null 2>&1
+[ "$(jq -r .scope_mode "$TMP/sd/9_scope.json" 2>/dev/null)" = full ] && ok || bad "a failed gh pr view must widen scope to full"
+
+echo "review-staging-pre.test.sh: passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/symbol-index.mjs

@@ -8,13 +8,17 @@
 // run prints only {"unsupported":"ts"|"js","reason":"no-parser"} and exits 0.
 // .py targets are handed to symbol-index.py. Never emits source text or literal values.
 //
-// Usage: node scripts/symbol-index.mjs <file | dir>...
+// Usage: node scripts/symbol-index.mjs [--shape] <file | dir>...
 // Output: {"symbols":[{name,kind,start,end,lines,public[,file]}], "edges":[{from,to}],
 //          "imports":[{module,names,line[,file]}], "cycles":[[module,...],...]}
 //   kind: function|async_function|class|method|const|interface|type|enum. public = exported (methods: exported class
 //   and not private/#private). One file: bare names; otherwise `file` on entries and "<module>:<symbol>" edge ends,
 //   module = path relative to its root without extension (index files name their directory). cycles = strongly
 //   connected components of the relative-import graph between indexed modules (`import type` ignored).
+//   --shape (forge#4449, bin/lean/apishape.mjs): functions, methods/accessors/constructors and consts initialised with
+//   an arrow or function expression also carry async, generator (`function*`) and sig: the normalized parameter list
+//   (`...` rest, name, `?` optional, `: <type text>`, `=` for a default but never its value) plus " -> <return type>".
+//   Kinds are unchanged; without --shape the output is unchanged. --shape is forwarded to symbol-index.py.
 // Exit: 0 ok or unsupported | 2 usage or missing path.
 
 import { spawnSync } from "node:child_process";
@@ -94,7 +98,18 @@ function tarjan(graph) {
   return comps;
 }
 
-function index(ts, entries, multi) {
+function fnShape(ts, fn, src) {
+  const K = ts.SyntaxKind;
+  const params = fn.parameters.map((p) => `${p.dotDotDotToken ? "..." : ""}${p.name.getText(src)}${p.questionToken ? "?" : ""}`
+    + `${p.type ? `: ${p.type.getText(src)}` : ""}${p.initializer ? "=" : ""}`);
+  return {
+    async: (ts.getModifiers?.(fn) ?? fn.modifiers ?? []).some((m) => m.kind === K.AsyncKeyword),
+    generator: !!fn.asteriskToken,
+    sig: `(${params.join(", ")})${fn.type ? ` -> ${fn.type.getText(src)}` : ""}`,
+  };
+}
+
+function index(ts, entries, multi, shape = false) {
   const K = ts.SyntaxKind;
   const byFile = new Map(entries.map((e) => [path.resolve(e.file), e]));
   const symbols = [], imports = [], edges = new Set(), graph = new Map(entries.map((e) => [e.module, new Set()]));
@@ -114,7 +129,9 @@ function index(ts, entries, multi) {
     tables.set(e.module, table);
     const add = (name, kind, node, pub, owner = null) => {
       const start = line(src, node.getStart(src)), end = line(src, node.getEnd());
-      symbols.push({ name, kind, start, end, lines: end - start + 1, public: !!pub, ...(multi ? { file: e.file } : {}) });
+      const fn = !shape ? null : ts.isFunctionLike(node) ? node
+        : ts.isVariableDeclaration(node) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer)) ? node.initializer : null;
+      symbols.push({ name, kind, start, end, lines: end - start + 1, public: !!pub, ...(multi ? { file: e.file } : {}), ...(fn ? fnShape(ts, fn, src) : {}) });
       table.set(name, { node, owner });
     };
     const exportNames = new Set();
@@ -218,9 +235,11 @@ function index(ts, entries, multi) {
   };
 }
 
-function main(argv) {
+function main(args) {
+  const shape = args.includes("--shape");
+  const argv = args.filter((a) => a !== "--shape");
   if (!argv.length || argv[0] === "-h" || argv[0] === "--help") {
-    process.stderr.write("usage: symbol-index.mjs <file | dir>...\n");
+    process.stderr.write("usage: symbol-index.mjs [--shape] <file | dir>...\n");
     return 2;
   }
   for (const p of argv) if (!existsSync(p)) { process.stderr.write(`symbol-index: no such path: ${p}\n`); return 2; }
@@ -229,7 +248,7 @@ function main(argv) {
   if (exts.includes(".py")) {
     if (exts.some((x) => x !== ".py")) return emit({ unsupported: "mixed", reason: "mixed-languages" }), 0;
     const py = path.join(path.dirname(fileURLToPath(import.meta.url)), "symbol-index.py");
-    const r = spawnSync("python3", [py, ...argv], { stdio: "inherit" });
+    const r = spawnSync("python3", [py, ...(shape ? ["--shape"] : []), ...argv], { stdio: "inherit" });
     if (r.error) return emit({ unsupported: "python", reason: "no-python3" }), 0;
     return r.status ?? 2;
   }
@@ -242,7 +261,7 @@ function main(argv) {
   if (!ts) return emit({ unsupported: lang, reason: "no-parser" }), 0;
   const multi = !(argv.length === 1 && files.length === 1);
   let out;
-  try { out = index(ts, entries, multi); } catch (err) {
+  try { out = index(ts, entries, multi, shape); } catch (err) {
     if (err && err.reason) return emit({ unsupported: err.lang, reason: err.reason }), 0;
     throw err;
   }

package/scripts/symbol-index.py

@@ -5,13 +5,16 @@
 # symbol-index.py: deterministic Python symbol index + module import-cycle detector for refactor:split (forge#4208).
 # stdlib only (ast). No LLM, no network. Never emits source text, docstrings or literal values.
 #
-# Usage: python3 scripts/symbol-index.py <file.py | dir>...
+# Usage: python3 scripts/symbol-index.py [--shape] <file.py | dir>...
 # Output (stdout, one JSON object):
 #   {"symbols":[{name,kind,start,end,lines,public[,file]}], "edges":[{from,to}],
 #    "imports":[{module,names,line[,file]}], "cycles":[[module,...],...]}
 #   kind: function|async_function|class|method|const. Methods (and nested classes) are named Class.method.
 #   start includes decorators; lines = end - start + 1. public = no leading underscore (method dunders count as
 #   public), and listed in a static __all__ when the module defines one.
+#   --shape (forge#4449, bin/lean/apishape.mjs): function/async_function/method entries also carry async (bool),
+#   generator (yield in the def's own scope) and sig: the normalized parameter list (kinds, names, annotation text,
+#   "=" for a default but never its value) plus " -> <return annotation>". Without --shape the output is unchanged.
 #   One .py file: names are bare. Otherwise (a directory or several files) each entry carries `file` and edge ends
 #   are "<module>:<symbol>"; module names are dotted paths relative to each root (a root that has __init__.py is
 #   itself the top package, so root .../pkg yields pkg.a). edges = references from one indexed symbol to another.
@@ -108,9 +111,47 @@ def module_imports(body):
     return out
 
 
+def is_generator(fn):
+    """True when yield / yield from occurs in fn's own scope (not in nested defs, lambdas or classes)."""
+    work = list(ast.iter_child_nodes(fn))
+    while work:
+        n = work.pop()
+        if isinstance(n, (ast.Yield, ast.YieldFrom)):
+            return True
+        if not isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)):
+            work.extend(ast.iter_child_nodes(n))
+    return False
+
+
+def signature(fn):
+    """Normalized parameter list of a def: names, kinds, annotation text, '=' for a default (never its value)."""
+    a = fn.args
+
+    def one(arg, default=False, prefix=""):
+        out = prefix + arg.arg
+        if arg.annotation is not None:
+            out += ": " + ast.unparse(arg.annotation)
+        return out + ("=" if default else "")
+
+    positional = a.posonlyargs + a.args
+    first_default = len(positional) - len(a.defaults)
+    parts = [one(x, i >= first_default) for i, x in enumerate(positional)]
+    if a.posonlyargs:
+        parts.insert(len(a.posonlyargs), "/")
+    if a.vararg is not None:
+        parts.append(one(a.vararg, prefix="*"))
+    elif a.kwonlyargs:
+        parts.append("*")
+    parts += [one(x, d is not None) for x, d in zip(a.kwonlyargs, a.kw_defaults)]
+    if a.kwarg is not None:
+        parts.append(one(a.kwarg, prefix="**"))
+    sig = "(" + ", ".join(parts) + ")"
+    return sig + (" -> " + ast.unparse(fn.returns) if fn.returns is not None else "")
+
+
 class Module:
-    def __init__(self, path, name, is_pkg):
-        self.path, self.name, self.is_pkg = path, name, is_pkg
+    def __init__(self, path, name, is_pkg, shape=False):
+        self.path, self.name, self.is_pkg, self.shape = path, name, is_pkg, shape
         self.symbols = []      # dicts without file
         self.nodes = {}        # symbol name -> (ast node, owning class name or None)
         self.imports = []      # (ast import node)
@@ -131,8 +172,11 @@ class Module:
 
         def add(name, kind, node, public, owner=None):
             start, end = def_start(node), node.end_lineno or node.lineno
-            self.symbols.append({"name": name, "kind": kind, "start": start, "end": end,
-                                 "lines": end - start + 1, "public": public})
+            sym = {"name": name, "kind": kind, "start": start, "end": end, "lines": end - start + 1, "public": public}
+            if self.shape and isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                sym.update({"async": isinstance(node, ast.AsyncFunctionDef), "generator": is_generator(node),
+                            "sig": signature(node)})
+            self.symbols.append(sym)
             self.nodes[name] = (node, owner)
 
         def add_class(node, prefix, public):
@@ -241,12 +285,12 @@ def tarjan(graph):
     return comps
 
 
-def build(paths):
+def build(paths, shape=False):
     entries = walk_roots(paths)
     multi = not (len(entries) == 1 and os.path.isfile(paths[0]) and len(paths) == 1)
     modules, by_name = [], {}
     for path, name, is_pkg in entries:
-        m = Module(path, name, is_pkg)
+        m = Module(path, name, is_pkg, shape)
         m.parse()
         modules.append(m)
         by_name.setdefault(name, m)
@@ -335,15 +379,17 @@ def build(paths):
 
 
 def main(argv):
+    shape = "--shape" in argv
+    argv = [a for a in argv if a != "--shape"]
     if not argv or argv[0] in ("-h", "--help"):
-        sys.stderr.write("usage: symbol-index.py <file.py | dir>...\n")
+        sys.stderr.write("usage: symbol-index.py [--shape] <file.py | dir>...\n")
         return 2
     for p in argv:
         if not os.path.exists(p):
             sys.stderr.write("symbol-index: no such path: %s\n" % p)
             return 2
     try:
-        out = build(argv)
+        out = build(argv, shape)
     except Unsupported as u:
         out = {"unsupported": u.lang, "reason": u.reason}
     sys.stdout.write(json.dumps(out, sort_keys=True, separators=(",", ":")) + "\n")

package/scripts/trusted-comments.test.sh

@@ -67,7 +67,7 @@ eq "trusted synthesis accepted" "$(printf '[%s]' "$(c NONE Bot b "$FAKE_SYN")" |
 eq "synthesis marker mid-body rejected" "$(printf '[%s]' "$(c NONE Bot b "intro${NL}${FAKE_SYN}")" | bash "$TC" count "$SYNTH_RE")" 0
 eq "synthesis for a different head rejected" "$(printf '[%s]' "$(c NONE Bot b "<!-- REVIEW-FINDINGS-SYNTHESIZED-START -->${NL}Reviewed-SHA: ${OTHER}")" | bash "$TC" count "$SYNTH_RE")" 0
 
-# Staging review spec (commands/review-pr-staging.md): same predicate, domains may carry digits/hyphens (bug-hunter-api)
+# Staging review (scripts/review-staging-post.sh delivery, formerly the commands/review-pr-staging.md fences): same predicate, domains may carry digits/hyphens (bug-hunter-api)
 STG_RE="^<!-- FORGE:REVIEW-AGENT:[a-z0-9-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${SHA}(\\r?\\n|\$)"
 STG_DOM_RE="^<!-- FORGE:REVIEW-AGENT:bug-hunter-api -->[\\s\\S]*(^|\\n)Reviewed-SHA: ${SHA}(\\r?\\n|\$)"
 STG_TRUE="<!-- FORGE:REVIEW-AGENT:bug-hunter-api -->${NL}Reviewed-SHA: ${SHA}${NL}<!-- FINDING:real-2 -->"