@rrgarciach/flow-spec 0.1.0

package/template/ai-specs/skills/code-auditing/references/audit-methodology.md

@@ -0,0 +1,371 @@
+# Code Audit Methodology
+
+This document provides a comprehensive, systematic approach to code quality auditing. Follow these phases for thorough analysis.
+
+## Phase 0: Pre-Analysis Setup
+
+Before analyzing code, establish the context:
+
+### 1. Project Configuration
+- **Package files**: package.json, requirements.txt, go.mod, pom.xml, etc.
+- **Tech stack**: Identify languages, frameworks, and core libraries
+- **Linting configs**: eslint, prettier, black, golint, etc.
+- **Project docs**: CLAUDE.md, README.md for project-specific guidelines
+
+### 2. Baseline Checks
+Run existing linting and testing:
+```bash
+# JavaScript/TypeScript
+npm run lint
+npm run typecheck
+npm test
+
+# Python
+black --check .
+flake8
+pytest
+
+# Go
+go vet ./...
+golint ./...
+```
+
+Document existing errors/warnings as baseline.
+
+### 3. Documentation Loading
+Use Context7 to pre-load documentation for identified core libraries:
+```
+mcp__context7__resolve-library-id  → Get library ID
+mcp__context7__query-docs    → Load current best practices
+```
+
+## Phase 1: Discovery
+
+### File Identification
+Find all code files by type:
+```
+*.js, *.ts, *.jsx, *.tsx  (JavaScript/TypeScript)
+*.py                       (Python)
+*.java                     (Java)
+*.go                       (Go)
+*.rs                       (Rust)
+*.rb                       (Ruby)
+```
+
+### Organization
+- Group files by module/feature for contextual analysis
+- Create a tracking list for systematic progress
+- Prioritize core business logic over utilities
+
+## Phase 2: File-by-File Analysis
+
+For each file, analyze for the following categories:
+
+### Dead Code
+- Unused functions and methods
+- Unused variables and imports
+- Unreachable code blocks
+- Commented-out code
+- Deprecated features still present
+
+### Code Smells & Anti-Patterns
+- Functions longer than 50 lines
+- High cyclomatic complexity (> 10)
+- Deeply nested conditionals (> 3 levels)
+- Magic numbers without constants
+- Copy-paste code duplication
+- God objects/functions doing too much
+- Long parameter lists (> 5 params)
+
+### Security Vulnerabilities
+- Hardcoded secrets, API keys, passwords
+- SQL injection vulnerabilities
+- XSS (Cross-Site Scripting) risks
+- Command injection risks
+- Insecure deserialization
+- Missing input validation
+- Information disclosure in errors
+
+### Performance Issues
+- O(n²) or worse algorithms in hot paths
+- Missing database indexes
+- N+1 query patterns
+- Unnecessary synchronous operations
+- Missing caching for expensive operations
+- Large memory allocations in loops
+- Blocking I/O in async contexts
+
+### TypeScript/Type Safety Issues
+- Missing type annotations
+- Excessive use of `any` type
+- Type assertions that could be avoided
+- Custom types duplicating official @types/* packages
+- Missing null/undefined checks
+
+### Async/Promise Issues
+- Missing `await` keywords
+- Unhandled promise rejections
+- Callback hell that should use async/await
+- Fire-and-forget promises without error handling
+
+### Memory Leaks
+- Event listeners not removed on cleanup
+- Timers (setInterval, setTimeout) not cleared
+- Large objects retained unnecessarily
+- Closures holding references too long
+- DOM references kept after element removal
+
+### Error Handling
+- Empty catch blocks
+- Catch-and-ignore patterns
+- Missing try/catch in async code
+- Inconsistent error types
+- Generic error messages hiding root cause
+
+## Phase 3: Best Practices Verification
+
+### Context7 Documentation Check
+For every major library identified:
+
+1. **Resolve library ID**:
+   ```
+   mcp__context7__resolve-library-id: "react"
+   ```
+
+2. **Get current best practices**:
+   ```
+   mcp__context7__query-docs: {
+     "context7CompatibleLibraryID": "/facebook/react",
+     "topic": "hooks best practices"
+   }
+   ```
+
+3. **Focus areas**:
+   - Migration guides between versions
+   - Deprecated features and replacements
+   - Performance best practices
+   - Security considerations
+   - Common pitfalls and anti-patterns
+
+### GitHub Research
+Use `gh` CLI to research real-world usage:
+
+```bash
+# Search for patterns
+gh search code "useEffect cleanup" --language=typescript
+
+# Check repository health
+gh repo view [library] --json stargazersCount,updatedAt,openIssues
+
+# Look for security advisories
+gh api /repos/{owner}/{repo}/security-advisories
+```
+
+### Cross-Reference Findings
+- Compare actual implementation vs official documentation
+- Identify deviations from recommended patterns
+- Note outdated patterns that need modernization
+- Flag anti-patterns explicitly discouraged in docs
+
+## Phase 3.5: TypeScript Types Verification
+
+For TypeScript projects, perform additional type analysis:
+
+### Check for Duplicate Types
+Search for custom interfaces that mirror official types:
+- React types (React.FC, React.Component, event types)
+- Node.js types (Buffer, Process, Global)
+- DOM types (HTMLElement, Event types)
+- Express types (Request, Response)
+- Popular library types (lodash, axios, etc.)
+
+### Verify @types Packages
+```bash
+# Check if official types exist
+npm view @types/[library] types
+
+# Verify installed @types versions
+npm ls @types/*
+```
+
+### Common Issues
+- Custom `IRequest` when `express.Request` exists
+- Custom event types when React provides them
+- Duplicating `@types/node` built-in types
+
+## Phase 4: Pattern Detection
+
+Look for recurring issues across the codebase:
+
+### Cross-File Patterns
+- Same anti-pattern repeated in multiple files
+- Duplicated utility functions
+- Inconsistent error handling approaches
+- Different coding styles in different modules
+
+### Abstraction Opportunities
+- Repeated code that could be a utility function
+- Common patterns that could be hooks (React)
+- Cross-cutting concerns needing middleware
+
+### Inconsistencies
+- Mixed async styles (callbacks, promises, async/await)
+- Inconsistent naming conventions
+- Different error handling strategies
+- Varying code organization patterns
+
+## Phase 5: Library Recommendations
+
+For custom implementations, find mature replacements:
+
+### Discovery Process
+1. **Check existing libraries first** - Use Context7 to see if current libraries already provide needed functionality
+2. **Search package registries** - npm, PyPI, crates.io, etc.
+3. **Verify library health**:
+   - Recent commits (active development)
+   - Open issues (responsiveness)
+   - Download stats (community adoption)
+   - Security advisories (vulnerability history)
+
+### Evaluation Criteria
+- **Maintenance**: Last commit < 6 months
+- **Adoption**: Significant download/star count
+- **Security**: No unaddressed vulnerabilities
+- **Bundle size**: Important for frontend code
+- **API stability**: Semantic versioning, migration guides
+- **Documentation**: Clear examples and API docs
+
+### Common Replacements
+| Custom Implementation | Recommended Library |
+|----------------------|---------------------|
+| Date manipulation | date-fns, dayjs |
+| HTTP client | axios, ky |
+| Form validation | zod, yup |
+| State management | zustand, jotai |
+| Deep cloning | lodash/cloneDeep, structuredClone |
+| UUID generation | uuid, nanoid |
+| Retry logic | p-retry, async-retry |
+
+## Phase 6: Report Generation
+
+### Report Structure
+
+#### Executive Summary (2-3 paragraphs)
+- Total files analyzed
+- High-level findings overview
+- Key risks and recommendations
+
+#### Critical Issues (Immediate Action)
+For each:
+- File path and line number
+- Issue description
+- Security/stability impact
+- Fix example
+- Effort estimate
+
+#### High Priority Issues
+- Performance bottlenecks
+- Maintainability problems
+- Missing error handling
+
+#### Medium Priority Issues
+- Best practices violations
+- Code quality concerns
+- Type safety improvements
+
+#### Low Priority Issues
+- Style inconsistencies
+- Minor improvements
+- Documentation gaps
+
+#### Library Recommendations
+For each suggested replacement:
+- Current custom code location
+- Recommended library
+- Migration effort
+- Bundle size impact
+
+#### Quick Wins
+Low-effort, high-value fixes:
+- < 30 minutes to implement
+- High impact on quality/security
+
+#### Action Plan
+Prioritized steps with:
+- Effort estimates (S/M/L/XL)
+- Dependencies between tasks
+- Suggested sprint allocation
+
+### Report Format Requirements
+
+Each issue should include:
+```markdown
+### [PRIORITY] Issue Title
+**Location:** `src/auth/login.js:42`
+
+**Problem:**
+Description of the issue and why it matters.
+
+**Before:**
+```javascript
+// problematic code
+```
+
+**After:**
+```javascript
+// fixed code
+```
+
+**Effort:** S (< 30 min) | M (1-4 hours) | L (4-8 hours) | XL (> 8 hours)
+```
+
+## Tool Usage Reference
+
+### Context7
+```
+# Resolve library ID first
+mcp__context7__resolve-library-id: "express"
+
+# Then get documentation
+mcp__context7__query-docs: {
+  "context7CompatibleLibraryID": "/expressjs/express",
+  "topic": "middleware"
+}
+```
+
+### GitHub CLI
+```bash
+# Repository health
+gh repo view owner/repo --json stargazersCount,updatedAt
+
+# Code search
+gh search code "pattern" --language=javascript
+
+# Issues search
+gh search issues "memory leak" --repo=owner/repo
+```
+
+### Package Research
+Use `mcp__fetch__fetch` for package registry pages:
+- npmjs.com/package/[name]
+- pypi.org/project/[name]
+
+## Common Pitfalls to Avoid
+
+1. **Don't rely on assumptions** - Always verify with documentation
+2. **Don't suggest outdated patterns** - Check current best practices
+3. **Don't recommend unmaintained libraries** - Verify activity
+4. **Don't ignore project conventions** - Respect CLAUDE.md guidelines
+5. **Don't break functionality** - Ensure fixes are safe
+6. **Don't over-engineer** - Consider cost/benefit ratio
+7. **Don't skip TypeScript type checks** - Types are documentation
+8. **Don't ignore bundle size** - Frontend performance matters
+
+## Performance Optimization
+
+For large codebases:
+- **Parallel processing**: Analyze multiple files simultaneously
+- **Batch operations**: Group similar checks together
+- **Selective scanning**: Focus on changed files first
+- **Cache documentation**: Reuse Context7 lookups
+- **Progressive reporting**: Provide interim results

package/template/ai-specs/skills/code-auditing/references/dead-code-methodology.md

@@ -0,0 +1,261 @@
+# Dead Code Detection Methodology
+
+This document provides guidance on detecting and removing dead code using automated tools and manual verification.
+
+## Overview
+
+Dead code is code that exists in the codebase but is never executed. It increases maintenance burden, bundle size, and cognitive load. This methodology uses specialized tools combined with agent verification to filter false positives.
+
+## Types of Dead Code
+
+### 1. Unused Imports
+Import statements for modules/symbols that are never used:
+```javascript
+import { unused } from './utils';  // Never referenced
+```
+
+### 2. Unused Exports
+Functions, classes, variables exported but never imported elsewhere:
+```javascript
+export function formatDate() { ... }  // Not imported anywhere
+```
+
+### 3. Unused Variables
+Variables declared but never read:
+```python
+result = compute()  # Never used after assignment
+```
+
+### 4. Unused Functions/Methods
+Functions defined but never called:
+```typescript
+function legacyHelper() { ... }  // Never invoked
+```
+
+### 5. Unused Files
+Entire files not imported anywhere in the codebase.
+
+### 6. Unused Dependencies
+Packages in package.json/requirements.txt not used in code.
+
+### 7. Unreachable Code
+Code after return/throw statements or in dead branches:
+```javascript
+function foo() {
+  return 42;
+  console.log('never runs');  // Unreachable
+}
+```
+
+## Detection Tools
+
+### Knip (JavaScript/TypeScript)
+
+**Installation:**
+```bash
+npm install -g knip
+# or use via npx (no install required)
+```
+
+**Commands:**
+```bash
+# Detection (default output)
+npx knip
+
+# JSON output for parsing
+npx knip --reporter json
+
+# Fix automatically (use with caution)
+npx knip --fix
+
+# Specific workspace
+npx knip --workspace packages/core
+
+# Include/exclude patterns
+npx knip --include files --exclude dependencies
+```
+
+**Configuration (`knip.json`):**
+```json
+{
+  "$schema": "https://unpkg.com/knip@latest/schema.json",
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts"],
+  "ignore": ["**/*.test.ts"],
+  "ignoreDependencies": ["@types/*"]
+}
+```
+
+**Categories detected:**
+- files, dependencies, devDependencies
+- exports, nsExports, classMembers
+- types, nsTypes, enumMembers
+- unlisted, binaries, unresolved, duplicates
+
+### Deadcode (Python)
+
+**Installation:**
+```bash
+pip install deadcode
+```
+
+**Commands:**
+```bash
+# Detection
+deadcode .
+
+# With verbose output
+deadcode . --verbose
+
+# Fix automatically
+deadcode . --fix
+
+# Dry run (show what would be fixed)
+deadcode . --dry
+
+# Specific path
+deadcode src/
+
+# Exclude patterns
+deadcode . --exclude tests/
+```
+
+**Detection capabilities:**
+- Unused imports (DC01)
+- Unused variables (DC02)
+- Unused functions (DC03)
+- Unused classes (DC04)
+- Unused methods (DC05)
+
+## False Positive Detection
+
+**CRITICAL: Always verify findings before reporting to the user.**
+
+### Common False Positives
+
+#### 1. Dynamic Imports
+```javascript
+// These imports appear unused but are loaded at runtime
+const module = await import(modulePath);
+require(variableName);
+```
+
+#### 2. Framework Magic
+```typescript
+// React components used in JSX
+export const Button = () => <button />;  // Used as <Button />
+
+// Decorators in TypeScript/Python
+@decorator
+export class Controller {}
+
+// Vue setup functions
+export function useCounter() { ... }  // Used in <script setup>
+```
+
+#### 3. Re-exports for Public API
+```typescript
+// index.ts barrel file - exports ARE the purpose
+export { Helper } from './helper';  // Re-exported for external use
+```
+
+#### 4. Entry Points
+```javascript
+// CLI scripts, serverless handlers, etc.
+export const handler = async (event) => { ... };  // AWS Lambda entry
+```
+
+#### 5. Test Utilities
+```typescript
+// Only used in test files
+export class TestHelper {}  // Referenced in *.test.ts
+```
+
+#### 6. String-Based References
+```javascript
+// Accessed via strings or reflection
+const fn = functions['dynamicName'];
+getattr(obj, 'method_name')()
+```
+
+### Verification Checklist
+
+For each flagged item, the agent MUST:
+
+1. **Read the flagged code** to understand context
+2. **Search for dynamic references**:
+   - `import(` or `require(` with variables
+   - String interpolation with the item name
+   - `eval`, `getattr`, or reflection patterns
+3. **Check framework patterns**:
+   - React: Is it a component used in JSX?
+   - Angular: Is it decorated with @Component, @Injectable, etc.?
+   - Express: Is it middleware or route handler?
+4. **Check for re-exports**:
+   - Is this in an index.ts/index.js barrel file?
+   - Is this part of the public API?
+5. **Check entry points**:
+   - Is this a CLI script, serverless handler, or worker?
+   - Is it referenced in package.json scripts or config files?
+
+## Workflow
+
+### 1. Run Detection Tool
+```bash
+# Use the helper script
+${CLAUDE_PLUGIN_ROOT}/scripts/dead-code-detect.sh --format json
+```
+
+### 2. Parse and Categorize
+Group findings by type:
+- Unused exports
+- Unused files
+- Unused dependencies
+- Unused imports
+- Unused class members
+
+### 3. Verify Each Finding
+For each item:
+1. Read the code
+2. Check for false positive patterns
+3. Mark as "verified" or "likely false positive"
+
+### 4. Present Verified Report
+Show user:
+- Summary counts (verified items only)
+- Detailed list with file:line references
+- Filtered items with reasons
+
+### 5. Apply Fixes (After Approval)
+```bash
+# Only after user confirms
+npx knip --fix
+# or
+deadcode . --fix
+```
+
+## Integration with Audits
+
+### Quick Check Integration
+- Run detection as part of automated checks
+- Report findings under "Dead Code" category
+- Don't auto-fix; inform user of findings
+
+### Deep Audit Integration
+- Run as Phase 2.5: Dead Code Detection
+- Include in comprehensive report
+- Provide fix commands for user to run
+
+### Standalone `/dead-code` Command
+- Focused workflow for dead code only
+- Interactive cleanup with user approval
+- Show verification process
+
+## Best Practices
+
+1. **Run regularly** - Include in CI/CD pipeline
+2. **Configure properly** - Set up ignore rules for framework patterns
+3. **Test after removal** - Ensure nothing breaks
+4. **Review before commit** - Manual verification recommended
+5. **Document exceptions** - Comment why certain "dead" code is intentional
+6. **Start conservative** - Better to miss some than to break things