skillstore-cli 1.0.0

package/data/shared/framework/skills/codebase-analysis/references/analysis-techniques.md

@@ -0,0 +1,241 @@
+# Analysis Techniques
+
+## Directory Structure Analysis
+
+### Identifying Architectural Patterns
+
+Examine the top-level directory layout to determine the architectural style:
+
+**Layered Architecture** — organized by technical concern:
+```
+src/
+  controllers/    # HTTP handlers
+  services/       # Business logic
+  repositories/   # Data access
+  models/         # Data structures
+  middleware/     # Cross-cutting concerns
+```
+
+**Feature-Based Architecture** — organized by domain feature:
+```
+src/
+  auth/           # Login, registration, tokens
+  tasks/          # Task CRUD, assignment
+  notifications/  # Email, push, in-app
+  shared/         # Common utilities
+```
+
+**Domain-Driven Design** — organized by bounded context:
+```
+src/
+  domains/
+    identity/     # User, role, permission
+    project/      # Project, milestone
+    task/          # Task, subtask, comment
+  infrastructure/ # DB, messaging, external APIs
+  application/    # Use cases, orchestration
+```
+
+### Structure Scan Commands
+
+```bash
+# Directory overview (3 levels, directories only)
+tree -L 3 -d
+
+# Find all entry points
+find . -name 'index.*' -o -name 'main.*' -o -name 'app.*' | grep -v node_modules
+
+# List all package.json files in a monorepo
+find . -name 'package.json' -not -path '*/node_modules/*' -maxdepth 3
+
+# Count files per directory (identify large modules)
+find src -type f | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20
+
+# Find configuration files
+find . -maxdepth 2 -name '*.config.*' -o -name '.*.rc' -o -name '.*rc.json' | grep -v node_modules
+```
+
+## Import/Dependency Graph Traversal
+
+### Tools by Language
+
+| Language | Tool | Install | Generate Graph |
+|---|---|---|---|
+| JavaScript/TS | madge | `npm i -g madge` | `madge --image graph.svg src/` |
+| Python | pydeps | `pip install pydeps` | `pydeps mypackage --cluster` |
+| Go | go mod graph | built-in | `go mod graph \| dot -Tsvg -o graph.svg` |
+| Java | jdeps | built-in (JDK) | `jdeps -summary -cp . *.jar` |
+| Rust | cargo-depgraph | `cargo install cargo-depgraph` | `cargo depgraph \| dot -Tsvg -o graph.svg` |
+
+### Reading Dependency Graphs
+
+- **Hub nodes** (many incoming edges): core modules everyone depends on — change carefully
+- **Leaf nodes** (many outgoing edges): modules with many dependencies — potential coupling issue
+- **Cycles**: circular arrows between nodes — must be broken for maintainability
+- **Clusters**: groups of tightly connected nodes — natural module boundaries
+
+## Dead Code Detection
+
+### Tools
+
+| Tool | Language | What It Finds |
+|---|---|---|
+| knip | JS/TS | Unused files, exports, dependencies, types |
+| ts-prune | TypeScript | Unused exports |
+| vulture | Python | Unused code (functions, variables, imports) |
+| deadcode | Go | Unreachable functions |
+
+### Coverage-Based Detection
+
+Files and functions with zero test coverage AND zero runtime usage (from logs/APM) are strong candidates for dead code:
+
+```bash
+# Find files never imported by any other file (JS/TS)
+madge --orphans src/
+
+# Find exports not imported anywhere (TypeScript)
+npx ts-prune | grep -v '(used in module)'
+
+# Comprehensive unused detection (JS/TS monorepo)
+npx knip
+```
+
+### Manual Heuristics
+
+- Files not modified in 12+ months with zero test coverage
+- Feature flags that have been permanently on/off
+- Commented-out code blocks (should be deleted — git has history)
+- API endpoints with zero traffic in monitoring dashboards
+
+## Complexity Metrics
+
+### Cyclomatic Complexity
+
+Measures the number of independent paths through code. Higher = harder to test and understand.
+
+| Score | Risk Level | Action |
+|---|---|---|
+| 1-5 | Low | Simple, well-testable |
+| 6-10 | Moderate | Consider refactoring |
+| 11-20 | High | Refactor — hard to test thoroughly |
+| 21+ | Critical | Must refactor — untestable |
+
+```bash
+# ESLint complexity rule (JavaScript/TypeScript)
+npx eslint --rule '{"complexity": ["error", 10]}' src/
+
+# Radon for Python
+radon cc src/ -a -nc
+
+# gocyclo for Go
+gocyclo -over 10 .
+```
+
+### Cognitive Complexity
+
+Measures how difficult code is to understand (SonarSource metric). Unlike cyclomatic complexity, it penalizes nested control flow more heavily.
+
+Key penalties:
+- Each nesting level adds to the score
+- `break`/`continue` with labels add extra
+- Recursion adds a penalty
+- Boolean operator sequences (`a && b || c && d`) add per operator
+
+### Halstead Metrics
+
+Volume-based metrics from operator/operand counts:
+- **Difficulty**: how error-prone the code is
+- **Volume**: information content of the code
+- **Effort**: estimated mental effort to understand
+
+Useful for comparing relative complexity between modules rather than absolute thresholds.
+
+## File Change Frequency Analysis (Hotspot Detection)
+
+Files that change frequently are maintenance hotspots. Combined with complexity, they indicate refactoring priority.
+
+```bash
+# Top 20 most frequently changed files (last 6 months)
+git log --since="6 months ago" --format=format: --name-only | sort | uniq -c | sort -rn | head -20
+
+# Change frequency for a specific file
+git log --format='%H' --follow src/services/taskService.ts | wc -l
+
+# Files changed together (coupling detection)
+git log --format=format: --name-only | awk 'NF' | sort | uniq -c | sort -rn
+
+# Correlate with bug-fix commits
+git log --grep='fix\|bug\|hotfix' --format=format: --name-only | sort | uniq -c | sort -rn | head -20
+```
+
+### Hotspot Matrix
+
+| | Low Change Frequency | High Change Frequency |
+|---|---|---|
+| **Low Complexity** | Stable — leave alone | Active development — monitor |
+| **High Complexity** | Legacy risk — document | **Refactoring priority** |
+
+## Test Coverage Mapping
+
+### Coverage by Module
+
+Rather than a single coverage number, break down coverage by module to find gaps:
+
+```bash
+# Jest coverage by directory
+npx jest --coverage --coverageReporters=text | grep -E '^[A-Za-z]'
+
+# Python coverage by module
+python -m pytest --cov=src --cov-report=term-missing
+
+# Go coverage by package
+go test -coverprofile=coverage.out ./...
+go tool cover -func=coverage.out
+```
+
+### Coverage vs. Risk Matrix
+
+| | Low Coverage | High Coverage |
+|---|---|---|
+| **Low Risk** (internal tools, admin) | Acceptable | Over-invested |
+| **High Risk** (payments, auth, data) | **Dangerous gap** | Appropriate |
+
+Focus testing investment on high-risk, low-coverage areas.
+
+## API Surface Analysis
+
+### Public Export Inventory
+
+```bash
+# List all exports in a TypeScript project
+npx ts-prune --skip-types | grep -v '(used in module)'
+
+# Find all exported functions/classes in Python
+grep -rn 'def \|class ' --include='*.py' src/ | grep -v '_'
+
+# Check what a package exposes
+node -e "console.log(Object.keys(require('./src')))"
+```
+
+### Backward Compatibility Assessment
+
+Check for breaking changes before modifying public APIs:
+- Removed or renamed exports
+- Changed function signatures (new required parameters)
+- Modified return types
+- Changed error types/codes
+- Altered side effects
+
+## Entry Point Tracing
+
+Follow a request from entry to database to understand a feature's full path:
+
+1. **HTTP Route** — find the route definition (`app.get('/tasks', ...)`)
+2. **Controller/Handler** — request parsing, validation, response formatting
+3. **Middleware** — auth checks, rate limiting, logging
+4. **Service Layer** — business logic, orchestration
+5. **Repository/Data Access** — database queries, cache reads
+6. **External Calls** — third-party APIs, message queues
+7. **Response** — serialization, status code selection
+
+Document this path for critical flows (authentication, payment, data export) to understand blast radius before changes.

package/data/shared/framework/skills/codebase-analysis/references/dependency-mapping.md

@@ -0,0 +1,280 @@
+# Dependency Mapping
+
+## Module Dependency Graphs
+
+### Generating Graphs
+
+```bash
+# JavaScript/TypeScript — visual graph
+madge --image graph.svg src/
+madge --image graph.svg --ts-config tsconfig.json src/
+
+# JavaScript/TypeScript — text output
+madge src/ --json > dependencies.json
+
+# Include only specific extensions
+madge --extensions ts,tsx src/
+
+# Python — visual dependency graph
+pydeps mypackage --cluster --max-bacon 3
+
+# Go — module dependency graph
+go mod graph | sed 's/@[^ ]*//g' | sort -u
+
+# Monorepo — workspace dependency graph
+npx turbo run build --graph=graph.svg
+```
+
+### Reading the Graph
+
+Key patterns to look for:
+
+- **Fan-out modules**: A module that imports 10+ other modules may be doing too much. Consider splitting responsibilities.
+- **Fan-in modules**: A module imported by 10+ others is a core dependency. Changes here have wide blast radius — test thoroughly.
+- **Long chains**: A → B → C → D → E means A is transitively coupled to E. Changes in E can break A unexpectedly.
+- **Islands**: Disconnected clusters may indicate dead code or poorly integrated features.
+
+## Circular Dependency Detection
+
+### Finding Cycles
+
+```bash
+# JavaScript/TypeScript
+madge --circular src/
+madge --circular --ts-config tsconfig.json src/
+
+# Python
+pydeps mypackage --show-cycles
+
+# Go (no built-in — use import analysis)
+go vet ./...  # will flag import cycles
+```
+
+### Why Circular Dependencies Are Problematic
+
+- **Build issues**: bundlers and compilers may produce undefined values or crash
+- **Initialization order**: module A depends on module B's value at import time, but B hasn't finished initializing because it's waiting on A
+- **Tight coupling**: changes in either module may break the other, making independent development impossible
+- **Testing difficulty**: cannot test one module without the other
+
+### Breaking Cycles
+
+**Strategy 1: Extract shared code** — move the shared dependency into a third module:
+```
+Before: A → B → A (cycle)
+After:  A → C, B → C (shared module C)
+```
+
+**Strategy 2: Dependency inversion** — depend on interfaces, not implementations:
+```
+Before: Service → Repository → Service (cycle)
+After:  Service → IRepository (interface), Repository implements IRepository
+```
+
+**Strategy 3: Event-based decoupling** — replace direct calls with events:
+```
+Before: OrderService → NotificationService → OrderService
+After:  OrderService emits "order.created", NotificationService subscribes
+```
+
+**Strategy 4: Lazy loading** — defer the import to break the initialization cycle:
+```typescript
+// Instead of top-level import
+// import { helper } from './moduleB';
+
+// Use dynamic import where needed
+async function doWork() {
+  const { helper } = await import('./moduleB');
+  return helper();
+}
+```
+
+## External Dependency Audit
+
+### Outdated Packages
+
+```bash
+# npm — list outdated with current, wanted, latest
+npm outdated
+
+# npm — major version updates only
+npm outdated | awk '$2 != $4'
+
+# Python
+pip list --outdated
+
+# Go
+go list -m -u all
+```
+
+### Vulnerability Scanning
+
+```bash
+# npm built-in audit
+npm audit
+npm audit --production  # only production deps
+
+# Snyk (more comprehensive)
+npx snyk test
+
+# Python
+pip-audit
+
+# Go
+govulncheck ./...
+
+# Multi-language
+trivy fs .
+```
+
+### Abandoned Package Detection
+
+Signs a package may be abandoned:
+- Last publish date > 2 years ago
+- Open issues > 100 with no maintainer response
+- No commits in 12+ months on the default branch
+- Deprecated notice on npm/PyPI
+
+```bash
+# Check last publish date (npm)
+npm view <package> time.modified
+
+# Check open issues count (via GitHub API)
+gh api repos/<owner>/<repo> --jq '.open_issues_count'
+
+# Check last commit date
+gh api repos/<owner>/<repo>/commits?per_page=1 --jq '.[0].commit.committer.date'
+```
+
+### License Compliance
+
+```bash
+# List all licenses in the dependency tree
+npx license-checker --summary
+npx license-checker --failOn 'GPL-2.0;GPL-3.0'
+
+# Python
+pip-licenses --format=table
+
+# Go
+go-licenses check ./...
+```
+
+Common license categories:
+- **Permissive** (MIT, Apache-2.0, BSD): safe for commercial use
+- **Weak copyleft** (LGPL, MPL): safe if used as a library, not modified
+- **Strong copyleft** (GPL, AGPL): may require open-sourcing your code — consult legal
+
+## Dependency Upgrade Strategy
+
+### Automated Minor/Patch Updates
+
+- Use Dependabot or Renovate for automated PRs on minor/patch versions
+- Require CI to pass before auto-merge
+- Group related packages (e.g., all `@babel/*` in one PR)
+
+### Major Version Updates
+
+- Review changelog and migration guide before upgrading
+- Check for breaking changes in your usage patterns
+- Upgrade in isolation — one major dependency per PR
+- Run full test suite + manual smoke test
+
+### Lock File Hygiene
+
+- Always commit lock files (`package-lock.json`, `yarn.lock`, `poetry.lock`, `go.sum`)
+- Never manually edit lock files — use the package manager commands
+- Periodically regenerate: delete lock file, reinstall, verify tests pass
+- In monorepos, ensure hoisted dependencies don't cause version conflicts
+
+## API Dependency Mapping
+
+### Service-to-Service Dependencies
+
+Document which services call which endpoints:
+
+| Consumer | Provider | Endpoint | Protocol | Auth |
+|---|---|---|---|---|
+| web-app | api-gateway | /api/v1/* | HTTPS | JWT |
+| api-gateway | user-service | /users/* | gRPC | mTLS |
+| api-gateway | task-service | /tasks/* | gRPC | mTLS |
+| task-service | notification-svc | /notify | AMQP | IAM |
+| notification-svc | email-provider | /v3/mail/send | HTTPS | API Key |
+
+### Contract Testing
+
+Verify API contracts between services don't break:
+
+```bash
+# Pact (consumer-driven contract testing)
+npx pact-broker can-i-deploy --pacticipant web-app --version $(git rev-parse HEAD)
+
+# OpenAPI diff (detect breaking changes)
+npx openapi-diff old-spec.yaml new-spec.yaml
+```
+
+## Database Schema Dependencies
+
+### What to Map
+
+- **Foreign key relationships**: which tables reference which
+- **Triggers**: hidden logic that fires on INSERT/UPDATE/DELETE
+- **Stored procedures**: business logic living in the database
+- **Views**: virtual tables that depend on underlying table structure
+- **Indexes**: which queries depend on which indexes for performance
+
+### Schema Visualization
+
+```bash
+# PostgreSQL — generate ER diagram
+pg_dump --schema-only mydb | sqlt-diagram
+
+# MySQL — schema export
+mysqldump --no-data mydb > schema.sql
+
+# Use SchemaSpy for HTML-based documentation
+java -jar schemaspy.jar -t pgsql -db mydb -o docs/schema
+```
+
+### Migration Dependency Chain
+
+Review migration files in order to understand how the schema evolved. Look for:
+- Columns added but never used (dead schema)
+- Tables with no foreign keys (orphaned data)
+- Missing indexes on frequently joined columns
+
+## Shared Library Analysis (Monorepo)
+
+### Which Packages Depend on What
+
+```bash
+# Turborepo — show dependency graph
+npx turbo run build --graph
+
+# Lerna — list packages and their dependencies
+npx lerna ls --graph --all
+
+# pnpm — list why a package is installed
+pnpm why <package>
+
+# Yarn — workspace dependency info
+yarn workspaces info
+```
+
+### Shared Package Impact
+
+When modifying a shared package, identify all consumers:
+
+```bash
+# Find all workspace packages that import from @myorg/shared
+grep -rn '@myorg/shared' --include='package.json' packages/
+
+# Check which packages would be affected by a change
+npx turbo run build --filter='@myorg/shared...'
+```
+
+### Versioning Strategy for Shared Packages
+
+- **Fixed versioning**: all packages share the same version number — simpler but forces unnecessary releases
+- **Independent versioning**: each package has its own version — more flexible but harder to coordinate
+- **Recommendation**: use fixed versioning for tightly coupled packages, independent for standalone utilities