Skip to content

[Phase 2] Fetch consumer references + assemble the DOWNSTREAM_IMPACT context block #751

Closed

Description

@github-actions

Story

As a pr-review maintainer,
I want a step that takes the mapped impacted consumers, fetches their referencing workflow files via GH_PAT, and assembles a size-capped DOWNSTREAM_IMPACT block to a file,
so that the triage/deep tiers can consume a ready-made, bounded downstream-impact context the same way they consume advisory-bot feedback.

Acceptance Criteria

  1. Given the impact object from Story 2, the step fetches, for each impacted consumer, the workflow file(s) that reference the impacted surface using gh + GH_PAT, and writes a human-readable DOWNSTREAM_IMPACT block to a file path exported as DOWNSTREAM_IMPACT_FILE.
  2. When no surfaces are impacted, the block is the literal (none) (no fetches performed).
  3. Degrades gracefully: a consumer repo that is private/unreadable or a missing token scope yields (none) for that entry (or an explicit unreadable note) and never fails the cascade — exit status stays 0.
  4. Fetch volume is bounded: only exact-matched consumers are fetched, capped at a configurable max repo count per PR, and the assembled block is truncated to a size cap (mirroring the 8 KB ADVISORY_BOT_FEEDBACK cap).
  5. A bats test stubs gh to cover: impacted-with-readable-consumer, impacted-with-unreadable-consumer (-> graceful), and no-impact (-> (none), zero fetches). shellcheck passes.

Tasks / Subtasks

Dev Notes

  • Mirror the ADVISORY_BOT_FEEDBACK_FILE lifecycle in scripts/review-one-pr.sh (~lines 570–575): write a capped block to a file under /tmp/cascade/, export the path for downstream tiers, rm -f stale copies first.
  • Cap discipline matches the existing advisory cap (~8 KB) so huge consumer sets cannot blow up the prompt — see the 'Cap total size' note around scripts/review-one-pr.sh:534.
  • Use GH_PAT via gh exactly as the rest of pr-review does; do not add a new secret. Read-only gh api GET calls on consumer .github/workflows/* paths; no enumeration beyond the exact-matched consumer set.
  • Graceful degradation is a hard requirement: the cascade must never fail because a consumer repo is private or the token lacks a scope — follow the rate-limit/error-handling philosophy already in review-one-pr.sh (degrade, log ::warning::, continue).
  • Stub gh in bats the way existing tests do (PATH shim / function override) — see tests/test_ci_status.bats for the pattern.

Project Structure Notes

Extends scripts/lib/downstream-impact.sh with the I/O assembler; adds a bats test. Still no prompt wiring (Story 4).

References

  • scripts/review-one-pr.sh#ADVISORY_BOT_FEEDBACK_FILE
  • scripts/review-one-pr.sh#cap-total-size
  • .github/workflows/pr-review.yml#GH_PAT
  • tests/test_ci_status.bats#gh-stub

Likely target surface

  • scripts/lib/
  • tests/

Story prepared by the BMAD Scrum Master (Bob) for epic #748. Status: ready-for-dev.

Activity

  1. don-petry commented on Jun 18, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

    Issue: #751 — [Phase 2] Fetch consumer references + assemble the DOWNSTREAM_IMPACT context block

    Scope

    Add an I/O assembler assemble_downstream_impact to scripts/lib/downstream-impact.sh that calls the pure mapper, fetches each impacted consumer's referencing workflow file(s) via gh+GH_PAT (bounded by a per-PR repo cap and an 8 KB size cap), degrades gracefully on unreadable/private repos, and writes a human-readable DOWNSTREAM_IMPACT block to DOWNSTREAM_IMPACT_FILE.

    Implementation Checklist

    • scripts/lib/downstream-impact.sh: add assemble_downstream_impact <changed_files> <manifest> [out_file] (calls compute_downstream_impact, fetches consumer workflow files, builds + caps the block, writes the file, exports DOWNSTREAM_IMPACT_FILE)
    • Honor DOWNSTREAM_IMPACT_MAX_REPOS (default 10) and DOWNSTREAM_IMPACT_MAX_BYTES (default 8000, mirrors ADVISORY_BOT_FEEDBACK cap)
    • Graceful degradation: unreadable/private/missing-scope consumer → unreadable note, never non-zero exit; no surfaces → literal (none) with zero fetches
    • .github/workflows/lint.yml: register the new bats test file in the run-bats.sh list

    Tests to Write

    • tests/test_downstream_impact_assemble.bats with a PATH-shimmed gh stub
    • impacted + readable consumer → block lists surfaces, consumers, and referencing workflow file(s)
    • impacted + unreadable consumer → graceful unreadable note, exit 0
    • no-impact change → block is literal (none), zero gh calls
    • repo cap + size cap enforced

    Test Command

    scripts/run-bats.sh tests/test_downstream_impact_assemble.bats (full suite via lint.yml), then bash .dev-lead/scripts/dev-lead-lint.sh

  2. don-petry commented on Jun 18, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    • Added assemble_downstream_impact <changed_files> <manifest> [out_file] to scripts/lib/downstream-impact.sh (calls the pure compute_downstream_impact mapper, fetches consumer workflow files, builds + caps the block, writes the file, exports DOWNSTREAM_IMPACT_FILE)
    • Honors DOWNSTREAM_IMPACT_MAX_REPOS (default 10) and DOWNSTREAM_IMPACT_MAX_BYTES (default 8000, mirrors the ADVISORY_BOT_FEEDBACK 8 KB cap)
    • Graceful degradation: unreadable/private/missing-scope consumer → unreadable note + ::warning::, never non-zero exit; no impacted surfaces → literal (none) with zero fetches
    • Uses GH_PAT via gh (preferred, falls back to ambient GH_TOKEN); no new secret
    • Added gh-stubbed bats test tests/test_downstream_impact_assemble.bats and registered it in .github/workflows/lint.yml

    Test Results

    $ bats tests/test_downstream_impact_assemble.bats
    1..6
    ok 1 impacted change with a readable consumer writes the surfaces, consumers, and referencing files
    ok 2 impacted change with an unreadable consumer degrades to 'unreadable' and exits 0
    ok 3 a no-impact change writes literal (none) and performs zero fetches
    ok 4 the per-PR repo cap bounds the number of consumers fetched
    ok 5 the assembled block is truncated to the configured size cap
    ok 6 DOWNSTREAM_IMPACT_FILE is exported and points at the written file
    
    $ scripts/run-bats.sh <downstream/manifest/consumer/ci-status/auth-scopes suites>
    1..95   (no failures)
    
    $ shellcheck -S warning scripts/lib/downstream-impact.sh
    === shellcheck (warning) OK ===
    
    $ bash .dev-lead/scripts/dev-lead-lint.sh
      [lint] shellcheck on 67 file(s)...
      [lint] validating 4 agent profile(s)...
      [lint] all checks passed
    

    Files Changed

    • scripts/lib/downstream-impact.sh: added the I/O assembler assemble_downstream_impact plus two private helpers (_downstream_gh for GH_PAT-preferring auth, _downstream_referencing_files for listing+fetching+matching a consumer's workflow files). The pure mapper is unchanged.
    • tests/test_downstream_impact_assemble.bats: new gh-stubbed bats test (6 cases) covering readable/unreadable/no-impact plus the repo cap, size cap, and path export.
    • .github/workflows/lint.yml: registered the new test file in the run-bats.sh list.

    Notes

    • Matching locates which file references a surface by substring-matching the repo-relative surface path (e.g. .github/workflows/pr-review.yml) against the consumer's uses: line — the consumer was already confirmed to pin that surface by the pure mapper, so this only resolves the filename. Best-effort context.
    • Verified the function returns 0 on every path under set -euo pipefail (the caller review-one-pr.sh runs with it), so a fetch failure can never break the cascade.
    • Per the issue, no prompt wiring is included — that is Story 4. Default output path is /tmp/cascade/downstream-impact.txt, mirroring the ADVISORY_BOT_FEEDBACK_FILE lifecycle.
    • Followed the repo constraint: did not commit, push, or open a PR — CI handles git operations.
  3. added a commit that references this issue on Jun 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions