tree-sitter-shellspec/.serena/memories/real_world_shellspec_patterns.md

Real-World ShellSpec Patterns Analysis

Based on analysis of 24 official ShellSpec example files from test/spec/, this document captures the comprehensive patterns discovered and how they've been integrated into the grammar.

Key Findings from Official Examples

1. Hook Statement Patterns

Discovery: ShellSpec uses both block-style hooks (with End) and statement-style hooks (without End)

Statement-style hooks (newly supported):

• Before 'setup' - Single function call
• Before 'setup1' 'setup2' - Multiple function calls
• After 'cleanup' - Cleanup functions
• Before 'value=10' - Inline code execution

Grammar Implementation: Added shellspec_hook_statement rule to handle Before/After statements without End blocks.

2. Directive Patterns

Discovery: ShellSpec has several directive-style statements that don't follow the typical block structure

Include directive:

• Include ./lib.sh - Include external scripts
• Include ./support/custom_matcher.sh

Conditional Skip:

• Skip if "reason" condition - Skip with conditions
• Skip if 'function returns "skip"' [ "$(conditions)" = "skip" ] - Complex conditions

Grammar Implementation: Added shellspec_directive_statement rule for Include and conditional Skip patterns.

3. Data Block Complexity (Future Enhancement)

Discovery: Data blocks have sophisticated syntax not yet fully supported:

• Data:raw and Data:expand modifiers for variable expansion control
• Data | filter syntax for piping data through filters
• #|content line prefix syntax for multi-line data
• Function-based data: Data function_name
• String-based data: Data 'string content'

Current Status: Basic Data blocks work as utility blocks, but advanced syntax requires future enhancement.

4. Top-Level Examples

Discovery: ShellSpec allows It/Example/Specify blocks at the top level without requiring Describe/Context wrapping.

Pattern:

It 'is simple'
  When call echo 'ok'
  The output should eq 'ok'
End

Grammar Implementation: Already supported through existing shellspec_it_block rule.

5. Complex Nesting and Context Switching

Discovery: Real-world examples show sophisticated nesting:

• Describe > Context > It hierarchies
• Mixed hook scoping (hooks defined at different nesting levels)
• Before/After hooks with multiple arguments for setup chains
• Comments and shellcheck directives intermixed

Grammar Enhancements Made

New Rules Added

1. shellspec_hook_statement - For Before/After without End
2. shellspec_directive_statement - For Include and conditional Skip
3. Enhanced conflicts array to handle new statement types

Test Coverage Added

• 63 total tests (as of 2025-12-11; originally 59, up from 53)
• New real_world_patterns.txt test file
• 6 additional tests covering hook statements, directives, and complex patterns
• 4 additional tests for Data block modifiers (added 2025-12-11)

Integration Status

✅ Fully Integrated:

• Hook statements (Before/After without End)
• Include directive
• Conditional Skip statements
• Top-level It blocks

⚠️ Partially Supported:

• Data blocks (basic functionality works, advanced syntax needs work)
• Complex conditional expressions in Skip

🔄 Future Enhancements Needed:

• Data block modifiers (:raw, :expand)
• Data block filters (| syntax)
• Data block #| line syntax
• More sophisticated conditional parsing for Skip

Real-World Usage Patterns Observed

1. Hook Chains: Multiple Before/After hooks for complex setup/teardown
2. Conditional Logic: Heavy use of conditional Skip statements
3. External Dependencies: Frequent use of Include for modular test organization
4. Mixed Context: ShellSpec blocks mixed with regular bash functions and variables
5. Assertion Patterns: Consistent use of When/The assertion syntax
6. Descriptive Strings: Heavy use of descriptive string literals for test names

Grammar Statistics

• Block types: 5 (Describe, Context, It, Hook, Utility)
• Statement types: 2 (Hook statements, Directives)
• Keywords supported: 25+ ShellSpec keywords
• Test coverage: 100% (63/63 tests passing as of 2025-12-11)
• Conflict warnings: 5 (optimized from 13, all necessary)

Recommendations for Future Development

1. Priority 1: Implement advanced Data block syntax for better real-world compatibility
2. Priority 2: Enhance conditional Skip parsing to handle complex bash expressions
3. Priority 3: Optimize conflict declarations to reduce parser warnings
4. Priority 4: Add support for ShellSpec assertion syntax (When/The statements)