codn_ts/README.md

智能代码分析工具 - 支持语义搜索、调用链分析和代码结构可视化，对大模型/AI agent 友好

# codn_ts - 智能代码分析工具

[![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
[![Test Coverage](https://img.shields.io/badge/Test%20Coverage-26%25-orange)](https://github.com/dweb-lab/codn_ts)

**codn_ts** 是一个基于 TypeScript 的智能代码分析工具，支持作为库和 CLI 工具使用，对大模型/AI agent 友好。

## ✨ 核心特性

### 🎯 智能语义搜索
- **5维度加权评分系统**：精确匹配、语义关键词、上下文相关性、依赖关系、使用频率
- **50+ 语义类别**：认证、数据处理、网络、数据库、文件操作、错误处理等
- **LSP 集成**：准确的代码结构分析
- **JSON 输出**：AI 友好的结构化数据

### 🔍 多维度搜索与分析
- **文件/符号/内容/语义搜索**
- **引用关系分析**：函数/类/变量引用关系
- **符号引用分析**：`cod ref` 支持精准分析任意符号的调用方/被调方
- **诊断检查**：`cod check` 基于 LSP 输出语法/类型错误和警告
- **调用链可视化**：生成 Mermaid 图表
- **项目统计**：代码质量分析

### 🛠️ 实用工具
- **目录列表**、**文件查看**、**语言检测**
- **MCP 协议支持**：可被 Claude Desktop/Agent 等 AI 工具远程调用

## 🚀 快速开始

### 安装

```bash
# 全局安装
npm install -g codn_ts

# 或本地安装
npm install codn_ts
```

### 基本使用

```bash
# 语义搜索
cod search "authentication" --semantic --json

# 文件大纲模式（查看单个文件的类和函数）
cod search "" -f src/index.ts --type all --json

# 分析引用关系
cod analyze --json

# 符号引用分析
cod ref -s "main" --json

# 诊断检查
cod check
cod check --file src/index.ts --json

# 调用链可视化
cod analyze --call-chain --from "main" --format mermaid --output callchain.md

# 列出目录
cod ls --long --json

# 查看文件
cod cat src/semantic_search.ts --json
```

## 📖 详细使用指南

### CLI 命令

#### `cod search` - 智能搜索
```bash
cod search "functionName"
cod search "authentication" --semantic
cod search "api" --type file,symbol,content
cod search "database" --semantic --json

# 文件大纲模式 - 查看单个文件结构
cod search "" -f src/user.ts --type all --json
cod search "" -f src/user.ts --type class
cod search "" -f src/user.ts --type function
```

#### `cod analyze` - 代码分析
```bash
cod analyze
cod analyze --call-chain --from "main"
cod analyze --call-chain --format mermaid --output diagram.md
cod analyze --json
```

#### `cod ref` - 符号引用分析
```bash
# 分析函数/类/变量引用关系
cod ref -s "authenticateUser"
cod ref -s "UserService" --json
cod ref -s "main" --format mermaid --output ref.md
```

#### `cod check` - 诊断检查（LSP）
```bash
# 全项目诊断
cod check
# 单文件诊断
cod check --file src/index.ts
# JSON 输出
cod check --json
```

#### `cod ls` - 目录列表
```bash
cod ls
cod ls --long
cod ls --recursive
cod ls --json
```

#### `cod cat` - 文件查看
```bash
cod cat src/index.ts
cod cat src/index.ts --line-numbers
cod cat src/index.ts --json
```

### 编程接口

```typescript
import { 
  searchProject, 
  analyzeProjectReferences,
  listDirectory,
  readFile,
  semanticSearch 
} from 'codn_ts';

// 语义搜索
const results = await semanticSearch(projectPath, "authentication", {
  semantic: true,
  json: true
});

// 分析引用关系
const references = await analyzeProjectReferences(projectPath);

// 搜索项目
const searchResults = await searchProject(projectPath, "api", {
  types: ['file', 'symbol', 'content']
});

// 列出目录
const files = await listDirectory(projectPath, {
  long: true,
  recursive: true
});

// 读取文件
const content = await readFile(filePath, {
  lineNumbers: true
});
```

## 🏗️ 技术架构

```
src/
├── index.ts              # 统一导出接口
├── cli.ts                # CLI 入口
├── search.ts             # 搜索功能
├── semantic_search.ts    # 语义搜索（5维度评分）
├── callChain.ts          # 调用链分析
├── ls.ts                 # 目录列表
├── cat.ts                # 文件读取
└── utils/
    ├── lsp_core.ts       # LSP 客户端
    ├── os_utils.ts       # 系统工具
    ├── reference_analyzer.ts  # 引用分析
    └── symbol_utils.ts   # 符号工具
```

## 🧪 测试

```bash
# 运行测试
npm test

# 运行测试覆盖率
npm run test:coverage
```

当前测试状态：
- ✅ 57个测试用例全部通过
- ✅ 核心模块覆盖率：96%+
- ✅ 生产就绪质量

## 📦 开发

### 构建
```bash
git clone https://github.com/dweb-lab/codn_ts.git
cd codn_ts
npm install
npm run build
```

### 开发模式
```bash
# 开发模式运行
npm run dev

# 格式化代码
npm run format

# 代码检查
npm run lint
```

## 🎯 使用场景

### 1. AI Agent 集成
```typescript
// 为 AI 提供代码上下文
const context = await semanticSearch(projectPath, userQuery, {
  semantic: true,
  json: true,
  limit: 10
});
```

### 2. 文件大纲查看
```bash
# 查看文件中的所有类和函数（类似 IDE 大纲）
cod search "" -f src/user.ts --type all --json

# 查看特定类的方法列表
cod show -f src/user.ts -s UserService -m methods
```

### 3. 代码审查
```bash
# 分析函数调用关系
cod analyze --call-chain --from "processPayment" --format mermaid

# 在特定文件中查找问题
cod search "TODO|FIXME" -f src/legacy.ts --regex
```

### 4. 项目重构
```bash
# 查找所有使用特定 API 的地方
cod search "deprecatedAPI" --semantic --type symbol,content

# 分析单个文件的依赖关系
cod search "" -f src/user.ts --semantic
```

### 5. 文档生成
```bash
# 生成项目结构图
cod analyze --call-chain --format mermaid --output docs/architecture.md

# 生成文件大纲文档
cod search "" -f src/user.ts --json > docs/user-outline.json
```

## 🔧 配置选项

### 搜索配置
- `-f, --file`: 限制搜索到指定文件（文件大纲模式）
- `--semantic`: 启用语义搜索
- `--type`: 指定搜索类型 (file|symbol|content)
- `--limit`: 限制结果数量
- `--json`: JSON 格式输出

### 分析配置
- `--call-chain`: 生成调用链
- `--from`: 指定起始函数
- `--format`: 输出格式 (json|mermaid|text)
- `--output`: 输出文件路径

### LSP 配置
可以通过 `LSPUserConfig` 接口自定义 LSP 配置，包括使用绝对路径指定语言服务器：

```typescript
import { LSPClient, LSPUserConfig } from 'codn_ts';

// 自定义 LSP 配置，可以使用绝对路径
const customConfig: LSPUserConfig = {
  timeout: 60000,
  logLevel: "debug",
  lspCommands: {
    // 使用自定义的绝对路径指定语言服务器
    typescript: ["/usr/local/bin/typescript-language-server", "--stdio"],
    python: ["/path/to/your/pyright-langserver", "--stdio"],
  }
};

// 将自定义配置传递给 LSPClient
const client = new LSPClient(rootUri, customConfig);
await client.start("typescript");
```

## 🤝 贡献

我们欢迎贡献！请查看我们的 [贡献指南](CONTRIBUTING.md)。

## 📄 许可证

MIT © askender

## 🗺️ 路线图

- [x] 核心搜索功能
- [x] 文件大纲模式（单文件符号查看）
- [x] 语义搜索
- [x] 调用链分析
- [x] CLI 工具
- [x] 测试覆盖
- [ ] Web 可视化界面
- [ ] 插件系统
- [ ] 多语言支持
- [ ] 企业级功能

### 🌐 MCP 协议与 AI 生态支持

- 支持 MCP 协议，可通过 HTTP JSON-RPC 远程调用 `codn_ref`（符号引用分析）、`codn_check`（诊断检查）等能力
- 适配 Claude Desktop/Agent、MCP Inspector 等 AI 工具生态
- 详见 CLI_GUIDE.md/ API.md 示例