@compilr-dev/agents-coding-ts 0.1.2 → 0.1.4

package/dist/tools/read-symbol.js

@@ -0,0 +1,464 @@
+/**
+ * Smart File Reading Tools
+ *
+ * AST-aware tools that extract specific code elements by name,
+ * returning exact source code without guessing line numbers.
+ *
+ * Tools:
+ * - read_function: Read a function/method by name
+ * - read_class: Read a class by name
+ * - read_type: Read a type/interface by name
+ */
+import * as fs from "node:fs/promises";
+import * as ts from "typescript";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { detectLanguage, isLanguageSupported, } from "../parser/typescript-parser.js";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get script kind from file extension
+ */
+function getScriptKind(filePath) {
+    const ext = filePath.toLowerCase().split(".").pop();
+    switch (ext) {
+        case "ts":
+        case "mts":
+        case "cts":
+            return ts.ScriptKind.TS;
+        case "tsx":
+            return ts.ScriptKind.TSX;
+        case "js":
+        case "mjs":
+        case "cjs":
+            return ts.ScriptKind.JS;
+        case "jsx":
+            return ts.ScriptKind.JSX;
+        default:
+            return ts.ScriptKind.TS;
+    }
+}
+/**
+ * Get the JSDoc comment for a node
+ */
+function getJsDoc(node, sourceFile) {
+    const jsDocNodes = ts.getJSDocCommentsAndTags(node);
+    if (jsDocNodes.length === 0)
+        return undefined;
+    // Get the full text range including JSDoc
+    const firstJsDoc = jsDocNodes[0];
+    const jsDocStart = firstJsDoc.getStart(sourceFile);
+    const nodeStart = node.getStart(sourceFile);
+    if (jsDocStart < nodeStart) {
+        return sourceFile.text.slice(jsDocStart, nodeStart).trim();
+    }
+    return undefined;
+}
+/**
+ * Get line number from character position
+ */
+function getLineNumber(sourceFile, pos) {
+    return sourceFile.getLineAndCharacterOfPosition(pos).line + 1;
+}
+/**
+ * Extract function signature (first line until opening brace or arrow)
+ */
+function extractSignature(content) {
+    // Find the first { or => and take everything before it
+    const braceIndex = content.indexOf("{");
+    const arrowIndex = content.indexOf("=>");
+    let endIndex = content.length;
+    if (braceIndex !== -1)
+        endIndex = Math.min(endIndex, braceIndex);
+    if (arrowIndex !== -1)
+        endIndex = Math.min(endIndex, arrowIndex + 2);
+    return content.slice(0, endIndex).trim();
+}
+/**
+ * Extract class signature (class declaration without body)
+ */
+function extractClassSignature(node, sourceFile) {
+    const start = node.getStart(sourceFile);
+    const bodyStart = node.members.length > 0
+        ? node.members[0].getStart(sourceFile)
+        : node.getEnd();
+    // Find the opening brace
+    let text = sourceFile.text.slice(start, bodyStart);
+    const braceIndex = text.indexOf("{");
+    if (braceIndex !== -1) {
+        text = text.slice(0, braceIndex).trim() + " { ... }";
+    }
+    return text;
+}
+// =============================================================================
+// read_function Tool
+// =============================================================================
+async function executeReadFunction(input) {
+    const { path: filePath, name, className, includeJsDoc = true } = input;
+    if (!filePath || !name) {
+        return createErrorResult("Both path and name are required");
+    }
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        return createErrorResult(`File not found: ${filePath}`);
+    }
+    const detection = detectLanguage(filePath);
+    if (!detection.language || !isLanguageSupported(detection.language)) {
+        return createErrorResult(`Unsupported file type: ${filePath}`);
+    }
+    try {
+        const sourceCode = await fs.readFile(filePath, "utf-8");
+        const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+        // Find the function
+        let foundNode;
+        let containerName;
+        let arrowFunctionStatement;
+        function visit(node) {
+            if (foundNode)
+                return;
+            // Function declaration
+            if (ts.isFunctionDeclaration(node) &&
+                node.name?.getText(sourceFile) === name &&
+                !className) {
+                foundNode = node;
+                return;
+            }
+            // Method in class
+            if (ts.isClassDeclaration(node) && node.name) {
+                const classNameText = node.name.getText(sourceFile);
+                if (!className || classNameText === className) {
+                    for (const member of node.members) {
+                        if (ts.isMethodDeclaration(member) &&
+                            member.name.getText(sourceFile) === name) {
+                            foundNode = member;
+                            containerName = classNameText;
+                            return;
+                        }
+                    }
+                }
+            }
+            // Arrow function assigned to variable
+            if (ts.isVariableStatement(node) && !className) {
+                for (const decl of node.declarationList.declarations) {
+                    if (decl.name.getText(sourceFile) === name &&
+                        decl.initializer &&
+                        ts.isArrowFunction(decl.initializer)) {
+                        foundNode = decl.initializer;
+                        arrowFunctionStatement = node;
+                        return;
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        if (!foundNode) {
+            const searchDesc = className
+                ? `method ${name} in class ${className}`
+                : `function ${name}`;
+            return createErrorResult(`Function not found: ${searchDesc}`);
+        }
+        // For arrow functions, use the full variable statement for content
+        const nodeForContent = arrowFunctionStatement ?? foundNode;
+        // Extract the source code
+        let start = nodeForContent.getStart(sourceFile);
+        const end = nodeForContent.getEnd();
+        // Include JSDoc if requested
+        if (includeJsDoc) {
+            const jsDoc = getJsDoc(nodeForContent, sourceFile);
+            if (jsDoc) {
+                // Find where the JSDoc starts
+                const jsDocStart = sourceFile.text.lastIndexOf("/**", start);
+                if (jsDocStart !== -1 && jsDocStart < start) {
+                    start = jsDocStart;
+                }
+            }
+        }
+        const content = sourceFile.text.slice(start, end);
+        const startLine = getLineNumber(sourceFile, start);
+        const endLine = getLineNumber(sourceFile, end);
+        const result = {
+            name,
+            kind: containerName ? "method" : "function",
+            startLine,
+            endLine,
+            content,
+            signature: extractSignature(content),
+            container: containerName,
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(`Failed to read function: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export const readFunctionTool = defineTool({
+    name: "read_function",
+    description: "Read a specific function or method by name. Returns the exact source code without guessing line numbers. " +
+        "Use this instead of read_file when you need to see a specific function. " +
+        "For methods, specify the className parameter.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute path to the file",
+            },
+            name: {
+                type: "string",
+                description: "Function or method name to read",
+            },
+            className: {
+                type: "string",
+                description: "Class name if reading a method (optional)",
+            },
+            includeJsDoc: {
+                type: "boolean",
+                description: "Include JSDoc comment (default: true)",
+            },
+        },
+        required: ["path", "name"],
+    },
+    execute: executeReadFunction,
+});
+// =============================================================================
+// read_class Tool
+// =============================================================================
+async function executeReadClass(input) {
+    const { path: filePath, name, include = "full", includeJsDoc = true } = input;
+    if (!filePath || !name) {
+        return createErrorResult("Both path and name are required");
+    }
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        return createErrorResult(`File not found: ${filePath}`);
+    }
+    const detection = detectLanguage(filePath);
+    if (!detection.language || !isLanguageSupported(detection.language)) {
+        return createErrorResult(`Unsupported file type: ${filePath}`);
+    }
+    try {
+        const sourceCode = await fs.readFile(filePath, "utf-8");
+        const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+        // Find the class
+        let foundNode;
+        function visit(node) {
+            if (foundNode)
+                return;
+            if (ts.isClassDeclaration(node) &&
+                node.name?.getText(sourceFile) === name) {
+                foundNode = node;
+                return;
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        if (!foundNode) {
+            return createErrorResult(`Class not found: ${name}`);
+        }
+        let start = foundNode.getStart(sourceFile);
+        const end = foundNode.getEnd();
+        // Include JSDoc if requested
+        if (includeJsDoc) {
+            const jsDoc = getJsDoc(foundNode, sourceFile);
+            if (jsDoc) {
+                const jsDocStart = sourceFile.text.lastIndexOf("/**", start);
+                if (jsDocStart !== -1 && jsDocStart < start) {
+                    start = jsDocStart;
+                }
+            }
+        }
+        let content;
+        if (include === "full") {
+            content = sourceCode.slice(start, end);
+        }
+        else if (include === "signature") {
+            content = extractClassSignature(foundNode, sourceFile);
+        }
+        else if (include === "methods-only") {
+            const methods = [];
+            for (const member of foundNode.members) {
+                if (ts.isMethodDeclaration(member)) {
+                    const memberStart = member.getStart(sourceFile);
+                    const memberEnd = member.getEnd();
+                    methods.push(sourceCode.slice(memberStart, memberEnd));
+                }
+            }
+            content = methods.join("\n\n");
+        }
+        else {
+            // include === 'properties-only'
+            const props = [];
+            for (const member of foundNode.members) {
+                if (ts.isPropertyDeclaration(member)) {
+                    const memberStart = member.getStart(sourceFile);
+                    const memberEnd = member.getEnd();
+                    props.push(sourceCode.slice(memberStart, memberEnd));
+                }
+            }
+            content = props.join("\n");
+        }
+        const startLine = getLineNumber(sourceFile, start);
+        const endLine = getLineNumber(sourceFile, end);
+        const result = {
+            name,
+            kind: "class",
+            startLine,
+            endLine,
+            content,
+            signature: extractClassSignature(foundNode, sourceFile),
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(`Failed to read class: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export const readClassTool = defineTool({
+    name: "read_class",
+    description: "Read a specific class by name. Returns the exact source code without guessing line numbers. " +
+        "Use the include parameter to get: full class, signature only, methods only, or properties only.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute path to the file",
+            },
+            name: {
+                type: "string",
+                description: "Class name to read",
+            },
+            include: {
+                type: "string",
+                enum: ["full", "signature", "methods-only", "properties-only"],
+                description: "What to include (default: full)",
+            },
+            includeJsDoc: {
+                type: "boolean",
+                description: "Include JSDoc comment (default: true)",
+            },
+        },
+        required: ["path", "name"],
+    },
+    execute: executeReadClass,
+});
+// =============================================================================
+// read_type Tool
+// =============================================================================
+async function executeReadType(input) {
+    const { path: filePath, name, includeJsDoc = true } = input;
+    if (!filePath || !name) {
+        return createErrorResult("Both path and name are required");
+    }
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        return createErrorResult(`File not found: ${filePath}`);
+    }
+    const detection = detectLanguage(filePath);
+    if (!detection.language || !isLanguageSupported(detection.language)) {
+        return createErrorResult(`Unsupported file type: ${filePath}`);
+    }
+    try {
+        const sourceCode = await fs.readFile(filePath, "utf-8");
+        const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true, getScriptKind(filePath));
+        // Find the type/interface/enum
+        let foundNode;
+        let kind = "type";
+        function visit(node) {
+            if (foundNode)
+                return;
+            if (ts.isInterfaceDeclaration(node) &&
+                node.name.getText(sourceFile) === name) {
+                foundNode = node;
+                kind = "interface";
+                return;
+            }
+            if (ts.isTypeAliasDeclaration(node) &&
+                node.name.getText(sourceFile) === name) {
+                foundNode = node;
+                kind = "type";
+                return;
+            }
+            if (ts.isEnumDeclaration(node) &&
+                node.name.getText(sourceFile) === name) {
+                foundNode = node;
+                kind = "enum";
+                return;
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        if (!foundNode) {
+            return createErrorResult(`Type/interface/enum not found: ${name}`);
+        }
+        let start = foundNode.getStart(sourceFile);
+        const end = foundNode.getEnd();
+        // Include JSDoc if requested
+        if (includeJsDoc) {
+            const jsDoc = getJsDoc(foundNode, sourceFile);
+            if (jsDoc) {
+                const jsDocStart = sourceFile.text.lastIndexOf("/**", start);
+                if (jsDocStart !== -1 && jsDocStart < start) {
+                    start = jsDocStart;
+                }
+            }
+        }
+        const content = sourceCode.slice(start, end);
+        const startLine = getLineNumber(sourceFile, start);
+        const endLine = getLineNumber(sourceFile, end);
+        const result = {
+            name,
+            kind,
+            startLine,
+            endLine,
+            content,
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(`Failed to read type: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export const readTypeTool = defineTool({
+    name: "read_type",
+    description: "Read a specific type, interface, or enum by name. Returns the exact source code without guessing line numbers. " +
+        "Works for TypeScript interfaces, type aliases, and enums.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute path to the file",
+            },
+            name: {
+                type: "string",
+                description: "Type, interface, or enum name to read",
+            },
+            includeJsDoc: {
+                type: "boolean",
+                description: "Include JSDoc comment (default: true)",
+            },
+        },
+        required: ["path", "name"],
+    },
+    execute: executeReadType,
+});
+// =============================================================================
+// Factory Functions
+// =============================================================================
+export function createReadFunctionTool() {
+    return readFunctionTool;
+}
+export function createReadClassTool() {
+    return readClassTool;
+}
+export function createReadTypeTool() {
+    return readTypeTool;
+}

package/dist/tools/types.d.ts

@@ -7,7 +7,7 @@
 /**
  * Supported languages for analysis
  */
-export type SupportedLanguage = 'typescript' | 'javascript';
+export type SupportedLanguage = "typescript" | "javascript";
 /**
  * Parameter information for functions/methods
  */
@@ -116,7 +116,7 @@ export interface MethodInfo {
     /** Method name */
     name: string;
     /** Visibility */
-    visibility: 'public' | 'private' | 'protected';
+    visibility: "public" | "private" | "protected";
     /** Is async */
     async: boolean;
     /** Is static */
@@ -135,7 +135,7 @@ export interface PropertyInfo {
     /** Type annotation */
     type?: string;
     /** Visibility */
-    visibility: 'public' | 'private' | 'protected';
+    visibility: "public" | "private" | "protected";
     /** Is static */
     static: boolean;
     /** Is readonly */
@@ -148,7 +148,7 @@ export interface VariableInfo {
     /** Variable name */
     name: string;
     /** Declaration kind */
-    kind: 'const' | 'let' | 'var';
+    kind: "const" | "let" | "var";
     /** Type annotation */
     type?: string;
     /** Is exported */
@@ -161,7 +161,7 @@ export interface TypeDefinitionInfo {
     /** Type name */
     name: string;
     /** Kind of type definition */
-    kind: 'interface' | 'type' | 'enum';
+    kind: "interface" | "type" | "enum";
     /** Is exported */
     exported: boolean;
 }
@@ -194,11 +194,11 @@ export interface ExtractorOptions {
 /**
  * Symbol kind for filtering
  */
-export type SymbolKind = 'function' | 'class' | 'variable' | 'type' | 'interface' | 'enum' | 'method' | 'property';
+export type SymbolKind = "function" | "class" | "variable" | "type" | "interface" | "enum" | "method" | "property";
 /**
  * Symbol kind filter (includes 'any' for no filtering)
  */
-export type SymbolKindFilter = SymbolKind | 'any';
+export type SymbolKindFilter = SymbolKind | "any";
 /**
  * Input for findSymbol tool
  */
@@ -262,7 +262,7 @@ export interface FindSymbolResult {
 /**
  * Reference type - how the symbol is used
  */
-export type ReferenceType = 'read' | 'write' | 'call' | 'import' | 'export' | 'type' | 'extend' | 'implement';
+export type ReferenceType = "read" | "write" | "call" | "import" | "export" | "type" | "extend" | "implement";
 /**
  * Input for findReferences tool
  */
@@ -427,7 +427,7 @@ export interface GetExportsInput {
 /**
  * Kind of exported symbol
  */
-export type ExportKind = 'function' | 'class' | 'variable' | 'type' | 'interface' | 'enum' | 'namespace' | 'unknown';
+export type ExportKind = "function" | "class" | "variable" | "type" | "interface" | "enum" | "namespace" | "unknown";
 /**
  * An exported symbol
  */
@@ -450,7 +450,7 @@ export interface ExportedSymbol {
  */
 export interface ReExport {
     /** What is being re-exported ('*' for all) */
-    symbols: string[] | '*';
+    symbols: string[] | "*";
     /** Source module */
     from: string;
     /** Resolved absolute path (for local modules) */
@@ -495,11 +495,11 @@ export interface GetExportsResult {
 /**
  * Direction for call graph traversal
  */
-export type CallGraphDirection = 'callers' | 'callees' | 'both';
+export type CallGraphDirection = "callers" | "callees" | "both";
 /**
  * Type of function call
  */
-export type CallType = 'direct' | 'callback' | 'promise' | 'event' | 'method';
+export type CallType = "direct" | "callback" | "promise" | "event" | "method";
 /**
  * Input for getCallGraph tool
  */
@@ -627,7 +627,7 @@ export interface DependencyEdge {
     /** Target module */
     to: string;
     /** Import type */
-    importType: 'named' | 'default' | 'namespace' | 'side-effect';
+    importType: "named" | "default" | "namespace" | "side-effect";
     /** Is type-only import */
     typeOnly: boolean;
     /** Number of symbols imported */
@@ -712,7 +712,7 @@ export interface ImplementationInfo {
     /** Column number (1-based) */
     column: number;
     /** Kind of implementation */
-    kind: 'class' | 'type' | 'object';
+    kind: "class" | "type" | "object";
     /** Is abstract (partial implementation) */
     isAbstract?: boolean;
     /** Is exported */
@@ -745,7 +745,7 @@ export interface FindImplementationsResult {
 /**
  * Direction for type hierarchy traversal
  */
-export type HierarchyDirection = 'ancestors' | 'descendants' | 'both';
+export type HierarchyDirection = "ancestors" | "descendants" | "both";
 /**
  * Input for getTypeHierarchy tool
  */
@@ -772,7 +772,7 @@ export interface TypeHierarchyNode {
     /** Line number (1-based) */
     line: number;
     /** Kind of type */
-    kind: 'class' | 'interface' | 'type';
+    kind: "class" | "interface" | "type";
     /** Is abstract */
     isAbstract?: boolean;
     /** Is exported */
@@ -815,7 +815,7 @@ export interface GetComplexityInput {
 /**
  * Complexity contributor type
  */
-export type ComplexityContributorType = 'if' | 'else' | 'switch' | 'case' | 'for' | 'while' | 'do' | 'catch' | 'ternary' | 'logical_and' | 'logical_or' | 'nullish' | 'nesting';
+export type ComplexityContributorType = "if" | "else" | "switch" | "case" | "for" | "while" | "do" | "catch" | "ternary" | "logical_and" | "logical_or" | "nullish" | "nesting";
 /**
  * A contributor to complexity score
  */
@@ -930,11 +930,11 @@ export interface DeadCodeItem {
     /** Line number */
     line: number;
     /** Kind of symbol */
-    kind: 'function' | 'class' | 'variable' | 'type' | 'interface' | 'enum' | 'export';
+    kind: "function" | "class" | "variable" | "type" | "interface" | "enum" | "export";
     /** Is exported */
     exported: boolean;
     /** Confidence level */
-    confidence: 'high' | 'medium' | 'low';
+    confidence: "high" | "medium" | "low";
     /** Reason for flagging */
     reason: string;
 }
@@ -1023,11 +1023,11 @@ export interface CodePattern {
     /** Description */
     description: string;
     /** Pattern type */
-    type: 'anti-pattern' | 'pattern' | 'smell';
+    type: "anti-pattern" | "pattern" | "smell";
     /** AST pattern or regex */
     matcher: string;
     /** Severity */
-    severity: 'error' | 'warning' | 'info';
+    severity: "error" | "warning" | "info";
 }
 /**
  * Input for findPatterns tool
@@ -1038,7 +1038,7 @@ export interface FindPatternsInput {
     /** Patterns to search for (uses built-in if not specified) */
     patterns?: CodePattern[];
     /** Pattern categories to include */
-    categories?: Array<'security' | 'performance' | 'maintainability' | 'all'>;
+    categories?: Array<"security" | "performance" | "maintainability" | "all">;
     /** Maximum files to analyze (default: 100) */
     maxFiles?: number;
 }
@@ -1051,7 +1051,7 @@ export interface PatternMatch {
     /** Pattern description */
     description: string;
     /** Severity */
-    severity: 'error' | 'warning' | 'info';
+    severity: "error" | "warning" | "info";
     /** File path */
     path: string;
     /** Line number */
@@ -1169,7 +1169,7 @@ export interface MemberSignature {
     /** Member name */
     name: string;
     /** Member kind */
-    kind: 'property' | 'method' | 'getter' | 'setter';
+    kind: "property" | "method" | "getter" | "setter";
     /** Signature string */
     signature: string;
     /** Is optional */
@@ -1177,14 +1177,14 @@ export interface MemberSignature {
     /** Is readonly */
     readonly: boolean;
     /** Visibility */
-    visibility?: 'public' | 'private' | 'protected';
+    visibility?: "public" | "private" | "protected";
     /** Is static */
     static?: boolean;
 }
 /**
  * Symbol kind for signature
  */
-export type SignatureSymbolKind = 'function' | 'method' | 'class' | 'interface' | 'type' | 'enum' | 'variable';
+export type SignatureSymbolKind = "function" | "method" | "class" | "interface" | "type" | "enum" | "variable";
 /**
  * Output from getSignature tool
  */
@@ -1219,7 +1219,7 @@ export interface GetSignatureResult {
 /**
  * Symbol kind for documentation extraction
  */
-export type DocumentationSymbolKind = 'function' | 'class' | 'interface' | 'type' | 'enum' | 'variable' | 'method' | 'property';
+export type DocumentationSymbolKind = "function" | "class" | "interface" | "type" | "enum" | "variable" | "method" | "property";
 /**
  * Input for getDocumentation tool
  */