@mycodemap/mycodemap 0.4.1 → 0.5.0

package/dist/cli/commands/analyze.js

@@ -2,18 +2,22 @@
  * [META] AnalyzeCommand - 统一分析入口
  * [WHY] 为 CI 与人工调用提供统一分析输出，支持 machine/json 契约
  */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { parseArgs } from 'node:util';
 import chalk from 'chalk';
 import { ImpactCommand } from './impact.js';
 import { DepsCommand } from './deps.js';
 import { ComplexityCommand } from './complexity.js';
+import { ANALYZE_PARSE_OPTIONS, getAnalyzeHelpText } from './analyze-options.js';
+import { PUBLIC_INTENTS, calculateConfidenceLevel } from '../../orchestrator/types.js';
 import { resolveTestFile } from '../../orchestrator/test-linker.js';
 import { ToolOrchestrator } from '../../orchestrator/tool-orchestrator.js';
 import { ResultFusion } from '../../orchestrator/result-fusion.js';
 import { CodemapAdapter } from '../../orchestrator/adapters/codemap-adapter.js';
 import { AstGrepAdapter } from '../../orchestrator/adapters/ast-grep-adapter.js';
 import { IntentRouter } from '../../orchestrator/intent-router.js';
-import { resolveOutputDir } from '../paths.js';
+import { resolveDataPath, resolveOutputDir } from '../paths.js';
 /**
  * 错误码定义
  */
