@compilr-dev/agents-coding-python 0.1.0

package/dist/parser/python-parser.js

@@ -0,0 +1,477 @@
+/**
+ * Python Parser using Tree-sitter
+ *
+ * Provides AST parsing and traversal for Python source files.
+ */
+import Parser from "tree-sitter";
+import Python from "tree-sitter-python";
+import { readFile } from "node:fs/promises";
+// Initialize parser
+const parser = new Parser();
+// Cast to any to work around tree-sitter type mismatches between versions
+parser.setLanguage(Python);
+/**
+ * Parse Python source code
+ */
+export function parseSource(source) {
+    const tree = parser.parse(source);
+    const errors = [];
+    // Find error nodes
+    const findErrors = (node) => {
+        if (node.type === "ERROR" || node.isMissing) {
+            errors.push({
+                message: node.isMissing ? `Missing: ${node.type}` : "Syntax error",
+                line: node.startPosition.row + 1,
+                column: node.startPosition.column,
+            });
+        }
+        for (const child of node.children) {
+            findErrors(child);
+        }
+    };
+    findErrors(tree.rootNode);
+    return {
+        tree,
+        source,
+        hasErrors: errors.length > 0,
+        errors,
+    };
+}
+/**
+ * Parse Python file
+ */
+export async function parseFile(path) {
+    const source = await readFile(path, "utf-8");
+    return parseSource(source);
+}
+/**
+ * Get text from a node
+ */
+export function getNodeText(node, source) {
+    return source.slice(node.startIndex, node.endIndex);
+}
+/**
+ * Extract docstring from a block
+ */
+export function extractDocstring(node, source) {
+    // Look for the first expression_statement containing a string
+    const block = node.childForFieldName("body");
+    if (!block)
+        return undefined;
+    const firstChild = block.firstChild;
+    if (!firstChild)
+        return undefined;
+    if (firstChild.type === "expression_statement") {
+        const expr = firstChild.firstChild;
+        if (expr && expr.type === "string") {
+            const text = getNodeText(expr, source);
+            // Remove quotes (single, double, triple)
+            return text.replace(/^['"]{1,3}|['"]{1,3}$/g, "").trim();
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse decorators from a decorated_definition
+ */
+export function parseDecorators(node, source) {
+    const decorators = [];
+    for (const child of node.children) {
+        if (child.type === "decorator") {
+            let nameNode;
+            let argsNode;
+            // Check if decorator is a call (e.g., @lru_cache(maxsize=100))
+            const callNode = child.children.find((c) => c.type === "call");
+            if (callNode) {
+                // Get the function name from the call
+                nameNode = callNode.children.find((c) => c.type === "identifier" || c.type === "attribute");
+                // Get arguments from the call's argument_list
+                argsNode = callNode.children.find((c) => c.type === "argument_list");
+            }
+            else {
+                // Simple decorator (e.g., @property)
+                nameNode = child.children.find((c) => c.type === "identifier" || c.type === "attribute");
+            }
+            if (nameNode) {
+                const decorator = {
+                    name: getNodeText(nameNode, source),
+                    line: child.startPosition.row + 1,
+                };
+                // Parse arguments if present
+                if (argsNode) {
+                    decorator.arguments = [];
+                    for (const arg of argsNode.children) {
+                        if (arg.type !== "(" && arg.type !== ")" && arg.type !== ",") {
+                            decorator.arguments.push(getNodeText(arg, source));
+                        }
+                    }
+                }
+                decorators.push(decorator);
+            }
+        }
+    }
+    return decorators;
+}
+/**
+ * Parse function parameters
+ */
+export function parseParameters(node, source) {
+    const params = [];
+    let seenSlash = false;
+    let seenStar = false;
+    const paramsNode = node.childForFieldName("parameters");
+    if (!paramsNode)
+        return params;
+    for (const child of paramsNode.children) {
+        if (child.type === "/" || getNodeText(child, source) === "/") {
+            seenSlash = true;
+            continue;
+        }
+        if (child.type === "*" && !child.firstChild) {
+            seenStar = true;
+            continue;
+        }
+        if (child.type === "identifier" ||
+            child.type === "typed_parameter" ||
+            child.type === "default_parameter" ||
+            child.type === "typed_default_parameter" ||
+            child.type === "list_splat_pattern" ||
+            child.type === "dictionary_splat_pattern") {
+            const param = {
+                name: "",
+                isArgs: child.type === "list_splat_pattern",
+                isKwargs: child.type === "dictionary_splat_pattern",
+                isPositionalOnly: !seenSlash,
+                isKeywordOnly: seenStar && !child.type.includes("splat"),
+            };
+            // Update positional only after we've seen /
+            if (seenSlash) {
+                param.isPositionalOnly = false;
+            }
+            // Get name - find the first identifier child
+            if (child.type === "identifier") {
+                param.name = getNodeText(child, source);
+            }
+            else {
+                // For typed_parameter, default_parameter, etc., find the identifier child
+                const nameNode = child.children.find((c) => c.type === "identifier");
+                if (nameNode) {
+                    param.name = getNodeText(nameNode, source);
+                }
+            }
+            // Skip 'self' and 'cls'
+            if (param.name === "self" || param.name === "cls") {
+                continue;
+            }
+            // Get type annotation
+            const typeNode = child.childForFieldName("type");
+            if (typeNode) {
+                param.type = getNodeText(typeNode, source);
+            }
+            // Get default value
+            const valueNode = child.childForFieldName("value");
+            if (valueNode) {
+                param.default = getNodeText(valueNode, source);
+            }
+            if (param.name) {
+                params.push(param);
+            }
+        }
+    }
+    return params;
+}
+/**
+ * Parse a function definition
+ */
+export function parseFunction(node, source, decorators = []) {
+    const nameNode = node.childForFieldName("name");
+    const returnTypeNode = node.childForFieldName("return_type");
+    // Check for async - either the node type or has an 'async' child
+    const isAsync = node.type === "async_function_definition" ||
+        node.parent?.type === "async_function_definition" ||
+        node.children.some((c) => c.type === "async");
+    // Check if generator (contains yield)
+    let isGenerator = false;
+    const checkYield = (n) => {
+        if (n.type === "yield")
+            return true;
+        for (const child of n.children) {
+            if (checkYield(child))
+                return true;
+        }
+        return false;
+    };
+    isGenerator = checkYield(node);
+    return {
+        name: nameNode ? getNodeText(nameNode, source) : "",
+        line: node.startPosition.row + 1,
+        endLine: node.endPosition.row + 1,
+        column: node.startPosition.column,
+        parameters: parseParameters(node, source),
+        returnType: returnTypeNode
+            ? getNodeText(returnTypeNode, source)
+            : undefined,
+        decorators,
+        isAsync,
+        isGenerator,
+        docstring: extractDocstring(node, source),
+    };
+}
+/**
+ * Parse a method (function inside a class)
+ */
+export function parseMethod(node, source, decorators = []) {
+    const func = parseFunction(node, source, decorators);
+    const decoratorNames = decorators.map((d) => d.name);
+    return {
+        ...func,
+        isClassMethod: decoratorNames.includes("classmethod"),
+        isStaticMethod: decoratorNames.includes("staticmethod"),
+        isProperty: decoratorNames.includes("property"),
+        isAbstract: decoratorNames.includes("abstractmethod"),
+    };
+}
+/**
+ * Parse a class definition
+ */
+export function parseClass(node, source, decorators = []) {
+    const nameNode = node.childForFieldName("name");
+    const basesNode = node.childForFieldName("superclasses");
+    const bases = [];
+    if (basesNode) {
+        for (const child of basesNode.children) {
+            if (child.type === "identifier" || child.type === "attribute") {
+                bases.push(getNodeText(child, source));
+            }
+        }
+    }
+    const methods = [];
+    const attributes = [];
+    // Parse body
+    const body = node.childForFieldName("body");
+    if (body) {
+        for (const child of body.children) {
+            if (child.type === "function_definition" ||
+                child.type === "async_function_definition") {
+                methods.push(parseMethod(child, source));
+            }
+            else if (child.type === "decorated_definition") {
+                const decs = parseDecorators(child, source);
+                const funcNode = child.children.find((c) => c.type === "function_definition" ||
+                    c.type === "async_function_definition");
+                if (funcNode) {
+                    methods.push(parseMethod(funcNode, source, decs));
+                }
+            }
+            else if (child.type === "expression_statement") {
+                // Class-level assignments
+                const expr = child.firstChild;
+                if (expr &&
+                    (expr.type === "assignment" || expr.type === "annotated_assignment")) {
+                    const leftNode = expr.childForFieldName("left") || expr.firstChild;
+                    if (leftNode && leftNode.type === "identifier") {
+                        const attr = {
+                            name: getNodeText(leftNode, source),
+                            line: child.startPosition.row + 1,
+                            isClassAttribute: true,
+                        };
+                        // Get type annotation
+                        const typeNode = expr.childForFieldName("type");
+                        if (typeNode) {
+                            attr.type = getNodeText(typeNode, source);
+                        }
+                        // Get value
+                        const valueNode = expr.childForFieldName("right") ||
+                            expr.childForFieldName("value");
+                        if (valueNode) {
+                            attr.default = getNodeText(valueNode, source);
+                        }
+                        attributes.push(attr);
+                    }
+                }
+            }
+        }
+    }
+    const decoratorNames = decorators.map((d) => d.name);
+    const isAbstract = bases.some((b) => b === "ABC" || b.endsWith(".ABC") || b === "ABCMeta");
+    const isDataclass = decoratorNames.includes("dataclass");
+    return {
+        name: nameNode ? getNodeText(nameNode, source) : "",
+        line: node.startPosition.row + 1,
+        endLine: node.endPosition.row + 1,
+        column: node.startPosition.column,
+        bases,
+        decorators,
+        methods,
+        attributes,
+        docstring: extractDocstring(node, source),
+        isAbstract,
+        isDataclass,
+    };
+}
+/**
+ * Parse import statement
+ */
+export function parseImport(node, source) {
+    if (node.type === "import_statement") {
+        const names = [];
+        let mainModule = "";
+        for (const child of node.children) {
+            if (child.type === "dotted_name") {
+                mainModule = getNodeText(child, source);
+                names.push({ name: mainModule });
+            }
+            else if (child.type === "aliased_import") {
+                const nameNode = child.childForFieldName("name");
+                const aliasNode = child.childForFieldName("alias");
+                if (nameNode) {
+                    const entry = {
+                        name: getNodeText(nameNode, source),
+                    };
+                    if (aliasNode) {
+                        entry.alias = getNodeText(aliasNode, source);
+                    }
+                    names.push(entry);
+                }
+            }
+        }
+        return {
+            module: mainModule || (names[0]?.name ?? ""),
+            names,
+            line: node.startPosition.row + 1,
+            isFromImport: false,
+            isRelative: false,
+            relativeDots: 0,
+        };
+    }
+    // import_from_statement
+    const moduleNode = node.childForFieldName("module_name");
+    const moduleName = moduleNode ? getNodeText(moduleNode, source) : "";
+    // Count relative dots
+    let relativeDots = 0;
+    for (const child of node.children) {
+        if (getNodeText(child, source) === ".") {
+            relativeDots++;
+        }
+    }
+    const names = [];
+    // Check for wildcard import
+    const wildcardNode = node.children.find((c) => getNodeText(c, source) === "*");
+    if (wildcardNode) {
+        names.push({ name: "*" });
+    }
+    else {
+        // Parse imported names
+        for (const child of node.children) {
+            if (child.type === "dotted_name" && child !== moduleNode) {
+                names.push({ name: getNodeText(child, source) });
+            }
+            else if (child.type === "aliased_import") {
+                const nameNode = child.childForFieldName("name");
+                const aliasNode = child.childForFieldName("alias");
+                if (nameNode) {
+                    const entry = {
+                        name: getNodeText(nameNode, source),
+                    };
+                    if (aliasNode) {
+                        entry.alias = getNodeText(aliasNode, source);
+                    }
+                    names.push(entry);
+                }
+            }
+        }
+    }
+    return {
+        module: moduleName,
+        names,
+        line: node.startPosition.row + 1,
+        isFromImport: true,
+        isRelative: relativeDots > 0,
+        relativeDots,
+    };
+}
+/**
+ * Parse variable assignment
+ */
+export function parseVariable(node, source) {
+    let nameNode = null;
+    let typeNode = null;
+    let valueNode = null;
+    if (node.type === "assignment") {
+        nameNode = node.childForFieldName("left");
+        valueNode = node.childForFieldName("right");
+    }
+    else if (node.type === "annotated_assignment") {
+        nameNode = node.childForFieldName("left") || node.firstChild;
+        typeNode = node.childForFieldName("type");
+        valueNode = node.childForFieldName("value");
+    }
+    if (!nameNode || nameNode.type !== "identifier") {
+        return null;
+    }
+    const name = getNodeText(nameNode, source);
+    // Check if constant (all uppercase)
+    const isConstant = /^[A-Z][A-Z0-9_]*$/.test(name);
+    return {
+        name,
+        type: typeNode ? getNodeText(typeNode, source) : undefined,
+        value: valueNode ? getNodeText(valueNode, source) : undefined,
+        line: node.startPosition.row + 1,
+        column: node.startPosition.column,
+        isConstant,
+    };
+}
+/**
+ * Walk the AST and collect all nodes of given types
+ */
+export function* walkTree(node, types) {
+    if (!types || types.includes(node.type)) {
+        yield node;
+    }
+    for (const child of node.children) {
+        yield* walkTree(child, types);
+    }
+}
+/**
+ * Find all nodes matching a predicate
+ */
+export function findNodes(node, predicate) {
+    const results = [];
+    const walk = (n) => {
+        if (predicate(n)) {
+            results.push(n);
+        }
+        for (const child of n.children) {
+            walk(child);
+        }
+    };
+    walk(node);
+    return results;
+}
+/**
+ * Get the containing scope for a node (function or class)
+ */
+export function getContainingScope(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === "function_definition" ||
+            current.type === "async_function_definition") {
+            const nameNode = current.childForFieldName("name");
+            return {
+                type: "function",
+                name: nameNode?.text ?? "",
+                node: current,
+            };
+        }
+        if (current.type === "class_definition") {
+            const nameNode = current.childForFieldName("name");
+            return {
+                type: "class",
+                name: nameNode?.text ?? "",
+                node: current,
+            };
+        }
+        current = current.parent;
+    }
+    return null;
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Python Skills
+ *
+ * Skills for Python code analysis, best practices, and workflows.
+ */
+export { pythonBestPracticesSkill } from "./python-best-practices.js";
+export { pythonCodeHealthSkill } from "./python-code-health.js";
+export { pythonCodeStructureSkill } from "./python-code-structure.js";
+export { pythonDependencyAuditSkill } from "./python-dependency-audit.js";
+export { pythonRefactorImpactSkill } from "./python-refactor-impact.js";
+import type { Skill } from "@compilr-dev/agents";
+/**
+ * All Python skills
+ */
+export declare const pythonSkills: Skill[];
+/**
+ * Python skills by name for selective use
+ */
+export declare const pythonSkillsMap: {
+    readonly bestPractices: Skill;
+    readonly codeHealth: Skill;
+    readonly codeStructure: Skill;
+    readonly dependencyAudit: Skill;
+    readonly refactorImpact: Skill;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAOxE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,EAM/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;CAMlB,CAAC"}

package/dist/skills/index.js

@@ -0,0 +1,36 @@
+/**
+ * Python Skills
+ *
+ * Skills for Python code analysis, best practices, and workflows.
+ */
+// Individual skill exports
+export { pythonBestPracticesSkill } from "./python-best-practices.js";
+export { pythonCodeHealthSkill } from "./python-code-health.js";
+export { pythonCodeStructureSkill } from "./python-code-structure.js";
+export { pythonDependencyAuditSkill } from "./python-dependency-audit.js";
+export { pythonRefactorImpactSkill } from "./python-refactor-impact.js";
+import { pythonBestPracticesSkill } from "./python-best-practices.js";
+import { pythonCodeHealthSkill } from "./python-code-health.js";
+import { pythonCodeStructureSkill } from "./python-code-structure.js";
+import { pythonDependencyAuditSkill } from "./python-dependency-audit.js";
+import { pythonRefactorImpactSkill } from "./python-refactor-impact.js";
+/**
+ * All Python skills
+ */
+export const pythonSkills = [
+    pythonBestPracticesSkill,
+    pythonCodeHealthSkill,
+    pythonCodeStructureSkill,
+    pythonDependencyAuditSkill,
+    pythonRefactorImpactSkill,
+];
+/**
+ * Python skills by name for selective use
+ */
+export const pythonSkillsMap = {
+    bestPractices: pythonBestPracticesSkill,
+    codeHealth: pythonCodeHealthSkill,
+    codeStructure: pythonCodeStructureSkill,
+    dependencyAudit: pythonDependencyAuditSkill,
+    refactorImpact: pythonRefactorImpactSkill,
+};

package/dist/skills/python-best-practices.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Python Best Practices Skill
+ *
+ * Provides guidance for Python-specific coding patterns and analysis.
+ */
+export declare const pythonBestPracticesSkill: import("@compilr-dev/agents").Skill;
+//# sourceMappingURL=python-best-practices.d.ts.map

package/dist/skills/python-best-practices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-best-practices.d.ts","sourceRoot":"","sources":["../../src/skills/python-best-practices.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,eAAO,MAAM,wBAAwB,qCAuEnC,CAAC"}

package/dist/skills/python-best-practices.js

@@ -0,0 +1,78 @@
+/**
+ * Python Best Practices Skill
+ *
+ * Provides guidance for Python-specific coding patterns and analysis.
+ */
+import { defineSkill } from "@compilr-dev/agents";
+export const pythonBestPracticesSkill = defineSkill({
+    name: "python-best-practices",
+    description: "Python-specific coding guidance and analysis workflow",
+    version: "1.0.0",
+    tags: ["python", "best-practices", "analysis"],
+    prompt: `You are in Python analysis mode. Use these tools for comprehensive code understanding:
+
+## Code Structure Analysis
+- **getFileStructure**: Get overview of classes, functions, imports, variables
+  - Use to understand file organization
+  - Identify public API surface
+  - See class hierarchies and method signatures
+
+## Python-Specific Guidance
+
+### Naming Conventions (PEP 8)
+- \`snake_case\` for functions, variables, modules
+- \`PascalCase\` for classes
+- \`UPPER_CASE\` for constants
+- \`_private\` for internal use
+- \`__dunder__\` for special methods
+
+### Type Hints (PEP 484, 585)
+- Always add type hints to function signatures
+- Use \`Optional[T]\` for nullable values
+- Use \`Union[A, B]\` for multiple types
+- Prefer \`list[T]\` over \`List[T]\` (Python 3.9+)
+
+### Docstrings (PEP 257)
+- Use triple quotes for all docstrings
+- First line is a summary
+- Blank line before detailed description
+- Document parameters, returns, raises
+
+### Best Practices
+- Use dataclasses or attrs for data containers
+- Prefer pathlib over os.path
+- Use f-strings over .format()
+- Use context managers for resources
+- Avoid mutable default arguments: \`def foo(x=None)\` not \`def foo(x=[])\`
+- Use \`__all__\` to define public API
+
+### Anti-Patterns to Avoid
+- Bare \`except:\` clauses (catch specific exceptions)
+- \`from module import *\` (explicit imports only)
+- Global variables
+- Deeply nested code (refactor to smaller functions)
+- Magic numbers (use named constants)
+
+## Analysis Workflow
+
+1. **Understand Structure**
+   \`\`\`
+   getFileStructure for overview
+   \`\`\`
+
+2. **Review Complexity**
+   - Look for functions with many parameters
+   - Check for deeply nested code
+   - Identify god classes
+
+3. **Check Code Quality**
+   - Look for missing type hints
+   - Check docstring coverage
+   - Find TODO/FIXME comments
+
+4. **Suggest Improvements**
+   - Recommend refactoring for complex code
+   - Suggest type hints where missing
+   - Propose better naming when unclear
+`,
+});

package/dist/skills/python-code-health.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Python Code Health Skill
+ *
+ * Orchestrates code quality analysis using complexity, dead code, duplicates, patterns, and other tools.
+ */
+export declare const pythonCodeHealthSkill: import("@compilr-dev/agents").Skill;
+//# sourceMappingURL=python-code-health.d.ts.map

package/dist/skills/python-code-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-code-health.d.ts","sourceRoot":"","sources":["../../src/skills/python-code-health.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,eAAO,MAAM,qBAAqB,qCA0MhC,CAAC"}