forgedock 1.27.0 → 1.28.0

package/scripts/check-devdocs-freshness.test.sh

@@ -114,7 +114,17 @@ run "no relevant changes pass" 0
 
 reset
 env PR_BODY="" bash "$S" no/such-ref >"$TMP/out" 2>&1; [ $? = 2 ] && PASS=$((PASS+1)) || bad "unknown base ref exits 2"
-env bash "$S" >"$TMP/out" 2>&1; [ $? = 2 ] && PASS=$((PASS+1)) || bad "missing base ref exits 2"
+env bash "$S" >"$TMP/out" 2>&1; [ $? = 2 ] && PASS=$((PASS+1)) || bad "missing base ref and no upstream exits 2"
+
+# #4220: without a base ref the branch's upstream is the base (CI always passes it explicitly).
+git branch -q --set-upstream-to=origin/staging
+printf '#!/bin/sh\necho bar\n' > scripts/foo.sh; commit
+env PR_BODY="" bash "$S" >"$TMP/out" 2>&1; [ $? = 1 ] && PASS=$((PASS+1)) || bad "no base ref: upstream diff, docs missing fails"
+printf 'docs-not-needed: fixture\n' > "$TMP/body"
+env PR_BODY="" bash "$S" --body-file "$TMP/body" >"$TMP/out" 2>&1; [ $? = 0 ] && PASS=$((PASS+1)) || bad "no base ref + --body-file uses the upstream"
+printf '# ADR\n' > devdocs/decisions/4220-x.md; commit
+env PR_BODY="" bash "$S" >"$TMP/out" 2>&1; [ $? = 0 ] && PASS=$((PASS+1)) || bad "no base ref: upstream diff with a new decision passes"
+git branch -q --unset-upstream
 
 echo "check-devdocs-freshness.test.sh: $PASS passed, $FAILN failed"
 [ "$FAILN" = 0 ]

package/scripts/check-spec-markers.sh

@@ -91,7 +91,9 @@ MARKER_REGISTRY="
   BENCH_SCORECARD
   BLAST_RADIUS
   BLOCKED_ON_HUMAN_MERGE
+  BOOTSTRAP_PLAN
   BODY
+  BOOTSTRAP_PLAN
   BUILDER
   BUILD_BLOCKED
   CALIBRATION_CHECK
@@ -106,6 +108,7 @@ MARKER_REGISTRY="
   COORD_ISSUE
   CRITIQUE
   DECISION_RECORD
+  BOOTSTRAP_PLAN
   DECOMPOSED
   DECOMPOSE_BLOCKED
   DEGRADED_REREVIEW

package/scripts/check-spec-size.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# check-spec-size.sh — PR spec-size budget (forge#3762).
+# check-spec-size.sh — PR spec-size budget for every command spec (forge#3762, #4164).
 # SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #
@@ -13,7 +13,9 @@
 # Exit:  0 pass/exempt, 1 budget violation, 2 usage/base-ref error (fail closed)
 #
 # Rules (against the merge-base of HEAD and the PR base, compared in bytes):
-#   1. Budgeted specs may not grow by more than 2% or more than 4096 bytes.
+#   1. Every commands/**/*.md spec (head files plus files deleted at head) may not grow by more
+#      than 2% or more than 4096 bytes. A new spec (absent at the base) may be at most 4096 bytes.
+#      CEILINGS adds a per-file hard size cap (path:max_bytes) checked whatever the growth.
 #   2. The NET count of canonical block markers across all of commands/**/*.md
 #      may not rise (moving a block between files, or replacing one with a stub,
 #      is allowed). Count-based until the shared helper lands (#3493).
@@ -25,8 +27,9 @@ set -uo pipefail
 
 BASE="${1:-${BASE_REF:-origin/staging}}"
 PCT_NUM=2            # 2%
-ABS_MAX=4096         # bytes
-BUDGETED="commands/review-pr.md commands/review-pr-staging.md commands/work-on/remediate.md commands/work-on/review.md commands/work-on.md"
+ABS_MAX=4096         # bytes; also the size cap for a new spec
+# Per-file hard ceilings, one path:max_bytes per line (a spec converted to a script stub stays small).
+CEILINGS="commands/issue.md:15360"
 
 SUMMARY="${GITHUB_STEP_SUMMARY:-/dev/stdout}"
 out() { printf '%s\n' "$*" >> "$SUMMARY"; }
@@ -67,27 +70,42 @@ out "## Spec-size budget (base: \`$BASE\`)"
 out ""
 out "| File | Base | Head | Delta | Delta % | Status |"
 out "|------|-----:|-----:|------:|--------:|--------|"
