thor/LOAD_GRAMMARS_IDEAS.md

load_grammar Optimization Ideas

Current bottleneck

load_grammar is called once per unique language on first use. Each call costs ~30-40ms:

• dlopen — loads .so from disk (dominant)
• read_entire_file_from_path — reads .scm from disk
• query_new — compiles query
• query_cursor_new — allocates cursor (cheap)

With ~7 languages, first-load cost is ~210-280ms. Subsequent calls hit cache (~0ms).

Code-level optimizations

Avoid double-cloning query source

Currently: read_entire_file_from_path → []byte → string(raw) → strings.clone_to_cstring(query_src). Two copies of the entire .scm file.

Fix: read into a buffer with a trailing null byte, use directly as cstring. One read, zero copies.

Reuse the grammar path string

fmt.tprintf("%s/%s.so", grammar_dir, lang) is computed in ensure_parser AND again in error diagnostics (line 284). Compute once, store in Grammar_Cache.

Avoid fmt.tprintf for symbol name

"tree_sitter_" + lang can be simple concatenation instead of format string parsing.

Extract error diagnostics to a separate proc

The query error diagnostics (lines 250-300) make up more than half of load_grammar. Extract to report_query_error(lang, query_src, err_offset, err_type, query_path). Makes load_grammar focused on the happy path.

Architectural optimizations

Pre-scan content for languages, then batch-load

Before rendering, scan all markdown for language-X code blocks. Collect the unique set. Load all grammars in one pass.

Benefits:

• Makes cost visible ("loading grammars for: bash, odin, nu...")
• Enables parallel loading
• Moves cost to a predictable point in the build

Parallel grammar loading

dlopen is thread-safe (POSIX). Load N grammars on N threads simultaneously.

• Sequential: ~210ms (7 languages × ~30ms each)
• Parallel (4 cores): ~60ms
• Parallel (7 threads): ~30ms

Biggest single win for first-load time. Odin's core:thread or core:sync can manage the thread pool.

Static-link more grammars

Extend the mkGrammarStaticLib pattern (already used for HTML/CSS in flake.nix) to bash, odin, nu, etc.

• Zero dlopen — grammars baked into binary
• Zero read_entire_file_from_path — queries embedded via #load or #directory
• Zero query_new compilation — could pre-compile or use compile-time embedding
• Downside: binary size grows (~500KB per language), adding languages requires recompiling

Embed queries at compile time

Even without static-linking grammars, the .scm query files could be embedded via #load or #directory.

• Eliminates read_entire_file_from_path per language
• Smaller win than static linking but simpler
• Queries are small text files (~2-10KB each)

Cache compiled queries across runs

query_new compiles the .scm source into an internal representation. If this could be serialized and cached to disk (like a .thorcache), subsequent builds could skip compilation.

• Tree-sitter's query format isn't documented as serializable — would need investigation
• Even if not serializable, caching the raw .scm source in memory avoids re-reading from disk in watch mode (already handled by grammar_cache persistence)

Pre-link common grammars in the flake

The flake could compile grammar .so files as Nix build inputs and pass their paths to thor at runtime via the grammars config field. This doesn't eliminate dlopen but ensures the files are always available in the Nix store.

Priority ranking

1. Parallel grammar loading — immediate ~4-7x speedup on first load, no binary changes
2. Static-link common grammars — eliminates the problem entirely, but requires flake work
3. Pre-scan + batch-load — enables parallel loading and better UX logging
4. Avoid double-clone of query source — quick code cleanup, small win
5. Embed queries at compile time — eliminates file reads, moderate effort