Review-LSP

Candidate-bound semantic code intelligence with provenance for AI code review.

Review-LSP runs LSP semantic queries against an exact Git candidate, not whichever checkout happens to be live. Each successful query returns a content-addressed receipt binding the candidate, document, semantic toolchain, environment, request, result, and isolation mode.

Current public release: 0.1.0-alpha.1.

npm install review-lsp@alpha
npx review-lsp artifact-info

The registry currently exposes both alpha and latest as 0.1.0-alpha.1. Use @alpha explicitly while Review-LSP is prerelease software.

Why Review-LSP?

Editor LSPs answer questions about the workspace that is open now. Code review frequently needs a different authority: the exact commit being reviewed.

Review-LSP makes that distinction explicit.

commit A: value is string
commit B: value becomes number
live checkout: B

query(candidate = A)  -> string
query(live workspace) -> irrelevant to the review

The included A/B acceptance test exercises exactly this case.

Related MCP server: io.github.wende/cicada

What it proves — and what it does not

Receipts are tamper-evident evidence, not signatures and not proof that the language server—or the reviewed code—is semantically correct.

Architecture

flowchart LR
    G[Exact Git commit] --> C[Candidate materialization]
    C --> M[Source manifest]
    M --> E[Environment admission]
    E --> L[Pinned TypeScript LSP]
    L --> R[Semantic result]
    R --> P[Content-addressed receipt]
    P --> X[Review consumer]

    W[Live checkout] -. not review authority .-> X

The standalone core does not depend on Zamery Workbench or OpenCodeReview. Consumer adapters can admit Review-LSP receipts independently.

For the component-level model and trust boundaries, see docs/ARCHITECTURE.md.

Alpha surface

The current TypeScript profile includes:

• typescript-language-server@6.0.0;

• typescript@6.0.3;

• exact local Git commit candidates;

• hover and definition;

• CLI lifecycle: prepare, inspect, query, validate, close;

• MCP stdio server with:

  • review_lsp_candidate_info

  • review_lsp_hover

  • review_lsp_definition;

• native TRUSTED_LOCAL execution;

• Linux CONTAINER_READ_ONLY execution;

• content-addressed package/provider artifact identity.

Quickstart

Prepare an exact commit:

npx review-lsp prepare /path/to/repo <commit> --state /tmp/review-lsp-state

The output includes candidate_descriptor. Query it using 0-based LSP positions:

npx review-lsp query <candidate.json> hover src/example.ts 12 8
npx review-lsp query <candidate.json> definition src/example.ts 12 8

Validate the persisted receipt:

npx review-lsp validate <receipt.json>

Release the retained candidate when finished:

npx review-lsp close <candidate.json>

Inspect the installed provider identity:

npx review-lsp artifact-info

MCP

Run an MCP stdio server bound to one candidate at process start:

npx review-lsp serve /path/to/repo <commit> --state /tmp/review-lsp-state

The semantic MCP tools require expected_candidate_id, so a caller cannot silently retarget a running process to another candidate. Logs go to stderr; stdout is reserved for MCP framing.

Linux container profile

From a source checkout on Linux with Docker:

pnpm container:build
pnpm test:container:linux

The container profile uses:

• a read-only candidate bind mount;

• a read-only root filesystem;

• no network;

• dropped Linux capabilities;

• no-new-privileges;

• bounded memory, CPU, and PIDs;

• tmpfs only for bounded writable state/scratch;

• exact Docker image identity in the environment manifest.

The inner process verifies that /candidate is an explicit Linux read-only mount before a receipt may claim CONTAINER_READ_ONLY.

Release evidence

0.1.0-alpha.1 was verified with:

• macOS 14 / Node 22.19.0 — PASS;

• macOS 14 / Node 24.19.0 — PASS;

• Ubuntu 24.04 / Node 22.19.0 — PASS;

• Ubuntu 24.04 / Node 24.19.0 — PASS;

• Linux Docker isolation smoke — PASS;

• clean public-registry install + A/B semantic smoke — PASS.

See compatibility evidence and the release notes.

Current limitations

• Dependency snapshots are not admitted yet; dependency-bearing projects remain PARTIAL.

• TypeScript only for this alpha.

• Dirty-worktree candidates are not supported.

• References, symbols, diagnostics, and additional semantic operations are deferred.

• MCP is local stdio only.

• Windows is not in the alpha compatibility claim.

• Native mode is not a hostile-host sandbox.

• A malicious container host administrator is outside the container profile's threat boundary.

See ROADMAP.md for likely next areas.

Development

Requirements:

• Node.js 22.19+ or 24.x;

• pnpm 10.20.0;

• Git;

• Docker for the Linux container profile.

git clone https://github.com/maemreyo/review-lsp.git
cd review-lsp
pnpm install --frozen-lockfile
pnpm check

This source repository is managed with pnpm. Do not run npm install review-lsp@alpha inside a checkout whose node_modules was created by pnpm; npm 11 can crash while traversing pnpm-managed symlinks. Test the published package in a fresh consumer directory instead.

Useful commands:

pnpm test:unit
pnpm test:acceptance
pnpm demo:ab
pnpm test:mcp:stdio
pnpm test:package
pnpm benchmark

Contributing and support

• Contributing guide

• Security policy

• Support

• Code of Conduct

• Changelog

Bugs and feature requests belong in GitHub Issues. Usage questions and integration design discussions belong in GitHub Discussions. Security vulnerabilities should use GitHub private vulnerability reporting.

License

Apache-2.0. Direct runtime dependency license evidence is generated into dist/review-lsp-licenses.json during the alpha build.