🔍 CodeLens-AI

AI 生成代码智能诊断引擎
72 条内置规则 · 支持 React / Vue / Svelte / HTML 多框架 · 零外部依赖

简体中文 · 繁體中文 · English

🎉 项目介绍

CodeLens-AI 是一款轻量级的 AI 生成代码智能诊断引擎，专为前端开发者打造。它能够自动检测 React、Vue、Svelte 和 HTML 组件代码中的质量问题，包括性能反模式、安全漏洞、可访问性问题和 AI 生成代码的典型特征。

灵感来源于 GitHub 热门项目 react-doctor，但做了全面的差异化升级：从仅支持 React 扩展到多框架支持，从 npm 包改为零依赖 Python CLI 工具，新增 AI 代码特征识别、自定义规则引擎和 TUI 交互界面。

✨ 核心特性

• 🔍 72 条内置诊断规则 — 覆盖 React(17) / Vue(13) / Svelte(11) / HTML(10) / AI 特征(11) / 安全(10) 六大类别
• 🚀 零外部依赖 — 纯 Python 标准库实现，无需安装任何第三方包
• 🎯 多框架支持 — React、Vue、Svelte、HTML 自动识别
• 🤖 AI 代码特征识别 — 检测过度注释、冗余包装、机械式模式等 AI 生成代码的典型特征
• 🖥️ CLI + TUI 双模式 — 命令行快速诊断 + 交互式终端界面
• 📊 多格式输出 — 彩色终端、结构化 JSON、独立 HTML 报告
• ⚙️ 自定义规则引擎 — 通过 YAML 配置文件自定义检测规则
• 🔧 CI/CD 集成 — 支持 GitHub Actions，JSON 报告输出，语义化退出码
• 🌍 多语言文档 — 简体中文、繁体中文、English 三语文档

🚀 快速开始

环境要求

• Python 3.9 或更高版本
• 无需安装任何第三方依赖

安装方式

# 克隆仓库
git clone https://github.com/gitstq/CodeLens-AI.git
cd CodeLens-AI

# 安装（可选）
pip install -e .

使用示例

# 检查单个文件
python -m codelens_ai check src/App.jsx

# 扫描整个目录
python -m codelens_ai scan ./src --framework react

# 启动 TUI 交互界面
python -m codelens_ai tui

# 查看所有规则
python -m codelens_ai rules

# 输出 JSON 报告
python -m codelens_ai check src/App.jsx --output json > report.json

# 输出 HTML 报告
python -m codelens_ai scan ./src --output html --report-path ./report.html

# 指定最低严重级别
python -m codelens_ai scan ./src --severity warning

# 忽略特定规则
python -m codelens_ai scan ./src --ignore ai-006,ai-008

📖 详细使用指南

CLI 参数说明

自定义配置文件 (.codelens.yaml)

# 框架配置
framework: auto  # auto/react/vue/svelte/html

# 严重级别过滤
severity: warning  # error/warning/info/hint

# 忽略规则
ignore:
  - ai-006
  - ai-008

# 规则配置覆盖
rules:
  react-001:
    severity: error
    enabled: true
  ai-009:
    severity: hint

# 输出配置
output:
  format: terminal  # terminal/json/html
  color: true

CI/CD 集成 (GitHub Actions)

name: CodeLens AI Check
on: [push, pull_request]
jobs:
  codelens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -e .
      - run: python -m codelens_ai scan ./src --output json --severity error > codelens-report.json
      - run: |
          if [ $? -ne 0 ]; then
            echo "::error::CodeLens-AI detected code quality issues"
            exit 1
          fi

退出码说明

💡 设计思路与迭代规划

设计理念

• 零依赖哲学：不引入任何第三方依赖，确保在任何 Python 环境下都能直接运行
• 多框架统一：一套工具覆盖主流前端框架，减少工具链碎片化
• AI 感知：不仅检测传统代码质量问题，还能识别 AI 生成代码的典型特征
• 开发者友好：清晰的错误提示、可操作的修复建议、丰富的输出格式

技术选型原因

