lidge-jun/repo-map

repo-map

cli-jaw map prints a compact, ranked symbol overview of a repository or subtree. It scans TS/JS-family sources, extracts definitions (functions, classes, interfaces, types, enums, exported consts, class methods), counts cross-file identifier references, and lists files ordered by reference gravity with their definitions and line numbers, cut to a token budget.

Reach for it before deep Grep dives when entering unfamiliar code: the map shows the project shape — which files own which symbols and where the likely architectural center is — so subsequent Grep/Read calls are targeted instead of exploratory.

Grep and map boundaries

Use Grep for text: literal strings, comments, config values, exact symbol lookups, and regex searches.

Use this skill for an overview map, not exact search. The map is a guide for where to inspect next, not proof that a symbol is absent. After the map narrows the territory, confirm targets with Grep/Read.

When to use this skill

• "Give me a structure map of this package."
• "I am in unfamiliar code; show me the shape first."
• "What files define the main symbols in this subtree?"
• "와꾸 먼저 보자."

CLI usage

cli-jaw map .                  # map the current repo
cli-jaw map src/ --budget 2048 # subtree map with a tighter budget

• <path> defaults to .; both files and directories are accepted.
• --budget N sets the approximate token budget (default 4096; tokens are estimated as chars/4).
• Common non-source dirs (.git, node_modules, dist, build, target, out, coverage, hidden dirs) are skipped during the walk.

Subtree maps for large monorepos

cli-jaw map <subdir> scopes BOTH the walk and the ranking to that subtree: the reference counts are computed only from files under <subdir>, so feature-partitioned monorepos get per-feature maps whose central files are not drowned out by global hubs. Prefer a subtree map plus a tight budget over one giant whole-repo map.

Ranking and coverage (v1)

• Ranking is reference-count gravity (how often a file's definitions are named across the scanned set), not PageRank. It is deterministic and dependency-free.
• Language tier: TS/JS family (.ts, .tsx, .js, .jsx, .mjs, .cjs) is the supported set. Other languages are not scanned in v1.
• Extraction is a line-based definition scan, honest about its limits: exotic syntax may be missed. Treat the map as orientation, then inspect the surfaced files.

Degradation

• cli-jaw map --help prints usage and exits 0 with no engine work.
• An unreadable or missing path prints one hint line and exits 1 — never a stack trace.

Doctrine

On-demand only: the map body is never preloaded into the system prompt or cached by a daemon. Generate it fresh when needed; a stale map is worse than no map.