Skip to content

feat(crystal): add Crystal language support - #3376

Open
n-rodriguez wants to merge 1 commit into
colbymchenry:mainfrom
n-rodriguez:feat/crystal-language-support
Open

n-rodriguez wants to merge 1 commit into
colbymchenry:mainfrom
n-rodriguez:feat/crystal-language-support

Conversation

@n-rodriguez

Copy link
Copy Markdown

Adds Crystal (.cr) to the extraction pipeline. Supersedes #3082 and #1458, rebased on today's main. #3082 could not be reopened: its head repository, my fork, was deleted by mistake. The code is the commit of #3082 unchanged; only the changelog entry (now under the new [Unreleased], after 1.6.3) and the README conflict moved.

Changes since #1458

  • The operator guard is Crystal-only. The call branch Crystal shares with Ruby now returns early on an operator method only when this.language === 'crystal'. Ruby's behaviour is unchanged: an explicit price.+(tax) still records its price.+ reference, and a new Ruby test pins that.
  • Relative require resolves to a file. require "./models/user" links to models/user.cr, or else to models/user/user.cr. Those are the two lookups the Crystal reference documents for the ./ form.
  • Crystal has its own code family in the name matcher, so a bare Crystal call can no longer name-match a same-named Ruby or TypeScript method in a polyglot repo.
  • record types are extracted. record Point, x : Int32, y : Int32 do … end becomes a struct with one property per field, and the defs in its block become the struct's methods.
  • Smaller extraction fixes:
    • A typed local (buffer : Int32 = 5) counts as a local, not as a parenthesis-less call.
    • A call on a constructed generic (Box(Int32).new.run) is named new Box().run.
    • A file-scope include is a reference, not a file "implementing" a module.
  • The changelog entry now sits under [Unreleased], and the site's languages page lists Crystal.

Grammar: source, version, license

No npm package or tree-sitter-wasms build of a Crystal grammar exists, so the .wasm is vendored:

  • Source: https://github.com/crystal-lang-tools/tree-sitter-crystal
  • Revision: 50ca9e6fcfb16a2cbcad59203cfd8ad650e25c49 (2025-10-12)
  • License: MIT
  • Build: tree-sitter build --wasm with tree-sitter-cli 0.25.10, run on the repository's checked-in parser.c (no tree-sitter generate). The result is ABI 15.
  • Vendored file: src/extraction/wasm/tree-sitter-crystal.wasm, sha256 502c25dafdbf047be120890253149903bd6a41a02a3d434ffad445ffbaf5f6fa

To rebuild it yourself:

git clone https://github.com/crystal-lang-tools/tree-sitter-crystal
cd tree-sitter-crystal
git checkout 50ca9e6fcfb16a2cbcad59203cfd8ad650e25c49
npx -p tree-sitter-cli@0.25.10 tree-sitter build --wasm

The same provenance is written in the grammar comment in src/extraction/grammars.ts. Crystal is not kernel-routed, so this file is the only grammar artifact for the language.

Core changes

All of them are gated on Crystal:

  • In src/extraction/tree-sitter.ts, the supertype is read from Crystal's superclass field.
  • The Ruby call path also serves Crystal, with the Crystal-only operator guard, and the generic receivers it handles (Box(Int32).new) name the bare type.
  • In src/resolution/import-resolver.ts, a crystal extension entry, the x/x.cr lookup, and a branch in resolveViaImport resolve relative requires to their file.
  • In src/resolution/name-matcher.ts, crystal is added to CODE_FAMILY.

Validation

  • 30 Crystal tests plus 1 Ruby test, in __tests__/extraction.test.ts. Each new one was seen failing before its fix.
  • Full suite on macOS: 10,791 passed and 30 failed. The 30 failures, all in installer-targets.test.ts (the local installs of the JSON mcpServers agents), fail identically on main on this machine and do not involve this change.
  • tsc --noEmit is clean.

Known gaps, unchanged from #1458

  • Macros are not expanded, so Kemal's {% for method in HTTP_METHODS %} verb DSL is absent from the graph.
  • require "./dir/*" and require "./dir/**" wildcards do not resolve to files.
  • There is no Crystal framework resolver and no dynamic-dispatch synthesizer.

🤖 Generated with Claude Code

- src/extraction/wasm/tree-sitter-crystal.wasm: vendored grammar built from
  crystal-lang-tools/tree-sitter-crystal @ 50ca9e6 (MIT) with tree-sitter-cli
  0.25.10 from the repo's checked-in parser.c, ABI 15. No npm or
  tree-sitter-wasms build of this grammar exists.
- src/extraction/languages/crystal.ts: new extractor — modules, classes,
  structs, `record` types (a struct with a property per field, the block's
  defs as its methods), enums, lib/fun C bindings, macros,
  getter/setter/property accessor macros, instance and class variables, type
  aliases, require imports, include/extend mixin edges (a file-scope include
  is a reference, not an implementation), and parenthesis-less bare calls (a
  bare identifier that names a parameter, a proc parameter, a `rescue`
  variable or a local in scope, typed locals included, is a value, not a
  call; one used as a value — `r = compute`, `return compute` — is a call).
  Generic types are named without their parameters (`class Box(T)` → `Box`),
  accessor macros under `private` are private, a bodiless struct is kept
  (Crystal has no forward declarations), and return types skip the `:`
  token the grammar tags with the same field. Initializers — accessor
  defaults, type-scope constants, instance and class variables — are walked
  with the declared symbol as the caller.
  File-scope assignments declare only their targets and walk their value, so a
  top-level `server = HTTP::Server.new do … end` keeps its calls, while an
  attribute or index assignment declares nothing. Block-local
  assignments are skipped without swallowing the subtree, since file-scope
  blocks (Kemal routes, specs) carry real call flow. The enclosing kind is
  looked up through an id index rather than a scan of the extracted nodes.
- src/extraction/tree-sitter.ts: two language-gated core touches — Crystal
  carries its supertype on a `superclass` field the generic type-matched loop
  never sees, and its `call` node has the same receiver/method shape Ruby
  already special-cases, with a Crystal-only guard because this grammar also
  parses infix operators as calls (Ruby keeps its explicit `price.+(tax)`).
  A generic receiver (`Box(Int32).new`, `Box(Int32).new.run`) names the bare
  type, matching how the generic declaration is named.
- src/resolution/import-resolver.ts: a relative `require "./x"` resolves to
  the file the compiler loads, `x.cr` or else `x/x.cr`.
- src/resolution/name-matcher.ts: Crystal gets its own code family, so a bare
  Crystal call never name-matches a method in another language.
- src/types.ts, src/extraction/grammars.ts, src/extraction/languages/index.ts:
  register the language, the `.cr` extension, the display name and the grammar.
- __tests__/extraction.test.ts: detection plus twenty-nine extraction and
  cross-file resolution tests, and a Ruby test that an explicit operator
  method call keeps its reference.
- README.md, CHANGELOG.md, site/src/content/docs/reference/languages.md:
  document the new language and add its tile to the language grid.
- assets/languages/crystal.svg, assets/generate-language-tiles.py: Crystal
  tile generated by the tile script from the simple-icons mark.
- .claude/skills/agent-eval/corpus.json: kemal, lavinmq and crystal-lang/crystal
  as the small, medium and large evaluation repos.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@n-rodriguez

Copy link
Copy Markdown
Author

ping @Sija

@Sija

Sija commented Nov 18, 2026

Copy link
Copy Markdown

@colbymchenry Hi, this PR resolves your #1458 (comment). Any chance to get this merged? Would be a big help to get this in before merge conflicts pop up again.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants