Understand an unfamiliar codebase without installing project dependencies.

A zero-third-party-runtime-dependency CLI that turns a repository into a searchable project map and explainable dependency graph.

REPOXRAY

OPEN SOURCE CLI

Text search finds words. It does not explain a project.

What grep can't tell you

Where is this functionality?

What does this file depend on?

What files use it?

What might be affected if it changes?

The gap

Find matching text — locate a string in a file.

Understand relationships — know what may depend on a file and estimate what might be affected if it changes.

RepoXray estimates dependency-based potential impact; it does not guarantee runtime breakage.

RepoXray builds an inspectable local model of the repository.

Project Mapping

Persistent JSON index of files and structure.

Indexed Search

Line-level results with optional path filtering.

Dependency Analysis

Python and JavaScript/TypeScript import extraction.

Impact Tracing

Direct and indirect potential-dependent identification.

File Inspection

Common structured and binary format analysis.

Incremental Rescanning

Added, changed, deleted, and renamed file reporting.

Every command can emit machine-readable JSON.

SCAN → INDEX → RESOLVE → ANALYZE → ANSWER

Five-stage pipeline — index stored locally as .repoxray.json

Scan

Walk the repo, detect file changes.

Index

Record metadata, SHA-256 hashes, searchable token indexes, and imports.

Resolve

Match local Python and JS/TS imports to paths.

Analyze

Build forward and reverse relationship graphs.

Answer

Return human-readable results or JSON.

Seven focused commands turn questions into answers.

scan [path]

Build or update the persistent project index.

overview [path]

Show project health, relationships, warnings, and the tree.

search <query> [path]

Search indexed content with optional path filtering.

inspect <file>

Identify and inspect supported file formats and metadata.

depends-on <file> [path]

Show the target file's dependencies.

who-uses <file> [path]

Show files that directly use the target.

impact <file> [path]

Trace direct and indirect potential dependents.

Example usage

python3 repoxray.py scan .

python3 repoxray.py overview .

python3 repoxray.py impact repoxray.py .

Uncertainty is surfaced — not silently guessed.

RepoXray classifies imported relationships as proven, heuristic, ambiguous, or unresolved. Ambiguous edges are excluded from graph traversal. Heuristic edges are included but labeled.

Python imports are extracted with the standard-library ast module. JavaScript/TypeScript imports are extracted with regular expressions — intentionally heuristic, not a complete language parser.

Proven

Resolved local, root, or relative relationship.

Heuristic

Basename fallback found one plausible candidate.

Ambiguous

Multiple candidates match; not treated as proven.

Unresolved

No repository path was resolved.

From "what changed?" to "what might be affected?"

Project Tree

Organized structure and type classification.

Relationship Counts

Proven, heuristic, ambiguous, and unresolved edge totals.

Orphan Source Files

Source files with no incoming users, excluding detected entry points.

Cycle Detection

Circular import detection in the dependency graph.

Warnings

Malformed or partial index entries surfaced explicitly.

Unknown Binaries

Unknown or non-text files retained and surfaced in health reporting.

A practical hackathon advantage: clone, run, inspect.

No third-party runtime dependencies.

RepoXray uses only the Python 3 standard library at runtime. Python 3 is required; no project package installation, virtual environment, or network service is needed.

stdlib import check

python3 -S -c "import repoxray

print('stdlib import check passed')"

argparse

CLI routing

os.walk

Repository traversal

ast

Python import extraction

re

JS/TS extraction

json

Persistent index and reports

hashlib

SHA-256 fingerprints

sqlite3

Read-only SQLite schema validation

defaultdict / deque

Graph maps and breadth-first traversal

The implementation is tested against real edge cases.

21

Tests Passing

Full suite in test_core.py

4

Test Categories

Shape, dependency, change safety, file handling

0

Third-Party Deps

At runtime — stdlib only

Edge cases tested

• Repository shape — empty projects, hidden files, ignored node_modules, Unicode paths, spaces, sorted trees.
• Dependency behavior — Python imports, relative imports, JS imports, ambiguous basenames, cycles, three-level impact chains.

• Change safety — same-size content changes, dependency addition/deletion, malformed or corrupt indexes.
• File handling — empty files, large text search, malformed JSON, deep traversal, zero-dependency import.

CI: GitHub Actions

Runs on push and PR to master — Python 3.13 — python -m unittest discover -v + python -S import check.

RepoXray turns repository archaeology into an explainable workflow.

See the Shape

Map files, categories, warnings, and health signals.

Follow the Relationships

Inspect dependencies, users, cycles, and potential impact.

Stay Honest About Uncertainty

Separate proven, heuristic, ambiguous, and unresolved edges.

Clone. Scan. Ask better questions.

github.com/saksham-2x7/repoxray