How brweinstein/runmd works
Project Type and Purpose
• This is a CLI tool (“runmd”) for treating Markdown files as executable notebooks.
• Primary implementation in Rust (under /src) for performance; a legacy Python implementation lives in /core.
• It locates fenced code blocks in .md files, spins up language-specific processes to run them, captures stdout/stderr, and injects standardized output blocks back into the Markdown.
File Structure
Top-level:
• Cargo.toml, src/ → active Rust code
• core/ → legacy Python code
• tests/ → benchmarks and integration tests (Rust and Python)
• README, license, config files.
Rust modules (src/):
• main.rs → CLI entry point (argument parsing, subcommand dispatch)
• core.rs → Markdown parsing, block detection
• runner.rs → execution engine (serial/parallel)
• languages.rs → built-in language definitions
• config.rs → external config loading (~/.config/runmd/languages.config)
Python modules (core/):
• Mirror of Rust: cli.py, core.py, runner.py, languages.py, plus utils.py.
README for Additional Insights
• CLI flags (-c, --init-config, -p, etc.).
• Performance goals: parsing speed, parallel execution.
• Extensibility: user config file for custom commands.
• Workflow: find blocks → write temp files → run interpreters/compilers → capture outputs → rewrite Markdown.
a. Main Components
• CLI Layer (Rust: main.rs / Python: cli.py)
• Parser (Rust: core.rs / Python: core.py)
• Execution Engine (Rust: runner.rs / Python: runner.py)
• Language Configuration (Rust: languages.rs + config.rs; Python: languages.py)
• File System & OS process manager (spawns interpreters, handles temp files)
• External Config Store (~/.config/runmd/languages.config)
• Test Harness (benchmarks & integration tests in tests/)
b. Relationships & Data Flows
1. User invokes CLI → CLI parses args
2. CLI hands off to Parser → scanning the Markdown
3. Parser emits a list of code‐block jobs
4. Execution Engine schedules jobs (serial vs. parallel)
5. For each job:
– Consult Language Config → build command string
– Write temp file → spawn OS process → capture output
6. Engine returns results → Parser/Renderer inserts output blocks
7. CLI writes the transformed Markdown back to disk (or stdout)
8. Clear operation (-c) reverses the injection step.
c. Architectural Patterns & Principles
• Modular separation: parsing, execution, config.
• Pipeline pattern: source → transform → sink.
• Strategy pattern: per‐language execution strategy.
• Configurable extension point for new languages via YAML file.
• Parallel execution for throughput (thread pool or async).
d. Key Technologies & Frameworks
• Rust toolchain & Cargo
• Python 3.8+ (legacy)
• OS process spawning (std::process::Command / subprocess)
• YAML or similar for user config
• Markdown parsing library (custom in Rust/Python core)