• Python 标准库：零依赖的核心优势，argparse 处理 CLI，re 处理正则分析，json 处理数据交换
• 正则表达式分析：对 JSX / Vue 模板等非标准语法，正则比 AST 更灵活实用
• curses TUI：Python 内置的终端 UI 库，无需额外安装

后续迭代计划

• 支持 TypeScript / TSX 文件分析
• 支持 Angular 模板诊断
• 添加 --fix 自动修复功能
• 支持自定义规则插件系统
• 添加 VS Code 扩展
• 支持增量扫描（仅检查变更文件）
• 添加 SARIF 格式输出（GitHub Code Scanning）

📦 打包与部署指南

本项目为 Python CLI 工具，无需打包即可直接使用：

# 直接运行
python -m codelens_ai scan ./src

# 或安装后使用
pip install -e .
codelens scan ./src

兼容环境

• Python 3.9+
• Linux / macOS / Windows
• 无需 Node.js、npm 或其他运行时

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-rule)
3. 提交更改 (git commit -m 'feat: 添加新的诊断规则')
4. 推送到分支 (git push origin feature/amazing-rule)
5. 创建 Pull Request

提交规范：遵循 Angular 提交规范

• feat: 新增功能
• fix: 修复问题
• docs: 文档更新
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具相关

📄 开源协议

本项目基于 MIT License 开源。

简体中文 · 繁體中文 · English

🎉 專案介紹

CodeLens-AI 是一款輕量級的 AI 生成程式碼智慧診斷引擎，專為前端開發者打造。它能夠自動偵測 React、Vue、Svelte 和 HTML 元件程式碼中的品質問題，包括效能反模式、安全漏洞、無障礙性問題和 AI 生成程式碼的典型特徵。

靈感來源於 GitHub 熱門專案 react-doctor，但做了全面的差異化升級：從僅支援 React 擴展到多框架支援，從 npm 套件改為零依賴 Python CLI 工具，新增 AI 程式碼特徵識別、自訂規則引擎和 TUI 互動介面。

✨ 核心特性

• 🔍 72 條內建診斷規則 — 覆蓋 React(17) / Vue(13) / Svelte(11) / HTML(10) / AI 特徵(11) / 安全(10) 六大類別
• 🚀 零外部依賴 — 純 Python 標準函式庫實作，無需安裝任何第三方套件
• 🎯 多框架支援 — React、Vue、Svelte、HTML 自動識別
• 🤖 AI 程式碼特徵識別 — 偵測過度註解、冗餘包裝、機械式模式等 AI 生成程式碼的典型特徵
• 🖥️ CLI + TUI 雙模式 — 命令列快速診斷 + 互動式終端介面
• 📊 多格式輸出 — 彩色終端、結構化 JSON、獨立 HTML 報告
• ⚙️ 自訂規則引擎 — 透過 YAML 設定檔自訂偵測規則
• 🔧 CI/CD 整合 — 支援 GitHub Actions，JSON 報告輸出，語意化退出碼
• 🌍 多語言文件 — 簡體中文、繁體中文、English 三語文件

🚀 快速開始

環境需求

• Python 3.9 或更高版本
• 無需安裝任何第三方依賴

安裝方式

# 克隆倉庫
git clone https://github.com/gitstq/CodeLens-AI.git
cd CodeLens-AI

# 安裝（可選）
pip install -e .

使用範例

# 檢查單個檔案
python -m codelens_ai check src/App.jsx

# 掃描整個目錄
python -m codelens_ai scan ./src --framework react

# 啟動 TUI 互動介面
python -m codelens_ai tui

# 查看所有規則
python -m codelens_ai rules

# 輸出 JSON 報告
python -m codelens_ai check src/App.jsx --output json > report.json

# 輸出 HTML 報告
python -m codelens_ai scan ./src --output html --report-path ./report.html

# 指定最低嚴重級別
python -m codelens_ai scan ./src --severity warning

# 忽略特定規則
python -m codelens_ai scan ./src --ignore ai-006,ai-008

📖 詳細使用指南

CLI 參數說明

自訂設定檔 (.codelens.yaml)

