Skip to content

README.md

Latest commit

 

History

History
107 lines (89 loc) · 7.42 KB

README.md

File metadata and controls

107 lines (89 loc) · 7.42 KB
Raw

Lighthouse: Local Code Review — Knowledge Base

Lighthouse: Local Code Review is a VS Code extension for reviewing local git branch diffs the way you'd review a pull request — with offline core review and review comments stored as plain JSON on disk. It adds a three-view "PR panel" (Comparison with commits, Changed Files, Threads), native inline comment threads, /tag classification, and a one-click Ask Copilot bridge that hands a review thread to the copilot CLI so an agent can reply in-thread and stamp its identity.

Status: local-only, single-developer tool. Published for reference; not on the Marketplace. The extension never calls a model directly — all AI work happens through an external Copilot CLI, through Ask Copilot or optional local MCP tools. Storage lives under .vscode/lighthouse-reviews/ and is a superset of, and never clobbers, the original Gururagavendra.local-pr-review format.

Documents

Doc What it covers
architecture.md Ownership split, the three views, activation fast-return, CommentController, the Ask-Copilot bridge, data flow, key decisions, known constraints
data-model.md On-disk layout (registry.json + comments.json), the v2 schema, v1 back-compat rules, the tag set, durable seqCounter, reviewedFiles
engineering.md Prerequisites, build/package/deploy commands, VM verification (Hyperloop + PrintWindow), the no-shell git helpers, commit conventions, known constraints
mcp-setup.md Script-first lighthouse-codereview installation/registration, manual fallback checklist, migration and troubleshooting

For troubleshooting and bug reports, see Support. Lighthouse requires a trusted, disk-backed workspace; Restricted Mode and virtual workspaces disable the extension.

For startup performance work, see Startup diagnostics: capture/export workflow, readiness milestones, dependency spans, timing semantics and limitations. For feature adoption and Source Control/discussion workflows, see Local feature usage.

The default layout keeps Comparison collapsed at the top, with its embedded Commits section also collapsed and loaded only when expanded. It expands all folders in Changed Files initially, and hides resolved threads. Saved VS Code pane layouts and explicit Show Resolved choices are preserved. The all-changes diff command remains available in the Command Palette, but is no longer a Changed Files toolbar button. Short Comparison panes scroll rather than hiding controls. A keyboard-accessible More below / More above cue reveals overflow; its footer slot stays reserved to avoid moving commit rows. Expanded Commits keeps enough space for its toolbar and rows, while collapsed Commits stays lazy.

Changed Files checkmarks certify the complete saved file change against the effective baseline. Saved edits or changed baseline content automatically uncheck affected files; staging/committing identical content preserves checks. Unsaved editors disable the entire checkbox and show an Unsaved explanation. Older checks without content fingerprints are cleared once when their review is first used; discussions are preserved. Validation is event-driven, not periodic hashing.

Immutable Git metadata is cached lazily in that comparison's metadata-cache.json, beside comments.json, so later sessions can reuse commit/path lookups. Saved bytes are still verified. The cache is disposable; tracking/ignoring it is your responsibility. No preloading is added.

Use New Thread in Threads for review-wide messages without a code location. Read opens a formatted discussion page with replies and explicit Copilot controls, while ordinary clicks on code-linked discussions still navigate to code. Native inline and Read-page composers both have Post and Approve buttons. Post covers questions/comments/decisions; Approve queues exactly the change described in the text box, without another dialog. Ctrl+Enter remains Post and appears in its tooltip. Thread identifiers have their own row. Below it, anchor warnings share a row with the icon-and-text Read, Code, and Resolve/Reopen buttons, which appear when hovering the thread or any of its comments, or when its header has keyboard focus. Without a warning, the entire row disappears when inactive, leaving no reserved gap; controls wrap in narrow panes.

Thread-page buttons pair a decorative icon with a visible title. Resolve/Reopen share the pane's checkbox icons; Refresh uses a circular arrow. Agent metadata stays inline with the author name. Existing conversation-named command IDs, settings and storage remain compatible.

30-second orientation

  • One extension, two owners. The extension owns the UI and writes comments.json. An external Copilot agent (the copilot CLI) reads that JSON, replies in-thread, and stamps an identity block. The extension is never an AI client.
  • Everything is a file. A "review" is a comments.json under .vscode/lighthouse-reviews/. There is no database or core-review server/network dependency. Optional Copilot, its bundled stdio MCP adapter, and explicit Git network actions are separate.
  • A comparison = base + compare. base is the TARGET branch or fixed commit, compare is the SOURCE branch under review. A separate effective baseline is inferred from local/upstream shared ancestry or fixed to an explicit ancestor commit. Comparison keeps the approved Base/Compare selectors; shared-ancestor details are in the Base tooltip, without extra Pin/Auto controls. Right-click a History/Review commit for Set as Base. All three views read one ActiveComparison; Source/Base badges precede commit text.
  • The model layer is vscode-free. reviewModel.ts has no vscode import so the schema and its migrations are unit-testable in isolation; callers wrap its outputs with VS Code types.
  • Writes are lazy + diff-friendly. comments.json is created on the first mutation (a comment or a reviewed-file checkbox), serialized as pretty-printed v2 with a trailing newline.

Fastest commands

# From the repo root: set up dependencies once, or after dependency changes.
npm ci
pwsh -File .\scripts\deploy-local.ps1   # compile, package and install the manifest's version
# Then: Developer: Reload Window

For subsequent source edits, rerun only the deploy command. Use -InstallOnly to reinstall the existing VSIX without rebuilding, or F5 with Run Extension to debug without installing. See engineering.md for prerequisites and individual build/test commands.

The schema documentation is available in this source repository, but neither docs nor the contributor .github instructions ship in the VSIX. The current Ask-Copilot prompt assumes schema guidance is supplied separately; it does not register instructions with other AI tools.

For LH-CLI-007, the VSIX additionally bundles a Node-only stdio MCP server with self-describing read/reply tools named lighthouse-codereview. scripts\setup-mcp.ps1 automates the explicit user-level opt-in, while Configure Copilot CLI MCP remains the GUI fallback, reusable across new repositories/worktrees without repository configuration. It needs Node.js 22+; core review does not. See Local MCP setup for setup, limits, workspace binding, update/removal behavior, and the distinction from Ask Copilot.