[colbymchenry]

Summary

codegraph indexed a Liquid variable declared with {% assign %} but not one declared with {% capture %}, Liquid's other way to declare a variable. A captured variable could not be found, and codegraph_explore reported its name as not in the index. This PR indexes capture declarations exactly as assign ones are indexed.

This PR is code only. The README and docs-site wording that the issue also asks about is in PR #2815, which is held for Colby's review, so this PR does not close the issue.

Refs #2498

Verdict: a bug, not a feature

The reporter calls #2498 "a feature/documentation request", so this is a judgement call, and the reasoning is here so it can be overridden:

• The extractor already indexes Liquid variable declarations: assign, in both spellings and comment-aware. Both language tables say "Full support" for Liquid.
• capture declares a variable in the same namespace. Missing it is an omission in an existing capability, not a new kind of behaviour: no new node kind, edge or tool.
• On main, codegraph explore captured bare_capture tells the agent that bare_capture is "Not in the index … If it is defined in this project, the file defining it is not indexed", which points it the wrong way.
• The issue's own "separate follow-ups" are features and stay out: Jekyll include rules, embedded JS/CSS, assets/blocks, settings and translations.

Root cause

extractAssignments ran findTagOccurrences('assign', …) and nothing read capture. Reproduced on efb091e with the issue's example, plus whitespace control, a quoted name, a {% liquid %} block and a commented-out control: both assigns became variables, and none of the four captures did.

Fix

src/extraction/liquid-extractor.ts:

• extractAssignments also reads capture through the same findTagOccurrences scanner, so both spellings (braced, and as a line of a {% liquid %} tag) and the comment/raw rule apply unchanged.
• The name rule is word characters, as for assign. The name may be in single or double quotes: Shopify's runtime reads {% capture 'title' %} as title, as the lax parser in Shopify/theme-tools documents. It must end at whitespace or the tag's end, -%} included.
• A name that goes on with - or ., which the assign rule doesn't read either, gets no node rather than a cut-short one.
• Captures are read after assigns. Node ids are keyed by file, kind, name and line, so an assign keeps its id when a capture of the same name shares its line.
• One addVariable helper builds the node and its contains edge for both. It computes the declaration's column once, where the old assign code computed it three times, and each computation split the whole file.

Validation

Tests: 13 new tests in __tests__/extraction.test.ts.

• 11 fail with main's extractor and pass with the fix:
  • 8 declaration forms: braced, whitespace-trimmed, tight -%}, single- and double-quoted, {% liquid %} lines with LF and CRLF, and a quoted {% liquid %} line;
  • an assign and two captures of one name on one line (distinct ids, and the assign keeps its own);
  • tags inside a capture body, which are still read;
  • an index-level test that searchNodes finds captured variables in a non-theme _includes/ folder.
• 2 guards pass on both:
  • no capture is read from comment or raw regions, inline # comments, prose, a nameless tag, or a tag inside a string;
  • a hyphenated or dotted name is never cut short.
• Red/green on the committed tree: 42 passed and 11 failed with efb091e's liquid-extractor.ts put back; 53 passed with the fix.

Full suite on f39fd69 (CODEGRAPH_KERNEL_EXPECT=1 npx vitest run --maxWorkers=4 --minWorkers=1): 727 files passed and 6 skipped; 8,700 tests passed, 82 skipped and 0 failed, in 660 s.

• f39fd69 was this PR's previous head. Its tree differs from the current head only in README.md and site/src/content/docs/reference/languages.md, which are now back to main's exact text, and one sentence about those tables, now dropped from the CHANGELOG bullet.
• On the current head: npm run build passes, the Liquid tests pass (53), and the 5 test files that mention the README pass (explore-long-query, frontload-hook, security, ui-search-model, worktree-detection: 161 passed, 2 POSIX-only skips).

A/B on efb091e, with each arm built from its own checkout. The repos and controls are the same as for #2812.

