ComponentGuard Svelte Themes

Componentguard

🛡️ Lightweight Frontend Component Code Quality Intelligent Diagnosis Engine - Supports React, Vue, Svelte | 零依赖前端组件代码质量智能诊断引擎

Download

🛡️ ComponentGuard

Lightweight Frontend Component Code Quality Intelligent Diagnosis Engine

简体中文 · 繁體中文 · English

🎉 项目介绍

ComponentGuard 是一款轻量级前端组件代码质量智能诊断引擎，零外部依赖，纯 Python 标准库实现。支持 React (JSX/TSX)、Vue (SFC) 和 Svelte 三大主流框架的组件代码质量检测。

💡 灵感来源

随着 AI 辅助编程工具的普及，AI 生成的组件代码往往存在各种反模式和潜在问题。ComponentGuard 旨在帮助开发者快速发现并修复这些问题，提升代码质量。

🌟 自研差异化亮点

  • 零依赖：纯 Python 标准库实现，无需安装 Node.js 或任何第三方包
  • 多框架支持：同时支持 React、Vue、Svelte 三大框架
  • 智能修复建议：每个问题都附带具体的修复方案
  • 批量扫描：递归扫描整个项目目录
  • 多格式报告：支持终端彩色输出、JSON 和 Markdown 报告导出

✨ 核心特性

⚛️ React 诊断规则

  • 缺失 Key 检测：自动发现 .map() 渲染中缺失的 key 属性
  • useEffect 依赖检查：检测空依赖数组与外部引用的冲突
  • 条件渲染陷阱：识别 0 && <JSX> 等常见 bug
  • 内联样式检测：发现过多的内联样式使用
  • 未使用导入：清理无用的 import 语句
  • Console 语句：标记遗留的调试日志
  • 直接 DOM 操作：检测 React 中的 document.getElementById 等反模式
  • 超大组件：识别需要拆分的大型组件

💚 Vue 诊断规则

  • v-if/v-for 同元素：检测优先级冲突问题
  • v-for 缺失 Key：确保列表渲染效率
  • v-html 安全风险：XSS 攻击预警
  • Console 语句：清理调试代码
  • Props 类型验证：提醒添加类型定义
  • Deep Watcher：性能优化建议
  • 未使用数据属性：清理冗余代码

🔥 Svelte 诊断规则

  • 响应式声明：检测潜在响应式问题
  • #each 缺失 Key：确保列表渲染正确
  • Console 语句：清理调试代码
  • 未使用导出：发现冗余的 prop 定义
  • Await 错误处理：确保异步操作有错误处理
  • 超大组件：识别需要拆分的组件

🚀 快速开始

📋 环境要求

  • Python 3.9+ （无需其他任何依赖）

🔧 安装

# 克隆仓库
git clone https://github.com/gitstq/ComponentGuard.git
cd ComponentGuard

# 直接使用（无需安装）
python3 -m componentguard ./src

# 或安装为全局命令
pip install .
componentguard ./src

🏃 基本用法

# 扫描当前目录
python3 -m componentguard

# 扫描指定目录
python3 -m componentguard ./src/components

# 扫描单个文件
python3 -m componentguard ./src/App.jsx

# 详细输出（含修复建议）
python3 -m componentguard ./src --verbose

# 仅扫描 React 文件
python3 -m componentguard ./src --framework react

# 禁用彩色输出
python3 -m componentguard ./src --no-color

📊 报告导出

# 导出 JSON 报告
python3 -m componentguard ./src --json report.json

# 导出 Markdown 报告
python3 -m componentguard ./src --md report.md

# 同时导出两种格式
python3 -m componentguard ./src --json report.json --md report.md

📖 详细使用指南

命令行参数

参数 说明 示例
path 扫描路径（文件或目录） ./src
-v, --verbose 显示详细修复建议 --verbose
--json FILE 导出 JSON 报告 --json report.json
--md FILE 导出 Markdown 报告 --md report.md
--no-color 禁用彩色输出 --no-color
--framework 仅扫描指定框架 --framework react
--version 显示版本号 --version

严重级别

级别 图标 说明
ERROR ✖ 必须修复的严重问题
WARNING ⚠ 建议修复的警告
INFO ℹ 信息提示
SUGGESTION 💡 优化建议

典型使用场景

1. CI/CD 集成

# GitHub Actions
- name: Run ComponentGuard
  run: |
    python3 -m componentguard ./src --json report.json --no-color
    # 检查是否有 error 级别问题
    python3 -c "import json; d=json.load(open('report.json')); exit(1 if d['summary']['total_errors'] > 0 else 0)"

2. Git Hook 集成

