@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/extract-docstrings.js

@@ -0,0 +1,575 @@
+/**
+ * extractDocstrings Tool
+ *
+ * Extract and parse docstrings from Python files.
+ * Supports Google, NumPy, Sphinx, and Epytext formats.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { parseFile, parseFunction, parseClass, parseDecorators, extractDocstring, } from "../parser/python-parser.js";
+// Tool description
+const TOOL_DESCRIPTION = `Extract and parse docstrings from Python files.
+Supports Google, NumPy, Sphinx, and Epytext docstring formats.
+Returns structured documentation with parameters, returns, raises, and examples.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "File or directory to analyze",
+        },
+        recursive: {
+            type: "boolean",
+            description: "Recursively analyze directory (default: false)",
+            default: false,
+        },
+        kinds: {
+            type: "array",
+            items: {
+                type: "string",
+                enum: ["function", "class", "method", "module"],
+            },
+            description: "Filter by symbol kinds",
+        },
+        documentedOnly: {
+            type: "boolean",
+            description: "Only include documented symbols (default: false)",
+            default: false,
+        },
+        maxFiles: {
+            type: "number",
+            description: "Maximum files to analyze (default: 50)",
+            default: 50,
+        },
+    },
+    required: ["path"],
+};
+/**
+ * extractDocstrings tool - Extract Python documentation
+ */
+export const extractDocstringsTool = defineTool({
+    name: "extract_docstrings_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeExtractDocstrings,
+});
+/**
+ * Execute the extractDocstrings tool
+ */
+async function executeExtractDocstrings(input) {
+    const { path: targetPath, recursive = false, kinds, documentedOnly = false, maxFiles = 50, } = input;
+    const resolvedPath = path.resolve(targetPath);
+    try {
+        await fs.access(resolvedPath);
+    }
+    catch {
+        return createErrorResult(`Path not found: ${resolvedPath}`);
+    }
+    const stats = await fs.stat(resolvedPath);
+    try {
+        const files = [];
+        if (stats.isFile()) {
+            if (!resolvedPath.endsWith(".py") && !resolvedPath.endsWith(".pyi")) {
+                return createErrorResult(`Not a Python file: ${resolvedPath}`);
+            }
+            const fileDoc = await analyzeFileDocumentation(resolvedPath, kinds, documentedOnly);
+            files.push(fileDoc);
+        }
+        else if (stats.isDirectory()) {
+            const pythonFiles = await collectPythonFiles(resolvedPath, recursive, maxFiles);
+            for (const filePath of pythonFiles) {
+                const fileDoc = await analyzeFileDocumentation(filePath, kinds, documentedOnly);
+                files.push(fileDoc);
+            }
+        }
+        // Calculate summary
+        let totalSymbols = 0;
+        let documentedSymbols = 0;
+        for (const file of files) {
+            totalSymbols += file.stats.totalSymbols;
+            documentedSymbols += file.stats.documentedSymbols;
+        }
+        const result = {
+            path: resolvedPath,
+            files,
+            summary: {
+                totalFiles: files.length,
+                totalSymbols,
+                documentedSymbols,
+                undocumentedSymbols: totalSymbols - documentedSymbols,
+                coveragePercent: totalSymbols > 0 ? (documentedSymbols / totalSymbols) * 100 : 100,
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to extract docstrings: ${message}`);
+    }
+}
+/**
+ * Analyze documentation in a single file
+ */
+async function analyzeFileDocumentation(filePath, kinds, documentedOnly) {
+    const parseResult = await parseFile(filePath);
+    const { tree, source } = parseResult;
+    const symbols = [];
+    let moduleDoc;
+    // Extract module docstring
+    const moduleDocstring = extractDocstring({ childForFieldName: () => tree.rootNode }, source);
+    if (moduleDocstring) {
+        moduleDoc = parseDocstring(moduleDocstring);
+    }
+    // Check if we should include certain kinds
+    const _includeModule = !kinds || kinds.includes("module"); // Reserved for future use
+    const includeFunction = !kinds || kinds.includes("function");
+    const includeClass = !kinds || kinds.includes("class");
+    const includeMethod = !kinds || kinds.includes("method");
+    // Extract function and class docstrings
+    for (const child of tree.rootNode.children) {
+        // Functions
+        if (includeFunction &&
+            (child.type === "function_definition" ||
+                child.type === "async_function_definition")) {
+            const funcInfo = parseFunction(child, source);
+            const hasDoc = !!funcInfo.docstring;
+            if (!documentedOnly || hasDoc) {
+                symbols.push({
+                    name: funcInfo.name,
+                    path: filePath,
+                    line: funcInfo.line,
+                    docstring: funcInfo.docstring,
+                    parsed: funcInfo.docstring
+                        ? parseDocstring(funcInfo.docstring)
+                        : undefined,
+                });
+            }
+        }
+        // Decorated functions
+        if (includeFunction && child.type === "decorated_definition") {
+            const funcNode = child.children.find((c) => c.type === "function_definition" ||
+                c.type === "async_function_definition");
+            if (funcNode) {
+                const decorators = parseDecorators(child, source);
+                const funcInfo = parseFunction(funcNode, source, decorators);
+                const hasDoc = !!funcInfo.docstring;
+                if (!documentedOnly || hasDoc) {
+                    symbols.push({
+                        name: funcInfo.name,
+                        path: filePath,
+                        line: funcInfo.line,
+                        docstring: funcInfo.docstring,
+                        parsed: funcInfo.docstring
+                            ? parseDocstring(funcInfo.docstring)
+                            : undefined,
+                    });
+                }
+            }
+        }
+        // Classes
+        if (includeClass && child.type === "class_definition") {
+            const classInfo = parseClass(child, source);
+            const hasDoc = !!classInfo.docstring;
+            if (!documentedOnly || hasDoc) {
+                symbols.push({
+                    name: classInfo.name,
+                    path: filePath,
+                    line: classInfo.line,
+                    docstring: classInfo.docstring,
+                    parsed: classInfo.docstring
+                        ? parseDocstring(classInfo.docstring)
+                        : undefined,
+                });
+            }
+            // Class methods
+            if (includeMethod) {
+                for (const method of classInfo.methods) {
+                    const hasMethodDoc = !!method.docstring;
+                    if (!documentedOnly || hasMethodDoc) {
+                        symbols.push({
+                            name: `${classInfo.name}.${method.name}`,
+                            path: filePath,
+                            line: method.line,
+                            docstring: method.docstring,
+                            parsed: method.docstring
+                                ? parseDocstring(method.docstring)
+                                : undefined,
+                        });
+                    }
+                }
+            }
+        }
+        // Decorated classes
+        if (includeClass && child.type === "decorated_definition") {
+            const classNode = child.children.find((c) => c.type === "class_definition");
+            if (classNode) {
+                const decorators = parseDecorators(child, source);
+                const classInfo = parseClass(classNode, source, decorators);
+                const hasDoc = !!classInfo.docstring;
+                if (!documentedOnly || hasDoc) {
+                    symbols.push({
+                        name: classInfo.name,
+                        path: filePath,
+                        line: classInfo.line,
+                        docstring: classInfo.docstring,
+                        parsed: classInfo.docstring
+                            ? parseDocstring(classInfo.docstring)
+                            : undefined,
+                    });
+                }
+                // Class methods
+                if (includeMethod) {
+                    for (const method of classInfo.methods) {
+                        const hasMethodDoc = !!method.docstring;
+                        if (!documentedOnly || hasMethodDoc) {
+                            symbols.push({
+                                name: `${classInfo.name}.${method.name}`,
+                                path: filePath,
+                                line: method.line,
+                                docstring: method.docstring,
+                                parsed: method.docstring
+                                    ? parseDocstring(method.docstring)
+                                    : undefined,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const documented = symbols.filter((s) => s.docstring).length;
+    return {
+        path: filePath,
+        moduleDoc,
+        symbols,
+        stats: {
+            totalSymbols: symbols.length,
+            documentedSymbols: documented,
+            undocumentedSymbols: symbols.length - documented,
+            coveragePercent: symbols.length > 0 ? (documented / symbols.length) * 100 : 100,
+        },
+    };
+}
+/**
+ * Parse a docstring into structured format
+ */
+function parseDocstring(docstring) {
+    const lines = docstring.split("\n").map((l) => l.trim());
+    const format = detectDocstringFormat(docstring);
+    // Extract summary (first paragraph)
+    let summary = "";
+    let descriptionStart = 0;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i] === "") {
+            descriptionStart = i + 1;
+            break;
+        }
+        summary += (summary ? " " : "") + lines[i];
+        descriptionStart = i + 1;
+    }
+    // Parse based on format
+    const parameters = [];
+    let returns;
+    const raises = [];
+    const examples = [];
+    let description;
+    let notes;
+    if (format === "google") {
+        const sections = parseGoogleStyle(docstring);
+        parameters.push(...(sections.params || []));
+        returns = sections.returns;
+        raises.push(...(sections.raises || []));
+        examples.push(...(sections.examples || []));
+        description = sections.description;
+        notes = sections.notes;
+    }
+    else if (format === "numpy") {
+        const sections = parseNumpyStyle(docstring);
+        parameters.push(...(sections.params || []));
+        returns = sections.returns;
+        raises.push(...(sections.raises || []));
+        examples.push(...(sections.examples || []));
+        description = sections.description;
+        notes = sections.notes;
+    }
+    else if (format === "sphinx") {
+        const sections = parseSphinxStyle(docstring);
+        parameters.push(...(sections.params || []));
+        returns = sections.returns;
+        raises.push(...(sections.raises || []));
+    }
+    else {
+        // Try to extract description from remaining lines
+        if (descriptionStart < lines.length) {
+            description =
+                lines.slice(descriptionStart).join("\n").trim() || undefined;
+        }
+    }
+    return {
+        summary,
+        description,
+        parameters,
+        returns,
+        raises,
+        examples,
+        notes,
+        format,
+    };
+}
+/**
+ * Detect docstring format
+ */
+function detectDocstringFormat(docstring) {
+    // Google style: "Args:", "Returns:", "Raises:"
+    if (/^\s*(Args|Arguments|Returns|Raises|Yields|Attributes):\s*$/m.test(docstring)) {
+        return "google";
+    }
+    // NumPy style: "Parameters", "Returns" with dashes
+    if (/^\s*(Parameters|Returns|Raises)\s*\n\s*-{3,}/m.test(docstring)) {
+        return "numpy";
+    }
+    // Sphinx style: ":param", ":returns:", ":raises:"
+    if (/:(param|returns?|raises?|type|rtype)/.test(docstring)) {
+        return "sphinx";
+    }
+    // Epytext: "@param", "@return", "@raise"
+    if (/@(param|return|raise|type)/.test(docstring)) {
+        return "epytext";
+    }
+    return "unknown";
+}
+/**
+ * Parse Google-style docstring
+ */
+function parseGoogleStyle(docstring) {
+    const result = {};
+    const lines = docstring.split("\n");
+    let currentSection = "";
+    let currentContent = [];
+    for (const line of lines) {
+        const sectionMatch = line.match(/^\s*(Args|Arguments|Returns|Raises|Yields|Example|Examples|Note|Notes):\s*$/);
+        if (sectionMatch) {
+            // Process previous section
+            processSectionContent(result, currentSection, currentContent);
+            currentSection = sectionMatch[1].toLowerCase();
+            currentContent = [];
+        }
+        else if (currentSection) {
+            currentContent.push(line);
+        }
+    }
+    // Process last section
+    processSectionContent(result, currentSection, currentContent);
+    return result;
+}
+/**
+ * Process section content for Google-style
+ */
+function processSectionContent(result, section, content) {
+    const text = content.join("\n").trim();
+    if (!text)
+        return;
+    switch (section) {
+        case "args":
+        case "arguments":
+            result.params = parseGoogleParams(text);
+            break;
+        case "returns":
+        case "yields":
+            result.returns = { description: text };
+            break;
+        case "raises":
+            result.raises = parseGoogleRaises(text);
+            break;
+        case "example":
+        case "examples":
+            result.examples = [text];
+            break;
+        case "note":
+        case "notes":
+            result.notes = text;
+            break;
+    }
+}
+/**
+ * Parse Google-style parameters
+ */
+function parseGoogleParams(text) {
+    const params = [];
+    const paramRegex = /^\s*(\w+)(?:\s*\(([^)]+)\))?:\s*(.+)$/gm;
+    let match;
+    while ((match = paramRegex.exec(text)) !== null) {
+        params.push({
+            name: match[1],
+            type: match[2],
+            description: match[3].trim(),
+            optional: match[2]?.includes("optional") || false,
+        });
+    }
+    return params;
+}
+/**
+ * Parse Google-style raises
+ */
+function parseGoogleRaises(text) {
+    const raises = [];
+    const raiseRegex = /^\s*(\w+):\s*(.+)$/gm;
+    let match;
+    while ((match = raiseRegex.exec(text)) !== null) {
+        raises.push({
+            type: match[1],
+            description: match[2].trim(),
+        });
+    }
+    return raises;
+}
+/**
+ * Parse NumPy-style docstring
+ */
+function parseNumpyStyle(docstring) {
+    // Simplified NumPy parsing - similar structure to Google but with different section headers
+    const result = {};
+    const sections = docstring.split(/\n(?=\w+\n-{3,})/);
+    for (const section of sections) {
+        const headerMatch = section.match(/^(\w+)\n-{3,}\n([\s\S]*)/);
+        if (headerMatch) {
+            const name = headerMatch[1].toLowerCase();
+            const content = headerMatch[2].trim();
+            switch (name) {
+                case "parameters":
+                    result.params = parseNumpyParams(content);
+                    break;
+                case "returns":
+                    result.returns = { description: content };
+                    break;
+                case "raises":
+                    result.raises = parseGoogleRaises(content);
+                    break;
+                case "examples":
+                    result.examples = [content];
+                    break;
+                case "notes":
+                    result.notes = content;
+                    break;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parse NumPy-style parameters
+ */
+function parseNumpyParams(text) {
+    const params = [];
+    const paramRegex = /^(\w+)\s*:\s*(\S+)?\s*\n\s+(.+)$/gm;
+    let match;
+    while ((match = paramRegex.exec(text)) !== null) {
+        params.push({
+            name: match[1],
+            type: match[2],
+            description: match[3].trim(),
+            optional: match[2]?.includes("optional") || false,
+        });
+    }
+    return params;
+}
+/**
+ * Parse Sphinx-style docstring
+ */
+function parseSphinxStyle(docstring) {
+    const result = {};
+    const params = [];
+    const raises = [];
+    // :param name: description
+    const paramRegex = /:param\s+(\w+):\s*(.+)/g;
+    let match;
+    while ((match = paramRegex.exec(docstring)) !== null) {
+        params.push({
+            name: match[1],
+            description: match[2].trim(),
+            optional: false,
+        });
+    }
+    // :type name: type
+    const typeRegex = /:type\s+(\w+):\s*(.+)/g;
+    let typeMatch;
+    while ((typeMatch = typeRegex.exec(docstring)) !== null) {
+        const tm = typeMatch; // Capture for TypeScript narrowing
+        const param = params.find((p) => p.name === tm[1]);
+        if (param) {
+            param.type = tm[2].trim();
+        }
+    }
+    // :returns: description
+    const returnMatch = docstring.match(/:returns?:\s*(.+)/);
+    if (returnMatch) {
+        result.returns = { description: returnMatch[1].trim() };
+    }
+    // :rtype: type
+    const rtypeMatch = docstring.match(/:rtype:\s*(.+)/);
+    if (rtypeMatch && result.returns) {
+        result.returns.type = rtypeMatch[1].trim();
+    }
+    // :raises Type: description
+    const raiseRegex = /:raises?\s+(\w+):\s*(.+)/g;
+    while ((match = raiseRegex.exec(docstring)) !== null) {
+        raises.push({
+            type: match[1],
+            description: match[2].trim(),
+        });
+    }
+    result.params = params;
+    result.raises = raises;
+    return result;
+}
+/**
+ * Collect Python files in a directory
+ */
+async function collectPythonFiles(dir, recursive, maxFiles) {
+    const files = [];
+    async function walk(currentDir) {
+        if (files.length >= maxFiles)
+            return;
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                break;
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory() && recursive) {
+                if (entry.name.startsWith(".") ||
+                    entry.name === "__pycache__" ||
+                    entry.name === "venv" ||
+                    entry.name === ".venv") {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile() &&
+                (fullPath.endsWith(".py") || fullPath.endsWith(".pyi"))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+/**
+ * Factory function to create a customized extractDocstrings tool
+ */
+export function createExtractDocstringsTool(options) {
+    const { defaultRecursive = false, defaultDocumentedOnly = false } = options ?? {};
+    return defineTool({
+        name: "extract_docstrings_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeExtractDocstrings({
+                ...input,
+                recursive: input.recursive ?? defaultRecursive,
+                documentedOnly: input.documentedOnly ?? defaultDocumentedOnly,
+            });
+        },
+    });
+}

package/dist/tools/find-dead-code.d.ts

@@ -0,0 +1,62 @@
+/**
+ * findDeadCode Tool
+ *
+ * Find potentially unused functions, classes, and variables in Python code.
+ * Uses static analysis to identify code that may be dead.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Input for findDeadCode tool
+ */
+export interface FindDeadCodeInput {
+    /** Directory to analyze */
+    path: string;
+    /** Include test files in analysis (default: false) */
+    includeTests?: boolean;
+    /** Check for unused functions (default: true) */
+    checkFunctions?: boolean;
+    /** Check for unused classes (default: true) */
+    checkClasses?: boolean;
+    /** Check for unused variables (default: false) */
+    checkVariables?: boolean;
+    /** Maximum files to analyze (default: 100) */
+    maxFiles?: number;
+}
+/**
+ * Dead code item
+ */
+export interface DeadCodeItem {
+    name: string;
+    path: string;
+    line: number;
+    kind: "function" | "class" | "variable" | "method";
+    confidence: "high" | "medium" | "low";
+    reason: string;
+}
+/**
+ * Result of findDeadCode
+ */
+export interface FindDeadCodeResult {
+    path: string;
+    deadCode: DeadCodeItem[];
+    stats: {
+        filesAnalyzed: number;
+        totalFunctions: number;
+        unusedFunctions: number;
+        totalClasses: number;
+        unusedClasses: number;
+        totalVariables: number;
+        unusedVariables: number;
+    };
+}
+/**
+ * findDeadCode tool
+ */
+export declare const findDeadCodeTool: Tool<FindDeadCodeInput>;
+/**
+ * Factory function to create a customized findDeadCode tool
+ */
+export declare function createFindDeadCodeTool(options?: {
+    defaultMaxFiles?: number;
+}): Tool<FindDeadCodeInput>;
+//# sourceMappingURL=find-dead-code.d.ts.map

package/dist/tools/find-dead-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-dead-code.d.ts","sourceRoot":"","sources":["../../src/tools/find-dead-code.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAQrE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iDAAiD;IACjD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kDAAkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;IACnD,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAuED;;GAEG;AACH,eAAO,MAAM,gBAAgB,yBAK3B,CAAC;AA4ZH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAa1B"}