s-map

/s:map - Codebase Mapper

Scan the project and generate a structured architectural overview. Produces a living document that helps orient anyone (human or AI) in the codebase.

Step 1: Scan Project Structure

Read the project's file tree, respecting .gitignore rules:

1. List all files and directories (skip node_modules/, .git/, dist/, build/, .next/, __pycache__/, venv/)
2. Count files by extension to detect primary languages
3. Identify the project root markers: package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, etc.
4. Detect monorepo patterns: packages/, apps/, services/, workspace configs

Display progress:

[MAP] Scanning project structure...
[MAP] Found {N} files across {M} directories
[MAP] Primary languages: {list}
[MAP] Project type: {monorepo|single-package|library|app}

Step 2: Detect Tech Stack

Identify all technologies in use:

Category	Detection Method
Language	File extensions (.ts, .py, .rs, .go)
Framework	Config files (next.config., vite.config., django settings)
Database	Migration files, ORM configs, schema files
Testing	Test runner configs (jest, vitest, pytest, cargo test)
CI/CD	.github/workflows/, Dockerfile, docker-compose.yml
Linting	.eslintrc, .prettierrc, ruff.toml, .rubocop.yml
Package mgr	package-lock.json, yarn.lock, pnpm-lock.yaml, Pipfile.lock

Output a tech stack summary table.

Step 3: Generate File Tree with Annotations

Create an annotated file tree. For each key directory and file, add a brief description:

project/
  src/
    api/               # API route handlers
      routes/           # Express/Next.js route definitions
      middleware/        # Auth, validation, error handling
    components/         # React UI components
      ui/               # Shared/primitive components
      features/         # Feature-specific components
    lib/                # Shared utilities and helpers
    db/                 # Database access layer
      migrations/       # Schema migrations
      models/           # ORM models / type definitions
    __tests__/          # Test files
  public/               # Static assets
  scripts/              # Build and dev scripts

Rules for annotation:

• Annotate directories, not every file
• Use 3-5 word descriptions
• Flag empty directories
• Flag unusually large directories (50+ files)

Step 4: Build Dependency Graph

Analyze import/require statements to build a module dependency graph:

1. Parse imports in all source files
2. Map which modules depend on which
3. Identify dependency direction (who imports whom)
4. Detect circular dependencies (flag as warnings)

Output format - adjacency list:

Module Dependencies:
  src/api/routes → src/db/models, src/lib/auth, src/lib/validation
  src/components/features → src/components/ui, src/lib/api-client
  src/db/models → src/lib/types

  CIRCULAR: src/lib/auth → src/db/models → src/lib/auth

For large projects, show only top-level module relationships, not file-by-file.

Step 5: Module Responsibility Map

For each top-level module/directory, identify its single responsibility:

Module	Responsibility	Key Files	Depends On
src/api/	HTTP request handling and routing	routes/*.ts, middleware/*.ts	db, lib
src/db/	Data persistence and queries	models/*.ts, migrations/*.sql	lib/types
src/components/	UI rendering and interaction	*.tsx	lib/api-client
src/lib/	Shared utilities and types	auth.ts, validation.ts	(none)

Flag modules that seem to have multiple responsibilities (possible refactoring target).

Step 6: Identify Entry Points

Find all entry points into the application:

Type	File	Purpose
App entry	src/index.ts	Main application start
API routes	src/api/routes/*.ts	HTTP endpoints
CLI commands	src/cli/*.ts	Command-line interface
Background jobs	src/jobs/*.ts	Scheduled/queued tasks
Tests	src/__tests__/*.test.ts	Test entry points
Config	next.config.js	Framework configuration
Scripts	scripts/*.sh	Build/deploy scripts

Step 7: Test Coverage Map

Identify which modules have tests and which don't:

Test Coverage Map:
  [TESTED]   src/api/routes/     → src/__tests__/api/
  [TESTED]   src/lib/auth.ts     → src/__tests__/lib/auth.test.ts
  [TESTED]   src/db/models/      → src/__tests__/db/
  [UNTESTED] src/components/ui/  → no test files found
  [UNTESTED] src/lib/validation  → no test files found
  [PARTIAL]  src/api/middleware/  → 2/5 files have tests

Calculate overall coverage estimate:

Estimated coverage: {N}% of modules have corresponding test files
  Tested modules: {X}/{Y}
  Untested modules: {list}

Step 8: Flag Concerns

Identify potential architectural issues:

Circular Dependencies

List any circular import chains found in Step 4.

Orphan Files

Files that are never imported by any other file (and are not entry points).

Large Files

Files exceeding 300 lines that might need splitting.

Missing Tests

Modules with no corresponding test files (from Step 7).

Mixed Concerns

Directories containing files with very different purposes.

Stale Code

Files not modified in 6+ months (check git log) that might be dead code.

Format:

Concerns:
  [CIRCULAR]  auth ↔ models circular dependency
  [ORPHAN]    src/lib/old-utils.ts - never imported
  [LARGE]     src/api/routes/users.ts - 450 lines
  [UNTESTED]  src/components/ui/ - 8 components, 0 tests
  [MIXED]     src/lib/ - contains both utils AND types AND config

Step 9: Write Output

Save the complete analysis to docs/ARCHITECTURE.md:

Structure:

# Architecture Overview
Generated: {YYYY-MM-DD}

## Tech Stack
{table from Step 2}

## File Structure
{annotated tree from Step 3}

## Module Map
{responsibility table from Step 5}

## Entry Points
{table from Step 6}

## Dependencies
{graph from Step 4}

## Test Coverage
{map from Step 7}

## Concerns
{flags from Step 8}

If docs/ARCHITECTURE.md already exists, UPDATE it rather than overwriting. Preserve any manually-added sections.

Step 10: Summary

Display a concise summary to the user:

[MAP] Codebase analysis complete.
[MAP] Saved to: docs/ARCHITECTURE.md
[MAP]
[MAP] Quick stats:
[MAP]   Files: {N} | Directories: {M} | Languages: {list}
[MAP]   Modules: {N} | Entry points: {M}
[MAP]   Test coverage: ~{N}% of modules
[MAP]   Concerns: {N} issues found
[MAP]
[MAP] Top concerns:
[MAP]   1. {most important concern}
[MAP]   2. {second concern}
[MAP]   3. {third concern}

Notes

• This skill is READ-ONLY - it analyzes but does not modify source code
• For large monorepos, offer to map a specific package/app instead of everything
• Rerun periodically to keep docs/ARCHITECTURE.md current
• Pairs well with /s:brainstorm (understand before you design) and /s:review (architecture checks)
• Respects .gitignore - never scans ignored directories
• Update STATE.md with "codebase mapped" entry after completion