codegraph/docs/design/r-kernel-port-checklist.md

# R kernel port (R7b batch 4) — the bug-for-bug checklist

**Status: SURVEY COMPLETE (2026-07-20)** — no walker exists yet. Survey basis:
every TS-side branch a `.R`/`.r` file exercises, with file:line anchors as of
**`45a53eb`** (HEAD at survey time, clean main). Every grammar-shape claim was
probed against the production vendored wasm
(`src/extraction/wasm/tree-sitter-r.wasm`, r-lib v1.2.0), and every
extraction-behavior claim was pinned against the real `dist/` extractor
(`extract-*.txt` ground-truth dumps in the session scratchpad `svy-r/` —
see §Probe artifacts) — not derived from code reading alone. Read WITH
`docs/design/rust-kernel-migration-plan.md` (§0a recipe, §2 boundary, §4
tracker row "r", §5 gates) and the format precedents
(`kotlin-kernel-port-checklist.md`, `swift-kernel-port-checklist.md`,
`ruby-kernel-port-checklist.md`).

**Blocking findings: none — and this is the LIGHTEST-shared-surface port so
far, but the HEAVIEST hook port.** Three structural facts shape everything:

1. **R has no declaration syntax** — `languages/r.ts` (310 lines) works
   ENTIRELY through the `visitNode` hook. Every type list except
   `callTypes: ['call']` is EMPTY, so the generic dispatch ladder, extract-
   Function/Method/Class/Enum/Interface/Variable/Field/Property/Import/
   TypeAlias, `visitFunctionBody`, docstrings, decorators, inheritance,
   instantiation — the entire shared extraction machine — **never runs**.
   The walker is: file node + a faithful transcription of the hook + the
   generic `extractCall` + pre-order recursion. Nothing else.
2. **R is in NONE of the cross-cutting language sets**: not in
   `VALUE_REF_LANGS` (tree-sitter.ts:401), not in `STATIC_MEMBER_LANGS`
   (:345-347), not in `TYPE_ANNOTATION_LANGUAGES` (:5752-5754), not in
   `FN_REF_SPECS` (function-ref.ts:376-398 — no `r` key). Four whole
   machineries (value-reference edges + the shadow prune, static-member
   reads, type-annotation refs, function-as-value capture) are **dead** and
   must STAY dead — the walker needs cheap early-outs that emit exactly
   nothing.
3. **Grammar prep is csharp-style: crate pin, zero grammar change.** The
   vendored wasm IS r-lib v1.2.0 and the crates.io `tree-sitter-r = "=1.2.0"`
   tarball is sha-identical on BOTH generated artifacts (§Grammar prep). No
   bump gate, no wasm re-vendor, no C vendoring.

Error incidence on the gate repos is **~0%** (ruby-class): any deferral on an
R sweep is a walker-bug signal, not grammar reality (§Error incidence).

## Grammar prep (crate pin — NO grammar change)

r IS already in `VENDORED_WASM_LANGS` (grammars.ts:292) and maps
`r: 'tree-sitter-r.wasm'` (grammars.ts:40). `.r` → `r` at EXTENSION_MAP
(grammars.ts:113); `detectLanguage` lowercases the extension (grammars.ts:473)
so **`.R` (the dominant real-world casing) resolves identically** — probed:
`extract.cjs smoke.R` → `language=r`. No content sniffing, no dialect.
(`.Rmd`/`.qmd`/`.Rprofile` are not in EXTENSION_MAP → `unknown` → never
extracted; out of scope.)

- **Provenance (verified, batch-4 grammar probe + this survey):** the
  production wasm is **r-lib/tree-sitter-r v1.2.0** — ABI 14, 2,072 states,
  135 node types (134 symbols + 1 alias), **20 fields** — positionally
  identical to the tag's `src/parser.c`. The crates.io **`tree-sitter-r`
  1.2.0** tarball ships BOTH generated artifacts sha-identical to the tag
  (R has an external scanner):
  - `src/parser.c` `622165734714c6e81f70d99d522d78cf98915fdf2b1032f8bb33e775a0b971c0`
  - `src/scanner.c` `1209d1107616b470a4292c18d57b56b44990c39792acf7af6ccada0af563dbff`
  Crate file list: `bindings/rust/{build.rs,lib.rs}`, `grammar.js`,
  `queries/{highlights,locals,tags}.scm`, `src/{parser.c,scanner.c,
  grammar.json,node-types.json}`, `src/tree_sitter/{alloc,array,parser}.h`,
  `tree-sitter.json`, Cargo metadata.
- **Crate usability (kotlin-lesson check): USABLE.** `[dependencies]` is
  `tree-sitter-language = "0.1"` only (`tree-sitter` 0.24.7 is a DEV-dep,
  `cc` 1.1.22 a build-dep) — no pin conflict with the kernel's tree-sitter
  0.25. Port route: **`tree-sitter-r = "=1.2.0"` in codegraph-kernel's
  Cargo.toml** (csharp-style), `langs.rs` `"r" => tree_sitter_r::LANGUAGE`,
  `LANGUAGES` 15→16.
- **v1.3.0 exists and is NOT this batch** (future accuracy PR only):
  return-as-identifier (changes the `return` callee quirk's CST shape —
  §extractCall), raw-string lexing split, and the **CRLF comment-node fix**
  (v1.2.0 comment nodes INCLUDE the trailing `\r` — probed:
  `"#' roxy for cf\r"` spans cols 0-15 on a CRLF file, `cst.cjs
  crlf-crlf.R`). Extraction-invisible today (R reads no comments — §Docstrings)
  but a bump would be a behavior change on three axes; treat it like any
  grammar bump with its own gate, never fold it into the walker PR.
- **Field table (1-based, all 20):** alternative, argument, arguments, body,
  close, condition, consequence, content, default, function, lhs, name, open,
  operator, parameter, parameters, rhs, sequence, value, variable
  (`table-dump.out`). **r.ts reads 9 of them**: `function`, `arguments`,
  `value`, `name`, `operator`, `lhs`, `rhs`, `parameters`, `body` — all via
  `childForFieldName` semantics (getChildByField, tree-sitter-helpers).
  Unlike kotlin's zero-field world, R's field lookups are LIVE — the walker
  uses real field IDs.
