MRJR0101/CodeGraphX

# CodeGraphX [](https://github.com/MRJR0101/CodeGraphX/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) [](CHANGELOG.md) CodeGraphX 是一个本地优先的代码智能 CLI 工具，它能够扫描代码库，将源文件解析为结构化事实，发出确定性图事件，并支持影响分析、快照、差异比较以及可选的 Neo4j 加载。 ## 为什么选择 CodeGraphX - 确定性输出：未更改的输入会生成稳定的 JSONL 构件和哈希值。 - 增量执行：解析、提取和图加载会重用缓存状态。 - 数据库可选：`scan`、`parse`、`extract`、`snapshots` 和 `delta` 可以在没有 Neo4j 的情况下工作。 - 可检查的流水线：每个阶段都会写入可供差异比较、审计和重放的构件。 - CI 覆盖：该代码库在 Ubuntu 和 Windows 上针对 Python 3.11 到 3.13 进行了测试。 ## 安装 ``` git clone https://github.com/MRJR0101/CodeGraphX.git cd CodeGraphX # pip python -m venv .venv .venv\Scripts\activate # Windows PowerShell # source .venv/bin/activate # Linux/macOS pip install -e ".[dev]" # 或 uv uv sync --all-groups ``` 验证 CLI： ``` python -m codegraphx --version python -m codegraphx --help ``` `python cli/main.py` 仍作为旧版兼容性垫片受到支持，但规范的入口点是 `python -m codegraphx` 和 `codegraphx`。 ## 快速开始 1. 从示例创建本地项目文件： ``` cp config/projects.example.yaml config/projects.yaml ``` 2. 编辑 `config/projects.yaml` 以指向一个或多个代码库。 3. 运行流水线： ``` codegraphx scan codegraphx parse codegraphx extract ``` 4. 检查前几个发出的事件： ``` Get-Content data/events.jsonl -TotalCount 5 # Windows PowerShell # head -n 5 data/events.jsonl # POSIX shells ``` ### 可选 Neo4j 设置 复制示例环境文件并填写您的凭据： ``` cp .env.example .env ``` **选项 A -- Docker（推荐用于本地使用）：** ``` # 使用 .env 中的凭证启动 Neo4j 5 容器 .\start-neo4j.ps1 ``` 该脚本会创建一个名为 `neo4j-cgx` 的容器，等待 bolt 准备就绪，并打印连接详细信息。在您需要 Neo4j 时随时运行它。要停止： ``` docker stop neo4j-cgx ``` **选项 B -- 现有的 Neo4j 实例：** 将您的 `.env` 中的 `NEO4J_URI`、`NEO4J_USER` 和 `NEO4J_PASSWORD` 指向正在运行的实例。 然后验证并加载： ``` codegraphx doctor codegraphx load codegraphx query "MATCH (f:Function) RETURN f.name LIMIT 10" ``` `load` 之后，`search` 命令会使用快速的 SQLite FTS 索引： ``` codegraphx search parse --index functions ``` CodeGraphX 在被 `config/default.yaml` 引用时会自动加载 `.env`。 ## 流水线 ``` Source repo(s) | v [scan] -> scan.jsonl File inventory by project/root/path | v [parse] -> ast.jsonl Parsed functions/imports/calls parse.cache.json parse.meta.json | v [extract] -> events.jsonl Project/File/Function/Symbol/Module events extract.cache.json extract.meta.json | v [load] -> Neo4j Incremental merge and stale-record cleanup load.state.json load.meta.json | v [search/query/impact/analyze/delta/snapshots] ``` ## 图模型 | Node | Key Properties | |------|----------------| | `Project` | `name` | | `File` | `uid`, `project`, `path`, `rel_path`, `language`, `line_count` | | `Function` | `uid`, `name`, `line`, `project`, `file_uid`, `signature_hash` | | `Symbol` | `uid`, `name` | | `Module` | `uid`, `name` | | Edge | Meaning | |------|---------| | `CONTAINS` | `Project -> File` | | `DEFINES` | `File -> Function` | | `CALLS` | `Function -> Symbol` 或 `File -> Symbol` | | `IMPORTS` | `File -> Module` | | `CALLS_FUNCTION` | `Function -> Function` | ## 命令 ### 核心流水线 | Command | Purpose | |---------|---------| | `scan` | 从 `config/projects.yaml` 发现项目文件 | | `parse` | 将支持的文件解析为类 AST 记录 | | `extract` | 将解析后的记录转换为图事件 | | `load` | 增量地将事件应用到 Neo4j | ### 分析与差异比较 | Command | Purpose | |---------|---------| | `analyze metrics` | 函数扇入/扇出样式指标 | | `analyze hotspots` | 基于已加载图数据的高行数热点 | | `analyze security` | 基于名称的安全模式查询 | | `analyze debt` | 聚合债务样式摘要 | | `analyze refactor` | 基于名称过滤的重构候选 | | `analyze duplicates` | 签名哈希重复检测 | | `analyze patterns` | 面向模式的函数搜索 | | `analyze full` | 多章节摘要报告 | | `snapshots create/list/diff/report` | 快照生命周期命令 | | `delta` | 详细的快照增量报告 | ### 搜索与查询 | Command | Purpose | |---------|---------| | `query` | 针对 Neo4j 运行 Cypher | | `search` | 按名称/路径搜索提取的事件 | | `ask` | 运行基于模板的 NL 样式查询 | | `compare` | 比较两个项目 | | `impact` | 追踪直接和传递调用者 | ### 诊断与自动化 | Command | Purpose | |---------|---------| | `doctor` | 验证配置、导入和可选的 Neo4j 连接 | | `completions` | 打印 shell 补全指南 | | `enrich backlog` | 对来自 SQLite 目录的候选代码库进行排序 | | `enrich chunk-scan` | 针对目标根目录运行分块扫描 | | `enrich campaign` | 计划或执行排序的丰富化活动 | | `enrich index-audit` | 审核推荐的 SQLite 索引 | | `enrich collectors` | 计算收集器样式的项目信号 | | `enrich intelligence` | 计算相似度和智能信号 | ## 配置 项目根目录在本地 `config/projects.yaml` 文件中配置： ``` projects: - name: DemoPython root: C:/path/to/python_project exclude: - .venv - __pycache__ - dist - build ``` 运行时行为来自 `config/default.yaml`： ``` run: out_dir: data max_files: 0 include_ext: [".py", ".js", ".ts"] neo4j: uri: ${NEO4J_URI:-bolt://localhost:7687} user: ${NEO4J_USER:-neo4j} password: ${NEO4J_PASSWORD:-} database: ${NEO4J_DATABASE:-neo4j} ``` 环境变量扩展使用 `${VAR:-default}` 语法。 ## 验证 ``` python -m pytest -q python -m codegraphx --help powershell -ExecutionPolicy Bypass -File .\scripts\smoke_no_db.ps1 -ReportPath smoke_no_db_report.json ``` 要运行完整的本地检查，请安装 `uv` 并运行： ``` powershell -ExecutionPolicy Bypass -File .\scripts\release_check.ps1 ``` ## 安全说明 - 用户提供的 Cypher 参数与查询文本分开传递。 - `query --safe` 为临时查询执行添加词法保护。 - 流水线中的路径处理避免遍历配置的根目录之外。 - 凭据应存在于 `.env` 或环境变量中，而不是提交的 YAML 中。 ## 文档 | Document | Purpose | |----------|---------| | [docs/README.md](docs/README.md) | 文档入口与导航 | | [docs/commands.md](docs/commands.md) | 命令示例与参考 | | [docs/design.md](docs/design.md) | 架构与阶段行为 | | [docs/schema.md](docs/schema.md) | 图实体与身份 | | [docs/queries.md](docs/queries.md) | 查询示例与模式 | | [docs/security-architecture.md](docs/security-architecture.md) | 威胁模型与保障措施 | | [docs/roadmap.md](docs/roadmap.md) | 计划工作 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献者工作流 | | [VERIFY.md](VERIFY.md) | 当前验证清单 | | [CHANGELOG.md](CHANGELOG.md) | 发布历史 | ## 兼容性 | Component | Supported | |-----------|-----------| | Python | 3.10+ | | CI matrix | 3.11, 3.12, 3.13 | | OS | Windows 和 Linux | | Neo4j | 5.x | ## 许可证 [MIT](LICENSE)

标签：AST解析, JSONL, Neo4j, Python, Tree-sitter, WebSocket, 云安全监控, 代码安全, 代码智能, 代码理解, 依赖分析, 增量解析, 影响分析, 快照差异, 数据管道, 数据管道, 无后门, 本地优先, 漏洞枚举, 请求拦截, 软件工程, 软件工程, 逆向工具, 静态分析