gx-code-agent 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,277 @@
-# Temporary Holding Version
+# gx-code-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+GX 高代码平台的伴生 CLI。M0 阶段提供 `gx init`：一次性完成 MCP Server 注册与平台规范注入。
+
+## 环境要求
+
+- Node.js 18+
+
+## 安装
+
+### 从公共 npm 安装（推荐）
+
+```bash
+# 主 CLI
+npm i -g gx-code-agent@0.1.0
+npx --yes gx-code-agent@0.1.0 --help
+
+# 独立本地 MCP 启动器
+npx --yes gx-mcp-local
+```
+
+包名、版本与发布流程见 `RELEASE.md`。公共 npm 发布若遇到 2FA/E403，使用 `npm run publish:public -- --otp=<验证码>` 或 granular token（需 Bypass 2FA）。
+
+### 本地开发
+
+```bash
+cd gx-code-agent
+npm ci
+npm link
+```
+
+或直接：
+
+```bash
+node bin/gx.js --help
+```
+
+## 快速开始
+
+```bash
+export GX_API_TOKEN=gxmcp_xxx
+gx init --client opencode \
+  --url http://127.0.0.1:4013/mcp \
+  --plan <planId> --template <templateId> \
+  --with-local --yes
+```
+
+初始化会做以下事情：
+
+1. 写入客户端 MCP 配置（OpenCode / Claude / Cline）；
+2. 写入 `timeout`，避免 `generate_code` / `search_code` 过大会话超时；
+3. 把平台规范 + 项目绑定（planId/templateId/生成层目录）注入 `AGENTS.md` / `CLAUDE.md`，带标记块，重复执行不会重复追加；
+4. 可选地把 `planId/templateId` 写入 `.gx/config.json`；
+5. 可选注册本地 stdio MCP `gx-local`（`--with-local`）；
+6. 写入 `.gx/.gitignore`，忽略 `backup/`、`generated/` 等本地文件；
+7. 写入前把已存在的配置文件备份到 `.gx/backup/<timestamp>/`，并保留最近 5 次；
+8. 初始化后调用 `ping`、`tools/list`、`get_current_user`，输出连接状态、工具数量和 Token scopes（可用 `--skip-verify` 跳过）。
+
+默认写入的是**环境变量引用**（如 `Bearer {env:GX_API_TOKEN}`），不会把明文 Token 落盘。只有显式加 `--embed-token` 才会写入明文，此时请勿提交对应配置文件。
+
+配置格式：
+
+- 默认 `--opencode-format legacy`：写 `mcp.gx-code`，兼容 OpenCode 1.x / 2.x；
+- `--opencode-format v2`：写 `mcp.servers.gx-code`，使用 2.x 原生格式与对象 timeout；
+- `--timeout <ms>`：远端 MCP 超时，默认 `180000`。
+
+## 支持的客户端
+
+| 客户端 | 写入文件 | 说明 |
+|---|---|---|
+| `opencode` | `opencode.json` | `mcp.gx-code`，`type: remote`，`oauth: false` |
+| `claude` | `.mcp.json` | `mcpServers.gx-code`，`type: http` |
+| `cline` | `.gx/cline-mcp-settings.json` | 生成片段，需合并到 Cline 的 MCP 设置 |
+
+## 命令
+
+```bash
+gx init [--client opencode|claude|cline] [--url <url>] [--token <token>] \
+        [--token-env <name>] [--embed-token] [--plan <planId>] [--template <templateId>] \
+        [--generated-dir <dir>] [--dir <path>] [--with-local] \
+        [--opencode-format legacy|v2] [--timeout <ms>] \
+        [--check] [--skip-verify] [--yes] [--dry-run]
+gx pull  --plan <planId> --template <templateId> [--model-ids a,b] [--url <url>] [--token <token>] [--dry-run]
+gx apply [--dir <path>] [--dry-run] [--force]
+gx verify [--dir <path>] [--manifest <path>] [--strict]
+gx scan   [--dir <path>] [--compile] [--report|--no-report] [--source-dir a,b]
+gx audit  [--dir <path>] [--compile] [--report|--no-report] [--strict]
+gx chunks [--dir <path>] [--source-dir a,b] [--report|--no-report] [--no-content] [--strict]
+gx version
+gx help
+```
+
+- Token 优先取 `--token`，其次取环境变量（默认 `GX_API_TOKEN`，可用 `--token-env` 改名）。
+- 默认写入环境变量引用；`--embed-token` 才会写入明文。
+- `--dry-run` 只打印将写入的内容与 diff，不落盘。
+- `--check` 只检查配置与连接，不写入；配置需要更新时退出码 1。检查时请带上与初始化相同的 `--client/--with-local/--opencode-format` 选项，否则会报告差异。
+- `--with-local` 同时注册 `gx-local` 本地 stdio MCP。
+- `--skip-verify` 跳过初始化后的连接检查（CI / 离线环境使用）。
+- 非交互模式写入必须带 `--yes`，否则退出码 2。
+- 不支持的客户端会直接报错，不会猜测格式。
+
+## M3：拉取 / 应用 / 校验
+
+```bash
+# 1. 从平台拉取生成结果（Token 只放环境变量，不落盘）
+export GX_API_TOKEN=gxmcp_xxx
+gx pull --plan plan-1 --template tpl-1
+
+# 2. 预览 apply
+gx apply --dry-run
+
+# 3. 应用；保留块内的用户代码不会被覆盖
+gx apply
+
+# 4. 已确认生成层被手改，强制覆盖
+gx apply --force
+
+# 4. CI 使用严格模式：manifest 缺失或漂移都会失败
+gx verify --strict
+```
+
+`gx pull` 会写入：
+
+- `.gx/generated/<path>`：平台返回的生成文件
+- `.gx/manifest.json`：文件 sha256 与 metadataVersion
+- `.gx/pull.json`：本次拉取信息
+
+`gx verify` 只校验生成骨架；保留块内部内容归用户所有，不参与漂移判断。
+
+`gx apply` 会先做预检：如果目标文件的生成骨架在最近一次 apply 后被修改，默认拒绝覆盖并提示使用 `gx apply --force`。首次 apply 没有历史指纹时会给出警告，但仍允许执行。
+
+## M4：扩展点与对账
+
+扩展层公开方法使用平台注解：
+
+```java
+@ExtMethod(entity = "Order", intent = "大额订单二级审批",
+           triggers = {"BEFORE_SAVE"}, fields = {"amount"})
+public void checkApproval(Order order) { ... }
+```
+
+```bash
+# 解析 @ExtMethod；配置了 planId + Token 时自动上报 record_ext_points
+gx scan
+
+# AST 扫描 + 编译扩展层（JDK 9+；推荐 JDK 17，可用 JAVA_HOME/JAVAC 指定）
+gx scan --compile --classpath pig-upms/gx-util-api/target/classes
+
+# 只扫描不上报
+gx scan --no-report
+
+# 上报扩展点、校验 manifest、调用 audit_alignment，输出待办清单
+gx audit
+gx audit --strict   # 有待办时退出码 1
+
+# 精简 CI 示例：失败即阻断
+gx audit --no-report --strict
+```
+
+`gx scan` 优先使用 JDK Compiler Tree API（AST）识别公开方法与 `@ExtMethod`；JDK 不可用时自动回退正则，并在 `coverage.facets.ast_scan` 中标记。`--compile` 通过 `javac` 校验类型引用，未解析的类型会写入 `compilation.errors` 并让 `--strict` 失败。
+
+`gx audit` 输出三类待办：
+
+1. `MISSING_EXT_METHOD`：扩展层公开方法缺少 `@ExtMethod`；
+2. `STALE_EXT_REFERENCE`：已上报扩展点引用了已删除/不存在的实体或字段（`@ExtMethod.fields`）；
+3. `FILE_DRIFTED` / `FILE_MISSING` / `MANIFEST_*`：manifest 与工作区不一致。
+
+扫描结果写入 `.gx/ext-points.json`，对账结果写入 `.gx/audit.json`；共享契约见 `contracts/alignment.schema.json`。
+
+## M5：代码切片与检索
+
+```bash
+# 本地生成 Java/Vue 方法级/类级切片，写入 .gx/chunks.json
+gx chunks --no-report
+
+# 生成并上报 record_code_chunks（配置 planId + GX_API_TOKEN）
+gx chunks
+
+# 数据敏感环境：只上报元数据，不上传切片内容
+gx chunks --no-content
+```
+
+Java 切片优先使用 JDK Compiler Tree API（AST）生成类/方法边界、行号与注解；JDK 不可用时自动回退正则。`coverage.facets.chunking.engine` 会标记 `ast` 或 `regex`。
+
+平台侧使用 `search_code` 做“关键词 + AST 标签 + pgvector 语义”混合检索（`layer`、`granularity`、`annotations`、`frameworkTags`）。CLI 上报时 `embedding` 可为空，平台会按切片内容自动向量化并写入 pgvector；未配置 EmbeddingModel 时自动降级为关键词检索。
+
+## 检索评测
+
+```bash
+gx eval-search --plan <planId> \
+  --dataset eval/code-search-eval.json \
+  --limit 5 --out .gx/eval-search.json
+```
+
+输出 HitRate、MRR、平均延迟与每条 query 的命中排名。评测集位于 `eval/code-search-eval.json`，可按项目复制扩展。
+
+## 本地 stdio MCP
+
+`gx-mcp-local` 提供不依赖平台的本地 MCP 工具：
+
+- `local_verify_manifest`：校验工作区与 `.gx/manifest.json`；
+- `local_scan_ext_points`：扫描 `@ExtMethod`、缺注解方法与编译结果。
+
+OpenCode / Claude Code 本地配置示例：
+
+```json
+{
+  "mcp": {
+    "gx-local": {
+      "type": "local",
+      "command": ["npx", "gx-mcp-local"],
+      "enabled": true
+    }
+  }
+}
+```
+
+也可直接用 `node bin/gx-stdio-mcp.js` 启动（JSON-RPC over stdio）。
+
+> `npx gx-mcp-local` 使用独立包 `gx-mcp-local`，它会调用已安装的 `gx-code-agent`；
+> 未发布或离线时请使用 `node /absolute/path/gx-code-agent/bin/gx-stdio-mcp.js`。
+
+## CI
+
+- GitLab：`ci/gitlab-ci-gx-verify.yml`
+- GitHub Actions：`ci/github-actions-gx-verify.yml`
+
+CI 默认执行：
+
+1. `gx verify --strict`：阻断生成层漂移；
+2. `gx scan --no-report`：输出 `gx-scan.json` artifact；
+3. 配置 `GX_API_TOKEN`（可选 `GX_PLAN_ID`）后执行 `gx audit --no-report --strict`，阻断缺注解/失效引用/manifest 漂移。
+
+CI 变量：
+
+| 变量 | 说明 |
+|---|---|
+| `GX_AGENT_VERSION` | 固定 CLI 版本，默认 `0.1.0` |
+| `NPM_REGISTRY` | npm registry；默认 `https://registry.npmjs.org/` |
+| `GX_API_TOKEN` / `GX_PLAN_ID` | MCP 鉴权与方案范围 |
+
+发布流水线：
+
+- GitHub Actions：`.github/workflows/publish.yml`
+- GitLab：`ci/gitlab-ci-publish.yml`
+- 发布步骤、公共 npm 登录与双包发布见 `RELEASE.md`。
+
+## 验证
+
+```bash
+node --test
+```
+
+当前：CLI `39/39`；平台侧 Java MCP `80/80`。
+
+## 当前进度与后续
+
+已完成：
+
+- M3：`gx pull` / `gx apply` / `gx verify`
+- M4：`@ExtMethod` / `gx scan` / `gx audit` / `record_ext_points` / `audit_alignment`
+- M5：`gx chunks` / `record_code_chunks` / `search_code`（关键词 + AST 标签 + pgvector 语义）
+- P5：apply 漂移预检、AST 扫描、编译级引用验证
+- P6：真实方案 `wk1` 完成 pull/apply/verify/scan/audit/chunks/search 全链路验收（2146 切片、语义检索通过）
+- P7：审计 compilation facet 合并、向量重建、审计保留、pgVector 健康检查
+- P8：Java AST chunker、混合检索评测集、本地 stdio MCP（`gx-mcp-local`）
+- CLI-02：`gx init` 支持 `--with-local`、timeout、项目绑定、连接自检、`.gx/.gitignore`、`--check`
+
+待办：
+
+- `gx context` / `gx push` / `gx adopt`
+- Agent 外壳（本地 stdio MCP 已提供基础版）
+- 公共 npm 发布（发布准备已完成，待 2FA OTP 或 Bypass 2FA granular token）
+
+## 与主平台的关系
+
+MCP Server 运行在 `gx-cloud-frp/pig-code-biz`，本仓库只负责开发者侧的注册、校验与代码文件操作。平台保证结构元数据唯一事实源；本 CLI 负责开发者仓库侧的文件级校验。

package/bin/gx-stdio-mcp.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+
+import { scanWorkflow } from "../src/application/scanWorkflow.js";
+import { verifyWorkflow } from "../src/application/verifyWorkflow.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+
+const TOOLS = [
+  {
+    name: "local_verify_manifest",
+    description: "本地校验仓库文件与 .gx/manifest.json 是否一致；不访问平台。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dir: { type: "string", description: "仓库目录，默认当前工作目录" },
+        manifestPath: { type: "string", description: "manifest 路径，默认 .gx/manifest.json" }
+      }
+    }
+  },
+  {
+    name: "local_scan_ext_points",
+    description: "本地扫描 @ExtMethod、缺注解方法与编译结果；不访问平台。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        dir: { type: "string", description: "仓库目录，默认当前工作目录" },
+        sourceDirs: {
+          oneOf: [
+            { type: "string", description: "逗号分隔的源码目录" },
+            { type: "array", items: { type: "string" } }
+          ]
+        },
+        compile: { type: "boolean", description: "是否执行 javac 编译" },
+        classpath: { type: "string", description: "javac classpath" }
+      }
+    }
+  }
+];
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function result(id, value) {
+  send({ jsonrpc: "2.0", id, result: value });
+}
+
+function error(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function toolResult(id, value, isError = false) {
+  result(id, {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    isError
+  });
+}
+
+function parseSourceDirs(value) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim());
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return undefined;
+}
+
+function callTool(name, args = {}) {
+  const dir = path.resolve(String(args.dir || process.cwd()));
+  if (name === "local_verify_manifest") {
+    return verifyWorkflow({
+      dir,
+      manifestPath: typeof args.manifestPath === "string" ? args.manifestPath : ".gx/manifest.json"
+    });
+  }
+  if (name === "local_scan_ext_points") {
+    return scanWorkflow({
+      dir,
+      sourceDirs: parseSourceDirs(args.sourceDirs),
+      compile: Boolean(args.compile),
+      classpath: typeof args.classpath === "string" ? args.classpath : undefined
+    });
+  }
+  throw new Error(`未知工具：${name}`);
+}
+
+function handle(message) {
+  if (!message || typeof message !== "object" || message.jsonrpc !== "2.0") {
+    error(null, -32600, "Invalid Request");
+    return;
+  }
+  const { id, method, params } = message;
+  if (method === "initialize") {
+    result(id, {
+      protocolVersion: "2025-06-18",
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: "gx-code-agent-local", version: PKG.version }
+    });
+    return;
+  }
+  if (method === "notifications/initialized" || method === "notifications/cancelled") {
+    return;
+  }
+  if (method === "ping") {
+    result(id, {});
+    return;
+  }
+  if (method === "tools/list") {
+    result(id, { tools: TOOLS });
+    return;
+  }
+  if (method === "tools/call") {
+    const name = params?.name;
+    const args = params?.arguments ?? {};
+    try {
+      toolResult(id, callTool(name, args));
+    }
+    catch (e) {
+      toolResult(id, { error: e instanceof Error ? e.message : String(e) }, true);
+    }
+    return;
+  }
+  error(id, -32601, `Method not found: ${method}`);
+}
+
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return;
+  }
+  try {
+    handle(JSON.parse(trimmed));
+  }
+  catch (e) {
+    error(null, -32700, `Parse error: ${e instanceof Error ? e.message : String(e)}`);
+  }
+});

