CraftLens — AI Code Quality Linter & Continuous Release Assurance

A second pair of eyes for modern software.
Find problems, understand why they matter, and improve them with confidence.

What CraftLens Is & Why It Exists

AI coding assistants write code faster than ever, but speed often comes at the cost of craft. AI-generated and rapidly assembled code frequently introduces subtle yet serious flaws:

• Shallow Patchwork & Silent Failures: Swallowed exceptions, missing return paths, unhandled promise rejections, and any escape hatches.
• Accessibility Oversights: Icon-only buttons without accessible names, missing keyboard focus outlines (:focus-visible), and broken color contrast.
• Generic AI UI Patterns: Monolithic components, card soup, uncalibrated visual hierarchy, identical button styling, and placeholder UX copy.
• Security & Supply Chain Risks: Hardcoded secrets, unescaped HTML injections, shell injection patterns, and unpinned dependencies.
• Untrusted Quick Fixes: Fixes that fix one line but introduce syntax errors, broken imports, or subtle regressions elsewhere in the codebase.

CraftLens operates as an automated senior staff engineer, security auditor, and product designer inside Visual Studio Code. It provides continuous static analysis, AST-based rule execution, unified issue management, safe atomic code changes, living repository ledgers, and full pre-release assurance.

What CraftLens Is NOT

• It is NOT an AI detector. CraftLens never attempts to determine whether code was typed by a human or generated by an LLM.
• It does not emit vague warnings like "AI code detected". It diagnoses concrete engineering defects: "Exception is silently swallowed. The catch block discards the error without logging or recovery."
• It does not ban modern libraries or frameworks (such as Tailwind CSS, React, Vue, Svelte, or Lucide). Technologies become issues only when misused in violation of core accessibility, security, or maintainability invariants.

Core Capabilities

1. Continuous Auto-Audit & In-Editor Intelligence

• AST Rule Engine: High-performance, multi-language static analysis inspecting code structure, design systems, accessibility, and security patterns.
• Inline CodeLens & Rich Hover: Clean, non-intrusive action links (Fix, Explain, Ignore) displayed directly above findings in the editor.
• Audit Levels: Configurable sensitivity from 🟢 Easy (high-confidence crashes and critical bugs) to 🟡 Moderate (recommended balance), 🟠 Hard (architectural smells and intent debt), and 🔴 Strict (production-grade rigor).

2. QA, Code Review & Release Assurance Engine (qa-release-assurance)

CraftLens includes an autonomous, end-to-end quality and release assurance pipeline powered by 13 specialized built-in analyzers:

• TypeScript & Boundary Analyzer: Validates compiler diagnostics and guards against unsafe property chains across data boundaries.
• Extension Manifest Analyzer: Verifies manifest structure, VS Code engine compatibility, icons, assets, and activation events.
• Command Registry Analyzer: Cross-references manifest declarations against active code handlers to guarantee zero broken or undefined commands.
• Runtime Safety Analyzer: Detects resource leaks, undisposed event subscriptions, orphaned timers, and disposed webview access.
• Webview Analyzer: Audits webview implementations for Content Security Policy (CSP) compliance, absence of unsafe-eval, unique DOM element IDs, and full keyboard accessibility.
• State Consistency Analyzer: Guarantees a single source of truth across all views without state divergence.
• Fix Engine Analyzer: Verifies that diff previews match applied patches identically without unpredictable regeneration.
• Dependency & Supply Chain Analyzer: Flags wildcards, deprecated packages, and conflicting version constraints.
• Security Analyzer: Inspects for leaked API tokens (OpenAI, GitHub, AWS, Google), private keys, shell command injections, and unescaped HTML rendering.
• Code Quality Analyzer: Catches swallowed exceptions, invalid NaN direct comparisons, and dead code branches.
• Test Suite Analyzer: Classifies and discovers unit, integration, webview, and regression test suites.
• Packaging Analyzer: Validates .vscodeignore patterns and VSIX bundle health.
• Architecture Boundary Analyzer: Enforces architectural boundaries between headless core services and host integration layers.

3. Universal Safe Fix & Regression Validation Pipeline

CraftLens treats every code modification as untrusted until proven safe:

Finding Identified
       ↓
Fix Capability Resolution
       ↓
Patch Generation
       ↓
Pre-Write Validation (Syntax, Structure, AST)
       ↓
Real Diff Preview Generation
       ↓
User Review & Approval
       ↓
Atomic Disk Application
       ↓
Post-Write Compiler & AST Validation
       ↓
Targeted Re-Analysis & Regression Check
       ↓
Verified & Recorded  (or Rolled Back Atomically on Failure)

• Supported Languages: TypeScript, TSX, JavaScript, JSX, CSS, SCSS, LESS, HTML, JSON, JSONC, Markdown, YAML, Vue, and Svelte.
• Guaranteed Rollback: If a fix fails syntax parsing, structural validation, or introduces a new regression, CraftLens rolls back the change atomically, keeps the issue open, and reports the exact failure cause.

4. Single Source of Truth

• A canonical selectedIssueId drives the entire UI. Selecting an issue in the Sidebar, the Project Overview, or the Problems Panel immediately synchronizes all surfaces.
• Canonical Fix Capability: Guarantees that all UI surfaces agree on whether an automated fix is available (canApply: true) or whether guided architectural recommendations apply (canApply: false).

