How georgepearse/tsrs works
Project Type and Purpose
• This is a Rust-based command-line tool (tsrs-cli) for performing tree-shaking (dead-code elimination) on Python modules/packages and producing “slim” virtual environments or minified source files.
• It also exposes its core engine as a Python extension via PyO3 for direct library use.
File Structure Analysis
• src/bin/cli.rs & tsrs-minify-tree.rs: Two CLI entry points (main app and a specialized minify tool).
• src/lib.rs + modules (venv.rs, imports.rs, callgraph.rs, slim.rs, minify.rs, reporting.rs, error.rs): Core library implementing:
– Virtual environment discovery & analysis (venv),
– Python import extraction (imports),
– Call‐graph construction & dead code detection (callgraph),
– Slim‐venv creation (slim),
– Minified source rewriting (minify),
– Reporting & stats (reporting).
• scripts/: Utility scripts for build/bootstrap.
• docs/ + site/: MkDocs documentation.
• test_packages/ & tests/: Integration and unit test suites.
• Cargo.toml & mkdocs.yml: Build and doc configuration.
Key Architecture Descriptions from README
• Core engine stages:
1. Scan Python code for imports
2. Discover packages in a venv
3. Build call graph across modules
4. Detect dead/unused code
5. Produce slim venv or rewrite source files
• Modules are highly decoupled, communicating via well-defined data structures (AST extracts, call-graph models, plan JSON).
a. Main Components
• CLI Layer (tsrs-cli binary)
• Core Engine Library
• Venv Discovery Module
• Import Extraction Module
• Call-Graph Module
• Dead-Code Analysis Module
• Slim-Venv Creator
• Minify/Rewriter
• Reporting
• Python Extension (PyO3 wrapper)
• File System / Python Virtual Env (external)
• Tests & CI (Cargo test & GitHub Actions)
b. Relationships & Data Flow
• User invokes CLI → CLI parses flags (analyze/slim/minify/plan)
→ passes config to Core Engine
→ Venv module scans FS for installed packages
→ Imports module parses Python source into import lists
→ Call-Graph module builds usage graph
→ Dead-Code module marks unused nodes
→ Slim module copies only used packages to new venv
or Minify module rewrites source files in place or out-dir
→ Reporting module aggregates stats/JSON/diffs → CLI outputs results
• Python Extension provides library entry points calling the same Core Engine API.
c. Architectural Patterns / Principles
• Pipeline pattern: clear sequential stages (scan → analyze → transform → report).
• Modular design: each concern in its own module.
• High-precision, conservative dead-code elimination.
• Parallel processing (Rayon thread pool) for directory operations.
d. Key Technologies & Frameworks
• Rust/Cargo, Clap (CLI parsing), Rayon (parallel jobs), PyO3 (Python bindings), MkDocs (documentation), GitHub Actions (CI), Virtualenv & file system interactions.