Skip to content

SPEC-020: PR Blast-Radius Review Action - #154

Merged
fgabelmannjr merged 48 commits into
mainfrom
020-pr-blast-radius-review-action
Jul 16, 2026
Merged

fgabelmannjr merged 48 commits into
mainfrom
020-pr-blast-radius-review-action

Conversation

@fgabelmannjr

@fgabelmannjr fgabelmannjr commented Jul 16, 2026 •

Copy link
Copy Markdown

SPEC-020: PR Blast-Radius Review Action

What changed

  • Added a reusable composite GitHub Action at actions/pr-impact/.
  • Added a packaged helper runtime with deterministic PR impact report generation.
  • Added fork-safe fallback delivery through workflow summary and artifact.
  • Added advisory dogfood workflow coverage for CodeGraph pull requests.
  • Added focused contract, cache, delivery, result-matrix, narrative, and runtime freshness tests.

Why

Reviewers need one current deterministic blast-radius report on pull requests. The action keeps ordinary impact advisory, enforces only opt-in thresholds, validates restored graph caches before use, and keeps optional narrative prose-only.

Non-goals

  • No detector rewrite.
  • No default blocking thresholds.
  • No new narrative provider system; SPEC-018 remains the owner of optional narrative behavior.
  • No pull_request_target execution of untrusted PR code.

Review order

  1. actions/pr-impact/action.yml
  2. actions/pr-impact/README.md
  3. actions/pr-impact/run.ts
  4. actions/pr-impact/dist/run.mjs
  5. __tests__/pr-impact-*.test.ts
  6. .github/workflows/pr-impact.yml
  7. SPEC-020 docs and CHANGELOG.md

Scope budget

  • Reviewability gate: warning accepted, pass=true.
  • Reviewable LOC: 455.
  • Production files: 4.
  • Total files: 11.
  • Blockers: none.

Traceability

Requirement area Implementation Verification
Deterministic report and sticky comment actions/pr-impact/run.ts, actions/pr-impact/action.yml __tests__/pr-impact-delivery.test.ts
Fork/restricted-token fallback actions/pr-impact/run.ts __tests__/pr-impact-delivery.test.ts, __tests__/pr-impact-result-matrix.test.ts
Threshold-only failures actions/pr-impact/run.ts __tests__/pr-impact-result-matrix.test.ts, __tests__/pr-impact-action-contract.test.ts
Cache validation/rebuild actions/pr-impact/run.ts, actions/pr-impact/action.yml __tests__/pr-impact-cache.test.ts
Prose-only narrative actions/pr-impact/run.ts __tests__/pr-impact-narrative.test.ts
Dogfood workflow .github/workflows/pr-impact.yml __tests__/pr-impact-action-contract.test.ts
Generated runtime actions/pr-impact/dist/run.mjs __tests__/pr-impact-runtime-freshness.test.ts

