Change label from Ready to Review to Reviewed on Code review completion

[Satendra-SR]

Refined Requirement: Change Review Status Label After Code Review Completion

1. Purpose

Ensure pull requests reflect the current review state by replacing the "Ready for review" label with a "Reviewed" label once a code review is completed.

2. Scope

In Scope

• Update pull request labels after a code review is completed.
• Remove the existing "Ready for review" label when review outcome is submitted.
• Add a reviewed-status label when review outcome is submitted.
• Treat both review outcomes as completion: "Approved" and "Request changes".

Out of Scope

• Changing label behavior before review completion.
• Changing reviewer assignment flow.
• Modifying other labels not related to review completion status.

3. Users / Roles Affected

• Pull request authors
• Code reviewers
• Team members tracking pull request status via labels

4. Functional Requirements

1. If a pull request has the "Ready for review" label, and a reviewer submits an "Approved" review, the "Ready for review" label must be removed.
2. If a pull request has the "Ready for review" label, and a reviewer submits a "Request changes" review, the "Ready for review" label must be removed.
3. After either of the above review submissions, a reviewed-status label must be added to the pull request.
4. The reviewed-status label to add must match one agreed label name from the available options in this issue.

5. Business Rules / Constraints

• The trigger event is review completion, specifically when outcome is "Approved" or "Request changes".
• Label naming must use an existing label from the repository label set.
• Existing behavior that adds "Ready for review" when PR is assigned for review remains unchanged.

6. Acceptance Criteria

• Given a pull request labeled "Ready for review", when a reviewer submits "Approved", then "Ready for review" is removed.
• Given a pull request labeled "Ready for review", when a reviewer submits "Request changes", then "Ready for review" is removed.
• Given either review outcome above, when review is submitted, then one reviewed-status label is added.
• Given this automation runs, when checking labels afterward, then both "Ready for review" and the reviewed-status label are not present together.

7. Open Questions

• Which exact reviewed-status label should be used consistently: "status : reviewed" or "Reviewed"?
  • Answer - Primarily "status : reviewed", but should support "Reviewed"

[Satendra-SR]

Implementation Plan (v1): Review Completion Label Transition

Overview

This plan implements issue #3 by updating PR labels when code review is completed:

• remove any "ready for review" label variant
• add reviewed label (primary: status : reviewed, also support Reviewed as acceptable existing variant)
• trigger only on completed review outcomes (approved, changes_requested)

Source requirement: #3

Objective

Ensure pull request labels accurately reflect post-review state by transitioning from ready-for-review to reviewed status at review completion.

Scope

In scope

• Add support for processing pull_request_review event with submitted action.
• Add rule/config capability for removing PR labels and adding reviewed label after review completion.
• Ensure behavior runs only for review outcomes: approved, changes_requested.
• Preserve existing behavior for current pull_request automation paths.
• Add/adjust tests and documentation.

Out of scope

• Changing issue assignment behavior.
• Changing Projects V2 status transitions.
• Adding label creation logic when labels do not exist in repo.
• Supporting additional review states (e.g., commented, dismissed) unless requested later.

Technical Analysis

Current automation flow supports only pull_request events (src/index.ts) and currently only adds labels via addLabelIfMissing (src/github/pr.ts). Rule composition in src/rules/router.ts/src/rules/types.ts supports additive actions but does not currently support label removal or review-state-based guards.

To implement issue #3 cleanly and consistently with existing config-driven behavior:

• extend config/rules to express label removal
• extend PR GitHub wrapper to remove labels safely and idempotently
• allow pull_request_review/submitted path and gate execution by review state
• keep existing pull_request behavior untouched

Files Expected To Change

