9thlevelsoftware/legion/codebase-mapper

Codebase Mapper

Codebase mapping engine for Legion. /legion:map is the canonical entry point. It analyzes existing codebases to produce a structured map of architecture, functionality, ownership, patterns, frameworks, risk areas, dependency graphs, test coverage, API surface, config/environment, and code patterns.

The backward-compatible human artifact remains .planning/CODEBASE.md. The full map dataset also includes machine-readable retrieval artifacts under .planning/codebase/:

• .planning/codebase/index.jsonl — chunk-level semantic index for LLM-assisted search.
• .planning/codebase/symbols.json — coarse symbols, entry points, APIs, tests, config, dependencies, and ownership areas.
• .planning/codebase/search.md — consumer protocol for semantic search/readback.
• .planning/config/directory-mappings.yaml — directory placement and validation mappings.

Consumers include /legion:start (pre-start map freshness check), /legion:plan (relevant map chunk retrieval and risk cross-reference), /legion:build (agent prompt enrichment), /legion:review (convention and risk checking), /legion:status (freshness detection), and /legion:quick (routing codebase-analysis requests to /legion:map).

All operations use Read, Bash, Glob, and Grep -- no external dependencies, no custom scripts, no MCP servers. The analysis is the host model reading and reasoning over files using a structured protocol.

References:

• State File Locations from workflow-common.md (state paths, degradation pattern)
• Codebase Map Conventions from workflow-common.md (lifecycle, paths, integration points)
• /legion:map in map.md (canonical command entry point)
• /legion:start in start.md (source detection and user-approved map pre-flight)
• /legion:plan in plan.md (map retrieval and CODEBASE.md context injection during phase decomposition)
• /legion:build in build.md (agent context injection via wave-executor Step 3.5)
• /legion:review in review.md (convention checking via review-loop Step 2.5)
• /legion:plan (critique) in skills/plan-critique/SKILL.md (risk cross-reference)
• /legion:status in status.md (staleness detection)
• /legion:quick in quick.md (routes analyze-codebase tasks to /legion:map)

Section 1: Principles & Detection

Core rules governing codebase mapping and the detection heuristic that determines when to run.

Principles

1. Opt-in only -- codebase mapping is never automatic outside an explicit /legion:map invocation. /legion:start always asks via AskUserQuestion before generating or refreshing a map. No background scanning, no silent analysis.
2. Backward-compatible markdown -- .planning/CODEBASE.md remains the human-readable architecture document consumed by older workflows.
3. Structured retrieval artifacts -- .planning/codebase/index.jsonl, .planning/codebase/symbols.json, and .planning/codebase/search.md are generated alongside CODEBASE.md so commands can retrieve relevant chunks instead of injecting the whole map.
4. No embeddings or external services -- semantic search is LLM-consumable metadata plus rg/Read over JSONL and source files. Do not require API keys, vector databases, or network services.
5. Graceful degradation -- every consumer checks for map artifact existence before using it. If absent, the workflow proceeds identically to greenfield mode. Mapping is an enhancement, never a requirement.
6. Heuristic-based -- all detection uses file presence, content grep, manifest parsing, and sampled reads, not mandatory AST/LSP analysis.
7. Depth-limited -- analysis constrains itself to avoid consuming the context window on large codebases. Work with counts, representative chunks, and summaries instead of full enumeration.
8. Calibrated scoring -- risk levels use per-file rates relative to project size, not absolute counts. A 5-file project with 10 TODOs is HIGH; a 500-file project with 10 TODOs is LOW.

When to Run

• Triggered explicitly by /legion:map
• Checked by /legion:start when existing source code is detected in the project directory
• Can be re-triggered manually with /legion:map --refresh if the codebase has changed significantly
• NEVER runs as an unannounced background scan -- /legion:start asks via AskUserQuestion before generating or refreshing the map
• If a complete map dataset exists, is <=30 days old, and its source fingerprint matches, treat it as fresh
• If CODEBASE.md exists but .planning/codebase/ artifacts are missing, treat the dataset as partial and recommend /legion:map --refresh

Source Code Detection Heuristic

Check for non-Legion files in the current directory. Run these checks in order:

1. Any source files outside .planning/ and .claude/?
   Glob("*.{ts,js,py,rb,go,rs,java,swift,kt,c,cpp,cs}")
   Glob("src/**", "app/**", "lib/**", "components/**")
 
