feat: v0.7.0 code graph developer preview

[theDakshJaitly]

Status

Important

Developer preview: do not merge yet.

main and npm remain on stable v0.6.3. This PR tracks the upcoming v0.7.0 code graph while it is tested, improved through contributions, documented, and prepared for a stable release. No v0.7.0 GitHub release or npm publish should happen from the current state.

Overview

This PR adds a deterministic, local code knowledge graph beneath Mex's markdown memory scaffold. Tree-sitter extraction writes structural code facts to SQLite so scaffold memory can point at exact symbols, detect when grounded behavior changes, and survive confident renames or moves through fingerprint reconciliation.

The preview package version is 0.7.0-dev.0. The graph is additive: existing scaffolds and the original filesystem/lexical drift checks continue to work when no graph is present.

What is included

• Tree-sitter extraction for TypeScript, TSX, JavaScript, and JSX.
• SQLite graph storage with nodes, edges, source locations, body hashes, MinHash fingerprints, and reconciliation data.
• Cross-file import, call, inheritance, containment, and reference edges.
• Express route-to-handler resolution as the reference framework resolver.
• Graph-backed grounding through frontmatter grounds_to entries and inline mex:// anchors.
• Grounding drift detection for changed, moved, ambiguous, and removed nodes.
• Durable grounding repair during mex sync.
• Fresh-setup graph population and an idempotent migration path for existing populated scaffolds.
• Source-level LanguageExtractor and FrameworkResolver contribution seams.
• Packaged SQLite schema and Tree-sitter WASM grammar assets.

New commands

mex graph
mex graph --json
mex graph scope <task>
mex graph ground
mex graph query where-defined <symbol>
mex graph query who-calls <symbol>
mex graph query what-calls <symbol>
mex impact <symbol-or-file>

The scope, query, and impact commands emit compact JSONL intended for coding-agent retrieval and structural analysis.

Architecture

1. Extraction: Tree-sitter grammars produce normalized nodes and syntax-level edges.
2. Resolution: cross-file and framework resolvers add semantic relationships.
3. Storage: SQLite persists graph facts, fingerprints, FTS data, and grounding baselines.
4. Retrieval: scope/query/impact commands hydrate relevant symbols and neighborhoods.
5. Grounding: scaffold prose records tight symbol pointers and fingerprints.
6. Drift and repair: mex check detects stale grounding; mex sync repairs prose and pointers.

The identity, reconciliation, schema, and drift semantics are core behavior. Changes to those areas require discussion before implementation.

Current constraints

• Requires Node.js 22.5 or newer because the preview uses built-in node:sqlite.
• Language extraction currently covers only TypeScript, TSX, JavaScript, and JSX.
• Express is the only framework-specific reference resolver.
• Unsupported-language files are skipped.
• Missing grammars, unavailable SQLite, or absent graph data degrade gracefully to the original checks.
• Graph contribution interfaces are source-level seams, not public npm API exports.
• The preview is available from source only and is not published to npm.

Testing

Validated on the preview branch with:

npm run typecheck
npm test
npm run build

Current result: 30 test files and 301 tests passing. The build also verifies that the graph schema and three grammar WASM assets are copied into dist/.

Contribution workflow

Code-graph issues must state:

Target branch: code-graph-preview

Create contribution branches from the preview branch:

git switch code-graph-preview
git pull
git switch -c <feature-or-fix-branch>

Open contributor PRs with:

• Base: code-graph-preview
• Compare: the contributor's feature or fix branch

Do not target main with code-graph contributions. Relevant labels include code-graph, developer-preview, language-support, tree-sitter, testing, performance, help wanted, and good first issue. Work affecting graph identity, reconciliation, schema, or drift semantics should use core / discuss-first.

Release checklist

Preview foundation

• Deterministic graph engine and SQLite storage
• TS/JS/TSX/JSX reference extraction
• Express reference resolver
• Graph CLI, retrieval, and impact commands
• Grounding drift detection and durable repair
• Existing-scaffold grounding migration
• Packaged graph assets
• Preview version set to 0.7.0-dev.0
• Contributor branch workflow documented
• Preview issue labels created
• Contributor PR CI enabled for code-graph-preview
• Preview branch protection requires CI, review, and resolved conversations
• Full typecheck, test, and build validation

Before stable v0.7.0

• Complete contributor testing on representative repositories
• Triage and fix preview bugs and graph-accuracy regressions
• Document extractor and resolver contribution walkthroughs
• Add extractor/resolver issue and PR templates
• Agree on and open the first bounded starter issues
• Expand fixtures and regression coverage from real repositories
• Review performance and graph-size behavior on larger codebases
• Document known limitations and supported-language status
• Validate a clean packed-install workflow
• Complete final compatibility and migration review
• Change package metadata from prerelease to 0.7.0
• Approve this PR for merge into main
• Create the GitHub v0.7.0 release
• Publish [email protected] to npm

Release flow

code-graph-preview
        ↓
       main
        ↓
GitHub v0.7.0 release
        ↓
npm [email protected]

Until every required release item is complete, this PR should remain open and in Draft state.