Module grammar_usage 

Persistent per-extension signature-backend telemetry (GH #690 Phase 2).

The tiering cut (“which of the ~27 static tree-sitter grammars are actually used, and how often?”) needs real usage history, but the only existing signal — signatures::signature_backend_stats() — is a pair of process-lifetime AtomicU64s with no language dimension: it resets on every restart and cannot say which grammar earned its binary bytes.

This store records, per file extension, how often the tree-sitter path vs the regex fallback produced a signature set, persisted across sessions (mirroring path_mode_memory’s store shape: load-once, atomic tmp+rename writes, periodic flush via tool_lifecycle::flush_all).

Storage: <cache_dir>/grammar_usage.json. Aggregate counters only — no paths, no file names, nothing project-identifying — so the store is safe to inspect and never a privacy concern.

Structs

ExtUsage

GrammarUsage

Functions

disk_ranked

Ranked per-extension usage, read straight from disk so a separate process (dashboard, doctor) sees what the MCP/CLI processes persisted.

flush

Flush pending counts (wired into tool_lifecycle::flush_all).

live_ranked

Ranked per-extension usage from the live in-process store (includes not-yet-flushed records) — what ctx_metrics shows.

record

Process-global: record one signature extraction for ext via the given backend. Called from the hot extract_signatures path — no I/O here; disk writes happen every FLUSH_EVERY records or on flush.