@compilr-dev/agents-coding-ts 0.1.0

package/dist/tools/get-documentation.js

@@ -0,0 +1,613 @@
+/**
+ * getDocumentation Tool
+ *
+ * Extract JSDoc/TSDoc documentation from source files.
+ * Provides documentation coverage metrics and identifies undocumented exports.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as ts from 'typescript';
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { detectLanguage, isLanguageSupported } from '../parser/typescript-parser.js';
+// Tool description
+const TOOL_DESCRIPTION = `Extract JSDoc/TSDoc documentation from source files.
+Returns documented symbols with their signatures and documentation content.
+Calculates documentation coverage metrics and identifies undocumented exports.
+Useful for generating API documentation and measuring doc coverage.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        path: {
+            type: 'string',
+            description: 'File or directory to analyze',
+        },
+        recursive: {
+            type: 'boolean',
+            description: 'Recursive analysis for directories (default: false)',
+            default: false,
+        },
+        kinds: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Filter by symbol kinds: function, class, interface, type, enum, variable, method, property',
+        },
+        exportedOnly: {
+            type: 'boolean',
+            description: 'Only include exported symbols (default: false)',
+            default: false,
+        },
+        documentedOnly: {
+            type: 'boolean',
+            description: 'Only include symbols with documentation (default: true)',
+            default: true,
+        },
+        maxFiles: {
+            type: 'number',
+            description: 'Maximum files to analyze (default: 50)',
+            default: 50,
+        },
+        includePrivate: {
+            type: 'boolean',
+            description: 'Include private class members (default: false)',
+            default: false,
+        },
+    },
+    required: ['path'],
+};
+// Default exclusions
+const DEFAULT_EXCLUDE = ['node_modules', 'dist', 'build', '.git', 'coverage'];
+/**
+ * getDocumentation tool
+ */
+export const getDocumentationTool = defineTool({
+    name: 'get_documentation',
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetDocumentation,
+});
+/**
+ * Execute the getDocumentation tool
+ */
+async function executeGetDocumentation(input) {
+    const { path: inputPath, recursive = false, kinds, exportedOnly = false, documentedOnly = true, maxFiles = 50, includePrivate = false, } = input;
+    try {
+        const resolvedPath = path.resolve(inputPath);
+        // Check if path exists
+        try {
+            await fs.access(resolvedPath);
+        }
+        catch {
+            return createErrorResult(`Path not found: ${resolvedPath}`);
+        }
+        const stats = await fs.stat(resolvedPath);
+        const files = [];
+        if (stats.isDirectory()) {
+            await collectFiles(resolvedPath, files, recursive ? 10 : 0, maxFiles);
+        }
+        else if (stats.isFile()) {
+            files.push(resolvedPath);
+        }
+        // Analyze each file
+        const fileResults = [];
+        let totalSymbols = 0;
+        let documentedSymbols = 0;
+        let undocumentedSymbols = 0;
+        const undocumentedExports = [];
+        for (const file of files) {
+            const fileResult = await analyzeFile(file, {
+                kinds,
+                exportedOnly,
+                documentedOnly,
+                includePrivate,
+            });
+            if (fileResult) {
+                fileResults.push(fileResult);
+                // Update totals
+                totalSymbols += fileResult.stats.totalSymbols;
+                documentedSymbols += fileResult.stats.documentedSymbols;
+                undocumentedSymbols += fileResult.stats.undocumentedSymbols;
+                // Track undocumented exports
+                for (const symbol of fileResult.symbols) {
+                    if (symbol.exported && !hasDocumentation(symbol.documentation)) {
+                        undocumentedExports.push({
+                            name: symbol.name,
+                            kind: symbol.kind,
+                            path: file,
+                            line: symbol.line,
+                        });
+                    }
+                }
+            }
+        }
+        const coveragePercent = totalSymbols > 0 ? Math.round((documentedSymbols / totalSymbols) * 100) : 100;
+        const result = {
+            path: resolvedPath,
+            files: fileResults,
+            summary: {
+                totalFiles: fileResults.length,
+                totalSymbols,
+                documentedSymbols,
+                undocumentedSymbols,
+                coveragePercent,
+            },
+            undocumentedExports: undocumentedExports.length > 0 ? undocumentedExports : undefined,
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(`Failed to extract documentation: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Check if documentation has meaningful content
+ */
+function hasDocumentation(doc) {
+    return !!(doc.summary ||
+        doc.description ||
+        doc.params ||
+        doc.returns ||
+        doc.examples?.length ||
+        doc.throws?.length);
+}
+/**
+ * Collect files to analyze
+ */
+async function collectFiles(dirPath, files, maxDepth, maxFiles, currentDepth = 0) {
+    if (currentDepth > maxDepth || files.length >= maxFiles)
+        return;
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                break;
+            const fullPath = path.join(dirPath, entry.name);
+            // Skip excluded directories
+            if (entry.isDirectory()) {
+                if (DEFAULT_EXCLUDE.includes(entry.name))
+                    continue;
+                await collectFiles(fullPath, files, maxDepth, maxFiles, currentDepth + 1);
+            }
+            else if (entry.isFile()) {
+                // Only include TypeScript/JavaScript files
+                if (/\.(ts|tsx|js|jsx)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore permission errors
+    }
+}
+/**
+ * Analyze documentation of a single file
+ */
+async function analyzeFile(filePath, options) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const detection = detectLanguage(filePath);
+        if (!detection.language || !isLanguageSupported(detection.language)) {
+            return null;
+        }
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, filePath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        // Extract file-level documentation
+        const fileDoc = extractFileDocumentation(sourceFile);
+        // Extract symbol documentation
+        const allSymbols = [];
+        extractSymbols(sourceFile, sourceFile, allSymbols, options);
+        // Apply filters
+        let symbols = allSymbols;
+        if (options.kinds && options.kinds.length > 0) {
+            const kinds = options.kinds;
+            symbols = symbols.filter((s) => kinds.includes(s.kind));
+        }
+        if (options.exportedOnly) {
+            symbols = symbols.filter((s) => s.exported);
+        }
+        if (options.documentedOnly) {
+            symbols = symbols.filter((s) => hasDocumentation(s.documentation));
+        }
+        // Calculate stats based on all symbols (before documentedOnly filter)
+        const totalSymbols = allSymbols.length;
+        const documentedCount = allSymbols.filter((s) => hasDocumentation(s.documentation)).length;
+        const undocumentedCount = totalSymbols - documentedCount;
+        const coveragePercent = totalSymbols > 0 ? Math.round((documentedCount / totalSymbols) * 100) : 100;
+        return {
+            path: filePath,
+            fileDoc: fileDoc && hasDocumentation(fileDoc) ? fileDoc : undefined,
+            symbols,
+            stats: {
+                totalSymbols,
+                documentedSymbols: documentedCount,
+                undocumentedSymbols: undocumentedCount,
+                coveragePercent,
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract file-level documentation (module doc comment at top of file)
+ */
+function extractFileDocumentation(sourceFile) {
+    // Look for JSDoc at the very beginning of the file
+    const text = sourceFile.getFullText();
+    const match = text.match(/^\s*\/\*\*([\s\S]*?)\*\//);
+    if (!match)
+        return undefined;
+    const commentText = match[1];
+    const lines = commentText.split('\n').map((l) => l.replace(/^\s*\*\s?/, '').trim());
+    // Filter out @module and similar file-level tags, and empty lines
+    const descLines = [];
+    let isFileLevel = false;
+    for (const line of lines) {
+        if (line.startsWith('@module') ||
+            line.startsWith('@fileoverview') ||
+            line.startsWith('@file')) {
+            isFileLevel = true;
+        }
+        else if (!line.startsWith('@') && line.length > 0) {
+            descLines.push(line);
+        }
+    }
+    // Only return if this looks like a file-level comment
+    if (!isFileLevel && descLines.length === 0)
+        return undefined;
+    const summary = descLines[0] || '';
+    const description = descLines.length > 1 ? descLines.slice(1).join('\n').trim() : undefined;
+    return {
+        summary,
+        description,
+    };
+}
+/**
+ * Extract documented symbols from a node
+ */
+function extractSymbols(node, sourceFile, symbols, options, _containerName) {
+    // Function declarations
+    if (ts.isFunctionDeclaration(node) && node.name) {
+        symbols.push(extractSymbolInfo(node, sourceFile, 'function', node.name.text));
+    }
+    // Variable declarations (arrow functions, const values)
+    else if (ts.isVariableStatement(node)) {
+        for (const decl of node.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name)) {
+                const kind = decl.initializer &&
+                    (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))
+                    ? 'function'
+                    : 'variable';
+                symbols.push(extractSymbolInfo(node, sourceFile, kind, decl.name.text));
+            }
+        }
+    }
+    // Class declarations
+    else if (ts.isClassDeclaration(node) && node.name) {
+        symbols.push(extractSymbolInfo(node, sourceFile, 'class', node.name.text));
+        // Extract class members
+        for (const member of node.members) {
+            // Skip private members if not included
+            if (!options.includePrivate && isPrivateMember(member))
+                continue;
+            if (ts.isMethodDeclaration(member) && ts.isIdentifier(member.name)) {
+                symbols.push(extractSymbolInfo(member, sourceFile, 'method', member.name.text, node.name.text));
+            }
+            else if (ts.isPropertyDeclaration(member) && ts.isIdentifier(member.name)) {
+                symbols.push(extractSymbolInfo(member, sourceFile, 'property', member.name.text, node.name.text));
+            }
+        }
+    }
+    // Interface declarations
+    else if (ts.isInterfaceDeclaration(node)) {
+        symbols.push(extractSymbolInfo(node, sourceFile, 'interface', node.name.text));
+        // Extract interface members
+        for (const member of node.members) {
+            if (ts.isPropertySignature(member) && ts.isIdentifier(member.name)) {
+                symbols.push(extractSymbolInfo(member, sourceFile, 'property', member.name.text, node.name.text));
+            }
+            else if (ts.isMethodSignature(member) && ts.isIdentifier(member.name)) {
+                symbols.push(extractSymbolInfo(member, sourceFile, 'method', member.name.text, node.name.text));
+            }
+        }
+    }
+    // Type alias declarations
+    else if (ts.isTypeAliasDeclaration(node)) {
+        symbols.push(extractSymbolInfo(node, sourceFile, 'type', node.name.text));
+    }
+    // Enum declarations
+    else if (ts.isEnumDeclaration(node)) {
+        symbols.push(extractSymbolInfo(node, sourceFile, 'enum', node.name.text));
+    }
+    // Continue traversing (but skip into class/interface bodies as they're handled above)
+    if (!ts.isClassDeclaration(node) && !ts.isInterfaceDeclaration(node)) {
+        ts.forEachChild(node, (child) => {
+            extractSymbols(child, sourceFile, symbols, options);
+        });
+    }
+}
+/**
+ * Check if a class member is private
+ */
+function isPrivateMember(node) {
+    if (!ts.canHaveModifiers(node))
+        return false;
+    const modifiers = ts.getModifiers(node);
+    return modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword) ?? false;
+}
+/**
+ * Extract symbol information
+ */
+function extractSymbolInfo(node, sourceFile, kind, name, containerName) {
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    const exported = isExported(node);
+    const documentation = extractDocumentation(node, sourceFile);
+    const signature = extractSignature(node, sourceFile, kind);
+    return {
+        name,
+        kind,
+        line: line + 1,
+        exported,
+        signature,
+        documentation,
+        container: containerName,
+    };
+}
+/**
+ * Check if node is exported
+ */
+function isExported(node) {
+    // For variable declarations, check the parent VariableStatement
+    if (ts.isVariableDeclaration(node)) {
+        const varDeclList = node.parent;
+        const varStatement = varDeclList.parent;
+        if (ts.canHaveModifiers(varStatement)) {
+            const modifiers = ts.getModifiers(varStatement);
+            return modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+        }
+        return false;
+    }
+    // For property/method in class/interface - inherit from parent
+    if (ts.isPropertyDeclaration(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isPropertySignature(node) ||
+        ts.isMethodSignature(node)) {
+        const parent = node.parent;
+        if (ts.isClassDeclaration(parent) || ts.isInterfaceDeclaration(parent)) {
+            return isExported(parent);
+        }
+        return false;
+    }
+    if (!ts.canHaveModifiers(node))
+        return false;
+    const modifiers = ts.getModifiers(node);
+    return modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+/**
+ * Extract signature from node
+ */
+function extractSignature(node, sourceFile, kind) {
+    switch (kind) {
+        case 'function': {
+            if (ts.isFunctionDeclaration(node) && node.name) {
+                const params = node.parameters.map((p) => p.getText(sourceFile)).join(', ');
+                const returnType = node.type ? `: ${node.type.getText(sourceFile)}` : '';
+                const generics = node.typeParameters
+                    ? `<${node.typeParameters.map((t) => t.getText(sourceFile)).join(', ')}>`
+                    : '';
+                return `function ${node.name.text}${generics}(${params})${returnType}`;
+            }
+            if (ts.isVariableStatement(node)) {
+                const decl = node.declarationList.declarations[0];
+                if (ts.isIdentifier(decl.name)) {
+                    if (decl.initializer &&
+                        (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))) {
+                        const func = decl.initializer;
+                        const params = func.parameters.map((p) => p.getText(sourceFile)).join(', ');
+                        const returnType = func.type ? `: ${func.type.getText(sourceFile)}` : '';
+                        return `const ${decl.name.text} = (${params})${returnType} => ...`;
+                    }
+                }
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        case 'class': {
+            if (ts.isClassDeclaration(node) && node.name) {
+                const generics = node.typeParameters
+                    ? `<${node.typeParameters.map((t) => t.getText(sourceFile)).join(', ')}>`
+                    : '';
+                let heritage = '';
+                if (node.heritageClauses) {
+                    for (const clause of node.heritageClauses) {
+                        const tokenKind = clause.token;
+                        if (tokenKind === ts.SyntaxKind.ExtendsKeyword) {
+                            heritage += ` extends ${clause.types.map((t) => t.getText(sourceFile)).join(', ')}`;
+                        }
+                        else if (tokenKind === ts.SyntaxKind.ImplementsKeyword) {
+                            heritage += ` implements ${clause.types.map((t) => t.getText(sourceFile)).join(', ')}`;
+                        }
+                    }
+                }
+                return `class ${node.name.text}${generics}${heritage}`;
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        case 'interface': {
+            if (ts.isInterfaceDeclaration(node)) {
+                const generics = node.typeParameters
+                    ? `<${node.typeParameters.map((t) => t.getText(sourceFile)).join(', ')}>`
+                    : '';
+                let heritage = '';
+                if (node.heritageClauses) {
+                    for (const clause of node.heritageClauses) {
+                        heritage += ` extends ${clause.types.map((t) => t.getText(sourceFile)).join(', ')}`;
+                    }
+                }
+                return `interface ${node.name.text}${generics}${heritage}`;
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        case 'type': {
+            if (ts.isTypeAliasDeclaration(node)) {
+                const generics = node.typeParameters
+                    ? `<${node.typeParameters.map((t) => t.getText(sourceFile)).join(', ')}>`
+                    : '';
+                const typeText = node.type.getText(sourceFile);
+                // Truncate long types
+                const maxLen = 80;
+                const truncatedType = typeText.length > maxLen ? typeText.slice(0, maxLen) + '...' : typeText;
+                return `type ${node.name.text}${generics} = ${truncatedType}`;
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        case 'enum': {
+            if (ts.isEnumDeclaration(node)) {
+                const members = node.members.map((m) => m.name.getText(sourceFile)).slice(0, 5);
+                const suffix = node.members.length > 5 ? ', ...' : '';
+                return `enum ${node.name.text} { ${members.join(', ')}${suffix} }`;
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        case 'variable': {
+            if (ts.isVariableStatement(node)) {
+                const decl = node.declarationList.declarations[0];
+                if (ts.isIdentifier(decl.name)) {
+                    const typeText = decl.type ? `: ${decl.type.getText(sourceFile)}` : '';
+                    return `const ${decl.name.text}${typeText}`;
+                }
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        case 'method': {
+            if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name)) {
+                const params = node.parameters.map((p) => p.getText(sourceFile)).join(', ');
+                const returnType = node.type ? `: ${node.type.getText(sourceFile)}` : '';
+                return `${node.name.text}(${params})${returnType}`;
+            }
+            if (ts.isMethodSignature(node) && ts.isIdentifier(node.name)) {
+                const params = node.parameters.map((p) => p.getText(sourceFile)).join(', ');
+                const returnType = node.type ? `: ${node.type.getText(sourceFile)}` : '';
+                return `${node.name.text}(${params})${returnType}`;
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        case 'property': {
+            if (ts.isPropertyDeclaration(node) && ts.isIdentifier(node.name)) {
+                const typeText = node.type ? `: ${node.type.getText(sourceFile)}` : '';
+                const optional = node.questionToken ? '?' : '';
+                return `${node.name.text}${optional}${typeText}`;
+            }
+            if (ts.isPropertySignature(node) && ts.isIdentifier(node.name)) {
+                const typeText = node.type ? `: ${node.type.getText(sourceFile)}` : '';
+                const optional = node.questionToken ? '?' : '';
+                return `${node.name.text}${optional}${typeText}`;
+            }
+            return node.getText(sourceFile).split('\n')[0];
+        }
+        default:
+            return node.getText(sourceFile).split('\n')[0];
+    }
+}
+/**
+ * Extract JSDoc documentation from a node
+ */
+function extractDocumentation(node, sourceFile) {
+    const jsDocTags = ts.getJSDocTags(node);
+    const jsDocComments = node.jsDoc;
+    const doc = {
+        summary: '',
+    };
+    // Get comment text
+    if (jsDocComments?.length) {
+        const firstDoc = jsDocComments[0];
+        if (typeof firstDoc.comment === 'string') {
+            const lines = firstDoc.comment.split('\n');
+            doc.summary = lines[0].trim();
+            if (lines.length > 1) {
+                doc.description = lines.slice(1).join('\n').trim();
+            }
+        }
+        else if (firstDoc.comment && typeof firstDoc.comment !== 'string') {
+            // JSDocComment can be an array of JSDocText | JSDocLink
+            const commentParts = firstDoc.comment;
+            const text = commentParts
+                .map((c) => (c.kind === ts.SyntaxKind.JSDocText ? c.text : ''))
+                .join('')
+                .trim();
+            const lines = text.split('\n');
+            doc.summary = lines[0].trim();
+            if (lines.length > 1) {
+                doc.description = lines.slice(1).join('\n').trim();
+            }
+        }
+    }
+    // Process tags
+    const params = {};
+    const throws = [];
+    const examples = [];
+    const see = [];
+    for (const tag of jsDocTags) {
+        const tagName = tag.tagName.text;
+        let tagComment = '';
+        if (typeof tag.comment === 'string') {
+            tagComment = tag.comment;
+        }
+        else if (tag.comment && typeof tag.comment !== 'string') {
+            const commentParts = tag.comment;
+            tagComment = commentParts
+                .map((c) => (c.kind === ts.SyntaxKind.JSDocText ? c.text : ''))
+                .join('')
+                .trim();
+        }
+        if (tagName === 'param' && ts.isJSDocParameterTag(tag)) {
+            const paramName = tag.name.getText(sourceFile);
+            params[paramName] = tagComment;
+        }
+        else if (tagName === 'returns' || tagName === 'return') {
+            doc.returns = tagComment;
+        }
+        else if (tagName === 'throws' || tagName === 'exception') {
+            throws.push(tagComment);
+        }
+        else if (tagName === 'example') {
+            examples.push(tagComment);
+        }
+        else if (tagName === 'see') {
+            see.push(tagComment);
+        }
+        else if (ts.isJSDocDeprecatedTag(tag)) {
+            doc.deprecatedMessage = tagComment || 'This API is deprecated';
+        }
+        else if (tagName === 'since') {
+            doc.since = tagComment;
+        }
+    }
+    if (Object.keys(params).length > 0)
+        doc.params = params;
+    if (throws.length > 0)
+        doc.throws = throws;
+    if (examples.length > 0)
+        doc.examples = examples;
+    if (see.length > 0)
+        doc.see = see;
+    return doc;
+}
+/**
+ * Create customizable getDocumentation tool
+ */
+export function createGetDocumentationTool(options) {
+    return defineTool({
+        name: options?.name ?? 'get_documentation',
+        description: options?.description ?? TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            const modifiedInput = {
+                ...input,
+                maxFiles: input.maxFiles ?? options?.defaultMaxFiles,
+                documentedOnly: input.documentedOnly ?? options?.defaultDocumentedOnly,
+            };
+            return executeGetDocumentation(modifiedInput);
+        },
+    });
+}

package/dist/tools/get-exports.d.ts

@@ -0,0 +1,21 @@
+/**
+ * getExports Tool
+ *
+ * Get all exports from a module.
+ * Uses TypeScript Compiler API for accurate AST analysis.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { GetExportsInput } from './types.js';
+/**
+ * getExports tool - Get all exports from a module
+ */
+export declare const getExportsTool: Tool<GetExportsInput>;
+/**
+ * Factory function to create a customized getExports tool
+ */
+export declare function createGetExportsTool(options?: {
+    /** Default includeReExports */
+    defaultIncludeReExports?: boolean;
+    /** Default resolveReExports */
+    defaultResolveReExports?: boolean;
+}): Tool<GetExportsInput>;