@compilr-dev/agents-coding-python 0.1.0

package/dist/skills/python-refactor-impact.js

@@ -0,0 +1,232 @@
+/**
+ * Python Refactor Impact Skill
+ *
+ * Assesses the impact of potential code changes and refactoring.
+ */
+import { defineSkill } from "@compilr-dev/agents";
+export const pythonRefactorImpactSkill = defineSkill({
+    name: "python-refactor-impact",
+    description: "Assess impact of Python code changes and refactoring",
+    version: "1.1.0",
+    tags: ["python", "refactoring", "impact", "analysis"],
+    prompt: `You are in Python refactor impact analysis mode. Use these tools systematically:
+
+## Impact Analysis Workflow
+
+### Step 1: Find the Symbol
+Use **find_symbol_python** to locate what you want to change:
+- Function definition
+- Class definition
+- Method or constant
+
+### Step 2: Find All References
+Use **find_references_python** to understand usage:
+- **definition**: Where it's defined
+- **read**: Where it's used/accessed
+- **write**: Where it's assigned
+- **call**: Where it's called as a function
+- **import**: Where it's imported
+- **attribute**: Where it's accessed as an attribute
+
+### Step 3: Analyze Call Graph
+Use **get_call_graph_python** to understand function relationships:
+- Who calls this function?
+- What functions does it call?
+- Trace impact through call chains
+
+\`\`\`
+get_call_graph_python({
+  startFunction: "process_order",
+  path: "/path/to/project",
+  direction: "both",  // "callers", "callees", or "both"
+  maxDepth: 3
+})
+\`\`\`
+
+### Step 4: Understand the Hierarchy
+Use **get_class_hierarchy_python** for class changes:
+- What classes inherit from this?
+- What does this class inherit from?
+- How will changes propagate?
+
+### Step 5: Find Implementations
+Use **find_implementations_python** for ABC/Protocol changes:
+- Find all concrete implementations of an abstract class
+- Find all classes implementing a Protocol
+- Understand which classes need updating
+
+\`\`\`
+find_implementations_python({
+  name: "BaseHandler",
+  scope: "/path/to/project"
+})
+\`\`\`
+
+### Step 6: Check Dependencies
+Use **get_imports_python** to see module dependencies:
+- What imports this module?
+- Breaking changes affect all importers
+
+### Step 7: Assess Complexity
+Use **get_complexity_python** to understand scope:
+- How complex is the current code?
+- Will the refactor simplify it?
+
+## Impact Categories
+
+### High Impact Changes
+- Renaming public classes/functions
+- Changing function signatures
+- Modifying class hierarchy (adding/removing base classes)
+- Changing module structure (moving files)
+- Modifying __init__.py exports
+
+### Medium Impact Changes
+- Adding optional parameters
+- Changing implementation (keeping signature)
+- Adding new methods to classes
+- Deprecating old interfaces
+
+### Low Impact Changes
+- Renaming private members (_name)
+- Changing internal implementation details
+- Adding docstrings
+- Fixing bugs without API changes
+
+## Python-Specific Considerations
+
+### Duck Typing Impact
+- Python uses duck typing - changes affect any code expecting the interface
+- No compiler to catch broken references
+- Tests are critical for catching breakage
+
+### Dynamic Imports
+\`\`\`python
+# These won't be caught by static analysis
+module = importlib.import_module(f"plugins.{name}")
+getattr(obj, "method_name")()
+\`\`\`
+
+### Magic Methods
+\`\`\`python
+# Changes to __init__, __str__, etc. have wide impact
+def __eq__(self, other):  # Affects dict keys, set membership
+def __hash__(self):       # Affects dict/set operations
+def __iter__(self):       # Affects for loops, unpacking
+\`\`\`
+
+### Decorators
+\`\`\`python
+@property  # Changes how attribute is accessed
+@classmethod  # Changes how method is called
+@staticmethod  # Changes binding behavior
+\`\`\`
+
+## Impact Assessment Checklist
+
+### Before Renaming
+- [ ] Find all references (find_references_python)
+- [ ] Check for string-based access (getattr, dictionary keys)
+- [ ] Check for dynamic imports
+- [ ] Check test files
+- [ ] Check config files
+
+### Before Changing Signature
+- [ ] Find all call sites (find_references_python with type: call)
+- [ ] Check for **kwargs usage (may hide callers)
+- [ ] Check for partial/functools.partial usage
+- [ ] Consider adding deprecation warning first
+
+### Before Changing Inheritance
+- [ ] Find all subclasses (get_class_hierarchy_python)
+- [ ] Check for super() calls
+- [ ] Check for overridden methods
+- [ ] Check for ABC abstract methods
+
+### Before Moving Code
+- [ ] Find all imports (find_references_python with type: import)
+- [ ] Check for relative imports
+- [ ] Update __init__.py exports
+- [ ] Consider re-exporting from old location temporarily
+
+## Impact Report Template
+
+\`\`\`markdown
+# Refactor Impact Analysis
+
+## Change Description
+- **Target**: function/class name
+- **Change**: rename/modify signature/move/delete
+- **Location**: file:line
+
+## Impact Summary
+- Files affected: N
+- Direct references: N
+- Indirect references: N
+- Risk level: High/Medium/Low
+
+## Direct References
+| File | Line | Type | Code Snippet |
+|------|------|------|--------------|
+| a.py | 42 | call | foo() |
+| b.py | 15 | import | from m import foo |
+
+## Inheritance Impact (for classes)
+- Subclasses: ChildA, ChildB
+- Methods overridden by: 3 classes
+
+## Test Coverage
+- Related tests: N
+- Test files: test_foo.py, test_bar.py
+
+## Migration Plan
+1. Add deprecation warning
+2. Create new function with new signature
+3. Update internal callers
+4. Update external callers
+5. Remove deprecated function
+
+## Risks
+- Dynamic imports may be missed
+- String-based getattr usage
+\`\`\`
+
+## Safe Refactoring Strategies
+
+### 1. Deprecation Path
+\`\`\`python
+import warnings
+
+def old_function():
+    warnings.warn(
+        "old_function is deprecated, use new_function instead",
+        DeprecationWarning,
+        stacklevel=2
+    )
+    return new_function()
+\`\`\`
+
+### 2. Backwards-Compatible Signature
+\`\`\`python
+def function(new_param=None, *, old_param=None):
+    if old_param is not None:
+        warnings.warn("old_param is deprecated", DeprecationWarning)
+        new_param = old_param
+    # ...
+\`\`\`
+
+### 3. Re-export After Move
+\`\`\`python
+# In old location's __init__.py
+from new_location import moved_function  # Re-export for backwards compat
+\`\`\`
+
+## When to Use This Skill
+
+- Before any refactoring
+- Planning breaking changes
+- Assessing technical debt cleanup
+- Preparing deprecation plans
+- Code review of refactoring PRs
+`,
+});