- **Named kinds that matter** (135 total, `table-dump.out`): `program`,
  `binary_operator`, `unary_operator`, `call`, `subset` (`x[i]`), `subset2`
  (`x[[i]]`), `arguments` (three positional kind ids 97/98/99, aliased to one
  name — call/`[`/`[[` argument lists), `argument`, `function_definition`
  (covers BOTH `function(x)` and the `\(x)` lambda — probed), `parameters`,
  `parameter`, `identifier`, `string`, `string_content`, `escape_sequence`,
  `namespace_operator` (`pkg::fn`, `pkg:::fn`), `extract_operator` (`x$y`
  AND `x@y`), `braced_expression`, `parenthesized_expression`,
  `if_statement`, `for_statement`, `while_statement`, `repeat_statement`,
  `comment`, `comma`, literals (`integer`, `float`, `complex`, `true`,
  `false`, `null`, `inf`, `nan`, `na`, `dots`, `dot_dot_i`), and **`return`,
  `next`, `break` as NAMED nodes** (v1.2.0 — the source of the `calls
  "return"` quirk below).
- `__tests__/kernel-grammar-parity.test.ts:39` `GRAMMAR_LANGUAGES += 'r'` —
  the id-by-id ABI/kind/field-table compare against the vendored wasm proves
  crate and wasm are the same revision.

## Architecture decisions

1. **No preParse, no POST_PASSES.** `rExtractor` has no `preParse` hook
   (languages/r.ts — whole file) → `preParsedSource` (kernel/index.ts:109) is
   identity; no `POST_PASSES` entry → `tryKernelExtractRaw` stays eligible
   (raw buffers-to-store transport on the bulk path).
2. **No framework resolver touches R.** Grep of `src/resolution/` finds `'r'`
   only in name-matcher.ts (two RESOLUTION-side branches — §Frameworks); no
   `frameworks/*.ts` lists r in `languages:` → parse-worker's
   framework-force-to-decoded-path never fires for R. All parity repos ride
   the raw path.
3. **One walker module** (suggest `codegraph-kernel/src/rlang.rs` — `r.rs`
   works too; no crate-name collision since the dep is `tree-sitter-r`),
   registered in langs.rs; per-file `has_error()` → `defer:` like every
   walker. **No existing walker is a close crib** — the nearest are the
   hook-branch parts of kotlin.rs/swift.rs, but R's walker is structurally
   simpler: ONE visit function implementing §The hook, calling extract_call
   for unconsumed `call` nodes, recursing namedChildren otherwise. There is
   no class-stack (`pushScope` is explicit in the hook), no
   isInsideClassLikeNode consult (nothing in the ladder needs it), no
   receiver machinery, no modifiers/visibility/async/static (§Extractor
   config — every hook absent).
4. **Deferral expectations: ~0%.** AnomalyDetection 0/11, dplyr 0/195,
   ggplot2 0/357, shiny 1/275 (0.36% — one moustache-template pseudo-R file,
   `inst/app_template/app.R`, `{{ … }}` placeholders; errors on BOTH arms).
   Keep the sweep default `--max-deferral 0.1`; **any deferral count above
   ~1 on an R sweep is a walker-bug signal** (ruby precedent, not swift's).
   The error battery (45 shapes, `err-battery.out`) found **NO phantom-error
   class**: trailing commas in calls/lists, `\(x)` lambdas, underscore pipe
   `f(y = _)`, raw strings `r"(...)"`/`r"#(...)#"`, BOM, CRLF, `x<-1`
   spacing, empty file — all parse clean; `hasError` was true only for
   genuinely-broken source (`x <-` MISSING node, stray `)` ERROR nodes).
   Trust `has_error()` exactly as elsewhere.
5. **REF_FLAG_FILE_PATH (wire v2 slot) is NOT needed.** No R ref carries
   `filePath` — the hook's imports/extends refs pass only {fromNodeId,
   referenceName, referenceKind, line, column} (r.ts:198-204, 122-129,
   138-145), and extractCall's calls refs likewise (tree-sitter.ts:4572-4580).
   Verified across every ground-truth dump — zero refs printed a filePath.
   `source("helpers.R")` resolves file-linking on the RESOLUTION side from
   the ref's `imports` kind + name text (`helpers.R`), not from a filePath
   field.
6. **Four dead machineries — reproduce the nothing.** (a) value-reference
   edges: capture may run TS-side but `flushValueRefs` exits at the language
   gate (tree-sitter.ts:784) → **zero `references` edges with
   metadata.valueRef, ever** — the assignment shadow-prune (:803+) is
   unreachable for R despite R being all-assignments; (b) static-member
   reads: gate at :4751 (`STATIC_MEMBER_LANGS`) → nothing (R's
   `extract_operator`/`namespace_operator` aren't in MEMBER_ACCESS_TYPES:323
   anyway); (c) type annotations: gates at :1285/:5790/:6075 → nothing;
   (d) function-as-value: `fnRefSpec` undefined → `maybeCaptureFnRefs`
   (:585-595) and `scanFnRefSubtree` (:603-620) are no-ops → **zero
   `function_ref` refs** — the post-hook `scanFnRefSubtree(node, 0)` at :951
   does nothing for R. Also: **zero `instantiates`** (no R kind in
   INSTANTIATION_KINDS:354-361 — `new("Patient")`/`Cls$new()` are plain
   calls), **zero `decorates`**, **zero docstrings** (§Docstrings), **zero
   `namespace` nodes** (no `packageTypes` → extractFilePackage:1397-1399
   returns null), **zero import nodes from the generic path**
   (importTypes=[] → :1209 never matches — R imports come ONLY from the
   hook).

## Extractor config (languages/r.ts — 310 lines, read it whole)

