@compilr-dev/agents-coding-go 0.1.0

package/dist/tools/extract-docstrings.js

@@ -0,0 +1,292 @@
+/**
+ * extractDocstrings Tool
+ *
+ * Extract documentation comments from Go code.
+ * Go uses godoc-style comments above declarations.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { parseFile, parseFunction, parseMethod, parseClass, extractDocComment, walkTree, } from "../parser/go-parser.js";
+// Tool description
+const TOOL_DESCRIPTION = `Extract documentation comments from Go code.
+Returns parsed godoc-style comments for functions, types, and methods.
+Helps understand code documentation coverage and quality.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "Go file or directory to analyze",
+        },
+        recursive: {
+            type: "boolean",
+            description: "Recursively scan directories (default: false)",
+            default: false,
+        },
+        name: {
+            type: "string",
+            description: "Filter to specific symbol name",
+        },
+        includeUndocumented: {
+            type: "boolean",
+            description: "Include symbols without documentation (default: false)",
+            default: false,
+        },
+        maxFiles: {
+            type: "number",
+            description: "Maximum files to process (default: 50)",
+            default: 50,
+        },
+    },
+    required: ["path"],
+};
+/**
+ * extractDocstrings tool - Extract Go documentation
+ */
+export const extractDocstringsTool = defineTool({
+    name: "extract_docstrings_go",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeExtractDocstrings,
+});
+/**
+ * Execute the extractDocstrings tool
+ */
+async function executeExtractDocstrings(input) {
+    const { path: inputPath, recursive = false, name, includeUndocumented = false, maxFiles = 50, } = input;
+    if (!inputPath) {
+        return createErrorResult("Path is required");
+    }
+    try {
+        const stats = await fs.stat(inputPath);
+        const docs = [];
+        if (stats.isFile()) {
+            if (!inputPath.endsWith(".go")) {
+                return createErrorResult("File must be a .go file");
+            }
+            const fileDocs = await extractFileDocstrings(inputPath, name, includeUndocumented);
+            docs.push(...fileDocs);
+        }
+        else if (stats.isDirectory()) {
+            const goFiles = await collectGoFiles(inputPath, recursive, maxFiles);
+            for (const filePath of goFiles) {
+                const fileDocs = await extractFileDocstrings(filePath, name, includeUndocumented);
+                docs.push(...fileDocs);
+            }
+        }
+        else {
+            return createErrorResult("Path must be a file or directory");
+        }
+        const documented = docs.filter((d) => d.doc);
+        const percentage = docs.length > 0 ? Math.round((documented.length / docs.length) * 100) : 0;
+        const result = {
+            path: inputPath,
+            docs,
+            stats: {
+                total: docs.length,
+                documented: documented.length,
+                undocumented: docs.length - documented.length,
+                percentage,
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to extract documentation: ${message}`);
+    }
+}
+/**
+ * Collect Go files from a directory
+ */
+async function collectGoFiles(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()) {
+                if (recursive &&
+                    !entry.name.startsWith(".") &&
+                    entry.name !== "vendor" &&
+                    entry.name !== "testdata") {
+                    await walk(fullPath);
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith(".go")) {
+                files.push(fullPath);
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+/**
+ * Extract documentation from a single file
+ */
+async function extractFileDocstrings(filePath, nameFilter, includeUndocumented) {
+    const docs = [];
+    try {
+        const parseResult = await parseFile(filePath);
+        const { tree, source } = parseResult;
+        for (const node of walkTree(tree.rootNode)) {
+            // Functions
+            if (node.type === "function_declaration") {
+                const funcInfo = parseFunction(node, source);
+                if (nameFilter && funcInfo.name !== nameFilter)
+                    continue;
+                const doc = extractDocComment(node, source);
+                if (!doc && !includeUndocumented)
+                    continue;
+                docs.push({
+                    name: funcInfo.name,
+                    path: filePath,
+                    line: funcInfo.line,
+                    doc,
+                    parsed: doc ? parseGodoc(doc) : undefined,
+                });
+            }
+            // Methods
+            if (node.type === "method_declaration") {
+                const methodInfo = parseMethod(node, source);
+                const fullName = methodInfo.receiverType
+                    ? `${methodInfo.receiverType}.${methodInfo.name}`
+                    : methodInfo.name;
+                if (nameFilter &&
+                    methodInfo.name !== nameFilter &&
+                    fullName !== nameFilter)
+                    continue;
+                const doc = extractDocComment(node, source);
+                if (!doc && !includeUndocumented)
+                    continue;
+                docs.push({
+                    name: fullName,
+                    path: filePath,
+                    line: methodInfo.line,
+                    doc,
+                    parsed: doc ? parseGodoc(doc) : undefined,
+                });
+            }
+            // Types (structs and interfaces)
+            if (node.type === "type_declaration") {
+                const typeInfo = parseClass(node, source);
+                if (nameFilter && typeInfo.name !== nameFilter)
+                    continue;
+                const doc = extractDocComment(node, source);
+                if (!doc && !includeUndocumented)
+                    continue;
+                docs.push({
+                    name: typeInfo.name,
+                    path: filePath,
+                    line: typeInfo.line,
+                    doc,
+                    parsed: doc ? parseGodoc(doc) : undefined,
+                });
+            }
+        }
+    }
+    catch {
+        // Skip files that can't be parsed
+    }
+    return docs;
+}
+/**
+ * Parse godoc-style documentation comment
+ *
+ * Godoc uses a simple format:
+ * - First sentence is the summary
+ * - Blank line separates summary from body
+ * - Deprecated: prefix marks deprecated items
+ * - Example blocks with indentation
+ */
+function parseGodoc(doc) {
+    const lines = doc.split("\n");
+    const summary = [];
+    const description = [];
+    const examples = [];
+    const params = [];
+    const errors = [];
+    let deprecated;
+    let inExample = false;
+    let currentExample = [];
+    let foundBlankLine = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Check for Deprecated marker
+        if (trimmed.startsWith("Deprecated:")) {
+            deprecated = trimmed.substring("Deprecated:".length).trim();
+            continue;
+        }
+        // Check for example (indented code block)
+        if (line.startsWith("    ") || line.startsWith("\t")) {
+            if (!inExample) {
+                inExample = true;
+                currentExample = [];
+            }
+            currentExample.push(line);
+            continue;
+        }
+        else if (inExample) {
+            // End of example
+            examples.push(currentExample.join("\n"));
+            inExample = false;
+            currentExample = [];
+        }
+        // Check for blank line
+        if (trimmed === "") {
+            foundBlankLine = true;
+            continue;
+        }
+        // Add to summary or description
+        if (!foundBlankLine) {
+            summary.push(trimmed);
+        }
+        else {
+            description.push(trimmed);
+        }
+    }
+    // Handle trailing example
+    if (inExample && currentExample.length > 0) {
+        examples.push(currentExample.join("\n"));
+    }
+    // Attempt to extract return info from description
+    let returns;
+    const returnMatch = description.join(" ").match(/returns?\s+(.+?)(?:\.|$)/i);
+    if (returnMatch) {
+        returns = { description: returnMatch[1].trim() };
+    }
+    return {
+        summary: summary.join(" "),
+        description: description.length > 0 ? description.join("\n") : undefined,
+        parameters: params, // Go doesn't have param docs in comments typically
+        returns,
+        errors, // Would need to parse "returns error if..." patterns
+        examples,
+        deprecated,
+        format: "godoc",
+    };
+}
+/**
+ * Factory function to create a customized extractDocstrings tool
+ */
+export function createExtractDocstringsTool(options) {
+    const { defaultMaxFiles = 50, defaultIncludeUndocumented = false } = options ?? {};
+    return defineTool({
+        name: "extract_docstrings_go",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeExtractDocstrings({
+                ...input,
+                maxFiles: input.maxFiles ?? defaultMaxFiles,
+                includeUndocumented: input.includeUndocumented ?? defaultIncludeUndocumented,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,62 @@
+/**
+ * findDeadCode Tool
+ *
+ * Find potentially unused functions, classes, and variables in Go 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;AAIrE;;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"}