Skip to main content

Issue preview cards

Comments reference the tracker all the time — // fixes #123, // see GH-42, // supersedes https://github.com/mcclowes/kiln/pull/552. kiln reads those references out of your comments and renders a small preview card in the margin, right beside the code that mentions them.

The card links straight to the issue or PR. Where the GitHub CLI (gh) can answer, it goes further and fills in the title and an open/closed/merged dot, so you can tell whether #123 is still live without leaving the editor.

What gets matched​

The scanner only looks inside comments — it rides the highlighter's comment ranges, the same seam the TODO tags and @mentions use — so a # in a string, a Swift macro like #Preview, or an { HTML entity is never mistaken for an issue. Three shapes are recognised:

  • #123 — a bare number, resolved against the workspace's own repo.
  • GH-123 / gh-123 — the same, case-insensitive.
  • A full github.com/owner/repo/issues/123 or /pull/123 URL — which can point at any repo, not just this one, and tells an issue from a PR by its path.

The rich card​

The title and state come from one gh api repos/{owner}/{repo}/issues/N call — the issues API answers for pull requests too, so a single lookup covers both. A merged PR shows a plum dot, a closed issue or PR shows rust, anything open shows sage.

The lookup is best-effort and cached. The first card for a given reference shells out; the rest read the cache, including the negative result — so a repo with no GitHub remote, a machine without gh, or an offline laptop falls back to a plain #123 ↗ link and never retries on every render. Concurrent cards for the same number share one gh run.

The scanner (IssueRefs) and the preview parse (IssuePreview) are pure and unit-tested; the live fetch and cache live in IssuePreviewStore, and the card itself is IssueRefCard in the editor's margin.