Types: `functionTypes=[]`, `classTypes=[]`, `methodTypes=[]`,
`interfaceTypes=[]`, `structTypes=[]`, `enumTypes=[]`, `typeAliasTypes=[]`,
`importTypes=[]`, **`callTypes=['call']`**, `variableTypes=[]`.
`nameField='name'`, `bodyField='body'`, `paramsField='parameters'` — all
three are **DEAD** (read only by extractName/extractFunction-family and
createNode's `resolveBody?.()` endLine extension, none of which run for R:
no `resolveBody` hook, and function/method nodes are hook-created, so
createNode:1329-1334's extension is skipped by the optional-chain on the
absent hook).

Hooks ABSENT (the walker must NOT invent them): `preParse`, `resolveName`,
`resolveBody`, `classifyClassNode`, `classifyMethodNode`, `getVisibility`,
`isStatic`, `isAsync`, `isConst`, `isExported`, `extractModifiers`,
`extractImport`, `extractPackage`/`packageTypes`, `getReceiverType`,
`extractPropertyName`, `propertyTypes`, `fieldTypes`,
`extraClassNodeTypes`, `synthesizeMembers`, `skipBodilessClass`,
`methodsAreTopLevel`, `resolveTypeAliasKind`, `getReturnType`. Consequences
on every R node: **no visibility, no isStatic, no isAsync, no returnType,
no decorators, no docstring, no isExported** (except the file node's literal
`false`). The ONLY extras ever set: `signature` (functions/methods/imports —
see per-construct rules), and nothing else (`{}` for classes/variables/
constants).

Module-level constants (transcribe exactly):

- `ASSIGN_LEFT = {'<-', '<<-', '='}`; `ASSIGN_RIGHT = {'->', '->>'}`
  (matched against the `operator` FIELD child's TEXT, r.ts:255).
- `IMPORT_FNS = {'library', 'require', 'requireNamespace', 'loadNamespace'}`
  (+ `'source'` checked alongside, r.ts:189).
- `CLASS_FNS = {'setClass', 'setRefClass', 'R6Class', 'ggproto'}`.
- `GENERIC_FNS = {'setGeneric', 'setMethod'}`.
- `CONSTANT_NAME = /^[A-Z][A-Z0-9._]*$/` — ALL-CAPS/dotted-caps → `constant`,
  else `variable`. Anchored full-match; `A.CONST` and `RIGHT.CONST` qualify,
  `Gen`/`dotted.var` don't (probed).

Helper semantics (r.ts:46-98, the hook building blocks):

- **calleeName(call)**: `function` field → `identifier` → its text;
  `namespace_operator` → its `rhs` field's text (**so `methods::setClass`,
  `R6::R6Class`, `base::library` all trigger their special branches** —
  pinned, `extract-classes2.txt`/`extract-imports.txt`); anything else
  (`extract_operator`, `subset2`, `string`, `call`, `return`…) → null.
- **firstArgValue(call)**: the FIRST namedChild of `arguments` whose type is
  `argument`, → its `value` field. **Named arguments are NOT skipped**:
  `library(help = docpkg)` → the first argument IS `help = docpkg` → value
  `docpkg` → **import node "docpkg"** (pinned — bug, PRESERVE). Note the
  `arguments` node's namedChildren include `comment` nodes in principle —
  the type filter skips them.
- **literalOrIdentifier(node)**: `identifier` → text (INCLUDING backticks if
  present); `string` → first `string_content` child's text, **`''` when the
  string is empty** (`library("")` → `''` → falsy → consumed silently —
  pinned); anything else (call, namespace_operator, TRUE, NULL…) → null.
- **emitMethodArg(entry)**: entry is an `argument` node; needs `name` field
  present AND `value` field of type `function_definition`, else returns
  silently (a positional `list(function() 1)` entry or `items = NULL` field
  emits NOTHING — pinned). Creates
  `createNode('method', nameText, entry, { signature: paramsText | undefined })`
  — **positioned at the ARGUMENT node** (`deposit = function(x)…` — L13 C4
  in `extract-classes.txt`), signature = the `parameters` node's raw text
  (`"(x)"`). Then `pushScope(method.id)`; **`ctx.visitNode(body)`** (the
  full hook-aware walker — NOT visitFunctionBody); `popScope()`.
- **extractClassMembers(classCall, classId)**: iterate `arguments`'
  namedChildren of type `argument` IN SOURCE ORDER, tracking a `positional`
  counter for unnamed args:
  - unnamed arg: `positional++`; **when positional===2 AND value is an
    `identifier`** → `extends` ref {from: classId, name: value text, line/
    col: the VALUE node} (ggproto's parent — `ggproto("GeomX", Geom, …)` →
    extends Geom; pinned). A string 2nd positional (`setClass("Patient",
    "rep")`) emits nothing (identifier-only).
  - named `inherit` or `contains`: value through literalOrIdentifier →
    `extends` ref at the value node (R6 `inherit = AbstractCollection`
    identifier, S4 `contains = "Person"` string — both pinned).
    **`inherit = pkg::Parent` → literalOrIdentifier null → NO ref** (pinned,
    `extract-classes2.txt` NoInherit).
  - named arg whose value is a `function_definition` → emitMethodArg
    (ggproto's direct-method style).
  - named arg whose value is a `call` with calleeName `list` → iterate ITS
    `arguments`' `argument` children → emitMethodArg each (R5 `methods =`,
    R6 `public =`/`private =`/`active =` — ALL list-valued named args
    qualify, name is not checked: `fields = list(balance = "numeric")`
    contributes nothing only because the entries aren't function_definitions).
  - everything else: skipped — **non-method argument subtrees are NEVER
    visited**: `representation(name = "character")` inside setClass emits no
    calls ref (pinned), `signature("Cls")` inside setMethod emits nothing
    (pinned).
  Emission order = argument order: `inherit` after `public` → the extends
  ref lands AFTER the methods' body refs (pinned, `extract-leftovers2.txt`
  Late: `calls p_call` precedes `extends LateBase`).

