spectra-cli 4.1.1 → 4.2.0

package/dist/knowledge-graph/unified-graph.d.ts

@@ -0,0 +1,310 @@
+/**
+ * UnifiedGraph schema — Feature 151 关键路径基建。
+ *
+ * 4 语言 Knowledge Graph 共享抽象层的核心 schema：
+ * - UnifiedNode：统一节点（module / symbol / spec / component / etc.）
+ * - UnifiedEdge：统一边（calls / depends-on / contains / cross-module / documents / ...）
+ * - UnifiedGraph：顶层装配（nodes + edges + metadata）
+ * - CallSite：函数调用点的原始记录（mapper 阶段产出，call-resolver 阶段消费）
+ *
+ * 关键设计决策（CL-01 / CL-07 / Codex C-1 / Codex C-3）：
+ * - CallSite 不携带 confidence 字段，confidence 在 call-resolver 阶段统一计算
+ * - UnifiedEdge.directional?: boolean — calls / depends-on / cross-module / contains 必须 true，
+ *   覆盖 GraphJSON.directed 全局开关，让 GraphQueryEngine 邻接表按 edge-level 决策
+ * - UnifiedGraph 同时包含 calls 与 depends-on 边；Feature 156 W1.4 起所有 17 consumer
+ *   统一通过 buildUnifiedGraph + deriveModuleGraph（src/knowledge-graph/module-derivation.ts）
+ *   消费 ModuleGraph 视图，不再走 dependency-cruiser 路径
+ */
+import { z } from 'zod';
+export { CalleeKindSchema, CallSiteSchema, type CalleeKind, type CallSite, } from '../models/call-site.js';
+/**
+ * 内部 UnifiedGraph 使用的 confidence 三档枚举。
+ *
+ * 注意：GraphJSON 输出层映射到现有 EXTRACTED / INFERRED / AMBIGUOUS enum
+ * （由 confidence-mapper.ts mapTierToConfidence 函数完成 1:1 转换）。
+ *
+ * 双轨设计动机（CL-08）：
+ * - high/medium/low 偏向"解析确定度"语义（对 call-resolver 直观）
+ * - EXTRACTED/INFERRED/AMBIGUOUS 偏向"证据质量"（对 graph 消费者直观）
+ * - 强制内部统一会污染 resolver 表达
+ */
+export declare const ConfidenceTierSchema: z.ZodEnum<["high", "medium", "low"]>;
+export type ConfidenceTier = z.infer<typeof ConfidenceTierSchema>;
+/**
+ * 节点种类枚举（**Codex P0 C-3 修订**）。
+ *
+ * 与 `src/panoramic/graph/graph-types.ts` 的 `GraphNode.kind` 范围严格对齐，
+ * 便于 graph-builder 在 GraphJSON 序列化时不出现 schema drift。
+ * 额外新增 `symbol`（UnifiedGraph 内部需要 function/class 级粒度，panoramic GraphNode 不区分）。
+ */
+export declare const UnifiedNodeKindSchema: z.ZodEnum<["module", "package", "component", "service", "spec", "document", "api", "api-schema", "event", "diagram", "symbol"]>;
+export type UnifiedNodeKind = z.infer<typeof UnifiedNodeKindSchema>;
+/**
+ * UnifiedNode — 4 语言共享的统一节点表示。
+ *
+ * `id` 约定：`<filePath>::<symbolName>` 或纯 `<filePath>` 表示模块节点。
+ * `metadata` 字段允许各 producer 注入扩展数据（如 callSitesCount，由 graph-builder 在 §3.6 注入，Codex C-4）。
+ */
+export declare const UnifiedNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    kind: z.ZodEnum<["module", "package", "component", "service", "spec", "document", "api", "api-schema", "event", "diagram", "symbol"]>;
+    language: z.ZodOptional<z.ZodString>;
+    filePath: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    kind: "symbol" | "module" | "package" | "component" | "service" | "spec" | "document" | "api" | "api-schema" | "event" | "diagram";
+    id: string;
+    label: string;
+    filePath?: string | undefined;
+    language?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    kind: "symbol" | "module" | "package" | "component" | "service" | "spec" | "document" | "api" | "api-schema" | "event" | "diagram";
+    id: string;
+    label: string;
+    filePath?: string | undefined;
+    language?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export type UnifiedNode = z.infer<typeof UnifiedNodeSchema>;
+/**
+ * UnifiedEdge 关系枚举。
+ *
+ * 与 panoramic/graph/graph-types.ts 的 GraphEdge.relation 兼容（含本 Feature 新增的 'calls'）。
+ */
+export declare const UnifiedEdgeRelationSchema: z.ZodEnum<["calls", "depends-on", "cross-module", "contains", "documents", "references", "conceptually_related_to", "rationale_for", "groups", "deploys"]>;
+export type UnifiedEdgeRelation = z.infer<typeof UnifiedEdgeRelationSchema>;
+/**
+ * UnifiedEdge — 统一边。
+ *
+ * `directional` 字段（CL-07 + Codex C-1）：
+ * - calls / depends-on / cross-module / contains 必须 true（语义有方向）
+ * - conceptually_related_to / references 等对称关系默认 false
+ * - GraphQueryEngine 邻接表按 edge.directional 判定双向 / 单向（不再依赖全局 GraphJSON.directed）
+ *
+ * `weight` 字段：可选数值，graph-builder 算分时使用。
+ *
+ * `evidence` 字段：自由文本注释，用于 debug 与 trace（W1.0 v2 / WARN-3 修订：
+ * 不再编码 importType 前缀，保持纯净 specifier，避免污染 panoramic 消费方）。
+ *
+ * `metadata` 字段：producer 注入的扩展结构化数据（如 importType / callSitesCount），
+ * 与 UnifiedNode.metadata 对应（Codex C-4 + Feature 156 W1.0 v2 / WARN-3 关闭）。
+ */
+export declare const UnifiedEdgeSchema: z.ZodEffects<z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+    relation: z.ZodEnum<["calls", "depends-on", "cross-module", "contains", "documents", "references", "conceptually_related_to", "rationale_for", "groups", "deploys"]>;
+    confidence: z.ZodEnum<["high", "medium", "low"]>;
+    directional: z.ZodOptional<z.ZodBoolean>;
+    evidence: z.ZodOptional<z.ZodString>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    target: string;
+    relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+    confidence: "high" | "medium" | "low";
+    metadata?: Record<string, unknown> | undefined;
+    directional?: boolean | undefined;
+    evidence?: string | undefined;
+    weight?: number | undefined;
+}, {
+    source: string;
+    target: string;
+    relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+    confidence: "high" | "medium" | "low";
+    metadata?: Record<string, unknown> | undefined;
+    directional?: boolean | undefined;
+    evidence?: string | undefined;
+    weight?: number | undefined;
+}>, {
+    source: string;
+    target: string;
+    relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+    confidence: "high" | "medium" | "low";
+    metadata?: Record<string, unknown> | undefined;
+    directional?: boolean | undefined;
+    evidence?: string | undefined;
+    weight?: number | undefined;
+}, {
+    source: string;
+    target: string;
+    relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+    confidence: "high" | "medium" | "low";
+    metadata?: Record<string, unknown> | undefined;
+    directional?: boolean | undefined;
+    evidence?: string | undefined;
+    weight?: number | undefined;
+}>;
+export type UnifiedEdge = z.infer<typeof UnifiedEdgeSchema>;
+/**
+ * UnifiedGraph metadata。
+ *
+ * `schemaVersion` 字段为后续 Feature 156 sqlite 持久化迁移留 anchor。
+ */
+export declare const UnifiedGraphMetadataSchema: z.ZodObject<{
+    generatedAt: z.ZodString;
+    projectRoot: z.ZodString;
+    schemaVersion: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    generatedAt: string;
+    projectRoot: string;
+    schemaVersion: string;
+}, {
+    generatedAt: string;
+    projectRoot: string;
+    schemaVersion: string;
+}>;
+export type UnifiedGraphMetadata = z.infer<typeof UnifiedGraphMetadataSchema>;
+/**
+ * UnifiedGraph — 顶层装配。
+ *
+ * Codex C-3 修订：buildUnifiedGraph 同时产出 calls 与 depends-on 边，
+ * 供 ModuleGraph 派生 import 视图（不再要求另起 import-edge 数据源）。
+ */
+export declare const UnifiedGraphSchema: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        kind: z.ZodEnum<["module", "package", "component", "service", "spec", "document", "api", "api-schema", "event", "diagram", "symbol"]>;
+        language: z.ZodOptional<z.ZodString>;
+        filePath: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "symbol" | "module" | "package" | "component" | "service" | "spec" | "document" | "api" | "api-schema" | "event" | "diagram";
+        id: string;
+        label: string;
+        filePath?: string | undefined;
+        language?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        kind: "symbol" | "module" | "package" | "component" | "service" | "spec" | "document" | "api" | "api-schema" | "event" | "diagram";
+        id: string;
+        label: string;
+        filePath?: string | undefined;
+        language?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">;
+    edges: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        source: z.ZodString;
+        target: z.ZodString;
+        relation: z.ZodEnum<["calls", "depends-on", "cross-module", "contains", "documents", "references", "conceptually_related_to", "rationale_for", "groups", "deploys"]>;
+        confidence: z.ZodEnum<["high", "medium", "low"]>;
+        directional: z.ZodOptional<z.ZodBoolean>;
+        evidence: z.ZodOptional<z.ZodString>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        target: string;
+        relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+        confidence: "high" | "medium" | "low";
+        metadata?: Record<string, unknown> | undefined;
+        directional?: boolean | undefined;
+        evidence?: string | undefined;
+        weight?: number | undefined;
+    }, {
+        source: string;
+        target: string;
+        relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+        confidence: "high" | "medium" | "low";
+        metadata?: Record<string, unknown> | undefined;
+        directional?: boolean | undefined;
+        evidence?: string | undefined;
+        weight?: number | undefined;
+    }>, {
+        source: string;
+        target: string;
+        relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+        confidence: "high" | "medium" | "low";
+        metadata?: Record<string, unknown> | undefined;
+        directional?: boolean | undefined;
+        evidence?: string | undefined;
+        weight?: number | undefined;
+    }, {
+        source: string;
+        target: string;
+        relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+        confidence: "high" | "medium" | "low";
+        metadata?: Record<string, unknown> | undefined;
+        directional?: boolean | undefined;
+        evidence?: string | undefined;
+        weight?: number | undefined;
+    }>, "many">;
+    metadata: z.ZodObject<{
+        generatedAt: z.ZodString;
+        projectRoot: z.ZodString;
+        schemaVersion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        generatedAt: string;
+        projectRoot: string;
+        schemaVersion: string;
+    }, {
+        generatedAt: string;
+        projectRoot: string;
+        schemaVersion: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    metadata: {
+        generatedAt: string;
+        projectRoot: string;
+        schemaVersion: string;
+    };
+    nodes: {
+        kind: "symbol" | "module" | "package" | "component" | "service" | "spec" | "document" | "api" | "api-schema" | "event" | "diagram";
+        id: string;
+        label: string;
+        filePath?: string | undefined;
+        language?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    edges: {
+        source: string;
+        target: string;
+        relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+        confidence: "high" | "medium" | "low";
+        metadata?: Record<string, unknown> | undefined;
+        directional?: boolean | undefined;
+        evidence?: string | undefined;
+        weight?: number | undefined;
+    }[];
+}, {
+    metadata: {
+        generatedAt: string;
+        projectRoot: string;
+        schemaVersion: string;
+    };
+    nodes: {
+        kind: "symbol" | "module" | "package" | "component" | "service" | "spec" | "document" | "api" | "api-schema" | "event" | "diagram";
+        id: string;
+        label: string;
+        filePath?: string | undefined;
+        language?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    edges: {
+        source: string;
+        target: string;
+        relation: "cross-module" | "calls" | "depends-on" | "contains" | "documents" | "references" | "conceptually_related_to" | "rationale_for" | "groups" | "deploys";
+        confidence: "high" | "medium" | "low";
+        metadata?: Record<string, unknown> | undefined;
+        directional?: boolean | undefined;
+        evidence?: string | undefined;
+        weight?: number | undefined;
+    }[];
+}>;
+export type UnifiedGraph = z.infer<typeof UnifiedGraphSchema>;
+/**
+ * 给定 relation 计算其默认 directional 值。
+ *
+ * 用于 producer 构造 UnifiedEdge 时不显式传 directional 的兜底；
+ * 也用于 GraphQueryEngine 在 edge.directional === undefined 时回退判定。
+ */
+export declare function defaultDirectionalForRelation(relation: UnifiedEdgeRelation): boolean;
+/**
+ * 当前 UnifiedGraph schema 版本号。
+ * 升级 schema 时需同步更新此常量并迁移 fixture / persistence 层。
+ */
+export declare const UNIFIED_GRAPH_SCHEMA_VERSION = "1.0";
+//# sourceMappingURL=unified-graph.d.ts.map

package/dist/knowledge-graph/unified-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-graph.d.ts","sourceRoot":"","sources":["../../src/knowledge-graph/unified-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,KAAK,UAAU,EACf,KAAK,QAAQ,GACd,MAAM,wBAAwB,CAAC;AAMhC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,sCAAoC,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,iIAahC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAO5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,4JAapC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwB1B,CAAC;AACL,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;EAIrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAa9D;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAEpF;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAQ,CAAC"}

package/dist/knowledge-graph/unified-graph.js

@@ -0,0 +1,182 @@
+/**
+ * UnifiedGraph schema — Feature 151 关键路径基建。
+ *
+ * 4 语言 Knowledge Graph 共享抽象层的核心 schema：
+ * - UnifiedNode：统一节点（module / symbol / spec / component / etc.）
+ * - UnifiedEdge：统一边（calls / depends-on / contains / cross-module / documents / ...）
+ * - UnifiedGraph：顶层装配（nodes + edges + metadata）
+ * - CallSite：函数调用点的原始记录（mapper 阶段产出，call-resolver 阶段消费）
+ *
+ * 关键设计决策（CL-01 / CL-07 / Codex C-1 / Codex C-3）：
+ * - CallSite 不携带 confidence 字段，confidence 在 call-resolver 阶段统一计算
+ * - UnifiedEdge.directional?: boolean — calls / depends-on / cross-module / contains 必须 true，
+ *   覆盖 GraphJSON.directed 全局开关，让 GraphQueryEngine 邻接表按 edge-level 决策
+ * - UnifiedGraph 同时包含 calls 与 depends-on 边；Feature 156 W1.4 起所有 17 consumer
+ *   统一通过 buildUnifiedGraph + deriveModuleGraph（src/knowledge-graph/module-derivation.ts）
+ *   消费 ModuleGraph 视图，不再走 dependency-cruiser 路径
+ */
+import { z } from 'zod';
+// ───────────────────────────────────────────────────────────
+// CallSite — Python adapter 抽取的函数调用点（CL-01 schema）
+//
+// **Codex P0 W-2 修订** — CallSite 的 schema 真正定义在 src/models/call-site.ts，
+// 本模块从 models 层 re-export 以保持 DAG 方向（models → knowledge-graph）。
+// CodeSkeleton.ts 现在直接从 models 层 import，不再反向依赖。
+// ───────────────────────────────────────────────────────────
+export { CalleeKindSchema, CallSiteSchema, } from '../models/call-site.js';
+// ───────────────────────────────────────────────────────────
+// ConfidenceTier — 内部 UnifiedGraph 的 confidence 三档
+// ───────────────────────────────────────────────────────────
+/**
+ * 内部 UnifiedGraph 使用的 confidence 三档枚举。
+ *
+ * 注意：GraphJSON 输出层映射到现有 EXTRACTED / INFERRED / AMBIGUOUS enum
+ * （由 confidence-mapper.ts mapTierToConfidence 函数完成 1:1 转换）。
+ *
+ * 双轨设计动机（CL-08）：
+ * - high/medium/low 偏向"解析确定度"语义（对 call-resolver 直观）
+ * - EXTRACTED/INFERRED/AMBIGUOUS 偏向"证据质量"（对 graph 消费者直观）
+ * - 强制内部统一会污染 resolver 表达
+ */
+export const ConfidenceTierSchema = z.enum(['high', 'medium', 'low']);
+// ───────────────────────────────────────────────────────────
+// UnifiedNode / UnifiedEdge / UnifiedGraph
+// ───────────────────────────────────────────────────────────
+/**
+ * 节点种类枚举（**Codex P0 C-3 修订**）。
+ *
+ * 与 `src/panoramic/graph/graph-types.ts` 的 `GraphNode.kind` 范围严格对齐，
+ * 便于 graph-builder 在 GraphJSON 序列化时不出现 schema drift。
+ * 额外新增 `symbol`（UnifiedGraph 内部需要 function/class 级粒度，panoramic GraphNode 不区分）。
+ */
+export const UnifiedNodeKindSchema = z.enum([
+    'module',
+    'package',
+    'component',
+    'service',
+    'spec',
+    'document',
+    'api',
+    'api-schema',
+    'event',
+    'diagram',
+    // UnifiedGraph 内部独有 — function/class/method 级符号节点
+    'symbol',
+]);
+/**
+ * UnifiedNode — 4 语言共享的统一节点表示。
+ *
+ * `id` 约定：`<filePath>::<symbolName>` 或纯 `<filePath>` 表示模块节点。
+ * `metadata` 字段允许各 producer 注入扩展数据（如 callSitesCount，由 graph-builder 在 §3.6 注入，Codex C-4）。
+ */
+export const UnifiedNodeSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    kind: UnifiedNodeKindSchema,
+    language: z.string().optional(),
+    filePath: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * UnifiedEdge 关系枚举。
+ *
+ * 与 panoramic/graph/graph-types.ts 的 GraphEdge.relation 兼容（含本 Feature 新增的 'calls'）。
+ */
+export const UnifiedEdgeRelationSchema = z.enum([
+    // 本 Feature 新增
+    'calls',
+    // 既有
+    'depends-on',
+    'cross-module',
+    'contains',
+    'documents',
+    'references',
+    'conceptually_related_to',
+    'rationale_for',
+    'groups',
+    'deploys',
+]);
+/**
+ * UnifiedEdge — 统一边。
+ *
+ * `directional` 字段（CL-07 + Codex C-1）：
+ * - calls / depends-on / cross-module / contains 必须 true（语义有方向）
+ * - conceptually_related_to / references 等对称关系默认 false
+ * - GraphQueryEngine 邻接表按 edge.directional 判定双向 / 单向（不再依赖全局 GraphJSON.directed）
+ *
+ * `weight` 字段：可选数值，graph-builder 算分时使用。
+ *
+ * `evidence` 字段：自由文本注释，用于 debug 与 trace（W1.0 v2 / WARN-3 修订：
+ * 不再编码 importType 前缀，保持纯净 specifier，避免污染 panoramic 消费方）。
+ *
+ * `metadata` 字段：producer 注入的扩展结构化数据（如 importType / callSitesCount），
+ * 与 UnifiedNode.metadata 对应（Codex C-4 + Feature 156 W1.0 v2 / WARN-3 关闭）。
+ */
+export const UnifiedEdgeSchema = z
+    .object({
+    source: z.string().min(1),
+    target: z.string().min(1),
+    relation: UnifiedEdgeRelationSchema,
+    confidence: ConfidenceTierSchema,
+    directional: z.boolean().optional(),
+    evidence: z.string().optional(),
+    weight: z.number().nonnegative().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+})
+    // **Codex P0 W-1 修订** — 强制 calls / depends-on / cross-module / contains 必须是
+    // directional=true（缺省也按 true 处理；显式 false 视为合同违反，零容忍）
+    .superRefine((edge, ctx) => {
+    const mustDirectional = ['calls', 'depends-on', 'cross-module', 'contains'].includes(edge.relation);
+    if (mustDirectional && edge.directional === false) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['directional'],
+            message: `relation "${edge.relation}" 必须 directional=true（不允许显式 false，违反 EC-11 / CL-07 合同）`,
+        });
+    }
+});
+/**
+ * UnifiedGraph metadata。
+ *
+ * `schemaVersion` 字段为后续 Feature 156 sqlite 持久化迁移留 anchor。
+ */
+export const UnifiedGraphMetadataSchema = z.object({
+    generatedAt: z.string().datetime(),
+    projectRoot: z.string().min(1),
+    schemaVersion: z.string().regex(/^\d+\.\d+$/),
+});
+/**
+ * UnifiedGraph — 顶层装配。
+ *
+ * Codex C-3 修订：buildUnifiedGraph 同时产出 calls 与 depends-on 边，
+ * 供 ModuleGraph 派生 import 视图（不再要求另起 import-edge 数据源）。
+ */
+export const UnifiedGraphSchema = z.object({
+    nodes: z.array(UnifiedNodeSchema),
+    edges: z.array(UnifiedEdgeSchema),
+    metadata: UnifiedGraphMetadataSchema,
+});
+// ───────────────────────────────────────────────────────────
+// 辅助：directional 默认值规则（与 EC-11 / CL-07 一致）
+// ───────────────────────────────────────────────────────────
+const DIRECTIONAL_RELATIONS = new Set([
+    'calls',
+    'depends-on',
+    'cross-module',
+    'contains',
+]);
+/**
+ * 给定 relation 计算其默认 directional 值。
+ *
+ * 用于 producer 构造 UnifiedEdge 时不显式传 directional 的兜底；
+ * 也用于 GraphQueryEngine 在 edge.directional === undefined 时回退判定。
+ */
+export function defaultDirectionalForRelation(relation) {
+    return DIRECTIONAL_RELATIONS.has(relation);
+}
+/**
+ * 当前 UnifiedGraph schema 版本号。
+ * 升级 schema 时需同步更新此常量并迁移 fixture / persistence 层。
+ */
+export const UNIFIED_GRAPH_SCHEMA_VERSION = '1.0';
+//# sourceMappingURL=unified-graph.js.map

package/dist/knowledge-graph/unified-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-graph.js","sourceRoot":"","sources":["../../src/knowledge-graph/unified-graph.ts"],"names":[],"mappings":"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"}

package/dist/mcp/agent-context-tools.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Feature 155 — Agent-Context MCP Tools (impact / context / detect_changes)
+ *
+ * 3 个 tool handler，建在 Feature 151 已 ship 的 UnifiedGraph + call-resolver 之上：
+ *   - impact: blast radius — 反向 BFS 找受影响 symbols
+ *   - context: 360° symbol 视图 — definition + callers + callees + imports + relatedSpec
+ *   - detect_changes: git diff → changedSymbols → impact 链
+ *
+ * 数据流：
+ *   getCachedGraphData(projectRoot)  // 来自 graph-tools.ts，含 mtime/size stale 检测
+ *     ↓
+ *   query-helpers.ts (bfsTraverse / canonicalizeSymbolId / findFuzzyMatches / ...)
+ *     ↓
+ *   tool handler 输出 JSON envelope
+ *
+ * 错误处理（FR-050）：统一 envelope `{ isError: true, content: [{type:'text', text: JSON({code, message, hint?, context?})}]}`
+ * 错误 code: graph-not-built / symbol-not-found / invalid-symbol-id / invalid-input /
+ *           invalid-diff / payload-too-large / git-spawn-failed / git-timeout / internal-error
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type BfsDirection } from '../knowledge-graph/query-helpers.js';
+interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+        [key: string]: unknown;
+    }>;
+    isError?: true;
+}
+/**
+ * Telemetry entry — 单次 handler 调用的可观测数据，按行写入 JSONL。
+ * 由 Group C MCP-augmented 评测脚本通过 SPECTRA_MCP_TELEMETRY_PATH 注入路径，
+ * SPECTRA_MCP_RUN_ID 标识本次 run，handler 不解析也不消费这两个 env，仅透传。
+ */
+export interface TelemetryEntry {
+    ts: string;
+    toolName: string;
+    requestSize: number;
+    responseSize: number;
+    durationMs: number;
+    runId: string;
+    errorCode?: string;
+    responseSummary?: Record<string, number>;
+    responseSamples?: {
+        symbols?: string[];
+        files?: string[];
+    };
+}
+/**
+ * 写入 telemetry JSONL —— 静默降级：
+ *   - env 未设置 → no-op
+ *   - 写入失败 → 静默吞，不影响 MCP response
+ *
+ * 实现说明（Codex W5 评估）：使用 appendFileSync 而非 async appendFile。
+ *   - eval 场景每 tool call 一次（非高频），SSD 上 sync write < 5ms 不构成瓶颈
+ *   - sync 保证测试可重现（async fire-and-forget 在测试 readFileSync 时可能 race）
+ *   - 如未来高频调用场景出现（生产 long-running MCP server），可切换到 async
+ *
+ * Feature 155 input/output schema 不变（FR-G 合同保护）。
+ */
+export declare function writeTelemetry(entry: TelemetryEntry): void;
+/**
+ * Wrapper：记录 handler 调用 telemetry 后返回原 result。
+ * 包裹所有 return 路径（含 buildErrorResponse 早 return）。
+ *
+ * 设计：调用前先采样 startTime + requestSize，handler 完成后调本函数。
+ * 不破坏 Feature 155 的 input/output schema：result 原样返回。
+ */
+export declare function recordAndReturn(toolName: string, startTimeMs: number, requestSize: number, result: ToolResult, responseSummary?: Record<string, number>, responseSamples?: {
+    symbols?: string[];
+    files?: string[];
+}): ToolResult;
+interface ImpactArgs {
+    target: string;
+    depth?: number;
+    minConfidence?: number;
+    direction?: BfsDirection;
+    budget?: number;
+    projectRoot?: string;
+}
+export declare function handleImpact(args: ImpactArgs): Promise<ToolResult>;
+interface ContextArgs {
+    symbolId: string;
+    include?: Array<'callers' | 'callees' | 'imports' | 'related-spec'>;
+    projectRoot?: string;
+}
+export declare function handleContext(args: ContextArgs): Promise<ToolResult>;
+interface DetectChangesArgs {
+    diff?: string;
+    baseRef?: string;
+    projectRoot?: string;
+    depth?: number;
+    budget?: number;
+    minConfidence?: number;
+}
+export declare function handleDetectChanges(args: DetectChangesArgs): Promise<ToolResult>;
+/**
+ * 把 3 个 Agent-Context tool 注册到 MCP server。
+ * 在 server.ts 里 registerGraphTools(server) 之后调用。
+ */
+export declare function registerAgentContextTools(server: McpServer): void;
+export {};
+//# sourceMappingURL=agent-context-tools.d.ts.map

package/dist/mcp/agent-context-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-context-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/agent-context-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,qCAAqC,CAAC;AAyB7C,UAAU,UAAU;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACvE,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAqBD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IAKnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGzC,eAAe,CAAC,EAAE;QAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAQ1D;AAkBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,UAAU,EAClB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,eAAe,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACzD,UAAU,CAuBZ;AA6DD,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAwHxE;AAeD,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,CAAC,CAAC;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA2G1E;AAwED,UAAU,iBAAiB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAYD,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwKtF;AA4PD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAyDjE"}