# .git/hooks/pre-commit
#!/bin/bash
python3 -m componentguard ./src --no-color
if [ $? -ne 0 ]; then
    echo "❌ ComponentGuard found errors. Please fix before committing."
    exit 1
fi

3. npm scripts 集成

{
  "scripts": {
    "lint:components": "python3 -m componentguard ./src --verbose"
  }
}

💡 设计思路与迭代规划

设计理念

  • 零依赖哲学：不引入任何第三方库，确保最大兼容性和最小安装成本
  • 正则解析策略：使用正则表达式进行轻量级 AST 分析，避免复杂的解析器依赖
  • 渐进式诊断：从 ERROR → WARNING → INFO → SUGGESTION 分级，让开发者优先处理关键问题

技术选型原因

选择 原因
Python 跨平台、开发者友好、标准库丰富
正则表达式 轻量级、零依赖、覆盖主流反模式
CLI 工具 易于集成到各种工作流

后续迭代计划

  • 🔄 支持 Angular 模板诊断
  • 🔄 支持 SolidJS 组件诊断
  • 🔄 添加 --fix 自动修复功能
  • 🔄 支持配置文件（.componentguardrc）
  • 🔄 添加 --watch 监听模式
  • 🔄 支持 SARIF 格式输出（GitHub Code Scanning）

📦 打包与部署

作为 Python 包安装

# 从源码安装
git clone https://github.com/gitstq/ComponentGuard.git
cd ComponentGuard
pip install .

# 验证安装
componentguard --version

作为独立脚本使用

# 无需安装，直接运行
python3 componentguard/cli.py ./src

兼容环境

环境 版本
Python 3.9+
操作系统 Windows / macOS / Linux
前端框架 React 16+ / Vue 2/3 / Svelte 3/4/5

🤝 贡献指南

欢迎社区贡献！请遵循以下规范：

提交 PR

  1. Fork 本仓库
  2. 创建特性分支：git checkout -b feat/new-rule
  3. 编写规则代码和对应测试
  4. 确保所有测试通过：python3 -m pytest tests/ -v
  5. 提交 PR 并描述变更内容

Issue 反馈

  • 🐛 Bug 报告：请附上复现代码和期望行为
  • 💡 新规则建议：请描述规则逻辑和适用场景
  • 📝 文档改进：欢迎修正任何语言版本的表达

📄 开源协议

本项目基于 MIT License 开源。

🎉 專案介紹

ComponentGuard 是一款輕量級前端元件程式碼品質智慧診斷引擎，零外部依賴，純 Python 標準函式庫實作。支援 React (JSX/TSX)、Vue (SFC) 和 Svelte 三大主流框架的元件程式碼品質檢測。

💡 靈感來源

隨著 AI 輔助程式設計工具的普及，AI 生成的元件程式碼往往存在各種反模式和潛在問題。ComponentGuard 旨在幫助開發者快速發現並修復這些問題，提升程式碼品質。

🌟 自研差異化亮點

  • 零依賴：純 Python 標準函式庫實作，無需安裝 Node.js 或任何第三方套件
  • 多框架支援：同時支援 React、Vue、Svelte 三大框架
  • 智慧修復建議：每個問題都附帶具體的修復方案
  • 批量掃描：遞迴掃描整個專案目錄
  • 多格式報告：支援終端彩色輸出、JSON 和 Markdown 報告匯出

✨ 核心特性

⚛️ React 診斷規則

  • 缺失 Key 偵測：自動發現 .map() 渲染中缺失的 key 屬性
  • useEffect 依賴檢查：偵測空依賴陣列與外部引用的衝突
  • 條件渲染陷阱：識別 0 && <JSX> 等常見 bug
  • 內聯樣式偵測：發現過多的內聯樣式使用
  • 未使用匯入：清理無用的 import 語句
  • Console 語句：標記遺留的除錯日誌
  • 直接 DOM 操作：偵測 React 中的 document.getElementById 等反模式
  • 超大元件：識別需要拆分的大型元件

💚 Vue 診斷規則

  • v-if/v-for 同元素：偵測優先級衝突問題
  • v-for 缺失 Key：確保列表渲染效率
  • v-html 安全風險：XSS 攻擊預警
  • Console 語句：清理除錯程式碼
  • Props 類型驗證：提醒添加類型定義
  • Deep Watcher：效能優化建議
  • 未使用資料屬性：清理冗餘程式碼

🔥 Svelte 診斷規則

  • 響應式宣告：偵測潛在響應式問題
  • #each 缺失 Key：確保列表渲染正確
  • Console 語句：清理除錯程式碼
  • 未使用匯出：發現冗餘的 prop 定義
  • Await 錯誤處理：確保非同步操作有錯誤處理
  • 超大元件：識別需要拆分的元件

