mirror of
https://github.com/ivuorinen/nvim-shellspec.git
synced 2026-01-26 11:34:04 +00:00
Ismo Vuorinen
ce620cd035
- Add modern Lua implementation with modular architecture - Implement HEREDOC preservation and smart comment indentation - Create dual implementation (Neovim Lua + VimScript fallback) - Add comprehensive health check and configuration system - Enhance formatting engine with state machine for context awareness - Update documentation with Lua configuration examples - Add memory files for development workflow and conventions
139 lines
4.7 KiB
Markdown
139 lines
4.7 KiB
Markdown
# Codebase Structure
|
|
|
|
## Directory Layout
|
|
|
|
```text
|
|
nvim-shellspec/
|
|
├── lua/shellspec/ # Modern Neovim Lua implementation
|
|
│ ├── init.lua # Main module entry point & setup
|
|
│ ├── config.lua # Configuration management
|
|
│ ├── format.lua # Enhanced formatting engine
|
|
│ ├── autocmds.lua # Neovim-native autocommands
|
|
│ └── health.lua # Health check support
|
|
├── autoload/ # Plugin functions (VimScript)
|
|
│ └── shellspec.vim # Enhanced formatting with HEREDOC support
|
|
├── bin/ # Standalone executables
|
|
│ └── shellspec-format # Bash formatter script
|
|
├── ftdetect/ # Filetype detection
|
|
│ └── shellspec.vim # Auto-detect ShellSpec files
|
|
├── indent/ # Indentation rules
|
|
│ └── shellspec.vim # Smart indentation for ShellSpec DSL
|
|
├── plugin/ # Main plugin file (loaded at startup)
|
|
│ └── shellspec.vim # Neovim detection & dual implementation
|
|
├── syntax/ # Syntax highlighting
|
|
│ └── shellspec.vim # ShellSpec DSL syntax rules
|
|
└── .github/ # GitHub workflows and templates
|
|
```
|
|
|
|
## Core Files
|
|
|
|
### Lua Implementation (Neovim 0.7+)
|
|
|
|
#### lua/shellspec/init.lua
|
|
|
|
- Main module entry point with setup() function
|
|
- Lua configuration interface
|
|
- Health check integration (:checkhealth support)
|
|
- Backward compatibility functions for VimScript
|
|
|
|
#### lua/shellspec/config.lua
|
|
|
|
- Configuration management with defaults
|
|
- Validation and type checking
|
|
- Support for:
|
|
- Auto-format settings
|
|
- Indentation preferences
|
|
- HEREDOC pattern customization
|
|
- Comment indentation options
|
|
|
|
#### lua/shellspec/format.lua
|
|
|
|
- Advanced formatting engine with state machine
|
|
- HEREDOC detection and preservation
|
|
- Smart comment indentation
|
|
- Context-aware formatting (normal, in-heredoc states)
|
|
- Async formatting capabilities
|
|
|
|
#### lua/shellspec/autocmds.lua
|
|
|
|
- Neovim-native autocommands using vim.api
|
|
- Buffer-local settings and commands
|
|
- Enhanced filetype detection patterns
|
|
- Auto-format on save integration
|
|
|
|
#### lua/shellspec/health.lua
|
|
|
|
- Comprehensive health checks for :checkhealth
|
|
- Configuration validation
|
|
- Module loading verification
|
|
- Project ShellSpec file detection
|
|
|
|
### VimScript Implementation (Compatibility)
|
|
|
|
#### plugin/shellspec.vim
|
|
|
|
- **Dual Implementation Logic**: Detects Neovim 0.7+ and loads appropriate implementation
|
|
- **Neovim Path**: Loads Lua modules and creates command delegators
|
|
- **Vim Path**: Falls back to enhanced VimScript implementation
|
|
- Maintains all existing functionality
|
|
|
|
#### autoload/shellspec.vim
|
|
|
|
- **Enhanced VimScript formatter** with same features as Lua version
|
|
- HEREDOC detection patterns and state machine
|
|
- Smart comment indentation logic
|
|
- Backward compatibility with older Vim versions
|
|
|
|
### Traditional Vim Plugin Structure
|
|
|
|
#### ftdetect/shellspec.vim
|
|
|
|
- Automatic filetype detection for ShellSpec files
|
|
- Patterns: `*_spec.sh`, `*.spec.sh`, `spec/*.sh`, `test/*.sh`
|
|
- Enhanced with nested spec directory support
|
|
|
|
#### indent/shellspec.vim
|
|
|
|
- Smart indentation based on ShellSpec block structure
|
|
- Handles `Describe`, `Context`, `It` blocks and their variants
|
|
- Special handling for `End` keyword and `Data`/`Parameters` blocks
|
|
|
|
#### syntax/shellspec.vim
|
|
|
|
- Complete syntax highlighting for ShellSpec DSL
|
|
- Keywords: Block structures, control flow, evaluation, expectations, hooks
|
|
- Supports nested shell code regions
|
|
- Proper highlighting for strings, variables, comments
|
|
|
|
## Configuration Files
|
|
|
|
### Development & Quality
|
|
|
|
- `.pre-commit-config.yaml` - Pre-commit hooks configuration
|
|
- `.mega-linter.yml` - MegaLinter configuration
|
|
- `.yamllint.yml` - YAML linting rules
|
|
- `.markdownlint.json` - Markdown linting rules
|
|
- `.editorconfig` - Editor configuration
|
|
|
|
### Git & CI/CD
|
|
|
|
- `.github/workflows/` - GitHub Actions for CI
|
|
- `.gitignore` - Git ignore patterns
|
|
|
|
## ShellSpec DSL Keywords Supported
|
|
|
|
- **Blocks**: Describe, Context, ExampleGroup, It, Specify, Example
|
|
- **Prefixed blocks**: xDescribe, fDescribe (skip/focus variants)
|
|
- **Hooks**: BeforeEach, AfterEach, BeforeAll, AfterAll
|
|
- **Evaluation**: When, call, run, command, script, source
|
|
- **Expectations**: The, Assert, should, output, stdout, error, stderr
|
|
- **Helpers**: Dump, Include, Set, Path, File, Dir, Data, Parameters
|
|
|
|
## Architecture Benefits
|
|
|
|
- **Performance**: Lua implementation for better performance in Neovim
|
|
- **Modern APIs**: Uses Neovim's native autocmd and formatting APIs
|
|
- **Maintainability**: Modular structure with clear separation of concerns
|
|
- **Extensibility**: Easy to add new features through Lua configuration
|
|
- **Compatibility**: Seamless fallback ensures broad editor support
|