forgedock 1.7.1 → 1.8.0

package/scripts/extract-affected-files.sh

@@ -7,7 +7,7 @@
 #   extract-affected-files.sh <issue_number> "-R <owner/repo>"   (single pre-joined token also accepted)
 #
 # Output (stdout):
-#   Line 1:   PROVENANCE=affected-files-section | body-fallback | none | error
+#   Line 1:   PROVENANCE=contract-deliverables | affected-files-section | body-fallback | none | error
 #   Line 2+:  one extracted file path per line (zero lines when PROVENANCE=none or error)
 #
 # Exit codes:
@@ -16,12 +16,39 @@
 #       that files were found).
 #   2 — Usage error (missing issue number, malformed -R value).
 #
-# Extraction rules (forge#2436):
+# Extraction rules (forge#2436, extended forge#2848):
+#   0. Highest-confidence path — the issue's FORGE:CONTRACT comment (if one exists),
+#      scoped to ONLY its own "### Deliverables" section. A contract deliverables table
+#      states *intent to change* ("I will edit this file"), whereas an investigation's
+#      Affected Files list and especially a raw issue body routinely name files as
+#      *context* ("this interacts with X", "similar to the check in Y"). Preferring the
+#      contract is what stops a cohort of issues that merely cite the same file from
+#      being serialized against each other (forge#2848).
+#      -> PROVENANCE=contract-deliverables
+#
+#      TEMPORAL CAVEAT — do not over-claim this source: FORGE:CONTRACT is posted at
+#      *build* time (work-on/build.md Phase B2), which is AFTER /orchestrate Phase 3
+#      builds the DAG. On a cold first-pass plan no contract exists yet, so this path is
+#      inert by construction. It pays off only on the paths that re-extract later: wake /
+#      re-plan after compaction, mid-batch re-derivation (phase-4-execution.md's DONE-arm
+#      DROP handling), and IN_PROGRESS predecessors built in an earlier wave or session.
+#
+#      FALL-THROUGH RULE (load-bearing — see forge#2848 risk table): a contract that
+#      exists but whose Deliverables section yields ZERO paths MUST fall through to the
+#      INVESTIGATOR path below. A contract is an *upgrade* over the investigator source,
+#      never a replacement for it — blackholing to `none` here would fire Layer 4's
+#      conservative serialization for exactly the mid-batch issues this change exists to
+#      un-serialize, i.e. the bug being fixed, inverted. Note this is deliberately NOT
+#      the same shape as the INVESTIGATOR->body relationship in rule 2, which does NOT
+#      fall through on zero files (see rule 2's own note, forge#2382).
 #   1. Primary path — the issue's FORGE:INVESTIGATOR comment (if one exists), scoped to
 #      ONLY its own "### Affected Files" section. Capture stops at the next markdown
 #      heading of any level, so paths mentioned in "### Evidence", "### Root Cause",
 #      "### Related Issues", etc. are never collected.
 #      -> PROVENANCE=affected-files-section
+#      NOTE (forge#2382): unlike rule 0, an INVESTIGATOR comment that EXISTS but yields
+#      zero paths does NOT fall through to rule 2 — an investigation that scoped its own
+#      Affected Files section to nothing is a confirmed-empty result, not a missing one.
 #   2. Fallback path — used ONLY when no FORGE:INVESTIGATOR comment exists at all.
 #      Scoped to a deliverables-shaped heading in the raw issue body:
 #      "## Affected Files", "## Deliverables", or "### Files to change". Capture stops
@@ -126,6 +153,20 @@ fi
 # deeper sub-heading inside a deliverables section still closes capture
 # rather than leaking into unrelated prose.
 # --------------------------------------------------------------------------- #
