codenexus 0.3.4

基于 LadybugDB 与 tree-sitter 的多语言代码知识图谱工具

English | 简体中文

目录

• 简介
• 核心特性
• 安装
• 快速开始
• CLI 命令
• MCP 集成
• 复杂度分析
• 架构
• 支持语言
• 开发
• 贡献
• 路线图
• 许可证

简介

CodeNexus 将源代码仓库索引为可查询的知识图谱。它使用 tree-sitter 进行多语言语法解析，LadybugDB 进行图存储，支持符号追踪、影响分析和数据流分析。

默认 full 预设支持 21 种语言：C、Rust、Fortran、Python、TypeScript、Go、Java、C++、JavaScript、Ruby、Haskell、OCaml、Scala、PHP、C#、Bash、HTML、CSS、JSON、Regex、Verilog。可通过 lang-* feature 选择所需语言，构建最小子集。

核心特性

安装

# 从 crates.io 安装（默认 full 预设，含全部 21 语言 + 所有功能）
cargo install codenexus

# 从源码构建
git clone https://github.com/Kirky-X/codenexus.git
cd codenexus
cargo install --path .

# 或直接编译
cargo build --release

# 仅构建 MCP 功能（默认 full 预设已含全部语言）
cargo build --release --features mcp

Feature 开关

预设：default = ["full"]

日志系统：inklog 是唯一日志后端（console + file rotation + daily 滚动 + LZ4 压缩），不再提供 tracing-subscriber 可选后端。

# 最小构建（仅 Rust，不含 daemon/analysis）
cargo build --release --no-default-features --features minimal

# 核心构建（C + Rust + Python）
cargo build --release --no-default-features --features core

# 单语言精简构建（例如仅 C）
cargo build --release --no-default-features --features lang-c

# 完整构建（默认，含所有语言 + 全部功能）
cargo build --release

# 含向量嵌入的构建
cargo build --release --features embed

快速开始

所有子命令参数均为 必填的 snake_case 长选项（例如 --symbol、--trace_type）。布尔选项需显式传值（true/false）。数据库路径通过全局 --db 选项指定（默认值 ./codenexus.lbug，需置于子命令之前）。

# 1. 索引一个代码仓库
codenexus index --path /path/to/project --name myproject

# 1b. RAM 优先索引（LZ4 内存压缩，适合中小仓库，更快）
codenexus index --path /path/to/project --name myproject --ram_first true

# 2. 查询函数
codenexus query --cypher "MATCH (f:Function) RETURN f.name LIMIT 10"

# 3. 追踪调用链
codenexus trace --symbol main --trace_type calls --depth 5 --path_filter "" --detect_cycles false --cross_service false
# 3b. 增强追踪：路径过滤 + 环检测 + 跨服务
codenexus trace --symbol main --trace_type calls --depth 5 --path_filter "/src/api/**" --detect_cycles true --cross_service true

# 4. 分析变更影响（多维 + 风险评估）
codenexus impact --symbol parse_function --depth 3 --edge_types "" --max_depth 0 --include_tests false
codenexus impact --symbol parse_function --edge_types "CALLS,IMPLEMENTS,USES_TYPE" --max_depth 5 --include_tests true

# 5. 搜索符号（5 种模式 + BM25 全文）
codenexus search --text "parse" --limit 20 --mode exact --fulltext false --project ""
codenexus search --text "get.*user" --mode regex --fulltext false --project ""
codenexus search --text "getuser" --mode fuzzy --fulltext false --project ""
codenexus search --text "authentication logic" --fulltext true --project ""

# 6. 360° 符号上下文（基础 + 多维增强）
codenexus context --symbol main --depth 1 --project "" --enhanced false
codenexus context --symbol main --project myproject --enhanced true

# 7. 检测 git diff 影响的符号
codenexus detect_changes --path /path/to/project --mode git

# 8. 重命名符号（图编辑 + 文本搜索；apply=false 即 dry-run）
codenexus rename --from old_name --to new_name --path /path/to/project --apply false

# 9. 导出 / 导入团队制品（--db 为全局选项，置于子命令之前）
codenexus --db ./my.lbug export --output team.graph.zst --project ""
codenexus --db ./shared.lbug import --input team.graph.zst --reindex false --path "" --name ""

# 10. 多智能体 MCP 集成
codenexus setup                    # 自动检测智能体，写入 MCP 配置
codenexus hook                     # 输出 PreToolUse/PostToolUse JSON
codenexus mcp                      # stdio MCP 服务（JSON-RPC 2.0）

# 11. 查看索引状态
codenexus status

# 12. 启动文件监视守护进程
codenexus daemon --path /path/to/project --name myproject

# 13. 列出所有项目
codenexus list

# 14. 删除项目
codenexus clean --project myproject

# 15. 死代码检测（多边类型 + FFI/导出检测 + 置信度）
codenexus dead_code --project myproject --entry "" --check_exported true --check_ffi true --edge_types ""
codenexus dead_code --project myproject --edge_types "CALLS,FFI_CALLS,IMPLEMENTS,USAGE,TESTS"

# 16. 跨服务调用链检测（HTTP REST / gRPC / GraphQL / 消息队列 / 事件总线）
codenexus cross_service --project myproject --protocol ""
codenexus cross_service --project myproject --protocol grpc

# 17. 架构概览（模块边界 + 依赖方向 + 分层 + 跨服务依赖）
codenexus architecture --project myproject

CLI 命令

MCP 集成

CodeNexus 使用 sdforge 提供 MCP（Model Context Protocol）服务器，通过 sdforge mcp stdio 传输暴露 6 个工具：

# 启动 MCP 服务（stdio）
codenexus mcp [--db <DB_PATH>]

# 自动检测智能体并写入 MCP 配置
codenexus setup

setup 自动检测已安装的 Claude Code（~/.claude/）、Cursor（~/.cursor/）、Codex（~/.codex/），并写入对应的 MCP 配置文件，指向 codenexus mcp。使用 --force 可跳过确认提示覆盖已有配置。

复杂度分析

complexity 子命令对项目内所有函数计算 AST 复杂度指标，输出 JSON（含 complexity 数组与 summary 统计）。

指标

每项指标按阈值分为 Green / Yellow / Red / Critical 四级，overall_severity 取最高级别。

阈值 CLI 参数

<O(...)> 取值：时间 O(1) / O(log n) / O(n) / O(n log n) / O(n^2) / O(n^3) / O(2^n)，空间 O(1) / O(n) / O(n^2)。未设置的参数走默认值。

默认阈值

maintainability 阈值含义反转：MI 越高越好，value >= green → Green，value >= yellow → Yellow，value >= red → Red，否则 Critical。space_complexity 只有 3 级（Green/Yellow/Red），无 Critical。

示例

# 默认阈值分析
codenexus complexity --project myproject

# 自定义圈复杂度阈值（green=5, yellow=10, red=15）
codenexus complexity --project myproject --cyclomatic_green 5 --cyclomatic_yellow 10 --cyclomatic_red 15

# 仅显示 Red 和 Critical 级函数并按严重度排序
codenexus complexity --project myproject --red_only true --sort_by_severity true

# 自定义时间复杂度阈值（green=O(1), yellow=O(n log n), red=O(n^2)）
codenexus complexity --project myproject --time_complexity_green "O(1)" --time_complexity_yellow "O(n log n)" --time_complexity_red "O(n^2)"

架构

三层源码结构

v0.3.2 起，CLI 和 MCP 接口通过 sdforge 的 #[forge] 宏统一封装在 src/service/ 模块中， 每个命令定义 core 函数 + CLI wrapper + MCP wrapper，替代了此前的 src/cli/*_cmd.rs 和 src/mcp/ 模块。

索引管线

graph TB
    subgraph "用户层"
        CLI["CLI (sdforge CliBuilder)"]
    end

    subgraph "核心层"
        IP["Index Pipeline<br/>索引流水线"]
        Q["Query<br/>查询引擎"]
        T["Trace<br/>追踪引擎"]
        D["Daemon<br/>守护进程"]
    end

    subgraph "解析层"
        R["Resolve<br/>符号解析 + 数据流"]
        P["Parse<br/>tree-sitter 多语言提取"]
    end

    subgraph "存储层"
        S["Storage<br/>LadybugDB"]
        H["Hash<br/>SHA-256 增量"]
    end

    CLI --> IP
    CLI --> Q
    CLI --> T
    CLI --> D
    IP --> R
    IP --> P
    IP --> S
    IP --> H
    Q --> S
    T --> S
    D --> IP

    style CLI fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style IP fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style S fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    style P fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

