@compilr-dev/agents-coding-go 0.1.0

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

@@ -0,0 +1,246 @@
+/**
+ * Go Dependency Audit Skill
+ *
+ * Analyzes Go imports, dependencies, and finds circular dependency issues.
+ */
+import { defineSkill } from "@compilr-dev/agents";
+export const goDependencyAuditSkill = defineSkill({
+    name: "go-dependency-audit",
+    description: "Audit Go imports and dependencies for issues",
+    version: "1.1.0",
+    tags: ["python", "dependencies", "imports", "audit"],
+    prompt: `You are in Go dependency audit mode. Use these tools systematically:
+
+## Dependency Audit Workflow
+
+### Step 1: Build Dependency Graph
+Use **get_dependency_graph_go** 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_go({
+  path: "/path/to/project",
+  includeExternal: true
+})
+\`\`\`
+
+### Step 2: Import Analysis
+Use **get_imports_go** to categorize all imports:
+- **stdlib**: Go standard library (safe, always available)
+- **third_party**: External packages (need installation)
+- **local**: Project-internal modules
+
+### Step 3: Reference Mapping
+Use **find_references_go** 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_go** to see module organization:
+- What each module exports
+- Public API surface (__all__)
+- Internal vs public modules
+
+### Step 5: Export Analysis
+Use **get_exports_go** to understand public API:
+- What symbols are in __all__
+- Public vs private symbols
+- Re-exports from submodules
+
+## Go 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_go
+The tool automatically detects circular dependencies:
+\`\`\`
+get_dependency_graph_go({ 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.go\` → \`module_b.go\` → \`module_a.go\`
+   - Severity: HIGH (2-node cycle)
+   - Suggested fix: Extract shared code to new module
+
+## Hot Spots
+| Module | Incoming | Outgoing | Risk |
+|--------|----------|----------|------|
+| utils/__init__.go | 15 | 3 | HIGH - God module |
+| services/api.go | 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.go:5 - unused import 'os'
+
+## Recommendations
+1. Break up utils/__init__.go 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_go({ path: "module.go" })
+\`\`\`
+
+### "What depends on this module?"
+\`\`\`
+find_references_go({ name: "my_module", filterType: "import" })
+\`\`\`
+
+### "Find all circular dependencies"
+\`\`\`
+get_dependency_graph_go({ path: "/path/to/project" })
+// Check circularDependencies in result
+\`\`\`
+
+### "Find all third-party dependencies"
+\`\`\`
+get_imports_go({ path: ".", recursive: true })
+// Filter result for category: "third_party"
+\`\`\`
+
+### "Check for import issues in a directory"
+\`\`\`
+get_imports_go({ path: "src/", recursive: true })
+// Look for: star imports, unused, circular patterns
+\`\`\`
+
+### "Analyze module's public API"
+\`\`\`
+get_exports_go({ path: "module.go" })
+// 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/go-refactor-impact.d.ts

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

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

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

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

@@ -0,0 +1,232 @@
+/**
+ * Go Refactor Impact Skill
+ *
+ * Assesses the impact of potential code changes and refactoring.
+ */
+import { defineSkill } from "@compilr-dev/agents";
+export const goRefactorImpactSkill = defineSkill({
+    name: "go-refactor-impact",
+    description: "Assess impact of Go code changes and refactoring",
+    version: "1.1.0",
+    tags: ["python", "refactoring", "impact", "analysis"],
+    prompt: `You are in Go refactor impact analysis mode. Use these tools systematically:
+
+## Impact Analysis Workflow
+
+### Step 1: Find the Symbol
+Use **find_symbol_go** to locate what you want to change:
+- Function definition
+- Class definition
+- Method or constant
+
+### Step 2: Find All References
+Use **find_references_go** 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_go** to understand function relationships:
+- Who calls this function?
+- What functions does it call?
+- Trace impact through call chains
+
+\`\`\`
+get_call_graph_go({
+  startFunction: "process_order",
+  path: "/path/to/project",
+  direction: "both",  // "callers", "callees", or "both"
+  maxDepth: 3
+})
+\`\`\`
+
+### Step 4: Understand the Hierarchy
+Use **get_class_hierarchy_go** 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_go** 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_go({
+  name: "BaseHandler",
+  scope: "/path/to/project"
+})
+\`\`\`
+
+### Step 6: Check Dependencies
+Use **get_imports_go** to see module dependencies:
+- What imports this module?
+- Breaking changes affect all importers
+
+### Step 7: Assess Complexity
+Use **get_complexity_go** 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__.go 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
+
+## Go-Specific Considerations
+
+### Duck Typing Impact
+- Go 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_go)
+- [ ] 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_go 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_go)
+- [ ] Check for super() calls
+- [ ] Check for overridden methods
+- [ ] Check for ABC abstract methods
+
+### Before Moving Code
+- [ ] Find all imports (find_references_go with type: import)
+- [ ] Check for relative imports
+- [ ] Update __init__.go 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.go | 42 | call | foo() |
+| b.go | 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.go, test_bar.go
+
+## 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__.go
+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/skills/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Go Skills
+ *
+ * Skills for Go code analysis, best practices, and workflows.
+ */
+export { goBestPracticesSkill } from "./go-best-practices.js";
+export { goCodeHealthSkill } from "./go-code-health.js";
+export { goCodeStructureSkill } from "./go-code-structure.js";
+export { goDependencyAuditSkill } from "./go-dependency-audit.js";
+export { goRefactorImpactSkill } from "./go-refactor-impact.js";
+import type { Skill } from "@compilr-dev/agents";
+/**
+ * All Go skills
+ */
+export declare const goSkills: Skill[];
+/**
+ * Go skills by name for selective use
+ */
+export declare const goSkillsMap: {
+    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,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAOhE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,KAAK,EAM3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;CAMd,CAAC"}

package/dist/skills/index.js

@@ -0,0 +1,36 @@
+/**
+ * Go Skills
+ *
+ * Skills for Go code analysis, best practices, and workflows.
+ */
+// Individual skill exports
+export { goBestPracticesSkill } from "./go-best-practices.js";
+export { goCodeHealthSkill } from "./go-code-health.js";
+export { goCodeStructureSkill } from "./go-code-structure.js";
+export { goDependencyAuditSkill } from "./go-dependency-audit.js";
+export { goRefactorImpactSkill } from "./go-refactor-impact.js";
+import { goBestPracticesSkill } from "./go-best-practices.js";
+import { goCodeHealthSkill } from "./go-code-health.js";
+import { goCodeStructureSkill } from "./go-code-structure.js";
+import { goDependencyAuditSkill } from "./go-dependency-audit.js";
+import { goRefactorImpactSkill } from "./go-refactor-impact.js";
+/**
+ * All Go skills
+ */
+export const goSkills = [
+    goBestPracticesSkill,
+    goCodeHealthSkill,
+    goCodeStructureSkill,
+    goDependencyAuditSkill,
+    goRefactorImpactSkill,
+];
+/**
+ * Go skills by name for selective use
+ */
+export const goSkillsMap = {
+    bestPractices: goBestPracticesSkill,
+    codeHealth: goCodeHealthSkill,
+    codeStructure: goCodeStructureSkill,
+    dependencyAudit: goDependencyAuditSkill,
+    refactorImpact: goRefactorImpactSkill,
+};

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

@@ -0,0 +1,51 @@
+/**
+ * extractDocstrings Tool
+ *
+ * Extract documentation comments from Go code.
+ * Go uses godoc-style comments above declarations.
+ */
+import type { Tool } from "@compilr-dev/agents";
+import type { DocumentationResult } from "./types.js";
+/**
+ * Input for extractDocstrings tool
+ */
+export interface ExtractDocstringsInput {
+    /** Path to Go file or directory */
+    path: string;
+    /** Recursive scan for directories */
+    recursive?: boolean;
+    /** Filter by symbol name */
+    name?: string;
+    /** Include undocumented symbols */
+    includeUndocumented?: boolean;
+    /** Maximum files to process */
+    maxFiles?: number;
+}
+/**
+ * Output from extractDocstrings tool
+ */
+export interface ExtractDocstringsResult {
+    /** Analyzed path */
+    path: string;
+    /** Documentation results */
+    docs: DocumentationResult[];
+    /** Statistics */
+    stats: {
+        total: number;
+        documented: number;
+        undocumented: number;
+        percentage: number;
+    };
+}
+/**
+ * extractDocstrings tool - Extract Go documentation
+ */
+export declare const extractDocstringsTool: Tool<ExtractDocstringsInput>;
+/**
+ * Factory function to create a customized extractDocstrings tool
+ */
+export declare function createExtractDocstringsTool(options?: {
+    defaultMaxFiles?: number;
+    defaultIncludeUndocumented?: 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;AASrE,OAAO,KAAK,EACV,mBAAmB,EAMpB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,EAAE,mBAAmB,EAAE,CAAC;IAC5B,iBAAiB;IACjB,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAsCD;;GAEG;AACH,eAAO,MAAM,qBAAqB,8BAKhC,CAAC;AAqRH;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE;IACpD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC,GAAG,IAAI,CAAC,sBAAsB,CAAC,CAmB/B"}