# @wanghuagui/code-model-context

在本地工程目录上运行，把源码解析成结构化的 **JSON_ROOT** 快照，并支持调用链差异、影响分析、字段级差异与质量基线等能力。**面向在 Node.js 里集成的开发者**（库 / 服务 / 工具链）。

---

## 安装

使用与你项目一致的包管理器即可（包已发布在 npm，**作用域名以 registry 为准**）：

```bash
pnpm add @wanghuagui/code-model-context
```

```bash
npm install @wanghuagui/code-model-context
```

```bash
yarn add @wanghuagui/code-model-context
```

- **要求**：Node.js（与当前 LTS 兼容即可）。
- **类型**：安装后可直接使用 TypeScript 类型提示（`types` 指向构建产物中的声明文件）。

---

## 作为库使用（推荐路径）

### 1. 引入并创建实例

主入口**只导出** `CodeModelContext` 类及构造/实例相关的 **TypeScript 类型**（见下方「类型」）。没有其它运行时「工具函数」从根路径导出。

```typescript
import { CodeModelContext } from "@wanghuagui/code-model-context";

const ctx = new CodeModelContext({
    target: "javascript#Vue3",
    projectRoot: "/absolute/path/to/your/project",
});

await ctx.parseProject();
// 首次为全量解析；同一实例上再次 await ctx.parseProject() 会走增量（Vue2/Vue3/React 等见实现说明）
```

### 2. 构造参数（常用）

| 字段 | 说明 |
|------|------|
| **`target`** | 必填。形如 `编程语言#解析范式`，例如 `javascript#Vue3`、`javascript#react`。`#` 后部分在可与内置解析器一一对应时可按约定省略（详见类型 `CodeModelContextInitOptions`）。 |
| **`projectRoot`** | 必填。项目根目录，**建议绝对路径**。 |
| **`noJson`** | 可选。解析选项，控制是否省略部分 JSON 细节。 |
| **`configFileName`** | 可选。项目根下配置文件名（如 `code.config.json`），与解析选项合并。 |
| **`impactWeights`** | 可选。影响分析默认权重；也可用 `analyzeImpactWithWeights` 单次覆盖。 |

### 3. 只读属性（getter）

解析成功后可通过 getter 读取当前状态（**不要假设构造后立刻有快照**，需先 `parseProject()` 或 `executeCoreAction` 的解析类动作）：

| 属性 | 说明 |
|------|------|
| `baselineSnapshot` / `currentSnapshot` | 基线与当前 **JSON_ROOT**；双快照能力依赖二者齐备。 |
| `targetProgrammingKey` / `targetLanguage` | 归一化后的语言键与解析器 id（如 `vue3`）。 |
| `projectRoot` | 解析时使用的项目根绝对路径。 |
| `defaultImpactWeights` | 构造时传入的影响权重快照。 |

### 4. 实例方法一览（对外 API）

**解析**

| 方法 | 说明 |
|------|------|
| **`parseProject()`** | **推荐的解析入口**：首次全量；之后在同一实例上再次调用则自动增量（具体策略依 `targetLanguage` 而定）。返回 `Promise<void>`，结果在 getter 中。 |
| **`getJsonByFilePath(filePath)`** | 只解析**单个文件**，返回 `FileNode`；**不**写入实例的 `baselineSnapshot` / `currentSnapshot`。`filePath` 须为绝对路径且在 `projectRoot` 下。 |

**双快照（需已先后形成 baseline + current，通常通过连续解析得到）**

| 方法 | 说明 |
|------|------|
| `getIncrementalDiffResult()` | 从双快照生成可序列化的增量片段。 |
| `updateOldSnapshot(patch)` | 将片段合并进基线快照的**副本**，不直接改实例内字段。 |
| `funcCallChainDiff()` | 调用链差异（按文件聚合）。 |
| `analyzeImpact()` | 影响分析（默认权重）。 |
| `analyzeImpactWithWeights(weights?)` | 带自定义/合并权重的影响分析（**未**映射到 `executeCoreAction` 的 `impact`）。 |
| `jsonFieldsChanged()` | 范式字段级差异。 |

**查询与质量**

| 方法 | 说明 |
|------|------|
| `queryFuncCallChainByFuncName(records, functionName)` | 在 `funcCallChainDiff` 的结果中按函数名筛选。 |
| `queryFuncChainsBySnapshot(targetFuncName)` | 基于**当前快照**枚举经过某函数名的调用链；要求已有 `currentSnapshot`。 |
| `evaluateQualityBaseline(benchmarkCases, previousReport?, config?)` | 质量基线评估；**不依赖**实例双快照。 |

**统一动作入口（与网关 / MCP 负载对齐）**

| 方法 | 说明 |
|------|------|
| `executeCoreAction(payload)` | 按 `payload.action` 分发：`parse` / `parseIncremental` 会注入本实例的 `projectRoot` 与解析选项并更新快照；`diff` / `impact` / `contextDiff` / `query` / `qualityAssess` / `queryFuncChainsBySnapshot` 委托到上表对应能力。适合希望**请求体与 MCP 一致**的集成方。 |

**元数据**

| 方法 | 说明 |
|------|------|
| `getJsonFieldsInfo()` | 返回当前 `targetLanguage` 下 **JSON_ROOT** 字段含义说明树。 |

**职责说明**：上述方法返回的是**内存中的 JSON 数据**；需要落盘时请在你的应用里自行 `fs.writeFile` 等。

---

## 命令行（CLI）

安装依赖后，本包提供全局/本地可执行命令 **`code-model-context`**：

```bash
pnpm exec code-model-context -- --help
pnpm exec code-model-context -- parse --help
```

解析类子命令需通过 **`--target-language` / `-T`** 指定解析器；**`--config`** 不能替代 `-T`。常见退出码：`0` 成功，`1` 运行时错误，`2` 参数错误，`3` IO 错误。

---

## MCP（Model Context Protocol）

安装后可用 **`code-model-context-mcp`**（stdio）。每次会话需传入与 `new CodeModelContext` 一致的 **`target`、`projectRoot`** 等元信息（与 MCP 工具参数一致，细节以工具描述为准）。

```bash
pnpm exec code-model-context-mcp
```

---

## TypeScript 类型（从主入口 `export type`）

包括但不限于：`CodeModelContextInitOptions`、`JSON_ROOT`、`FileNode`、`IncrementalDiffResult`、`FileCallChainDiffRecord`、`CoreActionPayload`、`CoreActionResult`、`ImpactWeights`、`JsonFieldsInfo`、`QualityBenchmarkCase`、`QualityAssessmentReport` 等。以安装包内 **`build/index.d.ts`** 与源码中 `src/index.ts` 的导出为准。

---

## 许可证

**Apache-2.0**（见包内 `LICENSE` 与 `package.json` 的 `license` 字段）。