索引流程

1. 文件发现 — ignore crate 遵守 .gitignore 规则
2. 增量哈希 — SHA-256 比对，跳过未变更文件
3. 并行解析 — Rayon 并行 + tree-sitter 提取节点/边
4. 符号解析 — FQN 生成、调用解析、数据流分析、跨语言 FFI
5. 批量入库 — CSV 生成 + COPY FROM 批量加载

图模型

• 44 种节点类型：Project, Folder, File, Module, Class, Struct, Enum, Trait, Impl, Function, Method, Variable, GlobalVar, Parameter, Const, Static, Macro, TypeAlias, Typedef, Namespace, Interface, Constructor, Property, Record, Delegate, Annotation, Template, Union, Variant, Field, Event, Handler, Middleware, Service, Endpoint, Route, Process, Database, Config, Test, Section, Community, Tool, Embedding
• 30 种边类型：Contains, Defines, MemberOf, Calls, FfiCalls, DataFlows, Reads, Writes, Implements, Extends, UsesType, References, Imports, Includes, HasMethod, HasProperty, Accesses, MethodOverrides, MethodImplements, StepInProcess, HandlesRoute, Fetches, HandlesTool, EntryPointOf, Usage, Tests, HttpCalls, AsyncCalls, Emits, ListensOn
• 每条边携带置信度分数 (0.0-1.0) 和置信度分层（SameFile / ImportScoped / Global）

支持语言

默认 full 预设编译 21 种语言。下表列出其中 8 种核心语言（C/Rust/Fortran/Python/TypeScript/Go/Java/C++）及其主要提取的节点/边类型；full 在此基础上额外启用 JavaScript、Ruby、Haskell、OCaml、Scala、PHP、C#、Bash、HTML、CSS、JSON、Regex、Verilog。

开发

# 运行测试
cargo test

# 代码检查
cargo clippy -- -D warnings

# 格式化
cargo +nightly fmt

# 基准测试
cargo bench

贡献

欢迎提交 Issue 和 Pull Request。请确保通过 cargo test 和 cargo clippy -- -D warnings。

详细贡献指南请参考 CONTRIBUTING.md。

路线图

CodeNexus 按当前优先级排序的规划工作：

• v0.1.0 — 多语言索引（C/Rust/Fortran/Python/TypeScript）、图模式（44 种节点类型 + 30 种边类型）、query/trace/impact/context/search、增量索引、RAM 优先模式、MCP 服务、团队 export/import、守护进程模式、置信度分层、歧义消解
• v0.1.x — 稳定性与性能加固：增量重索引覆盖、大仓库内存调优、更多语言专属边提取
• v0.2.0 — lsp feature：LSP 增强提取，超越 tree-sitter 的类型精确解析（rust-analyzer 集成）
• v0.2.0 — 扩展语言覆盖（Go、Java、C++，以及 JavaScript/Ruby/Haskell/OCaml/Scala/PHP/C#/Bash/HTML/CSS/JSON/Regex/Verilog），由新的 lang-* feature 控制
• v0.2.0 — 分析工具包：死代码检测、架构概览、API 审查（route_map/shape_check/api_impact/tool_map）、社区检测、跨服务链接检测
• v0.2.1 — AST 复杂度分析：圈/认知复杂度、嵌套深度、函数长度，绿/黄/红/致命四级告警
• v0.3.0 — sdforge-based MCP 服务器：#[forge] 宏 + sdforge mcp stdio 传输，替代手写 JSON-RPC；6 个工具（query/trace/impact/search/context/architecture）
• v0.3.2 — 跨语言数据流端到端追踪：TaintPathTracer BFS 遍历 DataFlows/Reads/Writes/FfiCalls 边
• v0.3.2 — 向量嵌入默认开启语义搜索（embed feature 已包含在 full 预设中）
• v0.3.3 — 国际化模块（i18n feature）：ICU4X Unicode case folding + NFC 规范化 + CJK 边界检测
• v0.3.3 — Harness 现代化：CI 升级 Rust 1.91 + 6 特性矩阵 + dependabot + codeql + crates.io 发布
• 未来 — 基于查询门面的 Web UI / 图可视化

许可证

MIT