whoareyou/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A CLI that looks up Swedish phone numbers ("who is calling me?") by scraping reverse-lookup sites. Old codebase: Rust edition 2018, reqwest 0.9 (synchronous API), insta 0.11.

Commands

cargo build
cargo run -- 0700000000                          # query a number (hitta.se built in)
cargo run -- -d definitions/vem_ringde.toml 0700000000   # add TOML-defined probes
cargo run -- -o 0700000000                       # open probe URLs in browser (macOS `open`)

cargo test                                       # all tests (insta snapshot tests)
cargo test probe::hitta                          # one module
cargo test test_0104754350                       # one test

cargo +nightly fmt                               # always nightly, not stable
cargo clippy

Tests are inline-snapshot tests (assert_yaml_snapshot!(..., @r###"..."###)) against checked-in HTML fixtures in fixtures/<provider>/<number>.html — no network needed. Refresh/add fixtures with ./fetch-fixture <number> (requires http/httpie); it fetches the number from all five sites into fixtures/.

Architecture

Everything revolves around the Probe trait (src/probe.rs): provider(), uri(number), fetch(number), parse(html) -> Result<Entry, ()>.

Two kinds of probes:

1. Hard-coded: Hitta (src/probe/hitta.rs) — extracts the __NEXT_DATA__ JSON blob via regex and deserializes it with serde. Always registered in main.rs.
2. Declarative: Definition (src/definition.rs) — generic scraper configured by a TOML file (definitions/*.toml) with CSS selectors for messages, history, and comments (each comment has optional date_time/title/message sub-selectors). The URL path is a tinytemplate string with { number }. Loaded at runtime via -d.

Flow in main.rs: build probe list → for each probe, check the cache (Context in src/context.rs, bincode files under the platform cache dir with a 1-day TTL) → otherwise fetch() and cache → parse() into an Entry (src/entry.rs) → Display it.

Gotchas

• src/probe/{eniro,konsument_info,telefonforsaljare,vem_ringde}.rs are orphaned — probe.rs only declares mod hitta;. Those providers were superseded by the TOML definitions in definitions/. Don't "fix" them or expect them to compile; they're kept as reference.
• _build.rs is intentionally disabled (underscore prefix, not referenced in Cargo.toml) — an abandoned attempt at generating fixture tests.
• definitions/vem_ringde.yml is an experimental YAML variant of the TOML definition, but main.rs only parses TOML (toml::from_slice).
• The Filter enum in src/definition.rs has no variants yet — filters is parsed from definitions but unimplemented (commented-out loops in parse).
• insta 0.11 is old: the macro is assert_yaml_snapshot! and inline-snapshot updates need a matching old cargo-insta; it's usually easier to update the inline @r###"..."### literals by hand.