Scope

Turn any file or directory into a structured codebase orientation map with entry points, exports, imports, symbol roles, and an importance ranking, as machine-readable JSON.

Scope is a CLI for the problem every developer meets: what is this file, what matters in it, and where do I look first? Instead of reading a whole file to find out, scope parses it with Tree-sitter (25+ languages), classifies each symbol into a role, detects structural anomalies, and ranks symbols by cross-file importance and blast radius, then emits clean JSON for jq, a script, or a coding agent.

Features

• One-file or whole-directory orientation, output as strict JSON (no human-formatting layer to fight).
• Role classification — every symbol tagged as an entry_point, http_caller, normalizer, accessor, mutator, predicate, etc.
• Graph ranking — PageRank over the import graph + transitive blast radius, so central files surface first.
• Anomaly detection — 12 heuristic rules flag high nesting, silent catch blocks, hardcoded values, unused exports, and more.
• Fast — symbol cache, --changed <ref> for diff-scoped scans, and 25+ languages via Tree-sitter.

Quick Start

pip install -e .          # or: uv sync && uv tool install .
scope --path src/main.py

JSON for any file in one command.

Usage

scope --path src/main.py             # one file  → JSON object
scope --path src/                    # a directory → JSON array of files
scope --path src/ --mode audit       # repo-wide structural view (JSON)
scope --path src/ --changed           # only files changed since HEAD
scope --path src/ --changed v1.0      # files changed since a ref
scope --schema                        # document the JSON shape, then exit

Drill in with jq:

scope --path src/ | \
  jq -r '.[].symbols[] | select(.role != "unknown") | [.name, .role, .refs, .blast_radius] | @tsv'

Documentation

• Reference — CLI flags & the JSON contract
• Tutorial — orient yourself in a new codebase
• How-to — practical workflows
• Architecture — how scope works

Contributing

Bug reports and pull requests are welcome. Requirements are enforced in CI (ruff, mypy, pytest).

License

MIT — see LICENSE.