LogSense

Imported from rishabhsharmaa/LogSense (AGENTS.md). Install upstream with npx skills add rishabhsharmaa/LogSense. Copyright stays with the author.

LogSense — Agent & Developer Codebase Map

This document is the fast-routing guide for the LogSense project. Whenever a task or prompt is received, use this document to immediately jump to the exact file and symbol rather than running global searches across the repository.

⚡ Fast Task-to-File Routing Directory

🏛️ Architecture Overview

[VS Code User / Editor]
       │
       │  (Select error -> Ctrl+Shift+L or Right-Click Context Menu)
       ▼
[extension/src/extension.ts] (Extension Host)
       │
       │  postMessage ("setLog", "apiKeyStatus", "modelStatus")
       ▼
[extension/webview-ui/src/App.tsx] (React 19 + Tailwind Webview)
       │
       │  HTTP POST /api/v1/analyze (with log, language, context, optional BYOK key & model)
       ▼
[backend/src/server.js]
       │
       ├──> [backend/src/middlewares/sanitizer.js] (Strips sk-*, AKIA*, paths before AI)
       │
       └──> [backend/src/controllers/analyzeController.js]
                 │
                 ├──> Google Gemini AI (@google/generative-ai)
                 │         └─ Prompt: Explanation, Original Code, Suggested Fix
                 │
                 └──> [backend/src/models/LogHistory.js] -> MongoDB Atlas

📁 Detailed Codebase Breakdown

1. Backend (/backend)

• backend/package.json: Node.js dependencies (@google/generative-ai, express, mongoose, cors, dotenv). Scripts: npm start, npm run dev (node --watch).
• backend/src/server.js: Express application initialization, MongoDB connection via Mongoose, CORS configuration, JSON body parsing limit (1mb), /health endpoint, listening on port process.env.PORT || 3001.
• backend/src/routes/api.js:
  • POST /api/v1/analyze: Chained with sanitizerMiddleware, runs analyze.
  • GET /api/v1/history/:userId: Runs getHistory.
• backend/src/controllers/analyzeController.js:
  • getModel(userApiKey, modelName): Instantiates Gemini model using per-request user BYOK key if supplied; otherwise uses cached instance with process.env.GEMINI_API_KEY.
  • buildprompt(log, language, context): Strict 3-section prompt asking for ## Explanation, ## Original Code (verbatim for search matching), and ## Suggested Fix (drop-in replacement).
  • analyze(req, res): Manages Gemini generation with 5x exponential backoff retry on 429 quota errors, regex extracts the 3 sections, strips diff prefixes (+/-), persists record to MongoDB, and returns JSON payload.
• backend/src/controllers/historyController.js:
  • getHistory(req, res): Single aggregation pipeline using $facet to simultaneously count total and retrieve paginated history records sorted newest first.
• backend/src/middlewares/sanitizer.js:
  • sanitize(text): Redacts API keys (sk-..., AKIA..., generic token/secret/apikey) and user file paths (C:\Users\..., /Users/..., /home/...) using string guards prior to regex execution for speed.
  • sanitizerMiddleware(req, res, next): Middleware mutating req.body.log in place.
• backend/src/models/LogHistory.js:
  • Mongoose model for LogHistory storing userId, rawLog (capped at 5,000 chars), languageContext, aiExplanation, aiSuggestedFix, createdAt.
  • Compound index: { userId: 1, createdAt: -1 }.

2. Extension Host (/extension)

