mirror of
https://github.com/ivuorinen/tree-sitter-shellspec.git
synced 2026-01-26 03:34:03 +00:00
Ismo Vuorinen
59b45f8505
- Change Node.js requirement from v16 to v22+ to align with CI matrix - Update tree-sitter CLI recommendation from global install to npx usage - Matches actual devDependency configuration in package.json Addresses PR #1 review comment from CodeRabbit.
351 lines
8.6 KiB
Markdown
351 lines
8.6 KiB
Markdown
# Contributing to tree-sitter-shellspec
|
|
|
|
Thank you for your interest in contributing to tree-sitter-shellspec! This document provides guidelines and information for contributors.
|
|
|
|
## Table of Contents
|
|
|
|
- [Getting Started](#getting-started)
|
|
- [Development Setup](#development-setup)
|
|
- [Grammar Development](#grammar-development)
|
|
- [Testing](#testing)
|
|
- [Code Style](#code-style)
|
|
- [Submitting Changes](#submitting-changes)
|
|
- [Reporting Issues](#reporting-issues)
|
|
- [Areas for Contribution](#areas-for-contribution)
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- [Node.js](https://nodejs.org/) (v22 or later)
|
|
- Tree-sitter CLI (provided via devDependency) — use `npx tree-sitter <cmd>`
|
|
- [Git](https://git-scm.com/)
|
|
- Basic knowledge of [Tree-sitter grammars](https://tree-sitter.github.io/tree-sitter/creating-parsers)
|
|
- Familiarity with [ShellSpec](https://shellspec.info/) syntax
|
|
|
|
### Fork and Clone
|
|
|
|
1. Fork the repository on GitHub
|
|
2. Clone your fork locally:
|
|
|
|
```bash
|
|
git clone https://github.com/YOUR_USERNAME/tree-sitter-shellspec.git
|
|
cd tree-sitter-shellspec
|
|
```
|
|
|
|
3. Add the upstream repository:
|
|
|
|
```bash
|
|
git remote add upstream https://github.com/ivuorinen/tree-sitter-shellspec.git
|
|
```
|
|
|
|
## Development Setup
|
|
|
|
1. **Install dependencies:**
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
2. **Generate the grammar:**
|
|
|
|
```bash
|
|
npm run generate
|
|
```
|
|
|
|
3. **Run tests:**
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
4. **Build the parser:**
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Development Workflow
|
|
|
|
Use the provided npm scripts for common development tasks:
|
|
|
|
```bash
|
|
# Development loop (generate + test)
|
|
npm run dev
|
|
|
|
# Watch mode for continuous development
|
|
npm run dev:watch
|
|
|
|
# Clean and rebuild everything
|
|
npm run rebuild
|
|
|
|
# Check code style
|
|
npm run lint
|
|
npm run lint:yaml
|
|
npm run lint:markdown
|
|
```
|
|
|
|
## Grammar Development
|
|
|
|
### Understanding the Grammar Structure
|
|
|
|
The grammar in `grammar.js` extends [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) and adds ShellSpec-specific constructs:
|
|
|
|
- **Block types**: Describe, Context, It, Example, Specify
|
|
- **Hook types**: BeforeEach, AfterEach, BeforeAll, AfterAll, etc.
|
|
- **Utility blocks**: Data, Parameters, Skip, Pending, Todo
|
|
- **Statement types**: Before/After hooks, Include directive
|
|
- **Directives**: Include, conditional Skip
|
|
|
|
### Making Grammar Changes
|
|
|
|
1. **Edit `grammar.js`** with your changes
|
|
2. **Generate the parser:** `npm run generate`
|
|
3. **Test your changes:** `npm test`
|
|
4. **Add test cases** in `test/corpus/` for new functionality
|
|
5. **Update documentation** if needed
|
|
|
|
### Grammar Development Guidelines
|
|
|
|
- **Follow existing patterns** - Look at similar rules in the grammar
|
|
- **Use appropriate precedence** - Avoid conflicts with bash grammar
|
|
- **Test extensively** - Add comprehensive test cases
|
|
- **Document new syntax** - Update README.md with examples
|
|
- **Consider real-world usage** - Test with actual ShellSpec files
|
|
|
|
### Adding Test Cases
|
|
|
|
Create or update files in `test/corpus/`:
|
|
|
|
```text
|
|
================================================================================
|
|
Test Name
|
|
================================================================================
|
|
|
|
ShellSpec code here
|
|
|
|
--------------------------------------------------------------------------------
|
|
|
|
(expected_parse_tree
|
|
structure_here)
|
|
```
|
|
|
|
**Test Organization:**
|
|
|
|
- `describe_blocks.txt` - Describe block variations
|
|
- `context_blocks.txt` - Context block variations
|
|
- `it_blocks.txt` - It/Example/Specify blocks
|
|
- `hook_blocks.txt` - Hook block patterns
|
|
- `utility_blocks.txt` - Data/Parameters/Skip/etc.
|
|
- `nested_structures.txt` - Complex nested patterns
|
|
- `real_world_patterns.txt` - Patterns from official examples
|
|
|
|
## Testing
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Test specific patterns
|
|
tree-sitter test --filter "describe_blocks"
|
|
tree-sitter test --filter "real_world_patterns"
|
|
|
|
# Test with debug output
|
|
tree-sitter test --debug
|
|
```
|
|
|
|
### Test Coverage Requirements
|
|
|
|
- **All new grammar rules** must have test coverage
|
|
- **Existing tests** must continue to pass
|
|
- **Real-world examples** should be included when possible
|
|
- **Edge cases** should be tested
|
|
|
|
### Testing New Functionality
|
|
|
|
1. Add test cases before implementing
|
|
2. Run tests to see them fail
|
|
3. Implement the grammar changes
|
|
4. Run tests until they pass
|
|
5. Add additional edge case tests
|
|
|
|
## Code Style
|
|
|
|
### Grammar Style
|
|
|
|
- Use **consistent indentation** (2 spaces)
|
|
- Add **descriptive comments** for complex rules
|
|
- Use **meaningful rule names** (e.g., `shellspec_describe_block`)
|
|
- Group **related rules** together
|
|
- Follow **tree-sitter conventions**
|
|
|
|
### JavaScript Style
|
|
|
|
- Follow **Prettier** formatting
|
|
- Use **const** for immutable values
|
|
- Add **JSDoc comments** for exported functions
|
|
- Follow **Node.js best practices**
|
|
|
|
### Documentation Style
|
|
|
|
- Use **clear, concise language**
|
|
- Provide **practical examples**
|
|
- Keep **README.md** up to date
|
|
- Include **code comments** where needed
|
|
|
|
## Submitting Changes
|
|
|
|
### Before Submitting
|
|
|
|
1. **Ensure all tests pass:** `npm test`
|
|
2. **Check code style:** `npm run lint && npm run format -- --check`
|
|
3. **Update documentation** if needed
|
|
4. **Test with real ShellSpec files** when possible
|
|
5. **Run the full development cycle:** `npm run rebuild`
|
|
|
|
### Pull Request Process
|
|
|
|
1. **Create a feature branch:**
|
|
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
```
|
|
|
|
2. **Make your changes** following the guidelines above
|
|
|
|
3. **Commit with clear messages:**
|
|
|
|
```bash
|
|
git commit -m "feat: add support for Data block modifiers
|
|
|
|
- Add :raw and :expand modifier support
|
|
- Update test cases for new syntax
|
|
- Add documentation examples"
|
|
```
|
|
|
|
4. **Push to your fork:**
|
|
|
|
```bash
|
|
git push origin feature/your-feature-name
|
|
```
|
|
|
|
5. **Create a Pull Request** with:
|
|
- Clear description of changes
|
|
- References to related issues
|
|
- Test results and coverage
|
|
- Breaking change notes (if any)
|
|
|
|
### Commit Message Guidelines
|
|
|
|
Use [Conventional Commits](https://conventionalcommits.org/):
|
|
|
|
- `feat:` - New features
|
|
- `fix:` - Bug fixes
|
|
- `docs:` - Documentation changes
|
|
- `test:` - Test additions or changes
|
|
- `refactor:` - Code refactoring
|
|
- `chore:` - Maintenance tasks
|
|
|
|
## Reporting Issues
|
|
|
|
### Bug Reports
|
|
|
|
Use the [Bug Report template](.github/ISSUE_TEMPLATE/bug_report.md) and include:
|
|
|
|
- ShellSpec code that doesn't parse correctly
|
|
- Expected vs actual behavior
|
|
- Environment information
|
|
- Tree-sitter parse output (if available)
|
|
|
|
### Feature Requests
|
|
|
|
Use the [Feature Request template](.github/ISSUE_TEMPLATE/feature_request.md) and include:
|
|
|
|
- ShellSpec syntax example
|
|
- Use case description
|
|
- Current behavior
|
|
- Links to ShellSpec documentation
|
|
|
|
### Grammar Issues
|
|
|
|
Use the [Grammar Issue template](.github/ISSUE_TEMPLATE/grammar_issue.md) for:
|
|
|
|
- Parsing errors
|
|
- Grammar conflicts
|
|
- Performance problems
|
|
- Integration issues
|
|
|
|
## Areas for Contribution
|
|
|
|
### High Priority
|
|
|
|
1. **Enhanced Data block support**
|
|
- `:raw` and `:expand` modifiers
|
|
- Pipe filter syntax (`Data | command`)
|
|
- Multi-line `#|` syntax
|
|
|
|
2. **Assertion parsing**
|
|
- When/The statement structures
|
|
- Matcher syntax parsing
|
|
- Subject/predicate analysis
|
|
|
|
3. **Performance optimization**
|
|
- Reduce parser conflicts
|
|
- Optimize grammar rules
|
|
- Improve parsing speed
|
|
|
|
### Medium Priority
|
|
|
|
1. **Editor integration**
|
|
- Neovim configuration examples
|
|
- VS Code extension support
|
|
- Emacs tree-sitter integration
|
|
|
|
2. **Tooling improvements**
|
|
- Syntax highlighting themes
|
|
- Language server features
|
|
- Code formatting rules
|
|
|
|
3. **Documentation**
|
|
- Usage tutorials
|
|
- Grammar development guide
|
|
- Editor setup instructions
|
|
|
|
### Low Priority
|
|
|
|
1. **Advanced features**
|
|
- ShellSpec custom matchers
|
|
- Configuration file parsing
|
|
- Metadata extraction
|
|
|
|
## Development Resources
|
|
|
|
### Useful Links
|
|
|
|
- [Tree-sitter Documentation](https://tree-sitter.github.io/tree-sitter/)
|
|
- [ShellSpec Documentation](https://shellspec.info/)
|
|
- [tree-sitter-bash Grammar](https://github.com/tree-sitter/tree-sitter-bash)
|
|
- [Tree-sitter Playground](https://tree-sitter.github.io/tree-sitter/playground)
|
|
|
|
### Learning Resources
|
|
|
|
- [Creating Tree-sitter Parsers](https://tree-sitter.github.io/tree-sitter/creating-parsers)
|
|
- [Grammar DSL Reference](https://tree-sitter.github.io/tree-sitter/creating-parsers#the-grammar-dsl)
|
|
- [Tree-sitter Conflicts](https://tree-sitter.github.io/tree-sitter/creating-parsers#conflicts)
|
|
|
|
## Getting Help
|
|
|
|
- **GitHub Discussions**: For questions and general discussion
|
|
- **Issues**: For bugs and feature requests
|
|
- **Pull Requests**: For code review and collaboration
|
|
|
|
## License
|
|
|
|
By contributing to tree-sitter-shellspec, you agree that your contributions will be licensed under the MIT License.
|
|
|
|
---
|
|
|
|
Thank you for contributing to tree-sitter-shellspec! 🎉
|