FPGA Error Decoder

FPGA Error Decoder turns noisy FPGA/EDA tool logs into actionable VS Code Problems and secure reports. It helps engineers quickly understand messages from Yosys, Verilator, GHDL, Icarus, nextpnr, openFPGALoader and vendor EDA logs without pretending to replace vendor documentation, timing closure, CDC/RDC analysis or signoff.

Use it when a synthesis, lint, simulation, place-and-route or programming run fails and the raw .log/.rpt/.jou/.txt output is too long to scan manually. The extension parses the log locally, matches validated JSON rules, groups related diagnostics, shows evidence and confidence, and gives next actions with privacy limits made explicit.

fpga.chat support is optional. Redacted one-shot requests require preview and confirmation. Workspace online warnings can send raw decoded logs only after trusted-workspace consent; after that consent, future decoded logs in that workspace are sent raw by default until disabled.

Why It Exists

• FPGA/EDA errors often bury the real cause across long logs and report files.
• Different tools format the same class of failure differently, which makes Problems diagnostics inconsistent.
• Vendor logs may contain private design, license, host or path data, so upload behavior must be explicit and inspectable.
• LLM/AI agents need a narrow, evidence-first contract: classify logs, cite local evidence, keep confidence bounded, and never invent vendor semantics.

MVP Features

• Decode current .log/.rpt/.jou/.txt file, selected text, clipboard text, a local VS Code Task result, explicit external-extension payloads, or opt-in VS Code Terminal Shell Integration output.
• Built-in JSON rule packs with schema validation and confidence scoring.
• Starter coverage for Yosys missing module, Verilator WIDTH/UNOPTFLAT, GHDL entity resolution, Icarus syntax, nextpnr constraints, openFPGALoader board/cable issues, plus a 78-rule synthetic diagnosis core for common missing file/include/top, syntax, timing-constraint, pin/IO, license, IP, placement/routing and programming failures.
• A 104-case public synthetic corpus and local corpus eval command track tool detection, recall-like coverage, precision-like false positive rate, abstain pass rate, unknown rate and fallback rate.
• Parse-only timing summary for visible WNS/TNS/slack, critical path endpoints, clock pairs and unconstrained-path hints. It is not timing closure or signoff.
• Project Context Lite scans local filenames and small HDL/constraint/build files for top candidates, source/file-order hints, include dirs, generated IP refs and constraints without executing scripts or vendor tools.
• VS Code Problems diagnostics from an owned DiagnosticCollection with source FPGA Error Decoder.
• CodeActions for report, explanation, redacted repro command, docs, fpga.chat preview, ignore, rule draft, and log navigation.
• CodeActions include local evidence search and project-context verification to help test a hypothesis without editing HDL automatically.
• Secure Webview report with CSP, escaped content, evidence, fixes, confidence, limitations, privacy note, and export buttons.
• Tree views for recent runs, failed runs, and rule packs.
• Project metadata for fpga.chat, fpga.camp, and GitHub issue reporting from the report Webview.
• Optional fpga.chat online warnings for decoded FPGA tool/EDA logs. No logs are uploaded before consent; after workspace-level raw-log consent, future decoded logs in that workspace are sent as raw logs by default. A status bar item shows whether raw sharing is on and exposes last-upload audit metadata without raw content. The default response mode is status-only to avoid noisy daily workflow interruptions.
• Redaction for paths, usernames, hostnames, private IPs, emails, tokens, internal URLs, private Git URLs, and license paths.

Commands

• FPGA Error Decoder: Decode Current Log
• FPGA Error Decoder: Decode Selection
• FPGA Error Decoder: Decode Clipboard Text
• FPGA Error Decoder: Decode External Log Payload
• FPGA Error Decoder: Run Task and Decode
• FPGA Error Decoder: Open Report
• FPGA Error Decoder: Preview fpga.chat Payload
• FPGA Error Decoder: Ask fpga.chat
• FPGA Error Decoder: Preview fpga.chat Log Payload
• FPGA Error Decoder: Enable fpga.chat Online Warnings
• FPGA Error Decoder: Disable fpga.chat Online Warnings
• FPGA Error Decoder: Open fpga.chat Online Warning Status
• FPGA Error Decoder: Analyze FPGA Project Context
• FPGA Error Decoder: Run Decoder Corpus Eval
• FPGA Error Decoder: Decode Log Artifact
• FPGA Error Decoder: Search Workspace for Evidence
• FPGA Error Decoder: Insert Recommended FPGA Task
• FPGA Error Decoder: Manage Rule Packs
• FPGA Error Decoder: Report Issue or UX Feedback

Build And Test

npm install
npm run compile
npm test
npm run package

npm test runs Node unit tests for parser/rules/redaction/report rendering and an @vscode/test-electron activation/decode integration test. The integration runner uses /usr/bin/code when available; otherwise @vscode/test-electron may need network access to resolve VS Code.

Local Use

1. Open the repository in VS Code.
2. Press F5 to launch Extension Development Host.
3. Open samples/public/verilator/width.log.
4. Run FPGA Error Decoder: Decode Current Log.
5. Check the report Webview and Problems diagnostics.

To install a local VSIX after packaging:

code --install-extension fpga-error-decoder-0.1.0.vsix

Or build and install into the local VS Code in one step:

npm run install:local

Privacy And Limits

• No private log upload by default.
• Terminal Shell Integration capture is off by default and only works in trusted workspaces after explicit setting opt-in.
• No raw HDL, raw logs, full paths, tokens, hostnames, or private repo URLs in telemetry.
• fpga.chat is disabled by default. Ask fpga.chat sends only a redacted payload after preview and confirmation.
• fpga.chat Online Warnings may send raw decoded logs only after a trusted workspace, exact payload preview, token prompt, and explicit workspace-level consent. After consent, raw decoded logs are sent by default for future decodes in that workspace until disabled with FPGA Error Decoder: Disable fpga.chat Online Warnings.
• Raw-sharing status and last upload metadata are visible through the status bar and Open fpga.chat Online Warning Status; this metadata stores hashes/ids/status only, not raw logs or tokens.
• Vendor tools are local only. The extension does not execute Vivado, Quartus, Gowin, or Lattice tools in a public cloud.
• Timing support is parse-only report triage. This is not HDL IDE functionality, timing closure, CDC/RDC analysis, formal proof, or signoff.
• Vendor starter rules are intentionally low confidence until validated against legal/public corpus.
• The bundled corpus is synthetic/public-safe. It is not a real vendor-approved corpus.

Documentation

• Security
• Privacy
• Contributing
• Rule Pack Guide
• FPGA/EDA Documentation Pack
• fpga.chat API Contract
• VS Code Tasks Guide
• UX Audit and UX Test Plan
• Русская инструкция по установке и работе
• LLM Agent Guide