@compilr-dev/agents-coding-ts 0.1.0

package/dist/tools/get-type-hierarchy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * getTypeHierarchy Tool
+ *
+ * Analyze the inheritance hierarchy of a class or interface.
+ * Shows ancestors (parents) and descendants (children) in the type tree.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { GetTypeHierarchyInput, HierarchyDirection } from './types.js';
+/**
+ * getTypeHierarchy tool - Analyze type inheritance
+ */
+export declare const getTypeHierarchyTool: Tool<GetTypeHierarchyInput>;
+/**
+ * Create customizable getTypeHierarchy tool
+ */
+export declare function createGetTypeHierarchyTool(options?: {
+    name?: string;
+    description?: string;
+    defaultDirection?: HierarchyDirection;
+    defaultMaxDepth?: number;
+    defaultScope?: string;
+}): Tool<GetTypeHierarchyInput>;

package/dist/tools/get-type-hierarchy.js

@@ -0,0 +1,485 @@
+/**
+ * getTypeHierarchy Tool
+ *
+ * Analyze the inheritance hierarchy of a class or interface.
+ * Shows ancestors (parents) and descendants (children) in the type tree.
+ */
+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 = `Analyze the inheritance hierarchy of a class or interface.
+Returns the type's ancestors (what it extends/implements) and descendants (what extends/implements it).
+Useful for understanding class hierarchies and interface relationships.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        name: {
+            type: 'string',
+            description: 'Class or interface name to analyze',
+        },
+        file: {
+            type: 'string',
+            description: 'File where the type is defined (improves accuracy)',
+        },
+        direction: {
+            type: 'string',
+            enum: ['ancestors', 'descendants', 'both'],
+            description: 'Direction: "ancestors" | "descendants" | "both" (default: "both")',
+            default: 'both',
+        },
+        maxDepth: {
+            type: 'number',
+            description: 'Maximum depth to traverse (default: 5)',
+            default: 5,
+        },
+        scope: {
+            type: 'string',
+            description: 'Scope directory for searching descendants (default: current directory)',
+        },
+    },
+    required: ['name'],
+};
+// Default file patterns
+const DEFAULT_INCLUDE = ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'];
+const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'];
+/**
+ * getTypeHierarchy tool - Analyze type inheritance
+ */
+export const getTypeHierarchyTool = defineTool({
+    name: 'get_type_hierarchy',
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetTypeHierarchy,
+});
+/**
+ * Execute the getTypeHierarchy tool
+ */
+async function executeGetTypeHierarchy(input) {
+    const { name, file, direction = 'both', maxDepth = 5, scope = '.' } = input;
+    // Validate input
+    if (!name || name.trim().length === 0) {
+        return createErrorResult('Type name is required');
+    }
+    try {
+        // Resolve scope path
+        const scopePath = path.resolve(scope);
+        // Check if scope exists
+        try {
+            await fs.access(scopePath);
+        }
+        catch {
+            return createErrorResult(`Scope path not found: ${scopePath}`);
+        }
+        const stats = await fs.stat(scopePath);
+        // Collect files to search
+        const files = stats.isDirectory()
+            ? await collectFiles(scopePath, DEFAULT_INCLUDE, DEFAULT_EXCLUDE, 10, 500)
+            : [scopePath];
+        // Build type information map
+        const typeMap = new Map();
+        let filesSearched = 0;
+        for (const filePath of files) {
+            const types = await extractTypeInfo(filePath);
+            filesSearched++;
+            for (const typeInfo of types) {
+                // If there's a specific file, prioritize that definition
+                if (typeInfo.name === name && file && filePath === path.resolve(file)) {
+                    typeMap.set(typeInfo.name, typeInfo);
+                }
+                else if (!typeMap.has(typeInfo.name)) {
+                    typeMap.set(typeInfo.name, typeInfo);
+                }
+            }
+        }
+        // Find the target type
+        let targetType = typeMap.get(name);
+        // If file is specified, try to find in that specific file
+        if (file) {
+            const resolvedFile = path.resolve(file);
+            try {
+                await fs.access(resolvedFile);
+                const types = await extractTypeInfo(resolvedFile);
+                const foundType = types.find((t) => t.name === name);
+                if (foundType) {
+                    targetType = foundType;
+                }
+            }
+            catch {
+                // Ignore file access error
+            }
+        }
+        if (!targetType) {
+            // Return empty result if type not found
+            const emptyRoot = {
+                name,
+                path: '',
+                line: 0,
+                kind: 'class',
+                exported: false,
+            };
+            const result = {
+                root: emptyRoot,
+                allTypes: [],
+                stats: {
+                    totalTypes: 0,
+                    maxDepthReached: 0,
+                    filesSearched,
+                },
+            };
+            return createSuccessResult(result);
+        }
+        // Build hierarchy based on direction
+        const allTypes = [];
+        let maxDepthReached = 0;
+        const rootNode = createTypeNode(targetType);
+        if (direction === 'ancestors' || direction === 'both') {
+            const { ancestors, depth } = buildAncestors(targetType, typeMap, maxDepth, 0);
+            rootNode.parents = ancestors;
+            if (depth > maxDepthReached)
+                maxDepthReached = depth;
+        }
+        if (direction === 'descendants' || direction === 'both') {
+            const { descendants, depth } = buildDescendants(targetType, typeMap, maxDepth, 0);
+            rootNode.children = descendants;
+            if (depth > maxDepthReached)
+                maxDepthReached = depth;
+        }
+        // Collect all types in the hierarchy
+        collectAllTypes(rootNode, allTypes);
+        const result = {
+            root: rootNode,
+            allTypes,
+            stats: {
+                totalTypes: allTypes.length,
+                maxDepthReached,
+                filesSearched,
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(`Failed to get type hierarchy: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Create a TypeHierarchyNode from TypeInfo
+ */
+function createTypeNode(info) {
+    return {
+        name: info.name,
+        path: info.path,
+        line: info.line,
+        kind: info.kind,
+        isAbstract: info.isAbstract,
+        exported: info.exported,
+    };
+}
+/**
+ * Build ancestor hierarchy (parents, grandparents, etc.)
+ */
+function buildAncestors(type, typeMap, maxDepth, currentDepth) {
+    if (currentDepth >= maxDepth) {
+        return { ancestors: [], depth: currentDepth };
+    }
+    const ancestors = [];
+    let maxDepthReached = currentDepth;
+    // Get parent types from extends and implements
+    const parentNames = [];
+    if (type.extends) {
+        parentNames.push(...type.extends);
+    }
+    if (type.implements) {
+        parentNames.push(...type.implements);
+    }
+    for (const parentName of parentNames) {
+        const parentInfo = typeMap.get(parentName);
+        if (parentInfo) {
+            const parentNode = createTypeNode(parentInfo);
+            // Recursively build ancestors for this parent
+            const { ancestors: grandparents, depth } = buildAncestors(parentInfo, typeMap, maxDepth, currentDepth + 1);
+            if (grandparents.length > 0) {
+                parentNode.parents = grandparents;
+            }
+            if (depth > maxDepthReached) {
+                maxDepthReached = depth;
+            }
+            ancestors.push(parentNode);
+        }
+        else {
+            // External type (not found in codebase)
+            ancestors.push({
+                name: parentName,
+                path: '',
+                line: 0,
+                kind: 'interface', // Assume interface for unknown types
+                exported: true,
+            });
+        }
+    }
+    return { ancestors, depth: maxDepthReached };
+}
+/**
+ * Build descendant hierarchy (children, grandchildren, etc.)
+ */
+function buildDescendants(type, typeMap, maxDepth, currentDepth) {
+    if (currentDepth >= maxDepth) {
+        return { descendants: [], depth: currentDepth };
+    }
+    const descendants = [];
+    let maxDepthReached = currentDepth;
+    // Find all types that extend or implement this type
+    for (const [, info] of typeMap) {
+        const isChild = (info.extends && info.extends.includes(type.name)) ||
+            (info.implements && info.implements.includes(type.name));
+        if (isChild) {
+            const childNode = createTypeNode(info);
+            // Recursively build descendants for this child
+            const { descendants: grandchildren, depth } = buildDescendants(info, typeMap, maxDepth, currentDepth + 1);
+            if (grandchildren.length > 0) {
+                childNode.children = grandchildren;
+            }
+            if (depth > maxDepthReached) {
+                maxDepthReached = depth;
+            }
+            descendants.push(childNode);
+        }
+    }
+    return { descendants, depth: maxDepthReached };
+}
+/**
+ * Collect all types from the hierarchy tree into a flat list
+ */
+function collectAllTypes(node, allTypes) {
+    // Avoid duplicates
+    if (!allTypes.find((t) => t.name === node.name && t.path === node.path)) {
+        // Create a copy without circular references for the flat list
+        const flatNode = {
+            name: node.name,
+            path: node.path,
+            line: node.line,
+            kind: node.kind,
+            isAbstract: node.isAbstract,
+            exported: node.exported,
+        };
+        allTypes.push(flatNode);
+    }
+    // Recursively collect from parents
+    if (node.parents) {
+        for (const parent of node.parents) {
+            collectAllTypes(parent, allTypes);
+        }
+    }
+    // Recursively collect from children
+    if (node.children) {
+        for (const child of node.children) {
+            collectAllTypes(child, allTypes);
+        }
+    }
+}
+/**
+ * Extract type information from a file
+ */
+async function extractTypeInfo(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const detection = detectLanguage(filePath);
+        if (!detection.language) {
+            return [];
+        }
+        if (!isLanguageSupported(detection.language)) {
+            return [];
+        }
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, filePath.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        const types = [];
+        const visit = (node) => {
+            // Class declarations
+            if (ts.isClassDeclaration(node) && node.name) {
+                const info = extractClassInfo(node, sourceFile, filePath);
+                if (info)
+                    types.push(info);
+            }
+            // Interface declarations
+            if (ts.isInterfaceDeclaration(node)) {
+                const info = extractInterfaceInfo(node, sourceFile, filePath);
+                if (info)
+                    types.push(info);
+            }
+            // Type alias declarations (only if they reference other types)
+            if (ts.isTypeAliasDeclaration(node)) {
+                const info = extractTypeAliasInfo(node, sourceFile, filePath);
+                if (info)
+                    types.push(info);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        return types;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Extract class type info
+ */
+function extractClassInfo(node, sourceFile, filePath) {
+    if (!node.name)
+        return null;
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    const isExported = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    const isAbstract = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.AbstractKeyword) ?? false;
+    const extendsTypes = [];
+    const implementsTypes = [];
+    if (node.heritageClauses) {
+        for (const clause of node.heritageClauses) {
+            if (clause.token === ts.SyntaxKind.ExtendsKeyword) {
+                for (const type of clause.types) {
+                    extendsTypes.push(type.expression.getText());
+                }
+            }
+            if (clause.token === ts.SyntaxKind.ImplementsKeyword) {
+                for (const type of clause.types) {
+                    implementsTypes.push(type.expression.getText());
+                }
+            }
+        }
+    }
+    return {
+        name: node.name.text,
+        path: filePath,
+        line: line + 1,
+        kind: 'class',
+        isAbstract,
+        exported: isExported,
+        extends: extendsTypes.length > 0 ? extendsTypes : undefined,
+        implements: implementsTypes.length > 0 ? implementsTypes : undefined,
+    };
+}
+/**
+ * Extract interface type info
+ */
+function extractInterfaceInfo(node, sourceFile, filePath) {
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    const isExported = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    const extendsTypes = [];
+    if (node.heritageClauses) {
+        for (const clause of node.heritageClauses) {
+            if (clause.token === ts.SyntaxKind.ExtendsKeyword) {
+                for (const type of clause.types) {
+                    extendsTypes.push(type.expression.getText());
+                }
+            }
+        }
+    }
+    return {
+        name: node.name.text,
+        path: filePath,
+        line: line + 1,
+        kind: 'interface',
+        exported: isExported,
+        extends: extendsTypes.length > 0 ? extendsTypes : undefined,
+    };
+}
+/**
+ * Extract type alias info (for types that extend others via intersection)
+ */
+function extractTypeAliasInfo(node, sourceFile, filePath) {
+    const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    const isExported = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    // Extract types from intersection type
+    const extendsTypes = [];
+    if (ts.isIntersectionTypeNode(node.type)) {
+        for (const type of node.type.types) {
+            if (ts.isTypeReferenceNode(type)) {
+                extendsTypes.push(type.typeName.getText());
+            }
+        }
+    }
+    else if (ts.isTypeReferenceNode(node.type)) {
+        // Direct type reference (type Foo = Bar)
+        extendsTypes.push(node.type.typeName.getText());
+    }
+    // Only include if it references other types
+    if (extendsTypes.length === 0) {
+        return null;
+    }
+    return {
+        name: node.name.text,
+        path: filePath,
+        line: line + 1,
+        kind: 'type',
+        exported: isExported,
+        extends: extendsTypes,
+    };
+}
+/**
+ * Collect files matching patterns
+ */
+async function collectFiles(dirPath, include, exclude, maxDepth, maxFiles, currentDepth = 0) {
+    if (currentDepth > maxDepth)
+        return [];
+    const files = [];
+    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);
+            const relativePath = fullPath;
+            // Check exclusions
+            const isExcluded = exclude.some((pattern) => {
+                if (pattern.includes('**')) {
+                    const simplePattern = pattern.replace(/\*\*/g, '');
+                    return relativePath.includes(simplePattern.replace(/\*/g, ''));
+                }
+                return entry.name === pattern || relativePath.includes(pattern);
+            });
+            if (isExcluded)
+                continue;
+            if (entry.isDirectory()) {
+                const subFiles = await collectFiles(fullPath, include, exclude, maxDepth, maxFiles - files.length, currentDepth + 1);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile()) {
+                // Check if file matches include patterns
+                const isIncluded = include.some((pattern) => {
+                    if (pattern.includes('*')) {
+                        const ext = pattern.replace('**/', '').replace('*', '');
+                        return entry.name.endsWith(ext);
+                    }
+                    return entry.name === pattern;
+                });
+                if (isIncluded) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore permission errors
+    }
+    return files;
+}
+/**
+ * Create customizable getTypeHierarchy tool
+ */
+export function createGetTypeHierarchyTool(options) {
+    return defineTool({
+        name: options?.name ?? 'get_type_hierarchy',
+        description: options?.description ?? TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            const modifiedInput = {
+                ...input,
+                direction: input.direction ?? options?.defaultDirection,
+                maxDepth: input.maxDepth ?? options?.defaultMaxDepth,
+                scope: input.scope ?? options?.defaultScope,
+            };
+            return executeGetTypeHierarchy(modifiedInput);
+        },
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Source Code Analysis Tools
+ *
+ * Tools for analyzing source code structure using TypeScript Compiler API.
+ * These tools reduce token usage by returning structured JSON
+ * instead of requiring the agent to read and reason through raw code.
+ */
+export { getFileStructureTool, createGetFileStructureTool } from './get-file-structure.js';
+export { findSymbolTool, createFindSymbolTool } from './find-symbol.js';
+export { findReferencesTool, createFindReferencesTool } from './find-references.js';
+export { getImportsTool, createGetImportsTool } from './get-imports.js';
+export { getExportsTool, createGetExportsTool } from './get-exports.js';
+export { getCallGraphTool, createGetCallGraphTool } from './get-call-graph.js';
+export { getDependencyGraphTool, createGetDependencyGraphTool } from './get-dependency-graph.js';
+export { findImplementationsTool, createFindImplementationsTool } from './find-implementations.js';
+export { getTypeHierarchyTool, createGetTypeHierarchyTool } from './get-type-hierarchy.js';
+export { getComplexityTool, createGetComplexityTool } from './get-complexity.js';
+export { findDeadCodeTool, createFindDeadCodeTool } from './find-dead-code.js';
+export { findDuplicatesTool, createFindDuplicatesTool } from './find-duplicates.js';
+export { findPatternsTool, createFindPatternsTool } from './find-patterns.js';
+export { getSignatureTool, createGetSignatureTool } from './get-signature.js';
+export { getDocumentationTool, createGetDocumentationTool } from './get-documentation.js';
+export type { SupportedLanguage, ParameterInfo, GetFileStructureInput, FileStructure, ImportInfo, ExportInfo, ClassInfo, FunctionInfo, MethodInfo, PropertyInfo, VariableInfo, TypeDefinitionInfo, FileStats, SymbolKind, SymbolKindFilter, FindSymbolInput, FindSymbolResult, SymbolDefinition, SearchStats, ReferenceType, FindReferencesInput, FindReferencesResult, Reference, FileReferences, GetImportsInput, GetImportsResult, DetailedImport, ImportedSymbol, TransitiveImport, ImportStats, GetExportsInput, GetExportsResult, ExportedSymbol, ExportKind, ReExport, ExportStats, CallGraphDirection, CallType, GetCallGraphInput, GetCallGraphResult, FunctionNode, CallInfo, CallGraphNode, CallGraphStats, GetDependencyGraphInput, GetDependencyGraphResult, ModuleNode, DependencyEdge, CircularDependency, DependencyGraphStats, FindImplementationsInput, FindImplementationsResult, ImplementationInfo, HierarchyDirection, GetTypeHierarchyInput, GetTypeHierarchyResult, TypeHierarchyNode, GetComplexityInput, GetComplexityResult, FileComplexity, FunctionComplexity, ComplexityContributor, ComplexityContributorType, FindDeadCodeInput, FindDeadCodeResult, DeadCodeItem, FindDuplicatesInput, FindDuplicatesResult, DuplicateGroup, CodeLocation, FindPatternsInput, FindPatternsResult, PatternMatch, CodePattern, GetSignatureInput, GetSignatureResult, ParameterDetail, TypeDetail, GenericDetail, Documentation, MemberSignature, SignatureSymbolKind, GetDocumentationInput, GetDocumentationResult, FileDocumentation, DocumentedSymbol, DocumentationSymbolKind, ExtractorOptions, } from './types.js';

package/dist/tools/index.js

@@ -0,0 +1,25 @@
+/**
+ * Source Code Analysis Tools
+ *
+ * Tools for analyzing source code structure using TypeScript Compiler API.
+ * These tools reduce token usage by returning structured JSON
+ * instead of requiring the agent to read and reason through raw code.
+ */
+// Tier 1 & 2 Tools
+export { getFileStructureTool, createGetFileStructureTool } from './get-file-structure.js';
+export { findSymbolTool, createFindSymbolTool } from './find-symbol.js';
+export { findReferencesTool, createFindReferencesTool } from './find-references.js';
+export { getImportsTool, createGetImportsTool } from './get-imports.js';
+export { getExportsTool, createGetExportsTool } from './get-exports.js';
+export { getCallGraphTool, createGetCallGraphTool } from './get-call-graph.js';
+export { getDependencyGraphTool, createGetDependencyGraphTool } from './get-dependency-graph.js';
+export { findImplementationsTool, createFindImplementationsTool } from './find-implementations.js';
+export { getTypeHierarchyTool, createGetTypeHierarchyTool } from './get-type-hierarchy.js';
+// Tier 3 Tools
+export { getComplexityTool, createGetComplexityTool } from './get-complexity.js';
+export { findDeadCodeTool, createFindDeadCodeTool } from './find-dead-code.js';
+export { findDuplicatesTool, createFindDuplicatesTool } from './find-duplicates.js';
+export { findPatternsTool, createFindPatternsTool } from './find-patterns.js';
+// Tier 4 Utility Tools
+export { getSignatureTool, createGetSignatureTool } from './get-signature.js';
+export { getDocumentationTool, createGetDocumentationTool } from './get-documentation.js';