xnt/codexray

# Codexray 一款面向 TypeScript 仓库的本地优先代码健康与重构分析工具。 ## 概述 Codexray 扫描 TypeScript 代码库，检测可维护性与结构性问题，使用字母等级（A–F）评估整体健康度，生成可操作的重构计划，并可视化符号级别的关系——所有操作完全离线。它在安装后本地运行，并且设计上易于 Dockerize。 ## 功能特性 - **CLI 优先体验** — 简单的命令行界面，包含六个命令：`scan`、`fix`、`report`、`explain`、`plan`、`symbols` - **本地优先** — 运行时无网络依赖 - **仅限 TypeScript** — 专注于 TypeScript 项目的分析 - **10 条内置规则** — 复杂度、嵌套、参数、抽象混合、错误处理、God modules（上帝模块）、布尔陷阱、switch 多态等 - **可维护性评级** — A–F 字母等级，附带扣分明细与热点识别 - **重构规划器** — 发现结果会被聚类，推断根本原因，并生成包含理由与步骤的优先计划项 - **符号分析** — 发现函数、类、方法和箭头函数；构建调用/包含图；在 TUI 和 HTML 中可视化关系 - **多格式输出** — 针对扫描、计划和符号，支持终端（彩色）、JSON 和 HTML 报告 - **安全的自动修复** — 针对明确安全场景的有限转换（例如，early-return 重构） - **可扩展** — 设计上支持更多规则、报告器和聚类策略 ## 快速开始 ``` # 克隆并构建 git clone cd codexray npm install npm run build # 扫描示例 fixture 项目 npm run scan:sample # 扫描 Codexray 自身源代码 npm run scan:src # 扫描任意 TypeScript 项目 (使用 -- 传递参数) npm run scan -- /path/to/your/project # 使用选项扫描 npm run scan -- ./src --verbose npm run scan -- ./src --format json npm run scan -- ./src --rules max-params,no-large-functions # 生成重构计划 npm run plan:sample # 可视化符号及其关系 npm run symbols:sample # 预览自动修复 (dry-run) npm run fix:dry # 运行所有测试 npm test # 运行测试并生成覆盖率 npm test -- --coverage ``` ## 安装 ``` npm install -g codexray ``` 或者直接通过 npx 使用： ``` npx codexray scan ./src ``` ## 使用方法 ### 扫描项目 ``` # 扫描目录 codexray scan ./src # 使用 JSON 输出扫描 codexray scan ./src --format json # 使用 HTML 输出扫描 codexray scan ./src --format html --output report.html # 使用特定规则扫描 codexray scan ./src --rules max-params,no-large-functions # 详细输出 codexray scan ./src --verbose # 保存输出到文件 codexray scan ./src --format json --output report.json ``` ### 修复问题 ``` # 预览修复 (dry-run) codexray fix ./src --dry-run # 应用修复 codexray fix ./src # 仅修复特定规则 codexray fix ./src --rules prefer-early-return # 修复前创建备份 codexray fix ./src --backup ``` ### 生成报告 ``` # 生成终端报告 codexray report ./src # 生成 JSON 报告 codexray report ./src --format json --output report.json # 生成 HTML 报告 codexray report ./src --format html --output report.html ``` ### 解释规则 ``` # 列出所有可用规则 codexray explain # 解释特定规则 codexray explain no-large-functions ``` ### 生成重构计划 ``` # 终端计划 (默认) codexray plan ./src # JSON 计划 codexray plan ./src --format json --output plan.json # HTML 计划 codexray plan ./src --format html --output plan.html # 仅针对特定规则的计划 codexray plan ./src --rules no-large-functions,no-deep-nesting ``` 规划器会将相关发现聚类，推断根本原因，并生成优先的计划项，包含： - **理由 (Rationale)** — 为什么需要此重构 - **建议步骤** — 具体、有序的操作 - **影响 / 工作量 / 置信度** 估算 - **符号感知聚类** — 将影响相关函数或方法的发现分组 ### 探索符号 ``` # 终端符号浏览器 (默认) codexray symbols ./src # HTML 符号报告 codexray symbols ./src --format html --output symbols.html ``` `symbols` 命令会发现所有函数、类、方法、箭头函数、构造函数和访问器。它构建调用/包含图并渲染： - 包含调用边的单文件符号树 - 类别细分和汇总统计 - **TLDR** — 一目了然地展示最繁忙的文件、最大的类、连接最多的符号以及导出表面 ## 内置规则 ### no-large-functions 检测超过可配置行数阈值的函数。 - **默认阈值**: 50 行 - **严重程度**: warning - **选项**: `maxLines` - 允许的最大行数 ``` { "rules": { "no-large-functions": { "enabled": true, "severity": "warning", "options": { "maxLines": 50 } } } } ``` ### max-params 检测参数过多的函数。 - **默认阈值**: 4 个参数 - **严重程度**: warning - **选项**: `maxParams` - 允许的最大参数数量 ``` { "rules": { "max-params": { "enabled": true, "severity": "warning", "options": { "maxParams": 4 } } } } ``` ### no-deep-nesting 检测嵌套深度超过阈值的函数。 - **默认阈值**: 4 层 - **严重程度**: warning - **选项**: `maxDepth` - 允许的最大嵌套深度 ``` { "rules": { "no-deep-nesting": { "enabled": true, "severity": "warning", "options": { "maxDepth": 4 } } } } ``` ### prefer-early-return 检测可以通过 guard clauses（卫语句）简化的嵌套条件语句。 - **默认阈值**: 2 层嵌套 - **严重程度**: info - **支持自动修复**: 是（针对安全场景） - **选项**: `minNestingLevel` - 报告的最小嵌套层数 ``` { "rules": { "prefer-early-return": { "enabled": true, "severity": "info", "options": { "minNestingLevel": 2 } } } } ``` ### boolean-parameter-trap 检测创建模糊调用点的布尔参数。 - **严重程度**: warning - **选项**: `minPosition` - 标记的最小参数位置（从 0 开始索引） ``` { "rules": { "boolean-parameter-trap": { "enabled": true, "severity": "warning", "options": { "minPosition": 0 } } } } ``` **示例:** ``` // ❌ Bad - what does true mean? createUser('john', true); // ✅ Better - use options object createUser('john', { isAdmin: true }); // ✅ Or split into separate functions createAdminUser('john'); ``` ### mixed-abstraction-levels 检测混合了高层编排与底层实现的函数。 - **严重程度**: warning - **选项**: - `minHighLevelScore` - 最小高层信号数（默认: 1） - `minLowLevelScore` - 最小底层信号数（默认: 2） ``` { "rules": { "mixed-abstraction-levels": { "enabled": true, "severity": "warning", "options": { "minHighLevelScore": 1, "minLowLevelScore": 2 } } } } ``` **高层信号:** 函数调用、分支、名称中的编排动词 **底层信号:** 循环、new 表达式、属性赋值、字符串格式化 ### inconsistent-error-handling 检测使用多种错误处理策略的文件。 - **严重程度**: warning - **选项**: `minFunctionCount` - 检查的最小函数数量（默认: 2） ``` { "rules": { "inconsistent-error-handling": { "enabled": true, "severity": "warning", "options": { "minFunctionCount": 2 } } } } ``` **检测到的策略:** - `throw` - 抛出异常 - `null-return` - 错误时返回 null - `undefined-return` - 错误时返回 undefined - `result-object` - 返回 `{ ok, data, error }` 风格的对象 - `fallback-in-catch` - 捕获并返回回退值 ### switch-wants-polymorphism 检测更适合使用 handler maps（处理器映射）或多态的 switch 语句。 - **严重程度**: info - **选项**: - `minCases` - 考虑的最小 case 数量（默认: 3） - `minStructuralSimilarity` - 相似度阈值 0-1（默认: 0.6） ``` { "rules": { "switch-wants-polymorphism": { "enabled": true, "severity": "info", "options": { "minCases": 3 } } } } ``` **检测内容:** - 类类型判别式 (type, kind, status, mode, provider) - 相似的 case 结构 - 跨 case 的重复赋值目标 ### god-module 检测职责过多的文件。 - **严重程度**: warning - **选项**: `minScore` - 触发的最小分数（默认: 3） ``` { "rules": { "god-module": { "enabled": true, "severity": "warning", "options": { "minScore": 3 } } } } ``` **评分标准:** - 行数: >300 得 +1，>600 得 +2 - 导出数: >8 得 +1，>15 得 +2 - 函数/方法数: >10 得 +1 - 类数: >2 得 +1 - 顶层语句数: >20 得 +1 - 导入区域数: >8 得 +1 ## 配置 在你的项目根目录创建一个 `codexray.config.json` 文件： ``` { "version": "1.0.0", "include": ["**/*.ts", "**/*.tsx"], "exclude": ["node_modules/**", "dist/**", "**/*.d.ts"], "rules": { "no-large-functions": { "enabled": true, "options": { "maxLines": 40 } }, "max-params": { "enabled": true, "options": { "maxParams": 3 } }, "no-deep-nesting": { "enabled": true, "options": { "maxDepth": 3 } }, "prefer-early-return": { "enabled": true } } } ``` ## 退出码 - `0` - 未发现错误 - `1` - 发现错误或命令失败 ## 开发 ``` # 安装依赖 npm install # 构建 npm run build # 运行测试 npm test npm run test:watch # Watch mode npm test -- --coverage # Coverage report # Scan 快捷方式 npm run scan # Scan (pass path after --) npm run scan:sample # Scan sample fixture npm run scan:src # Scan Codexray's source npm run scan:json # Scan with JSON output npm run scan:html # Scan with HTML output # Plan 快捷方式 npm run plan:sample # Plan for sample fixture npm run plan:json # Plan as JSON npm run plan:html # Plan as HTML # Symbol 快捷方式 npm run symbols:sample # Symbols for sample fixture npm run symbols:html # Symbols as HTML # Fix 快捷方式 npm run fix:dry # Preview autofixes ``` ### 传递参数 使用 `--` 向 npm scripts 传递参数： ``` npm run scan -- ./your-project npm run scan -- ./src --verbose --format json npm run plan -- ./your-project --format html --output plan.html npm run symbols -- ./your-project ``` ## 架构 Codexray 设计上关注点分离清晰： ``` src/ ├── cli/ # CLI layer (commands: scan, fix, report, explain, plan, symbols) ├── core/ # Analysis engine (scanner, analyzer, project loader) ├── rules/ # Rule system (types, registry, 10 implementations) ├── findings/ # Finding model (types) ├── fixes/ # Fix/edit model (types, apply logic) ├── planner/ # Refactor planner (clustering, inference, priority, generation) ├── rating/ # Maintainability rating engine (A–F grading) ├── symbols/ # Symbol subsystem (discovery, graph, index, call resolution) ├── reporters/ # Output adapters (terminal, JSON, HTML — for scans, plans, symbols) ├── config/ # Configuration (types, defaults) └── utils/ # AST helpers, error-handling helpers, scoring helpers ``` ### 扩展点 - **Rules (规则)**: 通过在 `src/rules/implementations/` 中实现 `Rule` 接口来添加新规则 - **Reporters (报告器)**: 通过在 `src/reporters/` 中实现报告器模式来添加新的输出格式 - **Fixes (修复)**: 通过实现 `AutoFixableRule` 添加自动修复能力 - **Planner patterns (规划器模式)**: 在 `src/planner/inference.ts` 中添加推断启发式算法 - **Clustering strategies (聚类策略)**: 在 `src/planner/clustering.ts` 中添加新的分组策略 - **Symbol analysis (符号分析)**: 使用新的边类型或跨文件解析扩展符号图 ## 许可证 MIT

标签：GNU通用公共许可证, HTML报告, MITM代理, Node.js, TUI, TypeScript, 云计算, 代码健康, 代码可视化, 代码复杂度, 代码规范, 依赖图, 可维护性, 安全插件, 开发效率, 扫描器, 技术债务, 数据管道, 文档结构分析, 暗色界面, 本地优先, 清理工具, 离线运行, 符号分析, 网络可观测性, 聊天机器人, 自动修复, 自动化攻击, 规则引擎, 软件工程, 重构工具, 错误基检测, 静态代码分析