chore(sync): merge upstream d2e0389 and release 1.6.2-fmagent.3

.claude/skills/add-lang/SKILL.md

@@ -60,11 +60,14 @@ still be unusable:**
 ```bash
 node scripts/add-lang/check-grammar.mjs <lang> path/to/valid-sample.<ext>
 ```
-It prints the grammar's ABI version and parses a valid sample many times in a
-multi-grammar runtime. If it **FAILs** (ERROR trees on valid code — an old ABI
+It prints the grammar's ABI version and runs it the way indexing does: in a
+child process with indexing's V8 flags, beside the vendored grammars, parsing a
+valid sample many times and once at the 1 MiB file-size limit. If it **FAILs**
+(ERROR trees, or later parses giving a different tree, on valid code — an old ABI
 corrupting the shared WASM heap, which silently drops nested calls/imports on
 every file after the first; e.g. the tree-sitter-wasms **Lua** grammar is ABI 13
-and fails), do NOT use that wasm. **Vendor a newer (ABI 14/15) build instead:**
+and fails — or the process running it crashing or hanging, even after every
+parse finished), do NOT use that wasm. **Vendor a newer (ABI 14/15) build instead:**
 ```bash
 npm pack @tree-sitter-grammars/tree-sitter-<lang>   # often ships a prebuilt *.wasm
 # or build one: npx tree-sitter build --wasm   (needs Docker/emscripten)
@@ -131,7 +134,7 @@ npm run build            # tsc + copy-assets (copies any vendored *.wasm into di
 ```
 Index a small sample repo and check extraction:
 ```bash
-( cd <sample-repo> && codegraph init -i )
+( cd <sample-repo> && codegraph init )
 node scripts/add-lang/verify-extraction.mjs <sample-repo> <lang>
 ```
 `verify-extraction.mjs` fails (exit 1) if the language isn't detected or only

.cursor/rules/codegraph.mdc

@@ -20,5 +20,5 @@ Reach for `codegraph_explore` before grep/find or Read for any **structural** qu
 
 ### If `.codegraph/` doesn't exist
 
-The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*
+The MCP tools say the project isn't indexed. Indexing is the user's decision: tell them they can run `codegraph init` to build the index, but don't run it yourself.
 <!-- CODEGRAPH_END -->

.gitattributes

@@ -0,0 +1,9 @@
+# Third-party tree-sitter grammars that the native kernel compiles from source
+# (codegraph-kernel/build.rs). Keep all of them out of GitHub's language
+# statistics, and collapse only the generated parser.c files in pull-request
+# diffs. The hand-written scanner.c files are where C gets patched or added,
+# so they stay expanded for review.
+# The /** is needed: an attributes pattern that names a directory does not
+# reach the files inside it.
+codegraph-kernel/grammars/** linguist-vendored
+codegraph-kernel/grammars/**/parser.c linguist-generated

.github/workflows/deploy-site.yml

@@ -24,9 +24,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Build with Astro
-        uses: withastro/action@v3
+        uses: withastro/action@v6
         with:
           path: site
           node-version: 22
@@ -40,4 +40,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

BUNDLING.md

