🏥 WebVitalScan

Lightweight Frontend Code Health Intelligence Diagnostic Engine
轻量级前端代码健康度智能诊断引擎

[!TIP] 🌐 Switch Language: 简体中文 | 繁體中文 | English

🇨🇳 简体中文

🎉 项目介绍

WebVitalScan 是一款轻量级前端代码健康度智能诊断引擎，灵感来源于对现代前端项目质量管理的深度思考。它能一键扫描你的前端项目，从 安全、性能、架构、可访问性、正确性、包体积 六大维度进行全面诊断，输出 0-100 的健康评分和可操作的诊断建议。

🎯 解决的核心痛点：

• 前端项目缺乏统一的质量诊断工具
• 现有工具大多依赖 Node.js 环境，安装繁琐
• 缺乏跨框架（React/Vue/Svelte/Angular）的统一诊断方案
• CI/CD 集成困难，缺少标准化的输出格式

✨ 自研差异化亮点：

• 🔧 零依赖：纯 Python 实现，无需 Node.js，pip install 即可使用
• 🧩 多框架支持：React、Vue、Svelte、Angular、HTML 全覆盖
• 📊 27+ 诊断规则：覆盖安全、性能、架构、可访问性、正确性、包体积六大维度
• 📋 四种输出格式：终端彩色报告、JSON、HTML 可视化报告、SARIF（GitHub Code Scanning 兼容）
• ⚡ 增量扫描：支持仅扫描变更文件，适合 CI/CD 场景
• 🚫 智能排除：自动跳过 node_modules、dist、.git 等非必要目录

✨ 核心特性

🚀 快速开始

环境要求： Python 3.8+（无需其他依赖）

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

# 直接运行（无需安装依赖）
python3 webvitalscan.py /path/to/your/project

# 或安装后使用
pip install -e .
webvitalscan /path/to/your/project

常用命令：

# 基础扫描
webvitalscan ./my-react-app

# 详细输出（含代码片段）
webvitalscan ./my-project --verbose

# 输出 HTML 报告
webvitalscan ./src -o html -f report.html

# 输出 JSON（适合 CI/CD）
webvitalscan . -o json -f result.json

# 输出 SARIF（GitHub Code Scanning）
webvitalscan . -o sarif -f results.sarif

# 排除测试文件
webvitalscan . --exclude "test_|spec_|mock_"

# 仅显示严重问题
webvitalscan . --min-severity error

📖 详细使用指南

输出格式说明

评分等级

CI/CD 集成示例

# GitHub Actions 示例
name: WebVitalScan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -e .
      - run: webvitalscan . -o sarif -f results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

💡 设计思路与迭代规划

设计理念：

• 零依赖哲学：不引入任何第三方库，确保在任何 Python 环境中都能运行
• 规则驱动：所有诊断逻辑以规则形式组织，易于扩展和自定义
• 多框架统一：一套工具覆盖主流前端框架，降低团队工具链复杂度

后续迭代计划：

• 📝 YAML 自定义规则引擎
• 🔌 VS Code 扩展
• 📊 历史趋势对比
• 🌐 GitLab CI/CD 模板
• 📱 更多框架支持（Solid.js、Qwik）

🤝 贡献指南

欢迎提交 Issue 和 PR！请遵循以下规范：

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-rule
3. 提交更改：git commit -m 'feat: add amazing security rule'
4. 推送分支：git push origin feature/amazing-rule
5. 提交 Pull Request

📄 开源协议

本项目基于 MIT License 开源。

🇹🇼 繁體中文

🎉 專案介紹

WebVitalScan 是一款輕量級前端程式碼健康度智慧診斷引擎。它能一鍵掃描你的前端專案，從 安全、效能、架構、無障礙、正確性、套件體積 六大維度進行全面診斷，輸出 0-100 的健康評分和可操作的診斷建議。

🎯 解決的核心痛點：

• 前端專案缺乏統一的品質診斷工具
• 現有工具大多依賴 Node.js 環境，安裝繁瑣
• 缺乏跨框架（React/Vue/Svelte/Angular）的統一診斷方案
• CI/CD 整合困難，缺少標準化的輸出格式

✨ 自研差異化亮點：

• 🔧 零依賴：純 Python 實現，無需 Node.js，pip install 即可使用
• 🧩 多框架支援：React、Vue、Svelte、Angular、HTML 全覆蓋
• 📊 27+ 診斷規則：覆蓋安全、效能、架構、無障礙、正確性、套件體積六大維度
• 📋 四種輸出格式：終端彩色報告、JSON、HTML 可視化報告、SARIF
• ⚡ 增量掃描：支援僅掃描變更檔案，適合 CI/CD 場景
• 🚫 智慧排除：自動跳過 node_modules、dist、.git 等非必要目錄