5. Four Canonical Project Markdown Artifacts (.craftlens/)

CraftLens maintains living, transparent project ledgers directly in your repository:

• issues.md: The authoritative registry of open and resolved issues, categorized with severity, file locations, confidence scores, root causes, and remediation guidance.
• suggestions.md: Actionable architectural recommendations, distinguishing between automated fixes, skill-assisted repairs, and pattern guidance.
• changes.md: Immutable log of user-approved changes, diffs, and verification outcomes.
• checklist.md: Living Master Audit Checklist tracking domain-by-domain verification states ([x] PASSED, [ ] FAILED, [-] NOT APPLICABLE).

6. Interactive Sidebar & Project Overview Bento Dashboard

• Sidebar Views: Fast switching across Audit (filterable issue list), Checklist (living requirements), Skills (specialized intelligence modules), Rules (rule explorer and overrides), and Metrics (health grades and living file links).
• Project Overview Dashboard: Rich Bento Grid with overall project health score, category breakdown, multi-location issue navigation, live side-by-side diff preview, and dedicated QA & Release assurance tab.

Supported Environments & File Formats

Quick Start & Usage Workflow

1. Install the Extension: Install CraftLens from the VS Code Marketplace or from the packaged .vsix file.
2. Open Your Project: CraftLens automatically initializes workspace inspection on startup.
3. Open the Sidebar: Click the CraftLens icon in the VS Code Activity Bar to open the interactive panel.
4. Run an Audit:
   • Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) and select CraftLens: Run Audit.
   • Choose your review domain: UI / UX, Frontend Security, Backend Security, Practical Security, Code Quality, or Full Audit.
5. Inspect & Fix Issues:
   • Click any finding in the Sidebar or Problems panel to jump to the code location.
   • Click Review Proposed Changes or Apply Fix to review the exact side-by-side diff.
   • Accept the change: CraftLens validates syntax and regression safety before permanently saving.
6. Track Progress: Open .craftlens/checklist.md to see requirements turn into [x] PASSED in real time.
7. Verify Release Readiness: Run CraftLens: Run QA or CraftLens: Verify Release prior to publishing or merging pull requests.

Commands

All commands are accessible via the VS Code Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Configuration Settings

Customize CraftLens in your VS Code settings (settings.json):

{
  // Enable or disable CraftLens analysis globally
  "craftlens.enabled": true,

  // Minimum severity threshold: "blocker" | "error" | "warning" | "suggestion" | "info"
  "craftlens.severity": "warning",

  // Audit sensitivity level: "easy" | "moderate" | "hard" | "strict"
  "craftlens.auditLevel": "moderate",

  // Continuously update Master Audit Checklist as files change
  "craftlens.autoAudit": true,

  // Display quiet inline CodeLens hints above findings in the editor
  "craftlens.enableCodeLens": true,

  // Persist Master Audit Checklist and state across VS Code sessions
  "craftlens.persistAudit": true,

  // Run CraftLens diagnostics whenever a file is saved
  "craftlens.scanOnSave": true,

  // Run fast-path diagnostics as files are edited (debounced)
  "craftlens.scanOnChange": true,

  // Maximum number of diagnostics reported per individual file
  "craftlens.maxDiagnosticsPerFile": 50
}

In-Code Suppressions

When a pattern is intentional, you can cleanly suppress findings using comments:

// Suppress next line for a specific rule
// craftlens-disable-next-line AP-008
try { riskyOperation(); } catch {}

// Suppress current line with an explanatory reason
try { cleanup(); } catch {} // craftlens-disable-line AP-008 -- reason: safe cleanup

// Suppress all CraftLens checks for the entire file
/* craftlens-disable-file */

Privacy & Security Statement

We believe developer tooling must respect privacy, intellectual property, and security above all else:

1. Does CraftLens send your code to external servers?
   No. CraftLens is strictly 100% local-first. All AST parsing, static analysis, QA analyzers, rule execution, and fix generation run entirely on your local machine inside the VS Code Extension Host process. Your code is never transmitted to any external server or cloud service.

2. What data is stored locally vs transmitted?
   All generated artifacts (audit history, checklists, issues, changes) are stored solely within your local workspace's .craftlens/ folder. Zero bytes of source code, AST nodes, or diagnostics are ever transmitted across the network.

3. How are API keys handled?
   CraftLens requires no API keys to run its full suite of built-in analyzers, rules, and deterministic fix engine. If you optionally choose to connect an external AI model provider (Bring Your Own Key), keys are stored securely using VS Code's encrypted native SecretStorage API and are never written to disk, version control, or log files.

4. Does CraftLens collect telemetry or analytics?
   No. CraftLens contains zero telemetry, zero crash reporting beacons, and zero usage tracking. We do not track keystrokes, filenames, project contents, or developer identities.

5. How does CraftLens prevent dangerous code changes?
   CraftLens implements a Universal Safe Fix Pipeline. Every proposed change is treated as untrusted until validated through syntax checking, AST structural validation, compiler type-check verification, and targeted regression scanning. If any safety check fails, changes are rolled back atomically, preserving your code exactly as it was.

License

CraftLens is open source software licensed under the MIT License.