03 — Discovery & materialization: walk the crate, ask cargo

[rahlk]

Part of #9. Phase 1 — level 1.

Learning goals

Iterators and closures for real work (TRPL Functional Language Features), ? propagation
through layered Results, std::process::Command (running cargo metadata), serde_json::Value
for schemaless JSON, Path/PathBuf ownership semantics.

Task

• Discover source files: walk -i recursively for *.rs, evaluating every skip predicate
  against the path RELATIVE to the project root — target/, vendor/, .git/, and test trees
  (tests/, benches/, #[cfg(test)] modules come later) behind --skip-tests. Sort for
  deterministic output. Support the three modes: whole-project, -t target-files, -s
  single-source.
• Materialize: run cargo metadata --format-version 1 for the workspace/crate graph (crate
  names, roots, deps) — this is what makes cross-crate signatures resolvable later. Cache the
  parsed result under -c; degrade gracefully (a non-cargo folder of .rs files must still
  analyze — partial resolution, never a crash).

Teacher's notes

• The absolute-path predicate bug is the skill's marquee trap: is_vendored("/Users/you/target-practice/src/lib.rs")
  matching target in YOUR OWN path silently empties the symbol table while every test passes.
  Write the failing test first: a project rooted under a directory literally named target/.
• cargo fetch is NOT needed for level 1 — tree-sitter parses source without deps present.
  Materialization here feeds your resolver (issue 06), which needs the crate-name → root map.

Gate

• Unit tests: relative-path predicates (including the trap test above), deterministic ordering,
  the three CLI modes selecting the right file sets.
• cargo metadata degradation test: a bare directory of .rs files analyzes without error.