✨ 核心特性

🚀 快速開始

環境要求： Python 3.8+（無需其他依賴）

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

# 直接運行（無需安裝依賴）
python3 webvitalscan.py /path/to/your/project

# 或安裝後使用
pip install -e .
webvitalscan /path/to/your/project

常用命令：

# 基礎掃描
webvitalscan ./my-react-app

# 詳細輸出（含程式碼片段）
webvitalscan ./my-project --verbose

# 輸出 HTML 報告
webvitalscan ./src -o html -f report.html

# 輸出 JSON（適合 CI/CD）
webvitalscan . -o json -f result.json

# 輸出 SARIF（GitHub Code Scanning）
webvitalscan . -o sarif -f results.sarif

# 排除測試檔案
webvitalscan . --exclude "test_|spec_|mock_"

# 僅顯示嚴重問題
webvitalscan . --min-severity error

📖 詳細使用指南

輸出格式說明

評分等級

💡 設計思路與迭代規劃

設計理念：

• 零依賴哲學：不引入任何第三方庫，確保在任何 Python 環境中都能運行
• 規則驅動：所有診斷邏輯以規則形式組織，易於擴展和自定義
• 多框架統一：一套工具覆蓋主流前端框架，降低團隊工具鏈複雜度

後續迭代計劃：

• 📝 YAML 自定義規則引擎
• 🔌 VS Code 擴展
• 📊 歷史趨勢對比
• 🌐 GitLab CI/CD 模板

🤝 貢獻指南

歡迎提交 Issue 和 PR！請遵循以下規範：

1. Fork 本倉庫
2. 建立特性分支：git checkout -b feature/amazing-rule
3. 提交更改：git commit -m 'feat: add amazing security rule'
4. 推送分支：git push origin feature/amazing-rule
5. 提交 Pull Request

📄 開源協議

本專案基於 MIT License 開源。

🇺🇸 English

🎉 Introduction

WebVitalScan is a lightweight frontend code health intelligence diagnostic engine. It scans your frontend project with a single command, performing comprehensive diagnostics across 6 dimensions: Security, Performance, Architecture, Accessibility, Correctness, and Bundle Size — outputting a 0-100 health score with actionable recommendations.

🎯 Core Problems Solved:

• Lack of unified quality diagnostic tools for frontend projects
• Existing tools require Node.js environments with complex setup
• No cross-framework (React/Vue/Svelte/Angular) unified diagnostic solution
• Difficult CI/CD integration with non-standardized output formats

✨ Key Differentiators:

• 🔧 Zero Dependencies: Pure Python implementation, no Node.js required
• 🧩 Multi-Framework: Full support for React, Vue, Svelte, Angular, and HTML
• 📊 27+ Diagnostic Rules: Covering security, performance, architecture, accessibility, correctness, and bundle size
• 📋 4 Output Formats: Colorful terminal, JSON, interactive HTML report, SARIF (GitHub Code Scanning compatible)
• ⚡ Incremental Scanning: Scan only changed files for CI/CD efficiency
• 🚫 Smart Exclusion: Auto-skips node_modules, dist, .git and other non-essential directories

✨ Core Features

🚀 Quick Start

Requirements: Python 3.8+ (no other dependencies needed)

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

# Run directly (no installation needed)
python3 webvitalscan.py /path/to/your/project

# Or install and use
pip install -e .
webvitalscan /path/to/your/project

Common Commands:

# Basic scan
webvitalscan ./my-react-app

# Verbose output (with code snippets)
webvitalscan ./my-project --verbose

# HTML report
webvitalscan ./src -o html -f report.html

# JSON output (for CI/CD)
webvitalscan . -o json -f result.json

# SARIF output (GitHub Code Scanning)
webvitalscan . -o sarif -f results.sarif

# Exclude test files
webvitalscan . --exclude "test_|spec_|mock_"

# Only show critical issues
webvitalscan . --min-severity error

📖 Detailed Usage Guide

Output Formats

Scoring Grades

CI/CD Integration Example

# GitHub Actions Example
name: WebVitalScan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -e .
      - run: webvitalscan . -o sarif -f results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

💡 Design Philosophy & Roadmap

Design Principles:

• Zero Dependency Philosophy: No third-party libraries, runs in any Python environment
• Rule-Driven Architecture: All diagnostic logic organized as rules, easy to extend
• Multi-Framework Unification: One tool covers all major frontend frameworks

Roadmap:

• 📝 YAML custom rule engine
• 🔌 VS Code extension
• 📊 Historical trend comparison
• 🌐 GitLab CI/CD template
• 📱 More framework support (Solid.js, Qwik)

🤝 Contributing

Issues and PRs are welcome! Please follow these guidelines:

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

📄 License

This project is licensed under the MIT License.

Made with ❤️ by SoloBot