-for f in $BUDGETED; do
-  [ -f "$f" ] || [ "$(base_size "$f")" != 0 ] || continue
+ceiling_of() { printf '%s\n' "$CEILINGS" | awk -F: -v f="$1" '$1 == f {print $2; exit}'; }
+HEAD_FILES=$(git ls-files 'commands/*.md' | sort -u)
+BASE_FILES=$(git ls-tree -r --name-only "$BASE" -- commands | grep -E '\.md$' | sort -u)
+ALL_FILES=$(printf '%s\n%s\n' "$HEAD_FILES" "$BASE_FILES" | sort -u)
+SPECS=0
+for f in $ALL_FILES; do
+  [ -n "$f" ] || continue
+  SPECS=$((SPECS + 1))
   b=$(base_size "$f")
   h=0; [ -f "$f" ] && h=$(wc -c < "$f" | tr -d ' ')
   g=$((h - b))
+  cap=$(ceiling_of "$f")
   status="ok"
-  if [ "$g" -gt 0 ] && { [ $((g * 100)) -gt $((b * PCT_NUM)) ] || [ "$g" -gt "$ABS_MAX" ]; }; then
-    status="OVER BUDGET"; FAILURES=$((FAILURES + 1))
+  if [ "$b" -eq 0 ]; then
+    [ "$h" -gt "$ABS_MAX" ] && status="OVER BUDGET (new spec > $ABS_MAX bytes)"
+  elif [ "$g" -gt 0 ] && { [ $((g * 100)) -gt $((b * PCT_NUM)) ] || [ "$g" -gt "$ABS_MAX" ]; }; then
+    status="OVER BUDGET"
+  fi
+  if [ -n "$cap" ] && [ "$h" -gt "$cap" ]; then
+    status="OVER CEILING ($cap bytes)"
   fi
+  # Only changed or failing specs get a row; the table would otherwise list every spec.
+  [ "$g" -ne 0 ] || [ "$status" != "ok" ] || continue
+  [ "$status" = "ok" ] || FAILURES=$((FAILURES + 1))
   if [ "$b" -gt 0 ]; then
     p=$(awk -v g="$g" -v b="$b" 'BEGIN{printf "%+.2f%%", g*100/b}')
   else p="n/a"; fi
   out "| \`$f\` | $b | $h | $g | $p | $status |"
 done
+out ""
+out "$SPECS spec(s) budgeted; unchanged specs within budget are not listed."
 
 # Net marker total across every commands/**/*.md: head (working tree, incl. new
 # files) vs base (incl. files deleted at head). Fail only when the total rises.
 HEAD_TOTAL=0; BASE_TOTAL=0; MARKER_ROWS=""
-HEAD_FILES=$(git ls-files 'commands/*.md' | sort -u)
-BASE_FILES=$(git ls-tree -r --name-only "$BASE" -- commands | grep -E '\.md$' | sort -u)
-for f in $(printf '%s\n%s\n' "$HEAD_FILES" "$BASE_FILES" | sort -u); do
+for f in $ALL_FILES; do
   [ -n "$f" ] || continue
   hc=0; [ -f "$f" ] && hc=$(grep -cE "$MARKERS" "$f" 2>/dev/null || true); hc=${hc:-0}
   bc=$(git show "$BASE:$f" 2>/dev/null | grep -cE "$MARKERS" 2>/dev/null || true); bc=${bc:-0}

package/scripts/check-spec-size.test.sh

@@ -45,8 +45,30 @@ run "over 4 KB fails" 1
 reset; gen 5 >> commands/review-pr.md     # small growth under both limits
 run "small growth passes" 0
 
