ProjectLens AI

ProjectLens is a VS Code extension that analyzes the workspace you have open and reports on its technologies, code quality, security risks, implementation progress and production readiness. All core analysis is local and deterministic. AI review is optional, works with Groq, OpenAI, Google Gemini or Anthropic Claude, and only runs when you trigger it and approve the exact context that will be sent.

Everything ProjectLens reports is advisory static analysis. Each finding has a confidence level and a detection status. A scan with no findings does not prove a project is secure or complete.

Features

Requirements

• VS Code 1.90 or newer
• Node.js 20+ for development (tested with Node 24)
• Optional, for AI features: an API key from Groq, OpenAI, Google AI Studio or Anthropic
• Optional: a locally installed Gitleaks binary

Getting started (development)

npm install
npm run build        # type-check, bundle the extension (esbuild) and the React webview (Vite)
npm run lint
npm run test         # Vitest unit tests (125 tests, no network required)

Run and debug in the Extension Development Host

1. Open this folder in VS Code.
2. Press F5 and choose Run ProjectLens, or Run ProjectLens on fixture (vulnerable-app) to open a deliberately insecure sample project. Both configurations are in .vscode/launch.json and run npm run build first.
3. In the new window, click the ProjectLens icon in the Activity Bar, then Quick Scan or Full Scan.

For iterative work, run npm run watch:extension and npm run watch:webview in two terminals, then reload the development host window (Developer: Reload Window).

Integration tests

npm run test:integration

This downloads a VS Code build into .vscode-test/ on first run, opens tests/fixtures/vulnerable-app, and runs the Mocha suite in tests/integration/. It covers command registration, Quick and Full Scan, Problems-panel diagnostics, and opening the dashboard.

Build a VSIX package

npm run package      # runs vsce package (vscode:prepublish builds first)
code --install-extension projectlens-0.1.0.vsix

To publish a new version to the Visual Studio Marketplace (publisher SandeepaMallawarachchi):

npx vsce login SandeepaMallawarachchi   # once; paste an Azure DevOps token with Marketplace → Manage scope
npx vsce publish patch                  # bumps the version, builds, and publishes

Commands

Configuration

Requirements-based progress (.projectlens.json)

{
  "version": 1,
  "features": [
    { "id": "auth", "name": "Authentication", "weight": 3, "match": ["auth", "login"] },
    { "id": "billing", "name": "Billing", "weight": 2, "match": ["billing"], "paths": ["app/billing/**"] }
  ]
}

Each feature is matched to detected modules, by keyword (match) or by file glob (paths). Its completion is the mean estimate of the matched modules; a feature with no match counts as 0% (Not detected). Overall completion is:

Completion = Σ(feature weight × estimated completion) / Σ(feature weights)

Without this file, ProjectLens shows Implementation Evidence: the mean completion of the modules it detected. That figure can't account for features that were never started.

Security and privacy

• API keys for every provider are stored only in VS Code SecretStorage, which is backed by the OS keychain, one entry per provider. They are never written to settings, sent to the webview, logged, or included in reports.
• AI requests go directly from the extension host to the selected provider's API, using its official SDK (groq-sdk, openai, @google/genai, @anthropic-ai/sdk). SDKs are loaded only when that provider is first used. The webview's Content Security Policy blocks all network access (connect-src 'none') and allows only nonce-tagged local scripts.
• AI requests run only when you trigger them. Before anything is sent, a modal shows the model, the file excerpts, the token estimate, how many values were redacted, and which files were excluded. Preview Payload opens the exact text.
• The context builder:
  • sends a compact summary of the local analysis plus only the relevant excerpts, within a token budget
  • never sends .env* files, keys, certificates, credential files, lockfiles or generated files
  • redacts detected secrets and private-key bodies
  • uses workspace-relative paths only
