syntax-definition

# Syntax Definition Use this skill when asked to create or update a syntax definition for a named language or file format. ## Goal Create or update exactly one grammar file in the repository top-level `syntaxes/` directory: - `syntaxes/<Language>.sublime-syntax` Also create or update one fixture/expectations pair under `tests/fixtures/syntaxes/<language>/`: - `<sample>.<ext>` - `<sample>.<ext>.tokens.yml` Examples: - `JSON` -> `syntaxes/JSON.sublime-syntax` - `TypeScript` -> `syntaxes/TypeScript.sublime-syntax` - `Elm` -> `syntaxes/Elm.sublime-syntax` - `Dockerfile` -> `syntaxes/Dockerfile.sublime-syntax` If a matching file already exists, update it instead of creating a duplicate. ## Required Constraints - Only produce Sublime Text 3 compatible grammars. - Do not use Sublime Text 4+ only syntax features. - Keep the file as YAML with the usual `.sublime-syntax` structure. - Do not write the grammar anywhere except the top-level `syntaxes/` directory unless the user explicitly asks for something else. - Keep syntax regression fixtures under `tests/fixtures/syntaxes/`. When compatibility is uncertain, prefer conservative syntax features: - `%YAML 1.2` - `name` - `file_extensions` - `scope` - `variables` - `contexts` - `match` - `captures` - `scope` - `push` - `set` - `pop` - `include` - `meta_scope` - `meta_content_scope` ## Workflow 1. Identify the requested language or format name. 2. Inspect nearby files in `syntaxes/` to match the repository's existing style and naming conventions. 3. Create a practical first-pass grammar with the core building blocks for that language: - comments - strings - numbers - keywords - operators or punctuation - identifiers 4. Add one representative sample file under `tests/fixtures/syntaxes/<language>/`. 5. Add a YAML expectations file named `<sample>.<ext>.tokens.yml` with: - `buffer_path`: the virtual filename used to select the syntax - `expectations`: an ordered list of critical `(text, scope)` checks 6. Run `cargo test syntaxes` to test and fix issues with the generated/updated syntax. ## Output guidelines ### For generated/updated syntaxes - Use a stable top-level scope such as `source.<language>` or `text.<format>` as appropriate. - Keep contexts readable and modular rather than over-optimizing the grammar. - If the language details are incomplete, make the smallest reasonable set of assumptions and state them briefly. - The resulting syntax file should be directly usable by the repository's syntax-loading code. - Prefer correctness and compatibility over advanced grammar tricks. ### For syntax fixtures - Use critical-scope expectations only; do not snapshot every token unless the user explicitly asks for exhaustive coverage. - The fixture should be directly usable by the repository's `scribe::Workspace.current_buffer_tokens()` test harness.