feat: add R language support (in five phases)

[kapelner]

Summary

Adds R language support to graft's Tier-1 extraction. tree-sitter-r (npm:@davisvaughan/tree-sitter-r — the real, maintained package; tree-sitter-r on npm itself is an unrelated squatted placeholder) parses .R/.r files.

R's class systems (S3/S4/R6) are library convention, not grammar syntax, unlike every other language graft supports — this is the first "pattern-match known call idioms → sometimes a class/method" language here, rather than "one grammar construct → one kind." Shipped in five incremental phases, each independently tested and (from Phase 2 on) verified against a real R6-heavy production package found while dogfooding:

Phase 1 — flat function extraction. Every name <- function(...) {} / name = function(...) {} / function(...) {} -> name becomes a flat function node — the same altitude Python support already operates at for module-level defs. function_definition carries no name field at all in this grammar, so the identifier always comes from an enclosing assignment. Right-assign (->/->>) needed its own logic rather than mirroring left-assign: its low operator precedence means it's absorbed into the function definition's own body field instead of the function sitting inside an outer binary_operator — confirmed by dumping the real AST, not assumed. library()/require()/source() calls are recognized as imports by pattern-matching the callee name (R has no import statement at the grammar level).

Phase 2 — S3/S4/R6 class awareness. R6 (Foo <- R6::R6Class("Foo", public = list(...), private = list(...))) gets full support: the class node, public =/private =/active = list entries as methods (private ones unexported), inherit = heritage, and self$/private$ calls resolving directly to the enclosing class the same way Python's self/TS's this already do. S4 (setClass()/setMethod()) become a class and an owned method respectively, with contains = heritage; setGeneric() isn't specially extracted. S3 (generic.Class <- function() {}) only becomes a method when generic is a known generic (registered locally via UseMethod(), or a small curated set of common base-R generics) — read.csv/data.frame are correctly NOT treated as S3 dispatch.

Phase 3 — roxygen @export visibility + R6 super$ dispatch. A #' @export tag marks a definition exported regardless of naming convention; a roxygen block with no @export tag is instead treated as explicit "not exported" (matching roxygen's own NAMESPACE-generation semantics). super$method() now resolves directly to the parent class's method via the already-extracted inherit = heritage, rather than risking a match on the current class's own same-named override.

Phase 4 — untyped R6 composition calls. private$other_obj$method() (one class holding another as a field) is a common real pattern that a field-type-binding table (the "field <- SomeClass$new()" pattern other languages use) turns out not to help with in practice — real-world field assignment is usually constructor-parameter pass-through or dynamic do.call() dispatch, neither of which names a class anywhere the AST can see. The actual fix: bare-name call resolution was silently restricted to "function"-kind nodes only, so since R6 methods are always kind "method", every such call was unconditionally unresolvable. Now allows a "method" match too, using the same "unique match resolves, ambiguous match safely drops" logic already used everywhere else.

Phase 5 — plain-list mixin/extension bundles. Found dogfooding a full rebuild of a real R6-heavy corpus: Foo <- list(public = list(...), private = list(...)), NOT wrapped in R6::R6Class(...) at all, is a real, deliberate convention for splicing a shared method bundle into multiple classes (public = c(Foo$public, list(...))) rather than using inherit =. Now recognized as a class-like container whenever the list has a public =/private = entry — precise enough that ordinary data/config lists are never mistaken for one.

Known limitations (documented in code + CHANGELOG)

• S3 generics registered in a different file than their methods aren't recognized (no whole-repo pass exists — same per-file limitation Go/C++ bindings already accept).
• S4's setMethod() only handles single-class dispatch, not signature()-based multiple dispatch.
• R6 active bindings are treated as ordinary (exported) methods, no distinction from regular ones.
• No general R6 field-type-binding table (Phase 4 addresses the highest-value case of this without one).

Test plan

• tsc --noEmit clean
• npm run build clean
• 5 dedicated test files (test/graph-r*.test.ts) covering all phases — Phase 1 flat extraction, Phase 2 S3/S4/R6, Phase 3 roxygen/super$, Phase 4 composition-call resolution, Phase 5 mixin bundles
• Full existing test suite green, no regressions
• Verified against a real ~180-file R6-heavy production package (--no-reuse forced full rebuild, not cache-replayed): confirmed real composition calls resolving (e.g. private$des_obj$get_n() → 13 real resolved call sites), roxygen @export/@keywords internal correctly driving visibility, and — after Phase 5 — zero unexplained empty files remaining across the corpus

🤖 Generated with Claude Code