-reset; gen 5000 >> commands/other.md      # not a budgeted spec
-run "non-budgeted growth passes" 0
+# Every spec is budgeted (#4164): top-level and nested specs outside the old review list
+reset; gen 5000 >> commands/other.md
+run "formerly unbudgeted spec growth fails" 1; has "other spec flagged" "| \`commands/other.md\`"
+reset; gen 1000 > commands/work-on/nested.md; git add -A; git commit -qm nested; git push -q origin HEAD:staging 2>/dev/null; git fetch -q origin staging
+gen 100 >> commands/work-on/nested.md
+run "nested spec over 2% fails" 1
+git reset -q --hard HEAD~1; git push -q -f origin HEAD:staging 2>/dev/null; git fetch -q origin staging; reset
+reset; gen 2 >> commands/other.md
+run "unbudgeted-before small growth passes" 0
+
+# New specs: up to 4096 bytes
+reset; gen 100 > commands/brand-new.md; git add -A    # ~2.8 KB
+run "new spec under 4 KB passes" 0
+reset; gen 200 > commands/brand-new.md; git add -A    # ~5.6 KB
+run "new spec over 4 KB fails" 1; has "new spec flagged" "new spec >"
+
+# Per-file ceiling: commands/issue.md may not exceed 15360 bytes whatever the growth
+reset; head -c 15300 /dev/zero | tr '\0' 'x' > commands/issue.md; git add -A; git commit -qm issue; git push -q origin HEAD:staging 2>/dev/null; git fetch -q origin staging
+printf '%050d' 0 >> commands/issue.md                 # 15350 bytes: +0.3%, under the cap
+run "ceiling: under the cap passes" 0
+printf '%050d' 0 >> commands/issue.md                 # 15400 bytes: +0.65% (within 2%/4 KB) but over the cap
+run "ceiling: over the cap fails" 1; has "ceiling flagged" "OVER CEILING (15360 bytes)"
+run "ceiling: exempt label waives" 0 PR_LABELS="spec-size-exempt"
+git reset -q --hard HEAD~1; git push -q -f origin HEAD:staging 2>/dev/null; git fetch -q origin staging; reset
 
 reset; gen 100 > commands/review-pr.md    # shrink
 run "shrink passes" 0
@@ -89,9 +111,10 @@ run "copy without removal still fails" 1
 # Shared-helper stubs (forge#3778): the sourced-helper stub shape carries none of the markers, so converting an inlined block to a stub
 # is a net reduction, while re-pasting the full block still fails.
 STUB_LOC='type forge_resolve >/dev/null 2>&1 || for _r in "${FORGEDOCK_HOME:-}"; do . "$_r/scripts/lib/forge-resolve.sh"; done'
-reset; printf '%s\n' "$STUB_LOC" '. "$(forge_resolve lib/fence-bootstrap.sh)" || exit 1   # FENCE_BOOTSTRAP' 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/other.md
+# (appended to the large work-on.md so the byte budget stays out of the marker cases)
+reset; printf '%s\n' "$STUB_LOC" '. "$(forge_resolve lib/fence-bootstrap.sh)" || exit 1   # FENCE_BOOTSTRAP' 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/work-on.md
 run "one-tag-per-stub design passes" 0
-reset; : > commands/donor.md; printf '%s\n' "$STUB_LOC" 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/other.md
+reset; : > commands/donor.md; printf '%s\n' "$STUB_LOC" 'HELPER_SCRIPT=$(forge_resolve x.sh)' >> commands/work-on.md
 run "block converted to a stub passes" 0
 reset; printf '%s\n' "$STUB_LOC" 'HELPER_SCRIPT=""' >> commands/other.md
 run "stub plus a re-pasted resolver block fails" 1

package/scripts/ci-local/lib.mjs

