codebase-scanning

What this skill does

# Codebase Scanning

Discover strategic product context from existing codebases. Covers web and mobile platforms.

Auto-loaded by the `context-scanner` agent for all codebase scanning operations. Also loaded when `pm-setup` bootstraps project context from code.

## Scanning Process

1. **Detect platform** - Identify web, mobile, or hybrid. For mobile, follow the detection order in `references/platform-detection.md`
2. **Parse tech stack** - Read manifests to identify frameworks, languages, databases. See `references/manifest-detection.md` for supported manifests per platform
3. **Discover features** - Scan routes, pages, and components for user-facing functionality
4. **Map integrations** - Match dependencies against known 3rd party services. See `references/integration-mapping.md` for lookup tables
5. **Estimate scale** - Count files, estimate LOC, assign complexity and maturity tiers
6. **Present results** - Use `assets/presentation-template.md` format, structured per `assets/output-schema.md`

## Feature Discovery

Scan routes, pages, and components to identify user-facing functionality.

**Methods**:

- Parse route files (Express routes, Next.js pages/, API routes)
- Analyze page/component names
- Identify API endpoints from route definitions
- Map features to evidence (file paths)

**Return format per feature**:

- name: Feature name (lowercase, descriptive)
- confidence: high/medium/low
- evidence: File paths, routes, or patterns

**Common features detected**: Authentication, project/task management, team collaboration, analytics/reporting, settings/configuration.

## Tech Stack Detection

Parse package manifests and project files to identify technologies. Supports 7 web platforms (Node.js, Python, Go, Ruby, PHP, Rust, Java) and 4 mobile platforms (iOS, Android, Flutter, React Native).

Full manifest tables and per-platform detection rules: `references/manifest-detection.md`

## Integration Discovery

Match package dependencies against known 3rd party services across 9 categories: Payments, Email, SMS, Auth, Cloud, Analytics, Monitoring, Push, Maps/Location.

Full lookup tables and cross-platform dependency mapping: `references/integration-mapping.md`

## Platform Detection

For mobile projects, detect platform type using ordered priority checks (Flutter > React Native > iOS Native > Android Native > Hybrid). Includes feature discovery rules per platform.

Detection order and feature discovery methods: `references/platform-detection.md`

## Scale Estimation

**Metrics to collect**:

- Total source files (excluding node_modules, dist, build, .git)
- Lines of code (estimate: average 25 LOC per KB of source file size, excluding binary and generated files)

**Complexity tiers**:

| Tier | Files | LOC | Characteristics |
|---|---|---|---|
| Simple | <50 | ~10k | Single service |
| Medium | 50-500 | 10k-100k | Few services |
| Complex | >500 | 100k+ | Many services/repos |

**Maturity signals**:

| Stage | LOC | Indicators |
|---|---|---|
| Prototype | ~5k | Rapid changes |
| MVP | 5k-25k | Core features present |
| Established | 25k-100k | Feature-complete |
| Mature | 100k+ | Extensive feature set |

## Confidence Assignment

- **High**: Direct evidence from routes, manifest versions, clear file patterns
- **Medium**: Package present but usage not verified; ambiguous naming patterns
- **Low**: Indirect evidence, weak signals, potentially deprecated

Package installed does not mean actively used. Assign medium confidence to integrations by default.

## Edge Cases & Limitations

### Large Codebases (>100k LOC, >1000 files)

- Limit scanning to primary directories: src/, pages/, routes/, api/, lib/
- Skip: node_modules/, dist/, build/, .git/, vendor/, test/ (unless small)
- Sample large directories (first 100 files, warn about remaining)
- Maximum 60 seconds total scan time
- Graceful degradation: return partial results with limitation note

### Monorepos

**Detection**: Check for lerna.json, nx.json, turbo.json, pnpm-workspace.yaml. Identify workspace structure (packages/, apps/).

**Handling**: Scan each workspace individually. Detect mobile + web combinations. Report tech stack per app with shared packages noted.

### Hybrid Mobile Apps

- React Native with custom native modules: ios/ and android/ with custom .swift or .kt files beyond standard RN setup
- Flutter with platform channels: ios/Runner/ or android/app/ with custom native code
- Capacitor/Ionic: capacitor.config.json present

### Conflicting Manifests

- If multiple manifests disagree (e.g., package.json has both react-native and expo), report both with evidence and let the user resolve
- Prefer the more specific indicator (expo in app.json overrides generic react-native in package.json)
- For monorepos with mixed platforms, report per-app rather than trying to unify

### Other Edge Cases

- **Permission issues**: Log warning, continue with accessible files, report in scan_limitations
- **Ambiguous patterns**: Assign lower confidence, provide evidence, let user decide. Better to under-report than hallucinate
- **Deprecated code**: Report what exists (facts), flag as medium/low confidence if evidence is weak
- **Multi-language projects**: Scan all tech stacks present, report separately
- **Empty projects**: Return empty findings, note "Project appears empty or very early stage". pm-setup falls back to manual questions