Repo (sha)	Files	Captures found by a separate scan	New variable nodes	Checked against source
Shopify/skeleton-theme (a7a655e7)	26	0	0	byte-identical
Shopify/dawn (05222537)	143	36	36	36 right
Shopify/horizon (dfad90d8)	381	192	192	192 right
ChumsInc/chums-impulse-dev (4fd6f08e)	219	90	90	90 right
agencecinq/cinquante-et-un (ecb0035a)	182	25	25	25 right
noclocks/shopify-devstore-theme (e1747695)	178	27	27	27 right
panoply/syncify (98d75fd0)	467	25	25	25 right
Shopify/theme-tools (20f8edfc)	1206	49	49	49 right
expressjs/express (0dee2c52), control	148		0	byte-identical
psf/requests (611c6162), control	49		0	byte-identical

• The only change is one variable node per capture, each with one contains edge.
  • 444 in all: 383 braced and 61 inside {% liquid %} tags.
  • Nothing is removed or moved, no unresolved ref changes, and no node present on both arms changed its id.
• A script checked every new node against the source text: it is a Liquid variable at the start of a capture tag naming it (a tag split over lines included), contained by its file node, with no other edge. 444 right, 0 wrong.
• In these themes, every capture and assign name is a plain word. None are quoted, hyphenated or dotted, so the quoted and cut-short rules are covered by the tests.
• The main arm's theme dumps are byte-identical to ones indexed from the same tree in the other checkout (the post-rebase run for fix(liquid): editor-saved Shopify JSON and {% sections %} groups link their sections #2812).

Cost:

• The extractor is faster with the fix. A microbenchmark over 1,386 Liquid files (8 MB), 15 runs in each of 3 interleaved rounds, gave per-round medians of 443–465 ms on main and 316–387 ms with the fix.
• Counting calls shows why: whole-file getLineStart scans fall from 29,807 to 20,671. That is 4,790 assigns going from three scans to one, plus one scan for each of the 444 captures.
• Index wall time, median of 3 interleaved runs:

Repo	main (ms)	fix (ms)
horizon	2975	2935
chums-impulse-dev	2404	2311
syncify	4329	3867
theme-tools	8405	8108
express (control, byte-identical)	2427	2417
requests (control, byte-identical)	2006	1942

Other agents' jobs were running on the machine, so single runs spread widely, and the medians are within noise. The controls index identical graphs on both arms.

Kernel parity: not applicable, because the kernel has no Liquid code.

Rebase:

• The A/B ran on efb091e. The branch is now rebased onto 68fcf2f, which brings only PR fix(js,ts): static and instance methods override only their own kind #2813 (JS/TS static and instance overrides). That PR changes the TS/JS kernel, so the kernel was rebuilt.
• On the rebased build the Liquid tests pass, and re-indexing the 8 theme repos changes no Liquid or JSON line.
• 4 themes are byte-identical to the pre-rebase fix arm. The other 4 differ only in PR fix(js,ts): static and instance methods override only their own kind #2813's own changes: the is_static flag on JavaScript methods (dawn 30, horizon 26, shopify-devstore-theme 14), and one synthesized TypeScript interface-impl call in syncify.

Contributor PR

PR #2504 by @Puma7 was read for guidance; this branch does not build on it.

• Kept from it: capture read through the shared tag scanner, quoted names, and the negative cases (comment/raw, inline # comments, a nameless tag).
• Changed:
  • -/. names get no node, for parity with the assign rule, where feat(liquid): index capture variables and document dialect coverage #2504 accepts hyphenated names;
  • captures are read after assigns, so existing ids never move;
  • the docs wording is in PR docs(liquid): say what Liquid support covers #2815, two table rows only.
• The CHANGELOG credits @Puma7 for the report and the pull request.

Left out

• README and docs-site wording: this is PR docs(liquid): say what Liquid support covers #2815, held for Colby's review.
• Hyphenated and dotted names ({% capture my-var %}, {% capture a.b %}): Liquid allows them, but the assign rule doesn't read them either, and none of the 8 theme repos uses one. Widening both rules together is a separate change.
• Variable-use edges: a captured variable, like an assigned one, is a searchable declaration. Its uses are not linked.
• increment / decrement: these declare counters in a separate namespace. They are not part of this report.
• The issue's follow-ups: Jekyll include and file-extension rules, Liquid in .html/.md, embedded JS/CSS, assets and theme blocks, settings and translation consumers. They need host-aware work and are features.

🤖 Generated with Claude Code