Skip to content

refactor(pkg/workflow): centralize condition/token helpers and normalize entity helper naming - #32227

Merged
pelikhan merged 6 commits into
mainfrom
copilot/refactor-condition-node-builders
May 15, 2026
Merged

pelikhan merged 6 commits into
mainfrom
copilot/refactor-condition-node-builders

Conversation

Copilot AI commented May 15, 2026 •

Copy link
Copy Markdown
Contributor

✨ Enhancement

pkg/workflow had function-location drift across three areas: ConditionNode builders were spread across compiler files, create/update/close helper naming was inconsistent, and token-resolution logic was split between unrelated helper files. This change consolidates ownership so symbol location and naming now match responsibility.

  • Condition builders canonicalized

    Moved scattered build*Condition helpers into expression_builder.go (canonical ConditionNode home), including:

    • comment author association conditions
    • skip-author-association conditions
    • detection success/passed conditions
      Compiler files now consume these helpers instead of owning duplicate builder logic.
  • Entity helper naming normalized

    Aligned create parser naming with existing verb-prefixed convention:

    • parseIssuesConfig → parseCreateIssuesConfig
    • parseDiscussionsConfig → parseCreateDiscussionsConfig
    • parsePullRequestsConfig → parseCreatePullRequestsConfig
      Also normalized update helper file names:
    • update_issue_helpers.go → update_issue.go
    • update_discussion_helpers.go → update_discussion.go
    • update_pull_request_helpers.go → update_pull_request.go
      Updated all internal call sites, tests, and relevant docs/comments.
  • Token resolution centralized and consistently named

    Moved token-resolution helpers out of safe_outputs_config_helpers.go into github_token.go and standardized naming to resolve*:

    • resolvePRCheckoutToken
    • resolveStaticCheckoutToken
    • resolveProjectToken
    • resolveProjectURLAndToken
      safe_outputs_config_helpers.go now focuses on safe-output config serialization utilities.
// before
issues := c.parseIssuesConfig(outputMap)
projectURL, projectToken := computeProjectURLAndToken(data.SafeOutputs)

// after
issues := c.parseCreateIssuesConfig(outputMap)
projectURL, projectToken := resolveProjectURLAndToken(data.SafeOutputs)

Copilot AI and others added 3 commits May 15, 2026 00:25
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot AI changed the title [WIP] Refactor pkg/workflow for consistent ConditionNode builders refactor(pkg/workflow): centralize condition/token helpers and normalize entity helper naming May 15, 2026
Copilot AI requested a review from pelikhan May 15, 2026 00:29
@pelikhan
pelikhan marked this pull request as ready for review May 15, 2026 00:30
Copilot AI review requested due to automatic review settings May 15, 2026 00:30

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

This PR refactors pkg/workflow to consolidate related helper logic (conditions + token resolution) and to normalize helper naming for safe-outputs entity config parsing, reducing “function-location drift” and improving discoverability/consistency.

Changes:

  • Centralizes multiple ConditionNode builder helpers into expression_builder.go and removes duplicates from compiler files.
  • Normalizes create-* safe-outputs parser method names (parse*Config → parseCreate*Config) and renames update-entity helper files to verb-aligned filenames.
  • Centralizes safe-outputs token resolution helpers into github_token.go with consistent resolve* naming, removing token logic from safe_outputs_config_helpers.go.
Show a summary per file
File Description
pkg/workflow/update_pull_request.go Adds update-pull-request config type + parser under normalized filename.
pkg/workflow/update_issue.go Adds update-issue config type + parser under normalized filename.
pkg/workflow/update_discussion.go Adds update-discussion config type + parser under normalized filename.
pkg/workflow/update_entity_helpers.go Updates documentation pointers to renamed update-* files.
pkg/workflow/safe_outputs_config.go Updates call sites to renamed create-* parser methods.
pkg/workflow/safe_outputs_config_helpers.go Removes token resolution helpers; leaves config serialization helpers.
pkg/workflow/github_token.go Adds centralized resolve* token helpers for safe-outputs operations.
pkg/workflow/expression_builder.go Becomes the canonical home for moved condition builder helpers.
pkg/workflow/create_pull_request.go Renames parser to parseCreatePullRequestsConfig and updates related comments.
pkg/workflow/create_issue.go Renames parser to parseCreateIssuesConfig.
pkg/workflow/create_discussion.go Renames parser to parseCreateDiscussionsConfig.
pkg/workflow/create_discussion_validation_test.go Updates tests to call renamed discussion parser.
pkg/workflow/create_discussion_dependencies_test.go Updates tests and messages to use renamed discussion parser.
pkg/workflow/create_code_scanning_alert.go Updates static checkout token helper call to resolveStaticCheckoutToken.
pkg/workflow/config_parsing_helpers_test.go Updates tests to use renamed create-* parser methods.
pkg/workflow/config_helpers.go Updates comment to reference renamed create-* parsers.
pkg/workflow/compiler_safe_outputs_steps.go Switches PR checkout token resolution to resolvePRCheckoutToken and project token helper to resolveProjectURLAndToken.
pkg/workflow/compiler_safe_outputs_job.go Removes detection condition helpers that were moved into expression_builder.go.
pkg/workflow/compiler_pre_activation_job.go Removes moved condition helpers and cleans up imports accordingly.
pkg/workflow/close_entity_helpers.go Updates documentation references to renamed update-* files.
DEVGUIDE.md Updates documentation examples to reflect renamed create-issue parser method.