## The visitNode hook — reproduction semantics (the whole game)

**Where the hook runs**: `visitNode` (tree-sitter.ts:936) calls it FIRST for
**every node the main walker visits** (:943-953) — including the root
`program` node and every node reached by plain recursion (:1295-1301,
namedChildren in order) AND every node reached re-entrantly through the
hook's own `ctx.visitNode(body)` calls (makeExtractorContext:1465-1480 wires
`visitNode` back to the real walker). **`visitFunctionBody` (:5129+) NEVER
RUNS for R** — nothing reachable calls it (functionTypes/methodTypes empty,
no swift/TS branches, and r.ts uses `ctx.visitNode`, never
`ctx.visitFunctionBody`). Every "body walk" in R is the ordinary
hook-consulting walk — this is DELIBERATE (r.ts:260-266 comment): nested
definitions are assignments only the hook can recognize.

**When the hook returns true** (consumed): the dispatcher runs
`scanFnRefSubtree(node, 0)` — a **NO-OP for R** (no fnRefSpec) — and returns
WITHOUT descending. When false: `maybeCaptureFnRefs` (no-op), then the
ladder — for R only `callTypes` can match (:1248 → extractCall, **children
still recursed afterward** — no skipChildren), else plain recursion.

**Truth table — `call` nodes** (hook r.ts:183-252). `fname = calleeName(node)`;
null (dollar/subset/string/return/call callees) → **false** → extractCall +
recursion.

| fname | branch | consumed? | emits |
|---|---|---|---|
| `library`/`require`/`requireNamespace`/`loadNamespace`/`source`, first-arg value a string/identifier | import (:189-208) | YES | `import` node (name = module/file text; extra `{signature: full call text .trim().slice(0,100)}` — UTF-16 slice) + `imports` ref {from: nodeStack TOP (file or enclosing function/method/class), name: module, line/col: CALL node start}. Node parent = stack top (contains edge), QN scope-prefixed (`use_it::inside_fn` — pinned) |
| same fns, first-arg missing/dynamic/empty-string/non-literal | import (:191) | **YES — silently** | **NOTHING AT ALL** — no import, no `calls` ref, and the argument subtree is never visited: `library()`, `source(file.path("R","dyn.R"))` (the `file.path` call vanishes), `requireNamespace(quietly = TRUE, package = "namedpkg")` (TRUE is first → null → the real package is LOST), `library("")` — all pinned in `extract-imports.txt` |
| `setClass`/`setRefClass`/`R6Class`/`ggproto`, first-arg value a string/identifier | class (:211-221) | YES | `class` node at the CALL node (extra `{}` — NO signature key) + pushScope + extractClassMembers (§above) + popScope. **An IDENTIFIER first arg names the class from the identifier text**: `R6Class(GenName, …)` → class "GenName" (pinned) |
| same fns, first-arg missing/dynamic/NULL | class (:213) | **NO — falls through** | generic call: `calls ggproto` + full recursion into arguments — method-arg bodies are walked at the ENCLOSING scope with NO method nodes (`BadGG <- ggproto(NULL, Geom, draw_key = function(x) render_key(x))` → `calls ggproto` + `calls render_key` both from FILE — pinned). Asymmetry vs imports, PRESERVE |
| `setGeneric`/`setMethod`, first-arg literal/identifier | generic (:224-249) | YES | `function` node at the CALL node, name = first-arg text, signature = params text of the FIRST argument (any position) whose value is a `function_definition` (else undefined); body walk via pushScope + `ctx.visitNode(body)` + popScope when that impl exists. `setMethod("area","Sq",area_impl)` → function node only, identifier impl NOT visited (pinned). `setGeneric("area")` → bodiless function node (pinned) |
| same fns, first-arg non-literal | generic (:226) | NO | falls to generic call (`calls setGeneric` + recursion) |
| any other fname (incl. `setValidity`, `assign`, `delayedAssign`, `makeActiveBinding`, `do.call`, `match.fun`, `Recall`, `UseMethod`, `structure`) | — | NO | generic extractCall + recursion — NO symbol nodes (all pinned in `extract-edge.txt`; `assign("via_assign", 11)` mints NO variable — known gap, PRESERVE) |

**Truth table — `binary_operator` nodes** (hook r.ts:254-306). `op` = the
`operator` field child's TEXT; missing → false (cannot occur).

