dev-code-quality

Code Quality Scan

Systematic codebase scan that identifies duplication, redundancy, architectural issues, and improvement opportunities. Produces a prioritized action plan.

Workflow

Step 1: Scope Definition

Determine the scan scope:

• Full repo: Scan everything (default)
• Directory: Scan a specific package/module
• Post-change: Scan only files changed since last commit or compared to a branch

Step 2: Structural Analysis

1. Project layout: Map the directory structure and identify the architecture pattern (flat, layered, hexagonal, etc.)
2. Dependency graph: Trace imports between packages to identify:
   • Circular dependencies
   • Unexpected cross-layer dependencies
   • Packages that import too many others (high fan-out)
   • Packages imported by too many others (high fan-in, potential God package)
3. File size distribution: Flag unusually large files (likely candidates for splitting)

Step 3: Duplication Detection

Search for code duplication across the codebase:

1. Structural duplication: Similar function signatures, similar struct/type definitions
2. Logic duplication: Repeated patterns (error handling, validation, formatting)
3. Cross-package duplication: Same utility reimplemented in multiple packages

For each duplication found, report:

• Location (files and line ranges)
• Nature of duplication (exact copy, similar pattern, same concept)
• Suggested refactoring (extract function, create shared package, use interface)

Step 4: Redundancy Check

1. Dead code: Functions, types, or constants that are never referenced
2. Unused imports/dependencies: Check go.mod, package.json for unused entries
3. Overlapping abstractions: Multiple types or interfaces serving the same purpose
4. Unnecessary complexity: Over-abstracted code, premature generalization

Step 5: Architecture Assessment

Evaluate the overall design:

1. Separation of concerns: Are layers (CLI, domain, storage, etc.) cleanly separated?
2. API surface: Are internal details leaking through public interfaces?
3. Error handling: Is error handling consistent? Are errors wrapped with context?
4. Naming consistency: Are naming conventions consistent across the codebase?

Step 6: Report & Prioritize

Present findings as a prioritized list:

Code Quality Scan Results:

High Priority:
1. [Issue] — [Location] — [Impact] — [Suggested fix]
2. ...

Medium Priority:
3. [Issue] — [Location] — [Impact] — [Suggested fix]
4. ...

Low Priority (nice to have):
5. ...

Prioritization criteria:

• High: Bugs, security issues, significant duplication, architectural violations
• Medium: Code quality improvements, moderate duplication, naming inconsistencies
• Low: Style preferences, minor optimizations, cosmetic improvements

Ask the user which items to address, then work through them.

What NOT to Flag

• Minor style differences that don't affect readability
• Test file duplication (test fixtures often intentionally repeat setup)
• Generated code
• Vendor/third-party code

Common Findings

• Formatter/display code duplicated across CLI commands: Extract to shared output or formatter package
• Similar validation logic in multiple handlers: Create a validation middleware or shared validator
• Multiple config parsing approaches: Consolidate into a single config package
• Type overlap between layers: Domain types leaked into CLI or storage layers
• N+1 patterns: Loop with individual API/DB calls instead of batch operations

Examples

Example 1: Full repo scan

User: "scan the repo and suggest improvements"
Action:
1. Map project structure
2. Trace dependencies between packages
3. Search for duplicated patterns
4. Check for dead code
5. Assess architecture
6. Present prioritized report

Example 2: Post-refactor validation

User: "find code duplications and refactoring plan"
Action:
1. Focus on structural and logic duplication
2. Identify extraction candidates
3. Propose concrete refactoring steps with file references
4. Estimate scope of each refactoring