@@ -33,6 +33,10 @@ scripts/build-bundle.sh linux-x64            # -> release/codegraph-linux-x64.ta
 scripts/build-bundle.sh win32-x64            # -> release/codegraph-win32-x64.zip
 ```
 
+The Node runtime is the official nodejs.org release named by the script's
+default `NODE_VERSION` (or its second argument). The download is refused
+unless it matches the SHA-256 listed in that release's `SHASUMS256.txt`.
+
 Because dropping better-sqlite3 left **zero native addons**, building a bundle is
 pure file-packaging — **any** target builds on **any** OS (the whole matrix builds
 on one Linux runner). Cross-compilation isn't a concern; only *run-testing* a

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to CodeGraph
+
+Thanks for helping out. Small, focused changes are the easiest to review and land.
+
+**Reporting a bug?** Open an [issue](https://github.com/colbymchenry/codegraph/issues) with your CodeGraph version (`codegraph --version`), Node.js version, operating system, the steps to reproduce it, what you expected, and what happened instead. A small public repository or snippet that shows the problem helps most.
+
+**Asking for a feature?** Describe the use case and why what's there today doesn't cover it.
+
+## Build from source
+
+You need Git, npm, and Node.js 22.12 or later, below 25. `npm ci` stops on anything older, because the build and test tools need it and running from source uses Node's built-in `node:sqlite`; the published installers bundle their own Node, so this only matters here.
+
+```bash
+# Fork the repository on GitHub, then:
+git clone https://github.com/<your-username>/codegraph.git
+cd codegraph
+git remote add upstream https://github.com/colbymchenry/codegraph.git
+
+npm ci
+npm run build
+```
+
+A globally installed `codegraph` doesn't run your changes, so run your build directly:
+
+```bash
+node dist/bin/codegraph.js --help    # the build as it stands
+npm run cli -- status                # rebuild first, then run a command
+npm run dev                          # recompile TypeScript on every save
+```
+
+`npm run build` covers the CLI, the SQL schema, the parser grammars and the browser viewer. Two builds are separate:
+
+- `npm run build:kernel` builds the optional native extraction kernel, and needs a Rust toolchain. Tests that need the kernel are skipped without it.
+- `npm run build:lib` builds the viewer's component library.
+
+## Test your change
+
+```bash
+npx vitest run __tests__/extraction.test.ts                   # one file
+npx vitest run __tests__/extraction.test.ts -t "TypeScript"   # tests matching a name
+npm run test:watch                                            # rerun as you edit
+npm test                                                      # everything
+```
+
+Run the focused tests while you work, then `npm test` before opening a pull request. Tests that run the compiled CLI use `dist/`, and the test setup rebuilds it first when it's stale.
+
+- **Tests live in `__tests__/`** and use real files and real SQLite databases, with no database mocking. Create temporary folders with `fs.mkdtempSync` and remove them in `afterEach`.
+- **A bug fix needs a test that fails without the fix.**
+- **Behavior that differs by platform** gets a gated test, such as `it.runIf(process.platform === 'win32')(...)`, and needs checking on the platforms it affects. See [cross-platform validation](AGENTS.md#cross-platform-validation).
+- **New language or framework support** needs validating on real repositories. Start with the `/add-lang` skill in [`.claude/skills/add-lang/SKILL.md`](.claude/skills/add-lang/SKILL.md), then follow the [validation methodology](docs/AGENTS.md#validation-methodology-required-for-every-new-languageframework) and the [coverage playbook](docs/design/dynamic-dispatch-coverage-playbook.md). Before extending a router or web framework, read [framework coverage](docs/design/framework-coverage.md).
+- **A documentation-only change** doesn't need the test suite. Check its examples and links instead.
+
+## Prepare a pull request
+
+- Branch from the latest `main`, and keep to one concern. Unrelated formatting, CI or feature work belongs in its own pull request.
+- Name commits `type(scope): what now works`, such as `fix(go): a constant in a const ( … ) group keeps its own doc comment`. Types in use are `feat`, `fix`, `docs`, `test`, `perf`, `chore` and `ci`.
+- In the description, explain the problem, the resulting behavior, and what you ran, including any failures and any platform you couldn't test.
+- Keep existing CLI commands and the default MCP tools working, unless the pull request exists to change them and says why.
+- Add a line to `CHANGELOG.md` under `## [Unreleased]`, in `### New Features` or `### Fixes`, for anything a user would notice. Write one plain sentence about what changed for them, without internal file names or benchmark numbers. Changes to the `codegraph ui` viewer, which isn't released yet, go in [`docs/viewer-launch-changelog.md`](docs/viewer-launch-changelog.md) instead.
+- Don't bump the version, and change `package-lock.json` only when you add or remove a dependency.
+- Use public or made-up examples. Keep local paths, private code and machine-specific settings out of fixtures.
+
+## What happens next
+
+A maintainer reads every change closely before anything lands, and may ask for changes. Keep your branch up to date by rebasing on `main`.
+
+A maintainer may also land your contribution as their own commit, rewritten where needed, instead of merging your branch. You're credited in the changelog either way.
+
+## Find your way around
+
+- [Documentation index](docs/README.md): guides, design notes and benchmarks.
+- [AGENTS.md](AGENTS.md): the architecture and the development rules, which [CLAUDE.md](CLAUDE.md) imports for Claude Code.

FORK.md

@@ -3,16 +3,18 @@
 FM-Agent's maintenance fork of
 [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph).
 
-**Pinned base:** upstream `10e316d` (`main`, 2026-10-19) — an untagged commit past
-`v1.6.2`, the exception the policy below allows. `v1.6.2` itself slows indexing of
-JavaScript and Python projects, fixed only on `main` (#2362, #2344), and the fixes
-this sync is for — C++ receiver types and overloads, Go interfaces and embedding,
-functions in named object literals (#2300) — are on `main` only.
+**Pinned base:** upstream `d2e0389` (`main`, 2026-11-01) — an untagged commit past
+`v1.6.2`, the exception the policy below allows: upstream has tagged nothing since
+`v1.6.2` (2026-10-03). This sync is for call resolution `main` gained after the
+previous base: Rust receiver types (`Box`/`Rc`/`Pin` self, `as_mut`, loop and tuple
+bindings, field chains, trait-bounded generics), which link about 900 more of
+ripgrep's calls, and calls on library and built-in values no longer landing on a
+same-named project method, in every language FM-Agent reads.
 
 It carries this project's
 [PR #1865](https://github.com/colbymchenry/codegraph/pull/1865) for Dart 3
 extension types ([#1784](https://github.com/colbymchenry/codegraph/issues/1784)),
-which was patch 5 here byte for byte, and fixes for three issues reported upstream
+which this fork once carried as a patch, byte for byte, and fixes for three issues reported upstream
 from this project: functions bound through a string-named wrapper
 ([#1747](https://github.com/colbymchenry/codegraph/issues/1747), upstream PR #2002),
 C/C++ functions defined through a single-argument macro
@@ -27,18 +29,24 @@ wrappers nothing binds, and calls into a service's members. Measured on
 `sst/opencode` (`df23b7f`) by source position, upstream alone reaches 1,017 of the
 1,055 `Effect.fn*("…")(function…)` sites; with patch 2, all 1,055.
 
-The previous base was `e63fe2e` (`main`, 2026-09-27), 363 commits behind this point,
-none of them merges. None of the four patches below was taken upstream in that span:
-all four merged back without a conflict and are byte for byte what they were.
+The previous base was `10e316d` (`main`, 2026-10-19), 354 commits behind this point,
+none of them merges. None of the patches below was taken upstream in that span.
+Patches 1–4 merged back without a conflict and are byte for byte what they were.
 Upstream's generator fix ([#1741](https://github.com/colbymchenry/codegraph/issues/1741))
 still stops short in one place — the two helpers that read a class field's value do
 not list `generator_function`, on either extraction path — so patch 4 stays.
+Patch 5 conflicted only by position: upstream added
+`blankCUnbalancedConditionalBranches` (`cbd9817`) beside it in `c-cpp.ts`. That
+pass now keeps an `else if` written across a directive inside its function, which
+patch 5 also does, but it leaves a function whose `#if`/`#else` branches each
+carry a header unindexed: 10 of the patch's 14 behaviour cases fail on upstream
+alone. Both passes run, patch 5's first, before the directive snapshot.
 
 Upstream shipped the C macro-attribute extraction fix (issue #1211, PR #1311) in
 v1.5.0, so the base carries it natively; the fork no longer needs its own patch
 for it.
 
-**Patches:** four, listed below, each one file of behaviour plus the regression
+**Patches:** five, listed below, each one file of behaviour plus the regression
 test that catches its loss. Apart from them the tree matches the pinned base, so
 the fork stays cheap to re-sync. Every patch lives as a merged pull request here
 and must be **re-applied on each upstream sync** — if a merge drops one, this list
@@ -58,6 +66,8 @@ members that naming leaves unresolved. Each goes when upstream covers its half.
 | `__tests__/fm-agent-effect-ts-resolution.test.ts` | Regression cover for the patch above: a member call on a `yield* Ns.Service` local and a direct call on an imported, self-re-exporting namespace, each picking the right one of two same-named members; the missing-import and shadow declines; the `Ns.Service.create` factory hop; and a bare call never reaching a wrapped function through its string's tail. |
 | `src/extraction/languages/typescript.ts`, `src/extraction/languages/javascript.ts`, `codegraph-kernel/src/tsjs/mod.rs` | **Generator class fields.** A class field holding a generator — `class Repo { loadAll = function* () {…} }`, directly or through a wrapper call — is a method written as a field. Two helpers decide that, one classifying the field and one finding the body to walk, and each lists the node types a field's value may have. Without `generator_function` on those lists the field is a property: no callable node, and the calls in its body attribute to the file. The lists exist once per extraction path — the walker's in the language files, the kernel's in `classify_ts_class_member` and `resolve_field_body` — and have to move together: with one side updated the same source is a method on one extraction path and a property on the other. |
 | `__tests__/fm-agent-generator-class-field.test.ts` | Regression cover for the patch above, in TypeScript and JavaScript: the field is a method under its class's qualified name, the wrapped form is too, its body's call is attributed to it rather than to the file, and both extraction paths return identical nodes, edges and refs for the same source. |
+| `src/extraction/languages/c-cpp.ts`, `codegraph-kernel/src/ccpp/mod.rs` | **C functions with a conditional signature.** Code like QP's `QActive_post_` gives each `#if`/`#else` branch its own header and shares one body after `#endif`; tree-sitter reads neither header as a definition, so the function was missing. `blankCAlternativeFunctionHeaders` keeps the first header and blanks the directives and the other headers — same length, line breaks kept, so offsets do not move — but only when every branch is a complete header for the same name, there is an `#else`, nothing else is nested inside, and `{` follows `#endif`; anything else is left as it was. The kept header is a representative, not a build configuration. Separately, error recovery could read `else if (…) {…}` across a directive as a function named `if`: C now treats a function named after a control keyword as a misparse, as C++ already did, and keeps its body's calls in the enclosing function, on both extraction paths. (#20) |
+| `__tests__/fm-agent-c-conditional-function-headers.test.ts` | Regression cover for the patch above, on both extraction paths with LF and CRLF line endings: a shared body is extracted once at its original lines with its calls; conditional `else if` calls stay with the real caller while a real function named `Q_REQUIRE_ID` is kept; `#elif` and function-pointer parameters; calls resolve to a recovered function in an indexed project; and eight unrelated or ambiguous shapes come out unchanged. |
 
 A sync brings new upstream test files in on its own — they are separate files, so
 git takes them without asking. The case to watch for is upstream *moving* the test