changelogs: Add --plan flag to changelog bundle

[cotti]

Dependency of elastic/docs-actions#42

This pull request adds a new --plan mode to the changelog bundling CLI and supporting code, allowing CI actions to determine required Docker flags, network access, and output paths before actually generating the bundle. The implementation includes a new planning method, structured result type, CLI wiring, and comprehensive tests.

The most important changes are:

New Planning Feature:

• Added a --plan option to the CLI, documented in docs/cli/changelog/bundle.md, which outputs a structured set of CI step outputs describing Docker flags, network requirements, and the resolved output path, then exits without generating the bundle.
• Introduced a new BundlePlanResult record type to represent the plan output, and implemented the PlanBundleAsync method in ChangelogBundlingService to resolve plan details from config/profile metadata without executing network calls or file scanning. [1] [2]

CLI and Service Integration:

• Updated the Bundle command in ChangelogCommand.cs to support the --plan flag, wiring it to call the new planning method and emit outputs for CI consumption. [1] [2] [3] [4] [5]

Testing:

• Added a new test suite BundlePlanTests to verify plan output logic for various config and profile scenarios, including output path resolution, network requirements, and error handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f6307b30-3c52-4f23-9ef7-02bcc10bb0f8

📥 Commits

Reviewing files that changed from the base of the PR and between 7e1be03 and 91aae3c.

📒 Files selected for processing (1)

• src/services/Elastic.Changelog/Bundling/ChangelogBundlingService.cs

🚧 Files skipped from review as they are similar to previous changes (1)

• src/services/Elastic.Changelog/Bundling/ChangelogBundlingService.cs

---

📝 Walkthrough

Walkthrough

Adds a --plan option to changelog bundle that resolves bundle inputs without executing bundling. Introduces ChangelogBundlingService.PlanBundleAsync(...) which loads configuration (profile or standard), determines whether network/GitHub token access is required (e.g., when a profile source is github_release), and computes the expected output path. When run in plan mode the CLI prints structured outputs (GitHub Actions outputs when applicable) and exits without creating the bundle. Documentation updated to describe the new general options and --plan.

Sequence Diagram

sequenceDiagram
    participant User as User/CLI
    participant Cmd as ChangelogCommand
    participant Svc as ChangelogBundlingService
    participant Config as Configuration Loader
    participant GH as GitHub Actions Outputs

    User->>Cmd: Run `changelog bundle --plan`
    activate Cmd
    Cmd->>Svc: PlanBundleAsync(collector, args, hasReleaseVersion, ctx)
    activate Svc
    Svc->>Config: Load changelog configuration (profile or standard)
    activate Config
    Config-->>Svc: Return configuration / profile metadata
    deactivate Config
    Svc->>Svc: Determine NeedsNetwork / NeedsGithubToken (e.g., github_release)
    Svc->>Svc: Compute OutputPath (profile templates or defaults)
    Svc-->>Cmd: Return BundlePlanResult{NeedsNetwork, NeedsGithubToken, OutputPath}
    deactivate Svc
    Cmd->>GH: Set outputs (needs_network, needs_github_token, output_path) or write to stdout
    Cmd-->>User: Exit (no bundle created)
    deactivate Cmd

Loading

Suggested labels

feature

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main feature: adding a --plan flag to the changelog bundle command, which is the primary change across all modified files.
Description check	✅ Passed	The description clearly relates to the changeset, detailing the --plan feature implementation, service integration, CLI wiring, and test coverage that match the actual changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feature/changelog-bundle-plan

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/Elastic.Changelog.Tests/Changelogs/BundlePlanTests.cs (1)

161-185: Misleading test name.

The test is named Plan_ProfileNotFound_ReturnsNull but asserts result.Should().NotBeNull(). Consider renaming to Plan_ProfileNotFound_ReturnsResultWithNoNetworkRequirement to match the actual behavior being tested.

Suggested rename

 [Fact]
-public async Task Plan_ProfileNotFound_ReturnsNull()
+public async Task Plan_ProfileNotFound_ReturnsResultWithNoNetworkRequirement()

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/Elastic.Changelog.Tests/Changelogs/BundlePlanTests.cs` around lines 161
- 185, Rename the misleading test method Plan_ProfileNotFound_ReturnsNull to
reflect its assertions (e.g.,
Plan_ProfileNotFound_ReturnsResultWithNoNetworkRequirement); update the method
name declaration in the BundlePlanTests class and any references to it so the
test name matches the behavior being asserted (result is not null and
NeedsNetwork is false) when calling Service.PlanBundleAsync with a nonexistent
profile via the BundleChangelogsArguments instance.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@tests/Elastic.Changelog.Tests/Changelogs/BundlePlanTests.cs`:
- Around line 161-185: Rename the misleading test method
Plan_ProfileNotFound_ReturnsNull to reflect its assertions (e.g.,
Plan_ProfileNotFound_ReturnsResultWithNoNetworkRequirement); update the method
name declaration in the BundlePlanTests class and any references to it so the
test name matches the behavior being asserted (result is not null and
NeedsNetwork is false) when calling Service.PlanBundleAsync with a nonexistent
profile via the BundleChangelogsArguments instance.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2b7a7b5c-1c2b-4521-b5f4-5f5005869e03

📥 Commits

Reviewing files that changed from the base of the PR and between c4473c9 and 7e1be03.

📒 Files selected for processing (4)

• docs/cli/changelog/bundle.md
• src/services/Elastic.Changelog/Bundling/ChangelogBundlingService.cs
• src/tooling/docs-builder/Commands/ChangelogCommand.cs
• tests/Elastic.Changelog.Tests/Changelogs/BundlePlanTests.cs