🚀 快速開始

📋 環境需求

  • Python 3.9+ （無需其他任何依賴）

🔧 安裝

# 克隆倉庫
git clone https://github.com/gitstq/ComponentGuard.git
cd ComponentGuard

# 直接使用（無需安裝）
python3 -m componentguard ./src

# 或安裝為全域命令
pip install .
componentguard ./src

🏃 基本用法

# 掃描當前目錄
python3 -m componentguard

# 掃描指定目錄
python3 -m componentguard ./src/components

# 掃描單個檔案
python3 -m componentguard ./src/App.jsx

# 詳細輸出（含修復建議）
python3 -m componentguard ./src --verbose

# 僅掃描 React 檔案
python3 -m componentguard ./src --framework react

# 停用彩色輸出
python3 -m componentguard ./src --no-color

📊 報告匯出

# 匯出 JSON 報告
python3 -m componentguard ./src --json report.json

# 匯出 Markdown 報告
python3 -m componentguard ./src --md report.md

# 同時匯出兩種格式
python3 -m componentguard ./src --json report.json --md report.md

📖 詳細使用指南

命令列參數

參數 說明 範例
path 掃描路徑（檔案或目錄） ./src
-v, --verbose 顯示詳細修復建議 --verbose
--json FILE 匯出 JSON 報告 --json report.json
--md FILE 匯出 Markdown 報告 --md report.md
--no-color 停用彩色輸出 --no-color
--framework 僅掃描指定框架 --framework react
--version 顯示版本號 --version

嚴重級別

級別 圖示 說明
ERROR ✖ 必須修復的嚴重問題
WARNING ⚠ 建議修復的警告
INFO ℹ 資訊提示
SUGGESTION 💡 優化建議

💡 設計思路與迭代規劃

設計理念

  • 零依賴哲學：不引入任何第三方函式庫，確保最大相容性和最小安裝成本
  • 正則解析策略：使用正則表示式進行輕量級 AST 分析，避免複雜的解析器依賴
  • 漸進式診斷：從 ERROR → WARNING → INFO → SUGGESTION 分級

後續迭代計畫

  • 🔄 支援 Angular 模板診斷
  • 🔄 支援 SolidJS 元件診斷
  • 🔄 添加 --fix 自動修復功能
  • 🔄 支援設定檔（.componentguardrc）
  • 🔄 添加 --watch 監聽模式

📦 打包與部署

# 從原始碼安裝
git clone https://github.com/gitstq/ComponentGuard.git
cd ComponentGuard
pip install .

# 驗證安裝
componentguard --version

相容環境

環境 版本
Python 3.9+
作業系統 Windows / macOS / Linux
前端框架 React 16+ / Vue 2/3 / Svelte 3/4/5

🤝 貢獻指南

歡迎社群貢獻！請遵循以下規範：

  1. Fork 本倉庫
  2. 建立特性分支：git checkout -b feat/new-rule
  3. 編寫規則程式碼和對應測試
  4. 確保所有測試通過：python3 -m pytest tests/ -v
  5. 提交 PR 並描述變更內容

📄 開源協議

本專案基於 MIT License 開源。

🎉 Introduction

ComponentGuard is a lightweight frontend component code quality intelligent diagnosis engine with zero external dependencies, built entirely with Python's standard library. It supports React (JSX/TSX), Vue (SFC), and Svelte — the three most popular frontend frameworks.

💡 Inspiration

With the rise of AI-assisted coding tools, AI-generated component code often contains anti-patterns and potential issues. ComponentGuard helps developers quickly identify and fix these problems to improve code quality.

🌟 Key Differentiators

  • Zero Dependencies: Pure Python standard library — no Node.js or third-party packages needed
  • Multi-Framework Support: React, Vue, and Svelte in a single tool
  • Smart Fix Suggestions: Every issue comes with actionable repair recommendations
  • Batch Scanning: Recursively scan entire project directories
  • Multiple Report Formats: Terminal (colorized), JSON, and Markdown export

✨ Core Features

⚛️ React Diagnostic Rules

  • Missing Key Detection: Finds .map() renders without key props
  • useEffect Dependency Check: Detects stale closure issues with empty dependency arrays
  • Conditional Rendering Traps: Catches 0 && <JSX> and similar bugs
  • Inline Style Detection: Flags excessive inline style usage
  • Unused Imports: Identifies dead import statements
  • Console Statements: Marks leftover debug logs
  • Direct DOM Manipulation: Detects document.getElementById and similar anti-patterns
  • Oversized Components: Flags components that should be split