• extension/package.json:
  • Extension ID: logsense by Rishabh-Sharma.
  • Contributed commands: logsense.start, logsense.analyzeSelection, logsense.analyzeTerminalSelection, logsense.setApiKey, logsense.removeApiKey.
  • Context menus: Editor selection (logsense.analyzeSelection), Terminal selection (logsense.analyzeTerminalSelection).
  • Keybinding: Ctrl+Shift+L (Cmd+Shift+L on macOS).
  • Settings: logsense.backendUrl (default: https://logsense-backend.onrender.com).
• extension/src/extension.ts:
  • Secret Management: Stores user's personal Gemini key in VS Code context.secrets under "logsense.geminiApiKey".
  • Model Storage: Persists user model choice in context.globalState under "logsense.selectedModel".
  • Terminal Selection: Uses workbench.action.terminal.copySelection with clipboard snapshot/restore with 1s safety timeouts.
  • Webview Host: openPanel() opens WebviewPanel beside the editor with local resource roots to webview-ui/dist.
  • IPC Protocol:
    • Host $\rightarrow$ Webview: apiKeyStatus, apiKeyValue, modelStatus, modelValue, backendUrl, setLog.
    • Webview $\rightarrow$ Host: webviewReady, getApiKey, promptSetApiKey, setModel, getModel, applyFix, showError, showInfo.
  • "Apply Fix" 3-Tier Algorithm:
    1. Exact substring matching (docText.indexOf(trimmedOrig)).
    2. Sliding window trimmed-line sequence matching.
    3. Anchor matching (first line to last line of original block).
    4. Guarded fallback to selection or cursor position with safety modal if selection is >3x fix line count.

3. Webview UI (/extension/webview-ui)

• extension/webview-ui/src/App.tsx:
  • Root component coordinating state for log text, language, framework, API keys, selected model, and backend URL.
  • Handles asynchronous fetch() requests to ${backendUrl}/api/v1/analyze.
  • Supports request abortion (AbortController) when user re-analyzes or clears.
• extension/webview-ui/src/components/LogInputArea.tsx:
  • Monospace input area with glassmorphic styling and visual hint badge for Ctrl+Shift+L.
• extension/webview-ui/src/components/ContextSelectors.tsx:
  • Language dropdown: TypeScript, JavaScript, Python, Java, C#, C++, Go, Rust, Ruby, PHP, Swift, Kotlin, Dart, Shell.
  • Framework dropdown: None, React, Next.js, Angular, Vue.js, Express.js, Spring Boot, Django, Flask, Rails, Laravel, ASP.NET, Flutter, NestJS, FastAPI.
• extension/webview-ui/src/components/ResultPanel.tsx:
  • Renders Explanation and Suggested Fix blocks.
  • Custom non-backtracking markdown parser parseBlocks().
  • stripDiffMarkers() removes accidental diff markers (+, -) from code outputs.
  • Syntax highlighting with line numbers via Prism oneDark.
  • "Apply Fix" button sending postMessage("applyFix", { text, originalCode }) to extension host.
• extension/webview-ui/src/hooks/useVscode.ts:
  • Singleton caching wrapper around window.acquireVsCodeApi().
  • Exported helper postMessageToExtension(command, data).
• extension/webview-ui/src/index.css:
  • CSS custom properties for LogSense theme (--ls-bg, --ls-card, --ls-accent, --ls-glow).

🛠️ Build & Development Commands

🧭 Step-by-Step Scenario Guide

Scenario 1: Changing or improving the Gemini prompt

1. Open backend/src/controllers/analyzeController.js.
2. Locate buildprompt(log, language, context) around line 53.
3. Update instructions, section headers, or formatting guidelines.
4. If output structure changes, adjust regex parsing around line 145 in analyze().

Scenario 2: Adding a new programming language or framework

1. Open extension/webview-ui/src/components/ContextSelectors.tsx.
2. Add the item to LANGUAGES or FRAMEWORKS arrays at lines 10–20.
3. Run npm run build inside extension/webview-ui.

Scenario 3: Modifying how "Apply Fix" updates user files

1. Open extension/src/extension.ts.
2. Locate case "applyFix": around line 357.
3. Modify or add replacement matching strategies (exact match, line-by-line, or AST).
4. Run npm run compile inside extension.

Scenario 4: Adding secret or path redaction patterns

1. Open backend/src/middlewares/sanitizer.js.
2. Add a new { guard, regex, replacement } object to SECRET_PATTERNS or PATH_PATTERNS.