| shape | branch | consumed? | emits |
|---|---|---|---|
| `op ∈ ASSIGN_LEFT` AND lhs `identifier` AND rhs `function_definition` — **ANY scope** | fn (:267-279) | YES | `function` node AT THE binary_operator (name = lhs text WITH backticks — `` `%+%` `` pinned; extra `{signature: parameters raw text or undefined}`) + pushScope + `ctx.visitNode(body field)` + popScope. Nested defs stack QNs: `nester::inner::innermost`; fires inside `if`/braces/bodies too (`f_in_if`, `braced_fn`, `local_fn` — all pinned, attributed to the nodeStack top which is still the FILE for statement-level nesting) |
| `parent.type === 'program'` AND `op ∈ ASSIGN_LEFT` AND lhs `identifier` AND rhs present (non-function) | var (:284-296) | YES | UNLESS rhs is a `call` whose calleeName ∈ CLASS_FNS ∪ GENERIC_FNS (the class-idiom suppression): `variable`/`constant` node (CONSTANT_NAME on the lhs text) at the binary_operator, extra `{}`. **Then `ctx.visitNode(rhs)` ALWAYS runs** (suppressed or not) → rhs calls/imports/classes extract with the FILE on top: `ans <- helper(x)` → variable + `calls helper` from file; `Account <- setRefClass("Account", …)` → class node ONLY (no variable — pinned); `BadGG <- ggproto(NULL, …)` → **NEITHER node** (suppression checks the callee NAME, the class branch then declines on the NULL — pinned) |
| `parent.type === 'program'` AND `op ∈ ASSIGN_RIGHT` AND rhs `identifier` AND lhs present | right-var (:298-303) | YES | variable/constant from RHS text + `ctx.visitNode(lhs)`. `(function(x) x*3) -> trpl` → variable trpl, NO function node (the paren'd function_definition recurses without a hook match — pinned) |
| anything else (`<-` with call/subset/string/`$`/`@` lhs, non-top-level value assigns, `:=`, `%>%`, `\|>`, `~`, arithmetic…) | (:305) | NO | plain recursion — rhs/lhs calls extract at the current scope; no nodes. Pinned: `x[1] <- 7` nothing; `attr(x,"who") <- 8` → `calls attr` (lhs IS a call node); `obj$field <- 9` nothing; `"strassign" <- 6` nothing; `env$attached <- function(x) side_call(x)` → **NO function node, `calls side_call` leaks to FILE scope** (the function_definition recurses, body walked at stack top — pinned, common R idiom, known gap); `dt[, b := compute_b(a)]` → `calls compute_b` from file |

**Precedence trap (probed, r.ts:13-16 comment is accurate):**
`function(y) y - 1 -> ghost` parses as `function_definition` whose BODY is
`(y-1) -> ghost` — top level sees a bare function_definition → no hook
match anywhere → **NOTHING extracted** (pinned). Chained
`chain_a <- chain_b <- 5`: rhs of the outer is a binary_operator (not
function_definition, rhs truthy) → **only `chain_a` minted**; the inner
`chain_b <- 5` is visited via `ctx.visitNode(rhs)` but its parent is the
OUTER binary_operator, not `program` → skipped (pinned).

**All other node types** return false immediately (:308) — `program`,
`braced_expression`, `if/for/while/repeat`, `function_definition` (bare),
`extract_operator`, `subset`/`subset2`, literals, comments — plain
recursion. Consequences pinned: top-level `{ hidden_var <- 42 }` loses the
variable (parent is braced_expression) but keeps a nested `braced_fn <-
function()` (fn branch is scope-free); for/while/if conditions and bodies
emit their calls at the enclosing scope.

## extractCall (tree-sitter.ts:3684) — the R paths

Entry gates: not vbnet/erlang (:3698/:3746), not ruby/arkts. R `call` nodes
reach the generic tail: `func = getChildByField(node, 'function') ??
node.namedChild(0)` (:4313) — **the `function` FIELD is always present** for
R calls (subset/subset2 carry the same fields but are not callTypes). The
cpp operator recovery (:4324) is language-gated off.

- **The member branch (:4364) is UNREACHABLE**: R func types are
  `identifier`, `namespace_operator`, `extract_operator`, `call`, `subset`/
  `subset2`, `string`, `parenthesized_expression`, `function_definition`,
  `return` — none is in the member list
  (member_expression/attribute/selector_expression/navigation_expression/
  field_expression), none is scoped_identifier, csharp branch is gated. So
  LITERAL_RECEIVER_TYPES, SKIP_RECEIVERS, the #750 re-encode, and receiver
  logic NEVER fire for R.
- **Everything lands in the else (:4518-4520): calleeName = RAW func text**
  (UTF-16 substring, verbatim — internal whitespace/newlines included).
  Pinned callee texts (`extract-edge.txt`):
  - bare `helper`; namespace `pkg::fn_q`, `pkg:::fn_h` (kept qualified —
    resolution matches them via the `^(\w+)::(\w+)$` colonMatch);
  - dollar `obj$meth`, chained `lst$a$b`, mixed slot `o@s$m` (feeds
    name-matcher's rDollarMatch `^([\w.]+)\$(\w+)$`);
  - call-of-call ``Negate(`%in%`)`` (raw inner text, backticks kept) — plus
    the INNER `calls Negate` from post-extractCall recursion (both at their
    own node starts);
  - `match.fun("fun_by_name")` + inner `match.fun` (same pattern);
  - string callee `"strfn"` — **QUOTES INCLUDED**;
  - subset callee `lst[[1]]`;
  - **`return`** — `return`/`next`/`break` are named nodes; `return(g(x))`
    emits `calls "return"` + `calls "g"` (pinned; HIGH VOLUME — every
    R file). Reproduce byte-for-byte.
- **The parenthesized-conversion regex (:4529-4532) IS live**: `(handler)(8)`
  → func text `(handler)` matches `/^\(\s*\*?\s*([A-Za-z_][\w.]*)\s*\)$/` →
  rewritten to **`handler`** (pinned). JS `\s` ⊇ `\r` — Rust `\s` parity
  holds. An IIFE `(function(x) x)(1)` does NOT match (inner text isn't a
  plain name) → raw text callee `(function(x) x)`; `(\(x) x)(1)` likewise —
  backslash isn't in the regex's first class.
- cpp template-strip (:4542) and fn-ptr fan-out (:4556) are c/cpp-gated —
  no.
- Final ref (:4572-4580): {fromNodeId: nodeStack top, referenceName,
  referenceKind `calls`, line: CALL node startRow+1, column: CALL node
  startColumn (UTF-16)}. **No skipChildren** → inner calls of chains/args
  are ALSO visited (each gets the hook first — a nested
  `suppressPackageStartupMessages(library(quietpkg))` emits `calls
  suppressPackageStartupMessages` THEN `import quietpkg` at the inner call's
  position C31, pinned).
- Pipes: `%>%` (operator token kind `special`) and `\|>` are plain
  binary_operators → no ref for the pipe itself; each rhs `call` node emits
  normally (`x %>% p_one() %>% p_two()` → calls p_one C6 + p_two C18 from
  the enclosing scope, pinned). The piped LHS argument is invisible —
  `$`-dispatch/pipe-flow resolution is a known runtime-semantics gap
  (r.ts:31-34 doc comment).

## Node creation, IDs, qualified names, order

- createNode (:1308): id = `generateNodeId(filePath, kind, name,
  startRow+1)` = `` `${kind}:${sha256(`${filePath}:${kind}:${name}:${line}`).hex.slice(0,32)}` ``
  (tree-sitter-helpers.ts:18-30). **Name keeps backticks** (`` `weird
  name` ``, `` `%+%` ``). The endLine body-extension (:1329-1334) is dead
  (no resolveBody hook) — endLine = the anchor node's endRow+1 (functions:
  the binary_operator; hook classes/generics: the call; methods: the
  argument; imports: the call).
- **Duplicate IDs are legal and must be reproduced**: two same-(kind, name,
  line) symbols (`f <- function() 1; f <- function() 2` on one line) push
  TWO node rows with the IDENTICAL id, differing only in columns (pinned,
  `leftovers.R --json`). No dedupe anywhere in extraction; the store upserts
  later. The parity harness compares the RAW arrays — emit both.
- File node (:508-521): id `file:${filePath}`, name basename, qualifiedName
  = filePath **verbatim as passed** (relative or absolute — pinned
  `gate-repos/ggplot2/R/geom-point.R`), endLine =
  `source.split('\n').length` (CRLF-safe — \r\n contains \n), startColumn/
  endColumn 0, isExported false. **The only node with isExported set.**
- qualifiedName = buildQualifiedName (:1447-1460): nodeStack names joined
  `::`, file kind skipped, namespacePrefix always empty for R. Top-level →
  bare (`top_fn`); nested → `nester::inner::innermost`, `Account::deposit`,
  `factory::LocalCls::lm`, `use_it::inside_fn` (all pinned). NOTE
  buildQualifiedName resolves stack ids through `this.nodes.find` — walker
  equivalent: maintain the name stack alongside the id stack.
- contains edge from stack top for EVERY created node (:1363-1372), pushed
  interleaved with node creation. extractModifiers merge (:1355) — hook
  absent, no-op. captureValueRefScope (:1374) — flush-gated dead (§arch-6).
- **Emission order contract** (the harness is rowid-order-sensitive): one
  pre-order walk; per construct — node row, then its contains edge, then
  (for classes) extractClassMembers output in ARGUMENT ORDER (extends refs
  and method nodes interleave chronologically; a method's body refs flush
  before a later argument's extends ref — pinned by Late), then (for
  fn/generic nodes) the body walk's refs. There is NO end-of-file flush for
  R (fn-ref and value-ref flushes emit nothing) — nodes[], edges[], refs[]
  are each strictly walk-ordered.

## Signatures — the only extra

- Function/generic nodes: raw `parameters` text — parens included, defaults/
  `...`/newlines verbatim (`"(a, b = 2, ...)"`;
  `"(\n  x,\n  y,\n  by = NULL,…)"` pinned on dplyr/join.R). Absent
  parameters → the `signature` key is passed with value `undefined` (wire:
  NONE — indistinguishable from omitted; keep it NONE).
- Method nodes: same, from the entry's function_definition.
- Import nodes: `getNodeText(call).trim().slice(0, 100)` — **UTF-16 slice of
  the WHOLE call text** including `base::` qualifiers and interior newlines;
  a >100-unit call truncates mid-text (multi-line `library(\n  crlfpkg\n)` →
  `"library(\n  crlfpkg\n)"`, and under CRLF `"library(\r\n  crlfpkg\r\n)"`
  — the ONLY LF↔CRLF extraction difference, §CRLF).
- Class/variable/constant nodes: NO signature key (`{}`).

## Docstrings — roxygen is DROPPED entirely

`getPrecedingDocstring` (tree-sitter-helpers.ts:95+) is called ONLY inside
extractFunction/Method/Class/… — none of which run for R; the hook's
createNode calls pass no docstring. **No R node ever carries a docstring**
— `#'` roxygen blocks, plain `#` comment runs, everything is invisible
(pinned: torture.R's roxygen'd `top_fn` and comment-run'd `eq_fn` both have
doc=undefined). The walker needs no comment handling at all — and must NOT
add any. (Roxygen-as-docstring would be an accuracy improvement for a later
TS+kernel PAIRED change, never walker-side alone.)

## CRLF & encoding

- **End-to-end probe** (`extract-crlf-lf.txt` vs `extract-crlf-crlf.txt`):
  identical nodes/edges/refs/lines/columns; the ONLY byte difference is
  `\r\n` inside a multi-line import signature. Comment nodes include the
  trailing `\r` at grammar level (v1.2.0) — extraction-invisible for R.
  The parity suite derives CRLF variants in-memory (kernel-tsjs-parity
  pattern); both arms parse the same bytes with the same grammar revision,
  so parity holds by construction — assert it anyway.
- **Columns are UTF-16 code units** (pinned `extract-utf16.txt`:
  `after_emoji("🎉🎉", target_fn())` → target_fn at C47 — each emoji counts
  2). All getNodeText slices and the signature `.trim().slice(0,100)` are
  UTF-16 (textutil::col16/slice_utf16 in the kernel).
- No regexes over multi-line source run for R except the
  parenthesized-conversion (single-name, `\s` semantics identical in Rust
  regex) — no `(?m)` hazards, no docstring.rs use.

## tree-sitter.ts anchor table (45a53eb)

| Path | Lines | R status |
|---|---|---|
| extract() wrap: file node, package, walk, flushes | 454-577 | live; extractFilePackage:1397 returns null (no packageTypes); both flushes no-op |
| visitNode hook dispatch + consumed-scan | 936-953 | live; scanFnRefSubtree no-op (:604 `!this.fnRefSpec`) |
| pascal/cpp-namespace/fn-ref capture | 957-990 | all no-op for r |
| dispatch ladder | 994-1292 | ONLY :1248 callTypes matches; everything else falls through |
| recursion | 1295-1301 | namedChildren in order — the walk R actually uses |
| createNode / findChildByTypes / extractFilePackage / buildQualifiedName / makeExtractorContext | 1308-1480 | live (§Node creation) |
| isInsideClassLikeNode / isClassScopeConstantAssignment | 1486-1516 | never consulted for r (ladder rows that use them don't match) |
| extractFunction…extractTypeAlias, extractImport, extractVariable/Field/Property | 1517-3236 | ALL DEAD for r |
| extractCall | 3684, 4313, 4518-4532, 4572-4580 | live (§extractCall) |
| extractInstantiation | 4610+ | dead (no kinds) |
| extractStaticMemberRef | 4750-4808 | dead (:4751 gate) |
| extractDecoratorsFor | 4897+ | dead (no callers run) |
| visitFunctionBody | 5129-5286 | NEVER RUNS |
| extractInheritance | 5595+ | dead (hook emits extends itself) |
| extractTypeAnnotations / extractVariableTypeAnnotation | 5788+, 6074+ | dead (gates) |
| flushFnRefCandidates / flushValueRefs | 622-728, 777-931 | no-op (no spec / :784 language gate) |

## Frameworks & synthesis consumers (stay TS-side — pin the contract)

- **No framework resolver, no synthesizer, no closure-collection** touches R
  (CC_LANGUAGES = {swift, kotlin}; no expect/actual; no R entry in any
  `frameworks/*.ts` languages list). Nothing to smoke-test on the decoded
  path — R always rides raw buffers.
- **name-matcher.ts consumes two R ref/node shapes** (resolution-side, no
  port — but the walker's output feeds them):
  - :1521 `rDollarMatch = /^([\w.]+)\$(\w+)$/` on `calls` ref names — the
    `obj$meth` raw-text encoding above is load-bearing (receiver/method
    split for #1108 local-receiver inference). Backticked or `@`-containing
    callees deliberately don't match.
  - :1235 local-receiver type inference regex `` `\b${r}\b\s*(?:<-|<<-|=)\s*([A-Z][\w.]*)\$new\b` `` — reads raw SOURCE lines, not extraction
    output; only node names/positions feed it.
  - The `^(\w+)::(\w+)$` colonMatch (shared) consumes `pkg::fn` callee
    texts.
- `source("helpers.R")` linking rides the ordinary `imports` ref
  (name = `helpers.R`) through import resolution — same store input from
  either arm.

## Error incidence & gate repos

Swept with the production wasm (`error-sweep.cjs`, all `.R`/`.r` ≤1 MiB):

| Repo | files | hasError | rate | notes |
|---|---|---|---|---|
| twitter/AnomalyDetection | 11 | 0 | 0.00% | the #839 small bench; pure base R |
| tidyverse/dplyr | 195 | 0 | 0.00% | medium; S3-heavy, 1,262 native pipes, S4 (3 setClass/3 setMethod), 2 R6Class, 25 `<<-` |
| tidyverse/ggplot2 | 357 | 0 | 0.00% | **the ggproto exerciser** — 239 ggproto sites |
| rstudio/shiny | 275 | 1 | 0.36% | **the R6 exerciser** — 33 R6Class, 9 source(), 480 `<<-`; the 1 error is `inst/app_template/app.R`, a moustache template (both-arm) |

**Gate repos: dplyr (small-medium), ggplot2 (medium, ggproto), shiny
(medium-large, R6)** — between them: S3 dotted functions, S4, R6, ggproto,
pipes both spellings, source(), heavy `<<-`. AnomalyDetection as the
30-second smoke (11 files). Rejected: r-lib/devtools (thin wrappers, no
distinctive shapes). **Flagged ambiguity: `setRefClass` count is 0 across
all four repos** — RefClass parity rides the fixture suite only; if the
maintainer wants a live RefClass sweep, add a Bioconductor repo
(e.g. Bioconductor/S4Vectors — also deepens S4 setMethod density) as an
optional 4th, not a gate.

Sweep policy: default `--max-deferral 0.1`; expect deferral counts of
**0/0/1** — anything more is a walker bug (ruby-style signal, §arch-4).

## Parity mechanics (all have bitten before)

- **Emission order** per §Node creation — single walk, no flushes.
- **generateNodeId inputs**: (filePath, kind, name, startRow+1) — name with
  backticks; import nodes named the module text (`helpers.R` keeps its
  extension); class nodes named from the STRING CONTENT (no quotes) or
  identifier text; duplicate ids pushed verbatim.
- **UTF-16 columns/slices** everywhere (§CRLF).
- **`.R` vs `.r`**: detectLanguage lowercases — both route to r; the parity
  sweep script's extension filter must catch BOTH casings (kernel-parity.mjs
  — verify before first sweep; `error-sweep.cjs` uses `/\.[rR]$/`).
- **Defer policy**: `has_error()` → `defer:` — no phantom class exists
  (§arch-4) but trust the flag regardless; wasm recovery is canonical for
  the two genuinely-broken shapes (MISSING-node incompletes, stray-paren
  ERRORs).
- **The `undefined`-signature nuance**: r.ts passes `signature: undefined`
  explicitly for parameterless generics — object-identical to omission in
  JSON/store/wire; emit NONE.
- **No node ever carries**: docstring, visibility, isStatic, isAsync,
  isExported (except file:false), returnType, decorators. A walker that
  "helpfully" fills any of these breaks byte parity.

## Gates (per plan §5, no exceptions)

- **No grammar-bump gate** (crate pin, no wasm change — first R7b language
  with a true no-op grammar prep; kernel-grammar-parity `+= 'r'` is the
  entire grammar proof).
- **Torture fixtures** per `## Fixtures to build`, exercised by a new
  `__tests__/kernel-r-parity.test.ts` (CRLF variants derived in-memory).
- **Parity sweeps** (`scripts/kernel-parity.mjs <dir>`, order-sensitive
  full-object, default `--max-deferral 0.1`): the survey clones live at the
  session scratchpad `svy-r/gate-repos/{AnomalyDetection,dplyr,ggplot2,
  shiny}` — re-clone fresh public OSS if gone (agent-eval policy). Expect
  0-diff on every file and deferrals 0/0/0/1.
- **Full-init dump-diffs byte-identical** (kernel arm vs `CODEGRAPH_KERNEL=0`,
  `scripts/dump-graph.mjs`, cmp) on dplyr, ggplot2, shiny ×3 runs.
- **Existing R suite stays green**: `__tests__/extraction.test.ts` R block
  (~:9080-9213 — detectLanguage, functions, classes, imports/source,
  constants, ggproto/geom-point shapes) runs through the same seam and must
  pass under routing.
- **`DEFAULT_ROUTED += 'r'`** (kernel/index.ts:37) only after ALL of the
  above; changelog rides the existing kernel entry.
- Post-route perf sanity: raw path everywhere (§arch-2), ~0% deferral —
  expect the full kernel speedup on ggplot2/shiny (275-357 files each).

## Fixtures to build

Seed from the survey's probe fixtures + their pinned dumps (torture/classes/
classes2/imports/edge/leftovers/leftovers2/crlf/utf16 — §Probe artifacts).
One consolidated `torture.R` should cover, by branch:

1. **Assignments**: all five ops minting nodes (`<-`, `=`, `<<-` fns +
   vars; `->`, `->>` vars); CONSTANT_NAME split (`MAX_RETRIES`, `A.CONST`,
   `RIGHT.CONST` vs `lower_var`, `dotted.var`, `x2`); backtick names
   (`` `weird name` `` var, `` `%+%` `` operator-function); chained
   `a <- b <- 5` (only a); paren'd right-assign fn (`trpl` var only); the
   precedence ghost (`function(y) y-1 -> ghost` → nothing); string-lhs,
   subset-lhs (nothing), call-lhs (`attr(x,…) <- 8` → calls attr),
   `$`/`@`-lhs (nothing incl. the `env$fn <- function` body-leak-to-file),
   `:=` (data.table rhs calls), `assign()`/`delayedAssign()` (plain calls).
2. **Functions & scopes**: `\(x)` lambda node; 3-deep nesting
   (`nester::inner::innermost` QNs + contains chain); fn-assignment inside
   `if` and inside a bare top-level `{ }` (extracted, file-scope) vs the
   sibling `hidden_var` (lost); `local({ … })` (calls local + inner fn
   extracted, inner var lost); local right-assign (`fetch() -> got` →
   calls fetch only); same-line duplicate `f`/`f` (duplicate ids); dots
   params `(a, b = 2, ...)` signature; multi-line signature.
3. **Imports**: all four IMPORT_FNS + source() (node+ref shapes, QN
   scoping in a function); the FIVE silent-consumption shapes (`library()`,
   dynamic source(file.path(…)), named-first requireNamespace, `library("")`,
   dynamic library(f())); `base::library` qualified; `library(help = docpkg)`
   named-first bug; nested `suppressPackageStartupMessages(library(x))`
   (calls-then-import order); sig truncation ≤100 + multi-line sig.
4. **Classes**: S4 setClass (+ representation invisibility + contains
   string); setGeneric with/without def; setMethod (+ signature() call
   invisibility + identifier-impl no-walk + duplicate `describe` name);
   setRefClass (fields ignored, methods list, `<<-` field writes inside
   methods, contains); R6Class (public/private/active all emit methods,
   `items = NULL` ignored, inherit identifier, inherit AFTER public for ref
   ordering, `inherit = pkg::Parent` dropped, empty `public = list()`);
   ggproto (name+parent positionals, direct method args, non-fn args
   skipped); qualified constructors (`methods::setClass`, `R6::R6Class`);
   identifier-named class (`R6Class(GenName, …)`); the ggproto(NULL,…)
   fall-through (calls + file-scope body leak, NO var); class in a function
   body (`factory::LocalCls::lm`); class-idiom var suppression
   (`Account <- setRefClass("Account"…)` → class only).
5. **Calls**: bare; `pkg::fn`/`pkg:::fn`; `obj$meth`/`lst$a$b`/`o@s$m`;
   call-of-call (``Negate(`%in%`)`` outer+inner); `match.fun("x")(3)`;
   string callee `"strfn"`; subset callee `lst[[1]]`; `(handler)(8)`
   conv-regex rewrite; IIFE raw-text callee; **`return(g(x))` → calls
   return + g**; `next`/`break` (nothing); pipes `%>%` and `|>` (rhs calls
   only, enclosing scope); if/for/while/repeat bodies; call args'
   nested-call recursion; `switch` arms.
6. **CRLF variant** derived in-memory (multi-line import sig is the only
   byte delta) + a roxygen/comment file (all doc=undefined) + the UTF-16
   line (emoji before/inside a call, column pins).
7. **Defer fixture**: genuinely-broken source (`x <-` incomplete — MISSING
   node) — kernel defers, wasm output byte-served; and the parse-clean
   battery shapes (trailing commas, raw strings, underscore-pipe, BOM) in
   the MAIN fixture to prove they DON'T defer.

## Probe artifacts (session scratchpad `svy-r/`)

`cst.cjs` (CST dumps against the production wasm, fields + anon fielded
children), `extract.cjs` (dist TreeSitterExtractor ground truth, rowid
order), `table-dump.cjs` + `table-dump.out` (ABI/state/kind/field tables),
`err-battery.cjs` + `err-battery.out` (48 shapes — no phantom class),
`error-sweep.cjs` + `error-sweep.out` (gate-repo hasError rates + the shiny
template file), fixtures `torture.R`, `classes.R`, `classes2.R`,
`imports.R`, `edge.R`, `leftovers.R`, `leftovers2.R`, `smoke.R`,
`crlf-lf.R`/`crlf-crlf.R`, `utf16.R` with pinned dumps
`extract-{torture,classes,classes2,imports,edge,leftovers2,crlf-lf,
crlf-crlf,utf16}.txt`, gate-repo clones under `gate-repos/`, and the crate
material at `../crates/tree-sitter-r-{1.2.0,1.3.0}/` +
`../r-tag-1.2.0-{parser,scanner}.c` (shas in §Grammar prep; full batch-4
probe record `../batch4-grammar-probe.md`). Scratch is throwaway —
re-derive from this doc if gone.