@mycodemap/mycodemap 0.4.2 → 0.5.0

package/dist/generator/ai-overview.d.ts

@@ -0,0 +1,51 @@
+import type { CodeMap } from '../types/index.js';
+import type { SubagentOutput } from '../ai/subagent-caller.js';
+/**
+ * AI Overview Generator 配置
+ */
+export interface AIOverviewConfig {
+    /** 输出目录 */
+    outputDir: string;
+    /** 是否启用 AI 生成 */
+    enabled?: boolean;
+    /** 输出文件名 */
+    filename?: string;
+}
+/**
+ * AI Overview Generator - 生成并保存 AI 概述
+ */
+export declare class AIOverviewGenerator {
+    private outputDir;
+    private enabled;
+    private filename;
+    constructor(config: AIOverviewConfig);
+    /**
+     * 生成并保存 AI 概述
+     */
+    generate(codeMap: CodeMap, aiOutput: SubagentOutput): Promise<string>;
+    /**
+     * 构建 Markdown 内容
+     */
+    private buildMarkdown;
+    /**
+     * 读取已保存的概述
+     */
+    read(): Promise<string | null>;
+    /**
+     * 检查概述是否存在
+     */
+    exists(): Promise<boolean>;
+    /**
+     * 获取输出文件路径
+     */
+    getOutputPath(): string;
+    /**
+     * 是否启用
+     */
+    isEnabled(): boolean;
+}
+/**
+ * 创建 AI Overview Generator 实例
+ */
+export declare function createAIOverviewGenerator(config: AIOverviewConfig): AIOverviewGenerator;
+//# sourceMappingURL=ai-overview.d.ts.map

package/dist/generator/ai-overview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-overview.d.ts","sourceRoot":"","sources":["../../src/generator/ai-overview.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,gBAAgB;IAMpC;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAe3E;;OAEG;IACH,OAAO,CAAC,aAAa;IAgGrB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUpC;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAWhC;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,SAAS,IAAI,OAAO;CAGrB;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,mBAAmB,CAEvF"}

package/dist/generator/ai-overview.js

