How ricl3/alloy works
1. What this repo is
- Alloy is a VS Code extension written in TypeScript.
- It is local-first: there is no Alloy backend service. The extension runs in the VS Code extension host, gathers local Git changes, and sends only the necessary redacted content to a user-selected model provider.
2. Top-level runtime boundary
- The main entrypoint is src/extension.ts.
- That module is responsible for wiring the extension into VS Code: command registration, editor/change listeners, and startup/shutdown lifecycle.
- src/config.ts centralizes settings like provider choice, review mode, file limits, categories, severities, and debounce behavior.
3. User-facing surfaces inside VS Code
- src/panels/SetupPanel.ts provides onboarding/configuration UI for provider setup.
- src/findingsTree.ts exposes reviewed issues in a tree view.
- src/commentController.ts manages inline review comments.
- src/codeActionProvider.ts exposes quick fixes and applyable actions in the editor.
- src/diagnosticBuilder.ts converts review results into VS Code diagnostics, which is the main “lint-like” feedback channel.
4. Core orchestration pipeline
- src/codeReviewService.ts is the central coordinator.
- It collects changed files, enforces limits, invokes parsing/context extraction, calls the model, and normalizes results back into editor-facing artifacts.
- The README’s review modes map to this layer: fast, deep, and architecture change how much analysis is done and how results are aggregated.
5. Diff and repository input layer
- src/gitUtils.ts and src/diffParser.ts are the source-of-truth for what changed.
- Git state is read locally, then diffs are parsed into file/hunk/range structures that downstream components can reason about.
- src/ignore.ts applies skip logic for generated files, dependency folders, lockfiles, .alloyignore, and configured skip paths.
6. Context enrichment before calling the model
- src/astContext.ts adds syntax-aware local context from the file’s AST and nearby code.
- src/repoStyleIndexer.ts appears to collect repository patterns or style signals so reviews can compare changes against local conventions.
- These modules reduce shallow comments by giving the LLM more than just raw line diffs.
7. Privacy and prompt safety boundary
- src/redaction.ts removes secrets and token-like literals before any prompt is sent out.
- src/secretManager.ts handles provider credentials, with the README indicating VS Code SecretStorage is used for API keys.
- This is an important architectural boundary: sensitive content is filtered locally before external model calls.
8. Model-provider abstraction
- src/llmRouter.ts is the provider dispatch layer.
- It routes requests to Groq, Gemini, OpenAI-compatible endpoints, or Ollama, matching the README’s supported providers.
- This keeps the review pipeline provider-agnostic and allows either cloud or fully local inference.
9. Review result structure and aggregation
- src/reviewGraph.ts and src/vectorStore.ts suggest internal structures for organizing findings, deduplication, and similarity-based retrieval/aggregation.
- src/customRules.ts likely adds local policy or rule overlays on top of model output.
- src/diagnosticBuilder.ts then translates the normalized findings into editor-native issue records with ranges, severities, and messages.
10. Performance and reliability controls
- src/rateLimiter.ts constrains concurrency and request pressure.
- src/reviewCache.ts caches review results to avoid recomputing identical work.
- The benchmark suite in src/test/benchmarks emphasizes these concerns: diff parsing, redaction, deduplication, cache behavior, concurrency, and vector operations are all treated as first-class performance surfaces.
11. Fix application and review workflow
- The README’s “one-click apply” behavior is reflected in the code action path and comment/diagnostic pipeline.
- Only high-confidence, range-bound replacements are promoted to actionable fixes, which keeps the extension from applying broad or risky edits automatically.
12. PR description generation and secondary outputs
- src/prDescriptionGenerator.ts indicates the review engine can also produce a synthesized summary suitable for pull-request text or change summaries.
- src/export.ts likely serves as a shared surface for consuming review outputs outside the main extension flow.
13. Testing and quality bar
- The repo has extensive unit tests around each boundary: config, diff parsing, redaction, provider routing, diagnostics, comments, code actions, cache, vector store, and secret handling.
- The benchmark files show that architecture and performance claims are meant to be reproducible, with mocked LLM calls so pipeline overhead can be measured deterministically.
14. How to diagram it
- A good architecture diagram should show: VS Code UI/events on the left, the local review pipeline in the center, the provider abstraction on the right, and persistent/local support services (cache, secrets, ignore rules, rate limiting) surrounding the pipeline.
- The main data flow is: editor/Git changes → diff + AST/context enrichment → redaction + filtering → LLM provider → structured findings → diagnostics/comments/code actions/tree view.
Main entry points: codeReviewService.ts Review service · extension.ts Extension entry · diagnosticBuilder.ts Diagnostics · llmRouter.ts LLM router
Components 22
VS Code surface
Extension host entrypoint and editor-facing UI/integration points.
- Extension entry · Registers commands, listeners, and startup/shutdown wiring in the VS Code host.
src/extension.ts - Setup panel · Provider and configuration setup surface shown inside VS Code.
src/panels/SetupPanel.ts - Findings tree · Displays review findings in a navigable VS Code sidebar tree.
src/findingsTree.ts - Comments · Manages inline review comments and their lifecycle in the editor.
src/commentController.ts - Quick fixes · Exposes applyable fixes and editor actions for actionable findings.
src/codeActionProvider.ts - Diagnostics · Converts normalized findings into VS Code diagnostics and ranges.
src/diagnosticBuilder.ts
Review pipeline
Local orchestration from git changes to structured findings.
- Review service · Central coordinator that gathers inputs, enforces limits, calls the model, and normalizes results.
src/codeReviewService.ts - Git input · Reads local repository state and changed files from Git.
src/gitUtils.ts - Diff parser · Turns raw diffs into file, hunk, and range structures for downstream analysis.
src/diffParser.ts - AST context · Adds syntax-aware local code context around changed lines.
src/astContext.ts - Style indexer · Collects repository-local patterns and conventions for comparison during review.
src/repoStyleIndexer.ts - PR summary · Generates pull-request style summaries or change descriptions from review output.
src/prDescriptionGenerator.ts - Export · Shared surface for consuming review outputs outside the main extension flow.
src/export.ts
Local services
Persistence, policy, and performance controls used by the pipeline.
- Redaction · Removes secrets and token-like content before any external prompt is sent.
src/redaction.ts - Ignore rules · Skips generated files, dependencies, lockfiles, and configured excluded paths.
src/ignore.ts - Review cache · Stores prior review results to avoid recomputing identical work.
src/reviewCache.ts - Rate limiter · Controls request pressure and concurrent review execution.
src/rateLimiter.ts - Custom rules · Applies local policy or rule adjustments on top of model output.
src/customRules.ts - Review graph · Organizes findings for deduplication, aggregation, and related-result handling.
src/reviewGraph.ts - Vector store · Supports similarity-based retrieval and deduplication across review artifacts.
src/vectorStore.ts - Secrets · Handles provider credentials via local secret storage.
src/secretManager.ts
Model providers
Provider dispatch and external inference endpoints.
- LLM router · Routes review requests to Groq, Gemini, OpenAI-compatible, or Ollama providers.
src/llmRouter.ts
Connections 25
- Extension entry → Review service: starts review · Extension activation and command wiring invoke the core review pipeline.
- Extension entry → Setup panel: opens setup · Extension exposes onboarding/configuration UI.
- Extension entry → Findings tree: registers tree · Extension wires the findings sidebar into VS Code.
- Extension entry → Comments: registers comments · Extension enables inline review comment management.
- Extension entry → Quick fixes: registers fixes · Extension exposes code actions for actionable findings.
- Extension entry → Diagnostics: publishes diagnostics · Extension connects review results to the diagnostics channel.
- Review service → Git input: reads changes · Coordinator pulls local Git state and changed files.
- Review service → Diff parser: parses diffs · Coordinator converts raw diffs into structured change data.
- Review service → AST context: adds context · Coordinator enriches diffs with syntax-aware local context.
- Review service → Style indexer: adds style · Coordinator incorporates repository pattern signals.
- Review service → Ignore rules: filters scope · Coordinator skips excluded files and paths before review.
- Review service → Redaction: redacts content · Coordinator ensures sensitive content is filtered before model calls.
- Review service → Review cache: checks cache · Coordinator reuses prior results when possible.
- Review service → Rate limiter: throttles work · Coordinator constrains concurrency and request pressure.
- Review service → Custom rules: applies rules · Coordinator overlays local policy onto findings.
- Review service → Review graph: organizes findings · Coordinator groups and deduplicates review results.
- Review service → LLM router: requests review · Coordinator sends enriched, redacted review prompts to a provider.
- Review graph → Vector store: similarity lookup · Review graph can use vector similarity for related findings and deduplication.
- LLM router → Secrets: uses credentials · Provider dispatch reads stored API keys or local credentials.
- LLM router → Diagnostics: returns findings · Structured model output is normalized into editor-ready diagnostics.
- Diagnostics → Findings tree: feeds tree · Diagnostics are also surfaced in the findings sidebar.
- Diagnostics → Comments: feeds comments · Diagnostic ranges and messages back inline comments.
- Diagnostics → Quick fixes: enables fixes · Only actionable, range-bound findings become quick fixes.
- Review service → PR summary: summarizes change · Review output can be transformed into PR-style descriptions.
- Review service → Export: exports output · Normalized review artifacts can be consumed by other surfaces.