refactor(changelog): prose Speakeasy summaries + skip empty releases (#511)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: steve-calvert-glean

packages/changelog-generator/src/pipeline.ts

@@ -5,6 +5,7 @@ import type { RawRelease, ReleaseResult } from './types.js';
 import { fetchNewReleases } from './release-fetcher.js';
 import { summarizeRelease } from './summarizer.js';
 import { renderEntry } from './entry-renderer.js';
+import { preProcessRelease } from './preprocessors/index.js';
 
 export async function processRelease(
   release: RawRelease,
@@ -15,6 +16,22 @@ export async function processRelease(
   },
 ): Promise<ReleaseResult> {
   try {
+    // Skip Speakeasy releases that have no structured API changes — these are
+    // SDK rebuilds (e.g. "Publishing Completed") with nothing user-facing to
+    // describe, and would otherwise produce noise entries in the changelog.
+    const preProcessed = preProcessRelease(release);
+    if (
+      preProcessed.format === 'speakeasy' &&
+      preProcessed.structuredChanges.length === 0
+    ) {
+      return {
+        status: 'skipped',
+        owner: release.owner,
+        repo: release.repo,
+        reason: `${release.tag} has no structured API changes`,
+      };
+    }
+
     const result = await summarizeRelease(release.body, {
       mode: opts.summarization.mode,
       maxBullets: opts.summarization.maxBullets,

packages/changelog-generator/src/preprocessors/__tests__/speakeasy.test.ts

@@ -54,6 +54,20 @@ Generated with [Speakeasy CLI 1.759.3](https://github.com/speakeasy-api/speakeas
 
 Publishing Completed`;
 
+const FIXTURE_EMPTY_SPEAKEASY = `# Generated by Speakeasy CLI
+
+## 2026-04-20 17:34:02
+### Changes
+Based on:
+- OpenAPI Doc 0.9.0
+- Speakeasy CLI 1.761.8 (2.881.2) https://github.com/speakeasy-api/speakeasy
+### Generated
+- [typescript v0.14.19] .
+### Releases
+- [NPM v0.14.19] https://www.npmjs.com/package/@gleanwork/api-client/v/0.14.19 - .
+
+Publishing Completed`;
+
 const FIXTURE_NOT_SPEAKEASY = `## What's Changed
 * Add installable skills for SDK usage
 * Add injectable GleanContext
@@ -91,6 +105,10 @@ describe('isSpeakeasyFormat', () => {
       false,
     );
   });
+
+  it('returns true for empty Speakeasy releases (Publishing Completed only)', () => {
+    expect(isSpeakeasyFormat(FIXTURE_EMPTY_SPEAKEASY)).toBe(true);
+  });
 });
 
 describe('parseSpeakeasyNotes', () => {
@@ -180,6 +198,11 @@ describe('parseSpeakeasyNotes', () => {
     });
   });
 
+  it('returns no changes for empty Speakeasy releases (signal for pipeline skip)', () => {
+    const changes = parseSpeakeasyNotes(FIXTURE_EMPTY_SPEAKEASY);
+    expect(changes).toHaveLength(0);
+  });
+
   it('returns correct method and action for each change', () => {
     const changes = parseSpeakeasyNotes(FIXTURE_GO_v0_11_40);
 
@@ -199,34 +222,45 @@ describe('formatSpeakeasySummary', () => {
     expect(result).toBe('Maintenance updates and improvements.');
   });
 
-  it('produces a single string without markdown bullets at line start', () => {
+  it('produces prose with no markdown bullets', () => {
     const changes = parseSpeakeasyNotes(FIXTURE_GO_v0_11_41);
     const result = formatSpeakeasySummary(changes);
 
-    // No lines starting with "- " (markdown bullet)
-    const lines = result.split('\n');
-    for (const line of lines) {
+    for (const line of result.split('\n')) {
       expect(line).not.toMatch(/^- /);
     }
   });
 
-  it('uses " - " separator for details', () => {
+  it('groups changes by action verb into one sentence each', () => {
+    const changes = parseSpeakeasyNotes(FIXTURE_GO_v0_11_40);
+    const result = formatSpeakeasySummary(changes);
+
+    // FIXTURE_GO_v0_11_40 has one 'changed' and one 'added'
+    expect(result).toMatch(/^Added\b/);
+    expect(result).toContain('Changed ');
+  });
+
+  it('backticks both field and method names', () => {
     const changes = parseSpeakeasyNotes(FIXTURE_GO_v0_11_41);
     const result = formatSpeakeasySummary(changes);
-    expect(result).toContain(' - ');
+
+    // Each phrase should look like `field` to|from|on `method`
+    expect(result).toMatch(/`[A-Za-z]+`\s+(to|from|on)\s+`[a-z.()]+`/);
   });
 
-  it('does not produce garbage like "- : - **Added**"', () => {
+  it('preserves dotted method paths', () => {
     const changes = parseSpeakeasyNotes(FIXTURE_GO_v0_11_41);
     const result = formatSpeakeasySummary(changes);
-    expect(result).not.toMatch(/- :\s*-?\s*\*\*/);
+
+    // "Glean.Governance.Createfindingsexport()" -> "governance.createfindingsexport()"
+    expect(result).toContain('governance.createfindingsexport()');
+    expect(result).toContain('governance.listfindingsexports()');
   });
 
   it('mentions actual field/method names from the changes', () => {
     const changes = parseSpeakeasyNotes(FIXTURE_GO_v0_11_40);
     const result = formatSpeakeasySummary(changes);
 
-    // Should reference method names or fields
     expect(result.toLowerCase()).toMatch(
       /insights|retrieve|search|retrievefeed|agentsresponse|spreadsheettype/,
     );
@@ -243,7 +277,17 @@ describe('formatSpeakeasySummary', () => {
     const result = formatSpeakeasySummary(changes);
 
     expect(result.length).toBeGreaterThan(20);
-    // Should start with an uppercase letter or digit
-    expect(result[0]).toMatch(/[A-Z0-9]/);
+    expect(result[0]).toMatch(/[A-Z]/);
+    expect(result.endsWith('.') || result.endsWith('...')).toBe(true);
+  });
+
+  it('caps items per verb with "and N more" when there are many changes', () => {
+    const changes = parseSpeakeasyNotes(FIXTURE_TS_v0_14_14);
+    // FIXTURE_TS_v0_14_14 has 9 'added' changes, default cap is 4
+    const result = formatSpeakeasySummary(changes, {
+      maxBullets: 4,
+      maxChars: 1000,
+    });
+    expect(result).toMatch(/and \d+ more/);
   });
 });

packages/changelog-generator/src/preprocessors/speakeasy.ts

@@ -70,44 +70,48 @@ export function parseSpeakeasyNotes(text: string): ParsedChange[] {
   return changes;
 }
 
-/**
- * Simplify a deep field path for human-readable summary.
- * e.g. "request.chatRequest.messages[].citations[].sourceFile.metadata.status.enum(partiallyProcessed)"
- *   -> "partiallyProcessed"
- *
- * But for simple paths: "request.document.nativeAppUrl" -> "nativeAppUrl"
- */
 function simplifyFieldPath(field: string): string {
-  // Extract enum value if present: .enum(value) -> "value enum"
   const enumMatch = field.match(/\.enum\((\w+)\)$/i);
   if (enumMatch) {
     return enumMatch[1];
   }
 
-  // Get the last meaningful segment
   const segments = field.split('.');
   const last = segments[segments.length - 1]
     .replace(/\[\]/g, '')
     .replace(/Map<\w+>/g, '');
   return last;
 }
 
-/**
- * Extract a short method name from the full SDK path.
- * e.g. "Glean.Client.Chat.Create()" -> "chat create"
- * e.g. "glean.client.chat.create()" -> "chat create"
- * e.g. "Glean.Governance.Createfindingsexport()" -> "governance createfindingsexport"
- */
 function shortMethodName(method: string): string {
-  const parts = method.replace(/\(\)$/, '').split('.');
-  // Skip "Glean"/"glean" and "Client"/"client" prefixes
-  const meaningful = parts.filter((p) => !/^(glean|client)$/i.test(p));
-  return meaningful.join(' ').toLowerCase();
+  // Strip the leading "Glean." namespace but preserve everything else,
+  // so we keep meaningful paths like "client.insights.retrieve()" or
+  // "governance.createfindingsexport()".
+  return method.replace(/^[Gg]lean\./, '').toLowerCase();
 }
 
+function joinList(items: string[]): string {
+  if (items.length === 0) return '';
+  if (items.length === 1) return items[0];
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+}
+
+const VERBS: Array<{
+  action: ParsedChange['action'];
+  verb: string;
+  preposition: string;
+}> = [
+  { action: 'added', verb: 'Added', preposition: 'to' },
+  { action: 'removed', verb: 'Removed', preposition: 'from' },
+  { action: 'changed', verb: 'Changed', preposition: 'on' },
+  { action: 'deprecated', verb: 'Deprecated', preposition: 'on' },
+];
+
 /**
- * Format parsed Speakeasy changes into a human-readable summary
- * matching the repo's established entry format.
+ * Format parsed Speakeasy changes into prose: one sentence per action verb,
+ * with backticked field and method names. Deterministic — only emits
+ * identifiers that appear in the parsed changes.
  */
 export function formatSpeakeasySummary(
   changes: ParsedChange[],
@@ -117,47 +121,26 @@ export function formatSpeakeasySummary(
     return 'Maintenance updates and improvements.';
   }
 
-  const maxBullets = opts.maxBullets ?? 3;
   const maxChars = opts.maxChars ?? 300;
-
-  // Group changes by action type
-  const byAction = new Map<string, ParsedChange[]>();
-  for (const c of changes) {
-    const existing = byAction.get(c.action) || [];
-    existing.push(c);
-    byAction.set(c.action, existing);
+  const itemsPerVerb = Math.max(1, opts.maxBullets ?? 4);
+
+  const sentences: string[] = [];
+  for (const { action, verb, preposition } of VERBS) {
+    const items = changes.filter((c) => c.action === action);
+    if (items.length === 0) continue;
+
+    const phrases = items.slice(0, itemsPerVerb).map((c) => {
+      const field = simplifyFieldPath(c.field);
+      const method = shortMethodName(c.method);
+      return `\`${field}\` ${preposition} \`${method}\``;
+    });
+
+    const overflow = items.length - itemsPerVerb;
+    const tail = overflow > 0 ? ` and ${overflow} more` : '';
+    sentences.push(`${verb} ${joinList(phrases)}${tail}.`);
   }
 
-  // Group changes by simplified method for the intro
-  const methodNames = new Set(changes.map((c) => shortMethodName(c.method)));
-  const methodList = [...methodNames].slice(0, 4);
-  const methodSuffix =
-    methodNames.size > 4 ? ` and ${methodNames.size - 4} more` : '';
-
-  // Build intro sentence
-  const actionCounts: string[] = [];
-  for (const [action, items] of byAction) {
-    actionCounts.push(
-      `${items.length} field${items.length > 1 ? 's' : ''} ${action}`,
-    );
-  }
-
-  const intro = `${actionCounts.join(', ')} across ${methodList.join(', ')}${methodSuffix} endpoints.`;
-
-  // Build detail bullets (up to maxBullets) using ` - ` separator format
-  const details: string[] = [];
-  for (const c of changes.slice(0, maxBullets)) {
-    const fieldName = simplifyFieldPath(c.field);
-    const method = shortMethodName(c.method);
-    details.push(`${c.action} ${fieldName} in ${method}`);
-  }
-
-  let result = details.length > 0 ? intro + ' - ' + details.join(' - ') : intro;
-
-  // Capitalize first letter
-  result = result.charAt(0).toUpperCase() + result.slice(1);
-
-  // Truncate if needed
+  let result = sentences.join(' ');
 
   if (result.length > maxChars) {
     result =

packages/changelog-generator/src/shared/github.ts

@@ -98,6 +98,13 @@ export async function analyze(repoRoot: string): Promise<AnalyzeOutput> {
         content: result.entry.content,
         commitMessage: result.entry.commitMessage,
       });
+    } else if (result.status === 'skipped') {
+      skipped.push({
+        owner: result.owner,
+        repo: result.repo,
+        decision: 'skip',
+        reason: result.reason,
+      });
     } else if (result.status === 'error') {
       const parts = result.error.release.split('/');
       errors.push({