Copilot's findings

Tip

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

  • Files reviewed: 18/21 changed files
  • Comments generated: 1

Comment on lines +219 to +229
func buildAuthorAssociationNodeForEvent(eventName string) ConditionNode {
switch eventName {
case "issue_comment", "pull_request_review_comment", "pull_request_review", "discussion_comment":
return BuildPropertyAccess("github.event.comment.author_association")
case "issues":
return BuildPropertyAccess("github.event.issue.author_association")
case "pull_request", "pull_request_target":
return BuildPropertyAccess("github.event.pull_request.author_association")
default:
return &ExpressionNode{Expression: "github.event.comment.author_association || github.event.issue.author_association || github.event.pull_request.author_association || github.event.author_association"}
}
@pelikhan

Copy link
Copy Markdown
Collaborator

@copilot review all comments and reviews

@github-actions

Copy link
Copy Markdown
Contributor

🧪 Test Quality Sentinel Report

Test Quality Score: N/A — No New Tests

i️ No new test functions were added or modified in this PR.

The three test files listed as changed contain only mechanical renames:

File Change
pkg/workflow/config_parsing_helpers_test.go Renamed calls: parseIssuesConfig → parseCreateIssuesConfig, parsePullRequestsConfig → parseCreatePullRequestsConfig, parseDiscussionsConfig → parseCreateDiscussionsConfig
pkg/workflow/create_discussion_dependencies_test.go Renamed call: parseDiscussionsConfig → parseCreateDiscussionsConfig (+ matching message string)
pkg/workflow/create_discussion_validation_test.go Renamed calls: parseDiscussionsConfig → parseCreateDiscussionsConfig

No test logic, assertions, or test function signatures were changed. All changes are keeping tests in sync with the production-code refactoring (function renames).


Verdict

✅ Check passed. No new test functions were added; the test changes are purely refactoring-induced renames with no behavioral change. No coding-guideline violations detected.


Language Support

Tests analyzed:

  • 🐹 Go (*_test.go): 0 new/modified test functions
  • 🟨 JavaScript (*.test.cjs, *.test.js): 0 tests

References: §25893510355

🧪 Test quality analysis by Test Quality Sentinel · ● 4.2M · ◷

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

✅ Test Quality Sentinel: N/A. No new test functions were added — all test changes are purely mechanical renames tracking the production-code refactoring. No coding-guideline violations detected.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Skills-Based Review 🧠

Applied /zoom-out and /improve-codebase-architecture — this is a refactor that consolidates module ownership, so those lenses are most relevant.

Key Themes

  • Depth improvement ✅ — expression_builder.go now owns all ConditionNode construction and github_token.go owns all token resolution. The deletion test passes: removing either old scattering would have forced callers to reconstruct the logic. Module depth is genuinely increased.
  • Naming consistency ✅ — parseCreate* and resolve* prefixes are now aligned with the verb-prefixed convention used elsewhere in the package. update_*_helpers.go → update_*.go is a nice cleanup of a gratuitous _helpers suffix.
  • Comment locality loss ⚠️ — Two minor comment drops during the move: buildAuthorAssociationNodeForEvent arrived without a doc comment, and buildCommentAuthorAssociationCondition lost the inline explanation of why github.actor is used for bot exemption instead of author_association. Both encoded non-obvious design decisions.
  • Named return readability ⚠️ — resolveProjectURLAndToken uses named returns with bare return statements. With three distinct priority branches it makes the data flow slightly harder to follow.

Positive Highlights

  • ✅ safe_outputs_config_helpers.go is now genuinely focused on safe-output serialisation — the file's stated purpose finally matches its contents
  • ✅ resolveProjectToken is a clean, shallow helper that removes duplication across the three project-URL branches
  • ✅ Doc comments on the new resolve* functions are thorough and include explicit precedence ladders
  • ✅ No behaviour changes — this is a pure structural move, which keeps the diff reviewable

Verdict

Observations only — no blocking issues. The comment-loss items are small enough to address in a follow-up or in this PR.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · ● 8.6M

return result
}

func buildAuthorAssociationNodeForEvent(eventName string) ConditionNode {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[/zoom-out] buildAuthorAssociationNodeForEvent lost its doc comment during the move. The function encodes non-obvious domain knowledge — specifically, which GitHub event schema field carries author_association for each event type, and why the default branch emits a multi-field OR expression. A short doc comment would preserve that intent for future readers:

// buildAuthorAssociationNodeForEvent returns the ConditionNode that reads the correct
// author_association field for the given event name. Each event type exposes the field
// at a different path in the GitHub event payload; the default fallback tries all known
// paths so unknown events still work.
func buildAuthorAssociationNodeForEvent(eventName string) ConditionNode {

BuildStringLiteral(bot),
)
}
result = BuildOr(result, BuildDisjunction(false, botTerms...))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[/zoom-out] The move dropped four inline comments from the bot-exemption block that explained why github.actor is used instead of author_association, and why BuildDisjunction is preferred over nested BuildOr calls. These are non-obvious design decisions worth preserving:

// Allow explicitly listed bot/app actors so on.bots behaviour is preserved.
// Bots typically carry no OWNER/MEMBER/COLLABORATOR association, so we exempt
// them by actor login rather than by author_association.
// Use BuildDisjunction to collect all bot conditions into a flat OR rather than
// building a deeply nested binary tree with repeated BuildOr calls.
result = BuildOr(result, BuildDisjunction(false, botTerms...))

Re-adding them maintains the locality of design rationale inside expression_builder.go.

tokenLog.Printf("Setting GH_AW_PROJECT_GITHUB_TOKEN from create-project config")
}

return

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[/improve-codebase-architecture] Named returns with bare return statements reduce readability here. The caller has to scroll back to the function signature to know what's being returned, and it's easy to accidentally return zero values by falling off the end of a branch. Explicit returns would make the function clearer, especially given the three distinct priority paths:

// instead of bare return:
return projectURL, projectToken

If named returns are kept for the early-exit return "", "" path, consider using them only there and making the remaining returns explicit.

Generated by the Design Decision Gate workflow. Documents the
centralization of ConditionNode builders into expression_builder.go,
the verb-prefixed create-entity parser rename, the update-entity file
rename (drop _helpers suffix), and the token-resolution move to
github_token.go with resolve* prefix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

Commit pushed: ce6bd00

🏗️ ADR gate enforced by Design Decision Gate 🏗️ · ● 7M

@github-actions

Copy link
Copy Markdown
Contributor

🏗️ Design Decision Gate — ADR Required

This PR makes significant changes to core business logic in pkg/workflow (301 new lines across expression_builder.go, github_token.go, and renames touching 30+ files) but does not have a linked Architecture Decision Record (ADR).

AI has analyzed the PR diff and generated a draft ADR to help you get started:

📄 Draft ADR: docs/adr/32227-centralize-condition-and-token-helpers-and-normalize-entity-helper-naming.md

The draft was inferred from the diff and PR description. It documents three structural decisions:

  1. Centralizing ConditionNode builders into expression_builder.go
  2. Renaming create-entity parsers to the verb-prefixed convention and dropping the _helpers suffix from update-entity files
  3. Moving token-resolution helpers into github_token.go and standardizing on the resolve* prefix

What to do next

  1. Review the draft ADR committed to your branch — it was generated from the PR diff and the PR description, and it cross-references the prior ADRs that established the semantic file-naming convention (ADR-27325, ADR-28282, ADR-29336).
  2. Complete any missing context — in particular, confirm the alternatives reflect what was actually considered and refine the rationale where AI inference may have generalized.
  3. Commit the finalized ADR to docs/adr/ on your branch (change Status from Draft to Proposed or Accepted once reviewed).
  4. Reference the ADR in this PR body by adding a line such as:

    ADR: ADR-32227: Centralize Condition and Token Helpers and Normalize Entity Helper Naming

Once an ADR is linked in the PR body, this gate will re-run and verify the implementation matches the decision.

Why ADRs Matter

ADRs create a searchable, permanent record of why the codebase looks the way it does. This PR is the fourth in a series of file-placement refactors (ADR-27325, ADR-28282, ADR-29336); recording it as an ADR keeps the chain of reasoning intact for future contributors and for the next round of semantic clustering analysis.

📋 Michael Nygard ADR Format Reference

An ADR must contain these four narrative sections to be considered complete:

  • Context — What is the problem? What forces are at play?
  • Decision — What did you decide? Why?
  • Alternatives Considered — What else could have been done?
  • Consequences — What are the trade-offs (positive and negative)?

This repo's ADRs additionally include a Part 2 normative specification using RFC 2119 keywords (MUST, SHOULD, MAY) for machine-checkable conformance. All ADRs are stored in docs/adr/ as Markdown files numbered by PR number.

🔒 This PR cannot merge until an ADR is linked in the PR body.

References:

🏗️ ADR gate enforced by Design Decision Gate 🏗️ · ● 7M · ◷

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI commented May 15, 2026

Copy link
Copy Markdown
Contributor Author

@copilot review all comments and reviews

Addressed the actionable review thread in commit 6d3b20f: pull_request_review now uses github.event.review.author_association (while pull_request_review_comment remains on github.event.comment.author_association), and I added regression coverage in skip_author_associations_test.go to verify the mapping and rendered pre-activation condition.

@pelikhan
pelikhan merged commit 46db492 into main May 15, 2026
@pelikhan
pelikhan deleted the copilot/refactor-condition-node-builders branch May 15, 2026 01:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

3 participants