+extract_contract_section() {
+  # forge#2848 — same sentinel shape as the two helpers below, targeting the
+  # FORGE:CONTRACT comment's "### Deliverables" table. The `/^### Deliverables/`
+  # heading and the awk sentinel are the ones already proven in-tree at
+  # commands/work-on/build.md:218 and :258; only the path-extraction step differs
+  # (this script uses grep -oE via extract_paths, never build.md's grep -oP —
+  # forge#2436 removed the PCRE dependency on purpose, see extract_paths below).
+  awk '
+    /^### Deliverables/ { p=1; next }
+    /^#/ { p=0 }
+    p { print }
+  ' <<< "$1"
+}
+
 extract_investigator_section() {
   awk '
     /^### Affected Files/ { p=1; next }
@@ -152,13 +193,49 @@ extract_paths() {
   grep -oE "$EXT_REGEX" <<< "$1" 2>/dev/null | tr -d '`' | sort -u || true
 }
 
-# --------------------------------------------------------------------------- #
-# Primary path: FORGE:INVESTIGATOR comment, scoped to its own Affected Files section
-# --------------------------------------------------------------------------- #
 PROVENANCE="none"
 FILES=""
 GH_CALL_FAILED=0
 
+# --------------------------------------------------------------------------- #
+# Highest-confidence path: FORGE:CONTRACT comment, scoped to its own Deliverables
+# section (forge#2848). Runs AHEAD of the INVESTIGATOR path because a deliverables
+# table states intent to change, while an Affected Files list may name files that
+# are merely relevant. See rule 0 in the header for the temporal caveat (a contract
+# only exists post-build, so this is inert on a cold first-pass plan).
+#
+# Uses the same `if ! VAR=$(cmd); then GH_CALL_FAILED=1; fi` idiom as the calls
+# below — never `|| true` — so a failed contract fetch stays distinguishable from
+# "no contract exists" and can still escalate to PROVENANCE=error if nothing else
+# recovers real data (forge#2504).
+# --------------------------------------------------------------------------- #
+if ! CONTRACT_BODY=$(gh api "repos/${REPO}/issues/${NUM}/comments" \
+  --jq '[.[] | select(.body | contains("FORGE:CONTRACT"))] | last | .body // ""' 2>/dev/null); then
+  GH_CALL_FAILED=1
+  echo "WARNING: gh api call failed while fetching comments for issue #$NUM (repo: $REPO) — cannot confirm whether a FORGE:CONTRACT comment exists; treating as inconclusive, not empty" >&2
+  CONTRACT_BODY=""
+fi
+
+if [[ -n "$CONTRACT_BODY" ]]; then
+  SCOPED=$(extract_contract_section "$CONTRACT_BODY")
+  FILES=$(extract_paths "$SCOPED")
+  if [[ -n "$FILES" ]]; then
+    PROVENANCE="contract-deliverables"
+  fi
+fi
+
+# --------------------------------------------------------------------------- #
+# Primary path: FORGE:INVESTIGATOR comment, scoped to its own Affected Files section
+#
+# Guarded on `-z "$FILES"` so the contract path above FALLS THROUGH when it yielded
+# zero paths (no contract, no Deliverables section, or a deliverables table naming no
+# recognized file extension). The guard wraps the whole INVESTIGATOR/body block from
+# the outside, leaving the INVESTIGATOR->body-fallback relationship inside it
+# byte-identical — that inner relationship deliberately does NOT fall through on zero
+# files (forge#2382), and this change must not alter it.
+# --------------------------------------------------------------------------- #
+if [[ -z "$FILES" ]]; then
+
 # NOTE: deliberately no `| tail -1` here — `gh api --jq`'s raw-string output
 # for a multi-line `.body` field embeds literal newlines, so isolating "the
 # last comment" by taking the last output LINE would instead truncate to
@@ -215,6 +292,9 @@ else
     fi
   fi
 fi
+fi  # end contract fall-through guard (forge#2848) — the INVESTIGATOR/body block
+    # above is intentionally left un-indented so it stays byte-identical to its
+    # pre-forge#2848 form; only the surrounding guard is new.
 
 # forge#2504: only escalate to "error" when neither path yielded real data AND
 # at least one gh call genuinely failed along the way. A failed primary call

package/scripts/extract-affected-files.test.sh

@@ -28,18 +28,38 @@ trap cleanup EXIT
 
 # --------------------------------------------------------------------------- #
 # Mock `gh` — intercepts:
-#   gh api repos/<repo>/issues/<num>/comments --jq '...'   -> cat $MOCK_GH_COMMENTS (if set+exists, else empty)
-#   gh issue view <num> -R <repo> --json body --jq '...'   -> cat $MOCK_GH_BODY (if set+exists, else empty)
+#   gh api .../comments --jq '...FORGE:CONTRACT...'      -> cat $MOCK_GH_CONTRACT (if set+exists, else empty)
+#   gh api .../comments --jq '...FORGE:INVESTIGATOR...'  -> cat $MOCK_GH_COMMENTS (if set+exists, else empty)
+#   gh issue view <num> -R <repo> --json body --jq '...'  -> cat $MOCK_GH_BODY (if set+exists, else empty)
 # Any other invocation is a test setup error.
 #
+# forge#2848: the two `gh api` call sites hit the same endpoint and differ only in
+# their --jq selector, so the mock dispatches on which FORGE marker the selector
+# names. This keeps the contract source and the investigator source independently
+# fixturable — required to assert the contract-beats-investigator ordering rule.
+#
 # forge#2504: MOCK_GH_COMMENTS_FAIL=1 / MOCK_GH_BODY_FAIL=1 force the respective
 # call site to simulate a genuine `gh` failure (non-zero exit, nothing on
 # stdout) instead of a "call succeeded, empty/no-match result" — this is the
 # distinction extract-affected-files.sh must now surface as PROVENANCE=error.
+# MOCK_GH_CONTRACT_FAIL=1 does the same for the contract fetch alone; note that
+# MOCK_GH_COMMENTS_FAIL=1 fails BOTH `gh api` call sites, which is the faithful
+# simulation of a real network/auth/rate-limit outage (a real outage does not
+# selectively spare one of two calls to the same endpoint).
 # --------------------------------------------------------------------------- #
 cat > "$TMP_BIN/gh" <<'MOCK'
 #!/usr/bin/env bash
 if [[ "$1" == "api" ]]; then
+  if [[ "$*" == *"FORGE:CONTRACT"* ]]; then
+    if [[ "${MOCK_GH_CONTRACT_FAIL:-}" == "1" || "${MOCK_GH_COMMENTS_FAIL:-}" == "1" ]]; then
+      echo "mock gh api: simulated failure (network error / rate limit)" >&2
+      exit 1
+    fi
+    if [[ -n "${MOCK_GH_CONTRACT:-}" && -f "${MOCK_GH_CONTRACT:-}" ]]; then
+      cat "$MOCK_GH_CONTRACT"
+    fi
+    exit 0
+  fi
   if [[ "${MOCK_GH_COMMENTS_FAIL:-}" == "1" ]]; then
     echo "mock gh api: simulated failure (network error / rate limit)" >&2
     exit 1
@@ -320,6 +340,138 @@ MOCK_GH_COMMENTS_FAIL=1 MOCK_GH_BODY="$BODY_SCOPED" assert_output \
   "forge#2504: primary gh api call fails but fallback succeeds with real files -> body-fallback, not error" \
   "body-fallback" "bin/engine.mjs,bin/engine/phases.mjs" 2506 -R test/repo
 
+# --------------------------------------------------------------------------- #
+# Scenario 12 (forge#2848): FORGE:CONTRACT comment present with a real
+# "### Deliverables" table -> PROVENANCE=contract-deliverables. Paths named in
+# the contract's OTHER sections ("### Proposed Approach", "### Out of Scope")
+# must be ignored — same heading-scoping guarantee the investigator path has.
+# --------------------------------------------------------------------------- #
+CONTRACT_FULL="$TMP_FIXTURES/contract_full.txt"
+cat > "$CONTRACT_FULL" <<'EOF'
+<!-- FORGE:CONTRACT -->
+## Builder Contract
+
+**Task type**: Bug Fix
+
+### Proposed Approach
+
+Mirrors the approach already taken in `bin/approach-only-context.mjs`.
+
+### Deliverables
+
+| File | Change | Why |
+|------|--------|-----|
+| `scripts/real-target.sh` | rewrite the parser | the actual defect |
+| `bin/real-target.mjs` | update the caller | keeps the pair in sync |
+
+### Out of Scope
+
+Anything under `bin/out-of-scope-file.mjs`.
+EOF
+
+unset MOCK_GH_COMMENTS MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_FULL" assert_output \
+  "forge#2848: FORGE:CONTRACT ### Deliverables -> contract-deliverables, ignores Approach/Out-of-Scope paths" \
+  "contract-deliverables" "bin/real-target.mjs,scripts/real-target.sh" 2848 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 13 (forge#2848 ORDERING rule): both a FORGE:CONTRACT and a
+# FORGE:INVESTIGATOR comment exist, and they name DIFFERENT files. The contract
+# must win — a deliverables table states intent to change, while an Affected
+# Files list may name files that are merely relevant. This is the assertion that
+# pins the provenance precedence order; without it the two sources could silently
+# swap with no test failure.
+# --------------------------------------------------------------------------- #
+INV_DIFFERENT="$TMP_FIXTURES/inv_different.txt"
+cat > "$INV_DIFFERENT" <<'EOF'
+<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+
+### Affected Files
+
+1. `scripts/investigator-guess.sh` — suspected
+2. `bin/investigator-guess.mjs` — suspected
+EOF
+
+unset MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_FULL" MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848 ordering: contract beats investigator when both exist and disagree" \
+  "contract-deliverables" "bin/real-target.mjs,scripts/real-target.sh" 2849 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 14 (forge#2848 FALL-THROUGH rule — load-bearing): a FORGE:CONTRACT
+# exists but yields ZERO paths. It must fall through to the INVESTIGATOR path,
+# NOT blackhole to PROVENANCE=none. Blackholing here would fire Layer 4's
+# conservative serialization for exactly the mid-batch issues this change exists
+# to un-serialize (the bug being fixed, inverted — see the forge#2848 risk table).
+# Two zero-yield shapes are covered: no "### Deliverables" heading at all, and a
+# Deliverables section that names no recognized file path.
+# --------------------------------------------------------------------------- #
+CONTRACT_NO_DELIV="$TMP_FIXTURES/contract_no_deliv.txt"
+cat > "$CONTRACT_NO_DELIV" <<'EOF'
+<!-- FORGE:CONTRACT -->
+## Builder Contract
+
+### Proposed Approach
+
+Prose only, mentioning `bin/should-not-be-extracted.mjs` as context.
+
+### Out of Scope
+
+Everything else.
+EOF
+
+unset MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_NO_DELIV" MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848 fall-through: contract with no ### Deliverables section -> falls through to affected-files-section" \
+  "affected-files-section" "bin/investigator-guess.mjs,scripts/investigator-guess.sh" 2850 -R test/repo
+
+CONTRACT_EMPTY_DELIV="$TMP_FIXTURES/contract_empty_deliv.txt"
+cat > "$CONTRACT_EMPTY_DELIV" <<'EOF'
+<!-- FORGE:CONTRACT -->
+## Builder Contract
+
+### Deliverables
+
+| File | Change | Why |
+|------|--------|-----|
+| (documentation-only, no code paths) | n/a | n/a |
+
+### Out of Scope
+
+Everything else.
+EOF
+
+unset MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT="$CONTRACT_EMPTY_DELIV" MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848 fall-through: contract Deliverables naming no recognized path -> falls through to affected-files-section" \
+  "affected-files-section" "bin/investigator-guess.mjs,scripts/investigator-guess.sh" 2851 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 15 (forge#2848 x forge#2504): the CONTRACT fetch specifically fails
+# while every other source is legitimately empty. Must yield PROVENANCE=error,
+# not none — the new call site doubles the gh failure surface, so its own
+# GH_CALL_FAILED wiring needs its own assertion rather than riding on the
+# investigator call's coverage.
+# --------------------------------------------------------------------------- #
+unset MOCK_GH_CONTRACT MOCK_GH_COMMENTS MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT_FAIL=1 assert_output \
+  "forge#2848: contract gh api call fails, no other usable source -> PROVENANCE=error, not none" \
+  "error" "" 2852 -R test/repo
+
+# --------------------------------------------------------------------------- #
+# Scenario 16 (forge#2848 x forge#2504): the CONTRACT fetch fails but the
+# investigator path succeeds with real files. A gh failure must never suppress
+# or overwrite data actually recovered by a subsequent successful call — same
+# invariant Scenario 11 asserts for the primary/fallback pair.
+# --------------------------------------------------------------------------- #
+unset MOCK_GH_CONTRACT MOCK_GH_BODY MOCK_GH_COMMENTS_FAIL MOCK_GH_BODY_FAIL
+MOCK_GH_CONTRACT_FAIL=1 MOCK_GH_COMMENTS="$INV_DIFFERENT" assert_output \
+  "forge#2848: contract fetch fails but investigator succeeds with real files -> affected-files-section, not error" \
+  "affected-files-section" "bin/investigator-guess.mjs,scripts/investigator-guess.sh" 2853 -R test/repo
+
+unset MOCK_GH_CONTRACT_FAIL
+
 # --------------------------------------------------------------------------- #
 # Summary
 # --------------------------------------------------------------------------- #