@claudetools/tools 0.7.0 → 0.7.2

package/dist/helpers/codebase-mapper.js

@@ -0,0 +1,634 @@
+/**
+ * Codebase Mapper
+ *
+ * Client-side AST analysis to generate codebase maps.
+ * Runs in the MCP server and uploads results to the API.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, relative, extname, basename, dirname } from 'path';
+import * as ts from 'typescript';
+import { API_BASE_URL } from './config.js';
+// =============================================================================
+// File Discovery
+// =============================================================================
+const IGNORED_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo',
+    '__pycache__', '.venv', 'venv', '.tox', 'target', '.idea', '.vscode',
+]);
+const SUPPORTED_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+]);
+function discoverFiles(root) {
+    const files = [];
+    function walk(dir) {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+            if (entry.startsWith('.') || IGNORED_DIRS.has(entry))
+                continue;
+            const fullPath = join(dir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (stat.isFile() && SUPPORTED_EXTENSIONS.has(extname(entry))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    walk(root);
+    return files;
+}
+// =============================================================================
+// AST Analysis
+// =============================================================================
+function analyzeFile(filePath, root) {
+    const content = readFileSync(filePath, 'utf-8');
+    const relativePath = relative(root, filePath);
+    const lines = content.split('\n').length;
+    const symbols = [];
+    const imports = [];
+    const exports = [];
+    // Parse with TypeScript
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, filePath.endsWith('.tsx') || filePath.endsWith('.jsx')
+        ? ts.ScriptKind.TSX
+        : ts.ScriptKind.TS);
+    function visit(node) {
+        const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;
+        // Track imports
+        if (ts.isImportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier;
+            if (ts.isStringLiteral(moduleSpecifier)) {
+                imports.push(moduleSpecifier.text);
+            }
+        }
+        // Track exports
+        if (ts.isExportDeclaration(node)) {
+            const moduleSpecifier = node.moduleSpecifier;
+            if (moduleSpecifier && ts.isStringLiteral(moduleSpecifier)) {
+                exports.push(moduleSpecifier.text);
+            }
+        }
+        // Check for export modifier using canHaveModifiers
+        const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+        const isExported = modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+        // Functions
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            symbols.push({
+                name: node.name.text,
+                type: 'function',
+                exported: isExported,
+                line,
+                signature: getSignature(node),
+            });
+        }
+        // Arrow functions and const declarations
+        if (ts.isVariableStatement(node)) {
+            const varModifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+            const isConstExported = varModifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name)) {
+                    const name = decl.name.text;
+                    let symbolType = 'const';
+                    // Detect React components (PascalCase + returns JSX)
+                    if (/^[A-Z]/.test(name) && decl.initializer) {
+                        if (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)) {
+                            symbolType = 'component';
+                        }
+                    }
+                    // Detect hooks
+                    if (name.startsWith('use') && name.length > 3) {
+                        symbolType = 'function';
+                    }
+                    symbols.push({
+                        name,
+                        type: symbolType,
+                        exported: isConstExported,
+                        line: sourceFile.getLineAndCharacterOfPosition(decl.getStart()).line + 1,
+                    });
+                }
+            }
+        }
+        // Classes
+        if (ts.isClassDeclaration(node) && node.name) {
+            symbols.push({
+                name: node.name.text,
+                type: 'class',
+                exported: isExported,
+                line,
+            });
+        }
+        // Interfaces
+        if (ts.isInterfaceDeclaration(node)) {
+            symbols.push({
+                name: node.name.text,
+                type: 'interface',
+                exported: isExported,
+                line,
+            });
+        }
+        // Type aliases
+        if (ts.isTypeAliasDeclaration(node)) {
+            symbols.push({
+                name: node.name.text,
+                type: 'type',
+                exported: isExported,
+                line,
+            });
+        }
+        // Enums
+        if (ts.isEnumDeclaration(node)) {
+            symbols.push({
+                name: node.name.text,
+                type: 'enum',
+                exported: isExported,
+                line,
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return {
+        path: filePath,
+        relativePath,
+        role: detectFileRole(relativePath, symbols),
+        symbols,
+        imports,
+        exports,
+        dependencies: [], // Populated later
+        dependents: [], // Populated later
+        linesOfCode: lines,
+    };
+}
+function getSignature(node) {
+    if (!node.parameters.length && !node.type)
+        return undefined;
+    const params = node.parameters
+        .map((p) => {
+        const name = p.name.getText();
+        const type = p.type?.getText() || 'any';
+        return `${name}: ${type}`;
+    })
+        .join(', ');
+    const returnType = node.type?.getText() || 'void';
+    return `(${params}) => ${returnType}`;
+}
+function detectFileRole(relativePath, symbols) {
+    const path = relativePath.toLowerCase();
+    const fileName = basename(path, extname(path));
+    // Test files
+    if (path.includes('.test.') || path.includes('.spec.') || path.includes('__tests__')) {
+        return 'test';
+    }
+    // Config files
+    if (fileName.includes('config') || fileName.includes('settings')) {
+        return 'config';
+    }
+    // Entry points
+    if (['index', 'main', 'app'].includes(fileName) && !path.includes('/')) {
+        return 'entry-point';
+    }
+    // Type definitions
+    if (path.includes('/types') || fileName.endsWith('.d') || path.includes('types.ts')) {
+        return 'type-definitions';
+    }
+    // Route handlers (Next.js, Remix, etc.)
+    if (path.includes('/routes/') || path.includes('/pages/') || path.includes('/app/')) {
+        return 'route-handler';
+    }
+    // API endpoints
+    if (path.includes('/api/') || path.includes('/handlers/')) {
+        return 'api-endpoint';
+    }
+    // MCP tools
+    if (path.includes('/tools') || path.includes('tool-handlers')) {
+        return 'mcp-tool';
+    }
+    // Components
+    if (path.includes('/components/') || symbols.some((s) => s.type === 'component')) {
+        return 'component';
+    }
+    // Hooks
+    if (path.includes('/hooks/') || symbols.some((s) => s.name.startsWith('use'))) {
+        return 'hook';
+    }
+    // Models
+    if (path.includes('/models/') || path.includes('/entities/') || path.includes('/schema')) {
+        return 'model';
+    }
+    // Services
+    if (path.includes('/services/') || path.includes('/providers/')) {
+        return 'service';
+    }
+    // Extractors
+    if (path.includes('/extraction/') || path.includes('/extractors/')) {
+        return 'extractor';
+    }
+    // Utilities
+    if (path.includes('/utils/') || path.includes('/helpers/') || path.includes('/lib/')) {
+        return 'utility';
+    }
+    return 'unknown';
+}
+// =============================================================================
+// Dependency Analysis
+// =============================================================================
+function buildDependencyGraph(files, root) {
+    // Build a map from relative import paths to file entries
+    const filesByPath = {};
+    for (const file of Object.values(files)) {
+        // Add with and without extension
+        const relPath = file.relativePath;
+        filesByPath[relPath] = relPath;
+        filesByPath[relPath.replace(/\.[^.]+$/, '')] = relPath;
+        // Add index files
+        if (basename(relPath).startsWith('index.')) {
+            filesByPath[dirname(relPath)] = relPath;
+        }
+    }
+    // Resolve dependencies
+    for (const file of Object.values(files)) {
+        const fileDir = dirname(file.relativePath);
+        for (const imp of file.imports) {
+            // Skip external packages
+            if (!imp.startsWith('.') && !imp.startsWith('/'))
+                continue;
+            // Resolve relative import
+            let resolved = imp.startsWith('.')
+                ? join(fileDir, imp).replace(/\\/g, '/')
+                : imp;
+            // Normalize
+            resolved = resolved.replace(/^\.\//, '');
+            // Find matching file
+            const target = filesByPath[resolved];
+            if (target && target !== file.relativePath) {
+                file.dependencies.push(target);
+                // Add reverse dependency
+                const targetFile = files[target];
+                if (targetFile) {
+                    targetFile.dependents.push(file.relativePath);
+                }
+            }
+        }
+    }
+}
+// =============================================================================
+// Call Graph Building
+// =============================================================================
+function buildCallGraph(files) {
+    const callGraph = {};
+    const reverseCallGraph = {};
+    // Build symbol lookup
+    const symbolFiles = {};
+    for (const file of Object.values(files)) {
+        for (const symbol of file.symbols) {
+            if (symbol.exported) {
+                symbolFiles[symbol.name] = file.relativePath;
+            }
+        }
+    }
+    // For now, use a simple heuristic based on dependencies
+    // Full call graph would require more sophisticated AST analysis
+    for (const file of Object.values(files)) {
+        for (const symbol of file.symbols) {
+            if (symbol.type === 'function' || symbol.type === 'component') {
+                callGraph[symbol.name] = [];
+                reverseCallGraph[symbol.name] = [];
+                // Infer calls from dependencies
+                for (const dep of file.dependencies) {
+                    const depFile = files[dep];
+                    if (depFile) {
+                        for (const depSymbol of depFile.symbols) {
+                            if (depSymbol.exported && (depSymbol.type === 'function' || depSymbol.type === 'component')) {
+                                callGraph[symbol.name].push(depSymbol.name);
+                                if (!reverseCallGraph[depSymbol.name]) {
+                                    reverseCallGraph[depSymbol.name] = [];
+                                }
+                                reverseCallGraph[depSymbol.name].push(symbol.name);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return { callGraph, reverseCallGraph };
+}
+// =============================================================================
+// Directory Analysis
+// =============================================================================
+function analyzeDirectories(files, root) {
+    const directories = {};
+    const dirFiles = {};
+    // Group files by directory
+    for (const file of Object.values(files)) {
+        const dir = dirname(file.relativePath) || '.';
+        if (!dirFiles[dir]) {
+            dirFiles[dir] = [];
+        }
+        dirFiles[dir].push(file);
+    }
+    // Analyze each directory
+    for (const [dir, filesInDir] of Object.entries(dirFiles)) {
+        const languages = {};
+        const keyFiles = [];
+        for (const file of filesInDir) {
+            const ext = extname(file.relativePath);
+            languages[ext] = (languages[ext] || 0) + 1;
+            // Key files are entry points or have many exports
+            if (file.role === 'entry-point' || file.symbols.filter((s) => s.exported).length > 5) {
+                keyFiles.push(file.relativePath);
+            }
+        }
+        const primaryLang = Object.entries(languages)
+            .sort((a, b) => b[1] - a[1])[0]?.[0] || 'unknown';
+        directories[dir] = {
+            path: dir,
+            role: detectDirectoryRole(dir, filesInDir),
+            fileCount: filesInDir.length,
+            primaryLanguage: primaryLang,
+            keyFiles: keyFiles.slice(0, 3),
+        };
+    }
+    return directories;
+}
+function detectDirectoryRole(dir, files) {
+    const dirLower = dir.toLowerCase();
+    if (dirLower.includes('component'))
+        return 'components';
+    if (dirLower.includes('hook'))
+        return 'hooks';
+    if (dirLower.includes('route') || dirLower.includes('page'))
+        return 'routes';
+    if (dirLower.includes('api') || dirLower.includes('handler'))
+        return 'api';
+    if (dirLower.includes('util') || dirLower.includes('helper') || dirLower.includes('lib'))
+        return 'utilities';
+    if (dirLower.includes('type'))
+        return 'types';
+    if (dirLower.includes('test') || dirLower.includes('spec'))
+        return 'tests';
+    if (dirLower.includes('config'))
+        return 'configuration';
+    if (dirLower.includes('model') || dirLower.includes('schema'))
+        return 'models';
+    if (dirLower.includes('service') || dirLower.includes('provider'))
+        return 'services';
+    // Check file roles
+    const roleCounts = {};
+    for (const file of files) {
+        roleCounts[file.role] = (roleCounts[file.role] || 0) + 1;
+    }
+    const topRole = Object.entries(roleCounts).sort((a, b) => b[1] - a[1])[0];
+    return topRole ? topRole[0] : 'misc';
+}
+// =============================================================================
+// Framework Detection
+// =============================================================================
+function detectFrameworks(root) {
+    const frameworks = [];
+    try {
+        const pkgPath = join(root, 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps.next)
+                frameworks.push('Next.js');
+            if (deps.react)
+                frameworks.push('React');
+            if (deps.vue)
+                frameworks.push('Vue');
+            if (deps.svelte)
+                frameworks.push('Svelte');
+            if (deps['@tanstack/react-query'])
+                frameworks.push('TanStack Query');
+            if (deps.express)
+                frameworks.push('Express');
+            if (deps.hono)
+                frameworks.push('Hono');
+            if (deps.fastify)
+                frameworks.push('Fastify');
+            if (deps.drizzle)
+                frameworks.push('Drizzle');
+            if (deps.prisma)
+                frameworks.push('Prisma');
+            if (deps.zod)
+                frameworks.push('Zod');
+            if (deps.typescript)
+                frameworks.push('TypeScript');
+        }
+    }
+    catch {
+        // Ignore package.json errors
+    }
+    return frameworks;
+}
+// =============================================================================
+// Markdown Generation
+// =============================================================================
+function generateMarkdown(index) {
+    let md = `# Codebase Map: ${basename(index.projectRoot)}\n\n`;
+    md += `> Generated ${index.generatedAt}\n\n`;
+    // Summary
+    md += `## Summary\n\n`;
+    md += `- **Files:** ${index.summary.totalFiles}\n`;
+    md += `- **Symbols:** ${index.summary.totalSymbols}\n`;
+    md += `- **Frameworks:** ${index.summary.frameworks.join(', ') || 'None detected'}\n\n`;
+    // Languages
+    md += `### Languages\n\n`;
+    for (const [lang, count] of Object.entries(index.summary.languages)) {
+        md += `- ${lang}: ${count} files\n`;
+    }
+    md += '\n';
+    // Directory structure
+    md += `## Structure\n\n`;
+    const sortedDirs = Object.values(index.directories).sort((a, b) => a.path.localeCompare(b.path));
+    for (const dir of sortedDirs) {
+        const indent = '  '.repeat(dir.path.split('/').length - 1);
+        md += `${indent}- **${dir.path}/** (${dir.role}, ${dir.fileCount} files)\n`;
+        if (dir.keyFiles.length > 0) {
+            for (const keyFile of dir.keyFiles) {
+                md += `${indent}  - 📄 ${basename(keyFile)}\n`;
+            }
+        }
+    }
+    md += '\n';
+    // Key entry points
+    const entryPoints = Object.values(index.files).filter((f) => f.role === 'entry-point' || f.symbols.filter((s) => s.exported).length > 10);
+    if (entryPoints.length > 0) {
+        md += `## Entry Points\n\n`;
+        for (const file of entryPoints.slice(0, 10)) {
+            const exportedSymbols = file.symbols.filter((s) => s.exported);
+            md += `### ${file.relativePath}\n`;
+            md += `- **Role:** ${file.role}\n`;
+            md += `- **Lines:** ${file.linesOfCode}\n`;
+            md += `- **Exports:** ${exportedSymbols.length}\n\n`;
+            if (exportedSymbols.length > 0 && exportedSymbols.length <= 20) {
+                for (const sym of exportedSymbols) {
+                    md += `  - \`${sym.name}\` (${sym.type})\n`;
+                }
+                md += '\n';
+            }
+        }
+    }
+    // Key symbols
+    const exportedSymbols = Object.entries(index.symbols)
+        .filter(([_, locs]) => locs.some((l) => l.exported))
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, 30);
+    if (exportedSymbols.length > 0) {
+        md += `## Key Symbols\n\n`;
+        md += `| Symbol | Type | Location |\n`;
+        md += `|--------|------|----------|\n`;
+        for (const [name, locs] of exportedSymbols) {
+            const loc = locs[0];
+            md += `| \`${name}\` | ${loc.type} | ${loc.file}:${loc.line} |\n`;
+        }
+        md += '\n';
+    }
+    return md;
+}
+// =============================================================================
+// Main Export
+// =============================================================================
+export async function generateCodebaseMap(projectRoot, projectId, apiKey) {
+    try {
+        // Discover and analyze files
+        const filePaths = discoverFiles(projectRoot);
+        if (filePaths.length === 0) {
+            return { success: false, error: 'No supported files found in project' };
+        }
+        const files = {};
+        const languages = {};
+        let totalSymbols = 0;
+        for (const filePath of filePaths) {
+            try {
+                const entry = analyzeFile(filePath, projectRoot);
+                files[entry.relativePath] = entry;
+                const ext = extname(entry.relativePath);
+                languages[ext] = (languages[ext] || 0) + 1;
+                totalSymbols += entry.symbols.length;
+            }
+            catch (err) {
+                // Skip files that can't be parsed
+                console.error(`Failed to analyze ${filePath}:`, err);
+            }
+        }
+        // Build dependency graph
+        buildDependencyGraph(files, projectRoot);
+        // Build call graph
+        const { callGraph, reverseCallGraph } = buildCallGraph(files);
+        // Analyze directories
+        const directories = analyzeDirectories(files, projectRoot);
+        // Detect frameworks
+        const frameworks = detectFrameworks(projectRoot);
+        // Build symbols index
+        const symbols = {};
+        for (const file of Object.values(files)) {
+            for (const sym of file.symbols) {
+                if (!symbols[sym.name]) {
+                    symbols[sym.name] = [];
+                }
+                symbols[sym.name].push({
+                    file: file.relativePath,
+                    line: sym.line,
+                    type: sym.type,
+                    exported: sym.exported,
+                });
+            }
+        }
+        // Build index
+        const index = {
+            version: '1.0.0',
+            generatedAt: new Date().toISOString(),
+            projectRoot,
+            summary: {
+                totalFiles: Object.keys(files).length,
+                totalSymbols,
+                languages,
+                frameworks,
+            },
+            directories,
+            files,
+            symbols,
+            callGraph,
+            reverseCallGraph,
+        };
+        // Generate markdown
+        const markdown = generateMarkdown(index);
+        // Upload to API
+        const response = await fetch(`${API_BASE_URL}/api/v1/codebase/${projectId}/generate`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ index, markdown }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            return { success: false, error: `API error: ${response.status} - ${text}` };
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: String(err) };
+    }
+}
+/**
+ * Generate a codebase map locally without uploading
+ * Useful for previewing or debugging
+ */
+export function generateCodebaseMapLocal(projectRoot) {
+    const filePaths = discoverFiles(projectRoot);
+    const files = {};
+    const languages = {};
+    let totalSymbols = 0;
+    for (const filePath of filePaths) {
+        try {
+            const entry = analyzeFile(filePath, projectRoot);
+            files[entry.relativePath] = entry;
+            const ext = extname(entry.relativePath);
+            languages[ext] = (languages[ext] || 0) + 1;
+            totalSymbols += entry.symbols.length;
+        }
+        catch {
+            // Skip files that can't be parsed
+        }
+    }
+    buildDependencyGraph(files, projectRoot);
+    const { callGraph, reverseCallGraph } = buildCallGraph(files);
+    const directories = analyzeDirectories(files, projectRoot);
+    const frameworks = detectFrameworks(projectRoot);
+    const symbols = {};
+    for (const file of Object.values(files)) {
+        for (const sym of file.symbols) {
+            if (!symbols[sym.name]) {
+                symbols[sym.name] = [];
+            }
+            symbols[sym.name].push({
+                file: file.relativePath,
+                line: sym.line,
+                type: sym.type,
+                exported: sym.exported,
+            });
+        }
+    }
+    const index = {
+        version: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        projectRoot,
+        summary: {
+            totalFiles: Object.keys(files).length,
+            totalSymbols,
+            languages,
+            frameworks,
+        },
+        directories,
+        files,
+        symbols,
+        callGraph,
+        reverseCallGraph,
+    };
+    const markdown = generateMarkdown(index);
+    return { index, markdown };
+}

package/dist/helpers/config.d.ts

@@ -34,7 +34,7 @@ export declare function resolveProjectId(): string;
 export declare function resolveProjectIdAsync(): Promise<string>;
 /**
  * Gets the default project ID (synchronous version)
- * Throws if not already resolved - call resolveProjectIdAsync() first
+ * Checks session-context.md first, then config, then falls back to cwd resolution
  */
 export declare function getDefaultProjectId(): string;
 /**