# 框架設定
framework: auto  # auto/react/vue/svelte/html

# 嚴重級別過濾
severity: warning  # error/warning/info/hint

# 忽略規則
ignore:
  - ai-006
  - ai-008

# 規則設定覆蓋
rules:
  react-001:
    severity: error
    enabled: true
  ai-009:
    severity: hint

# 輸出設定
output:
  format: terminal  # terminal/json/html
  color: true

CI/CD 整合 (GitHub Actions)

name: CodeLens AI Check
on: [push, pull_request]
jobs:
  codelens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -e .
      - run: python -m codelens_ai scan ./src --output json --severity error > codelens-report.json
      - run: |
          if [ $? -ne 0 ]; then
            echo "::error::CodeLens-AI detected code quality issues"
            exit 1
          fi

退出碼說明

💡 設計思路與迭代規劃

設計理念

• 零依賴哲學：不引入任何第三方依賴，確保在任何 Python 環境下都能直接執行
• 多框架統一：一套工具覆蓋主流前端框架，減少工具鏈碎片化
• AI 感知：不僅偵測傳統程式碼品質問題，還能識別 AI 生成程式碼的典型特徵
• 開發者友善：清晰的錯誤提示、可操作的修復建議、豐富的輸出格式

技術選型原因

• Python 標準函式庫：零依賴的核心優勢，argparse 處理 CLI，re 處理正則分析，json 處理資料交換
• 正則表示式分析：對 JSX / Vue 模板等非標準語法，正則比 AST 更靈活實用
• curses TUI：Python 內建的終端 UI 函式庫，無需額外安裝

後續迭代計畫

• 支援 TypeScript / TSX 檔案分析
• 支援 Angular 模板診斷
• 新增 --fix 自動修復功能
• 支援自訂規則外掛系統
• 新增 VS Code 擴充功能
• 支援增量掃描（僅檢查變更檔案）
• 新增 SARIF 格式輸出（GitHub Code Scanning）

📦 打包與部署指南

本專案為 Python CLI 工具，無需打包即可直接使用：

# 直接執行
python -m codelens_ai scan ./src

# 或安裝後使用
pip install -e .
codelens scan ./src

相容環境

• Python 3.9+
• Linux / macOS / Windows
• 無需 Node.js、npm 或其他執行環境

🤝 貢獻指南

歡迎貢獻程式碼！請遵循以下步驟：

1. Fork 本倉庫
2. 建立功能分支 (git checkout -b feature/amazing-rule)
3. 提交變更 (git commit -m 'feat: 新增新的診斷規則')
4. 推送到分支 (git push origin feature/amazing-rule)
5. 建立 Pull Request

提交規範：遵循 Angular 提交規範

• feat: 新增功能
• fix: 修復問題
• docs: 文件更新
• refactor: 程式碼重構
• test: 測試相關
• chore: 建構/工具相關

📄 開源協議

本專案基於 MIT License 開源。

简体中文 · 繁體中文 · English

🎉 About

CodeLens-AI is a lightweight intelligent diagnostic engine for AI-generated code, built for frontend developers. It automatically detects quality issues in React, Vue, Svelte, and HTML component code — including performance anti-patterns, security vulnerabilities, accessibility problems, and telltale signs of AI-generated code.

Inspired by the popular GitHub project react-doctor, CodeLens-AI takes a fundamentally different approach: expanding from React-only to multi-framework support, replacing an npm package with a zero-dependency Python CLI tool, and introducing AI code pattern detection, a custom rule engine, and an interactive TUI.

✨ Key Features

• 🔍 72 Built-in Diagnostic Rules — Covering React(17) / Vue(13) / Svelte(11) / HTML(10) / AI Patterns(11) / Security(10)
• 🚀 Zero External Dependencies — Built entirely with the Python standard library
• 🎯 Multi-Framework Support — Auto-detection for React, Vue, Svelte, and HTML
• 🤖 AI Code Pattern Detection — Identifies over-commenting, redundant wrappers, mechanical patterns, and other hallmarks of AI-generated code
• 🖥️ CLI + TUI Dual Mode — Quick command-line diagnostics and an interactive terminal UI
• 📊 Multiple Output Formats — Colorized terminal, structured JSON, and standalone HTML reports
• ⚙️ Custom Rule Engine — Define your own detection rules via YAML configuration files
• 🔧 CI/CD Integration — GitHub Actions support, JSON report output, and semantic exit codes
• 🌍 Multilingual Docs — Documentation in Simplified Chinese, Traditional Chinese, and English

