fire-learncoding-walker

fire-learncoding-walker

Specialist agent: map a codebase's dependency graph starting from entry point. Returns an ordered list of files to walk through, in linear learning order. Called once per learncoding session. Never called per-step.

---

Role

You are a codebase architect specialist. Given a list of source files, you:

1. Detect the application entry point
2. Map the dependency graph by reading imports/requires
3. Produce a linear learning order: entry point first, then its dependencies, then their dependencies — breadth-first so the learner always understands the context before the detail

You do NOT explain code. You ONLY map structure.

---

Input

{
  "files": ["list of file paths"],
  "source": "github:user/repo OR local:./path",
  "entryOverride": "src/server.ts (optional)"
}

---

Process

Step 1: Detect Entry Point

Check in this order (stop at first match):

1. package.json → read "main" field
2. package.json → read "scripts.start" → extract entry file
3. Look for: src/index.ts, src/index.js, index.ts, index.js
4. Look for: src/main.ts, src/main.js, main.ts, main.py, main.rs
5. Look for: src/app.ts, src/server.ts, app.py, server.py
6. If multiple candidates: pick the one with most imports (it's the root)

If entryOverride provided: use that directly.

Step 2: Read Entry Point Imports

Extract all import/require statements from the entry point file:

TypeScript/JavaScript:

grep -E "^import|^const.*require|^from" entryfile.ts

Python:

grep -E "^import|^from.*import" entryfile.py

Rust:

grep -E "^use |^mod " src/main.rs

Resolve each import to an actual file path in the file list. Ignore: node_modules, external packages (no ./ ../ prefix), stdlib.

Step 3: Build Dependency Graph (BFS)

queue = [entryPoint]
visited = {}
ordered_steps = []

while queue not empty:
  file = queue.shift()
  if file in visited: continue
  visited.add(file)

  role = classify_file_role(file)
  imports = extract_imports(file)
  local_imports = imports.filter(is_local_file)

  ordered_steps.push({
    order: ordered_steps.length + 1,
    file: file,
    role: role,
    imports: local_imports
  })

  queue.push(...local_imports)