autosnippet 3.2.10 → 3.2.12

package/dist/lib/service/wiki/WikiUtils.js

@@ -0,0 +1,971 @@
+/**
+ * WikiUtils.js — Wiki 生成器工具函数
+ *
+ * 从 WikiGenerator.js 中提取的纯工具/辅助函数，无 class 依赖。
+ *
+ * @module WikiUtils
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import Logger from '../../infrastructure/logging/Logger.js';
+import { LanguageService } from '../../shared/LanguageService.js';
+const logger = Logger.getInstance();
+// ─── 工具函数 ────────────────────────────────────────────────
+/**
+ * 文本 slug 化
+ */
+export function slug(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase();
+}
+/**
+ * Mermaid 安全 ID
+ */
+export function mermaidId(name) {
+    return name.replace(/[^a-zA-Z0-9]/g, '_');
+}
+/**
+ * 遍历目录（排除 build/Pods/DerivedData 等）
+ */
+export function walkDir(dir, callback, maxFiles = 500) {
+    const excludeNames = new Set([
+        'Pods',
+        'Carthage',
+        'node_modules',
+        '.build',
+        'build',
+        'DerivedData',
+        'vendor',
+        '.git',
+        '__tests__',
+        'Tests',
+        'AutoSnippet',
+        '.cursor',
+    ]);
+    let count = 0;
+    const walk = (d) => {
+        if (count >= maxFiles) {
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (count >= maxFiles) {
+                return;
+            }
+            if (excludeNames.has(entry.name)) {
+                continue;
+            }
+            if (entry.name.startsWith('.')) {
+                continue;
+            }
+            const fullPath = path.join(d, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                callback(fullPath);
+                count++;
+            }
+        }
+    };
+    walk(dir);
+}
+/**
+ * 从文件相对路径推断所属模块名
+ * 支持多种项目结构约定:
+ *   SPM:     Sources/{ModuleName}/...
+ *   Node.js: packages/{name}/... | src/{name}/... | lib/{name}/...
+ *   Go:      pkg/{name}/... | internal/{name}/... | cmd/{name}/...
+ *   Rust:    crates/{name}/... | src/ (单 crate)
+ *   Python:  src/{name}/... | {name}/ (顶层包)
+ *   Java/Kt: src/main/java/{pkg}/... (取第一个包段)
+ *   Dart:    lib/{name}/...
+ *
+ * 兜底: 取第一级目录名
+ */
+export function inferModuleFromPath(filePath) {
+    const parts = filePath.split('/');
+    // SPM: Sources/{Module}/...
+    const sourcesIdx = parts.indexOf('Sources');
+    if (sourcesIdx >= 0 && sourcesIdx + 1 < parts.length) {
+        return parts[sourcesIdx + 1];
+    }
+    // Node.js monorepo: packages/{name}/... | apps/{name}/...
+    for (const dir of ['packages', 'apps', 'modules']) {
+        const idx = parts.indexOf(dir);
+        if (idx >= 0 && idx + 1 < parts.length) {
+            return parts[idx + 1];
+        }
+    }
+    // Go: pkg/{name}/... | internal/{name}/... | cmd/{name}/...
+    for (const dir of ['pkg', 'internal', 'cmd']) {
+        const idx = parts.indexOf(dir);
+        if (idx >= 0 && idx + 1 < parts.length) {
+            return parts[idx + 1];
+        }
+    }
+    // Rust: crates/{name}/...
+    const cratesIdx = parts.indexOf('crates');
+    if (cratesIdx >= 0 && cratesIdx + 1 < parts.length) {
+        return parts[cratesIdx + 1];
+    }
+    // Java/Kotlin: src/main/java/{pkg}/... → 跳过域名前缀，取最后一个有意义的包目录
+    //   例: src/main/java/org/springframework/samples/petclinic/vet/Vet.java → "vet"
+    //   例: src/main/java/com/example/demo/DemoApp.java → "demo"
+    for (const langDir of ['java', 'kotlin']) {
+        const langIdx = parts.indexOf(langDir);
+        if (langIdx >= 0 && langIdx + 1 < parts.length) {
+            // 文件名所在目录（倒数第二个 part）才是 "模块"
+            const pkgParts = parts.slice(langIdx + 1, parts.length - 1); // 包路径（不含文件名）
+            if (pkgParts.length >= 2) {
+                // 从尾部取: 最后一个包段即为功能模块
+                return pkgParts[pkgParts.length - 1];
+            }
+            if (pkgParts.length === 1) {
+                return pkgParts[0];
+            }
+            // 只有文件直接在 java/ 下
+            return parts[langIdx + 1];
+        }
+    }
+    // Generic: src/{name}/... | lib/{name}/... (至少 3 层深时)
+    for (const dir of ['src', 'lib']) {
+        const idx = parts.indexOf(dir);
+        if (idx >= 0 && idx + 1 < parts.length && parts.length > idx + 2) {
+            return parts[idx + 1];
+        }
+    }
+    // 兜底: 取第一级目录名
+    return parts.length > 1 ? parts[0] : null;
+}
+/**
+ * 获取某个 Target 对应的源文件列表
+ * 按优先级匹配: target.path → target.info.path → sourceFilesByModule[name]
+ */
+export function getModuleSourceFiles(target, projectInfo) {
+    const sfm = projectInfo.sourceFilesByModule || {};
+    const name = target.name;
+    // 1. 按模块名直接匹配（最常见: Sources/{name}/ 解析出的 key）
+    if (sfm[name]?.length > 0) {
+        return sfm[name];
+    }
+    // 2. 通过 target.path 或 target.info.path 匹配
+    const targetPath = target.path || target.info?.path;
+    if (targetPath) {
+        const matched = (projectInfo.sourceFiles || []).filter((f) => f.startsWith(`${targetPath}/`) || f.startsWith(targetPath + path.sep));
+        if (matched.length > 0) {
+            return matched;
+        }
+    }
+    // 3. 大小写不敏感模糊匹配
+    const lower = name.toLowerCase();
+    for (const [key, files] of Object.entries(sfm)) {
+        if (key.toLowerCase() === lower) {
+            return files;
+        }
+    }
+    return [];
+}
+/**
+ * 基于模块名称和内容推断模块功能
+ * 对常见命名模式做智能推断
+ */
+export function inferModulePurpose(name, classes, protocols, files) {
+    const lower = name.toLowerCase();
+    const _fileNames = files.map((f) => path.basename(f).toLowerCase());
+    // 常见模块功能推断规则
+    const rules = [
+        {
+            match: /network|http|api|client|request|fetch/i,
+            zh: '负责网络通信和 API 调用',
+            en: 'handles network communication and API calls',
+        },
+        {
+            match: /ui|view|component|widget|screen|page/i,
+            zh: '提供用户界面组件',
+            en: 'provides user interface components',
+        },
+        {
+            match: /model|entity|domain|data/i,
+            zh: '定义数据模型和领域实体',
+            en: 'defines data models and domain entities',
+        },
+        {
+            match: /storage|database|cache|persist|core\s*data|realm/i,
+            zh: '负责数据持久化和存储',
+            en: 'manages data persistence and storage',
+        },
+        {
+            match: /auth|login|session|token|credential/i,
+            zh: '处理认证授权和会话管理',
+            en: 'handles authentication and session management',
+        },
+        {
+            match: /util|helper|extension|common|shared|foundation/i,
+            zh: '提供公共工具类和扩展方法',
+            en: 'provides common utilities and extensions',
+        },
+        { match: /test|spec|mock/i, zh: '包含单元测试和 Mock', en: 'contains unit tests and mocks' },
+        {
+            match: /router|navigation|coordinator|flow/i,
+            zh: '管理页面路由和导航流',
+            en: 'manages page routing and navigation flow',
+        },
+        {
+            match: /config|setting|preference|env/i,
+            zh: '管理应用配置和环境设置',
+            en: 'manages app configuration and environment settings',
+        },
+        {
+            match: /log|analytics|track|monitor/i,
+            zh: '提供日志记录和数据分析能力',
+            en: 'provides logging and analytics capabilities',
+        },
+        {
+            match: /media|image|video|audio|player/i,
+            zh: '处理多媒体资源',
+            en: 'handles multimedia resources',
+        },
+        {
+            match: /service|manager|provider/i,
+            zh: '提供核心业务服务',
+            en: 'provides core business services',
+        },
+    ];
+    // 先按模块名匹配
+    for (const rule of rules) {
+        if (rule.match.test(lower)) {
+            return rule;
+        }
+    }
+    // 再按类名匹配
+    const classStr = classes.join(' ');
+    for (const rule of rules) {
+        if (rule.match.test(classStr)) {
+            return rule;
+        }
+    }
+    return null;
+}
+/**
+ * 从 CodeEntityGraph 提取继承根节点
+ * @param {object|null} codeEntityGraph
+ * @returns {Array<{name: string, children: string[]}>}
+ */
+export function getInheritanceRoots(codeEntityGraph) {
+    if (!codeEntityGraph) {
+        return [];
+    }
+    try {
+        // 尝试查询继承关系
+        const entities = codeEntityGraph.queryEntities?.({ entityType: 'class', limit: 50 }) || [];
+        const roots = [];
+        for (const e of entities) {
+            const _parents = codeEntityGraph.queryEdges?.({ toId: e.entityId, relation: 'inherits' }) || [];
+            const children = codeEntityGraph.queryEdges?.({ fromId: e.entityId, relation: 'inherits' }) || [];
+            if (children.length > 0) {
+                roots.push({
+                    name: e.name,
+                    children: children.map((c) => c.toId || c.to_id || ''),
+                });
+            }
+        }
+        return roots.sort((a, b) => (b.children?.length || 0) - (a.children?.length || 0));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 两层去重
+ *
+ * Layer 1: Title slug 碰撞 — 同名文件不同目录 → hash 相同则删除副本
+ * Layer 2: Content hash    — 跨文件内容完全相同 → 仅保留第一个
+ *
+ * @param {Array} files
+ * @param {string} wikiDir
+ * @param {(phase: string, progress: number, message: string) => void} emit
+ * @returns {{ removed: string[], kept: number }}
+ */
+export function dedup(files, wikiDir, emit) {
+    const removed = [];
+    // Layer 1: slug 碰撞（同名文件跨目录）
+    const slugMap = new Map(); // slug → first file
+    for (const file of files) {
+        const s = path.basename(file.path, path.extname(file.path)).toLowerCase();
+        if (slugMap.has(s)) {
+            const existing = slugMap.get(s);
+            // 完全相同 hash → 移除后来的
+            if (existing.hash === file.hash) {
+                const fullPath = path.join(wikiDir, file.path);
+                if (!fullPath.startsWith(path.resolve(wikiDir) + path.sep)) {
+                    logger.warn(`[WikiGenerator] Dedup: path escape blocked — ${file.path}`);
+                    continue;
+                }
+                try {
+                    fs.unlinkSync(fullPath);
+                }
+                catch {
+                    /* skip */
+                }
+                removed.push(file.path);
+                logger.info(`[WikiGenerator] Dedup: removed ${file.path} (same hash as ${existing.path})`);
+            }
+            // hash 不同 → 保留两个（不同目录允许同名）
+        }
+        else {
+            slugMap.set(s, file);
+        }
+    }
+    // Layer 2: content hash 碰撞（不同文件名但内容相同）
+    const hashMap = new Map(); // hash → first file path
+    for (const file of files) {
+        if (removed.includes(file.path)) {
+            continue;
+        }
+        if (hashMap.has(file.hash)) {
+            const firstPath = hashMap.get(file.hash);
+            // 优先保留代码生成的（非 synced）
+            const isFirstSynced = firstPath.startsWith('documents/') || firstPath.startsWith('skills/');
+            const isCurrentSynced = file.path.startsWith('documents/') || file.path.startsWith('skills/');
+            if (isCurrentSynced && !isFirstSynced) {
+                // 当前是 synced，first 是 codegen → 删除 synced
+                const fullPath = path.join(wikiDir, file.path);
+                if (!fullPath.startsWith(path.resolve(wikiDir) + path.sep)) {
+                    logger.warn(`[WikiGenerator] Dedup: path escape blocked — ${file.path}`);
+                    continue;
+                }
+                try {
+                    fs.unlinkSync(fullPath);
+                }
+                catch {
+                    /* skip */
+                }
+                removed.push(file.path);
+                logger.info(`[WikiGenerator] Dedup: removed synced ${file.path} (same content as ${firstPath})`);
+            }
+            // 其他情况保留两个
+        }
+        else {
+            hashMap.set(file.hash, file.path);
+        }
+    }
+    // 从 files 数组中移除已删除的
+    for (let i = files.length - 1; i >= 0; i--) {
+        if (removed.includes(files[i].path)) {
+            files.splice(i, 1);
+        }
+    }
+    if (removed.length > 0) {
+        emit('dedup', 93, `去重: 移除 ${removed.length} 个重复文件`);
+    }
+    else {
+        emit('dedup', 93, '无重复文件');
+    }
+    return { removed, kept: files.length };
+}
+// ─── 多语言支持 ──────────────────────────────────────────────
+/**
+ * 按主语言返回 AST 术语（中英文）
+ *
+ * 不同语言对"类"和"接口"有不同称谓，Wiki 文档应使用合适的措辞。
+ *
+ * @param {string} langId - LanguageService langId，如 'swift', 'python', 'go'
+ * @returns {{ typeLabel: {zh: string, en: string}, interfaceLabel: {zh: string, en: string}, moduleMetric: {zh: string, en: string} }}
+ */
+export function getLangTerms(langId) {
+    const TERMS = {
+        swift: {
+            typeLabel: { zh: '类/结构体', en: 'Classes/Structs' },
+            interfaceLabel: { zh: '协议', en: 'Protocols' },
+            moduleMetric: { zh: 'SPM Targets', en: 'SPM Targets' },
+        },
+        objectivec: {
+            typeLabel: { zh: '类', en: 'Classes' },
+            interfaceLabel: { zh: '协议', en: 'Protocols' },
+            moduleMetric: { zh: 'Targets', en: 'Targets' },
+        },
+        typescript: {
+            typeLabel: { zh: '类', en: 'Classes' },
+            interfaceLabel: { zh: '接口', en: 'Interfaces' },
+            moduleMetric: { zh: 'Packages', en: 'Packages' },
+        },
+        javascript: {
+            typeLabel: { zh: '类/模块', en: 'Classes/Modules' },
+            interfaceLabel: { zh: '接口', en: 'Interfaces' },
+            moduleMetric: { zh: 'Packages', en: 'Packages' },
+        },
+        python: {
+            typeLabel: { zh: '类', en: 'Classes' },
+            interfaceLabel: { zh: '抽象基类', en: 'Abstract Base' },
+            moduleMetric: { zh: 'Packages', en: 'Packages' },
+        },
+        go: {
+            typeLabel: { zh: '结构体', en: 'Structs' },
+            interfaceLabel: { zh: '接口', en: 'Interfaces' },
+            moduleMetric: { zh: 'Go Modules', en: 'Go Modules' },
+        },
+        rust: {
+            typeLabel: { zh: '结构体/枚举', en: 'Structs/Enums' },
+            interfaceLabel: { zh: 'Trait', en: 'Traits' },
+            moduleMetric: { zh: 'Crates', en: 'Crates' },
+        },
+        java: {
+            typeLabel: { zh: '类', en: 'Classes' },
+            interfaceLabel: { zh: '接口', en: 'Interfaces' },
+            moduleMetric: { zh: 'Modules', en: 'Modules' },
+        },
+        kotlin: {
+            typeLabel: { zh: '类', en: 'Classes' },
+            interfaceLabel: { zh: '接口', en: 'Interfaces' },
+            moduleMetric: { zh: 'Modules', en: 'Modules' },
+        },
+        dart: {
+            typeLabel: { zh: '类', en: 'Classes' },
+            interfaceLabel: { zh: '抽象类', en: 'Abstract Classes' },
+            moduleMetric: { zh: 'Packages', en: 'Packages' },
+        },
+        csharp: {
+            typeLabel: { zh: '类', en: 'Classes' },
+            interfaceLabel: { zh: '接口', en: 'Interfaces' },
+            moduleMetric: { zh: 'Projects', en: 'Projects' },
+        },
+    };
+    return (TERMS[langId] || {
+        typeLabel: { zh: '类型', en: 'Types' },
+        interfaceLabel: { zh: '接口', en: 'Interfaces' },
+        moduleMetric: { zh: 'Modules', en: 'Modules' },
+    });
+}
+/**
+ * 已知的构建系统标志文件 → 生态类型映射
+ *
+ * @deprecated 请使用 LanguageService.buildSystemMarkers。此处保留为只读引用以保持向后兼容。
+ * @type {ReadonlyArray<{file: string, eco: string, buildTool: string}>}
+ */
+export const BUILD_SYSTEM_MARKERS = LanguageService.buildSystemMarkers;
+/**
+ * 检测项目根目录中存在的构建系统标志
+ *
+ * 两级检测:
+ *   1. 先检查根目录的一级文件
+ *   2. 如果根目录未找到，检查一级子目录（支持 monorepo 如 AppFlowy/frontend/...）
+ *
+ * @param {string[]} rootEntryNames 项目根目录一级文件/目录名列表
+ * @param {string} [projectRoot] 可选的项目根路径，用于二级检测
+ * @returns {Array<{eco: string, buildTool: string}>} 匹配到的构建系统
+ */
+export function detectBuildSystems(rootEntryNames, projectRoot) {
+    // 委托给 LanguageService 做一级匹配
+    const results = LanguageService.matchBuildMarkers(rootEntryNames);
+    const seenEco = new Set(results.map((r) => r.eco));
+    // 二级检测: monorepo / 嵌套项目 — 检查一级子目录
+    if (projectRoot && results.length === 0) {
+        const skipDirs = LanguageService.scanSkipDirs;
+        try {
+            const entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+            for (const dir of entries) {
+                if (!dir.isDirectory() || dir.name.startsWith('.') || skipDirs.has(dir.name)) {
+                    continue;
+                }
+                try {
+                    const subEntries = fs
+                        .readdirSync(path.join(projectRoot, dir.name))
+                        .filter((n) => !n.startsWith('.'));
+                    const subResults = LanguageService.matchBuildMarkers(subEntries);
+                    for (const r of subResults) {
+                        if (!seenEco.has(r.eco)) {
+                            results.push(r);
+                            seenEco.add(r.eco);
+                        }
+                    }
+                }
+                catch {
+                    /* skip unreadable subdirs */
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return results;
+}
+// ─── Folder Profile 分析 (AST 不可用时的降级策略) ─────────
+/**
+ * @typedef {object} FolderProfile
+ * @property {string}  name           文件夹名
+ * @property {string}  relPath        相对于项目根的路径
+ * @property {number}  fileCount      源文件数 (递归)
+ * @property {number}  totalSize      总字节数
+ * @property {number}  depth          距项目根的深度
+ * @property {Record<string, number>} langBreakdown - {语言 → 文件数}
+ * @property {string[]} keyFiles      重要文件 (入口、配置、大文件)
+ * @property {string[]} fileNames     所有源文件 basename (排序)
+ * @property {string|null} readme     文件夹内 README 内容摘要
+ * @property {string|null} purpose    从命名推断的功能描述
+ * @property {string[]} imports       通过 import/require regex 提取的外部依赖目标 (其他文件夹)
+ * @property {string[]} entryPoints   检测到的入口文件 (index.*, main.*, __init__.py, mod.rs)
+ * @property {string[]} namingPatterns 检测到的命名约定
+ * @property {string[]} headerComments 从关键文件提取的首段注释
+ */
+/** 入口文件名模式 */
+const ENTRY_POINT_NAMES = new Set([
+    'index.js',
+    'index.ts',
+    'index.tsx',
+    'index.jsx',
+    'index.mjs',
+    'main.js',
+    'main.ts',
+    'main.go',
+    'main.py',
+    'main.rs',
+    'main.dart',
+    'main.c',
+    'main.cpp',
+    'mod.rs',
+    'lib.rs',
+    '__init__.py',
+    'app.js',
+    'app.ts',
+    'app.py',
+    'app.rb',
+    'server.js',
+    'server.ts',
+    'server.py',
+]);
+/** 多语言 import/require 正则 (轻量级, 不依赖 AST) */
+const IMPORT_PATTERNS = [
+    // JS/TS: import ... from '...'  or  require('...')
+    /(?:import\s+.*?\s+from\s+['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\))/,
+    // Python: import xxx / from xxx import yyy
+    /(?:^from\s+([.\w]+)\s+import|^import\s+([.\w]+))/,
+    // Go: import "path/to/pkg"
+    /import\s+(?:\w+\s+)?["']([^"']+)["']/,
+    // Rust: use crate::xxx / use super::xxx / mod xxx
+    /(?:use\s+(?:crate|super)::(\w+)|mod\s+(\w+)\s*;)/,
+    // Java/Kotlin: import com.xxx.yyy
+    /import\s+([\w.]+)/,
+    // Ruby: require 'xxx' / require_relative 'xxx'
+    /require(?:_relative)?\s+['"]([^'"]+)['"]/,
+    // C/C++: #include "xxx"
+    /#include\s+"([^"]+)"/,
+    // Dart: import 'package:xxx/yyy.dart'
+    /import\s+['"](?:package:)?([^'"]+)['"]/,
+];
+/**
+ * 分析项目中重要文件夹，生成 FolderProfile 列表
+ *
+ * 适用场景: AST 无法提取 target（类/函数/协议）的语言，
+ * 通过文件夹结构、文件命名、轻量 import 分析来产出有意义的 wiki 内容。
+ *
+ * @param {object} projectInfo - WikiGenerator._scanProject() 的输出
+ * @param {object} [options]
+ * @param {number} [options.minFiles=3]      文件夹最少文件数阈值
+ * @param {number} [options.maxFolders=20]   最多分析的文件夹数
+ * @param {number} [options.sampleLines=40]  每个文件采样行数 (用于 import 提取)
+ * @returns {FolderProfile[]}
+ */
+export function profileFolders(projectInfo, options = {}) {
+    const { minFiles = 3, maxFolders = 20, sampleLines = 40 } = options;
+    const root = projectInfo.root;
+    const sourceFiles = projectInfo.sourceFiles || [];
+    // ── 1. 按文件夹分组源文件 ──
+    /** @type {Map<string, string[]>} relDir → [relFilePath, ...] */
+    const folderFiles = new Map();
+    for (const relFile of sourceFiles) {
+        const dir = path.dirname(relFile);
+        if (!folderFiles.has(dir)) {
+            folderFiles.set(dir, []);
+        }
+        folderFiles.get(dir).push(relFile);
+    }
+    // ── 2. 聚合: 将子文件夹的文件计入父文件夹 (递归) ──
+    /** @type {Map<string, string[]>} relDir → 所有递归子文件 */
+    const folderRecursive = new Map();
+    for (const [dir, files] of folderFiles) {
+        // 把文件计入 dir 本身及所有祖先
+        const parts = dir.split('/');
+        for (let depth = 1; depth <= parts.length; depth++) {
+            const ancestor = parts.slice(0, depth).join('/');
+            if (!folderRecursive.has(ancestor)) {
+                folderRecursive.set(ancestor, []);
+            }
+            folderRecursive.get(ancestor).push(...files);
+        }
+    }
+    // ── 3. 筛选重要文件夹 ──
+    const candidates = [];
+    for (const [dir, files] of folderRecursive) {
+        if (files.length < minFiles) {
+            continue;
+        }
+        // 排除根目录 '.'
+        if (dir === '.') {
+            continue;
+        }
+        // 排除太深的目录 (depth > 4), 这些通常是叶子目录, 信息量低
+        const depth = dir.split('/').length;
+        if (depth > 4) {
+            continue;
+        }
+        candidates.push({ dir, files, depth });
+    }
+    // 按文件数降序, 优先保留文件多的大模块
+    candidates.sort((a, b) => b.files.length - a.files.length);
+    // 去除被父级包含且文件完全是父级子集的冗余候选
+    // (保留层次分明的目录: 如果父子文件数差异不大, 去掉子)
+    const selected = _pruneRedundantFolders(candidates.slice(0, maxFolders * 2), maxFolders);
+    // ── 4. 为每个选中的文件夹生成 Profile ──
+    const profiles = [];
+    for (const { dir, files, depth } of selected) {
+        const profile = _buildFolderProfile(dir, files, depth, root, sampleLines);
+        if (profile) {
+            profiles.push(profile);
+        }
+    }
+    // 按 fileCount 降序 + depth 升序 排序
+    profiles.sort((a, b) => {
+        if (b.fileCount !== a.fileCount) {
+            return b.fileCount - a.fileCount;
+        }
+        return a.depth - b.depth;
+    });
+    return profiles.slice(0, maxFolders);
+}
+/**
+ * 修剪冗余文件夹: 如果子目录文件数与父目录接近 (>80%), 仅保留父目录
+ * @private
+ */
+function _pruneRedundantFolders(candidates, maxFolders) {
+    const kept = [];
+    const removedDirs = new Set();
+    for (const c of candidates) {
+        if (removedDirs.has(c.dir)) {
+            continue;
+        }
+        // 检查是否有已 kept 的父目录, 且文件比率 > 80%
+        let isRedundant = false;
+        for (const k of kept) {
+            if (c.dir.startsWith(`${k.dir}/`)) {
+                // c 是 k 的子目录
+                if (c.files.length / k.files.length > 0.8) {
+                    isRedundant = true;
+                    break;
+                }
+            }
+            else if (k.dir.startsWith(`${c.dir}/`)) {
+                // c 是 k 的父目录, k 覆盖了 c 大部分 → 保留 c (更高层), 移除 k
+                if (k.files.length / c.files.length > 0.8) {
+                    removedDirs.add(k.dir);
+                }
+            }
+        }
+        if (!isRedundant) {
+            kept.push(c);
+        }
+        if (kept.length >= maxFolders) {
+            break;
+        }
+    }
+    return kept.filter((c) => !removedDirs.has(c.dir));
+}
+/**
+ * 为单个文件夹构建 FolderProfile
+ * @private
+ */
+function _buildFolderProfile(relDir, files, depth, projectRoot, sampleLines) {
+    const fullDir = path.join(projectRoot, relDir);
+    const folderName = path.basename(relDir);
+    // ── 语言分布 ──
+    const langBreakdown = {};
+    let totalSize = 0;
+    for (const f of files) {
+        const ext = path.extname(f);
+        const lang = LanguageService.displayNameFromExt(ext) || ext;
+        langBreakdown[lang] = (langBreakdown[lang] || 0) + 1;
+        try {
+            const stat = fs.statSync(path.join(projectRoot, f));
+            totalSize += stat.size;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    // ── 文件名列表 ──
+    const fileNames = files.map((f) => path.basename(f)).sort();
+    // ── 入口点检测 ──
+    const entryPoints = files.filter((f) => ENTRY_POINT_NAMES.has(path.basename(f).toLowerCase()));
+    // ── 重要文件 (大文件 top5 + 入口文件) ──
+    const fileSizes = [];
+    for (const f of files) {
+        try {
+            const stat = fs.statSync(path.join(projectRoot, f));
+            fileSizes.push({ file: f, size: stat.size });
+        }
+        catch {
+            /* skip */
+        }
+    }
+    fileSizes.sort((a, b) => b.size - a.size);
+    const keyFiles = [...new Set([...entryPoints, ...fileSizes.slice(0, 5).map((fs) => fs.file)])];
+    // ── README 检测 ──
+    let readme = null;
+    const readmeNames = ['README.md', 'readme.md', 'README.txt', 'README', 'readme.markdown'];
+    for (const rn of readmeNames) {
+        const rPath = path.join(fullDir, rn);
+        try {
+            if (fs.existsSync(rPath)) {
+                const content = fs.readFileSync(rPath, 'utf-8');
+                readme = content.slice(0, 1000); // 只取前 1000 字符
+                break;
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    // ── 命名模式检测 ──
+    const namingPatterns = _detectNamingPatterns(fileNames);
+    // ── 轻量 Import 分析 ──
+    const imports = _extractImports(keyFiles.slice(0, 10), projectRoot, sampleLines, relDir);
+    // ── 头部注释提取 (从关键文件提取首段注释) ──
+    const headerComments = [];
+    for (const f of keyFiles.slice(0, 3)) {
+        const comment = _extractHeaderComment(path.join(projectRoot, f));
+        if (comment) {
+            headerComments.push(`${path.basename(f)}: ${comment}`);
+        }
+    }
+    // ── 功能推断 (复用已有 inferModulePurpose + 增强) ──
+    const purpose = inferModulePurpose(folderName, [], [], files);
+    return {
+        name: folderName,
+        relPath: relDir,
+        fileCount: files.length,
+        totalSize,
+        depth,
+        langBreakdown,
+        keyFiles,
+        fileNames,
+        readme,
+        purpose: purpose ? purpose : null,
+        imports,
+        entryPoints: [...new Set(entryPoints.map((f) => path.basename(f)))],
+        namingPatterns,
+        headerComments,
+    };
+}
+/**
+ * 从文件名列表检测命名约定
+ * @private
+ * @param {string[]} fileNames - basename 列表
+ * @returns {string[]}
+ */
+function _detectNamingPatterns(fileNames) {
+    const patterns = [];
+    const lower = fileNames.map((n) => n.toLowerCase());
+    // 测试文件
+    const testFiles = lower.filter((n) => n.startsWith('test_') ||
+        n.startsWith('test.') ||
+        n.endsWith('_test.go') ||
+        n.endsWith('.test.js') ||
+        n.endsWith('.test.ts') ||
+        n.endsWith('.spec.js') ||
+        n.endsWith('.spec.ts') ||
+        n.endsWith('_spec.rb') ||
+        (n.startsWith('test') && n.includes('.')));
+    if (testFiles.length > 0) {
+        patterns.push(`test files: ${testFiles.length}`);
+    }
+    // 常见后缀模式
+    const suffixes = {};
+    for (const name of fileNames) {
+        const base = path.basename(name, path.extname(name));
+        // 检测 CamelCase 后缀: UserController → Controller
+        const camelMatch = base.match(/([A-Z][a-z]+)$/);
+        if (camelMatch) {
+            const suffix = camelMatch[1];
+            suffixes[suffix] = (suffixes[suffix] || 0) + 1;
+        }
+        // 检测 snake_case 后缀: user_controller → controller
+        const snakeMatch = base.match(/_([a-z]+)$/);
+        if (snakeMatch) {
+            const suffix = snakeMatch[1];
+            suffixes[suffix] = (suffixes[suffix] || 0) + 1;
+        }
+    }
+    // 出现 ≥2 次的后缀视为命名约定
+    for (const [suffix, count] of Object.entries(suffixes).sort((a, b) => b[1] - a[1])) {
+        if (count >= 2) {
+            patterns.push(`*${suffix}: ${count}`);
+        }
+    }
+    return patterns.slice(0, 8);
+}
+/**
+ * 从文件顶部提取 import/require 语句，推断文件夹级依赖
+ * @private
+ */
+function _extractImports(keyFiles, projectRoot, sampleLines, currentDir) {
+    const importTargets = new Set();
+    // Node.js / 常见运行时内置模块 — 不应计入项目文件夹依赖
+    const BUILTIN_MODULES = new Set([
+        'fs',
+        'path',
+        'os',
+        'http',
+        'https',
+        'url',
+        'util',
+        'crypto',
+        'stream',
+        'events',
+        'child_process',
+        'cluster',
+        'net',
+        'dns',
+        'tls',
+        'zlib',
+        'readline',
+        'assert',
+        'buffer',
+        'querystring',
+        'string_decoder',
+        'timers',
+        'tty',
+        'dgram',
+        'vm',
+        'worker_threads',
+        'perf_hooks',
+        'async_hooks',
+        'v8',
+        'inspector',
+        'console',
+        'process',
+        'module',
+        // node: prefix 会被 firstSeg 拆出 "node" — 直接排除
+        'node',
+        // 常见第三方包 (非项目目录)
+        'react',
+        'vue',
+        'express',
+        'lodash',
+        'axios',
+        'moment',
+        'dayjs',
+        'webpack',
+        'vite',
+        'jest',
+        'mocha',
+        'chai',
+    ]);
+    for (const relFile of keyFiles) {
+        try {
+            const fullPath = path.join(projectRoot, relFile);
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const lines = content.split('\n').slice(0, sampleLines);
+            for (const line of lines) {
+                for (const pattern of IMPORT_PATTERNS) {
+                    const match = line.match(pattern);
+                    if (match) {
+                        // 取第一个非 undefined 捕获组
+                        const target = match[1] || match[2];
+                        if (target) {
+                            // 跳过 node: 协议前缀 (Node.js 内置模块)
+                            if (target.startsWith('node:')) {
+                                continue;
+                            }
+                            // 解析相对路径 import → 文件夹名
+                            if (target.startsWith('.') || target.startsWith('/')) {
+                                const resolved = path.normalize(path.join(currentDir, target));
+                                const topDir = resolved.split('/')[0];
+                                if (topDir &&
+                                    topDir !== '.' &&
+                                    topDir !== '..' &&
+                                    topDir !== currentDir.split('/')[0]) {
+                                    importTargets.add(topDir);
+                                }
+                            }
+                            else {
+                                // 绝对 import → 取第一段作为模块名
+                                const firstSeg = target.split(/[/.]/)[0];
+                                if (firstSeg && firstSeg.length > 1 && !BUILTIN_MODULES.has(firstSeg)) {
+                                    importTargets.add(firstSeg);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            /* skip unreadable files */
+        }
+    }
+    return [...importTargets].slice(0, 20);
+}
+/**
+ * 提取文件头部注释 (第一个注释块)
+ * @private
+ */
+function _extractHeaderComment(fullPath) {
+    try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        const lines = content.split('\n').slice(0, 30);
+        // 尝试匹配多行注释 /** ... */ 或 /* ... */
+        const joined = lines.join('\n');
+        const blockMatch = joined.match(/\/\*\*?([\s\S]*?)\*\//);
+        if (blockMatch) {
+            const comment = blockMatch[1]
+                .split('\n')
+                .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+                .filter((l) => l && !l.startsWith('@'))
+                .join(' ')
+                .slice(0, 200);
+            if (comment.length > 10) {
+                return comment;
+            }
+        }
+        // 尝试匹配 # 或 // 开头的连续行注释
+        const lineComments = [];
+        for (const line of lines) {
+            const stripped = line.trim();
+            if (stripped.startsWith('#') &&
+                !stripped.startsWith('#!') &&
+                !stripped.startsWith('#include')) {
+                lineComments.push(stripped.replace(/^#+\s*/, ''));
+            }
+            else if (stripped.startsWith('//')) {
+                lineComments.push(stripped.replace(/^\/\/\s*/, ''));
+            }
+            else if (stripped.startsWith('"""') || stripped.startsWith("'''")) {
+                // Python docstring
+                const docMatch = joined.match(/(?:"""|''')([\s\S]*?)(?:"""|''')/);
+                if (docMatch) {
+                    return docMatch[1].trim().slice(0, 200);
+                }
+            }
+            else if (lineComments.length > 0) {
+                break; // 注释块结束
+            }
+        }
+        if (lineComments.length > 0) {
+            const comment = lineComments.join(' ').slice(0, 200);
+            if (comment.length > 10) {
+                return comment;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=WikiUtils.js.map