@compilr-dev/agents-coding-python 0.1.0

package/dist/skills/python-code-health.js

@@ -0,0 +1,209 @@
+/**
+ * Python Code Health Skill
+ *
+ * Orchestrates code quality analysis using complexity, dead code, duplicates, patterns, and other tools.
+ */
+import { defineSkill } from "@compilr-dev/agents";
+export const pythonCodeHealthSkill = defineSkill({
+    name: "python-code-health",
+    description: "Comprehensive Python code quality and health analysis",
+    version: "1.1.0",
+    tags: ["python", "code-health", "quality", "analysis"],
+    prompt: `You are in Python code health analysis mode. Use these tools systematically:
+
+## Health Check Workflow
+
+### Step 1: Complexity Analysis
+Use **get_complexity_python** to find complex code:
+- Cyclomatic complexity > 10 indicates complex logic
+- Cognitive complexity > 15 indicates hard-to-understand code
+- High nesting depth suggests refactoring needed
+- Functions with many parameters need restructuring
+
+### Step 2: Dead Code Detection
+Use **find_dead_code_python** to find unused code:
+- Unused functions (defined but never called)
+- Unused classes (defined but never instantiated)
+- Unused variables (declared but never used)
+- Confidence levels (high/medium/low)
+
+### Step 3: Code Duplication
+Use **find_duplicates_python** to detect duplicated code:
+- Content-based hashing for exact matches
+- Normalized comparison (ignores formatting)
+- Identifies refactoring opportunities
+- Shows duplication percentage
+
+### Step 4: Anti-Patterns and Code Smells
+Use **find_patterns_python** to find issues:
+- Security issues (eval, exec, pickle with untrusted data)
+- Performance issues (star imports, bare except)
+- Maintainability issues (mutable default args, magic numbers)
+- Custom pattern support
+
+### Step 5: Documentation Coverage
+Use **extract_docstrings_python** to check documentation:
+- Functions without docstrings need documentation
+- Missing parameter descriptions
+- Missing return type documentation
+- Missing exception documentation
+
+### Step 6: Import Analysis
+Use **get_imports_python** to review dependencies:
+- High third-party dependency count increases risk
+- Unused imports add clutter
+- Circular import patterns cause issues
+- Prefer stdlib over third-party when possible
+
+### Step 7: Code Structure
+Use **get_file_structure_python** to understand organization:
+- God classes with too many methods
+- Files with too many classes/functions
+- Deep class hierarchies
+- Missing __all__ for public API
+
+## Health Metrics
+
+### Code Complexity
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Cyclomatic | < 5 | 5-10 | > 10 |
+| Cognitive | < 8 | 8-15 | > 15 |
+| Nesting | < 3 | 3-4 | > 4 |
+| Parameters | < 4 | 4-6 | > 6 |
+
+### Dead Code
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Unused functions | 0 | 1-3 | > 3 |
+| Unused classes | 0 | 1-2 | > 2 |
+| Confidence HIGH items | 0 | 0 | > 0 |
+
+### Code Duplication
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Duplication % | < 3% | 3-7% | > 7% |
+| Duplicate blocks | < 3 | 3-5 | > 5 |
+
+### Pattern Issues
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Security issues | 0 | 0 | > 0 |
+| Performance issues | < 3 | 3-5 | > 5 |
+| Maintainability | < 5 | 5-10 | > 10 |
+
+### Documentation
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Public funcs documented | 100% | > 80% | < 80% |
+| Params documented | 100% | > 70% | < 70% |
+| Classes with docstrings | 100% | > 90% | < 90% |
+
+### Dependencies
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Third-party imports | < 10 | 10-20 | > 20 |
+| Local circular deps | 0 | 1-2 | > 2 |
+
+## Quick Health Check (use for rapid assessment)
+
+\`\`\`
+// Step 1: Check complexity hotspots
+get_complexity_python({
+  path: "/path/to/project",
+  recursive: true,
+  threshold: 10,
+  onlyAboveThreshold: true
+})
+
+// Step 2: Find critical patterns
+find_patterns_python({
+  path: "/path/to/project",
+  categories: ["security", "performance"]
+})
+\`\`\`
+
+## Full Health Audit
+
+\`\`\`
+// Step 1: Complexity analysis
+get_complexity_python({ path: "/path/to/project", recursive: true })
+
+// Step 2: Dead code detection
+find_dead_code_python({ path: "/path/to/project" })
+
+// Step 3: Duplication analysis
+find_duplicates_python({ path: "/path/to/project", minLines: 6 })
+
+// Step 4: Pattern analysis
+find_patterns_python({ path: "/path/to/project", categories: ["all"] })
+
+// Step 5: Documentation coverage
+extract_docstrings_python({ path: "/path/to/project" })
+\`\`\`
+
+## Analysis Report Template
+
+\`\`\`markdown
+# Code Health Report
+
+## Summary
+| Metric | Value | Status |
+|--------|-------|--------|
+| Files analyzed | N | - |
+| Avg complexity | X | Good/Warning/Critical |
+| Max complexity | Y | Good/Warning/Critical |
+| Dead code items | N | Good/Warning/Critical |
+| Duplicate blocks | M | Good/Warning/Critical |
+| Duplication % | X% | Good/Warning/Critical |
+| Security issues | S | Good/Warning/Critical |
+| Performance issues | P | Good/Warning/Critical |
+
+## Complexity Hotspots (top 5)
+| Function | File | Cyclomatic | Cognitive | Action |
+|----------|------|------------|-----------|--------|
+| process_order | orders.py:45 | 25 | 32 | Refactor immediately |
+| validate_input | utils.py:120 | 15 | 18 | Consider splitting |
+
+## Dead Code
+| Name | File | Type | Confidence |
+|------|------|------|------------|
+| old_helper | utils.py:89 | function | HIGH |
+| LegacyClass | models.py:12 | class | MEDIUM |
+
+## Code Duplication
+| ID | Lines | Files | Sample |
+|----|-------|-------|--------|
+| DUP-1 | 15 | 3 | \`def validate...\` |
+
+## Pattern Issues
+| Pattern | Severity | Count | Files |
+|---------|----------|-------|-------|
+| eval-usage | ERROR | 2 | api.py, utils.py |
+| bare-except | WARNING | 5 | various |
+| mutable-default | WARNING | 3 | models.py |
+
+## Recommendations (prioritized)
+
+### Critical (fix immediately)
+1. **Security**: Remove eval() usage in api.py:45
+2. **Complexity**: Refactor process_order() - split into smaller functions
+
+### Important (fix soon)
+1. **Dead code**: Remove unused LegacyClass
+2. **Duplication**: Extract common validation logic (DUP-1)
+
+### Suggestions (improve when touching these files)
+1. Add docstrings to undocumented public functions
+2. Fix bare except clauses - catch specific exceptions
+\`\`\`
+
+## When to Use This Skill
+
+- Before code review
+- After major refactoring
+- During tech debt assessment
+- For new team member onboarding
+- Regular health checks (weekly/monthly)
+`,
+});

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

