spectra-cli 4.1.1 → 4.3.0

package/dist/knowledge-graph/relativize.js

@@ -0,0 +1,104 @@
+/**
+ * Feature 193 — 路径相对化共享 helper（决策 2 / FR-001~FR-004）。
+ *
+ * 职责：把图节点 / 边 id 内嵌的**绝对路径前缀**相对化为 POSIX 相对路径，
+ * 使 graph.json + 快照跨 worktree byte 可移植（同一 commit 的不同路径 worktree
+ * 构建出 byte 一致的图）。
+ *
+ * 核心约定：
+ * - symbol id 结构分隔符（`::` / `.`）不变，仅相对化其中的**路径部分**（第一个 `::` 之前）。
+ * - projectRoot 之内 → strip 前缀 + POSIX 化（`\` → `/`）。
+ * - projectRoot 之外（node_modules / 跨仓 / monorepo 外部）→ **保留绝对原样**，
+ *   由调用方标记 external，绝不生成 `../` 越界链（越界链内嵌 worktree 目录深度，
+ *   跨不同深度 worktree 不一致）。
+ * - 幂等：输入已是相对路径（非绝对）时原样返回。
+ */
+import * as path from 'node:path';
+/**
+ * 跨平台「绝对 / 异源路径」判定（Codex implement-C1.1 / new-2）。
+ *
+ * 命中任一即视为非 POSIX 相对路径：
+ * - POSIX 绝对（`/...`）
+ * - Windows 绝对（`C:\...` / `C:/...` / UNC `\\...`）
+ * - Windows 盘符前缀（含 drive-relative `C:foo`，`path.win32.isAbsolute` 对其返回 false 会漏判）
+ *
+ * 用于：加载期 graph-format-stale 检测 + 写入前 portable 守卫——保证 POSIX 运行时也能识别
+ * 旧 Windows 导出图里的绝对/盘符路径，三处调用点共用同一判定避免分叉。
+ */
+export function isAbsoluteForeignPath(p) {
+    return path.posix.isAbsolute(p) || path.win32.isAbsolute(p) || /^[a-zA-Z]:/.test(p);
+}
+/**
+ * segment-aware 包含判定：filePart 是否真位于 root 之内（Codex implement-C1.2）。
+ *
+ * 用 `path.relative` 段级判定，避免两类误判：
+ * - 前缀歧义：`/repo/app-old` 不应判为在 `/repo/app` 内（startsWith 会误判）
+ * - 同名目录：`..foo`（合法子目录）不应被 `rel.startsWith('..')` 误判为越界
+ *
+ * 仅当 rel 恰为 `..` 或以 `../`(POSIX) / `..\`(Win) 起始 / 仍是绝对路径时，判为不在 root 内。
+ */
+export function isPathContainedUnder(root, filePart) {
+    const rel = path.relative(root, filePart);
+    if (rel === '')
+        return true; // filePart === root 本身
+    if (rel === '..')
+        return false;
+    if (rel.startsWith(`..${path.sep}`) || rel.startsWith('../'))
+        return false;
+    if (path.isAbsolute(rel))
+        return false; // 跨盘符等 path.relative 退化为绝对
+    return true;
+}
+/**
+ * 把绝对路径相对化为相对 projectRoot 的 POSIX 路径。
+ *
+ * - 输入非绝对（已相对 / 逻辑名）→ 原样返回（幂等），external=false。
+ * - 输入绝对且在 projectRoot 内 → strip 前缀 + POSIX 化，external=false。
+ * - 输入绝对但在 projectRoot 外 → 返回原绝对值，external=true。
+ *
+ * @param absPath 待处理路径（可能绝对、可能已相对）
+ * @param projectRoot 项目根（相对化基准）
+ */
+export function relativizePosix(absPath, projectRoot) {
+    // 幂等：已是相对路径 / 逻辑名，原样返回（不误把相对路径再次 path.relative）
+    if (!path.isAbsolute(absPath)) {
+        return { value: toPosix(absPath), external: false };
+    }
+    const root = path.resolve(projectRoot);
+    const resolved = path.resolve(absPath);
+    // rel === '' 表示 absPath === projectRoot 本身（罕见），视为 root 内的 '.'，非 external。
+    if (resolved === root) {
+        return { value: '.', external: false };
+    }
+    // projectRoot 之外（真正越界 `../` 或跨盘符）→ 保留原绝对值 + 标 external，不生成越界链。
+    // Codex implement-C1.2：用 isPathContainedUnder 段级判定，避免 `..foo` 同名子目录被误判越界。
+    if (!isPathContainedUnder(root, resolved)) {
+        return { value: toPosix(absPath), external: true };
+    }
+    return { value: toPosix(path.relative(root, resolved)), external: false };
+}
+/**
+ * 相对化一个 symbol id（形如 `<path>::<name>` / `<path>::<name>.<member>` / 纯 `<path>`）。
+ *
+ * 只相对化第一个 `::` 之前的路径部分，保留 `::` / `.` 结构分隔符与 symbol 段不变。
+ *
+ * @param id 原始 symbol id（路径部分可能绝对）
+ * @param projectRoot 相对化基准
+ * @returns 相对化后的 id + 路径部分是否 external
+ */
+export function relativizeSymbolId(id, projectRoot) {
+    const sepIdx = id.indexOf('::');
+    if (sepIdx < 0) {
+        // 纯路径节点（module id）或非路径逻辑 id
+        return relativizePosix(id, projectRoot);
+    }
+    const filePart = id.slice(0, sepIdx);
+    const rest = id.slice(sepIdx); // 含 `::` 起的剩余结构（symbol 段）
+    const r = relativizePosix(filePart, projectRoot);
+    return { value: r.value + rest, external: r.external };
+}
+/** Windows 反斜杠统一为 POSIX 正斜杠（FR-003 跨平台 byte 一致） */
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+//# sourceMappingURL=relativize.js.map

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

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

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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"}