@@ -47,14 +51,7 @@ export const ERROR_MESSAGES = {
  * 支持的 intent 列表
  */
 export const VALID_INTENTS = [
-    'impact',
-    'dependency',
-    'search',
-    'documentation',
-    'complexity',
-    'overview',
-    'refactor',
-    'reference',
+    ...PUBLIC_INTENTS,
 ];
 /**
  * AnalyzeCommand 分析命令类
@@ -73,12 +70,30 @@ export class AnalyzeCommand {
      * @throws AnalyzeError 当参数无效时
      */
     validate() {
+        if (!this.args.intent) {
+            throw this.createError(AnalyzeErrorCode.E0002_MISSING_REQUIRED_PARAM, '缺少必要参数: intent');
+        }
+        const intentRouter = new IntentRouter();
         // 验证 intent
-        if (this.args.intent && !VALID_INTENTS.includes(this.args.intent)) {
+        if (!intentRouter.isValidIntent(this.args.intent)) {
             throw this.createError(AnalyzeErrorCode.E0001_INVALID_INTENT, `无效的 intent: ${this.args.intent}。支持的选项: ${VALID_INTENTS.join(', ')}`);
         }
-        // 验证 targets
-        if (!this.args.targets || this.args.targets.length === 0) {
+        const routedIntent = intentRouter.route(this.args);
+        const normalizedIntent = routedIntent.intent;
+        const hasTargets = Boolean(this.args.targets && this.args.targets.length > 0);
+        const hasKeywords = Boolean(this.args.keywords && this.args.keywords.length > 0);
+        if (normalizedIntent === 'find') {
+            if (!hasTargets && !hasKeywords) {
+                throw this.createError(AnalyzeErrorCode.E0002_MISSING_REQUIRED_PARAM, '缺少必要参数: targets 或 keywords');
+            }
+            return;
+        }
+        if (normalizedIntent === 'link' &&
+            routedIntent.compatibility?.normalizedFrom === 'reference' &&
+            hasKeywords) {
+            return;
+        }
+        if (!hasTargets) {
             throw this.createError(AnalyzeErrorCode.E0002_MISSING_REQUIRED_PARAM, '缺少必要参数: targets');
         }
     }
@@ -95,33 +110,39 @@ export class AnalyzeCommand {
      */
     async execute() {
         this.validate();
-        const intent = this.args.intent || 'impact';
-        const scope = this.args.scope || 'direct';
+        const intentRouter = new IntentRouter();
+        const intentObj = intentRouter.route(this.args);
+        const scope = intentObj.scope;
         const topK = this.args.topK || 8;
-        // 尝试使用 ToolOrchestrator 和 ResultFusion
-        try {
-            return await this.executeWithOrchestrator(intent, scope, topK);
-        }
-        catch (error) {
-            // 回退到原有实现
-            console.warn('[Analyze] Orchestrator not available, falling back to legacy mode');
-        }
-        // 根据 intent 路由 (legacy)
-        switch (intent) {
-            case 'impact':
-                return this.executeImpact(scope, topK);
-            case 'dependency':
-                return this.executeDeps(topK);
-            case 'complexity':
-                return this.executeComplexity(topK);
+        switch (intentObj.intent) {
+            case 'read':
+                return this.executeRead(intentObj, scope, topK);
+            case 'link':
+                return this.executeLink(intentObj, topK);
+            case 'show':
+                return this.executeShow(intentObj, topK);
+            case 'find':
+                return this.executeFindWithFallback(intentObj, topK);
             default:
-                return this.executeImpact(scope, topK);
+                throw this.createError(AnalyzeErrorCode.E0001_INVALID_INTENT, `无效的 intent: ${intentObj.intent}`);
+        }
+    }
+    /**
+     * `find` 优先走 orchestrator，失败时回退到 AstGrep 搜索
+     */
+    async executeFindWithFallback(intentObj, topK) {
+        try {
+            return this.withCompatibility(await this.executeWithOrchestrator(intentObj, topK), intentObj.compatibility);
+        }
+        catch {
+            console.warn('[Analyze] Orchestrator not available, falling back to AstGrep search');
+            return this.executeFind(intentObj, topK);
         }
     }
     /**
      * 使用编排器执行分析
      */
-    async executeWithOrchestrator(intent, scope, topK) {
+    async executeWithOrchestrator(intentObj, topK) {
         const orchestrator = new ToolOrchestrator();
         // 注册适配器
         const codemapAdapter = new CodemapAdapter({ codemapPath: resolveOutputDir().outputDir });
@@ -129,13 +150,7 @@ export class AnalyzeCommand {
         orchestrator.registerAdapter(codemapAdapter);
         orchestrator.registerAdapter(astGrepAdapter);
         const fusion = new ResultFusion();
-        const intentRouter = new IntentRouter();
-        // 构建意图对象
-        const intentObj = intentRouter.route({
-            ...this.args,
-            intent: intent,
-            scope: scope,
-        });
+        const effectiveIntent = intentObj.executionIntent ?? intentObj.intent;
         let orchestratedResults = [];
         let confidence;
         if (intentObj.secondary) {
@@ -143,7 +158,7 @@ export class AnalyzeCommand {
             const resultsByTool = await orchestrator.executeParallel(intentObj, tools);
             orchestratedResults = fusion.fuse(resultsByTool, {
                 topK,
-                intent: intentObj.intent,
+                intent: effectiveIntent,
                 keywordWeights: {},
                 maxTokens: 160,
             });
@@ -165,17 +180,525 @@ export class AnalyzeCommand {
         const resultsWithLocation = this.enrichWithLocation(orchestratedResults);
         return {
             schemaVersion: 'v1.0.0',
-            intent: intent,
+            intent: intentObj.intent,
             tool: 'codemap-orchestrated',
             confidence,
             results: resultsWithLocation,
             metadata: {
                 total: orchestratedResults.length,
-                scope,
+                scope: intentObj.scope,
                 resultCount: orchestratedResults.length,
             },
         };
     }
+    /**
+     * 为输出添加兼容期 warning
+     */
+    withCompatibility(output, compatibility) {
+        const warnings = this.buildCompatibilityWarnings(compatibility);
+        if (warnings.length === 0) {
+            return output;
+        }
+        return {
+            ...output,
+            warnings
+        };
+    }
+    /**
+     * 生成结构化兼容 warning
+     */
+    buildCompatibilityWarnings(compatibility) {
+        if (!compatibility?.isDeprecated || !compatibility.normalizedFrom) {
+            return [];
+        }
+        const replacementIntent = compatibility.normalizedFrom === 'search'
+            ? 'find'
+            : compatibility.normalizedFrom === 'impact' || compatibility.normalizedFrom === 'complexity'
+                ? 'read'
+                : compatibility.normalizedFrom === 'dependency' || compatibility.normalizedFrom === 'reference'
+                    ? 'link'
+                    : 'show';
+        return [{
+                code: 'deprecated-intent',
+                severity: 'warning',
+                message: `legacy intent "${compatibility.normalizedFrom}" 已弃用，请改用 "${replacementIntent}"`,
+                deprecatedIntent: compatibility.normalizedFrom,
+                replacementIntent,
+                sunsetPolicy: '2-minor-window'
+            }];
+    }
+    /**
+     * find fallback
+     */
+    async executeFind(intentObj, topK) {
+        const searchTerms = intentObj.keywords.length > 0 ? intentObj.keywords : intentObj.targets;
+        const adapter = new AstGrepAdapter({ includeTests: this.args.includeTests ?? true });
+        const rawResults = await adapter.execute(searchTerms, {
+            topK,
+            includeTests: this.args.includeTests,
+            keywords: searchTerms
+        });
+        const results = this.enrichWithLocation(rawResults).slice(0, topK);
+        const confidence = this.buildConfidence(this.calculateConfidence(results));
+        return this.withCompatibility({
+            schemaVersion: 'v1.0.0',
+            intent: 'find',
+            tool: 'ast-grep-find',
+            confidence,
+            results,
+            metadata: {
+                total: results.length,
+                resultCount: results.length,
+                scope: intentObj.scope
+            }
+        }, intentObj.compatibility);
+    }
+    /**
+     * 执行 read 聚合
+     */
+    async executeRead(intentObj, scope, topK) {
+        const [impactOutput, complexityOutput] = await Promise.all([
+            this.executeImpact(scope, topK),
+            this.executeComplexity(topK)
+        ]);
+        const mergedResults = this.mergeUnifiedResults(impactOutput.results, complexityOutput.results);
+        const results = mergedResults.slice(0, topK);
+        const analysis = {
+            intent: 'read',
+            impact: impactOutput.results
+                .filter(result => result.content.startsWith('被 '))
+                .map(result => ({
+                file: result.file,
+                location: result.location,
+                changedFiles: [result.file],
+                transitiveDependencies: result.metadata?.dependencies ?? [],
+                impactCount: result.metadata?.impactCount ?? 0,
+                risk: result.metadata?.riskLevel ?? 'low'
+            })),
+            complexity: complexityOutput.results
+                .filter(result => Boolean(result.metadata?.complexityMetrics))
+                .map(result => ({
+                file: result.file,
+                location: result.location,
+                metrics: result.metadata?.complexityMetrics ?? {
+                    cyclomatic: 0,
+                    cognitive: 0,
+                    maintainability: 0
+                },
+                risk: result.metadata?.riskLevel ?? 'low'
+            }))
+        };
+        return this.withCompatibility({
+            schemaVersion: 'v1.0.0',
+            intent: 'read',
+            tool: 'codemap-read',
+            confidence: this.combineConfidence([impactOutput.confidence, complexityOutput.confidence], results),
+            results,
+            analysis,
+            metadata: {
+                total: mergedResults.length,
+                resultCount: results.length,
+                scope
+            }
+        }, intentObj.compatibility);
+    }
+    /**
+     * 执行 link 聚合
+     */
+    async executeLink(intentObj, topK) {
+        const dependencyOutput = intentObj.targets.length > 0
+            ? await this.executeDeps(Math.max(topK, intentObj.targets.length))
+            : this.createEmptyOutput('link', 'codemap-link', intentObj.scope);
+        const codeMap = await this.loadCodeMap();
+        const dependency = codeMap
+            ? this.buildLinkDependencyAnalysis(codeMap, intentObj.targets)
+            : [];
+        const reference = codeMap
+            ? this.buildLinkReferenceAnalysis(codeMap, intentObj.targets, intentObj.keywords)
+            : [];
+        const referenceResults = this.buildReferenceResults(reference);
+        const mergedResults = this.mergeUnifiedResults(dependencyOutput.results, referenceResults);
+        const results = mergedResults.slice(0, topK);
+        const confidence = this.combineConfidence([
+            dependencyOutput.confidence,
+            this.buildConfidence(this.calculateConfidence(referenceResults))
+        ], results);
+        const analysis = {
+            intent: 'link',
+            ...(reference.length > 0 ? { reference } : {}),
+            ...(dependency.length > 0 ? { dependency } : {})
+        };
+        return this.withCompatibility({
+            schemaVersion: 'v1.0.0',
+            intent: 'link',
+            tool: 'codemap-link',
+            confidence,
+            results,
+            analysis,
+            metadata: {
+                total: mergedResults.length,
+                resultCount: results.length,
+                scope: intentObj.scope
+            }
+        }, intentObj.compatibility);
+    }
+    /**
+     * 执行 show 聚合
+     */
+    async executeShow(intentObj, topK) {
+        const codeMap = await this.loadCodeMap();
+        const modules = codeMap ? this.findMatchingModules(codeMap, intentObj.targets) : [];
+        const analysis = {
+            intent: 'show',
+            overview: modules.map(module => ({
+                title: path.basename(module.absolutePath),
+                file: this.toRelativePath(codeMap, module.absolutePath),
+                overview: module.overview ?? `模块 ${this.toRelativePath(codeMap, module.absolutePath)}，导出 ${module.exports.length} 个符号，依赖 ${module.dependencies.length} 个模块`,
+                exports: module.exports.map(exp => exp.name)
+            })),
+            documentation: modules.map(module => ({
+                title: path.basename(module.absolutePath),
+                file: this.toRelativePath(codeMap, module.absolutePath),
+                content: module.overview
+                    ?? `类型: ${module.type}; 代码行: ${module.stats.codeLines}; 导出: ${module.exports.map(exp => exp.name).join(', ') || '无'}`
+            }))
+        };
+        const results = this.buildShowResults(analysis).slice(0, topK);
+        return this.withCompatibility({
+            schemaVersion: 'v1.0.0',
+            intent: 'show',
+            tool: 'codemap-show',
+            confidence: this.buildConfidence(this.calculateConfidence(results)),
+            results,
+            analysis,
+            metadata: {
+                total: results.length,
+                resultCount: results.length,
+                scope: intentObj.scope
+            }
+        }, intentObj.compatibility);
+    }
+    /**
+     * 创建空输出
+     */
+    createEmptyOutput(intent, tool, scope) {
+        return {
+            schemaVersion: 'v1.0.0',
+            intent,
+            tool,
+            confidence: this.buildConfidence(0),
+            results: [],
+            metadata: {
+                total: 0,
+                resultCount: 0,
+                scope
+            }
+        };
+    }
+    /**
+     * 聚合多个 Confidence
+     */
+    combineConfidence(confidences, results) {
+        const effective = confidences.filter(confidence => Number.isFinite(confidence.score));
+        if (effective.length === 0) {
+            return this.buildConfidence(this.calculateConfidence(results));
+        }
+        const score = Math.round((effective.reduce((sum, confidence) => sum + confidence.score, 0) / effective.length) * 100) / 100;
+        return this.buildConfidence(score);
+    }
+    /**
+     * 构建 Confidence
+     */
+    buildConfidence(score) {
+        const normalizedScore = Math.round(Math.max(0, Math.min(score, 1)) * 100) / 100;
+        return {
+            score: normalizedScore,
+            level: calculateConfidenceLevel(normalizedScore)
+        };
+    }
+    /**
+     * 合并 UnifiedResult
+     */
+    mergeUnifiedResults(...collections) {
+        const merged = new Map();
+        for (const results of collections) {
+            for (const result of results) {
+                const key = `${result.file}:${result.location?.line ?? result.line ?? 1}`;
+                const existing = merged.get(key);
+                if (!existing || result.relevance > existing.relevance) {
+                    merged.set(key, result);
+                }
+            }
+        }
+        return Array.from(merged.values()).sort((left, right) => right.relevance - left.relevance);
+    }
+    /**
+     * 加载 CodeMap 数据
+     */
+    async loadCodeMap() {
+        try {
+            const dataPath = resolveDataPath();
+            const raw = await readFile(dataPath, 'utf-8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 查找目标模块
+     */
+    findMatchingModules(codeMap, targets) {
+        const seen = new Set();
+        const modules = [];
+        for (const target of targets) {
+            const module = this.findMatchingModule(codeMap, target);
+            if (module && !seen.has(module.id)) {
+                seen.add(module.id);
+                modules.push(module);
+            }
+        }
+        return modules;
+    }
+    /**
+     * 查找单个匹配模块
+     */
+    findMatchingModule(codeMap, target) {
+        return codeMap.modules.find(module => {
+            const relativePath = this.toRelativePath(codeMap, module.absolutePath);
+            return module.absolutePath.includes(target) || relativePath.includes(target);
+        });
+    }
+    /**
+     * 构建 link dependency analysis
+     */
+    buildLinkDependencyAnalysis(codeMap, targets) {
+        return this.findMatchingModules(codeMap, targets).map(module => ({
+            file: this.toRelativePath(codeMap, module.absolutePath),
+            location: {
+                file: this.toRelativePath(codeMap, module.absolutePath),
+                line: 1,
+                column: 1
+            },
+            imports: module.dependencies,
+            importedBy: module.dependents.map(id => {
+                const dependent = codeMap.modules.find(candidate => candidate.id === id);
+                return dependent ? this.toRelativePath(codeMap, dependent.absolutePath) : id;
+            }),
+            cycles: []
+        }));
+    }
+    /**
+     * 构建 link reference analysis
+     */
+    buildLinkReferenceAnalysis(codeMap, targets, keywords) {
+        const items = [];
+        for (const module of this.findMatchingModules(codeMap, targets)) {
+            items.push(this.buildModuleReferenceItem(codeMap, module));
+        }
+        for (const keyword of keywords) {
+            items.push(this.buildKeywordReferenceItem(codeMap, keyword));
+        }
+        const merged = new Map();
+        for (const item of items) {
+            const existing = merged.get(item.target);
+            if (!existing) {
+                merged.set(item.target, item);
+                continue;
+            }
+            merged.set(item.target, {
+                target: item.target,
+                callers: Array.from(new Set([...existing.callers, ...item.callers])),
+                callees: Array.from(new Set([...existing.callees, ...item.callees])),
+                matches: [...existing.matches, ...item.matches]
+            });
+        }
+        return Array.from(merged.values());
+    }
+    /**
+     * 基于模块构建 reference item
+     */
+    buildModuleReferenceItem(codeMap, module) {
+        const relativePath = this.toRelativePath(codeMap, module.absolutePath);
+        const exportedSymbols = new Set(module.exports.map(exp => exp.name));
+        const matchTokens = new Set([
+            relativePath,
+            this.stripModuleExtension(relativePath),
+            path.basename(relativePath),
+            this.stripModuleExtension(path.basename(relativePath)),
+            module.id
+        ]);
+        const callers = new Set();
+        const matches = [];
+        for (const candidate of codeMap.modules) {
+            if (candidate.id === module.id) {
+                continue;
+            }
+            const candidatePath = this.toRelativePath(codeMap, candidate.absolutePath);
+            for (const entry of candidate.imports) {
+                const sourceMatched = this.matchesModuleSource(entry.source, matchTokens);
+                const symbolMatched = entry.specifiers.some(specifier => exportedSymbols.has(specifier.name));
+                if (!sourceMatched && !symbolMatched) {
+                    continue;
+                }
+                callers.add(candidatePath);
+                matches.push({
+                    file: candidatePath,
+                    line: 1,
+                    snippet: entry.source
+                });
+            }
+        }
+        return {
+            target: relativePath,
+            callers: Array.from(callers),
+            callees: module.dependencies,
+            matches
+        };
+    }
+    /**
+     * 基于关键词构建 reference item
+     */
+    buildKeywordReferenceItem(codeMap, keyword) {
+        const callers = new Set();
+        const callees = new Set();
+        const matches = [];
+        for (const module of codeMap.modules) {
+            const relativePath = this.toRelativePath(codeMap, module.absolutePath);
+            const definesKeyword = module.exports.some(exp => exp.name === keyword)
+                || module.symbols.some(symbol => symbol.name === keyword);
+            if (definesKeyword) {
+                callees.add(relativePath);
+            }
+            for (const entry of module.imports) {
+                const sourceMatched = entry.source.toLowerCase().includes(keyword.toLowerCase());
+                const specifierMatched = entry.specifiers.some(specifier => specifier.name === keyword || specifier.alias === keyword);
+                if (!sourceMatched && !specifierMatched) {
+                    continue;
+                }
+                callers.add(relativePath);
+                matches.push({
+                    file: relativePath,
+                    line: 1,
+                    snippet: entry.source
+                });
+            }
+        }
+        return {
+            target: keyword,
+            callers: Array.from(callers),
+            callees: Array.from(callees),
+            matches
+        };
+    }
+    /**
+     * 将 reference analysis 转为 results
+     */
+    buildReferenceResults(items) {
+        return items.map(item => ({
+            id: `reference-${item.target}`,
+            source: 'codemap',
+            toolScore: 0.8,
+            type: 'symbol',
+            file: item.matches[0]?.file ?? item.callees[0] ?? item.target,
+            line: item.matches[0]?.line ?? 1,
+            location: {
+                file: item.matches[0]?.file ?? item.callees[0] ?? item.target,
+                line: item.matches[0]?.line ?? 1,
+                column: 1
+            },
+            content: `发现 ${item.callers.length} 个引用方，${item.callees.length} 个关联目标`,
+            relevance: Math.min(0.4 + item.callers.length * 0.1, 0.95),
+            keywords: [item.target],
+            metadata: {
+                dependencies: item.callees,
+                impactCount: item.callers.length,
+                stability: true,
+                riskLevel: item.callers.length > 10 ? 'high' : item.callers.length > 3 ? 'medium' : 'low'
+            }
+        }));
+    }
+    /**
+     * 构建 show 结果
+     */
+    buildShowResults(analysis) {
+        const results = [];
+        for (const section of analysis.overview ?? []) {
+            results.push({
+                id: `show-overview-${section.file}`,
+                source: 'codemap',
+                toolScore: 0.75,
+                type: 'documentation',
+                file: section.file,
+                line: 1,
+                location: {
+                    file: section.file,
+                    line: 1,
+                    column: 1
+                },
+                content: section.overview,
+                relevance: 0.75,
+                keywords: section.exports,
+                metadata: {
+                    stability: true,
+                    riskLevel: 'low'
+                }
+            });
+        }
+        for (const section of analysis.documentation ?? []) {
+            results.push({
+                id: `show-documentation-${section.file}`,
+                source: 'codemap',
+                toolScore: 0.7,
+                type: 'documentation',
+                file: section.file,
+                line: 1,
+                location: {
+                    file: section.file,
+                    line: 1,
+                    column: 1
+                },
+                content: section.content,
+                relevance: 0.7,
+                keywords: [],
+                metadata: {
+                    stability: true,
+                    riskLevel: 'low'
+                }
+            });
+        }
+        return this.mergeUnifiedResults(results);
+    }
+    /**
+     * 转为相对路径
+     */
+    toRelativePath(codeMap, filePath) {
+        return path.relative(codeMap.project.rootDir, filePath).replace(/\\/g, '/');
+    }
+    /**
+     * 去除模块扩展名
+     */
+    stripModuleExtension(value) {
+        return value.replace(/\.[cm]?[jt]sx?$/i, '');
+    }
+    /**
+     * 判断 import source 是否引用目标模块
+     */
+    matchesModuleSource(source, tokens) {
+        const normalizedSource = this.stripModuleExtension(source).replace(/\\/g, '/').toLowerCase();
+        for (const token of tokens) {
+            const normalizedToken = this.stripModuleExtension(token).replace(/\\/g, '/').toLowerCase();
+            if (!normalizedToken) {
+                continue;
+            }
+            if (normalizedSource === normalizedToken
+                || normalizedSource.endsWith(normalizedToken)
+                || normalizedSource.includes(normalizedToken)) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * 为 UnifiedResult 添加 location 字段
      */
@@ -220,33 +743,16 @@ export class AnalyzeCommand {
         // 添加 location 字段
         const resultsWithLocation = this.enrichWithLocation(resultsWithTests);
         const typedResults = resultsWithLocation;
-        // 输出格式处理
-        if (this.args.outputMode === 'machine' || this.args.json) {
-            return {
-                schemaVersion: 'v1.0.0',
-                intent: 'impact',
-                tool: 'codemap-impact',
-                confidence,
-                results: typedResults.slice(0, topK),
-                metadata: {
-                    total: resultsWithTests.length,
-                    scope,
-                    resultCount: resultsWithTests.length,
-                },
-            };
-        }
-        // 人类可读输出
-        this.printHumanOutput(resultsWithTests, 'impact');
         return {
             schemaVersion: 'v1.0.0',
-            intent: 'impact',
+            intent: 'read',
             tool: 'codemap-impact',
             confidence,
-            results: typedResults,
+            results: typedResults.slice(0, topK),
             metadata: {
                 total: resultsWithTests.length,
                 scope,
-                resultCount: resultsWithTests.length,
+                resultCount: typedResults.slice(0, topK).length,
             },
         };
     }
@@ -284,31 +790,15 @@ export class AnalyzeCommand {
         // 添加 location 字段
         const resultsWithLocation = this.enrichWithLocation(resultsWithTests);
         const typedResults = resultsWithLocation;
-        // 输出格式处理
-        if (this.args.outputMode === 'machine' || this.args.json) {
-            return {
-                schemaVersion: 'v1.0.0',
-                intent: 'dependency',
-                tool: 'codemap-deps',
-                confidence,
-                results: typedResults.slice(0, topK),
-                metadata: {
-                    total: resultsWithTests.length,
-                    resultCount: resultsWithTests.length,
-                },
-            };
-        }
-        // 人类可读输出
-        this.printHumanOutput(resultsWithTests, 'dependency');
         return {
             schemaVersion: 'v1.0.0',
-            intent: 'dependency',
+            intent: 'link',
             tool: 'codemap-deps',
             confidence,
-            results: typedResults,
+            results: typedResults.slice(0, topK),
             metadata: {
                 total: resultsWithTests.length,
-                resultCount: resultsWithTests.length,
+                resultCount: typedResults.slice(0, topK).length,
             },
         };
     }
@@ -332,31 +822,15 @@ export class AnalyzeCommand {
         // 添加 location 字段
         const resultsWithLocation = this.enrichWithLocation(resultsWithTests);
         const typedResults = resultsWithLocation;
-        // 输出格式处理
-        if (this.args.outputMode === 'machine' || this.args.json) {
-            return {
-                schemaVersion: 'v1.0.0',
-                intent: 'complexity',
-                tool: 'codemap-complexity',
-                confidence,
-                results: typedResults.slice(0, topK),
-                metadata: {
-                    total: resultsWithTests.length,
-                    resultCount: resultsWithTests.length,
-                },
-            };
-        }
-        // 人类可读输出
-        this.printHumanOutput(resultsWithTests, 'complexity');
         return {
             schemaVersion: 'v1.0.0',
-            intent: 'complexity',
+            intent: 'read',
             tool: 'codemap-complexity',
             confidence,
-            results: typedResults,
+            results: typedResults.slice(0, topK),
             metadata: {
                 total: resultsWithTests.length,
-                resultCount: resultsWithTests.length,
+                resultCount: typedResults.slice(0, topK).length,
             },
         };
     }
@@ -400,68 +874,31 @@ export class AnalyzeCommand {
 /**
  * 解析 CLI 参数
  */
+function normalizeStringArray(value) {
+    if (typeof value === 'string') {
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === 'string');
+    }
+    return [];
+}
 export function parseAnalyzeArgs(argv) {
     try {
         const { values, positionals } = parseArgs({
-            argv,
+            args: argv,
             allowPositionals: true,
-            options: {
-                intent: {
-                    type: 'string',
-                    short: 'i',
-                },
-                targets: {
-                    type: 'string',
-                    multiple: true,
-                    short: 't',
-                },
-                keywords: {
-                    type: 'string',
-                    multiple: true,
-                    short: 'k',
-                },
-                scope: {
-                    type: 'string',
-                    short: 's',
-                },
-                topK: {
-                    type: 'string',
-                    short: 'n',
-                },
-                'include-tests': {
-                    type: 'boolean',
-                    default: false,
-                },
-                'include-git-history': {
-                    type: 'boolean',
-                    default: false,
-                },
-                json: {
-                    type: 'boolean',
-                    default: false,
-                },
-                structured: {
-                    type: 'boolean',
-                    default: false,
-                },
-                'output-mode': {
-                    type: 'string',
-                },
-                help: {
-                    type: 'boolean',
-                    short: 'h',
-                    default: false,
-                },
-            },
+            options: ANALYZE_PARSE_OPTIONS,
         });
         // 合并位置参数和 --targets 参数作为 targets
         const positionalTargets = positionals?.filter(p => !p.startsWith('-')) || [];
-        const explicitTargets = values.targets ? (Array.isArray(values.targets) ? values.targets : [values.targets]) : [];
+        const explicitTargets = normalizeStringArray(values.targets);
         const allTargets = [...explicitTargets, ...positionalTargets];
+        const keywords = normalizeStringArray(values.keywords);
         return {
             intent: values.intent,
             targets: allTargets.length > 0 ? allTargets : undefined,
-            keywords: values.keywords,
+            keywords: keywords.length > 0 ? keywords : undefined,
             scope: values.scope,
             topK: values.topK ? parseInt(values.topK, 10) : undefined,
             includeTests: values['include-tests'],
@@ -510,6 +947,9 @@ export async function analyzeCommand(argv) {
         else {
             // human 模式：打印格式化输出
             const typedOutput = output;
+            for (const warning of typedOutput.warnings || []) {
+                console.warn(chalk.yellow(`⚠️  ${warning.message}`));
+            }
             console.log(chalk.bold(`\n📊 ${typedOutput.intent?.toUpperCase() || 'ANALYSIS'} 分析结果\n`));
             for (const result of typedOutput.results || []) {
                 const lineInfo = result.location?.line ? `:${result.location.line}` : '';
@@ -538,30 +978,6 @@ export async function analyzeCommand(argv) {
  * 打印帮助信息
  */
 function printHelp() {
-    console.log(`
-${chalk.bold('codemap analyze')} - 统一分析入口
-
-${chalk.bold('用法:')}
-  codemap analyze [选项]
-
-${chalk.bold('选项:')}
-  -i, --intent <type>          分析类型 (impact|dependency|search|documentation|complexity|overview|refactor|reference)
-  -t, --targets <paths>       目标文件/模块路径 (多个)
-  -k, --keywords <words>      搜索关键词 (多个)
-  -s, --scope <scope>         范围 (direct|transitive)
-  -n, --topK <number>        返回结果数量 (默认 8, 最大 100)
-  --include-tests             包含测试文件
-  --include-git-history       包含 Git 历史
-  --json                     JSON 格式输出
-  --structured               输出完全结构化的 JSON（移除自然语言字符串）
-  --output-mode <mode>       输出模式 (machine|human)
-  -h, --help                 显示帮助
-
-${chalk.bold('示例:')}
-  codemap analyze -i impact -t src/index.ts
-  codemap analyze -i dependency -t src/utils --scope transitive --json
-  codemap analyze -i complexity -t src/ --include-tests
-  codemap analyze -i search -k "SourceLocation" --json --structured
-`);
+    console.log(getAnalyzeHelpText());
 }
 //# sourceMappingURL=analyze.js.map