nvim-shellspec/.serena/memories/codebase_structure.md

Codebase Structure

Directory Layout

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