• src/config.ts
• src/rules/types.ts
• src/rules/router.ts
• src/index.ts
• src/github/pr.ts
• tests/router.test.ts
• tests/* (new or updated tests for PR label transition and review-state gating)
• README.md
• examples/coloredcow-admin-sneha/.github/automation.yml (if kept aligned)
• dist/index.js (after npm run bundle)

Implementation Tasks (Phased, <=4 hours each)

Phase 1: Rule and config model updates

• T1: Extend config schema for reviewed label transition actions

  • Estimate: 1.5h
  • Files: src/config.ts
  • Definition of Done:
    • Config type supports explicit remove-label action for PR labels.
    • Validation accepts reviewed label config (primary + alias list as needed).
    • Backward compatibility retained for existing configs.
  • Dependencies: None

• T2: Extend action plan model/router to carry label removal action

  • Estimate: 1.0h
  • Files: src/rules/types.ts, src/rules/router.ts, tests/router.test.ts
  • Definition of Done:
    • Router maps new do action into action plan.
    • Existing rule mapping tests remain green.
    • New tests cover combined add/remove behavior precedence and defaults.
  • Dependencies: T1

Phase 2: Runtime behavior for review completion

• T3: Add PR label removal helper with idempotent/error-safe behavior

  • Estimate: 1.5h
  • Files: src/github/pr.ts, tests for PR helper
  • Definition of Done:
    • Helper removes configured label variants from a PR.
    • Dry-run path logs and skips writes.
    • Not-found/unapplied cases do not fail execution.
  • Dependencies: None

• T4: Add pull_request_review/submitted handling and review-state gating

  • Estimate: 3.0h
  • Files: src/index.ts, related tests
  • Definition of Done:
    • Entry flow handles both pull_request and pull_request_review contexts.
    • On review submitted, runs label transition only for approved and changes_requested states.
    • For non-target states, exits without mutations.
    • Existing pull-request paths continue working unchanged.
  • Dependencies: T2, T3

Phase 3: Integration, docs, and release artifact

• T5: Update default/config examples and documentation

  • Estimate: 1.0h
  • Files: README.md, example config files
  • Definition of Done:
    • Docs include new event trigger and rule examples.
    • Label naming guidance reflects issue decision (status : reviewed primary, Reviewed supported).
  • Dependencies: T4

• T6: Validation and dist bundle refresh

  • Estimate: 0.5h
  • Files: dist/index.js (+ any touched source/test files)
  • Definition of Done:
    • npm test passes.
    • npm run build passes.
    • npm run bundle completes and updates dist/index.js.
  • Dependencies: T5

Config/Rules Changes

Planned config additions (exact key names to be finalized during execution while preserving consistency):

• Add reviewed label config entries under labels:
  • primary reviewed label: status : reviewed
  • acceptable aliases list including Reviewed
• Add new rule do capability to remove PR label(s) when condition is met.
• Add rule for pull_request_review + submitted to transition labels.

API/Integration Changes

• Continue using GitHub REST issues labels endpoints for PR labels (PR is an issue resource).
• Add removal calls for ready-for-review variants before adding reviewed label.
• Ensure retries reuse existing wrapper strategy (withRetry) and avoid failures for benign no-op scenarios.
• Validate permissions remain within existing required scopes (pull-requests: write, issues: write).

Testing Strategy

• Unit tests for router mapping of new do-action.
• Unit tests for PR label removal helper:
  • remove when present
  • skip/no-op when absent
  • dry-run behavior
• Runtime/flow tests for review completion path:
  • approved transitions labels
  • changes_requested transitions labels
  • commented does nothing
• Regression tests for existing pull_request paths (opened/synchronize/review_requested/ready_for_review behavior remains intact).

Risks and Mitigations

• Risk: Incorrect event payload handling between pull_request and pull_request_review.
  • Mitigation: Explicit event-type branching and dedicated tests per payload shape.
• Risk: Label name mismatch across repos.
  • Mitigation: Support alias arrays and case-insensitive checks; document exact config examples.
• Risk: Duplicate/oscillating labels due to partial operations.
  • Mitigation: Remove ready labels first, then add reviewed label idempotently.
• Risk: Breaking existing workflows.
  • Mitigation: Preserve backward-compatible config parsing and add regression tests.

Validation Commands and Expected Outcomes

• npm test
  • Expected: all unit tests pass, including new review transition coverage.
• npm run build
  • Expected: TypeScript compilation succeeds with no errors.
• npm run bundle
  • Expected: dist/index.js regenerates successfully from updated source.

Ready-for-Execution Checklist

• Open question resolved and fixed in config/docs: primary reviewed label is status : reviewed; Reviewed supported as alias.
• Plan approved (/plan-approve or explicit approval by maintainer).
• Execution branch name decided using codex/<issue>-<slug> convention.
• Target workflow in consuming repo includes pull_request_review submitted trigger.

Out-of-Scope Future Enhancements

• Support configurable review-state filters beyond approved/changes_requested.
• Add telemetry/metrics for label transition outcomes.
• Add optional auto-cleanup for older status label families.