@@ -327,7 +327,7 @@ export function shellQuote(s) {
 // An allowlist, not a blacklist: remote CI starts from a clean environment, so ambient operator state (agent
 // credentials, install-root overrides, git hook variables such as GIT_DIR/GIT_INDEX_FILE, FORGE_*/CLAUDE_* settings)
 // must not reach the jobs. Toolchain variables are passed through; credential-looking names are always dropped.
-const ENV_EXACT = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LANGUAGE', 'TERM', 'TMPDIR', 'TMP', 'TEMP', 'TZ', 'COLORTERM', 'NO_COLOR', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy', 'DOCKER_HOST', 'JAVA_HOME', 'GOPATH', 'GOROOT', 'GOFLAGS', 'GOCACHE', 'GOMODCACHE', 'GOPROXY', 'GOTOOLCHAIN', 'VIRTUAL_ENV', 'PYTHONPATH', 'PYTHONDONTWRITEBYTECODE', 'RUSTFLAGS', 'RUSTUP_HOME', 'SDKMAN_DIR', 'PNPM_HOME', 'BUN_INSTALL', 'NVM_DIR', 'NVM_BIN', 'NVM_INC', 'RBENV_ROOT', 'PYENV_ROOT', 'ASDF_DIR', 'ASDF_DATA_DIR', 'MISE_DATA_DIR', 'HOMEBREW_PREFIX', 'ComSpec', 'SystemRoot', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMFILES', 'MSYSTEM']);
+const ENV_EXACT = new Set(['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LANGUAGE', 'TERM', 'TMPDIR', 'TMP', 'TEMP', 'TZ', 'COLORTERM', 'NO_COLOR', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy', 'DOCKER_HOST', 'JAVA_HOME', 'GOPATH', 'GOROOT', 'GOFLAGS', 'GOCACHE', 'GOMODCACHE', 'GOPROXY', 'GOTOOLCHAIN', 'VIRTUAL_ENV', 'PYTHONPATH', 'PYTHONDONTWRITEBYTECODE', 'RUSTFLAGS', 'RUSTUP_HOME', 'SDKMAN_DIR', 'PNPM_HOME', 'BUN_INSTALL', 'NVM_DIR', 'NVM_BIN', 'NVM_INC', 'RBENV_ROOT', 'PYENV_ROOT', 'ASDF_DIR', 'ASDF_DATA_DIR', 'MISE_DATA_DIR', 'HOMEBREW_PREFIX', 'ComSpec', 'SystemRoot', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMFILES', 'MSYSTEM', 'FORGE_HOST_PARALLELISM']);
 const ENV_PREFIX = ['LC_', 'XDG_', 'CARGO_', 'MAVEN_', 'M2_', 'GRADLE_', 'DOTNET_', 'npm_config_', 'NPM_CONFIG_', 'YARN_', 'UV_', 'POETRY_', 'PIP_CACHE', 'FORGE_CI_LOCAL_'];
 // Substring tokens are unambiguous; short ones (PASS, PAT, KEY, IDENT, CRED, SESSION, COOKIE) match only as whole
 // name segments (or a trailing _KEY) so benign names such as FORGE_CI_LOCAL_PASSTHROUGH or PATH are kept.
@@ -347,6 +347,13 @@ export function scrubbedEnv(extra = {}) {
   return Object.assign(env, extra);
 }
 
+// Host-derived worker cap a ForgeDock lane exports (#4182): never run more jobs/slots than FORGE_HOST_PARALLELISM.
+export function capParallel(n, env = process.env) {
+  const s = String(env?.FORGE_HOST_PARALLELISM ?? '').trim();
+  const p = /^\d+$/.test(s) ? Number(s) : 0;
+  return p > 0 ? Math.min(n, p) : n;
+}
+
 export function homeForgeDir() {
   return process.env.FORGE_CI_LOCAL_HOME || path.join(process.env.HOME || os.homedir(), '.forge');
 }

package/scripts/ci-local/parallelism.test.mjs

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { scrubbedEnv, capParallel } from "./lib.mjs";
+
+describe("ci-local host parallelism (#4182)", () => {
+  it("scrubbedEnv passes FORGE_HOST_PARALLELISM through and still drops secrets", () => {
+    const keep = { FORGE_HOST_PARALLELISM: process.env.FORGE_HOST_PARALLELISM, FD_TEST_API_TOKEN: process.env.FD_TEST_API_TOKEN, FORGE_OTHER_SETTING: process.env.FORGE_OTHER_SETTING };
+    process.env.FORGE_HOST_PARALLELISM = "2"; process.env.FD_TEST_API_TOKEN = "s3cret"; process.env.FORGE_OTHER_SETTING = "x";
+    try {
+      const env = scrubbedEnv({});
+      assert.equal(env.FORGE_HOST_PARALLELISM, "2");
+      assert.equal(env.FD_TEST_API_TOKEN, undefined);
+      assert.equal(env.FORGE_OTHER_SETTING, undefined, "other FORGE_* settings stay out");
+    } finally {
+      for (const [k, v] of Object.entries(keep)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+    }
+  });
+
+  it("capParallel caps slots/job parallelism at a positive FORGE_HOST_PARALLELISM, else leaves them alone", () => {
+    assert.equal(capParallel(4, { FORGE_HOST_PARALLELISM: "2" }), 2);
+    assert.equal(capParallel(1, { FORGE_HOST_PARALLELISM: "2" }), 1);
+    assert.equal(capParallel(4, {}), 4);
+    for (const bad of ["0", "abc", "-1", "", " "]) assert.equal(capParallel(4, { FORGE_HOST_PARALLELISM: bad }), 4, JSON.stringify(bad));
+  });
+});

package/scripts/ci-local/run.mjs

@@ -11,7 +11,7 @@ import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
-import { run as runSync, commandExists, scrubbedEnv, homeForgeDir, sha256, fileHash, toolVersion, shellSplit } from './lib.mjs';
+import { run as runSync, commandExists, scrubbedEnv, capParallel, homeForgeDir, sha256, fileHash, toolVersion, shellSplit } from './lib.mjs';
 import { shellArgv } from './adapters/common.mjs';
 import { checkPortability } from './adapters/portability.mjs';
 
@@ -25,7 +25,7 @@ for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => { clean
 // ---- machine-wide slot semaphore ----
 function slotCount() {
   const n = Number(process.env.FORGE_CI_LOCAL_SLOTS);
-  return n > 0 ? n : Math.max(2, Math.min(8, Math.floor(os.cpus().length / 2)));
+  return capParallel(n > 0 ? n : Math.max(2, Math.min(8, Math.floor(os.cpus().length / 2))));
 }
 function alive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } }
 
@@ -372,7 +372,7 @@ export async function runPlan(plan, o = {}) {
   // (DEGRADED) and a re-run resumes from the result cache.
   const maxInvS = Number(process.env.FORGE_CI_LOCAL_MAX_INVOCATION_SECONDS) || 540;
   const budgetS = Math.min(requestedS, maxInvS); const capped = requestedS > maxInvS;
-  const maxParallel = o.maxParallel || plan.config.max_parallel || Number(process.env.FORGE_CI_LOCAL_MAX_PARALLEL) || 4;
+  const maxParallel = capParallel(o.maxParallel || plan.config.max_parallel || Number(process.env.FORGE_CI_LOCAL_MAX_PARALLEL) || 4);
   const tmpRoot = fs.mkdtempSync(path.join(process.env.TMPDIR || os.tmpdir(), 'forge-ci-local.'));
   cleanups.add(() => { try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ } });
   const ctx = {

package/scripts/ci-local/scoping.mjs

@@ -342,6 +342,7 @@ export function scopeCommand(cmd, cwdRel, sctx, depth = 0) {
 
   let r = null;
   if (LINTERS[tool] && !(LINTERS[tool].sub && !LINTERS[tool].sub.has(rest[1]))) r = scopeLint(tool, rest, cmd, cwdRel, sctx, join);
+  else if (tool === 'tsc') r = scopeTsc(rest, cmd, cwdRel, sctx, join);
   else if (tool === 'jest') r = scopeJest(rest, cmd, cwdRel, sctx, join);
   else if (tool === 'vitest') r = scopeVitest(rest, cmd, cwdRel, sctx, join);
   else if (tool === 'pytest' || tool === 'py.test' || (/^python[0-9.]*$/.test(tool) && rest[1] === '-m' && rest[2] === 'pytest')) r = scopeRunner('pytest', tool === 'pytest' || tool === 'py.test' ? rest.slice(1) : rest.slice(3), tool === 'pytest' || tool === 'py.test' ? [rest[0]] : rest.slice(0, 3), cmd, cwdRel, sctx, join);
@@ -507,6 +508,87 @@ function scopeMaven(rest, cmd, cwdRel, sctx, join) {
   return scoped(join([...rest, '-pl', [...mods].sort().join(','), '-amd']), mods.size, null, 'maven-affected');
 }
 
+// ---- TypeScript compiler: the owning tsconfig project(s) of the changed files and of the files that reference them ----
+const TS_EXT = set('ts tsx mts cts js jsx mjs cjs');
+const TSC_VALUE = set('-p --project -t --target -m --module --outDir --outFile --rootDir --lib --jsx --tsBuildInfoFile --declarationDir --moduleResolution --baseUrl --types --typeRoots --locale --generateTrace --maxNodeModuleJsDepth --moduleDetection --verbatimModuleSyntax');
+
+// tsconfig.json is JSON with comments and trailing commas; null when unreadable.
+function readTsconfig(sctx, dir) {
+  sctx.cache.tsconfig = sctx.cache.tsconfig || new Map();
+  if (sctx.cache.tsconfig.has(dir)) return sctx.cache.tsconfig.get(dir);
+  let cfg = null;
+  try {
+    const raw = fs.readFileSync(path.join(sctx.repo, dir, 'tsconfig.json'), 'utf8');
+    const noComments = raw.replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (m, q) => q || '');
+    cfg = JSON.parse(noComments.replace(/,(\s*[}\]])/g, '$1'));
+  } catch { cfg = null; }
+  sctx.cache.tsconfig.set(dir, cfg);
+  return cfg;
+}
+
+// The directory of the nearest tsconfig.json above `file` ('.' for the repo root), or '' when none owns it.
+export function tsProjectOf(sctx, file) {
+  for (let d = px.dirname(file); ; d = px.dirname(d)) {
+    if (sctx.present.has(d === '.' ? 'tsconfig.json' : `${d}/tsconfig.json`)) return d;
+    if (d === '.' || d === '/') return '';
+  }
+}
+
+// A project `tsc -b` can build: composite itself, or listed in another tsconfig's `references`.
+function tsBuildable(sctx, dir) {
+  const cfg = readTsconfig(sctx, dir);
+  if (cfg && cfg.compilerOptions && cfg.compilerOptions.composite === true) return true;
+  if (!sctx.cache.tsRefs) {
+    sctx.cache.tsRefs = new Set();
+    for (const f of sctx.tracked) {
+      if (px.basename(f) !== 'tsconfig.json' || !sctx.present.has(f)) continue;
+      const from = px.dirname(f); const c = readTsconfig(sctx, from);
+      for (const r of (c && Array.isArray(c.references) ? c.references : [])) {
+        if (!r || typeof r.path !== 'string') continue;
+        const to = px.normalize(px.join(from, r.path));
+        sctx.cache.tsRefs.add(to.endsWith('.json') ? px.dirname(to) : to);
+      }
+    }
+  }
+  return sctx.cache.tsRefs.has(dir);
+}
+
+function scopeTsc(rest, cmd, cwdRel, sctx, join) {
+  const flags = []; let project = ''; let build = false; const buildTargets = [];
+  for (let i = 1; i < rest.length; i++) {
+    const t = rest[i];
+    if (t === '-p' || t === '--project') { if (i + 1 >= rest.length) return full(cmd, '', { selector: 'unscoped:tsc-args' }); project = rest[++i]; continue; }
+    if (t.startsWith('--project=')) { project = t.slice(10); continue; }
+    if (t === '-b' || t === '--build') { build = true; continue; }
+    if (t === '-w' || t === '--watch') return full(cmd, '', { selector: 'unscoped:tsc-watch' });
+    if (t.startsWith('-')) { flags.push(t); if (TSC_VALUE.has(t) && i + 1 < rest.length) flags.push(rest[++i]); continue; }
+    if (!build) return full(cmd, '', { selector: 'unscoped:tsc-explicit-files' });
+    buildTargets.push(t);
+  }
+  if (/[$`*?]/.test(project) || buildTargets.some((t) => /[$`*?]/.test(t))) return full(cmd, '', { selector: 'unscoped:complex-target' });
+  // The project this command checks: -p X, the single -b target, else the tsconfig in its cwd.
+  const targetOf = (t) => { const r = rel(cwdRel, t); return r.endsWith('.json') ? px.dirname(r) : r; };
+  if (buildTargets.length > 1) return full(cmd, '', { selector: 'unscoped:explicit-targets' });
+  const target = project ? targetOf(project) : buildTargets.length ? targetOf(buildTargets[0]) : rel(cwdRel, '.');
+  if (sctx.widen) return full(cmd, sctx.widen, { selector: 'tsc-project' });
+  const un = unmappedFile(sctx.changed, TS_EXT);
+  if (un) return full(cmd, `unknown-language: ${un}`, { selector: 'tsc-project' });
+  const r = reach(sctx);
+  if (r.widen) return full(cmd, r.widen, { selector: 'tsc-project' });
+  const tsFiles = [...r.files].filter((f) => TS_EXT.has(extOf(f)));
+  if (!tsFiles.length) return skipNo(0, null, 'tsc-project', 'no changed TS/JS file');
+  const owners = dedupe(tsFiles.map((f) => tsProjectOf(sctx, f)).filter(Boolean))
+    .filter((d) => target === '.' || d === target || d.startsWith(target + '/')).sort();
+  if (!owners.length) return skipNo(0, null, 'tsc-project', `no changed TS/JS file in ${target}`);
+  // A command already aimed at one non-root project is that project's check: keep it as is.
+  if (target !== '.') return scoped(cmd, owners.length, null, 'tsc-project', { projects: owners });
+  if (owners.includes('.')) return full(cmd, 'root-project', { selector: 'tsc-project', projects: owners });
+  if (owners.length === 1) return scoped(join([rest[0], build ? '-b' : '-p', fromCwd(cwdRel, owners[0]), ...flags]), 1, null, 'tsc-project', { projects: owners });
+  if (!owners.every((d) => tsBuildable(sctx, d))) return full(cmd, 'multi-project', { selector: 'tsc-project', projects: owners });
+  // Build mode rejects --noEmit; composite projects emit their declarations as the repo's own build does.
+  return scoped(join([rest[0], '-b', ...owners.map((d) => fromCwd(cwdRel, d)), ...flags.filter((f) => f !== '--noEmit')]), owners.length, null, 'tsc-project', { projects: owners });
+}
+
 function scopeMono(tool, rest, cmd, sctx, join) {
   if (sctx.widen) return full(cmd, sctx.widen, { selector: `${tool}-affected` });
   const base = sctx.from || sctx.baseRef;

package/scripts/ci-local.test.sh

@@ -432,7 +432,7 @@ SHIM
 chmod +x "$T/bin/docker"
 export FAKE_DOCKER_LOG="$T/docker.log"
 : > "$FAKE_DOCKER_LOG"
-OUT=$(PATH="$T/bin:$PATH" bash "$S" run --repo "$r" --base main --base-branch main --head-branch feat 2>&1); RC=$?
+OUT=$(env -u FORGE_DOCKER_LABELS PATH="$T/bin:$PATH" bash "$S" run --repo "$r" --base main --base-branch main --head-branch feat 2>&1); RC=$?
 eq "a service job runs when docker is available" 0 "$RC"
 LOG=$(cat "$FAKE_DOCKER_LOG")
 has "container is started with the same image" "$LOG" "postgres:16"

package/scripts/fixtures/symbol-index/other/sample.rb

@@ -0,0 +1,3 @@
+def greet(name)
+  "hi #{name}"
+end

package/scripts/fixtures/symbol-index/py/pkg/__init__.py

@@ -0,0 +1 @@
+from .c import value

package/scripts/fixtures/symbol-index/py/pkg/a.py

@@ -0,0 +1,5 @@
+from pkg import b
+
+
+def run():
+    return b.step()

package/scripts/fixtures/symbol-index/py/pkg/b.py

@@ -0,0 +1,14 @@
+from typing import TYPE_CHECKING
+
+from . import c
+
+if TYPE_CHECKING:
+    from . import a
+
+
+def step():
+    from .a import run  # function-local: not a module-level edge
+    return c.value + (0 if run else 1)
+
+
+from .a import run as _run_alias  # noqa: E402  module-level a <-> b cycle

package/scripts/fixtures/symbol-index/py/pkg/c.py

@@ -0,0 +1 @@
+value = 1

package/scripts/fixtures/symbol-index/py/sample.py

@@ -0,0 +1,41 @@
+"""Fixture module for symbol-index.test.sh. SECRET_DOCSTRING_MARKER"""
+import os
+from collections import OrderedDict as OD
+
+__all__ = ["Greeter", "greet", "fetch", "LIMIT"]
+
+LIMIT = 10
+_cache = OD()
+
+
+def _normalise(name):
+    return name.strip().lower()
+
+
+def greet(name):
+    return "hi " + _normalise(name)
+
+
+async def fetch(key):
+    return _cache.get(key, LIMIT)
+
+
+def helper():
+    return os.getcwd()
+
+
+class Greeter:
+    """SECRET_CLASS_DOC_MARKER"""
+
+    def __init__(self, name):
+        self.name = name
+
+    @property
+    def text(self):
+        return greet(self.name)
+
+    def _shout(self):
+        return self.text.upper()
+
+    def shout(self):
+        return self._shout()

package/scripts/fixtures/symbol-index/ts/sample.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+
+export const LIMIT = 10;
+
+export function load(path: string): string {
+  return readFileSync(path, "utf8").slice(0, LIMIT);
+}
+
+export class Loader {
+  read(path: string): string {
+    return load(path);
+  }
+}

package/scripts/fixtures/symbol-move/gen_big.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# gen_big.py: deterministic fixture for scripts/symbol-move.test.sh (forge#4210). stdlib only, no randomness.
+# Usage: python3 gen_big.py <out_root>
+# Writes <out_root>/pkg/__init__.py, pkg/big.py (~3k lines) and tests/__init__.py, tests/test_big.py.
+# big.py groups (the test's plan): consts (LIMIT_*, _SEPARATOR), helpers (_scale_*, compute_*, join_parts),
+# aio (fetch_*), models (Item_*); VERSION, describe() and DEFAULT_TOTAL stay behind and use moved names.
+
+import os
+import sys
+
+N_FUNCS = 90
+N_ASYNC = 30
+N_CLASSES = 30
+
+
+def big():
+    out = ['"""Fixture module for the symbol-move codemod test."""', "",
+           "from __future__ import annotations", "",
+           "import functools", "import os", "", "", "# ---- constants ----", ""]
+    for i in range(N_FUNCS):
+        out.append("LIMIT_%02d = %d  # upper bound for compute_%02d" % (i, 10 + i, i))
+    out += ["", '_SEPARATOR = os.sep + "|"', "", ""]
+    out += ["# ---- helpers ----", ""]
+    for i in range(N_FUNCS):
+        out += [
+            "",
+            "def _scale_%02d(value: int) -> int:" % i,
+            "    # private helper: scales by the group factor",
+            "    factor = %d" % (i % 7 + 1),
+            "    if value < 0:",
+            "        return -value * factor",
+            "    return value * factor",
+            "",
+            "",
+            "def compute_%02d(value: int) -> int:" % i,
+            '    """Scale value and clamp it to LIMIT_%02d."""' % i,
+            "    scaled = _scale_%02d(value)" % i,
+            "    if scaled > LIMIT_%02d:" % i,
+            "        return LIMIT_%02d" % i,
+            "    total = 0",
+            "    for step in range(scaled):",
+            "        total += step % 3",
+            "    return scaled + total - total",
+            "",
+        ]
+    out += [
+        "",
+        "def join_parts(*parts: str) -> str:",
+        "    # joins with the module separator",
+        "    return _SEPARATOR.join(str(p) for p in parts)",
+        "",
+        "",
+        "# ---- async ----",
+        "",
+    ]
+    for i in range(N_ASYNC):
+        out += [
+            "",
+            "async def fetch_%02d(value: int) -> dict:" % i,
+            '    """Pretend to fetch: returns the computed value in a record."""',
+            "    result = compute_%02d(value)" % i,
+            '    record = {"id": %d, "value": result}' % i,
+            "    if result % 2:",
+            '        record["odd"] = True',
+            "    return record",
+            "",
+        ]
+    out += ["", "# ---- models ----", ""]
+    for i in range(N_CLASSES):
+        out += [
+            "",
+            "@functools.total_ordering",
+            "class Item_%02d:" % i,
+            '    """A comparable item backed by compute_%02d."""' % i,
+            "",
+            '    kind = "item-%02d"' % i,
+            "",
+            "    def __init__(self, raw: int) -> None:",
+            "        self.raw = raw",
+            "",
+            "    @property",
+            "    def value(self) -> int:",
+            "        return compute_%02d(self.raw)" % i,
+            "",
+            "    def label(self) -> str:",
+            '        return join_parts(self.kind, self.value, LIMIT_%02d)' % i,
+            "",
+            "    def __eq__(self, other: object) -> bool:",
+            "        if not isinstance(other, Item_%02d):" % i,
+            "            return NotImplemented",
+            "        return self.value == other.value",
+            "",
+            "    def __lt__(self, other: Item_%02d) -> bool:" % i,
+            "        return self.value < other.value",
+            "",
+            "    def __hash__(self) -> int:",
+            "        return hash((self.kind, self.value))",
+            "",
+        ]
+    out += [
+        "",
+        "# ---- kept in place ----",
+        "",
+        'VERSION = "1.0"',
+        "",
+        "",
+        "def describe() -> str:",
+        "    return join_parts(VERSION, compute_00(1), Item_01(2).label())",
+        "",
+        "",
+        "DEFAULT_TOTAL = LIMIT_03 * 2",
+    ]
+    return "\n".join(out) + "\n"
+
+
+TESTS = '''import asyncio
+import os
+import unittest
+
+from pkg.big import (
+    DEFAULT_TOTAL,
+    LIMIT_05,
+    VERSION,
+    Item_03,
+    _scale_02,
+    _SEPARATOR,
+    compute_04,
+    compute_89,
+    describe,
+    fetch_08,
+    join_parts,
+)
+import pkg.big as big
+
+
+class BigTest(unittest.TestCase):
+    def test_constant(self):
+        self.assertEqual(LIMIT_05, 15)
+
+    def test_private_helper(self):
+        self.assertEqual(_scale_02(-2), 6)
+
+    def test_compute_clamps(self):
+        self.assertEqual(compute_04(100), 14)
+
+    def test_compute_last(self):
+        self.assertEqual(compute_89(1), 6)
+
+    def test_join(self):
+        self.assertEqual(join_parts("a", 1), "a" + os.sep + "|1")
+        self.assertEqual(_SEPARATOR, os.sep + "|")
+
+    def test_async(self):
+        self.assertEqual(asyncio.run(fetch_08(1)), {"id": 8, "value": 2})
+
+    def test_item_order(self):
+        self.assertLess(Item_03(1), Item_03(2))
+        self.assertEqual(Item_03(1), Item_03(1))
+        self.assertGreaterEqual(Item_03(3), Item_03(2))
+
+    def test_item_label(self):
+        self.assertEqual(Item_03(1).label(), join_parts("item-03", 4, 13))
+
+    def test_kept_names(self):
+        self.assertEqual(VERSION, "1.0")
+        self.assertEqual(DEFAULT_TOTAL, 26)
+        self.assertTrue(describe().startswith("1.0"))
+
+    def test_module_attributes(self):
+        self.assertIs(big.os, os)
+        self.assertEqual(big.Item_29(1).value, 2)
+
+    @unittest.skip("documents a skipped case for the count check")
+    def test_skipped(self):
+        pass
+
+
+if __name__ == "__main__":
+    unittest.main()
+'''
+
+
+def main(argv):
+    if len(argv) != 1:
+        sys.stderr.write("usage: gen_big.py <out_root>\n")
+        return 2
+    root = argv[0]
+    for d in ("pkg", "tests"):
+        os.makedirs(os.path.join(root, d), exist_ok=True)
+    files = {"pkg/__init__.py": "", "pkg/big.py": big(), "tests/__init__.py": "", "tests/test_big.py": TESTS}
+    for rel, text in files.items():
+        with open(os.path.join(root, rel), "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))