Verification

  • Focused PR-impact suite: PASS — 6 files, 28 tests.
  • npm run build: PASS.
  • npm run typecheck: PASS.
  • npm test: PARTIAL — 239 files passed; one detect-changes-cli test timed out under full-suite load.
  • npm test -- __tests__/detect-changes-cli.test.ts: PASS — 1 file, 4 tests.
  • Warm-cache deterministic sample median: 149s, below the 180s target.
  • Verify-tasks phantom check: PASS — 60/60 completed tasks verified.
  • Code review remediation: PASS — comparison-base defaulting, final delivery metadata consistency, and merge-base metadata fixed.
  • PR check remediation: PASS locally — external actions/* references are pinned to full commit SHAs.
  • PR check remediation: PASS locally — cold cache misses initialize the CodeGraph index before analysis.
  • PR check remediation: PASS locally — dogfood installs the checked-out workspace package so unreleased detector commands are available.
  • PR check remediation: PASS locally — dogfood builds the workspace package before local file:. installation.
  • PR check remediation: PASS locally — fallback restore-key caches are validated from metadata instead of treated as cold misses.
  • PR check remediation: PASS locally — helper uses the resolved installed CLI path and falls back from failed restored-cache reindex to cold initialization.
  • PR check remediation: PASS locally — omitted base-ref uses the computed merge base/base SHA for detector execution in detached PR checkouts.
  • Live PR checks: PASS — pr-impact, CodeQL, dependency review, installer coverage guard, and OS/Node test matrix passed on run 29464931728.

Known gaps

Rollback

  • Remove .github/workflows/pr-impact.yml to disable dogfood.
  • Remove or stop using the uses: ./actions/pr-impact workflow step for consumers.
  • The action is additive and does not change detector internals.

@fgabelmannjr fgabelmannjr self-assigned this Jul 16, 2026
@fgabelmannjr
fgabelmannjr marked this pull request as ready for review July 16, 2026 01:26
Copilot AI review requested due to automatic review settings July 16, 2026 01:26

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds SPEC-020’s reusable “PR Impact” composite GitHub Action to generate and deliver a deterministic CodeGraph blast-radius report on pull requests (with fork-safe degradation), along with dogfood workflow wiring, packaging/build integration for the compiled helper runtime, and a focused test suite plus spec artifacts.

Changes:

  • Introduces actions/pr-impact/ composite action + compiled helper runtime to run codegraph detect-changes and publish a deterministic report with sticky-comment + summary/artifact fallback.
  • Adds advisory self-dogfood workflow for CodeGraph PRs and integrates helper build output into npm run build + package publishing.
  • Adds comprehensive Vitest coverage for action contract, cache validation, delivery/result-matrix behavior, narrative degradation, and runtime freshness; updates roadmap/spec docs and changelog.

Reviewed changes

Copilot reviewed 40 out of 42 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
specs/020-pr-blast-radius-review-action/verify-tasks-report.md Task verification report artifact
specs/020-pr-blast-radius-review-action/uat-runbook.md Manual UAT steps/runbook
specs/020-pr-blast-radius-review-action/tasks.md Dependency-ordered implementation tasks
specs/020-pr-blast-radius-review-action/spec.md Feature spec (US/FR/SC)
specs/020-pr-blast-radius-review-action/SPEC-MOC.md Spec map-of-content marker
specs/020-pr-blast-radius-review-action/retrospective.md Implementation retrospective notes
specs/020-pr-blast-radius-review-action/research.md Design decisions & references
specs/020-pr-blast-radius-review-action/quickstart.md Local verification quickstart
specs/020-pr-blast-radius-review-action/pr-review-packet.md Review packet & evidence
specs/020-pr-blast-radius-review-action/pr-body.md Generated PR body text
specs/020-pr-blast-radius-review-action/plan.md Implementation plan & gates
specs/020-pr-blast-radius-review-action/data-model.md Action/cache/delivery data model
specs/020-pr-blast-radius-review-action/contracts/result-matrix.md Contract for conclusion mapping
specs/020-pr-blast-radius-review-action/contracts/report-contract.md Deterministic report contract
specs/020-pr-blast-radius-review-action/contracts/action-contract.md Action I/O contract documentation
specs/020-pr-blast-radius-review-action/code-review-report.md Recorded review findings/remediation
specs/020-pr-blast-radius-review-action/checklists/security.md Generated security checklist
specs/020-pr-blast-radius-review-action/checklists/requirements.md Generated requirements checklist
specs/020-pr-blast-radius-review-action/checklists/performance.md Generated performance checklist
specs/020-pr-blast-radius-review-action/checklists/error-handling.md Generated error-handling checklist
specs/020-pr-blast-radius-review-action/checklists/api-contracts.md Generated API-contracts checklist
actions/pr-impact/action.yml Composite action definition + steps
actions/pr-impact/README.md Action usage & behavior documentation
actions/pr-impact/run.ts Helper source for orchestration/reporting
actions/pr-impact/dist/run.mjs Generated compiled helper runtime
.github/workflows/pr-impact.yml Advisory dogfood workflow for PRs
tests/fixtures/pr-impact.ts Deterministic fixtures for tests
tests/pr-impact-action-contract.test.ts Action contract + workflow pinning tests
tests/pr-impact-runtime-freshness.test.ts Generated runtime freshness tests
tests/pr-impact-delivery.test.ts Comment/summary/artifact delivery tests
tests/pr-impact-result-matrix.test.ts Conclusion mapping/result-matrix tests
tests/pr-impact-cache.test.ts Cache validation/rebuild behavior tests
tests/pr-impact-narrative.test.ts Narrative suppression/degradation tests
package.json Build + package surface updates (actions + helper build)
CHANGELOG.md Unreleased feature note for PR impact action
.gitignore Unignore generated action runtime for commit
docs/ai/specs/intelligence-platform-technical-roadmap.md Roadmap status update for SPEC-020
docs/ai/specs/intelligence-platform-roadmap-MOC.md Adds SPEC-020 to roadmap MOC index
docs/ai/specs/.process/SPEC-020-workflow.md SPEC-020 workflow artifact
docs/ai/specs/.process/SPEC-020-design-concept.md SPEC-020 design concept/Q&A log
.specify/feature.json SpecKit feature directory pointer

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread actions/pr-impact/run.ts Resolved
Comment thread actions/pr-impact/README.md Resolved
@github-actions

github-actions Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

CodeGraph PR Impact

Run metadata

Summary

  • Detector status: impact
  • Detector exit code: 1
  • Final conclusion: pass
  • Threshold breached: false
  • Cache status: rebuilt
  • Delivery status: comment
  • Narrative status: disabled
  • Artifact: codegraph-pr-impact

Changed symbols

  • prImpactHelperVersion (constant) — tests/fixtures/pr-impact.ts
  • prImpactGitHubEvent (constant) — tests/fixtures/pr-impact.ts
  • prImpactForkEvent (constant) — tests/fixtures/pr-impact.ts
  • prImpactDetectorResults (constant) — tests/fixtures/pr-impact.ts
  • prImpactDeliveryResults (constant) — tests/fixtures/pr-impact.ts
  • ROOT (constant) — tests/pr-impact-action-contract.test.ts
  • ACTION_YML (constant) — tests/pr-impact-action-contract.test.ts
  • ACTION_README (constant) — tests/pr-impact-action-contract.test.ts
  • DOGFOOD_WORKFLOW (constant) — tests/pr-impact-action-contract.test.ts
  • PACKAGE_JSON (constant) — tests/pr-impact-action-contract.test.ts
  • PACK_NPM (constant) — tests/pr-impact-action-contract.test.ts
  • INPUTS (constant) — tests/pr-impact-action-contract.test.ts
  • OUTPUTS (constant) — tests/pr-impact-action-contract.test.ts
  • readAction (function) — tests/pr-impact-action-contract.test.ts
  • readPackage (function) — tests/pr-impact-action-contract.test.ts
  • outputMap (function) — tests/pr-impact-action-contract.test.ts
  • typeSurface (constant) — tests/pr-impact-action-contract.test.ts
  • outputMap (function) — tests/pr-impact-cache.test.ts
  • runWithCacheStatus (function) — tests/pr-impact-cache.test.ts
  • lockfileHash (function) — tests/pr-impact-cache.test.ts
  • healthyStatus (function) — tests/pr-impact-cache.test.ts
  • cacheMetadata (function) — tests/pr-impact-cache.test.ts
  • runWithMetadata (function) — tests/pr-impact-cache.test.ts
  • tmpDir (function) — tests/pr-impact-delivery.test.ts
  • outputMap (function) — tests/pr-impact-delivery.test.ts
  • deps (function) — tests/pr-impact-delivery.test.ts
  • depsForEvent (function) — tests/pr-impact-delivery.test.ts
  • outputMap (function) — tests/pr-impact-narrative.test.ts
  • runNarrative (function) — tests/pr-impact-narrative.test.ts
  • outputMap (function) — tests/pr-impact-result-matrix.test.ts
  • baseDeps (function) — tests/pr-impact-result-matrix.test.ts
  • runMatrixCase (function) — tests/pr-impact-result-matrix.test.ts
  • ROOT (constant) — tests/pr-impact-runtime-freshness.test.ts
  • SOURCE (constant) — tests/pr-impact-runtime-freshness.test.ts
  • RUNTIME (constant) — tests/pr-impact-runtime-freshness.test.ts
  • TSC (constant) — tests/pr-impact-runtime-freshness.test.ts
  • sha256 (function) — tests/pr-impact-runtime-freshness.test.ts
  • compileRuntime (function) — tests/pr-impact-runtime-freshness.test.ts
  • HELPER_VERSION (constant) — actions/pr-impact/run.ts
  • DEFAULT_CODEGRAPH_VERSION (constant) — actions/pr-impact/run.ts
  • ACTION_MARKER (constant) — actions/pr-impact/run.ts
  • SummaryStatus (type_alias) — actions/pr-impact/run.ts
  • DetectorExitCode (type_alias) — actions/pr-impact/run.ts
  • CacheStatus (type_alias) — actions/pr-impact/run.ts
  • DeliveryStatus (type_alias) — actions/pr-impact/run.ts
  • NarrativeStatus (type_alias) — actions/pr-impact/run.ts
  • FinalConclusion (type_alias) — actions/pr-impact/run.ts
  • PullRequestContext (interface) — actions/pr-impact/run.ts
  • ActionInputs (interface) — actions/pr-impact/run.ts
  • DetectorResult (interface) — actions/pr-impact/run.ts
  • DeliveryResult (interface) — actions/pr-impact/run.ts
  • NarrativeResult (interface) — actions/pr-impact/run.ts
  • CacheIdentity (interface) — actions/pr-impact/run.ts
  • CacheMetadata (interface) — actions/pr-impact/run.ts
  • BaseIndexPreparation (type_alias) — actions/pr-impact/run.ts
  • RunResult (interface) — actions/pr-impact/run.ts
  • RunDependencies (interface) — actions/pr-impact/run.ts
  • FetchLike (type_alias) — actions/pr-impact/run.ts
  • createRunDependencies (function) — actions/pr-impact/run.ts
  • parseActionInputs (function) — actions/pr-impact/run.ts
  • determineConclusion (function) — actions/pr-impact/run.ts
  • runAction (function) — actions/pr-impact/run.ts
  • prepareCache (function) — actions/pr-impact/run.ts
  • validateWorkspaceHead (function) — actions/pr-impact/run.ts
  • prepareBaseIndexIfNeeded (function) — actions/pr-impact/run.ts
  • prDiffHasDeletedFiles (function) — actions/pr-impact/run.ts
  • isPlainCodeGraphDirName (function) — actions/pr-impact/run.ts
  • cacheIdentity (function) — actions/pr-impact/run.ts
  • validateCacheMetadata (function) — actions/pr-impact/run.ts
  • validateWarmIndexHealth (function) — actions/pr-impact/run.ts
  • rebuildCodeGraphIndex (function) — actions/pr-impact/run.ts
  • resetCodeGraphIndex (function) — actions/pr-impact/run.ts
  • readOptionalFile (function) — actions/pr-impact/run.ts
  • fileExists (function) — actions/pr-impact/run.ts
  • restoreOptionalFile (function) — actions/pr-impact/run.ts
  • writeCacheMetadata (function) — actions/pr-impact/run.ts
  • hashFirstExistingFile (function) — actions/pr-impact/run.ts
  • writeReportFile (function) — actions/pr-impact/run.ts
  • readPullRequestContext (function) — actions/pr-impact/run.ts
  • resolveBaseRef (function) — actions/pr-impact/run.ts
  • resolveDetectorBaseRef (function) — actions/pr-impact/run.ts
  • resolveMergeBase (function) — actions/pr-impact/run.ts
  • trustedContextFor (function) — actions/pr-impact/run.ts
  • hasTrustedWriteToken (function) — actions/pr-impact/run.ts
  • readGitHubEvent (function) — actions/pr-impact/run.ts
  • runDetector (function) — actions/pr-impact/run.ts
  • detectorArgs (function) — actions/pr-impact/run.ts
  • failOnPolicy (function) — actions/pr-impact/run.ts
  • runDetectorCommand (function) — actions/pr-impact/run.ts
  • codegraphBin (function) — actions/pr-impact/run.ts
  • normalizeDetectorResult (function) — actions/pr-impact/run.ts
  • createUnavailableDetector (function) — actions/pr-impact/run.ts
  • createInitialDelivery (function) — actions/pr-impact/run.ts
  • deliverReportComment (function) — actions/pr-impact/run.ts
  • patchDeliveredComment (function) — actions/pr-impact/run.ts
  • writeSummary (function) — actions/pr-impact/run.ts
  • createInitialNarrative (function) — actions/pr-impact/run.ts
  • renderReport (function) — actions/pr-impact/run.ts
  • GitHubComment (interface) — actions/pr-impact/run.ts
  • listComments (function) — actions/pr-impact/run.ts
  • fetchJson (function) — actions/pr-impact/run.ts
  • createComment (function) — actions/pr-impact/run.ts
  • patchComment (function) — actions/pr-impact/run.ts
  • issueCommentsUrl (function) — actions/pr-impact/run.ts
  • apiBase (function) — actions/pr-impact/run.ts
  • githubHeaders (function) — actions/pr-impact/run.ts
  • compareCommentNewestFirst (function) — actions/pr-impact/run.ts
  • isActionOwnedComment (function) — actions/pr-impact/run.ts
  • isGitHubComment (function) — actions/pr-impact/run.ts
  • formatChangedSymbols (function) — actions/pr-impact/run.ts
  • formatCallers (function) — actions/pr-impact/run.ts
  • formatAffectedFlows (function) — actions/pr-impact/run.ts
  • formatItems (function) — actions/pr-impact/run.ts
  • emitOutput (function) — actions/pr-impact/run.ts
  • readInput (function) — actions/pr-impact/run.ts
  • stringAt (function) — actions/pr-impact/run.ts
  • numberAt (function) — actions/pr-impact/run.ts
  • numberOr (function) — actions/pr-impact/run.ts
  • objectValue (function) — actions/pr-impact/run.ts
  • objectField (function) — actions/pr-impact/run.ts
  • requiredStringField (function) — actions/pr-impact/run.ts
  • requiredNumberField (function) — actions/pr-impact/run.ts
  • hasOwn (function) — actions/pr-impact/run.ts
  • stringField (function) — actions/pr-impact/run.ts
  • normalizeAffectedFlows (function) — actions/pr-impact/run.ts
  • isSummaryStatus (function) — actions/pr-impact/run.ts
  • isDetectorExitCode (function) — actions/pr-impact/run.ts
  • isCacheStatus (function) — actions/pr-impact/run.ts
  • parseOptionalInteger (function) — actions/pr-impact/run.ts
  • parseInteger (function) — actions/pr-impact/run.ts
  • parseBoolean (function) — actions/pr-impact/run.ts
  • escapeOutputFileValue (function) — actions/pr-impact/run.ts
  • escapeCommandValue (function) — actions/pr-impact/run.ts
  • isDirectRun (function) — actions/pr-impact/run.ts
  • acquireGitDiff (function) — src/analysis/detect-changes/git-diff.ts
  • argsForMode (function) — src/analysis/detect-changes/git-diff.ts
  • enrichImpact (function) — src/analysis/detect-changes/impact.ts
  • collectCallers (function) — src/analysis/detect-changes/impact.ts
  • enrichAffectedFlows (function) — src/analysis/detect-changes/impact.ts
  • collectAffectedFlowMatches (function) — src/analysis/detect-changes/impact.ts
  • DiffRequest (interface) — src/analysis/detect-changes/index.ts
  • DetectChangesOptions (interface) — src/analysis/detect-changes/index.ts
  • detectChanges (function) — src/analysis/detect-changes/index.ts
  • mapDiffToSymbols (function) — src/analysis/detect-changes/mapper.ts
  • classifyUnmapped (function) — src/analysis/detect-changes/mapper.ts
  • mappingPath (function) — src/analysis/detect-changes/mapper.ts
  • intersectingSymbolsForHunk (function) — src/analysis/detect-changes/mapper.ts
  • symbolsIntersecting (function) — src/analysis/detect-changes/mapper.ts
  • hunkRange (function) — src/analysis/detect-changes/mapper.ts
  • normalizeDetectChangesRequest (function) — src/analysis/detect-changes/report.ts
  • main (function) — src/bin/codegraph.ts
  • main::validateCodeGraphDirOption (function) — src/bin/codegraph.ts

Impacted callers

  • readPackage — tests/pr-impact-action-contract.test.ts
  • deliverReportComment — actions/pr-impact/run.ts
  • listComments — actions/pr-impact/run.ts
  • createComment — actions/pr-impact/run.ts
  • patchComment — actions/pr-impact/run.ts
  • deliverReportComment — actions/pr-impact/run.ts
  • deliverReportComment — actions/pr-impact/run.ts
  • patchDeliveredComment — actions/pr-impact/run.ts
  • listComments — actions/pr-impact/run.ts
  • createComment — actions/pr-impact/run.ts
  • patchComment — actions/pr-impact/run.ts
  • issueCommentsUrl — actions/pr-impact/run.ts
  • listComments — actions/pr-impact/run.ts
  • createComment — actions/pr-impact/run.ts
  • patchComment — actions/pr-impact/run.ts
  • deliverReportComment — actions/pr-impact/run.ts
  • deliverReportComment — actions/pr-impact/run.ts
  • listComments — actions/pr-impact/run.ts
  • createComment — actions/pr-impact/run.ts
  • renderReport — actions/pr-impact/run.ts

Affected flows

  • State: available
  • createRunDependencies
  • detect-changes

Risks

  • {"code":"high-callers","severity":"warning","targetId":"symbol:57","message":"Changed symbol has 37 direct upstream callers, above display cap 20."}
  • {"code":"hub","severity":"warning","targetId":"symbol:57","message":"Changed symbol has 37 direct upstream callers, above hub threshold 20.","policy":"hub"}
  • {"code":"truncated-callers","severity":"info","targetId":"report","message":"Caller rows were truncated to maxCallers=20."}

Warnings

  • {"code":"generated","message":"Generated or dependency output is intentionally not mapped to symbols."}
  • {"code":"unsupported","message":"File type is not supported by the current extractor set."}

Limits

  • Caller depth: 1
  • Max callers: 20

Fallback delivery note

  • Report path: pr-impact-report.md
  • Duplicate comments retired: 0
  • Duplicate cleanup failures: 0
  • Comment delivery is attempted only when a trusted pull-request token is available.

@fgabelmannjr fgabelmannjr added the enhancement New feature or request label Jul 16, 2026
@fgabelmannjr
fgabelmannjr merged commit 316ca16 into main Jul 16, 2026
11 checks passed
@fgabelmannjr
fgabelmannjr deleted the 020-pr-blast-radius-review-action branch July 16, 2026 15:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants