feat(extensions): expose public hunk summaries on file views

[benvinegar]

What

Adds ExtensionDiffHunk to the public extension API and fills a hunks list on every read-only file view Hunk hands outward — event payloads, sidebar props, and a command's selection.

Each summary carries index, the @@ header, and inclusive old/new line spans, in render order. The index is the same one selectedHunkIndex reports and actions.selectHunk accepts, so the three hunk surfaces line up by design.

Why

Extension-author feedback (follow-up 2 of the report addressed by #625): selectedHunkIndex is public, but hunk headers, ranges, and counts lived inside the opaque file.metadata. That limited a progress view to files viewed and made a hunk checklist or agent-annotation navigator impossible without casting into an object the contract promises not to describe — the authoring guide's own pick-hunk example did exactly that cast.

How

• ExtensionDiffHunk is declared in src/extension-api/types.ts (which stays import-free; check:pack passes) and exported from the barrel.
• Summaries are derived from metadata at the view boundary in toReadOnlyFileViews — like changeType, transforms neither receive nor produce them, and a stale hunks value spread through a transform is replaced by what the metadata actually parses to. Derivation is cached per parsed-diff metadata object (views are rebuilt on every emit), and repeated conversions hand back the identical frozen list.
• The derivation lives in one core helper, src/core/hunkSummary.ts, now shared with the agent session surface (buildSessionFiles), so the two external views of a review cannot drift apart. A transform-synthesized hunk without numeric line data gets its declared header text (or an empty one) and no ranges, instead of NaN spans.
• The guide's pick-hunk example now uses ctx.selection.file.hunks instead of casting into metadata, the sidebar props docs describe the checklist/navigator recipe, and the transform docs state the derived-at-boundary contract.

Testing

• New colocated src/core/hunkSummary.test.ts (real Pierre-parsed hunks plus synthesized-hunk edge cases).
• New toReadOnlyFileViews coverage in src/extensions/events.test.ts: derivation, frozen/cached identity, metadata-authoritative replacement, shared empty list for binary/skipped files.
• bun run typecheck, bun run lint, bun run check:pack (typechecks all 20 docs examples for nodenext + bundler consumers), full src/ suite (1583 pass), test/cli + test/session, and the extensions PTY integration tests all green.

Changeset: minor for hunkdiff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01M7EZpzieiVPdj6LZn4oBYJ

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ready	Preview	Jul 28, 2026 3:47pm

[greptile-apps]

Greptile Summary

Adds immutable public hunk summaries to extension-facing file views and unifies their derivation with the session review surface.

• Introduces and exports the ExtensionDiffHunk public API type.
• Derives cached hunk headers, indices, and inclusive line ranges from authoritative diff metadata.
• Exposes summaries through events, sidebar props, and command selections.
• Updates extension documentation, changeset metadata, and focused tests.

Confidence Score: 5/5

The pull request appears safe to merge with no actionable defects identified.

The new extension-facing summaries are derived from the same metadata and range helpers used by existing review surfaces, remain immutable at the public boundary, and preserve optional-range handling for legally synthesized hunks.

Important Files Changed

Filename	Overview
src/core/hunkSummary.ts	Adds a shared hunk-summary derivation that safely omits ranges for synthesized hunks lacking numeric fields.
src/extensions/events.ts	Derives, freezes, caches, and attaches metadata-authoritative hunk summaries to extension-facing file views.
src/extension-api/types.ts	Defines the public hunk-summary contract and documents its relationship to selection and navigation.
src/hunk-session/sessionRegistration.ts	Reuses the shared summary helper for session review exports without changing their established wire shape.
src/core/hunkSummary.test.ts	Covers parsed hunks and transform-synthesized hunks with missing numeric metadata.
src/extensions/events.test.ts	Covers summary derivation, immutability, cache identity, stale-field replacement, and empty metadata cases.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  M[Parsed file metadata] --> S[summarizeHunk]
  S --> C[Cached frozen summaries]
  C --> E[Extension event payloads]
  C --> B[Sidebar file props]
  C --> X[Command selection]
  S --> R[Session review export]

Loading

_{Reviews (1): Last reviewed commit: "feat(extensions): expose public hunk sum..." | Re-trigger Greptile}