Skip to content

[Phase 2] Pure mapping helper: changed files -> impacted shared surfaces + consumers #750

Closed

Description

@github-actions

Story

As a pr-review maintainer,
I want a pure, network-free helper that takes a PR's changed file list plus the manifest and returns the impacted shared surfaces and the exact-matched consumers,
so that the impact computation is deterministic and unit-testable in isolation from any GitHub I/O.

Acceptance Criteria

  1. A pure function (bash + jq, NO network/gh calls) accepts a newline-delimited list of changed paths and the manifest path, and emits a JSON object: {impacted_surfaces: [...], impacted_consumers: [{repo, via:[surface,...]}], ...}.
  2. Matching is exact-path: a changed reusable-workflow path matches consumers whose refs contain exactly that path; a changed scripts/lib/*.sh or prompts/* path matches via surface_sources (the reusables that list it), then to those reusables' consumers. No prefix/glob/transitive expansion beyond the single documented hop.
  3. Changed paths that are not in any shared surface produce an empty impact result (no false positives).
  4. A bats test (tests/test_downstream_impact_map.bats) drives fixtures covering: a direct reusable-workflow change, a scripts/lib change mapped via surface_sources, a prompts/ change, a no-impact change, and a change touching multiple surfaces.
  5. shellcheck passes on the new helper.

Tasks / Subtasks

Dev Notes

  • Keep this helper PURE (no gh, no env-dependent state) so it is trivially unit-testable — mirror the structure of scripts/lib/review-cycle.sh (jq-program helpers, defensive degradation to empty on malformed input).
  • Exact-path matching only (💡 Cross-Repo Impact-Aware Review Annotations for Downstream Breakage Detection #653). The two match kinds: (a) changed path is itself a reusable-workflow ref -> direct consumer match; (b) changed path is a lib/prompt listed in some reusable's surface_sources -> map to those reusables, then to their consumers. Do not implement recursive source-graph resolution.
  • Degrade defensively: malformed manifest or empty changed-file list yields an empty, well-formed impact object (never an error that breaks the cascade) — same philosophy as compute_review_cycle returning 0 on bad input.
  • Reuse the repo's fixture convention under tests/fixtures/; consume the manifest produced by Story 1 (do not redefine its shape).

Project Structure Notes

Adds scripts/lib/downstream-impact.sh + fixtures + a bats test. Pure logic only — no wiring into review-one-pr.sh yet (that is Story 4).

References

  • scripts/lib/review-cycle.sh#compute_review_cycle
  • tests/test_review_cycle.bats
  • docs/initiatives/agentic-release-strategy.md#consumers
  • .github/workflows/lint.yml#bats

Likely target surface

  • scripts/lib/
  • tests/
  • tests/fixtures/

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: #750 — [Phase 2] Pure mapping helper: changed files -> impacted shared surfaces + consumers

    Scope

    Add a pure, network-free bash+jq helper (compute_downstream_impact <changed_files> <manifest>) that maps a PR's changed-file list, over the Story-1 consumer manifest, to the impacted shared surfaces and exact-matched consumers — no gh/network, defensively degrading to an empty well-formed object on bad input.

    Implementation Checklist

    • scripts/lib/downstream-impact.sh — sourced lib exposing compute_downstream_impact, jq-program style mirroring scripts/lib/review-cycle.sh. Two match kinds: (a) changed reusable-workflow path that a consumer ref pins exactly (provider-prefix normalized) → direct surface; (b) changed scripts/lib/*.sh / prompts/* path listed in a surface_sources value → its reusable key(s) → those reusables' consumers. Single hop, no transitive/glob expansion. Degrades to {impacted_surfaces:[],impacted_consumers:[],unmatched:[]} on malformed manifest / empty input.
    • tests/fixtures/downstream-impact/manifest.json — controlled fixture manifest (providers/consumers/surface_sources) decoupled from the live committed manifest.
    • Register tests/test_downstream_impact_map.bats in .github/workflows/lint.yml bats list.

    Tests to Write (tests/test_downstream_impact_map.bats)

    • direct reusable-workflow change → impacted surface + its consumers
    • scripts/lib/*.sh change mapped via surface_sources → reusable(s) → consumers
    • prompts/* change mapped via surface_sources
    • no-impact change (path in no surface) → empty impact, listed under unmatched
    • change touching multiple surfaces → union of surfaces + consumers
    • degrade cases: empty changed list, missing/malformed manifest → empty well-formed object

    Test Command

    bats tests/test_downstream_impact_map.bats (full suite via scripts/run-bats.sh ...); lint via bash .dev-lead/scripts/dev-lead-lint.sh + shellcheck.

  2. don-petry commented on Jun 18, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    • Added the pure mapping helper scripts/lib/downstream-impact.sh exposing compute_downstream_impact <changed_files> <manifest> (bash + jq, no gh/network), styled after scripts/lib/review-cycle.sh.
    • Implemented single-hop, exact-path matching: (a) changed reusable-workflow path that a consumer ref pins exactly → direct surface; (b) changed scripts/lib/*.sh / prompts/* path listed in a reusable's surface_sources → that reusable → its consumers. Provider prefix on consumer refs is normalised (longest-match) so the helper is provider-agnostic — no transitive/glob expansion.
    • Defensive degradation: missing/unreadable/malformed manifest, empty changed-file list, or any jq failure → {"impacted_surfaces":[],"impacted_consumers":[],"unmatched":[]} (never a non-zero exit).
    • Added fixture manifest tests/fixtures/downstream-impact/manifest.json (decoupled from the live committed manifest).
    • Added tests/test_downstream_impact_map.bats (15 tests) covering all AC Optimize review: small-PR and incremental fast paths #4 cases.
    • Registered the new bats file in .github/workflows/lint.yml.

    Output shape

    {
      "impacted_surfaces":  ["<repo-relative reusable path>", ...],
      "impacted_consumers": [{"repo": "...", "via": ["<surface>", ...]}, ...],
      "unmatched":          ["<changed path with no shared surface>", ...]
    }

    Test Results

    # tests/test_downstream_impact_map.bats
    1..15
    ok 1 direct reusable-workflow change maps to the consumers that pin it
    ok 2 direct change to the other reusable maps to a different consumer set
    ok 3 scripts/lib change maps via surface_sources to its reusable and consumers
    ok 4 prompts change maps via surface_sources to its reusable and consumers
    ok 5 a change in no shared surface produces an empty impact result
    ok 6 a scripts/lib file not listed in any surface_sources is no-impact
    ok 7 a source shared by two reusables impacts both surfaces and the union of consumers
    ok 8 changed list mixing an impacting and a non-impacting path reports both correctly
    ok 9 duplicate changed paths are de-duplicated
    ok 10 empty changed-file list yields an empty, well-formed object
    ok 11 missing argument yields an empty, well-formed object
    ok 12 a non-existent manifest path degrades to an empty object
    ok 13 a malformed manifest degrades to an empty object, not an error
    ok 14 a manifest missing keys still yields a well-formed object
    ok 15 output is always single well-formed JSON object on every path
    
    # Full lint.yml bats suite (30 files): 546 tests, 0 failures
    # shellcheck --severity=warning -x scripts/lib/downstream-impact.sh: OK
    # .dev-lead/scripts/dev-lead-lint.sh: all checks passed
    

    Smoke test against the real committed manifest

    • scripts/lib/review-cycle.sh → surface .github/workflows/pr-review.yml → 5 consumers (.github-private, ContentTwin, bmad-bgreat-suite, google-app-scripts, markets). Correctly excludes TalkTerm/broodly (they pin pr-review-reusable.yml, a different name).
    • .github/workflows/dev-lead-reusable.yml → 8 consumers.
    • README.md → empty impact, listed under unmatched.

    Files Changed

    • scripts/lib/downstream-impact.sh (new): the pure helper + jq program.
    • tests/test_downstream_impact_map.bats (new): 15-case bats suite.
    • tests/fixtures/downstream-impact/manifest.json (new): controlled fixture manifest.
    • .github/workflows/lint.yml: registered the new bats file in the bats job list (per the AGENTS.md repo-specific test-list exception).

    Notes

    • Output includes an extra unmatched field (sanctioned by the ... in the AC test issue from agent #1 shape) so the consuming story can report changed paths with no known downstream surface; the AC Add @claude delegation, auto-merge, and rebase handling #3 "empty impact result" guarantee is upheld (impacted_surfaces/impacted_consumers are []).
    • Like its sibling review-cycle.sh, this is a sourced library (no set -euo pipefail, no top-level execution) so it never mutates the caller's shell options. Pure logic only — no wiring into review-one-pr.sh (that is Story 4).
  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