agent-ide 0.7.5 → 0.8.0

package/dist/plugins/shared/constants.js

@@ -0,0 +1,78 @@
+/**
+ * Parser 共用常數
+ * TypeScript 和 JavaScript Parser 共享的設定值
+ */
+/**
+ * 行號匹配的容差值（允許 JSDoc 造成的偏移）
+ * JSDoc 可能跨越多行，因此需要容差來正確匹配目標宣告
+ */
+export const LINE_TOLERANCE = 10;
+/**
+ * 通用排除模式（適用於所有語言）
+ */
+export const COMMON_EXCLUDE_PATTERNS = [
+    'node_modules/**',
+    '.git/**',
+    'dist/**',
+    'build/**',
+    'coverage/**',
+    '.next/**',
+    '.nuxt/**',
+    'out/**',
+    '.cache/**',
+    '.turbo/**'
+];
+/**
+ * TypeScript 特定排除模式
+ */
+export const TYPESCRIPT_EXCLUDE_PATTERNS = [
+    ...COMMON_EXCLUDE_PATTERNS,
+    '**/*.test.ts',
+    '**/*.spec.ts',
+    '**/*.test.tsx',
+    '**/*.spec.tsx',
+    '**/__tests__/**',
+    '**/__mocks__/**',
+    '**/*.d.ts'
+];
+/**
+ * JavaScript 特定排除模式
+ */
+export const JAVASCRIPT_EXCLUDE_PATTERNS = [
+    ...COMMON_EXCLUDE_PATTERNS,
+    '**/*.test.js',
+    '**/*.spec.js',
+    '**/*.test.jsx',
+    '**/*.spec.jsx',
+    '**/*.test.mjs',
+    '**/*.spec.mjs',
+    '**/*.test.cjs',
+    '**/*.spec.cjs',
+    '**/__tests__/**',
+    '**/__mocks__/**'
+];
+/**
+ * Factory 模式識別的回傳型別排除清單
+ * 這些型別不視為 factory 模式的產物
+ */
+export const NON_FACTORY_RETURN_TYPES = [
+    'void',
+    'never',
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'undefined',
+    'symbol',
+    'bigint'
+];
+/**
+ * Factory 模式函數名稱前綴
+ * 符合這些前綴的函數更可能是 factory
+ */
+export const FACTORY_NAME_PREFIXES = [
+    'create',
+    'make',
+    'build'
+];
+//# sourceMappingURL=constants.js.map

package/dist/plugins/shared/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/plugins/shared/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,iBAAiB;IACjB,SAAS;IACT,SAAS;IACT,UAAU;IACV,aAAa;IACb,UAAU;IACV,UAAU;IACV,QAAQ;IACR,WAAW;IACX,WAAW;CACH,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,GAAG,uBAAuB;IAC1B,cAAc;IACd,cAAc;IACd,eAAe;IACf,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,WAAW;CACH,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,GAAG,uBAAuB;IAC1B,cAAc;IACd,cAAc;IACd,eAAe;IACf,eAAe;IACf,eAAe;IACf,eAAe;IACf,eAAe;IACf,eAAe;IACf,iBAAiB;IACjB,iBAAiB;CACT,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,MAAM;IACN,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,MAAM;IACN,WAAW;IACX,QAAQ;IACR,QAAQ;CACA,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,QAAQ;IACR,MAAM;IACN,OAAO;CACC,CAAC"}

package/dist/plugins/shared/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parser 共用模組
+ * 提供 TypeScript 和 JavaScript Parser 共享的常數和輔助函數
+ */
+export { LINE_TOLERANCE, COMMON_EXCLUDE_PATTERNS, TYPESCRIPT_EXCLUDE_PATTERNS, JAVASCRIPT_EXCLUDE_PATTERNS, NON_FACTORY_RETURN_TYPES, FACTORY_NAME_PREFIXES } from './constants.js';
+export { isLineMatch, isFactoryReturnType, calculateFactoryConfidence, createFactoryPatternInfo, parseJSDocContent, createDocumentation, createFormattedParameter, createEmptyRange, isRelativePath, UNICODE_IDENTIFIER_PATTERN, isValidUnicodeIdentifier, matchesAnyPattern } from './parser-helpers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/shared/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/shared/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,wBAAwB,EACxB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC"}

package/dist/plugins/shared/index.js

@@ -0,0 +1,9 @@
+/**
+ * Parser 共用模組
+ * 提供 TypeScript 和 JavaScript Parser 共享的常數和輔助函數
+ */
+// 常數
+export { LINE_TOLERANCE, COMMON_EXCLUDE_PATTERNS, TYPESCRIPT_EXCLUDE_PATTERNS, JAVASCRIPT_EXCLUDE_PATTERNS, NON_FACTORY_RETURN_TYPES, FACTORY_NAME_PREFIXES } from './constants.js';
+// 輔助函數
+export { isLineMatch, isFactoryReturnType, calculateFactoryConfidence, createFactoryPatternInfo, parseJSDocContent, createDocumentation, createFormattedParameter, createEmptyRange, isRelativePath, UNICODE_IDENTIFIER_PATTERN, isValidUnicodeIdentifier, matchesAnyPattern } from './parser-helpers.js';
+//# sourceMappingURL=index.js.map

package/dist/plugins/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/shared/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,KAAK;AACL,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,wBAAwB,EACxB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO;AACP,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,wBAAwB,EACxB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC"}

package/dist/plugins/shared/parser-helpers.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Parser 共用輔助函數
+ * TypeScript 和 JavaScript Parser 共享的邏輯
+ */
+import type { Range } from '../../shared/types/core.js';
+import type { Documentation, DocumentationTag, PatternInfo, FormattedParameter } from '../../infrastructure/parser/index.js';
+/**
+ * 檢查節點行號是否匹配目標行號
+ * 允許 JSDoc 造成的偏移
+ *
+ * @param nodeStartLine 節點起始行（1-based）
+ * @param targetLine 目標行（1-based）
+ * @returns 是否匹配
+ */
+export declare function isLineMatch(nodeStartLine: number, targetLine: number): boolean;
+/**
+ * 判斷回傳型別是否符合 factory 模式
+ * 排除 void、never、基本型別、Promise<void> 等
+ *
+ * @param typeName 型別名稱
+ * @returns 是否可能是 factory 回傳型別
+ */
+export declare function isFactoryReturnType(typeName: string): boolean;
+/**
+ * 計算 factory 模式的信心度
+ *
+ * @param functionName 函數名稱
+ * @param returnType 回傳型別（可選，JavaScript 沒有型別）
+ * @param hasNewExpression 是否有 new 表達式
+ * @param hasObjectReturn 是否回傳物件字面量
+ * @returns 信心度 (0-1)
+ */
+export declare function calculateFactoryConfidence(functionName: string, returnType: string | undefined, hasNewExpression: boolean, hasObjectReturn: boolean): number;
+/**
+ * 建立 PatternInfo 物件
+ *
+ * @param symbolName 符號名稱
+ * @param confidence 信心度
+ * @param producedType 產生的型別（可選）
+ * @returns PatternInfo 物件
+ */
+export declare function createFactoryPatternInfo(symbolName: string, confidence: number, producedType?: string): PatternInfo;
+/**
+ * 解析 JSDoc 內容
+ * 從原始 JSDoc 文字中提取描述和標籤
+ *
+ * @param content JSDoc 內容（不含 /** 和 * /）
+ * @returns 解析後的描述和標籤
+ */
+export declare function parseJSDocContent(content: string): {
+    description?: string;
+    tags: DocumentationTag[];
+};
+/**
+ * 建立 Documentation 物件
+ *
+ * @param rawText 原始 JSDoc 文字
+ * @param description 描述
+ * @param tags 標籤列表
+ * @returns Documentation 物件，如果無內容則返回 null
+ */
+export declare function createDocumentation(rawText: string, description?: string, tags?: DocumentationTag[]): Documentation | null;
+/**
+ * 建立 FormattedParameter 物件
+ *
+ * @param name 參數名稱
+ * @param type 參數型別（JavaScript 預設為 'any'）
+ * @param optional 是否可選
+ * @param defaultValue 預設值
+ * @returns FormattedParameter 物件
+ */
+export declare function createFormattedParameter(name: string, type?: string, optional?: boolean, defaultValue?: string): FormattedParameter;
+/**
+ * 建立空 Range（用於錯誤情況）
+ */
+export declare function createEmptyRange(): Range;
+/**
+ * 檢查路徑是否為相對路徑
+ * 相對路徑以 ./ 或 ../ 開頭
+ *
+ * @param path 路徑字串
+ * @returns 是否為相對路徑
+ */
+export declare function isRelativePath(path: string): boolean;
+/**
+ * 預編譯的 Unicode 識別符正則表達式
+ * 符合 UAX #31 標準：
+ * - 第一個字元：Unicode 類別 ID_Start、底線、或 $
+ * - 後續字元：Unicode 類別 ID_Continue 或 $
+ */
+export declare const UNICODE_IDENTIFIER_PATTERN: RegExp;
+/**
+ * 檢查名稱是否符合 Unicode 識別符格式
+ * 不包含保留字檢查，僅驗證格式
+ *
+ * @param name 識別符名稱
+ * @returns 是否符合格式
+ */
+export declare function isValidUnicodeIdentifier(name: string): boolean;
+/**
+ * 檢查檔案路徑是否匹配任一模式
+ * 使用簡單的字串匹配，不依賴外部 glob 套件
+ *
+ * @param filePath 檔案路徑
+ * @param patterns 模式列表
+ * @returns 是否匹配
+ */
+export declare function matchesAnyPattern(filePath: string, patterns: readonly string[]): boolean;
+//# sourceMappingURL=parser-helpers.d.ts.map

package/dist/plugins/shared/parser-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser-helpers.d.ts","sourceRoot":"","sources":["../../../src/plugins/shared/parser-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAY,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EACnB,MAAM,iCAAiC,CAAC;AAOzC;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAmB7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,gBAAgB,EAAE,OAAO,EACzB,eAAe,EAAE,OAAO,GACvB,MAAM,CAyBR;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,WAAW,CAOb;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,gBAAgB,EAAE,CAAC;CAC1B,CA4BA;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,gBAAgB,EAAE,GACxB,aAAa,GAAG,IAAI,CAUtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAc,EACpB,QAAQ,GAAE,OAAe,EACzB,YAAY,CAAC,EAAE,MAAM,GACpB,kBAAkB,CAOpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,KAAK,CAGxC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAA2C,CAAC;AAEnF;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA2BxF"}

package/dist/plugins/shared/parser-helpers.js

@@ -0,0 +1,223 @@
+/**
+ * Parser 共用輔助函數
+ * TypeScript 和 JavaScript Parser 共享的邏輯
+ */
+import { LINE_TOLERANCE, NON_FACTORY_RETURN_TYPES, FACTORY_NAME_PREFIXES } from './constants.js';
+/**
+ * 檢查節點行號是否匹配目標行號
+ * 允許 JSDoc 造成的偏移
+ *
+ * @param nodeStartLine 節點起始行（1-based）
+ * @param targetLine 目標行（1-based）
+ * @returns 是否匹配
+ */
+export function isLineMatch(nodeStartLine, targetLine) {
+    return Math.abs(nodeStartLine - targetLine) <= LINE_TOLERANCE;
+}
+/**
+ * 判斷回傳型別是否符合 factory 模式
+ * 排除 void、never、基本型別、Promise<void> 等
+ *
+ * @param typeName 型別名稱
+ * @returns 是否可能是 factory 回傳型別
+ */
+export function isFactoryReturnType(typeName) {
+    const normalizedType = typeName.trim().toLowerCase();
+    // 排除基本排除型別
+    if (NON_FACTORY_RETURN_TYPES.includes(normalizedType)) {
+        return false;
+    }
+    // 排除 Promise<void>
+    if (/^promise\s*<\s*void\s*>$/i.test(typeName)) {
+        return false;
+    }
+    // 排除純陣列基本型別
+    if (/^(string|number|boolean)\[\]$/.test(normalizedType)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * 計算 factory 模式的信心度
+ *
+ * @param functionName 函數名稱
+ * @param returnType 回傳型別（可選，JavaScript 沒有型別）
+ * @param hasNewExpression 是否有 new 表達式
+ * @param hasObjectReturn 是否回傳物件字面量
+ * @returns 信心度 (0-1)
+ */
+export function calculateFactoryConfidence(functionName, returnType, hasNewExpression, hasObjectReturn) {
+    let confidence = 0;
+    // 名稱前綴權重
+    const nameWeight = returnType ? 0.3 : 0.4; // JavaScript 沒有型別，名稱權重較高
+    if (FACTORY_NAME_PREFIXES.some(prefix => functionName.toLowerCase().startsWith(prefix))) {
+        confidence += nameWeight;
+    }
+    // 回傳型別權重（僅 TypeScript）
+    if (returnType && returnType !== 'any') {
+        confidence += 0.3;
+    }
+    // Factory 行為權重
+    if (hasNewExpression) {
+        confidence += 0.4;
+    }
+    if (hasObjectReturn) {
+        confidence += 0.3;
+    }
+    return Math.min(confidence, 1);
+}
+/**
+ * 建立 PatternInfo 物件
+ *
+ * @param symbolName 符號名稱
+ * @param confidence 信心度
+ * @param producedType 產生的型別（可選）
+ * @returns PatternInfo 物件
+ */
+export function createFactoryPatternInfo(symbolName, confidence, producedType) {
+    return {
+        type: 'factory',
+        symbolName,
+        confidence,
+        metadata: producedType ? { producedType } : undefined
+    };
+}
+/**
+ * 解析 JSDoc 內容
+ * 從原始 JSDoc 文字中提取描述和標籤
+ *
+ * @param content JSDoc 內容（不含 /** 和 * /）
+ * @returns 解析後的描述和標籤
+ */
+export function parseJSDocContent(content) {
+    const lines = content.split('\n');
+    const tags = [];
+    const descriptionLines = [];
+    let inDescription = true;
+    for (const line of lines) {
+        // 移除行首的 * 和空白
+        const trimmedLine = line.replace(/^\s*\*\s?/, '').trim();
+        // 檢查是否為標籤行
+        const tagMatch = trimmedLine.match(/^@(\w+)\s*(.*)?$/);
+        if (tagMatch) {
+            inDescription = false;
+            const tagName = tagMatch[1];
+            const tagText = tagMatch[2]?.trim() ?? '';
+            tags.push({ name: tagName, text: tagText });
+        }
+        else if (inDescription && trimmedLine) {
+            descriptionLines.push(trimmedLine);
+        }
+    }
+    const description = descriptionLines.length > 0
+        ? descriptionLines.join(' ').trim()
+        : undefined;
+    return { description, tags };
+}
+/**
+ * 建立 Documentation 物件
+ *
+ * @param rawText 原始 JSDoc 文字
+ * @param description 描述
+ * @param tags 標籤列表
+ * @returns Documentation 物件，如果無內容則返回 null
+ */
+export function createDocumentation(rawText, description, tags) {
+    if (!rawText.trim()) {
+        return null;
+    }
+    return {
+        rawText,
+        description,
+        tags: tags ?? []
+    };
+}
+/**
+ * 建立 FormattedParameter 物件
+ *
+ * @param name 參數名稱
+ * @param type 參數型別（JavaScript 預設為 'any'）
+ * @param optional 是否可選
+ * @param defaultValue 預設值
+ * @returns FormattedParameter 物件
+ */
+export function createFormattedParameter(name, type = 'any', optional = false, defaultValue) {
+    return {
+        name,
+        type,
+        optional,
+        defaultValue
+    };
+}
+/**
+ * 建立空 Range（用於錯誤情況）
+ */
+export function createEmptyRange() {
+    const emptyPosition = { line: 0, column: 0, offset: 0 };
+    return { start: emptyPosition, end: emptyPosition };
+}
+/**
+ * 檢查路徑是否為相對路徑
+ * 相對路徑以 ./ 或 ../ 開頭
+ *
+ * @param path 路徑字串
+ * @returns 是否為相對路徑
+ */
+export function isRelativePath(path) {
+    return path.startsWith('./') || path.startsWith('../');
+}
+/**
+ * 預編譯的 Unicode 識別符正則表達式
+ * 符合 UAX #31 標準：
+ * - 第一個字元：Unicode 類別 ID_Start、底線、或 $
+ * - 後續字元：Unicode 類別 ID_Continue 或 $
+ */
+export const UNICODE_IDENTIFIER_PATTERN = /^[\p{ID_Start}_$][\p{ID_Continue}$]*$/u;
+/**
+ * 檢查名稱是否符合 Unicode 識別符格式
+ * 不包含保留字檢查，僅驗證格式
+ *
+ * @param name 識別符名稱
+ * @returns 是否符合格式
+ */
+export function isValidUnicodeIdentifier(name) {
+    if (!name || name.length === 0) {
+        return false;
+    }
+    return UNICODE_IDENTIFIER_PATTERN.test(name);
+}
+/**
+ * 檢查檔案路徑是否匹配任一模式
+ * 使用簡單的字串匹配，不依賴外部 glob 套件
+ *
+ * @param filePath 檔案路徑
+ * @param patterns 模式列表
+ * @returns 是否匹配
+ */
+export function matchesAnyPattern(filePath, patterns) {
+    const normalizedPath = filePath.replace(/^\.?\//, '');
+    return patterns.some(pattern => {
+        try {
+            // 直接使用字串包含檢查來提高效能
+            if (pattern.includes('**')) {
+                // 對於包含 ** 的模式，進行簡單的子字串匹配
+                const simplePattern = pattern.replace(/\*\*/g, '').replace(/\//g, '');
+                if (normalizedPath.includes(simplePattern)) {
+                    return true;
+                }
+            }
+            // 檢查檔案路徑是否匹配模式
+            if (pattern.startsWith('**/')) {
+                const suffix = pattern.substring(3);
+                if (normalizedPath.endsWith(suffix) || normalizedPath.includes('/' + suffix)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+//# sourceMappingURL=parser-helpers.js.map

package/dist/plugins/shared/parser-helpers.js.map

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

package/dist/plugins/typescript/declaration-analyzer.d.ts

@@ -0,0 +1,123 @@
+/**
+ * TypeScript 宣告分析器
+ * 負責解析宣告範圍、import 宣告、函數簽章和 JSDoc 文件
+ */
+import * as ts from 'typescript';
+import type { ImportDeclaration, FormattedSignature, FormattedParameter, Documentation } from '../../infrastructure/parser/index.js';
+import type { Range } from '../../shared/types/index.js';
+/**
+ * 宣告分析器類別
+ * 提供 TypeScript 程式碼的宣告解析功能
+ */
+export declare class DeclarationAnalyzer {
+    private readonly compilerOptions?;
+    /**
+     * 建立宣告分析器實例
+     * @param compilerOptions TypeScript 編譯器選項
+     */
+    constructor(compilerOptions?: ts.CompilerOptions | undefined);
+    /**
+     * 取得完整宣告範圍（包含前導註解）
+     * @param code 原始程式碼
+     * @param symbolName 符號名稱
+     * @param symbolType 符號類型
+     * @param startLine 起始行號（1-based）
+     * @returns 完整範圍或 null
+     */
+    getFullDeclarationRange(code: string, symbolName: string, symbolType: string, startLine: number): Range | null;
+    /**
+     * 在 AST 中尋找符合條件的宣告節點
+     * @param sourceFile TypeScript SourceFile
+     * @param symbolName 符號名稱
+     * @param symbolType 符號類型
+     * @param startLine 起始行號（1-based）
+     * @returns 符合條件的節點或 null
+     */
+    findDeclarationNode(sourceFile: ts.SourceFile, symbolName: string, symbolType: string, startLine: number): ts.Node | null;
+    /**
+     * 檢查節點是否符合目標宣告
+     * @param node AST 節點
+     * @param symbolName 符號名稱
+     * @param symbolType 符號類型
+     * @param nodeStartLine 節點起始行號
+     * @param targetStartLine 目標起始行號
+     * @returns 是否符合
+     */
+    isMatchingDeclaration(node: ts.Node, symbolName: string, symbolType: string, nodeStartLine: number, targetStartLine: number): boolean;
+    /**
+     * 解析程式碼中的所有 import 宣告
+     * 使用 TypeScript Compiler API 精確解析
+     * @param code 原始程式碼
+     * @returns import 宣告陣列或 null
+     */
+    getImportDeclarations(code: string): ImportDeclaration[] | null;
+    /**
+     * 解析單個 import 宣告節點
+     * @param node import 宣告節點
+     * @param sourceFile TypeScript SourceFile
+     * @param code 原始程式碼
+     * @returns ImportDeclaration 或 null
+     */
+    parseImportDeclaration(node: ts.ImportDeclaration, sourceFile: ts.SourceFile, code: string): ImportDeclaration | null;
+    /**
+     * 格式化函數簽章
+     * 使用 TypeScript Compiler API 精確解析，正確處理複雜泛型巢狀
+     * @param code 原始程式碼
+     * @param functionName 函數名稱
+     * @param line 行號（1-based）
+     * @returns 格式化簽章或 null
+     */
+    formatSignature(code: string, functionName: string, line: number): FormattedSignature | null;
+    /**
+     * 尋找符合條件的函數節點
+     * @param sourceFile TypeScript SourceFile
+     * @param functionName 函數名稱
+     * @param targetLine 目標行號（1-based）
+     * @returns 函數節點或 null
+     */
+    findFunctionNode(sourceFile: ts.SourceFile, functionName: string, targetLine: number): ts.FunctionDeclaration | ts.MethodDeclaration | ts.ArrowFunction | null;
+    /**
+     * 提取函數參數
+     * @param node 函數節點
+     * @param sourceFile TypeScript SourceFile
+     * @returns 格式化參數陣列
+     */
+    extractParameters(node: ts.FunctionDeclaration | ts.MethodDeclaration | ts.ArrowFunction, sourceFile: ts.SourceFile): FormattedParameter[];
+    /**
+     * 提取函數回傳型別
+     * @param node 函數節點
+     * @param sourceFile TypeScript SourceFile
+     * @returns 回傳型別字串
+     */
+    extractReturnType(node: ts.FunctionDeclaration | ts.MethodDeclaration | ts.ArrowFunction, sourceFile: ts.SourceFile): string;
+    /**
+     * 提取泛型參數
+     * @param node 函數節點
+     * @returns 泛型參數名稱陣列
+     */
+    extractTypeParameters(node: ts.FunctionDeclaration | ts.MethodDeclaration | ts.ArrowFunction): string[];
+    /**
+     * 提取符號的 JSDoc 文件註解
+     * 使用 TypeScript Compiler API 精確識別屬於該節點的 JSDoc
+     * @param code 原始程式碼
+     * @param symbolName 符號名稱
+     * @param symbolType 符號類型
+     * @param line 行號（1-based）
+     * @returns Documentation 或 null
+     */
+    getDocumentation(code: string, symbolName: string, symbolType: string, line: number): Documentation | null;
+    /**
+     * 提取 JSDoc 標籤的文字內容
+     * @param tag JSDoc 標籤節點
+     * @param sourceFile TypeScript SourceFile
+     * @returns 標籤文字
+     */
+    extractJSDocTagText(tag: ts.JSDocTag, sourceFile: ts.SourceFile): string;
+}
+/**
+ * 建立宣告分析器實例
+ * @param compilerOptions TypeScript 編譯器選項
+ * @returns DeclarationAnalyzer 實例
+ */
+export declare function createDeclarationAnalyzer(compilerOptions?: ts.CompilerOptions): DeclarationAnalyzer;
+//# sourceMappingURL=declaration-analyzer.d.ts.map

package/dist/plugins/typescript/declaration-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration-analyzer.d.ts","sourceRoot":"","sources":["../../../src/plugins/typescript/declaration-analyzer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,KAAK,EACV,iBAAiB,EAEjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EAEd,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAGpD;;;GAGG;AACH,qBAAa,mBAAmB;IAKlB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC;IAJ7C;;;OAGG;gBAC0B,eAAe,CAAC,EAAE,EAAE,CAAC,eAAe,YAAA;IAEjE;;;;;;;OAOG;IACH,uBAAuB,CACrB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,KAAK,GAAG,IAAI;IA0Cf;;;;;;;OAOG;IACH,mBAAmB,CACjB,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,EAAE,CAAC,IAAI,GAAG,IAAI;IAoBjB;;;;;;;;OAQG;IACH,qBAAqB,CACnB,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,GACtB,OAAO;IAuEV;;;;;OAKG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,GAAG,IAAI;IA2B/D;;;;;;OAMG;IACH,sBAAsB,CACpB,IAAI,EAAE,EAAE,CAAC,iBAAiB,EAC1B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,IAAI;IAmE3B;;;;;;;OAOG;IACH,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,kBAAkB,GAAG,IAAI;IA6B5B;;;;;;OAMG;IACH,gBAAgB,CACd,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,EAAE,CAAC,mBAAmB,GAAG,EAAE,CAAC,iBAAiB,GAAG,EAAE,CAAC,aAAa,GAAG,IAAI;IA2C1E;;;;;OAKG;IACH,iBAAiB,CACf,IAAI,EAAE,EAAE,CAAC,mBAAmB,GAAG,EAAE,CAAC,iBAAiB,GAAG,EAAE,CAAC,aAAa,EACtE,UAAU,EAAE,EAAE,CAAC,UAAU,GACxB,kBAAkB,EAAE;IA+BvB;;;;;OAKG;IACH,iBAAiB,CACf,IAAI,EAAE,EAAE,CAAC,mBAAmB,GAAG,EAAE,CAAC,iBAAiB,GAAG,EAAE,CAAC,aAAa,EACtE,UAAU,EAAE,EAAE,CAAC,UAAU,GACxB,MAAM;IAOT;;;;OAIG;IACH,qBAAqB,CACnB,IAAI,EAAE,EAAE,CAAC,mBAAmB,GAAG,EAAE,CAAC,iBAAiB,GAAG,EAAE,CAAC,aAAa,GACrE,MAAM,EAAE;IAQX;;;;;;;;OAQG;IACH,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,aAAa,GAAG,IAAI;IAmEvB;;;;;OAKG;IACH,mBAAmB,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,MAAM;CAwBzE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,eAAe,CAAC,EAAE,EAAE,CAAC,eAAe,GAAG,mBAAmB,CAEnG"}