@@ -0,0 +1,160 @@
+// ============================================
+// AI Overview Generator - AI 概述生成与保存
+// ============================================
+import * as fs from 'fs/promises';
+import * as path from 'path';
+/**
+ * AI Overview Generator - 生成并保存 AI 概述
+ */
+export class AIOverviewGenerator {
+    outputDir;
+    enabled;
+    filename;
+    constructor(config) {
+        this.outputDir = config.outputDir;
+        this.enabled = config.enabled ?? true;
+        this.filename = config.filename || 'AI_OVERVIEW.md';
+    }
+    /**
+     * 生成并保存 AI 概述
+     */
+    async generate(codeMap, aiOutput) {
+        const outputPath = path.join(this.outputDir, this.filename);
+        // 构建 Markdown 内容
+        const content = this.buildMarkdown(codeMap, aiOutput);
+        // 确保输出目录存在
+        await fs.mkdir(this.outputDir, { recursive: true });
+        // 写入文件
+        await fs.writeFile(outputPath, content, 'utf-8');
+        return outputPath;
+    }
+    /**
+     * 构建 Markdown 内容
+     */
+    buildMarkdown(codeMap, aiOutput) {
+        const lines = [];
+        // 标题
+        lines.push('# ' + aiOutput.title);
+        lines.push('');
+        // 元数据
+        lines.push('<!-- AI Generated Overview -->');
+        lines.push(`- **生成时间**: ${new Date(aiOutput.metadata.generatedAt).toLocaleString('zh-CN')}`);
+        lines.push(`- **模型**: ${aiOutput.metadata.model}`);
+        lines.push('');
+        // 项目统计
+        lines.push('## 项目统计');
+        lines.push('');
+        lines.push(`| 指标 | 数值 |`);
+        lines.push(`|------|------|`);
+        lines.push(`| 文件总数 | ${codeMap.summary.totalFiles} |`);
+        lines.push(`| 代码行数 | ${codeMap.summary.totalLines} |`);
+        lines.push(`| 模块数量 | ${codeMap.summary.totalModules} |`);
+        lines.push(`| 导出符号 | ${codeMap.summary.totalExports} |`);
+        lines.push(`| 类型定义 | ${codeMap.summary.totalTypes} |`);
+        lines.push('');
+        // 架构信息
+        if (aiOutput.architecture) {
+            lines.push('## 架构分析');
+            lines.push('');
+            lines.push(`- **架构模式**: ${aiOutput.architecture.pattern || '未识别'}`);
+            lines.push('');
+            if (aiOutput.architecture.layers && aiOutput.architecture.layers.length > 0) {
+                lines.push('### 分层结构');
+                lines.push('');
+                for (const layer of aiOutput.architecture.layers) {
+                    lines.push(`#### ${layer.name}`);
+                    lines.push(`- **职责**: ${layer.responsibility}`);
+                    if (layer.modules.length > 0) {
+                        lines.push(`- **模块**: ${layer.modules.join(', ')}`);
+                    }
+                    lines.push('');
+                }
+            }
+            if (aiOutput.architecture.metrics) {
+                lines.push('### 架构指标');
+                lines.push('');
+                lines.push(`- **耦合度**: ${aiOutput.architecture.metrics.coupling}`);
+                lines.push(`- **内聚度**: ${aiOutput.architecture.metrics.cohesion}`);
+                lines.push(`- **复杂度**: ${aiOutput.architecture.metrics.complexity}`);
+                lines.push('');
+            }
+        }
+        // AI 生成的内容
+        lines.push('## 项目概述');
+        lines.push('');
+        lines.push(aiOutput.content);
+        lines.push('');
+        // 亮点模块
+        if (aiOutput.highlights.length > 0) {
+            lines.push('## 亮点模块');
+            lines.push('');
+            for (const highlight of aiOutput.highlights) {
+                lines.push(`- ${highlight}`);
+            }
+            lines.push('');
+        }
+        // 模块列表（简要）
+        lines.push('## 模块列表');
+        lines.push('');
+        lines.push('| 模块路径 | 导出数 | 依赖数 |');
+        lines.push('|----------|--------|--------|');
+        for (const mod of codeMap.modules.slice(0, 20)) {
+            const exportsCount = mod.exports.length;
+            const depsCount = mod.dependencies.length;
+            const relPath = path.relative(codeMap.project.rootDir, mod.path);
+            lines.push(`| ${relPath} | ${exportsCount} | ${depsCount} |`);
+        }
+        if (codeMap.modules.length > 20) {
+            lines.push(`| ... | ... | ... |`);
+        }
+        lines.push('');
+        lines.push('---');
+        lines.push('');
+        lines.push('*由 CodeMap AI Generator 生成*');
+        return lines.join('\n');
+    }
+    /**
+     * 读取已保存的概述
+     */
+    async read() {
+        const outputPath = path.join(this.outputDir, this.filename);
+        try {
+            return await fs.readFile(outputPath, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 检查概述是否存在
+     */
+    async exists() {
+        const outputPath = path.join(this.outputDir, this.filename);
+        try {
+            await fs.access(outputPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 获取输出文件路径
+     */
+    getOutputPath() {
+        return path.join(this.outputDir, this.filename);
+    }
+    /**
+     * 是否启用
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+}
+/**
+ * 创建 AI Overview Generator 实例
+ */
+export function createAIOverviewGenerator(config) {
+    return new AIOverviewGenerator(config);
+}
+//# sourceMappingURL=ai-overview.js.map

package/dist/generator/ai-overview.js.map

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

package/dist/infrastructure/storage/StorageFactory.d.ts

@@ -22,15 +22,22 @@ export declare class StorageFactory implements IStorageFactory {
      * @returns 初始化的存储实例
      */
     createForProject(projectPath: string, config: StorageConfig): Promise<IStorage>;
+    /**
+     * 检查 KùzuDB 是否可用
+     * 尝试动态导入 kuzu 并创建临时数据库验证功能正常
+     */
+    private checkKuzuAvailability;
     /**
      * 自动确定存储类型
      *
-     * 策略：
-     * - 小项目（<100文件）: 文件系统
-     * - 中等项目（100-1000文件）: 文件系统
-     * - 大项目（>1000文件）: KùzuDB
+     * 策略（DEC-01）：
+     * - 优先尝试 KùzuDB（如果可用）
+     * - KùzuDB 不可用时 fallback 到文件系统
+     * - 显式配置优先于自动选择
      *
-     * 可通过配置调整阈值
+     * 降级策略（DEC-03）：
+     * - auto 模式：静默 fallback 到 filesystem
+     * - kuzudb 模式：抛出错误，由调用者处理降级
      */
     private determineStorageType;
     /**

package/dist/infrastructure/storage/StorageFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageFactory.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/storage/StorageFactory.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACb,WAAW,EACZ,MAAM,kCAAkC,CAAC;AAmB1C;;;;;;;;GAQG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqCtD;;;;;OAKG;IACG,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMrF;;;;;;;;;OASG;YACW,oBAAoB;IAWlC;;;;OAIG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO;IAkBzD;;;OAGG;IACH,MAAM,CAAC,wBAAwB,IAAI,WAAW,EAAE;CAIjD;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC"}
+{"version":3,"file":"StorageFactory.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/storage/StorageFactory.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACb,WAAW,EACZ,MAAM,kCAAkC,CAAC;AAmB1C;;;;;;;;GAQG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAiDtD;;;;;OAKG;IACG,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMrF;;;OAGG;YACW,qBAAqB;IAcnC;;;;;;;;;;;OAWG;YACW,oBAAoB;IAwBlC;;;;OAIG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO;IAkBzD;;;OAGG;IACH,MAAM,CAAC,wBAAwB,IAAI,WAAW,EAAE;CAIjD;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC"}

package/dist/infrastructure/storage/StorageFactory.js

@@ -34,9 +34,22 @@ export class StorageFactory {
      * @returns 存储实例
      */
     async create(config) {
-        const storageType = config.type === 'auto'
-            ? await this.determineStorageType(config)
-            : config.type;
+        let storageType;
+        try {
+            storageType = config.type === 'auto'
+                ? await this.determineStorageType(config)
+                : config.type;
+        }
+        catch (error) {
+            // 如果确定类型失败且是 kuzudb 请求，fallback 到 filesystem
+            if (config.type === 'kuzudb' && error instanceof StorageError && error.code === 'KUZU_NOT_AVAILABLE') {
+                console.warn('[StorageFactory] KùzuDB unavailable, falling back to filesystem');
+                storageType = 'filesystem';
+            }
+            else {
+                throw error;
+            }
+        }
         switch (storageType) {
             case 'filesystem':
                 return new FileSystemStorage(config);
@@ -67,23 +80,51 @@ export class StorageFactory {
         await storage.initialize(projectPath);
         return storage;
     }
+    /**
+     * 检查 KùzuDB 是否可用
+     * 尝试动态导入 kuzu 并创建临时数据库验证功能正常
+     */
+    async checkKuzuAvailability() {
+        try {
+            // @ts-ignore kuzu is an optional dependency, not installed in CI
+            const kuzu = await import('kuzu');
+            const tempDb = new kuzu.Database(':memory:');
+            if (typeof tempDb.close === 'function') {
+                await tempDb.close();
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * 自动确定存储类型
      *
-     * 策略：
-     * - 小项目（<100文件）: 文件系统
-     * - 中等项目（100-1000文件）: 文件系统
-     * - 大项目（>1000文件）: KùzuDB
+     * 策略（DEC-01）：
+     * - 优先尝试 KùzuDB（如果可用）
+     * - KùzuDB 不可用时 fallback 到文件系统
+     * - 显式配置优先于自动选择
      *
-     * 可通过配置调整阈值
+     * 降级策略（DEC-03）：
+     * - auto 模式：静默 fallback 到 filesystem
+     * - kuzudb 模式：抛出错误，由调用者处理降级
      */
     async determineStorageType(config) {
-        const thresholds = config.autoThresholds ?? {
-            useGraphDBWhenFileCount: 1000,
-            useGraphDBWhenNodeCount: 10000,
-        };
-        // 默认使用文件系统，因为它最简单可靠
-        // 实际项目分析后可能需要更复杂的启发式算法
+        // 如果明确指定了非 auto 类型，直接返回
+        if (config.type !== 'auto' && config.type !== 'kuzudb') {
+            return config.type;
+        }
+        // 优先尝试 KùzuDB
+        const kuzuAvailable = await this.checkKuzuAvailability();
+        if (kuzuAvailable) {
+            return 'kuzudb';
+        }
+        // 如果明确指定 kuzudb 但不可用，抛出错误让调用者处理降级
+        if (config.type === 'kuzudb') {
+            throw new StorageError('KùzuDB is not available. Install with: npm install kuzu', 'KUZU_NOT_AVAILABLE');
+        }
+        // auto 模式下 fallback 到 filesystem
         return 'filesystem';
     }
     /**

package/dist/infrastructure/storage/StorageFactory.js.map

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

package/dist/infrastructure/storage/adapters/Neo4jStorage.d.ts

@@ -0,0 +1,41 @@
+import type { StorageConfig, Cycle, ImpactResult, ProjectStatistics } from '../../../interface/types/storage.js';
+import type { CodeGraph, Module, Symbol, Dependency } from '../../../interface/types/index.js';
+import { StorageBase } from '../interfaces/StorageBase.js';
+/**
+ * Neo4j 存储适配器（可选依赖）
+ *
+ * 安装：npm install neo4j-driver
+ *
+ * 特点：
+ * - 连接远程/本地 Neo4j 实例
+ * - 用 snapshot 节点持久化完整 CodeGraph
+ * - 查询/分析接口与共享 storage contract 保持一致
+ * - 错误语义显式暴露，不再静默 fallback
+ */
+export declare class Neo4jStorage extends StorageBase {
+    readonly type: "neo4j";
+    private driver;
+    private readonly dbConfig;
+    constructor(config: StorageConfig);
+    protected doInitialize(): Promise<void>;
+    protected doClose(): Promise<void>;
+    saveCodeGraph(graph: CodeGraph): Promise<void>;
+    loadCodeGraph(): Promise<CodeGraph>;
+    deleteProject(): Promise<void>;
+    updateModule(module: Module): Promise<void>;
+    deleteModule(moduleId: string): Promise<void>;
+    findModuleById(id: string): Promise<Module | null>;
+    findModulesByPath(path: string): Promise<Module[]>;
+    findSymbolByName(name: string): Promise<Symbol[]>;
+    findSymbolById(id: string): Promise<Symbol | null>;
+    findDependencies(moduleId: string): Promise<Dependency[]>;
+    findDependents(moduleId: string): Promise<Dependency[]>;
+    findCallers(functionId: string): Promise<Symbol[]>;
+    findCallees(functionId: string): Promise<Symbol[]>;
+    detectCycles(): Promise<Cycle[]>;
+    calculateImpact(moduleId: string, depth: number): Promise<ImpactResult>;
+    getStatistics(): Promise<ProjectStatistics>;
+    private getDriver;
+    private runStatement;
+}
+//# sourceMappingURL=Neo4jStorage.d.ts.map

package/dist/infrastructure/storage/adapters/Neo4jStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Neo4jStorage.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/storage/adapters/Neo4jStorage.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EACL,YAAY,EACZ,iBAAiB,EAClB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EACV,SAAS,EACT,MAAM,EACN,MAAM,EACN,UAAU,EACX,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAgB,MAAM,8BAA8B,CAAC;AA4DzE;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,SAAQ,WAAW;IAC3C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;gBAE7B,MAAM,EAAE,aAAa;cAKjB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;cAkB7B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQlC,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAe9C,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC;IAkBnC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7C,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMlD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAMlD,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAMjD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMlD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAKzD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAKvD,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKlD,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAKlD,YAAY,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAKhC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKvE,aAAa,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAKjD,OAAO,CAAC,SAAS;YAWH,YAAY;CAkB3B"}

package/dist/infrastructure/storage/adapters/Neo4jStorage.js

@@ -0,0 +1,162 @@
+// [META] since:2026-03 | owner:architecture-team | stable:false
+// [WHY] Neo4j storage adapter - enterprise graph database backend
+// ============================================
+// Neo4j 存储适配器 - 企业级图数据库后端
+// ============================================
+import { StorageBase, StorageError } from '../interfaces/StorageBase.js';
+import { calculateImpactInGraph, createEmptyCodeGraph, deleteModuleFromGraph, deserializeCodeGraphSnapshot, detectCyclesInGraph, findCalleesInGraph, findCallersInGraph, findDependenciesInGraph, findDependentsInGraph, getProjectStatisticsFromGraph, serializeCodeGraphSnapshot, upsertModuleInGraph, } from '../graph-helpers.js';
+async function loadNeo4jModule() {
+    const moduleName = 'neo4j-driver';
+    return await import(moduleName);
+}
+function normalizeNeo4jValue(value) {
+    if (typeof value === 'object' &&
+        value !== null &&
+        'toNumber' in value &&
+        typeof value.toNumber === 'function') {
+        return value.toNumber();
+    }
+    return value;
+}
+/**
+ * Neo4j 存储适配器（可选依赖）
+ *
+ * 安装：npm install neo4j-driver
+ *
+ * 特点：
+ * - 连接远程/本地 Neo4j 实例
+ * - 用 snapshot 节点持久化完整 CodeGraph
+ * - 查询/分析接口与共享 storage contract 保持一致
+ * - 错误语义显式暴露，不再静默 fallback
+ */
+export class Neo4jStorage extends StorageBase {
+    type = 'neo4j';
+    driver = null;
+    dbConfig;
+    constructor(config) {
+        super();
+        this.dbConfig = config;
+    }
+    async doInitialize() {
+        try {
+            const neo4j = await loadNeo4jModule();
+            const uri = this.dbConfig.uri ?? 'bolt://localhost:7687';
+            const username = this.dbConfig.username ?? 'neo4j';
+            const password = this.dbConfig.password ?? 'password';
+            this.driver = neo4j.driver(uri, neo4j.auth.basic(username, password));
+            await this.driver.verifyConnectivity();
+        }
+        catch (error) {
+            throw new StorageError('Failed to initialize Neo4j storage', 'NEO4J_INIT_FAILED', error);
+        }
+    }
+    async doClose() {
+        if (this.driver) {
+            await this.driver.close();
+        }
+        this.driver = null;
+    }
+    async saveCodeGraph(graph) {
+        this.ensureInitialized();
+        await this.runStatement('MATCH (s:CodeMapSnapshot) DETACH DELETE s');
+        await this.runStatement('CREATE (s:CodeMapSnapshot {id: $id, projectId: $projectId, graph: $graph, updatedAt: $updatedAt})', {
+            id: 'codemap-snapshot',
+            projectId: graph.project.id,
+            graph: serializeCodeGraphSnapshot(graph),
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async loadCodeGraph() {
+        this.ensureInitialized();
+        const result = await this.runStatement('MATCH (s:CodeMapSnapshot) RETURN s.graph AS graph LIMIT 1');
+        const record = result.records[0];
+        const snapshot = typeof record?.get === 'function'
+            ? normalizeNeo4jValue(record.get('graph'))
+            : null;
+        if (typeof snapshot !== 'string') {
+            return createEmptyCodeGraph(this.projectPath ?? '');
+        }
+        return deserializeCodeGraphSnapshot(snapshot, this.projectPath ?? '');
+    }
+    async deleteProject() {
+        this.ensureInitialized();
+        await this.runStatement('MATCH (s:CodeMapSnapshot) DETACH DELETE s');
+    }
+    async updateModule(module) {
+        this.ensureInitialized();
+        const graph = await this.loadCodeGraph();
+        await this.saveCodeGraph(upsertModuleInGraph(graph, module));
+    }
+    async deleteModule(moduleId) {
+        this.ensureInitialized();
+        const graph = await this.loadCodeGraph();
+        await this.saveCodeGraph(deleteModuleFromGraph(graph, moduleId));
+    }
+    async findModuleById(id) {
+        this.ensureInitialized();
+        const graph = await this.loadCodeGraph();
+        return graph.modules.find(module => module.id === id) ?? null;
+    }
+    async findModulesByPath(path) {
+        this.ensureInitialized();
+        const graph = await this.loadCodeGraph();
+        return graph.modules.filter(module => module.path.includes(path));
+    }
+    async findSymbolByName(name) {
+        this.ensureInitialized();
+        const graph = await this.loadCodeGraph();
+        return graph.symbols.filter(symbol => symbol.name.includes(name));
+    }
+    async findSymbolById(id) {
+        this.ensureInitialized();
+        const graph = await this.loadCodeGraph();
+        return graph.symbols.find(symbol => symbol.id === id) ?? null;
+    }
+    async findDependencies(moduleId) {
+        this.ensureInitialized();
+        return findDependenciesInGraph(await this.loadCodeGraph(), moduleId);
+    }
+    async findDependents(moduleId) {
+        this.ensureInitialized();
+        return findDependentsInGraph(await this.loadCodeGraph(), moduleId);
+    }
+    async findCallers(functionId) {
+        this.ensureInitialized();
+        return findCallersInGraph(await this.loadCodeGraph(), functionId);
+    }
+    async findCallees(functionId) {
+        this.ensureInitialized();
+        return findCalleesInGraph(await this.loadCodeGraph(), functionId);
+    }
+    async detectCycles() {
+        this.ensureInitialized();
+        return detectCyclesInGraph(await this.loadCodeGraph());
+    }
+    async calculateImpact(moduleId, depth) {
+        this.ensureInitialized();
+        return calculateImpactInGraph(await this.loadCodeGraph(), moduleId, depth);
+    }
+    async getStatistics() {
+        this.ensureInitialized();
+        return getProjectStatisticsFromGraph(await this.loadCodeGraph());
+    }
+    getDriver() {
+        if (!this.driver) {
+            throw new StorageError('Neo4j driver not initialized', 'NEO4J_DRIVER_NOT_READY');
+        }
+        return this.driver;
+    }
+    async runStatement(query, params) {
+        const session = this.getDriver().session();
+        try {
+            return await session.run(query, params);
+        }
+        catch (error) {
+            throw new StorageError('Failed to execute Neo4j query', 'NEO4J_QUERY_FAILED', error);
+        }
+        finally {
+            await session.close();
+        }
+    }
+}
+//# sourceMappingURL=Neo4jStorage.js.map

package/dist/infrastructure/storage/adapters/Neo4jStorage.js.map

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

package/dist/interface/types/design-contract.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 必填 section
+ */
+export type DesignContractRequiredSectionId = 'goal' | 'constraints' | 'acceptanceCriteria' | 'nonGoals';
+/**
+ * 可选 section
+ */
+export type DesignContractOptionalSectionId = 'context' | 'openQuestions' | 'notes';
+/**
+ * 全量 section 标识
+ */
+export type DesignContractSectionId = DesignContractRequiredSectionId | DesignContractOptionalSectionId;
+/**
+ * 结构化诊断严重级别
+ */
+export type DesignContractDiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * 结构化诊断代码
+ */
+export type DesignContractDiagnosticCode = 'file-not-found' | 'missing-section' | 'duplicate-section' | 'empty-section' | 'unknown-section' | 'ambiguous-heading';
+/**
+ * 原始/归一化 section 内容
+ */
+export interface DesignContractSection {
+    id: DesignContractSectionId;
+    title: string;
+    rawHeading: string;
+    content: string[];
+    line: number;
+}
+/**
+ * 设计契约元数据
+ */
+export interface DesignContractMetadata {
+    version: 'v1';
+    title?: string;
+    sourcePath?: string;
+}
+/**
+ * 结构化诊断
+ */
+export interface DesignContractDiagnostic {
+    code: DesignContractDiagnosticCode;
+    severity: DesignContractDiagnosticSeverity;
+    message: string;
+    section?: DesignContractSectionId;
+    heading?: string;
+    line?: number;
+    suggestion?: string;
+}
+/**
+ * 原始设计契约文档
+ */
+export interface DesignContract {
+    metadata: DesignContractMetadata;
+    sections: DesignContractSection[];
+}
+/**
+ * 归一化设计契约（允许带缺失段，供 validator/CLI 决策）
+ */
+export interface NormalizedDesignContract {
+    metadata: DesignContractMetadata;
+    sections: Partial<Record<DesignContractSectionId, DesignContractSection>>;
+    orderedSections: DesignContractSection[];
+    missingRequiredSections: DesignContractRequiredSectionId[];
+    diagnostics: DesignContractDiagnostic[];
+}
+//# sourceMappingURL=design-contract.d.ts.map