🚀 Quick Start

Prerequisites

• Python 3.9 or later
• No third-party dependencies required

Installation

# Clone the repository
git clone https://github.com/gitstq/CodeLens-AI.git
cd CodeLens-AI

# Install (optional)
pip install -e .

Usage Examples

# Check a single file
python -m codelens_ai check src/App.jsx

# Scan an entire directory
python -m codelens_ai scan ./src --framework react

# Launch the TUI interface
python -m codelens_ai tui

# List all rules
python -m codelens_ai rules

# Output a JSON report
python -m codelens_ai check src/App.jsx --output json > report.json

# Output an HTML report
python -m codelens_ai scan ./src --output html --report-path ./report.html

# Set minimum severity level
python -m codelens_ai scan ./src --severity warning

# Ignore specific rules
python -m codelens_ai scan ./src --ignore ai-006,ai-008

📖 Detailed Guide

CLI Reference

Custom Configuration (.codelens.yaml)

# Framework configuration
framework: auto  # auto/react/vue/svelte/html

# Severity level filter
severity: warning  # error/warning/info/hint

# Ignored rules
ignore:
  - ai-006
  - ai-008

# Rule configuration overrides
rules:
  react-001:
    severity: error
    enabled: true
  ai-009:
    severity: hint

# Output configuration
output:
  format: terminal  # terminal/json/html
  color: true

CI/CD Integration (GitHub Actions)

name: CodeLens AI Check
on: [push, pull_request]
jobs:
  codelens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -e .
      - run: python -m codelens_ai scan ./src --output json --severity error > codelens-report.json
      - run: |
          if [ $? -ne 0 ]; then
            echo "::error::CodeLens-AI detected code quality issues"
            exit 1
          fi

Exit Codes

💡 Design Philosophy & Roadmap

Design Principles

• Zero-Dependency Philosophy: No third-party dependencies whatsoever — runs in any Python environment out of the box
• Multi-Framework Unification: One tool covers all major frontend frameworks, reducing toolchain fragmentation
• AI-Aware: Goes beyond traditional code quality checks to identify patterns characteristic of AI-generated code
• Developer-Friendly: Clear error messages, actionable fix suggestions, and rich output formats

Technical Choices

• Python Standard Library: The foundation of our zero-dependency approach — argparse for CLI, re for regex-based analysis, json for data exchange
• Regex-Based Analysis: More flexible and practical than AST parsing for non-standard syntax like JSX and Vue templates
• curses TUI: Python's built-in terminal UI library — no additional installation needed

Roadmap

• TypeScript / TSX file analysis
• Angular template diagnostics
• --fix auto-fix capability
• Custom rule plugin system
• VS Code extension
• Incremental scanning (changed files only)
• SARIF format output (GitHub Code Scanning)

📦 Packaging & Deployment

CodeLens-AI is a Python CLI tool that works out of the box — no packaging required:

# Run directly
python -m codelens_ai scan ./src

# Or install and use
pip install -e .
codelens scan ./src

Compatible Environments

• Python 3.9+
• Linux / macOS / Windows
• No Node.js, npm, or other runtimes required

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-rule)
3. Commit your changes (git commit -m 'feat: add a new diagnostic rule')
4. Push to the branch (git push origin feature/amazing-rule)
5. Create a Pull Request

Commit Convention: Follow the Angular commit convention

• feat: New feature
• fix: Bug fix
• docs: Documentation update
• refactor: Code refactoring
• test: Test-related changes
• chore: Build/tooling changes

📄 License

This project is licensed under the MIT License.

简体中文 · 繁體中文 · English