fix(internal): wrap angle bracket type references in changelog entries with backticks

[iamnamananand996]

Description

Refs: Reported by customer — Optional<String> and similar Java type references in auto-generated changelogs cause MDX compilation failures when changelogs are pulled into documentation sites, as MDX parsers interpret <String> as an unclosed HTML/JSX tag.

This PR adds post-processing sanitization to wrap type references containing angle brackets (e.g. Optional<String>, Map<String, Object>) in inline code fences (backticks) across both changelog generation paths.

Changes Made

• New shared utility sanitizeChangelogEntry in @fern-api/core-utils — balanced-bracket parser that finds Identifier<...> patterns and wraps them in backticks. Supports arbitrary nesting depth (e.g. Map<String, Map<String, List<Integer>>>). Splits on existing backtick spans to avoid double-wrapping.
• writeChangelogEntries.ts (seed path) — imports shared utility and applies it to summary, added, changed, deprecated, removed, fixed, and upgradeNotes fields.
• LocalTaskHandler.ts (auto-versioning path) — sanitizes the changelogEntry via re-exported utility before it flows into the analysis object. prDescription is intentionally not sanitized — it flows to GitHub PR bodies (standard Markdown), not MDX.
• BAML prompt (diff_analyzer.baml) — adds an instruction to the AI to wrap angle-bracket type references in backticks at generation time (defense in depth).
• Unit tests — 15 tests in sanitizeChangelogEntry.test.ts covering simple generics, nested generics (2- and 3-level), double-wrap prevention, multiple types per line, bare angle brackets, comparison operators, empty strings, and multiline entries.
• versions.yml — adds CLI version 4.31.2 entry.

Human Review Checklist

• Balanced-bracket parser edge cases: The parser is hand-rolled character-by-character. Unit tests cover the main scenarios but consider: unbalanced brackets (e.g. Foo<Bar without closing >), empty angle brackets (Foo<>), identifiers immediately adjacent to punctuation.
• False positive risk: Any single-letter identifier followed by < with a balanced > will match (e.g. a<b> in prose). Unlikely in real changelog text but worth noting.
• Backtick splitting assumption: The split regex /(`[^`]+`)/g handles single-backtick code spans. Triple-backtick fenced blocks in changelog entries (unlikely but possible) would not be handled correctly.
• BAML prompt effectiveness: The AI instruction is defense-in-depth; the post-processing sanitization is the real safety net. The AI may not always comply.

Testing

• Unit tests added — 15 tests in sanitizeChangelogEntry.test.ts (all passing via vitest)
• Lint passes (pnpm run check / biome check)
• CI green (291/291 checks passing)
• Manual / integration testing — no end-to-end test with actual changelog generation

Link to Devin session: https://app.devin.ai/sessions/423b9cc168b44b199e679cdd9c74adfc
Requested by: @iamnamananand996

[claude]

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit in Settings → Usage.

Once credits are available, reopen this pull request to trigger a review.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring