repowiki-core 0.1.0

package/src/detector/tech-stack-detector.ts

@@ -0,0 +1,377 @@
+/**
+ * @module detector/tech-stack-detector
+ * 技术栈探测器
+ *
+ * 通过分析项目中的配置文件（package.json、requirements.txt、docker-compose.yml 等）
+ * 以及文件扩展名分布，自动识别项目使用的编程语言、框架、包管理器、数据库和服务。
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { FileNode } from '../models/index.js';
+
+// ---------------------------------------------------------------------------
+// 公开接口
+// ---------------------------------------------------------------------------
+
+/** 技术栈检测结果 */
+export interface TechStackResult {
+    /** 检测到的编程语言列表 */
+    languages: string[];
+    /** 检测到的框架列表 */
+    frameworks: string[];
+    /** 检测到的包管理器列表 */
+    packageManagers: string[];
+    /** 检测到的数据库列表 */
+    databases: string[];
+    /** 检测到的服务/中间件列表 */
+    services: string[];
+    /** 参与检测的配置文件列表 */
+    configFiles: string[];
+}
+
+// ---------------------------------------------------------------------------
+// 匹配规则
+// ---------------------------------------------------------------------------
+
+/** Node.js 依赖名 → 框架显示名 */
+const NODE_FRAMEWORK_MAP: Record<string, string> = {
+    next: 'Next.js',
+    react: 'React',
+    vue: 'Vue.js',
+    '@angular/core': 'Angular',
+    vite: 'Vite',
+    express: 'Express',
+    '@nestjs/core': 'NestJS',
+    fastify: 'Fastify',
+};
+
+/** Python 包名关键字 → 框架显示名 */
+const PYTHON_FRAMEWORK_MAP: Record<string, string> = {
+    fastapi: 'FastAPI',
+    django: 'Django',
+    flask: 'Flask',
+    langchain: 'LangChain',
+    langgraph: 'LangGraph',
+};
+
+/** docker-compose 服务镜像/名称关键字 → 数据库/服务显示名 */
+const DOCKER_SERVICE_MAP: Record<string, { name: string; kind: 'database' | 'service' }> = {
+    postgres: { name: 'PostgreSQL', kind: 'database' },
+    mysql: { name: 'MySQL', kind: 'database' },
+    redis: { name: 'Redis', kind: 'database' },
+    mongo: { name: 'MongoDB', kind: 'database' },
+    minio: { name: 'MinIO', kind: 'service' },
+    rabbitmq: { name: 'RabbitMQ', kind: 'service' },
+    elasticsearch: { name: 'Elasticsearch', kind: 'service' },
+};
+
+/** 锁文件 → 包管理器名称 */
+const LOCKFILE_MAP: Record<string, string> = {
+    'package-lock.json': 'npm',
+    'yarn.lock': 'yarn',
+    'pnpm-lock.yaml': 'pnpm',
+};
+
+/** 文件扩展名 → 语言名称（用于统计文件数量） */
+const EXTENSION_LANGUAGE_MAP: Record<string, string> = {
+    '.ts': 'TypeScript',
+    '.tsx': 'TypeScript',
+    '.js': 'JavaScript',
+    '.jsx': 'JavaScript',
+    '.py': 'Python',
+    '.rs': 'Rust',
+    '.go': 'Go',
+    '.java': 'Java',
+    '.kt': 'Kotlin',
+    '.swift': 'Swift',
+    '.rb': 'Ruby',
+    '.php': 'PHP',
+    '.cs': 'C#',
+    '.cpp': 'C++',
+    '.c': 'C',
+    '.dart': 'Dart',
+    '.scala': 'Scala',
+    '.lua': 'Lua',
+    '.zig': 'Zig',
+};
+
+/** 需要达到的最低文件数量阈值，才会报告该语言 */
+const LANGUAGE_FILE_THRESHOLD = 5;
+
+// ---------------------------------------------------------------------------
+// 辅助函数
+// ---------------------------------------------------------------------------
+
+/**
+ * 安全读取文件内容，文件不存在时返回 null。
+ * @param filePath 要读取的文件绝对路径
+ */
+async function safeReadFile(filePath: string): Promise<string | null> {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 在文件节点列表中查找指定相对路径的文件是否存在。
+ * @param files 文件节点列表
+ * @param relativePath 待查找的相对路径
+ */
+function hasFile(files: FileNode[], relativePath: string): boolean {
+    const normalized = relativePath.replace(/\\/g, '/');
+    return files.some(
+        (f) => f.nodeType === 'file' && f.relativePath.replace(/\\/g, '/') === normalized,
+    );
+}
+
+/**
+ * 在文件节点列表中查找指定相对路径前缀的目录是否存在。
+ * @param files 文件节点列表
+ * @param dirPrefix 待查找的目录前缀（如 "agents/"）
+ */
+function hasDirectory(files: FileNode[], dirPrefix: string): boolean {
+    const normalized = dirPrefix.replace(/\\/g, '/');
+    return files.some((f) => {
+        const rel = f.relativePath.replace(/\\/g, '/');
+        return rel === normalized.replace(/\/$/, '') || rel.startsWith(normalized);
+    });
+}
+
+/**
+ * 对结果数组进行去重。
+ */
+function unique(arr: string[]): string[] {
+    return [...new Set(arr)];
+}
+
+// ---------------------------------------------------------------------------
+// 检测子流程
+// ---------------------------------------------------------------------------
+
+/**
+ * 从 package.json 中检测 Node.js 框架和包管理器。
+ */
+async function detectFromPackageJson(
+    rootPath: string,
+    files: FileNode[],
+    result: TechStackResult,
+): Promise<void> {
+    const content = await safeReadFile(path.join(rootPath, 'package.json'));
+    if (!content) return;
+
+    result.configFiles.push('package.json');
+
+    let pkg: Record<string, unknown>;
+    try {
+        pkg = JSON.parse(content) as Record<string, unknown>;
+    } catch {
+        return;
+    }
+
+    // 合并 dependencies 和 devDependencies
+    const deps: Record<string, unknown> = {
+        ...((pkg.dependencies as Record<string, unknown>) ?? {}),
+        ...((pkg.devDependencies as Record<string, unknown>) ?? {}),
+    };
+
+    for (const [depName, frameworkName] of Object.entries(NODE_FRAMEWORK_MAP)) {
+        if (depName in deps) {
+            result.frameworks.push(frameworkName);
+        }
+    }
+
+    // 检测包管理器（通过锁文件）
+    for (const [lockFile, managerName] of Object.entries(LOCKFILE_MAP)) {
+        if (hasFile(files, lockFile)) {
+            result.packageManagers.push(managerName);
+        }
+    }
+}
+
+/**
+ * 从 requirements.txt 中检测 Python 框架。
+ */
+async function detectFromRequirementsTxt(
+    rootPath: string,
+    result: TechStackResult,
+): Promise<void> {
+    const content = await safeReadFile(path.join(rootPath, 'requirements.txt'));
+    if (!content) return;
+
+    result.configFiles.push('requirements.txt');
+    const lower = content.toLowerCase();
+
+    for (const [keyword, frameworkName] of Object.entries(PYTHON_FRAMEWORK_MAP)) {
+        if (lower.includes(keyword)) {
+            result.frameworks.push(frameworkName);
+        }
+    }
+}
+
+/**
+ * 从 pyproject.toml 中检测 Python 框架。
+ */
+async function detectFromPyprojectToml(
+    rootPath: string,
+    result: TechStackResult,
+): Promise<void> {
+    const content = await safeReadFile(path.join(rootPath, 'pyproject.toml'));
+    if (!content) return;
+
+    result.configFiles.push('pyproject.toml');
+    const lower = content.toLowerCase();
+
+    for (const [keyword, frameworkName] of Object.entries(PYTHON_FRAMEWORK_MAP)) {
+        if (lower.includes(keyword)) {
+            result.frameworks.push(frameworkName);
+        }
+    }
+}
+
+/**
+ * 从 docker-compose 配置中检测数据库和服务。
+ * 同时检测 docker-compose.yml 和 docker-compose.yaml 两种命名。
+ */
+async function detectFromDockerCompose(
+    rootPath: string,
+    result: TechStackResult,
+): Promise<void> {
+    const candidates = ['docker-compose.yml', 'docker-compose.yaml'];
+
+    for (const fileName of candidates) {
+        const content = await safeReadFile(path.join(rootPath, fileName));
+        if (!content) continue;
+
+        result.configFiles.push(fileName);
+        const lower = content.toLowerCase();
+
+        for (const [keyword, info] of Object.entries(DOCKER_SERVICE_MAP)) {
+            if (lower.includes(keyword)) {
+                if (info.kind === 'database') {
+                    result.databases.push(info.name);
+                } else {
+                    result.services.push(info.name);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * 通过 Cargo.toml / go.mod 检测 Rust / Go 语言。
+ */
+async function detectFromLanguageManifests(
+    rootPath: string,
+    result: TechStackResult,
+): Promise<void> {
+    const cargoContent = await safeReadFile(path.join(rootPath, 'Cargo.toml'));
+    if (cargoContent) {
+        result.languages.push('Rust');
+        result.configFiles.push('Cargo.toml');
+    }
+
+    const goModContent = await safeReadFile(path.join(rootPath, 'go.mod'));
+    if (goModContent) {
+        result.languages.push('Go');
+        result.configFiles.push('go.mod');
+    }
+}
+
+/**
+ * 根据文件扩展名分布统计语言，仅报告文件数超过阈值的语言。
+ */
+function detectLanguagesFromExtensions(files: FileNode[], result: TechStackResult): void {
+    const counts = new Map<string, number>();
+
+    for (const file of files) {
+        if (file.nodeType !== 'file') continue;
+        const ext = path.extname(file.relativePath).toLowerCase();
+        const lang = EXTENSION_LANGUAGE_MAP[ext];
+        if (lang) {
+            counts.set(lang, (counts.get(lang) ?? 0) + 1);
+        }
+    }
+
+    for (const [lang, count] of counts) {
+        if (count >= LANGUAGE_FILE_THRESHOLD) {
+            result.languages.push(lang);
+        }
+    }
+}
+
+/**
+ * 根据目录结构模式检测架构特征（Agent 架构、Workflow 编排等）。
+ */
+function detectDirectoryPatterns(files: FileNode[], result: TechStackResult): void {
+    // Agent 架构：app/agents 或 agents/
+    if (hasDirectory(files, 'app/agents/') || hasDirectory(files, 'agents/')) {
+        result.frameworks.push('Agent Architecture');
+    }
+
+    // Workflow 编排：workflows/
+    if (hasDirectory(files, 'workflows/')) {
+        result.frameworks.push('Workflow Orchestration');
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 主入口
+// ---------------------------------------------------------------------------
+
+/**
+ * 检测项目技术栈。
+ *
+ * 通过读取配置文件内容和分析文件扩展名分布，自动识别项目使用的
+ * 编程语言、框架、包管理器、数据库和服务。
+ *
+ * @param rootPath 项目根目录的绝对路径
+ * @param files    FileScanner 输出的文件节点列表
+ * @returns 技术栈检测结果
+ *
+ * @example
+ * ```ts
+ * const result = await detectTechStack('/path/to/project', files);
+ * console.log(result.frameworks); // ['Next.js', 'FastAPI']
+ * ```
+ */
+export async function detectTechStack(
+    rootPath: string,
+    files: FileNode[],
+): Promise<TechStackResult> {
+    const result: TechStackResult = {
+        languages: [],
+        frameworks: [],
+        packageManagers: [],
+        databases: [],
+        services: [],
+        configFiles: [],
+    };
+
+    // 并行执行所有检测子流程
+    await Promise.all([
+        detectFromPackageJson(rootPath, files, result),
+        detectFromRequirementsTxt(rootPath, result),
+        detectFromPyprojectToml(rootPath, result),
+        detectFromDockerCompose(rootPath, result),
+        detectFromLanguageManifests(rootPath, result),
+    ]);
+
+    // 基于文件扩展名统计语言（同步操作）
+    detectLanguagesFromExtensions(files, result);
+
+    // 目录模式检测（同步操作）
+    detectDirectoryPatterns(files, result);
+
+    // 去重
+    result.languages = unique(result.languages);
+    result.frameworks = unique(result.frameworks);
+    result.packageManagers = unique(result.packageManagers);
+    result.databases = unique(result.databases);
+    result.services = unique(result.services);
+    result.configFiles = unique(result.configFiles);
+
+    return result;
+}

package/src/generator/index.ts

@@ -0,0 +1,36 @@
+/**
+ * generator 模块入口
+ * 负责将静态分析结果组装、排版为符合规范的 Markdown 格式 Wiki 文档，并生成 Mermaid 关系图表。
+ */
+
+export {
+    generateTable,
+    formatSourceRef,
+    formatSectionSource,
+    formatDiagramSource,
+    formatCiteBlock,
+    formatToc,
+    formatFileTable,
+    wrapMermaid,
+    formatTroubleshootingTable,
+    assembleWikiPage,
+} from './markdown-generator.js';
+
+export {
+    generateArchitectureDiagram,
+    generateERDiagram,
+    generateDependencyDiagram,
+    generateApiDiagram,
+    generateTechStackDiagram,
+} from './mermaid-generator.js';
+
+export {
+    generateSidebar,
+    generateHome,
+} from './sidebar-generator.js';
+
+export {
+    WikiGenerator,
+    type WikiGeneratorConfig,
+    type PlannedPage,
+} from './wiki-generator.js';

package/src/generator/markdown-generator.ts

@@ -0,0 +1,277 @@
+import { type SourceReference } from '../models/index.js';
+
+/**
+ * Markdown 文档生成工具集
+ * 提供格式化表格、源码引用链接、页面结构等工具函数
+ */
+
+/**
+ * 生成 Markdown 表格
+ */
+export function generateTable(headers: string[], rows: string[][]): string {
+    if (rows.length === 0) return '';
+
+    const headerLine = `| ${headers.join(' | ')} |`;
+    const separatorLine = `| ${headers.map(() => '---').join(' | ')} |`;
+    const dataLines = rows.map(row => `| ${row.join(' | ')} |`);
+
+    return [headerLine, separatorLine, ...dataLines].join('\n');
+}
+
+/**
+ * 生成源码引用链接
+ * 格式: [file.py:1-50](file://project/path/to/file.py#L1-L50)
+ */
+export function formatSourceRef(
+    ref: SourceReference,
+    projectRoot: string
+): string {
+    const fileName = ref.filePath.split('/').pop() || ref.filePath;
+    const label = `${fileName}:${ref.startLine}-${ref.endLine}`;
+    const normalizedRoot = projectRoot.replace(/\\/g, '/');
+    const normalizedPath = ref.filePath.replace(/\\/g, '/');
+    return `[${label}](file://${normalizedRoot}/${normalizedPath}#L${ref.startLine}-L${ref.endLine})`;
+}
+
+/**
+ * 生成源码引用块（章节来源）
+ */
+export function formatSectionSource(refs: SourceReference[], projectRoot: string): string {
+    if (refs.length === 0) return '';
+
+    const lines = [
+        '',
+        '> **章节来源**',
+        ...refs.map(ref => `> - ${formatSourceRef(ref, projectRoot)}`),
+        ''
+    ];
+    return lines.join('\n');
+}
+
+/**
+ * 生成图表来源引用
+ */
+export function formatDiagramSource(refs: SourceReference[], projectRoot: string): string {
+    if (refs.length === 0) return '';
+
+    const lines = [
+        '',
+        '> **图表来源**',
+        ...refs.map(ref => `> - ${formatSourceRef(ref, projectRoot)}`),
+        ''
+    ];
+    return lines.join('\n');
+}
+
+/**
+ * 生成 <cite> 引用块，列出所有被引用的源码文件
+ */
+export function formatCiteBlock(refs: SourceReference[], projectRoot: string): string {
+    if (refs.length === 0) return '';
+
+    // 去重文件路径
+    const uniqueFiles = [...new Set(refs.map(r => r.filePath))];
+    const normalizedRoot = projectRoot.replace(/\\/g, '/');
+
+    const lines = [
+        '<cite>',
+        '**本文引用的文件**',
+        ...uniqueFiles.map(fp => {
+            const normalized = fp.replace(/\\/g, '/');
+            return `- [${fp}](file://${normalizedRoot}/${normalized})`;
+        }),
+        '</cite>',
+        ''
+    ];
+    return lines.join('\n');
+}
+
+/**
+ * 生成目录（Table of Contents）
+ */
+export function formatToc(headings: string[]): string {
+    const lines = [
+        '## 目录',
+        '',
+        ...headings.map((h, i) => `${i + 1}. [${h}](#${headingToAnchor(h)})`)
+    ];
+    return lines.join('\n');
+}
+
+/**
+ * 将标题转换为 Markdown 锚点
+ */
+function headingToAnchor(heading: string): string {
+    return heading
+        .toLowerCase()
+        .replace(/[^\w\u4e00-\u9fff\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+
+/**
+ * 生成文件列表表格
+ */
+export function formatFileTable(
+    files: Array<{ path: string; description: string }>
+): string {
+    const headers = ['文件', '作用'];
+    const rows = files.map(f => [`\`${f.path}\``, f.description]);
+    return generateTable(headers, rows);
+}
+
+/**
+ * 包裹 Mermaid 代码块
+ */
+export function wrapMermaid(code: string): string {
+    return `\`\`\`mermaid\n${code}\n\`\`\``;
+}
+
+/**
+ * 生成故障排查表格
+ */
+export function formatTroubleshootingTable(
+    issues: Array<{ problem: string; cause: string; resolution: string }>
+): string {
+    const headers = ['问题', '可能原因', '排查方式'];
+    const rows = issues.map(i => [i.problem, i.cause, i.resolution]);
+    return generateTable(headers, rows);
+}
+
+/**
+ * 组装完整的 Wiki 页面
+ * 将各部分内容按照标准模板结构拼装
+ */
+export function assembleWikiPage(sections: {
+    title: string;
+    citeRefs: SourceReference[];
+    projectRoot: string;
+    introduction: string;
+    projectStructure?: string;
+    projectStructureDiagram?: string;
+    coreComponents?: string;
+    architectureOverview?: string;
+    architectureDiagram?: string;
+    detailedAnalysis?: string;
+    dependencyAnalysis?: string;
+    dependencyDiagram?: string;
+    troubleshooting?: string;
+    conclusion?: string;
+    appendix?: string;
+}): string {
+    const parts: string[] = [];
+
+    // 1. 标题
+    parts.push(`# ${sections.title}`);
+    parts.push('');
+
+    // 2. cite 引用块
+    if (sections.citeRefs.length > 0) {
+        parts.push(formatCiteBlock(sections.citeRefs, sections.projectRoot));
+    }
+
+    // 收集目录项
+    const tocItems: string[] = [];
+    if (sections.introduction) tocItems.push('引言');
+    if (sections.projectStructure) tocItems.push('项目结构与关系');
+    if (sections.coreComponents) tocItems.push('核心组件总览');
+    if (sections.architectureOverview) tocItems.push('架构总览');
+    if (sections.detailedAnalysis) tocItems.push('详细组件分析');
+    if (sections.dependencyAnalysis) tocItems.push('依赖分析');
+    if (sections.troubleshooting) tocItems.push('故障排查指南');
+    if (sections.conclusion) tocItems.push('结论');
+    if (sections.appendix) tocItems.push('附录');
+
+    // 3. 目录
+    if (tocItems.length > 0) {
+        parts.push(formatToc(tocItems));
+        parts.push('');
+    }
+
+    // 4. 引言
+    if (sections.introduction) {
+        parts.push('## 引言');
+        parts.push('');
+        parts.push(sections.introduction);
+        parts.push('');
+    }
+
+    // 5. 项目结构
+    if (sections.projectStructure) {
+        parts.push('## 项目结构与关系');
+        parts.push('');
+        parts.push(sections.projectStructure);
+        if (sections.projectStructureDiagram) {
+            parts.push('');
+            parts.push(wrapMermaid(sections.projectStructureDiagram));
+        }
+        parts.push('');
+    }
+
+    // 6. 核心组件
+    if (sections.coreComponents) {
+        parts.push('## 核心组件总览');
+        parts.push('');
+        parts.push(sections.coreComponents);
+        parts.push('');
+    }
+
+    // 7. 架构总览
+    if (sections.architectureOverview) {
+        parts.push('## 架构总览');
+        parts.push('');
+        parts.push(sections.architectureOverview);
+        if (sections.architectureDiagram) {
+            parts.push('');
+            parts.push(wrapMermaid(sections.architectureDiagram));
+        }
+        parts.push('');
+    }
+
+    // 8. 详细组件分析
+    if (sections.detailedAnalysis) {
+        parts.push('## 详细组件分析');
+        parts.push('');
+        parts.push(sections.detailedAnalysis);
+        parts.push('');
+    }
+
+    // 9. 依赖分析
+    if (sections.dependencyAnalysis) {
+        parts.push('## 依赖分析');
+        parts.push('');
+        parts.push(sections.dependencyAnalysis);
+        if (sections.dependencyDiagram) {
+            parts.push('');
+            parts.push(wrapMermaid(sections.dependencyDiagram));
+        }
+        parts.push('');
+    }
+
+    // 10. 故障排查
+    if (sections.troubleshooting) {
+        parts.push('## 故障排查指南');
+        parts.push('');
+        parts.push(sections.troubleshooting);
+        parts.push('');
+    }
+
+    // 11. 结论
+    if (sections.conclusion) {
+        parts.push('## 结论');
+        parts.push('');
+        parts.push(sections.conclusion);
+        parts.push('');
+    }
+
+    // 12. 附录
+    if (sections.appendix) {
+        parts.push('## 附录');
+        parts.push('');
+        parts.push(sections.appendix);
+        parts.push('');
+    }
+
+    return parts.join('\n');
+}