package/dist/tools/extract-docstrings.d.ts

@@ -0,0 +1,70 @@
+/**
+ * extractDocstrings Tool
+ *
+ * Extract and parse docstrings from Python files.
+ * Supports Google, NumPy, Sphinx, and Epytext formats.
+ */
+import type { Tool } from "@compilr-dev/agents";
+import type { DocumentationResult, ParsedDocstring } from "./types.js";
+/**
+ * Input for extractDocstrings tool
+ */
+export interface ExtractDocstringsInput {
+    /** File or directory to analyze */
+    path: string;
+    /** Recursive analysis for directories (default: false) */
+    recursive?: boolean;
+    /** Filter by symbol kinds */
+    kinds?: Array<"function" | "class" | "method" | "module">;
+    /** Only include documented symbols (default: false) */
+    documentedOnly?: boolean;
+    /** Maximum files to analyze (default: 50) */
+    maxFiles?: number;
+}
+/**
+ * Extracted documentation for a file
+ */
+export interface FileDocumentation {
+    /** File path */
+    path: string;
+    /** Module-level docstring */
+    moduleDoc?: ParsedDocstring;
+    /** Documented symbols */
+    symbols: DocumentationResult[];
+    /** Statistics */
+    stats: {
+        totalSymbols: number;
+        documentedSymbols: number;
+        undocumentedSymbols: number;
+        coveragePercent: number;
+    };
+}
+/**
+ * Output from extractDocstrings tool
+ */
+export interface ExtractDocstringsResult {
+    /** Analyzed path */
+    path: string;
+    /** Documentation by file */
+    files: FileDocumentation[];
+    /** Summary statistics */
+    summary: {
+        totalFiles: number;
+        totalSymbols: number;
+        documentedSymbols: number;
+        undocumentedSymbols: number;
+        coveragePercent: number;
+    };
+}
+/**
+ * extractDocstrings tool - Extract Python documentation
+ */
+export declare const extractDocstringsTool: Tool<ExtractDocstringsInput>;
+/**
+ * Factory function to create a customized extractDocstrings tool
+ */
+export declare function createExtractDocstringsTool(options?: {
+    defaultRecursive?: boolean;
+    defaultDocumentedOnly?: boolean;
+}): Tool<ExtractDocstringsInput>;
+//# sourceMappingURL=extract-docstrings.d.ts.map

package/dist/tools/extract-docstrings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-docstrings.d.ts","sourceRoot":"","sources":["../../src/tools/extract-docstrings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAQrE,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAKhB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;IAC1D,uDAAuD;IACvD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,yBAAyB;IACzB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,iBAAiB;IACjB,KAAK,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,yBAAyB;IACzB,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AA0CD;;GAEG;AACH,eAAO,MAAM,qBAAqB,8BAKhC,CAAC;AAmnBH;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE;IACpD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,GAAG,IAAI,CAAC,sBAAsB,CAAC,CAkB/B"}