add-shellspec-rule

name	add-shellspec-rule
description	Add a new ShellSpec grammar rule with tests, following project conventions

Add ShellSpec Rule

Follow these steps to add a new ShellSpec construct to the grammar:

Arguments

• rule_name (required): Name of the ShellSpec construct (e.g., "Tag", "Filter")
• type (required): One of block (needs End terminator), statement (single-line), directive (% prefixed)

Steps

1. Research the construct in ShellSpec documentation. Understand its syntax, variants, and where it appears in real spec files.

2. Add the rule to grammar.js:

   • Prefix the rule name with shellspec_ (e.g., shellspec_tag_statement)
   • For blocks: use prec.right() with seq(keyword, ..., repeat($._terminated_statement), "End")
   • For statements: use seq(keyword, ...args)
   • For directives: use seq("%" + name, ...args)
   • Use field() for named parts (e.g., field("description", ...))

3. Register in _statement_not_subshell: Add the new rule to the choice array in _statement_not_subshell.

4. Create corpus tests in the appropriate test/corpus/*.txt file:

   • Include basic usage, all variants, and edge cases
   • Follow the corpus format: === header, code, --- separator, S-expression AST
   • Aim for 3-5 test cases minimum

5. Update queries/highlights.scm: Add highlighting patterns for any new keywords.

6. Verify:

   • Run npm run generate — check for new conflicts (minimize them)
   • Run npm test — all tests must pass
   • Run spec file check: for f in test/spec/*.sh; do tree-sitter parse "$f" 2>&1 | grep -c ERROR; done

7. Update documentation:

   • Update the rule list in CLAUDE.md
   • Update the ShellSpec Language Support section in README.md

Grammar Gotchas (from CLAUDE.md)

• Don't use compound keyword tokens (e.g., "Data:raw") — they force tokenizer behavior globally
• prec(N) on simple alternatives can beat prec.right(M) on blocks at the initial ambiguity point
• [ ... ] is $.test_command in tree-sitter-bash, not literal bracket tokens