Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Crate Decisions

1. Decision principles

  • Correctness and stability over novelty.
  • Keep runtime dependencies minimal for CLI/library users.
  • Use ecosystem-standard crates with strong maintenance signals.

2. Selected crates by concern

Parsing

  • tree-sitter + language crates (c, cpp, python, javascript, typescript, rust, go)
  • Rationale: robust incremental parsing and grammar-level extraction.
  • Language crates provide battle-tested queries and node definitions.
  • python, javascript, typescript as a start in every iteration.

Graph and SCC

  • petgraph
  • Rationale: mature directed graph algorithms and built-in Tarjan SCC.

Serialization

  • serde, serde_json, yaml_serde
  • Rationale: stable, standard JSON and YAML contract tooling.

CLI and watch

  • clap, notify, notify-debouncer-mini, blake3
  • Rationale: battle-tested CLI ergonomics with color, derive, and env support. notify and notify-debouncer-mini provide OS file events for watch mode. blake3 provides fast, deterministic cryptographic content hashing for file change fingerprinting.

Parallelism

  • rayon
  • Rationale: data-parallel file processing with work-stealing. A thread-local pool of Parser instances (thread_local!) enables safe parallel parse + extract per-file without non-Sync parser contention.

Enum utilities

  • strum
  • Rationale: derive macros for Display, EnumIter, EnumString on enums.

Filesystem

  • ignore, dunce
  • Rationale: gitignore-aware file walking (respecting .gitignore and .ignore files) and cross-platform path canonicalization.

Browser

  • webbrowser
  • Rationale: auto-open HTML dashboard in the user’s default browser.

Error handling

  • thiserror (library errors), anyhow (application boundary)
  • Rationale: explicit typed errors + practical context propagation.

3. Development dependencies

  • insta - snapshot testing for JSON output contracts.
  • criterion - benchmark gating (pipeline, graph, and incremental).
  • tempfile - isolated filesystem fixtures for integration testing.

4. Feature flags

  • watch - debounced file-system watch mode with incremental re-analysis and BLAKE3 fingerprinting.
  • dataflow - data/flow node tracking and def-use graph extraction.
  • metacall-deploy - includes deploy scanner/manifest/mesh generators for MetaCall deployment manifest generation.
  • tracing, tracing-subscriber - structured observability.
  • cbindgen - C ABI header generation when ABI phase begins.

6. Alternatives and trade-offs

  • Graph: custom adjacency maps can be faster but increase maintenance cost.
  • CLI: smaller parsers reduce binary size but lose feature depth.
  • JSON: high-performance serializers are unnecessary before proven bottleneck.
  • Parallelism: crossbeam scopes are an alternative but rayon’s work-stealing is better suited for file-level data parallelism.
  • Language dispatch: trait objects allow runtime plugins but lose compile-time completeness checking; enum dispatch chosen (see STRUCTURE.md).

7. Risk register

  • Grammar drift risk (low): mitigate with fixtures + snapshots.
  • Watch-mode debounce edge cases (low): mitigate with integration tests.
  • Over-scoping optional sinks (medium): keep feature-gated.

8. Policy

Crate upgrades that affect behavior must include:

  1. CI pass on all platforms.
  2. Snapshot/fixture update.
  3. Documentation update in this file and specs/symbol-extraction.md.