X-Ray

See what a Git change can break — with evidence.

Local-first code intelligence for TypeScript / React / Next.js. Open a repo, get its real code graph, and ask the question that matters in review: what changed → what may be affected → what should I check?

Watch the 90-second demo · Quick start · Docs · 🇺🇿 O'zbekcha

The demo analyses one real commit in the open-source taxonomy Next.js app: env.mjs changed. A voiced preview is in docs/demo.mp4; full-quality YouTube and Reels cuts are attached to the release.

Why X-Ray

When one function changes in a project you do not know well, the answer to "who depends on this?" is usually grep plus experience. X-Ray makes that answer deterministic and inspectable.

• Change-first — the starting point is the diff, not a graph you have to stare at.

• Evidence-first — every result carries file:line, the chain that connects it to the change, and a confidence level.

• Local-first — analysis and index stay on your machine; nothing is written to the repo, and repo code is never executed.

• Measured — accuracy is checked against an independent oracle (results below) and limitations are written down (KNOWN_LIMITS).

Related MCP server: CodeGraph MCP

Features

• Code graph from the real TypeScript program + type checker: 9 node types (file, function, component, hook, class, type, variable, …) and 6 edge types (calls, renders, references, exports, imports, tests). Incremental indexing is proven equal to a full re-index.

• Change Impact for the working tree, staged changes, or any base...head range (merge-base aware; renames, deletes and untracked files handled). Direct and indirect dependents, evidence paths, and an explicit uncertain list.

• Related tests classified as direct-use, transitive, imports-only — plus untested — and a ready-to-run command (Vitest / Jest detected from package.json) for just the affected test files.

• Next.js routes — pages, layouts, route handlers and middleware have no importers (the framework calls them), so X-Ray derives routes from file paths (App Router groups/slots, Pages Router, middleware/proxy, monorepos) and lists which routes a change may affect. A changed layout covers everything beneath it.

• Interactive Graph Explorer — zoom/pan, search, filters, N-hop neighbourhood, and a source view that jumps to the exact line.

• MCP server — xray mcp lets AI agents (Claude Code, Cursor, …) query impact, search and nodes over stdio. Read-only. Setup.

• Ask — optional Q&A over the graph with validated citations. Off by default; needs explicit consent, redacts secrets, and falls back to evidence-only answers.

• Bilingual — UI, reports, errors and CLI in English and Uzbek (--lang, XRAY_LANG, EN/UZ switch).

Quick start

Requirements: Node ≥ 24 (tested on v26.11; needs type-stripping and node:sqlite), pnpm, git, tar. Tested on Linux only.

git clone https://github.com/lynxstac/xray.git && cd xray
pnpm install

pnpm demo                                   # reproducible demo: fixture repo + signature change + report
pnpm xray index  <path/to/repo>             # index (incremental; cache in ~/.cache/xray)
pnpm xray impact <path/to/repo>             # working tree vs HEAD
pnpm xray impact <path/to/repo> --base main --head feature --md
pnpm xray search <path/to/repo> useArticle
pnpm serve                                  # local web UI (URL + token printed in the terminal)

Set XRAY_LANG=en (or pass --lang en) for English CLI output.

Use it from an AI agent (MCP)

{
  "mcpServers": {
    "xray": { "command": "node", "args": ["/path/to/xray/packages/cli/src/main.ts", "mcp"] }
  }
}

Tools: xray_impact, xray_search, xray_node, xray_index. See docs/MCP.md.

Confidence model

verified is about the link, not about whether something breaks. Reports say "may be affected" — never "will break" (enforced by tests).

Accuracy

Independent oracle = TypeScript LanguageService findReferences, file level, exported symbols, 7 real projects (3,414 symbols): four private codebases and three open-source Next.js apps.

⚠️ The oracle also uses the TypeScript checker, so this measures extraction completeness, not dynamic or framework-level links. Remaining gaps are in KNOWN_LIMITS; human-labelled impact ground truth is not done yet. Performance: 1,267 files ≈ 3 s (460 MB RSS) cold, 0.15 s to reopen unchanged, 1–2 s after a one-file change. Details: BENCHMARKS.

Architecture

 scanner ─► parser ─► graph (TS Program + checker, SQLite, incremental) ─► impact ◄─ git
                         │                                                  │
                         └──► retrieval (symbol + FTS5 + graph) ─► ai ──────┤
                                                                            ▼
                                        server (127.0.0.1, token) ─► web UI · CLI · MCP

A modular monolith in a pnpm workspace; analysis packages do not depend on React, the DOM or HTTP. See ARCHITECTURE and TECHNICAL_DECISIONS.

Security & privacy

Local-only server bound to 127.0.0.1 with a token; protection against DNS rebinding and CSRF; Git argument and core.fsmonitor vectors closed; symlink escape blocked; secret files never indexed; prompt-injection and redaction tests for the optional AI path; no network code runs without explicit consent. See SECURITY.

Testing

pnpm check = typecheck + 156 unit/integration tests + 34 browser E2E tests (Playwright, Chrome), including exact match against a hand-written expected-graph.json, six impact scenarios with hand-computed ground truth, incremental ≡ full, and the security cases above.

Documentation

PRODUCT_SPEC · ARCHITECTURE · TECHNICAL_DECISIONS · BENCHMARKS · KNOWN_LIMITS · SECURITY · ROADMAP · MCP · TRY_IT · Video pipeline

Feedback is very welcome — see FEEDBACK_TEMPLATE.

License

MIT