@@ -0,0 +1,7 @@
+/**
+ * Python Code Structure Skill
+ *
+ * Analyzes Python codebase structure, organization, and architecture patterns.
+ */
+export declare const pythonCodeStructureSkill: import("@compilr-dev/agents").Skill;
+//# sourceMappingURL=python-code-structure.d.ts.map

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

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

package/dist/skills/python-code-structure.js

@@ -0,0 +1,155 @@
+/**
+ * Python Code Structure Skill
+ *
+ * Analyzes Python codebase structure, organization, and architecture patterns.
+ */
+import { defineSkill } from "@compilr-dev/agents";
+export const pythonCodeStructureSkill = defineSkill({
+    name: "python-code-structure",
+    description: "Analyze Python codebase structure and organization",
+    version: "1.0.0",
+    tags: ["python", "structure", "architecture", "analysis"],
+    prompt: `You are in Python code structure analysis mode. Use these tools systematically:
+
+## Structure Analysis Workflow
+
+### Step 1: File-Level Overview
+Use **get_file_structure_python** to understand each file:
+- Classes and their methods
+- Standalone functions
+- Module-level constants
+- Import organization
+
+### Step 2: Class Hierarchy
+Use **get_class_hierarchy_python** to understand inheritance:
+- Find parent classes (ancestors)
+- Find child classes (descendants)
+- Understand Method Resolution Order (MRO)
+- Identify mixin patterns
+
+### Step 3: Symbol Navigation
+Use **find_symbol_python** to locate definitions:
+- Find where functions are defined
+- Locate class definitions
+- Find constant declarations
+
+### Step 4: Usage Analysis
+Use **find_references_python** to understand usage:
+- How classes/functions are used
+- Import patterns across the codebase
+- Call sites and data flow
+
+## Python Package Structure
+
+### Standard Package Layout
+\`\`\`
+my_package/
+├── __init__.py          # Package exports (__all__)
+├── __main__.py          # Entry point for python -m
+├── core/
+│   ├── __init__.py
+│   └── models.py
+├── utils/
+│   ├── __init__.py
+│   └── helpers.py
+├── cli.py               # CLI entry point
+└── py.typed             # PEP 561 marker
+\`\`\`
+
+### Test Structure
+\`\`\`
+tests/
+├── __init__.py
+├── conftest.py          # pytest fixtures
+├── test_core/
+│   └── test_models.py
+└── test_utils/
+    └── test_helpers.py
+\`\`\`
+
+## Patterns to Look For
+
+### Good Patterns
+- **Layered Architecture**: Clear separation of concerns
+- **Dependency Injection**: Loose coupling via constructor params
+- **Interface Segregation**: Small, focused abstract base classes
+- **Composition over Inheritance**: Prefer has-a over is-a
+
+### Anti-Patterns
+- **God Class**: Class with too many responsibilities (>10 methods, >500 lines)
+- **Circular Dependencies**: Module A imports B, B imports A
+- **Deep Inheritance**: More than 3 levels of inheritance
+- **Spaghetti Code**: No clear structure or organization
+- **Feature Envy**: Methods that use other class's data more than their own
+
+## Structure Metrics
+
+### File Level
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Lines per file | < 300 | 300-500 | > 500 |
+| Classes per file | 1-3 | 4-5 | > 5 |
+| Functions per file | < 15 | 15-25 | > 25 |
+| Imports | < 15 | 15-25 | > 25 |
+
+### Class Level
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Methods per class | < 10 | 10-15 | > 15 |
+| Lines per class | < 200 | 200-400 | > 400 |
+| Inheritance depth | 1-2 | 3 | > 3 |
+| Public methods | < 8 | 8-12 | > 12 |
+
+### Function Level
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Lines per function | < 20 | 20-40 | > 40 |
+| Parameters | < 4 | 4-6 | > 6 |
+| Return paths | < 3 | 3-5 | > 5 |
+
+## Common Refactoring Suggestions
+
+1. **Extract Class**: Split large class into smaller focused ones
+2. **Extract Function**: Break long functions into smaller ones
+3. **Move Method**: Move method to class where data lives
+4. **Introduce Abstract Base Class**: Create interface for polymorphism
+5. **Replace Inheritance with Composition**: Use delegation instead
+
+## Structure Report Template
+
+\`\`\`markdown
+# Code Structure Report
+
+## Overview
+- Total files: N
+- Total classes: N
+- Total functions: N
+
+## Package Organization
+- Root: my_package/
+- Key modules: core, utils, api
+
+## Class Hierarchy
+1. BaseClass
+   ├── ChildA
+   └── ChildB
+       └── GrandChild
+
+## Hotspots
+1. large_module.py - 600 lines, 8 classes
+2. god_class.py::MegaClass - 25 methods
+
+## Recommendations
+1. Split large_module.py into smaller modules
+2. Extract responsibilities from MegaClass
+\`\`\`
+
+## When to Use This Skill
+
+- Onboarding to a new codebase
+- Before major refactoring
+- Architecture review
+- Documentation generation
+- Understanding legacy code
+`,
+});

package/dist/skills/python-dependency-audit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Python Dependency Audit Skill
+ *
+ * Analyzes Python imports, dependencies, and finds circular dependency issues.
+ */
+export declare const pythonDependencyAuditSkill: import("@compilr-dev/agents").Skill;
+//# sourceMappingURL=python-dependency-audit.d.ts.map

package/dist/skills/python-dependency-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-dependency-audit.d.ts","sourceRoot":"","sources":["../../src/skills/python-dependency-audit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,eAAO,MAAM,0BAA0B,qCA+OrC,CAAC"}

package/dist/skills/python-dependency-audit.js

@@ -0,0 +1,246 @@
+/**
+ * Python Dependency Audit Skill
+ *
+ * Analyzes Python imports, dependencies, and finds circular dependency issues.
+ */
+import { defineSkill } from "@compilr-dev/agents";
+export const pythonDependencyAuditSkill = defineSkill({
+    name: "python-dependency-audit",
+    description: "Audit Python imports and dependencies for issues",
+    version: "1.1.0",
+    tags: ["python", "dependencies", "imports", "audit"],
+    prompt: `You are in Python dependency audit mode. Use these tools systematically:
+
+## Dependency Audit Workflow
+
+### Step 1: Build Dependency Graph
+Use **get_dependency_graph_python** to build a complete module dependency graph:
+- Detect circular dependencies
+- Identify external vs internal dependencies
+- Find modules with excessive dependencies
+- Find highly-depended-upon modules
+
+\`\`\`
+get_dependency_graph_python({
+  path: "/path/to/project",
+  includeExternal: true
+})
+\`\`\`
+
+### Step 2: Import Analysis
+Use **get_imports_python** to categorize all imports:
+- **stdlib**: Python standard library (safe, always available)
+- **third_party**: External packages (need installation)
+- **local**: Project-internal modules
+
+### Step 3: Reference Mapping
+Use **find_references_python** to understand usage:
+- How modules depend on each other
+- What functions/classes are imported where
+- Which modules are most heavily used
+
+### Step 4: Structure Review
+Use **get_file_structure_python** to see module organization:
+- What each module exports
+- Public API surface (__all__)
+- Internal vs public modules
+
+### Step 5: Export Analysis
+Use **get_exports_python** to understand public API:
+- What symbols are in __all__
+- Public vs private symbols
+- Re-exports from submodules
+
+## Python Dependency Types
+
+### Direct Dependencies
+\`\`\`python
+import requests  # Whole module
+from flask import Flask  # Specific import
+\`\`\`
+
+### Relative Imports (Local)
+\`\`\`python
+from . import utils  # Same package
+from ..core import models  # Parent package
+from .helpers import parse  # Same package, specific
+\`\`\`
+
+### Conditional/Lazy Imports
+\`\`\`python
+if TYPE_CHECKING:
+    from heavy_module import BigClass  # Type-only
+
+def get_thing():
+    from expensive import Thing  # Lazy load
+    return Thing()
+\`\`\`
+
+## Circular Dependency Detection
+
+### Using get_dependency_graph_python
+The tool automatically detects circular dependencies:
+\`\`\`
+get_dependency_graph_python({ path: "/path/to/project" })
+// Check result.circularDependencies array
+// Each cycle shows: [A → B → C → A]
+\`\`\`
+
+### Severity Assessment
+- 2-node cycles: HIGH - direct mutual dependency
+- 3-node cycles: MEDIUM - triangular dependency
+- 4+ node cycles: LOW - long chain, often architectural
+
+### Common Solutions
+1. **Extract Common Code**: Move shared code to a third module
+2. **Use Lazy Imports**: Import inside functions, not at module level
+3. **Dependency Inversion**: Depend on abstractions, not concrete modules
+4. **TYPE_CHECKING Guard**: For type hints only, use conditional import
+
+\`\`\`python
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from other_module import SomeClass  # Only for type checking
+\`\`\`
+
+## Import Best Practices
+
+### Order (PEP 8)
+\`\`\`python
+# 1. Standard library
+import os
+import sys
+
+# 2. Third-party
+import requests
+import flask
+
+# 3. Local
+from . import utils
+from .models import User
+\`\`\`
+
+### What to Avoid
+- **\`from module import *\`**: Pollutes namespace, unclear dependencies
+- **Unused imports**: Adds clutter, confuses readers
+- **Circular imports**: Causes runtime errors
+- **Absolute imports of local modules**: Use relative imports within package
+
+## Dependency Metrics
+
+### Import Health
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Third-party deps | < 10 | 10-20 | > 20 |
+| Circular deps | 0 | 1-2 | > 2 |
+| Star imports | 0 | 0 | > 0 |
+| Unused imports | 0 | 1-3 | > 3 |
+
+### Module Coupling
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Inbound refs | < 10 | 10-20 | > 20 |
+| Outbound deps | < 8 | 8-15 | > 15 |
+| Depth in hierarchy | < 3 | 3-4 | > 4 |
+
+### Dependency Graph Stats
+| Metric | Good | Acceptable | Needs Work |
+|--------|------|------------|------------|
+| Total modules | < 50 | 50-100 | > 100 |
+| Avg deps per module | < 5 | 5-10 | > 10 |
+| Most depended-upon | < 15 | 15-25 | > 25 |
+
+## Audit Report Template
+
+\`\`\`markdown
+# Dependency Audit Report
+
+## Dependency Graph Summary
+| Metric | Value |
+|--------|-------|
+| Total modules | X |
+| Internal modules | Y |
+| External packages | Z |
+| Total edges | N |
+| Circular dependencies | M |
+
+## Circular Dependencies (if any)
+1. \`module_a.py\` → \`module_b.py\` → \`module_a.py\`
+   - Severity: HIGH (2-node cycle)
+   - Suggested fix: Extract shared code to new module
+
+## Hot Spots
+| Module | Incoming | Outgoing | Risk |
+|--------|----------|----------|------|
+| utils/__init__.py | 15 | 3 | HIGH - God module |
+| services/api.py | 2 | 12 | MEDIUM - Many deps |
+
+## External Packages (N total)
+- **Core**: requests, flask, sqlalchemy
+- **Dev**: pytest, mypy, black
+- **Potential issues**:
+  - requests + httpx (duplicate functionality)
+
+## Import Breakdown
+| Category | Count | % |
+|----------|-------|---|
+| stdlib | N | X% |
+| third_party | N | X% |
+| local | N | X% |
+
+## Unused Imports
+1. module.py:5 - unused import 'os'
+
+## Recommendations
+1. Break up utils/__init__.py into focused modules
+2. Resolve circular dependency between A and B
+3. Consider replacing requests with httpx for async support
+4. Remove unused imports (N total)
+\`\`\`
+
+## Common Scenarios
+
+### "What does this module depend on?"
+\`\`\`
+get_imports_python({ path: "module.py" })
+\`\`\`
+
+### "What depends on this module?"
+\`\`\`
+find_references_python({ name: "my_module", filterType: "import" })
+\`\`\`
+
+### "Find all circular dependencies"
+\`\`\`
+get_dependency_graph_python({ path: "/path/to/project" })
+// Check circularDependencies in result
+\`\`\`
+
+### "Find all third-party dependencies"
+\`\`\`
+get_imports_python({ path: ".", recursive: true })
+// Filter result for category: "third_party"
+\`\`\`
+
+### "Check for import issues in a directory"
+\`\`\`
+get_imports_python({ path: "src/", recursive: true })
+// Look for: star imports, unused, circular patterns
+\`\`\`
+
+### "Analyze module's public API"
+\`\`\`
+get_exports_python({ path: "module.py" })
+// Shows __all__, public symbols, re-exports
+\`\`\`
+
+## When to Use This Skill
+
+- Before adding new dependencies
+- During code review
+- Debugging import errors
+- Planning module restructuring
+- Dependency cleanup sprints
+`,
+});

package/dist/skills/python-refactor-impact.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Python Refactor Impact Skill
+ *
+ * Assesses the impact of potential code changes and refactoring.
+ */
+export declare const pythonRefactorImpactSkill: import("@compilr-dev/agents").Skill;
+//# sourceMappingURL=python-refactor-impact.d.ts.map

package/dist/skills/python-refactor-impact.d.ts.map

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