💚 Vue Diagnostic Rules

  • v-if/v-for on Same Element: Detects priority conflict issues
  • v-for Missing Key: Ensures efficient list rendering
  • v-html Security Risk: XSS attack warnings
  • Console Statements: Cleanup debug code
  • Props Type Validation: Reminds to add type definitions
  • Deep Watcher: Performance optimization suggestions
  • Unused Data Properties: Cleanup redundant code

🔥 Svelte Diagnostic Rules

  • Reactive Declarations: Detects potential reactivity issues
  • #each Missing Key: Ensures correct list rendering
  • Console Statements: Cleanup debug code
  • Unused Exports: Finds redundant prop definitions
  • Await Error Handling: Ensures async operations have error handlers
  • Oversized Components: Flags components that need splitting

🚀 Quick Start

📋 Requirements

  • Python 3.9+ (no other dependencies required)

🔧 Installation

# Clone the repository
git clone https://github.com/gitstq/ComponentGuard.git
cd ComponentGuard

# Run directly (no installation needed)
python3 -m componentguard ./src

# Or install as a global command
pip install .
componentguard ./src

🏃 Basic Usage

# Scan current directory
python3 -m componentguard

# Scan a specific directory
python3 -m componentguard ./src/components

# Scan a single file
python3 -m componentguard ./src/App.jsx

# Verbose output (with fix suggestions)
python3 -m componentguard ./src --verbose

# Only scan React files
python3 -m componentguard ./src --framework react

# Disable colored output
python3 -m componentguard ./src --no-color

📊 Report Export

# Export JSON report
python3 -m componentguard ./src --json report.json

# Export Markdown report
python3 -m componentguard ./src --md report.md

# Export both formats
python3 -m componentguard ./src --json report.json --md report.md

📖 Detailed Usage Guide

CLI Arguments

Argument Description Example
path Scan path (file or directory) ./src
-v, --verbose Show detailed fix suggestions --verbose
--json FILE Export JSON report --json report.json
--md FILE Export Markdown report --md report.md
--no-color Disable colored output --no-color
--framework Only scan specific framework --framework react
--version Show version --version

Severity Levels

Level Icon Description
ERROR ✖ Critical issues that must be fixed
WARNING ⚠ Issues recommended to fix
INFO ℹ Informational notices
SUGGESTION 💡 Optimization suggestions

Typical Use Cases

1. CI/CD Integration

# GitHub Actions
- name: Run ComponentGuard
  run: |
    python3 -m componentguard ./src --json report.json --no-color
    python3 -c "import json; d=json.load(open('report.json')); exit(1 if d['summary']['total_errors'] > 0 else 0)"

2. Git Hook Integration

# .git/hooks/pre-commit
#!/bin/bash
python3 -m componentguard ./src --no-color
if [ $? -ne 0 ]; then
    echo "❌ ComponentGuard found errors. Please fix before committing."
    exit 1
fi

💡 Design Philosophy & Roadmap

Design Principles

  • Zero-Dependency Philosophy: No third-party libraries for maximum compatibility
  • Regex Parsing Strategy: Lightweight AST analysis without complex parser dependencies
  • Progressive Diagnosis: ERROR → WARNING → INFO → SUGGESTION severity levels

Roadmap

  • 🔄 Angular template diagnostics support
  • 🔄 SolidJS component diagnostics support
  • 🔄 --fix auto-fix functionality
  • 🔄 Configuration file support (.componentguardrc)
  • 🔄 --watch watch mode
  • 🔄 SARIF format output (GitHub Code Scanning)

📦 Packaging & Deployment

# Install from source
git clone https://github.com/gitstq/ComponentGuard.git
cd ComponentGuard
pip install .

# Verify installation
componentguard --version

Compatible Environments

Environment Version
Python 3.9+
OS Windows / macOS / Linux
Frameworks React 16+ / Vue 2/3 / Svelte 3/4/5

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork this repository
  2. Create a feature branch: git checkout -b feat/new-rule
  3. Write rule code and corresponding tests
  4. Ensure all tests pass: python3 -m pytest tests/ -v
  5. Submit a PR describing your changes

Issue Reporting

  • 🐛 Bug Reports: Please include reproduction code and expected behavior
  • 💡 New Rule Suggestions: Describe the rule logic and applicable scenarios
  • 📝 Documentation: Corrections to any language version are welcome

📄 License

This project is licensed under the MIT License.

Built with ❤️ by gitstq

Top categories

tailwinddaisyuiadmin templatepopupmdsvexportfolioblogformecommerceuicarouselauthdarkseoimagerouting
Loading Svelte Themes