Add description-visibility option to changelog directive

[lcawl]

Summary

This PR adds a new option to the changelog directive so that teams can have full control over whether changelog description fields are shown in the output.

Screenshots

Before:

After:

AI implementation details

Behaviour

• New option :description-visibility: on {changelog} with values auto (default), keep-descriptions, hide-descriptions.
• auto: hides per-entry description when the bundle’s repo has no private constituent (+-split repo names vs assembler.yml privates — same constituent resolution as links). HasAnyPrivateRepoConstituent mirrors link logic; ShouldHideLinksForRepo now delegates to it so split/trim behaviour stays aligned.
• Bundle-level description (intro prose) is unchanged — only entry bodies / dropdown intros are gated.
• Invalid values → warning + auto (same spirit as :link-visibility:).

Code

File	Change
ChangelogDescriptionVisibility.cs	New enum
ChangelogBlock.cs	DescriptionVisibility, ParseDescriptionVisibility
ChangelogInlineRenderer.cs	ShouldHideEntryDescriptionsForRepo, HasAnyPrivateRepoConstituent, plumbed hideEntryDescriptions through all bullet + dropdown paths (including :type: highlight)

Tests

• ChangelogDescriptionVisibilityTests.cs — helper unit tests + directive coverage (default/auto, keep, hide, invalid, private-repo case via RenderChangelogMarkdown after mutating PrivateRepositories, matching the hide-links tests).
• ChangelogBasicTests.cs — ChangelogTitleDescriptionSpacingTests now uses :description-visibility: keep-descriptions so it still verifies body text spacing.

Docs

• docs/syntax/changelog.md — options table, :description-visibility: section (contrast vs :link-visibility:), rendered-output note distinguishing bundle vs record descriptions.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-2, claude-4-sonnet-thinking

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 735aa95a-c051-4e31-b38c-83ba6be5f5e8

📥 Commits

Reviewing files that changed from the base of the PR and between a3b9491 and b5ca405.

📒 Files selected for processing (6)

• docs/syntax/changelog.md
• src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogBlock.cs
• src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogDescriptionVisibility.cs
• src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.cs
• tests/Elastic.Markdown.Tests/Directives/ChangelogBasicTests.cs
• tests/Elastic.Markdown.Tests/Directives/ChangelogDescriptionVisibilityTests.cs

---

📝 Walkthrough

Walkthrough

This PR adds a new :description-visibility: option to the {changelog} directive that controls whether per-record YAML descriptions are rendered. The option supports three modes: auto (default, omits descriptions for all-public bundles), keep-descriptions (always renders descriptions), and hide-descriptions (always omits descriptions). A new enum ChangelogDescriptionVisibility defines these modes. The ChangelogBlock class is updated to parse and store this option. The renderer implements privacy-aware logic via two helper methods that check repository constituents and determine visibility based on the selected mode. Comprehensive test coverage validates all three modes and their behaviors.

Sequence Diagram

sequenceDiagram
    participant Block as ChangelogBlock
    participant Parser as Parser/Validator
    participant Renderer as ChangelogInlineRenderer
    participant PrivacyCheck as Privacy Logic
    participant Output as Rendered Output

    Block->>Parser: Parse :description-visibility: option
    Parser->>Block: Set DescriptionVisibility enum (auto/keep/hide)
    
    Block->>Renderer: RenderChangelogMarkdown(block with DescriptionVisibility)
    Renderer->>Renderer: RenderSingleBundle(descriptionVisibility)
    
    Renderer->>PrivacyCheck: ShouldHideEntryDescriptionsForRepo(bundle, visibility)
    
    alt visibility == auto
        PrivacyCheck->>PrivacyCheck: HasAnyPrivateRepoConstituent(bundleRepo)
        PrivacyCheck-->>Renderer: hideDescriptions = has_private_repo
    else visibility == keep-descriptions
        PrivacyCheck-->>Renderer: hideDescriptions = false
    else visibility == hide-descriptions
        PrivacyCheck-->>Renderer: hideDescriptions = true
    end
    
    Renderer->>Renderer: RenderSingleEntry / RenderDetailedEntry
    
    alt hideDescriptions == true
        Renderer->>Output: Render title/links only
    else hideDescriptions == false
        Renderer->>Output: Render title + description
    end

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a new description-visibility option to the changelog directive.
Description check	✅ Passed	The description thoroughly explains the new feature, behavior options, code implementation, tests, and documentation changes related to the changelog directive enhancement.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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 changelog-descriptions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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