• AI output is treated as untrusted data. It is validated with Zod, file references that weren't in the provided context are dropped, and the output is rendered as plain text. It is never executed and never applied to your files.
• Secrets are never shown in full. The dashboard, reports, logs and diagnostics show redacted previews (for example gsk_•••••• (56 chars)).
• Repository code is never executed. ProjectLens doesn't run package scripts, migrations or the repository's ESLint config (flat configs are JavaScript). ESLint runs in memory with a built-in rule set.
• Workspace Trust: in restricted mode only the in-memory analyzers run, and Gitleaks is disabled. Gitleaks is never installed automatically; ProjectLens runs it only from an absolute path or PATH, with execFile (no shell), a timeout and --redact.
• Local storage: the latest result and a per-file analysis cache are kept in the workspace storage folder. They hold redacted single-line evidence and structural facts, never full source. History and AI insights are kept in workspaceState.
• No telemetry.

Architecture

src/
  extension.ts                activation, command registration
  controller.ts               app state, scan/AI orchestration, typed webview messages
  config.ts                   settings access
  core/                       VS Code-independent engine
    fileDiscovery.ts          walk, .gitignore, excludes, binary and size limits, multi-root
    fileContext.ts            per-file context, roles (server/client/test), TS AST
    scanner.ts                Quick/Full pipeline, cancellation, yielding, cache use
    cache.ts                  per-file analysis cache (mtime/size/mode/version stamp)
    findings.ts               finding factory, stable IDs, dedupe, sorting
    report.ts                 JSON and Markdown reports
  analyzers/
    technology/               catalog, manifests and lockfiles, evidence-based detector
    quality/                  AST rules, in-memory ESLint, markers, duplicates
    security/                 secret patterns, env, AST rules, authorization, config, Gitleaks adapter
    progress/                 structural facts, module estimator, requirements
    dependencies/             offline dependency checks
  scoring/scoring.ts          check-based, explainable scores and recommended actions
  ai/
    AIProvider.ts             provider abstraction
    providers/                Groq and OpenAI (shared Chat Completions base), Gemini, Anthropic Claude;
                              structured output with fallback modes, shared error mapping
    retry.ts, errors.ts       backoff with Retry-After, error taxonomy
    contextBuilder.ts         selection, exclusion, redaction, budgeting
    aiService.ts              consent, limits, batching, validation
  models/                     shared types, Zod schemas, message protocol
  storage/                    SecretStorage wrapper, scan, history and insight storage
  views/                      sidebar and dashboard webviews, CSP HTML, diagnostics, navigation
webview/src/                  React dashboard (components, pages, hooks, styles)
tests/unit/                   Vitest suites
tests/integration/            VS Code Extension Host tests
tests/fixtures/               healthy-nextjs, vulnerable-app, partial-saas

To add support for a new language, add an analyzer that takes a FileContext and returns Finding[], then register it in core/scanner.ts's analyzeFile. To add a new AI provider, implement AIProvider.

Known limitations

• AST-based analysis covers JavaScript and TypeScript only. Other languages get only the secret, environment and configuration rules, and the scan warns about this.
• Authorization checks are heuristic and are always marked Needs review. Global middleware lowers their severity, but ProjectLens can't prove that a route is protected.
• The dependency advisory list is a small, curated offline list. Run npm audit or an SCA tool for complete coverage.
• tsconfig extends chains aren't followed when checking strict.
• Express routes mounted under a prefix are matched by path suffix when checking UI→API connections. Projects using Next.js rewrites or a Vite proxy skip this check.
• Remote and virtual file systems aren't supported. Remote SSH and WSL work because the extension runs on the remote host.
• Gitleaks integration uses gitleaks detect --no-git and has been unit-tested against its JSON report format, but not against a live binary in this repository's CI.
• All four providers are covered by mocked API tests only. Running them against the live APIs requires your own keys.
• Claude requests on models that support it (Opus 5/5.5, Fable 5, Sonnet 5.5) enable Anthropic's server-side refusal fallback (fallbacks: "default"). Any remaining refusal from a provider is reported as "declined".