Metadata-Version: 2.4
Name: vcode-analysis
Version: 0.5.0
Summary: 基于大模型的智能代码分析工具，支持代码审查、文档生成、架构分析和安全扫描
Author-email: Wellchang <2483808264@qq.com>
License: MIT
Project-URL: Homepage, https://xxxxxx
Project-URL: Repository, https://xxxxxx
Project-URL: Documentation, https://xxxxxx
Project-URL: Bug Tracker, https://xxxxxx
Keywords: vcode-analysis,llm,code-review,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: docopt>=0.6.2
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: rich
Requires-Dist: rich>=13.0.0; extra == "rich"
Provides-Extra: parsers
Requires-Dist: javalang>=0.13.0; extra == "parsers"
Requires-Dist: pycparser>=2.21; extra == "parsers"
Dynamic: license-file

# Code Analysis - 智能代码分析工具

[![PyPI version](https://img.shields.io/pypi/v/vcode-analysis.svg)](https://pypi.org/project/vcode-analysis/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

基于私有化部署大模型的智能代码分析工具，支持代码审查、文档生成、架构分析和安全扫描。

## ✨ 核心特性

| 特性 | 描述 |
|------|------|
| 🔍 **代码审查** | 自动分析代码质量，识别问题和安全漏洞 |
| 📝 **文档生成** | 自动生成模块文档、API 文档 |
| 🏗️ **架构分析** | 分析项目结构、依赖关系、代码度量 |
| 🔒 **安全扫描** | 检测常见安全漏洞和风险代码 |
| 🔗 **上下文增强** | 解析项目依赖关系，提供关联文件上下文给 LLM |
| ⚡ **并发分析** | 支持多线程并发分析，默认 5 个线程 |
| 📦 **批量操作** | 批量克隆、批量 Git 操作、多仓库管理 |
| 📂 **目录分析** | 扫描项目结构、识别技术栈 |
| 🌐 **多语言支持** | Python, Java, Kotlin, C/C++, JavaScript, TypeScript, Vue 等 |
| 🤖 **私有化部署** | 兼容 OpenAI API 格式，支持任何私有化 LLM |
| 🌍 **环境变量** | 支持环境变量配置，方便 CI/CD 集成 |

## 🚀 快速开始

### 安装

**方式一：从 PyPI 安装（推荐）**

```bash
# 基础安装
pip install vcode-analysis

# 安装额外解析器支持
pip install vcode-analysis[parsers]

# 安装所有可选依赖
pip install vcode-analysis[parsers,rich]
```

**方式二：从源码安装**

```bash
git clone 
cd code-analysis
pip install -e .
```

**方式三：离线安装**

```bash
# Windows
install_offline.bat

# Linux/macOS
bash install_offline.sh
```

### 配置

```bash
# 初始化配置文件
vcode-analysis config --init

# 编辑配置文件
# ~/.code-analysis/config.yaml
```

### 使用

```bash
# 代码审查（默认启用批量分析和缓存，大幅减少 API 调用）
vcode-analysis review ./src

# 架构分析
vcode-analysis arch ./src

# 安全扫描
vcode-analysis security ./src --deep

# 使用 10 个并发线程加速分析
vcode-analysis review ./src --workers 10

# 禁用缓存（强制重新分析）
vcode-analysis review ./src --no-cache

# 禁用批量分析（逐文件分析）
vcode-analysis review ./src --no-batch

# 启用上下文增强（提供项目结构和依赖关系）
vcode-analysis review ./src --context

# 输出 JSON 格式
vcode-analysis review ./src --format json

# 目录扫描
vcode-analysis scan-dir ./project

# 目录扫描（指定深度）
vcode-analysis scan-dir ./project --depth 3
```

## ⚡ 性能优化

### 批量分析 + 缓存（v0.4.0 新增）

**默认启用**，可大幅提升分析效率：

| 场景 | 原方式 | 优化后 | 提升 |
|------|--------|--------|------|
| 首次分析 100 个文件 | 100 次 API 调用 | ~15 次 | 减少 85% |
| 二次分析（仅 10 个文件变更） | 100 次 API 调用 | ~2 次 | 减少 98% |

**优化原理**：
- **智能合并**：按语言类型分组，动态估算 Token 数，多文件合并为一次 API 调用
- **双层缓存**：内存缓存（快速）+ 磁盘缓存（持久化），基于内容哈希
- **增量分析**：自动跳过未变更的文件

**缓存位置**：`~/.code-analysis/cache/`

## 📖 命令概览

```bash
Commands:
    review          代码审查
    review-commit   审查指定提交
    doc             生成文档
    arch            架构分析
    security        安全漏洞扫描
    clone           克隆仓库并分析
    batch-clone     批量克隆仓库
    batch-pull      批量拉取更新
    git-status      查看多仓库状态
    scan-dir        扫描目录结构
    config          配置管理

Options:
    -c, --config <file>     配置文件路径
    --base-url <url>        LLM API 地址
    --api-key <key>         API 密钥
    -m, --model <name>      模型名称
    --max-tokens <n>        最大输出 Token 数 (默认: 4096)
    --timeout <n>           请求超时时间/秒 (默认: 180)
    -o, --output <file>     输出文件路径
    -f, --format <format>   输出格式 (markdown/json)
    -w, --workers <n>       并发线程数 (默认: 5)
    --context               启用上下文增强分析
    --no-cache              禁用缓存（默认启用缓存）
    --no-batch              禁用批量分析（默认启用批量合并）
    --deep                  深度扫描 (安全扫描)
    --branch <name>         克隆的分支名
    --analyze               克隆后自动分析
    --parallel              并行克隆
    --repos <names>         指定仓库名列表（逗号分隔）
    --depth <n>             扫描深度
    --type <type>           文档类型 (module/api)
```

## 🌍 支持的语言

| 语言 | 文件扩展名 | 解析模式 |
|------|------------|----------|
| Python | `.py` | AST |
| Java | `.java` | AST |
| Kotlin | `.kt`, `.kts` | 双模式 |
| C | `.c`, `.h` | 双模式 |
| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx` | 正则 |
| JavaScript | `.js`, `.jsx` | 正则 |
| TypeScript | `.ts`, `.tsx` | 正则 |
| Vue | `.vue` | 正则 |

> 此外还支持配置文件（`.json`、`.yaml`、`.yml`）和文档（`.md`）的分析

## 📚 文档

- [完整使用手册](docs/USER_MANUAL.md)
- [批量分析与缓存优化设计](docs/design/batch-cache-optimization.md)
- [Kotlin 解析器设计](docs/design/kotlin-parser-design.md)
- [C 解析器设计](docs/design/c-parser-design.md)

## 🔧 项目结构

```
code-analysis/
├── cli.py                 # CLI 入口
├── core/
│   ├── analyzer.py        # 分析引擎核心
│   ├── llm_client.py      # LLM 客户端
│   ├── git_handler.py     # Git 操作 + 批量操作
│   ├── config.py          # 配置管理
│   ├── ignore.py          # 统一过滤规则
│   ├── token_estimator.py # Token 估算模块
│   ├── batch_planner.py   # 批量分析规划器
│   ├── batch_analyzer.py  # 批量分析器
│   └── cache_manager.py   # 缓存管理器
├── analyzers/
│   ├── code_review.py     # 代码审查
│   ├── documentation.py   # 文档生成
│   ├── architecture.py    # 架构分析
│   ├── security.py        # 安全扫描
│   ├── directory.py       # 目录分析
│   └── context_builder.py # 上下文构建器
└── parsers/
    ├── python_parser.py   # Python AST 解析器
    ├── java_parser.py     # Java AST 解析器
    ├── kotlin_parser.py   # Kotlin 解析器（双模式）
    ├── c_parser.py        # C 语言解析器（双模式）
    ├── javascript_parser.py # JavaScript 解析器
    ├── typescript_parser.py # TypeScript 解析器
    └── ...
```

## 💡 使用示例

### 代码审查

```bash
# 审查整个项目（结果保存到 result/src_review_20260320_120000.md）
vcode-analysis review ./src

# 使用 10 个线程加速分析
vcode-analysis review ./src --workers 10

# 自定义输出路径
vcode-analysis review ./src --output custom_report.md

# 输出 JSON 格式
vcode-analysis review ./src --format json

# 启用上下文增强（提供项目依赖关系和关联文件信息）
vcode-analysis review ./src --context

# 审查最新提交
vcode-analysis review-commit HEAD

# 审查指定提交
vcode-analysis review-commit abc1234 --path ./src
```

### 文档生成

```bash
# 生成模块文档（默认）
vcode-analysis doc ./src

# 生成 API 文档
vcode-analysis doc ./src --type api

# 自定义输出路径
vcode-analysis doc ./src --output docs.md
```

### 安全扫描

```bash
# 深度安全扫描
vcode-analysis security ./src --deep

# 快速扫描
vcode-analysis security ./src
```

### 批量操作

```bash
# 批量克隆（从文件读取 URL 列表）
vcode-analysis batch-clone repos.txt ./projects --parallel

# 克隆后自动分析
vcode-analysis batch-clone repos.txt ./projects --parallel --analyze

# 克隆指定分支
vcode-analysis clone https://example.com/repo.git --branch develop

# 批量拉取更新
vcode-analysis batch-pull ~/projects

# 拉取指定仓库
vcode-analysis batch-pull ~/projects --repos repo1,repo2

# 查看多仓库状态
vcode-analysis git-status ~/projects
```

## ⚙️ 配置示例

```yaml
# ~/.code-analysis/config.yaml
llm:
  base_url: http://localhost:8000/v1
  api_key: sk-your-api-key
  model: qwen3.5-35b-a3b
  temperature: 0.7
  max_tokens: 4096
  timeout: 180                    # 请求超时时间（秒）

analysis:
  max_file_size: 102400
  max_workers: 5                  # 并发分析线程数

  # 支持的文件扩展名（不在此列表中的文件将被忽略）
  supported_extensions:
    - ".py"
    - ".java"
    - ".kt"
    - ".kts"
    - ".js"
    - ".jsx"
    - ".ts"
    - ".tsx"
    - ".vue"
    - ".c"
    - ".h"
    - ".cpp"
    - ".hpp"
    - ".cc"
    - ".cxx"

  ignore_patterns:
    # 默认已包含多语言依赖目录和缓存文件
    # Python: .venv, venv, __pycache__, .pytest_cache, .mypy_cache
    # Node.js: node_modules, .npm, .yarn
    # Java: target, .gradle
    # Go: vendor
    # .NET: bin, obj
    # 以及: .git, .idea, .vscode, *.pyc, *.min.js 等
    # 用户可在此添加额外的自定义忽略规则

cache:
  ttl: 604800                     # 缓存有效期（秒），默认 7 天
  memory_cache_size: 1000         # 内存缓存最大条目数
```

### 环境变量

除了配置文件，还可以通过环境变量设置（优先级高于配置文件）：

| 环境变量 | 对应配置项 |
|----------|-----------|
| `OPENAI_API_BASE` 或 `OPENAI_BASE_URL` | `llm.base_url` |
| `OPENAI_API_KEY` | `llm.api_key` |
| `CODE_ANALYSIS_MODEL` | `llm.model` |
| `CODE_ANALYSIS_TEMPERATURE` | `llm.temperature` |
| `CODE_ANALYSIS_MAX_TOKENS` | `llm.max_tokens` |

## 🤝 扩展开发

### 添加新的分析器

```python
from core import Analyzer

class CustomAnalyzer:
    def __init__(self, analyzer: Analyzer):
        self.analyzer = analyzer

    def analyze(self, file_path: str) -> dict:
        content = self.analyzer.read_file(file_path)
        prompt = f"分析以下代码：\n{content}"
        result = self.analyzer.llm_client.chat(prompt)
        return {"result": result}
```

### 使用解析器 API

```python
from parsers import KotlinASTParser, CASTParser

# Kotlin 解析
parser = KotlinASTParser()
result = parser.parse_file('Example.kt', mode='auto')

# C 解析
parser = CASTParser()
result = parser.parse_file('main.c', mode='fast')
```

## 📦 发布到 PyPI

### 发布新版本

```bash
# 安装发布工具
pip install build twine

# 构建包
python -m build

# 上传到 PyPI
twine upload dist/*
```

### 发布到 TestPyPI（测试）

```bash
# 上传到 TestPyPI
twine upload --repository testpypi dist/*
```

