# CodeModelContext

面向 AI 编程与静态分析的**项目源码 → 结构化快照**引擎：在磁盘上的工程目录上运行，产出可计算的 `JSON_ROOT` 范式数据，并支持快照之间的**调用链差异**、**影响评估**、**上下文字段差异**与**质量基线**等能力。

- **包名**：`CodeModelContext`（`package.json`）；作为依赖被宿主引用时， monorepo 内也可能以 `codeModelContext` 等别名链接（见上层仓库说明）。
- **运行时**：Node.js；**主入口**仅导出 **`CodeModelContext`** 类及构造/实例 API 相关 **TypeScript 类型**（见 `src/index.ts`）。

## 特性概览

| 能力 | 说明 |
|------|------|
| **全量 / 增量解析** | **`parseProject()`**（**唯一**对外实例入口：首次全量、之后自动增量）；网关/CLI 另用 **`executeCoreAction`**（`parse` / `parseIncremental`）或 **`actions/api`**（`vue2` / `vue3` / `react` 走解析阶段增量，其余范式可能退化为全量） |
| **单文件解析** | **`getJsonByFilePath(filePath)`**：仅解析单个文件，返回 **`FileNode`**，不修改实例快照 |
| **增量片段** | `getIncrementalDiffResult` / `updateOldSnapshot`：两份全量快照之间摘片段与回灌合并 |
| **差异与分析** | `funcCallChainDiff`、`analyzeImpact`、`analyzeImpactWithWeights`、`jsonFieldsChanged` |
| **查询与质量** | `queryFuncCallChainByFuncName`、`evaluateQualityBaseline` |
| **统一入口** | `executeCoreAction`：与网关 / MCP 的动作负载对齐；`parse` / `parseIncremental` 由实例注入 `projectRoot` 与解析选项 |
| **解析器** | 内置注册 `Vue2` / `Vue3` / `React` 及 `nodejs` / `python` / `go` / `java` 等（见 `actions/parsers/`） |

**职责边界**：实例方法**只返回内存中的 JSON 数据**，不代替宿主写磁盘；需要落盘时请自行 `fs.writeFile`，或配合 CLI / 网关使用。

## 安装

在依赖本包的工程目录中（包管理器择一）：

```bash
pnpm add CodeModelContext
# 或
npm install CodeModelContext
```

若从 npm 安装，**以注册表上的实际包名为准**（可能与 `package.json` 的 `name` 字段一致）。从**本仓库源码**联调时，通常在上层目录通过 `file:../CodeModelContext` / `insideBuild` 产物链接（见仓库根目录 `README.md` 中 **service** / 网关相关章节）。

## 快速开始

```typescript
import { CodeModelContext } from "CodeModelContext";
// 若上层以 codeModelContext 链接： import { CodeModelContext } from "codeModelContext";

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

    await ctx.parseProject();
    const baseline = ctx.currentSnapshot;
    await ctx.parseProject();
    const diffRecords = await ctx.funcCallChainDiff();
    void baseline;
    void diffRecords;
}

main().catch(console.error);
```

**构造参数要点**（详见类型 `CodeModelContextInitOptions`）：

- **`target`**：单一字符串，`编程语言#解析范式`（如 `javascript#vue3`、`javascript#react`）；`#` 后可在 `java` / `python` / `go` / `nodejs` 与解析器一一对应时省略。
- **`projectRoot`**：项目根路径（必填）。
- 可选：**`noJson`**、**`configFileName`**、**`impactWeights`**（影响分析默认权重）。

## API 一览

| 方法 | 说明 |
|------|------|
| `parseProject()` | **唯一**对外解析入口；首次全量、之后自动增量，`Promise<void>`，快照见 getter |
| `getJsonByFilePath(filePath)` | 仅解析 `projectRoot` 下该文件的绝对路径，返回 **`FileNode`**（不写入实例快照） |
| `getIncrementalDiffResult()` | 实例双快照 → 增量片段 |
| `updateOldSnapshot(patch)` | 将片段合并进基线快照（见类说明） |
| `funcCallChainDiff()` | 调用链差异记录 |
| `analyzeImpact` / `analyzeImpactWithWeights` | 影响分析报告 |
| `jsonFieldsChanged` | 范式字段级差异 |
| `queryFuncCallChainByFuncName` | 在 diff 记录中按函数名筛选 |
| `evaluateQualityBaseline` | 质量基线评估 |
| `executeCoreAction` | 统一动作分发（与 MCP/网关对齐） |
| `getJsonFieldsInfo` | 无参；返回当前 **`targetLanguage`** 对应的 **`JSON_ROOT`** 字段含义树（与仓库根目录 **`rule-vue2.js` / `rule-vue3.js` / `rule-react.js`** 对齐；`nodejs`/`python`/`go`/`java` 为通用说明） |

**只读 getter**：`targetProgrammingKey`、`targetLanguage`、`projectRoot`、`defaultImpactWeights`。

**从包内深度引用**（不经主入口导出）：快照校验/序列化见 `actions/snapshot/snapshotIO`（如 `serializeSnapshot`、`parseSnapshotText`、`loadSnapshot`、`saveSnapshot`）；CLI 与宿主可自行 `import` 子路径（需注意打包与 `exports` 字段）。

## 命令行（CLI）

构建后可用全局/本地命令 **`code-model-context`**（`package.json` 的 `bin` 指向 `build/cli.js`）：

```bash
pnpm run build
pnpm run cli -- --help
pnpm run cli -- parse --help
```

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

## MCP

构建产物 **`build/mcp.js`** 对应可执行名 **`code-model-context-mcp`**（stdio MCP）。每次调用需传入与 `new CodeModelContext` 一致的 **`target` / `projectRoot`** 等元信息（详见 MCP 工具说明）。

## 开发与构建

```bash
pnpm install
pnpm run build    # webpack 主包 + cli + mcp + d.ts
pnpm run dev      # watch + 可选 dev-smoke，见 scripts/run-dev.cjs
pnpm test         # node --test
```

- **开发态**主 bundle：`dist/index.js`（见 `webpack.dev.js`）。
- **发布态**入口：`build/index.js`、`build/cli.js`、`build/mcp.js`（需先 `pnpm run build`）。

## 配置与环境变量（摘要）

- **解析器允许列表**：包根 **`.env`** → **`CODE_CONTEXT_BUILTIN_PARSER_IDS`**（默认包含 `vue3,vue2,react,nodejs,python,go,java`）。
- **项目侧**：项目根 **`code.config.json`**（如 `noJson`、性能选项等），与构造参数合并规则见 `ParseProjectOptions` 与仓库根 **README**。

完整说明、网关、目录哈希与范式字段语义见**仓库根目录** [**`../README.md`**](../README.md)。

## 类型导出

主入口 `export type` 包括：`JSON_ROOT`、`JsonFieldsInfo`、`JsonFieldsInfoNode`、`JsonFieldsInfoObject`、`CodeModelContextInitOptions`、`ImpactWeights`、`IncrementalDiffResult`、`FileCallChainDiffRecord`、`CoreActionPayload`、`CoreActionResult`、`QualityBenchmarkCase`、`GetJsonFieldsInfo` 等（以 `src/index.ts` 与 `actions/types` 为准）。

## 许可证

**Apache License 2.0**（见 `package.json` 的 `license` 字段）。