package/bin/gx.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parseArgs, usage } from "../src/adapters/cli/args.js";
+import { runApply } from "../src/application/applyWorkflow.js";
+import { runAudit } from "../src/application/auditCommand.js";
+import { runChunks } from "../src/application/chunksCommand.js";
+import { runEvalSearch } from "../src/application/evalSearchCommand.js";
+import { runInit } from "../src/application/initWorkflow.js";
+import { runPull } from "../src/application/pullWorkflow.js";
+import { runScan } from "../src/application/scanCommand.js";
+import { verifyWorkflow } from "../src/application/verifyWorkflow.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0] || "help";
+
+  if (command === "help" || args.help) {
+    usage();
+    return;
+  }
+  if (command === "version") {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+    console.log(pkg.version);
+    return;
+  }
+  if (command === "init") {
+    await runInit(args);
+    return;
+  }
+  if (command === "pull") {
+    await runPull(args);
+    return;
+  }
+  if (command === "apply") {
+    await runApply(args);
+    return;
+  }
+  if (command === "verify") {
+    const dir = path.resolve(String(args.dir || process.cwd()));
+    const result = verifyWorkflow({
+      dir,
+      manifestPath: typeof args.manifest === "string" ? args.manifest : ".gx/manifest.json"
+    });
+    printJson(result);
+    if (!result.ok || (args.strict && result.coverage.status !== "complete")) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (command === "scan") {
+    const result = await runScan(args);
+    if (args.strict && (result.unannotatedMethods?.length > 0
+      || result.report?.status === "failed"
+      || (result.report?.rejected?.length ?? 0) > 0
+      || (result.compilation?.available === true && result.compilation.success === false))) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (command === "chunks") {
+    const result = await runChunks(args);
+    if (args.strict && (result.report?.status === "failed" || (result.report?.rejected?.length ?? 0) > 0)) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (command === "eval-search") {
+    await runEvalSearch(args);
+    return;
+  }
+  if (command === "audit") {
+    const result = await runAudit(args);
+    if (!result.ok || (args.strict && result.coverage?.status === "unknown")) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  usage();
+  process.exitCode = 1;
+}
+
+try {
+  await main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[gx] ${message}`);
+  process.exitCode = error && typeof error === "object" && "exitCode" in error ? error.exitCode : 1;
+}

package/contracts/README.md

@@ -0,0 +1,40 @@
+# GX 共享契约（contractVersion: 1）
+
+本目录是 gx-code-agent（Node/CLI）与 gx-cloud-frp（Java MCP）之间的传输契约源。
+
+## 文件
+
+| 文件 | 用途 |
+|---|---|
+| `evidence.schema.json` | Evidence 记录 |
+| `unknown.schema.json` | Residual Unknown（对账待办） |
+| `manifest.schema.json` | 生成清单与 checksum |
+| `ext-method.schema.json` | 扩展方法声明（`fields` 为可选的字段级引用） |
+| `alignment.schema.json` | `audit_alignment` 对账结果 |
+| `code-chunk.schema.json` | M5 代码切片（embedding 可空，平台按需自动向量化） |
+| `examples/` | 双端共用的测试 fixture |
+
+## 通用规则
+
+1. JSON Schema Draft 2020-12。
+2. 未知字段一律拒绝（`additionalProperties: false`）。
+3. 字符串不做 Unicode 归一化；问题文本在生成 `unk_` 前做空白归一化。
+4. 对象 key 按 Unicode code point 排序；`undefined` 字段丢弃。
+5. 摘要统一使用小写 SHA-256 hex。
+
+## ID 规则
+
+- Evidence：`ev_` + `sha256(canonicalJson(evidenceWithoutEvidenceId))`
+- Unknown：`unk_` + `sha256(canonicalJson({domain, question, scope}))`
+  - `question` 先执行 `replace(/\s+/gu, " ").trim()`
+- Manifest：`manifestHash = sha256(canonicalJson(manifestWithoutManifestHash))`
+
+## 版本策略
+
+- 新增字段必须可选，保持 v1 兼容。
+- 删除字段、修改字段语义、修改 ID 计算方式必须升 major（v2），并在 Node/Java 两端同时更新。
+- 发布前运行 `node --test test/contracts.test.js` 与 Java `ContractSerializationTest`。
+
+## MIT 说明
+
+本目录的字段设计参考了 REA（https://github.com/morluto/rea，MIT）的 Evidence / Unknown 设计思想，但 Schema 与示例为 GX 按自身领域重写，不包含 REA 源代码副本。

package/contracts/alignment.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gx.local/contracts/alignment.schema.json",
+  "title": "GX Audit Alignment Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["planId", "ok", "extPointCount", "drift", "missingAnnotations", "staleReferences", "todos", "coverage"],
+  "properties": {
+    "planId": { "type": "string", "minLength": 1 },
+    "ok": { "type": "boolean" },
+    "extPointCount": { "type": "integer", "minimum": 0 },
+    "drift": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["planId", "manifestVersion", "currentVersion", "drifted", "missing", "extra", "reason"],
+      "properties": {
+        "planId": { "type": "string" },
+        "manifestVersion": { "type": ["integer", "null"] },
+        "currentVersion": { "type": "integer", "minimum": 1 },
+        "drifted": { "type": "array", "items": { "type": "string" } },
+        "missing": { "type": "array", "items": { "type": "string" } },
+        "extra": { "type": "array", "items": { "type": "string" } },
+        "reason": { "type": ["string", "null"] }
+      }
+    },
+    "missingAnnotations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["className", "methodName", "file", "line", "reason"],
+        "properties": {
+          "className": { "type": "string" },
+          "methodName": { "type": "string" },
+          "file": { "type": ["string", "null"] },
+          "line": { "type": ["integer", "null"] },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "staleReferences": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["className", "methodName", "entity", "field", "reason"],
+        "properties": {
+          "className": { "type": "string" },
+          "methodName": { "type": "string" },
+          "entity": { "type": ["string", "null"] },
+          "field": { "type": ["string", "null"] },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "todos": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["todoId", "type", "severity", "summary", "action", "className", "methodName", "entity", "files"],
+        "properties": {
+          "todoId": { "type": "string", "pattern": "^align_[a-f0-9]{16}$" },
+          "type": {
+            "type": "string",
+            "enum": ["MANIFEST_MISSING", "MANIFEST_PLAN_MISMATCH", "MANIFEST_VERSION_MISSING", "MANIFEST_VERSION_MISMATCH", "MANIFEST_ENTRY_INVALID", "MANIFEST_ENTRY_DUPLICATE", "FILE_DRIFTED", "FILE_MISSING", "EXTRA_FILE", "MISSING_EXT_METHOD", "STALE_EXT_REFERENCE"]
+          },
+          "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+          "summary": { "type": "string" },
+          "action": { "type": "string" },
+          "className": { "type": ["string", "null"] },
+          "methodName": { "type": ["string", "null"] },
+          "entity": { "type": ["string", "null"] },
+          "files": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "facets"],
+      "properties": {
+        "status": { "type": "string", "enum": ["complete", "partial", "unknown"] },
+        "facets": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["available"],
+            "properties": {
+              "available": { "type": "boolean" },
+              "reason": { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    }
+  }
+}