Skip to content

cache.md

Latest commit

 

History

History
94 lines (67 loc) · 3.43 KB

cache.md

File metadata and controls

94 lines (67 loc) · 3.43 KB

Cache Semantics

TSDL caches parser builds in <build-dir>/cache.toml. The cache is a build reuse decision, not only a list of produced files. A cache entry is reused only when the parser source, build inputs, and expected artifacts still match the current request.

Cache Entries

Each grammar is cached independently under a language/grammar key. For example, the JSON parser is cached as json/json, while a repository with multiple grammars can produce keys such as typescript/typescript and typescript/tsx.

Each entry records:

  • the grammar.js content hash;
  • the parser repository URL;
  • the requested parser git ref;
  • the parser source cache identity;
  • the resolved tree-sitter CLI release tag, platform, and repository;
  • the build script, output prefix, and target;
  • the expected build artifacts on disk.

If any of these values no longer match, the grammar is rebuilt.

Parser Git Refs

Parser refs are first interpreted from the user definition in parsers.toml or from the default unpinned build behavior.

Stable parser refs are cached by the requested ref only:

  • full 40-character commit SHAs;
  • dotted versions such as 0.21.0, normalized to v0.21.0;
  • v plus dotted versions such as v0.21.0;
  • explicit tag refs under refs/tags/....

Moving parser refs are cached by both the requested ref and the checked-out commit:

  • HEAD;
  • branches such as master, main, or dev;
  • explicit branch refs under refs/heads/...;
  • other unqualified names such as release, stable, or vnext.

The requested ref always remains part of the cache identity. If main and stable point to the same commit, they are still different cache identities.

Moving Ref Behavior

Moving refs are resolved before cache lookup. TSDL checks out the requested ref, reads the resulting HEAD commit, and compares that commit with the cached commit for the same requested ref.

This means:

  • if a branch or HEAD has not moved, the cache can be reused;
  • if a branch or HEAD has moved, the affected grammars are rebuilt;
  • if the requested ref changes, the cache misses even when both refs currently point to the same commit.

Tag-like parser refs are not remotely resolved for cache purposes. A tag ref is treated as stable by name. If a remote tag is moved, TSDL does not detect that movement from the cache alone; use --force or --fresh when you need to force a rebuild.

Tree-Sitter CLI Identity

The tree-sitter CLI version is resolved to the actual release tag that exists in the configured tree-sitter repository. The cache records that resolved release tag rather than the raw input string.

For example, if both 0.26.5 and v0.26.5 resolve to the same release tag, the parser cache treats them as the same tree-sitter CLI identity.

Changing the tree-sitter CLI release tag, platform, or repository invalidates the affected parser cache entries.

Cache Format

The parser source identity is intentionally small. Stable refs store only that they are stable because the requested ref is already part of the build spec. Moving refs additionally store the checked-out commit.

Older cache files from previous major versions are not migrated; rebuild after upgrading when needed.

Manual Controls

Use --force to ignore cache reuse for the current build. Use --fresh to clear the build directory before building. These options override normal cache reuse and are useful when remote state was intentionally changed outside the semantics above.