From 1f1b9c2364c53f44211a34d9d9d9558913fb65b5 Mon Sep 17 00:00:00 2001 From: "sepehr.sadri" Date: Sun, 16 Aug 2026 14:44:49 +0200 Subject: [PATCH] logic-probe: friendly labels for known census tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace raw 4-letter tags (karT, gRuA, lFuA...) with readable category names from docs/FORMATS.md's tag table. Deliberately does NOT claim the record count equals a real object count for most tags — wit-logic's census module doc measured an ~8.4x record-to-track multiplier on a real project, so that stays disclaimed pending issue #3. The one exception is audio files (lFuA/AuFl), which docs/FORMATS.md measured matching MetaData.plist exactly (35 -> 37) on the one real project checked. Reviewed via /code-review: fixed an overclaim (audio files got the same blanket disclaimer as unverified tags, losing validated signal), removed a dead gnoS mapping entry (root record count can never differ between two successfully-walked files), and added unit tests for the new tag_info() following this file's existing human_bytes() test convention. --- crates/wit-cli/src/main.rs | 96 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 92 insertions(+), 4 deletions(-) diff --git a/crates/wit-cli/src/main.rs b/crates/wit-cli/src/main.rs index 602c280..712b4a8 100644 --- a/crates/wit-cli/src/main.rs +++ b/crates/wit-cli/src/main.rs @@ -236,15 +236,72 @@ fn logic_probe(old: &std::path::Path, new: &std::path::Path) -> ExitCode { ExitCode::SUCCESS } +/// What kind of object a census tag's records cluster around, for display +/// only — plus whether the raw record count is known to line up 1:1 with a +/// real object count. Only `lFuA`/`AuFl` (audio files) has that evidence: +/// `docs/FORMATS.md` measured it matching `MetaData.plist`'s real count +/// exactly (35 -> 37). Every other tag here stays disclaimed: `wit-logic`'s +/// census module doc measured an ~8.4x record-to-track multiplier on a real +/// project (260 `karT` records against 31 actual tracks), so a tag graduates +/// to an actual object count only after issue #3's per-tag payload work, not +/// here. Deliberately excludes `gnoS` (the root/song record) — `wit-logic`'s +/// frame doc guarantees exactly one per valid file, so it can never differ +/// between two successfully-walked files and the diff branch below would +/// never fire for it. +struct TagInfo { + noun: &'static str, + verified_count: bool, +} + +fn tag_info(tag: &str) -> Option { + match tag { + "karT" => Some(TagInfo { + noun: "tracks", + verified_count: false, + }), + "gRuA" => Some(TagInfo { + noun: "regions", + verified_count: false, + }), + "lFuA" => Some(TagInfo { + noun: "audio files", + verified_count: true, + }), + "UCuA" => Some(TagInfo { + noun: "plugins", + verified_count: false, + }), + "qeSM" => Some(TagInfo { + noun: "MIDI sequences", + verified_count: false, + }), + "qSvE" => Some(TagInfo { + noun: "event sequences", + verified_count: false, + }), + _ => None, + } +} + fn print_census_diff(a: &wit_logic::Census, b: &wit_logic::Census) { let tags: BTreeSet<&String> = a.keys().chain(b.keys()).collect(); for tag in tags { let ca = a.get(tag).copied().unwrap_or(0); let cb = b.get(tag).copied().unwrap_or(0); if ca != cb { - println!( - " {tag}: {ca} -> {cb} record(s) [internal count, not a musician-facing number]" - ); + match tag_info(tag) { + Some(info) if info.verified_count => println!( + " {}: {ca} -> {cb} ({tag}) [verified against MetaData.plist on the one real project measured — see docs/FORMATS.md]", + info.noun + ), + Some(info) => println!( + " {}-related records ({tag}): {ca} -> {cb} [internal record count, does NOT equal the number of {} — record-to-object ratio isn't 1:1, see wit-logic's census module doc]", + info.noun, info.noun + ), + None => println!( + " {tag}: {ca} -> {cb} record(s) [internal count, unmapped tag — not a musician-facing number]" + ), + } } } } @@ -456,7 +513,7 @@ fn logic_report(path: &std::path::Path) -> ExitCode { #[cfg(test)] mod tests { - use super::human_bytes; + use super::{human_bytes, tag_info}; #[test] fn byte_counts_are_formatted_in_decimal_units_not_binary() { @@ -472,4 +529,35 @@ mod tests { assert_eq!(human_bytes(22_200_000_000), "22.2 GB"); assert_eq!(human_bytes(0), "0 B"); } + + #[test] + fn only_audio_files_are_marked_as_a_verified_count() { + // lFuA is the only tag docs/FORMATS.md measured matching + // MetaData.plist exactly — every other mapped tag showed a + // record-to-object multiplier and must stay disclaimed. + let audio_files = tag_info("lFuA").expect("lFuA is a mapped tag"); + assert_eq!(audio_files.noun, "audio files"); + assert!(audio_files.verified_count); + + for (tag, noun) in [ + ("karT", "tracks"), + ("gRuA", "regions"), + ("UCuA", "plugins"), + ("qeSM", "MIDI sequences"), + ("qSvE", "event sequences"), + ] { + let info = tag_info(tag).unwrap_or_else(|| panic!("{tag} should be mapped")); + assert_eq!(info.noun, noun); + assert!(!info.verified_count, "{tag} has no verified 1:1 count"); + } + } + + #[test] + fn unmapped_and_root_tags_have_no_category() { + assert!(tag_info("MneG").is_none()); + // gnoS (the root/song record) is deliberately excluded: wit-logic's + // frame doc guarantees exactly one per valid file, so its count can + // never differ between two successfully-walked files. + assert!(tag_info("gnoS").is_none()); + } }