2. Any dependency manifests at root?
   package.json, Gemfile, pyproject.toml, requirements.txt, go.mod, Cargo.toml, pom.xml
 
3. Any build/config files?
   Makefile, Dockerfile, docker-compose.yml, tsconfig.json, webpack.config.*

Decision logic:

• If ANY of the above are found: existing codebase detected. Proceed to AskUserQuestion.
• If NONE found: pure greenfield. Skip codebase mapping silently.
• If ONLY .md files found: content project, not a codebase. Skip codebase mapping silently.

Constants

CODEBASE_MAP_PATH = '.planning/CODEBASE.md'
CODEBASE_INDEX_PATH = '.planning/codebase/index.jsonl'
CODEBASE_SYMBOLS_PATH = '.planning/codebase/symbols.json'
CODEBASE_SEARCH_DOC_PATH = '.planning/codebase/search.md'
DIRECTORY_MAPPINGS_PATH = '.planning/config/directory-mappings.yaml'
MAP_SCHEMA_VERSION = '2.0'
MAX_TREE_DEPTH = 2
MAX_FILE_SAMPLE = 10  (per category — don't enumerate every file)
STALE_THRESHOLD_DAYS = 30

Graceful Degradation

• If CODEBASE.md does not exist: all consumers skip map context silently unless the command is /legion:map --query
• If .planning/codebase/ artifacts are missing but CODEBASE.md exists: fall back to CODEBASE.md only and recommend /legion:map --refresh
• If the map is stale (>30 days or fingerprint mismatch): consumers warn but do not block
• Never error, never block, never require mapping for workflow completion outside /legion:map
• All workflows function identically to their pre-map behavior when map artifacts are absent

Section 2: Map Generation (MAP-CORE-01)

Building the structural map of the codebase. This section produces the file tree, language distribution, entry points, and module structure that form the foundation of CODEBASE.md.

2.1: File Tree Summary

Generate a depth-limited directory tree, excluding noise directories and files:

# Depth-limited tree summary (max 2 levels, ignore noise)
find . -maxdepth ${MAX_TREE_DEPTH} \
  -not -path './.git/*' \
  -not -path './node_modules/*' \
  -not -path './.planning/*' \
  -not -path './.claude/*' \
  -not -name '*.lock' \
  -not -name 'package-lock.json' \
  -not -name 'yarn.lock' \
  -not -name '.DS_Store' \
  | sort

Large codebase handling:

• Count entries at depth 2. If >500 entries: reduce to maxdepth 1
• For depth-1 results, add per-directory file counts:

``bash # Count files per top-level directory for dir in $(find . -maxdepth 1 -type d -not -name '.git' -not -name 'node_modules' -not -name '.planning' -not -name '.claude'); do echo "$dir: $(find "$dir" -type f | wc -l) files" done ``

• Never enumerate every file in a directory -- summarize by count

2.2: Language Distribution

Count files by extension to understand the language composition:

For each detected extension:
  count = Glob("**/*.{ext}") result count
  percentage = (count / total_source_files) * 100
 
Sort by count descending.
Only include extensions with >= 2 files (filter noise from single-file extensions).

Output format:

Extension detection approach:

1. Run find . -type f -not -path './.git/*' -not -path './node_modules/*' -not -path './.planning/*' -not -path './.claude/*' -not -name '*.lock' via Bash
2. Extract extensions, count occurrences, sort by frequency
3. Filter to extensions with >= 2 files

2.3: Entry Points

Identify project entry points by checking for known patterns:

Detection protocol:

1. Check for each indicator file using Glob
2. For package.json: Read and extract main, module, bin fields
3. For Makefile: Read first 20 lines to find target names
4. Record each found entry point with its path and type

Output format:

2.4: Module Structure

Detect how the codebase is organized by examining directory layout:

Detection protocol:

1. List top-level and second-level directories using Glob
2. Match directory names against heuristic patterns above
3. If multiple patterns match, report the most specific one
4. Use directory name heuristics only -- do not read every file

Output: Single line describing detected structure type with evidence. Example:

Module structure: Component-based (components/, modules/ directories detected)

2.5: Directory Mapping Extraction (ENV-01, ENV-02)

Automatically identifies standard directory locations based on codebase structure and conventions.

2.5.1: Standard Category Detection

Detect these standard categories by examining directory structure: