AICodeLens 是一款专注于前端代码的 AI 生成痕迹智能检测引擎，通过 98 条规则和置信度评分体系，帮助开发者与安全团队快速识别 AI 生成代码中的幻觉导入、安全隐患和性能反模式等特有风险。
[简体中文](#简体中文) | [繁體中文](#繁體中文) | [English](#english)
# 简体中文
## 🎉 项目介绍
**AICodeLens** 是一款专为前端开发者打造的 **AI 生成代码智能检测引擎**，以命令行工具（CLI）的形式提供开箱即用的静态分析能力。
### 解决的核心痛点
随着 ChatGPT、GitHub Copilot、Claude 等 AI 编码助手的普及，越来越多的前端项目直接或间接包含了 AI 生成的代码。这些代码往往存在以下典型问题：
- **幻觉导入**：AI 编造不存在的 npm 包名，导致构建失败
- **安全隐患**：硬编码 API 密钥、使用危险的 `innerHTML`、缺少 CSP 配置
- **过度工程化**：多层 HOC 嵌套、不必要的工厂模式、过度抽象的自定义 Hook
- **无障碍缺失**：图片缺少 `alt` 属性、表单缺少 `label`、模态框缺少焦点管理
- **性能反模式**：渲染函数中创建内联对象、`useEffect` 缺少依赖数组、未使用懒加载
### 与传统 Linter 的差异化定位
传统 Linter（如 ESLint、Stylelint）关注的是**代码风格和语法正确性**，而 AICodeLens 专注于**识别 AI 生成代码的特有反模式**。每条规则都附带 **AI 置信度评分**（0.0 ~ 1.0），帮助你快速判断代码是否由 AI 生成，以及其中潜藏的风险等级。
### 灵感来源
本项目灵感来源于日常开发中频繁遇到的 AI 生成代码问题——从 Copilot 补全的幻觉导入，到 ChatGPT 生成的缺少错误处理的异步函数。我们希望提供一个系统化的检测方案，让 AI 辅助编码真正安全可靠。
## ✨ 核心特性
- 🔍 **98 条 AI 反模式检测规则**，覆盖 **12 大类别**：幻觉导入、错误边界缺失、硬编码密钥、过度工程化、无障碍访问、性能反模式、死代码、不一致模式、安全漏洞、类型安全、状态管理、CSS 样式
- 🎯 **AI 置信度评分系统**：每条规则附带 0.0 ~ 1.0 的置信度评分，量化 AI 生成概率
- 🧩 **多框架支持**：React/JSX、Vue/SFC、Svelte、HTML、JavaScript、TypeScript
- 📊 **Git Diff 增量扫描**：仅扫描变更文件，完美适配 Code Review 工作流
- 📝 **多格式报告输出**：SARIF（GitHub Code Scanning 兼容）、JSON、HTML（暗色主题）、Markdown、Terminal
- 🖥️ **TUI 交互式仪表板**：ANSI 彩色进度条、统计摘要表格、严重程度分布柱状图、文件浏览器
- 🔄 **CI/CD 集成**：支持 CI 模式，发现问题即返回非零退出码
- ⚡ **零外部依赖**：纯 Python 标准库实现，Python 3.8+ 即可运行
## 🚀 快速开始
### 环境要求
- Python 3.8 或更高版本
- 无需安装任何第三方依赖
### 安装
**方式一：从 PyPI 安装（推荐）**
pip install aicodelens
**方式二：从源码安装**
git clone https://github.com/your-username/aicodelens.git
cd aicodelens
pip install -e .
### 快速扫描
安装完成后，直接在项目根目录运行：
# 扫描当前目录
aicodelens scan .
# 扫描指定目录
aicodelens scan ./src
# 扫描单个文件
aicodelens scan ./src/components/Button.tsx
输出示例：
╔══════════════════════════════════════════════════════════════╗
║ AICodeLens v1.0.0 ║
║ AI-Generated Frontend Code Detection Engine ║
╚══════════════════════════════════════════════════════════════╝
🔍 Scanning: /path/to/project/src
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
┌──────────────────────────────────────────────────────────────┐
│ Scan Summary │
├──────────────────┬───────────────────────────────────────────┤
│ Files Scanned │ 42 │
│ Total Lines │ 3,847 │
│ AI Score │ 67.3% │
├──────────────────┼──────┬──────┬──────┬─────────────────────┤
│ Severity │ Error│ Warn │ Info │ Total │
├──────────────────┼──────┼──────┼──────┼─────────────────────┤
│ Count │ 5 │ 12 │ 23 │ 40 │
└──────────────────┴──────┴──────┴──────┴─────────────────────┘
Errors ████████████████████░░░░░░░░░░░░░░ 12.5%
Warnings ████████████████████████████████░░░ 30.0%
Info ██████████████████████████████████████ 57.5%
## 📖 详细使用指南
### 扫描命令
# 基础扫描
aicodelens scan <路径>
# 指定输出格式
aicodelens scan ./src --format json
aicodelens scan ./src --format sarif
aicodelens scan ./src --format html
aicodelens scan ./src --format markdown
# 输出到文件
aicodelens scan ./src --format json --output report.json
aicodelens scan ./src --format html --output report.html
aicodelens scan ./src --format sarif --output results.sarif
# 按严重程度过滤（仅显示 error 和 warning）
aicodelens scan ./src --severity warning
# 按框架过滤
aicodelens scan ./src --framework react
aicodelens scan ./src --framework vue
aicodelens scan ./src --framework svelte
# 显示详细输出（含代码片段和修复建议）
aicodelens scan ./src --verbose
# 禁用彩色输出
aicodelens scan ./src --no-color
### 查看检测规则
# 列出所有规则（表格形式）
aicodelens rules
# 按类别过滤
aicodelens rules --category hallucinated_imports
aicodelens rules --category security
aicodelens rules --category performance
# 按框架过滤
aicodelens rules --framework react
aicodelens rules --framework vue
# JSON 格式输出
aicodelens rules --format json
### 配置文件
在项目根目录创建 `.aicodelens.json` 配置文件：
# 生成默认配置文件
aicodelens init
# 强制覆盖已有配置
aicodelens init --force
配置文件示例：
{
"format": "terminal",
"severity": "info",
"framework": "all",
"no_color": false,
"verbose": false,
"ci": false,
"include_snippets": true,
"max_snippet_lines": 3,
"exclude": [
"node_modules",
"dist",
"build",
".next",
".nuxt",
".output",
".svelte-kit",
"coverage"
],
"ignore_rules": []
}
### Git Diff 增量扫描
仅扫描 Git 变更的文件，非常适合在 Code Review 时使用：
# 扫描相对于默认分支的所有变更文件
aicodelens scan . --diff
# 扫描相对于指定分支的变更
aicodelens scan . --diff --diff-base main
aicodelens scan . --diff --diff-base origin/main
# 扫描最近一次提交的变更
aicodelens scan . --diff --diff-base HEAD~1
### CI/CD 集成
在 CI/CD 流水线中使用，发现问题自动阻断：
# GitHub Actions 示例
name: AICodeLens Scan
on: [pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install AICodeLens
run: pip install aicodelens
- name: Run AI Code Detection
run: aicodelens scan . --diff --diff-base origin/main --format sarif --output results.sarif --ci
- name: Upload SARIF Report
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
# GitLab CI 示例
aicodelens_scan:
stage: test
image: python:3.11
before_script:
- pip install aicodelens
script:
- aicodelens scan . --diff --diff-base $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --format json --output report.json --ci
artifacts:
reports:
codequality: report.json
when: always
### 报告格式
| 格式 | 说明 | 适用场景 |
|------|------|----------|
| `terminal` | ANSI 彩色终端输出（默认） | 本地开发、快速查看 |
| `json` | 结构化 JSON | 程序化处理、自定义工具链 |
| `sarif` | GitHub Code Scanning 兼容 | GitHub PR 集成、代码质量管理 |
| `html` | 自包含暗色主题 HTML 报告 | 团队分享、归档存档 |
| `markdown` | Markdown 格式摘要 | 文档集成、Issue 跟踪 |
## 💡 设计思路与迭代规划
### 设计哲学
1. **零依赖原则**：仅使用 Python 标准库，确保在任何环境下都能快速安装运行，不引入版本冲突风险
2. **AI 置信度驱动**：不仅告诉你"有什么问题"，还告诉你"这有多可能是 AI 造成的"，帮助开发者做出更明智的判断
3. **渐进式采用**：从单文件扫描到项目级扫描，从终端查看到 CI/CD 集成，按需选择使用深度
4. **多框架平等**：不偏袒任何前端框架，React、Vue、Svelte、HTML 一视同仁
### 为什么需要 AI 专属检测？
传统代码质量工具无法识别 AI 生成代码的特有问题。例如：
- ESLint 不会告诉你 `import { useMagic } from 'react-super-enhanced'` 是一个**不存在的包**
- TypeScript 编译器不会警告你 `as any` 的滥用是 **AI 生成代码的典型特征**
- 安全扫描工具不会标记 `console.log("Here is the code")` 这种 **AI 典型注释风格**
AICodeLens 填补了这一空白，专注于 AI 生成代码的**指纹识别**。
### 未来路线图
- [ ] **VS Code 扩展**：编辑器内实时检测与修复建议
- [ ] **JetBrains 插件**：IntelliJ / WebStorm 集成
- [ ] **规则自定义 DSL**：允许用户编写自定义检测规则
- [ ] **AI 模型指纹识别**：区分不同 AI 模型（GPT-4、Claude、Copilot）的生成特征
- [ ] **自动修复**：对部分规则提供一键修复能力
- [ ] **历史趋势分析**：追踪项目中 AI 代码比例的变化趋势
- [ ] **团队仪表板**：Web 端团队级 AI 代码质量看板
## 📄 开源协议
本项目基于 [MIT License](https://opensource.org/licenses/MIT) 开源。
MIT License
Copyright (c) 2024 AICodeLens Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# 繁體中文
## 🎉 專案介紹
**AICodeLens** 是一款專為前端開發者打造的 **AI 生成程式碼智慧偵測引擎**，以命令列工具（CLI）的形式提供開箱即用的靜態分析能力。
### 解決的核心痛點
隨著 ChatGPT、GitHub Copilot、Claude 等 AI 編碼助手的普及，越來越多的前端專案直接或間接包含了 AI 生成的程式碼。這些程式碼往往存在以下典型問題：
- **幻覺匯入**：AI 憑空捏造不存在的 npm 套件名稱，導致建置失敗
- **安全隱患**：硬編碼 API 金鑰、使用危險的 `innerHTML`、缺少 CSP 設定
- **過度工程化**：多層 HOC 巢狀、不必要的工廠模式、過度抽象的自訂 Hook
- **無障礙缺失**：圖片缺少 `alt` 屬性、表單缺少 `label`、對話框缺少焦點管理
- **效能反模式**：渲染函式中建立內聯物件、`useEffect` 缺少依賴陣列、未使用懶載入
### 與傳統 Linter 的差異化定位
傳統 Linter（如 ESLint、Stylelint）關注的是**程式碼風格和語法正確性**，而 AICodeLens 專注於**識別 AI 生成程式碼的特有反模式**。每條規則都附帶 **AI 信賴度評分**（0.0 ~ 1.0），幫助你快速判斷程式碼是否由 AI 生成，以及其中潛藏的風險等級。
### 靈感來源
本專案靈感來自於日常開發中頻繁遇到的 AI 生成程式碼問題——從 Copilot 補全的幻覺匯入，到 ChatGPT 生成的缺少錯誤處理的非同步函式。我們希望提供一個系統化的偵測方案，讓 AI 輔助編碼真正安全可靠。
## ✨ 核心特性
- 🔍 **98 條 AI 反模式偵測規則**，覆蓋 **12 大類別**：幻覺匯入、錯誤邊界缺失、硬編碼密鑰、過度工程化、無障礙訪問、效能反模式、死程式碼、不一致模式、安全漏洞、型別安全、狀態管理、CSS 樣式
- 🎯 **AI 信賴度評分系統**：每條規則附帶 0.0 ~ 1.0 的信賴度評分，量化 AI 生成機率
- 🧩 **多框架支援**：React/JSX、Vue/SFC、Svelte、HTML、JavaScript、TypeScript
- 📊 **Git Diff 增量掃描**：僅掃描變更檔案，完美適配 Code Review 工作流程
- 📝 **多格式報告輸出**：SARIF（GitHub Code Scanning 相容）、JSON、HTML（暗色主題）、Markdown、Terminal
- 🖥️ **TUI 互動式儀表板**：ANSI 彩色進度條、統計摘要表格、嚴重程度分佈柱狀圖、檔案瀏覽器
- 🔄 **CI/CD 整合**：支援 CI 模式，發現問題即回傳非零退出碼
- ⚡ **零外部依賴**：純 Python 標準函式庫實作，Python 3.8+ 即可執行
## 🚀 快速開始
### 環境需求
- Python 3.8 或更高版本
- 無需安裝任何第三方依賴
### 安裝
**方式一：從 PyPI 安裝（推薦）**
pip install aicodelens
**方式二：從原始碼安裝**
git clone https://github.com/your-username/aicodelens.git
cd aicodelens
pip install -e .
### 快速掃描
安裝完成後，直接在專案根目錄執行：
# 掃描目前目錄
aicodelens scan .
# 掃描指定目錄
aicodelens scan ./src
# 掃描單一檔案
aicodelens scan ./src/components/Button.tsx
輸出範例：
╔══════════════════════════════════════════════════════════════╗
║ AICodeLens v1.0.0 ║
║ AI-Generated Frontend Code Detection Engine ║
╚══════════════════════════════════════════════════════════════╝
🔍 Scanning: /path/to/project/src
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
┌──────────────────────────────────────────────────────────────┐
│ Scan Summary │
├──────────────────┬───────────────────────────────────────────┤
│ Files Scanned │ 42 │
│ Total Lines │ 3,847 │
│ AI Score │ 67.3% │
├──────────────────┼──────┬──────┬──────┬─────────────────────┤
│ Severity │ Error│ Warn │ Info │ Total │
├──────────────────┼──────┼──────┼──────┼─────────────────────┤
│ Count │ 5 │ 12 │ 23 │ 40 │
└──────────────────┴──────┴──────┴──────┴─────────────────────┘
Errors ████████████████████░░░░░░░░░░░░░░ 12.5%
Warnings ████████████████████████████████░░░ 30.0%
Info ██████████████████████████████████████ 57.5%
## 📖 詳細使用指南
### 掃描指令
# 基礎掃描
aicodelens scan <路徑>
# 指定輸出格式
aicodelens scan ./src --format json
aicodelens scan ./src --format sarif
aicodelens scan ./src --format html
aicodelens scan ./src --format markdown
# 輸出到檔案
aicodelens scan ./src --format json --output report.json
aicodelens scan ./src --format html --output report.html
aicodelens scan ./src --format sarif --output results.sarif
# 按嚴重程度過濾（僅顯示 error 和 warning）
aicodelens scan ./src --severity warning
# 按框架過濾
aicodelens scan ./src --framework react
aicodelens scan ./src --framework vue
aicodelens scan ./src --framework svelte
# 顯示詳細輸出（含程式碼片段和修復建議）
aicodelens scan ./src --verbose
# 停用彩色輸出
aicodelens scan ./src --no-color
### 查看偵測規則
# 列出所有規則（表格形式）
aicodelens rules
# 按類別過濾
aicodelens rules --category hallucinated_imports
aicodelens rules --category security
aicodelens rules --category performance
# 按框架過濾
aicodelens rules --framework react
aicodelens rules --framework vue
# JSON 格式輸出
aicodelens rules --format json
### 設定檔
在專案根目錄建立 `.aicodelens.json` 設定檔：
# 產生預設設定檔
aicodelens init
# 強制覆寫已有設定
aicodelens init --force
設定檔範例：
{
"format": "terminal",
"severity": "info",
"framework": "all",
"no_color": false,
"verbose": false,
"ci": false,
"include_snippets": true,
"max_snippet_lines": 3,
"exclude": [
"node_modules",
"dist",
"build",
".next",
".nuxt",
".output",
".svelte-kit",
"coverage"
],
"ignore_rules": []
}
### Git Diff 增量掃描
僅掃描 Git 變更的檔案，非常適合在 Code Review 時使用：
# 掃描相對於預設分支的所有變更檔案
aicodelens scan . --diff
# 掃描相對於指定分支的變更
aicodelens scan . --diff --diff-base main
aicodelens scan . --diff --diff-base origin/main
# 掃描最近一次提交的變更
aicodelens scan . --diff --diff-base HEAD~1
### CI/CD 整合
在 CI/CD 流水線中使用，發現問題自動阻斷：
# GitHub Actions 範例
name: AICodeLens Scan
on: [pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install AICodeLens
run: pip install aicodelens
- name: Run AI Code Detection
run: aicodelens scan . --diff --diff-base origin/main --format sarif --output results.sarif --ci
- name: Upload SARIF Report
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
# GitLab CI 範例
aicodelens_scan:
stage: test
image: python:3.11
before_script:
- pip install aicodelens
script:
- aicodelens scan . --diff --diff-base $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --format json --output report.json --ci
artifacts:
reports:
codequality: report.json
when: always
### 報告格式
| 格式 | 說明 | 適用場景 |
|------|------|----------|
| `terminal` | ANSI 彩色終端輸出（預設） | 本地開發、快速查看 |
| `json` | 結構化 JSON | 程式化處理、自訂工具鏈 |
| `sarif` | GitHub Code Scanning 相容 | GitHub PR 整合、程式碼品質管理 |
| `html` | 自包含暗色主題 HTML 報告 | 團隊分享、歸檔存檔 |
| `markdown` | Markdown 格式摘要 | 文件整合、Issue 追蹤 |
## 💡 設計思路與迭代規劃
### 設計哲學
1. **零依賴原則**：僅使用 Python 標準函式庫，確保在任何環境下都能快速安裝執行，不引入版本衝突風險
2. **AI 信賴度驅動**：不僅告訴你「有什麼問題」，還告訴你「這有多可能是 AI 造成的」，幫助開發者做出更明智的判斷
3. **漸進式採用**：從單檔掃描到專案級掃描，從終端查看到 CI/CD 整合，按需選擇使用深度
4. **多框架平等**：不偏袒任何前端框架，React、Vue、Svelte、HTML 一視同仁
### 為什麼需要 AI 專屬偵測？
傳統程式碼品質工具無法識別 AI 生成程式碼的特有問題。例如：
- ESLint 不會告訴你 `import { useMagic } from 'react-super-enhanced'` 是一個**不存在的套件**
- TypeScript 編譯器不會警告你 `as any` 的濫用是 **AI 生成程式碼的典型特徵**
- 安全掃描工具不會標記 `console.log("Here is the code")` 這種 **AI 典型註解風格**
AICodeLens 填補了這一空白，專注於 AI 生成程式碼的**指紋識別**。
### 未來路線圖
- [ ] **VS Code 擴充功能**：編輯器內即時偵測與修復建議
- [ ] **JetBrains 外掛**：IntelliJ / WebStorm 整合
- [ ] **規則自訂 DSL**：允許使用者撰寫自訂偵測規則
- [ ] **AI 模型指紋識別**：區分不同 AI 模型（GPT-4、Claude、Copilot）的生成特徵
- [ ] **自動修復**：對部分規則提供一鍵修復能力
- [ ] **歷史趨勢分析**：追蹤專案中 AI 程式碼比例的變化趨勢
- [ ] **團隊儀表板**：Web 端團隊級 AI 程式碼品質看板
## 🤝 貢獻指南
我們歡迎並感謝所有形式的貢獻！
### 提交 Pull Request
1. Fork 本儲存庫並建立特性分支：`git checkout -b feature/your-feature`
2. 確保所有測試通過：`python -m pytest tests/ -v`
3. 新增功能請附帶對應的單元測試
4. 提交 PR 時請填寫清晰的變更說明
### 提交 Issue
- **Bug 回報**：請包含重現步驟、預期行為、實際行為以及執行環境資訊
- **規則建議**：請描述偵測場景、AI 生成程式碼範例以及建議的規則邏輯
- **功能請求**：請說明使用場景和期望的行為
## 📄 開源協議
本專案基於 [MIT License](https://opensource.org/licenses/MIT) 開源。
MIT License
Copyright (c) 2024 AICodeLens Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# English
## 🎉 Introduction
**AICodeLens** is an **AI-Generated Frontend Code Intelligent Detection Engine** built as a command-line tool (CLI) that provides out-of-the-box static analysis capabilities for frontend developers.
### Core Pain Points Solved
With the widespread adoption of AI coding assistants like ChatGPT, GitHub Copilot, and Claude, an increasing number of frontend projects contain AI-generated code, either directly or indirectly. This code typically exhibits the following issues:
- **Hallucinated Imports**: AI fabricates non-existent npm package names, causing build failures
- **Security Vulnerabilities**: Hardcoded API keys, dangerous `innerHTML` usage, missing CSP configuration
- **Over-Engineering**: Deeply nested HOC chains, unnecessary factory patterns, over-abstracted custom Hooks
- **Accessibility Gaps**: Images missing `alt` attributes, forms missing `label` elements, modals lacking focus management
- **Performance Anti-patterns**: Inline object creation in render functions, `useEffect` missing dependency arrays, no lazy loading
### Differentiation from Traditional Linters
Traditional linters (like ESLint, Stylelint) focus on **code style and syntax correctness**, while AICodeLens specializes in **identifying anti-patterns unique to AI-generated code**. Every rule comes with an **AI Confidence Score** (0.0 ~ 1.0), helping you quickly determine whether code was likely generated by AI and the risk level of the issues found.
### Inspiration
This project was inspired by the recurring issues we encounter with AI-generated code in daily development -- from hallucinated imports in Copilot completions to async functions without error handling generated by ChatGPT. We aim to provide a systematic detection solution that makes AI-assisted coding truly safe and reliable.
## ✨ Core Features
- 🔍 **98 AI anti-pattern detection rules** across **12 categories**: hallucinated imports, missing error boundaries, hardcoded secrets, over-engineering, accessibility, performance anti-patterns, dead code, inconsistent patterns, security vulnerabilities, type safety, state management, CSS styling
- 🎯 **AI Confidence Scoring System**: Each rule includes a 0.0 ~ 1.0 confidence score, quantifying the probability of AI generation
- 🧩 **Multi-framework Support**: React/JSX, Vue/SFC, Svelte, HTML, JavaScript, TypeScript
- 📊 **Git Diff Incremental Scanning**: Scan only changed files, perfectly suited for Code Review workflows
- 📝 **Multi-format Report Output**: SARIF (GitHub Code Scanning compatible), JSON, HTML (dark theme), Markdown, Terminal
- 🖥️ **TUI Interactive Dashboard**: ANSI-colored progress bars, summary tables, severity distribution charts, file browser
- 🔄 **CI/CD Integration**: CI mode support with non-zero exit codes when issues are found
- ⚡ **Zero External Dependencies**: Pure Python standard library implementation, runs on Python 3.8+
## 🚀 Quick Start
### Prerequisites
- Python 3.8 or later
- No third-party dependencies required
### Installation
**Option 1: Install from PyPI (Recommended)**
pip install aicodelens
**Option 2: Install from Source**
git clone https://github.com/your-username/aicodelens.git
cd aicodelens
pip install -e .
### Quick Scan
After installation, run directly from your project root:
# Scan the current directory
aicodelens scan .
# Scan a specific directory
aicodelens scan ./src
# Scan a single file
aicodelens scan ./src/components/Button.tsx
Sample output:
╔══════════════════════════════════════════════════════════════╗
║ AICodeLens v1.0.0 ║
║ AI-Generated Frontend Code Detection Engine ║
╚══════════════════════════════════════════════════════════════╝
🔍 Scanning: /path/to/project/src
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
┌──────────────────────────────────────────────────────────────┐
│ Scan Summary │
├──────────────────┬───────────────────────────────────────────┤
│ Files Scanned │ 42 │
│ Total Lines │ 3,847 │
│ AI Score │ 67.3% │
├──────────────────┼──────┬──────┬──────┬─────────────────────┤
│ Severity │ Error│ Warn │ Info │ Total │
├──────────────────┼──────┼──────┼──────┼─────────────────────┤
│ Count │ 5 │ 12 │ 23 │ 40 │
└──────────────────┴──────┴──────┴──────┴─────────────────────┘
Errors ████████████████████░░░░░░░░░░░░░░ 12.5%
Warnings ████████████████████████████████░░░ 30.0%
Info ██████████████████████████████████████ 57.5%
## 📖 Detailed Usage Guide
### Scan Commands
# Basic scan
aicodelens scan
# Specify output format
aicodelens scan ./src --format json
aicodelens scan ./src --format sarif
aicodelens scan ./src --format html
aicodelens scan ./src --format markdown
# Output to file
aicodelens scan ./src --format json --output report.json
aicodelens scan ./src --format html --output report.html
aicodelens scan ./src --format sarif --output results.sarif
# Filter by severity (show only error and warning)
aicodelens scan ./src --severity warning
# Filter by framework
aicodelens scan ./src --framework react
aicodelens scan ./src --framework vue
aicodelens scan ./src --framework svelte
# Verbose output (with code snippets and fix suggestions)
aicodelens scan ./src --verbose
# Disable colored output
aicodelens scan ./src --no-color
### Listing Detection Rules
# List all rules (table format)
aicodelens rules
# Filter by category
aicodelens rules --category hallucinated_imports
aicodelens rules --category security
aicodelens rules --category performance
# Filter by framework
aicodelens rules --framework react
aicodelens rules --framework vue
# JSON format output
aicodelens rules --format json
### Configuration File
Create a `.aicodelens.json` configuration file in your project root:
# Generate default configuration file
aicodelens init
# Force overwrite existing configuration
aicodelens init --force
Configuration file example:
{
"format": "terminal",
"severity": "info",
"framework": "all",
"no_color": false,
"verbose": false,
"ci": false,
"include_snippets": true,
"max_snippet_lines": 3,
"exclude": [
"node_modules",
"dist",
"build",
".next",
".nuxt",
".output",
".svelte-kit",
"coverage"
],
"ignore_rules": []
}
### Git Diff Incremental Scanning
Scan only Git-changed files, ideal for use during Code Review:
# Scan all changed files relative to the default branch
aicodelens scan . --diff
# Scan changes relative to a specific branch
aicodelens scan . --diff --diff-base main
aicodelens scan . --diff --diff-base origin/main
# Scan changes from the last commit
aicodelens scan . --diff --diff-base HEAD~1
### CI/CD Integration
Use in CI/CD pipelines to automatically block on issues found:
# GitHub Actions example
name: AICodeLens Scan
on: [pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install AICodeLens
run: pip install aicodelens
- name: Run AI Code Detection
run: aicodelens scan . --diff --diff-base origin/main --format sarif --output results.sarif --ci
- name: Upload SARIF Report
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
# GitLab CI example
aicodelens_scan:
stage: test
image: python:3.11
before_script:
- pip install aicodelens
script:
- aicodelens scan . --diff --diff-base $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --format json --output report.json --ci
artifacts:
reports:
codequality: report.json
when: always
### Report Formats
| Format | Description | Use Case |
|--------|-------------|----------|
| `terminal` | ANSI-colored terminal output (default) | Local development, quick inspection |
| `json` | Structured JSON | Programmatic processing, custom toolchains |
| `sarif` | GitHub Code Scanning compatible | GitHub PR integration, code quality management |
| `html` | Self-contained dark-themed HTML report | Team sharing, archiving |
| `markdown` | Markdown format summary | Documentation integration, issue tracking |
## 💡 Design Philosophy & Roadmap
### Design Principles
1. **Zero Dependencies**: Built exclusively with the Python standard library, ensuring fast installation and zero version conflict risk in any environment
2. **AI Confidence-Driven**: Not only tells you "what's wrong" but also "how likely this was caused by AI", helping developers make more informed decisions
3. **Progressive Adoption**: From single-file scanning to project-level analysis, from terminal output to CI/CD integration -- choose your depth of usage
4. **Framework Agnostic**: No favoritism toward any frontend framework -- React, Vue, Svelte, and HTML are treated equally
### Why AI-Specific Detection Matters
Traditional code quality tools cannot identify issues unique to AI-generated code. For example:
- ESLint won't tell you that `import { useMagic } from 'react-super-enhanced'` is a **non-existent package**
- The TypeScript compiler won't warn you that `as any` abuse is a **hallmark of AI-generated code**
- Security scanners won't flag `console.log("Here is the code")` as an **AI-typical comment style**
AICodeLens fills this gap by focusing on **fingerprinting AI-generated code**.
### Roadmap
- [ ] **VS Code Extension**: Real-time detection and fix suggestions within the editor
- [ ] **JetBrains Plugin**: IntelliJ / WebStorm integration
- [ ] **Custom Rule DSL**: Allow users to write their own detection rules
- [ ] **AI Model Fingerprinting**: Distinguish generation characteristics of different AI models (GPT-4, Claude, Copilot)
- [ ] **Auto-Fix**: One-click fix capability for select rules
- [ ] **Historical Trend Analysis**: Track changes in AI code ratio across your project over time
- [ ] **Team Dashboard**: Web-based team-level AI code quality dashboard
## 🤝 Contributing
We welcome and appreciate contributions of all forms!
### Submitting a Pull Request
1. Fork this repository and create a feature branch: `git checkout -b feature/your-feature`
2. Ensure all tests pass: `python -m pytest tests/ -v`
3. New features should include corresponding unit tests
4. Provide a clear description of changes when submitting your PR
### Submitting an Issue
- **Bug Reports**: Please include reproduction steps, expected behavior, actual behavior, and runtime environment details
- **Rule Suggestions**: Describe the detection scenario, AI-generated code examples, and proposed rule logic
- **Feature Requests**: Explain the use case and expected behavior
## 📄 License
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
MIT License
Copyright (c) 2024 AICodeLens Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.