Metadata-Version: 2.4
Name: zlsp
Version: 1.0.0
Summary: Modern Language Server Protocol (LSP) for .zolo files with semantic highlighting, validation, and Vim integration
Author-email: Gal Nachshon <hello@zolo.ai>
Maintainer-email: Gal Nachshon <hello@zolo.ai>
License: MIT with Ethical Use Clause
Project-URL: Homepage, https://github.com/ZoloAi/ZoloMedia
Project-URL: Documentation, https://github.com/ZoloAi/ZoloMedia/tree/main/zlsp
Project-URL: Repository, https://github.com/ZoloAi/ZoloMedia
Project-URL: Bug Tracker, https://github.com/ZoloAi/ZoloMedia/issues
Keywords: zlsp,zolo,lsp,language-server,language-server-protocol,parser,semantic-highlighting,vim,neovim,declarative,configuration,syntax-highlighting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Text Editors :: Integrated Development Environments (IDE)
Classifier: Operating System :: OS Independent
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pygls>=1.3.0
Requires-Dist: lsprotocol>=2023.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: themes
Requires-Dist: pyyaml>=6.0; extra == "themes"
Provides-Extra: all
Requires-Dist: zlsp[dev,themes]; extra == "all"

# Zolo LSP

**Language Server Protocol implementation for `.zolo` declarative files**

Pure LSP architecture following the TOML model: single source of truth (parser) → LSP wrapper → thin editor clients.

## Features

- **String-First Philosophy** - Values are strings by default, with explicit type hints
- **Pure LSP** - No grammar files, parser is the source of truth
- **Terminal-First** - Perfect Vim/Neovim support (Phase 1)
- **Editor Agnostic** - Same LSP server for all editors (Vim, VS Code, IntelliJ)
- **Multi-Language Support** - Python SDK (ready), C++/Java/Rust (planned)
- **Industry-Grade Architecture** - Modular, tested, maintainable (see below!)

## Recent Improvements (January 2026)

🎉 **Major Refactoring Complete!** The codebase has been transformed to industry-grade standards:

### Phase 1-3 Achievements:
- ✅ **Parser Modularization**: Broke monolithic 2,700-line parser into 13 focused modules (364-line thin API)
  - Each module <500 lines for maintainability
  - Extracted: BlockTracker, FileTypeDetector, KeyDetector, ValueValidator
  - Removed YAML dependency - pure .zolo format!

- ✅ **Provider Modularization**: Refactored all providers (72% code reduction!)
  - hover_provider: 285 → 55 lines (-81%)
  - completion_provider: 301 → 62 lines (-79%)
  - diagnostics_engine: 234 → 114 lines (-51%)
  - Zero duplication through DocumentationRegistry (SSOT)

- ✅ **Test Coverage**: Expanded from 162 → 261 tests
  - 162 parser tests (98% coverage for key modules)
  - 99 provider tests (88-97% coverage each)
  - 63% overall coverage

- ✅ **Architecture**: Thin wrapper pattern throughout
  - Single Source of Truth (SSOT) for documentation
  - Context-aware completions
  - Modular diagnostic formatting

**Result**: Clean, maintainable, industry-grade codebase ready for expansion!

## Project Structure

```
zlsp/
├── core/          # Language-agnostic LSP implementation
│   ├── server/    # LSP protocol, semantic tokens
│   ├── parser/    # Zolo parser (single source of truth)
│   └── providers/ # Completion, hover, diagnostics
│
├── bindings/      # Language-specific SDKs
│   └── python/    # Python SDK ✅ (ready)
│       └── zlsp/  # pip install zlsp
│
├── editors/       # Editor integrations
│   └── vim/       # Vim integration ✅ (ready)
│
└── Documentation/ # All documentation
    ├── bindings/  # Per-language guides
    └── editors/   # Per-editor guides
```

**Design:** Each folder (`core/`, `bindings/python/`, `editors/vim/`) can be extracted to its own repository when ready for publication. The monorepo structure makes development easier!

## Quick Start

### Installation (One Command!)

**From PyPI (Production):**

```bash
# Install and setup - that's it!
pip install zlsp && zolo-vim-install
```

**From GitHub (Development):**

```bash
# Install from monorepo
pip install git+https://github.com/ZoloAi/Zolo.git#subdirectory=zLSP && zolo-vim-install
```

**Local Development:**

```bash
cd zlsp
pip install -e . && zolo-vim-install
```

### What Gets Installed (Automatically)

The `zolo-vim-install` command:
1. ✅ Installs Vim plugin files to `~/.vim/` or `~/.config/nvim/`
2. ✅ **Detects Vim version** and auto-installs vim-lsp if needed (Vim 9+)
3. ✅ **Sets up vim-plug** and configures your `~/.vimrc` (with backup)
4. ✅ Verifies `zolo-lsp` server is available

**No manual steps required!** Just run and use.

### Vim/Neovim Support

**Neovim 0.8+:** Built-in LSP - works automatically!
```bash
nvim test.zolo  # Just works! 🎉
```

**Vim 9+:** Auto-configured with vim-lsp during installation
```bash
vim test.zolo  # LSP enabled automatically! 🎉
```

**Vim 8 or older:** Basic syntax highlighting (no LSP)
```bash
vim test.zolo  # Basic colors only
# Recommendation: Upgrade to Vim 9+ or use Neovim
```

See [`zlsp/vim/README.md`](zlsp/vim/README.md) for troubleshooting and advanced setup.

## String-First Philosophy

Zolo's core innovation: **values are strings by default**, with explicit type hints for conversion.

```zolo
# String (default)
name: Zolo
description: A declarative config format

# Explicit type conversion
version(float): 1.0
port(int): 8080
enabled(bool): true
timeout(float): 30.5

# Force string (even if looks like number)
id(str): 12345
code(str): 007

# Null values
empty(null):
```

**Why String-First?**
- **No ambiguity** - YAML's `yes` = `true` problem doesn't exist
- **Explicit > Implicit** - Clear intent, no surprises
- **Easy to understand** - What you see is what you get

## Architecture

```
┌─────────────────────┐
│   parser.py         │  ← Single source of truth
│   (String-first)    │     • tokenize() → semantic tokens
└──────────┬──────────┘     • load/loads() → parse data
           │                • dump/dumps() → write data
           ↓
┌─────────────────────┐
│   lsp_server.py     │  ← Thin wrapper
│   (LSP Protocol)    │     Provides ALL features:
└──────────┬──────────┘     • Semantic highlighting
           │                • Diagnostics
           │                • Completion
           ↓                • Hover
    ┌──────┴──────┐
    ↓             ↓
┌────────┐    ┌────────┐
│  Vim   │    │ VS Code│  ← Thin LSP clients
│  LSP   │    │ (Phase │    (No grammar files!)
└────────┘    └───2)───┘
```

**No grammar files.** The parser provides semantic tokens directly to the LSP, which editors consume.

See [`ARCHITECTURE.md`](ARCHITECTURE.md) for detailed design docs.

## LSP Features

All features come from the LSP (no grammar files):

### ✅ Semantic Highlighting
- Keys, values, comments colored by parser
- Context-aware (zUI, zConfig, zEnv files)
- Type hints highlighted

### ✅ Diagnostics
- Syntax errors (duplicate keys, invalid YAML)
- Type mismatches (e.g., `port(int): abc`)
- Real-time error reporting

### ✅ Hover Information
- Type hint documentation
- Value type detection
- Key descriptions

### ✅ Code Completion
- Type hints: `(int)`, `(float)`, `(bool)`, etc.
- Common values: `true`, `false`, `null`
- Context-aware suggestions

## Usage

### As a Parser

```python
from zolo import load, loads, dump, dumps

# Load from file
data = load('config.zolo')

# Load from string
data = loads('''
name: Zolo
version(float): 1.0
enabled(bool): true
''')
# → {'name': 'Zolo', 'version': 1.0, 'enabled': True}

# Dump to file
dump(data, 'output.zolo')

# Dump to string
text = dumps(data)
```

### As an LSP Server

The `zolo-lsp` command starts the LSP server:

```bash
zolo-lsp
```

Editors connect to it automatically when you open a `.zolo` file.

## File Structure

```
zLSP/
├── src/zolo/
│   ├── parser.py              ← THE BRAIN (2,700+ lines)
│   ├── lsp_server.py          ← LSP wrapper (~350 lines)
│   ├── semantic_tokenizer.py  ← Token encoding
│   ├── lsp_types.py           ← Type definitions
│   ├── type_hints.py          ← String-first type system
│   ├── constants.py           ← Shared constants
│   ├── exceptions.py          ← Error types
│   ├── providers/             ← LSP feature providers
│   └── vim/                   ← Vim integration (Phase 1)
├── tests/                     ← Unit tests
├── examples/                  ← Example .zolo files
├── docs/                      ← Documentation
└── README.md                  ← This file
```

## Comparison to Other Languages

Zolo follows the same architecture as modern language servers:

| Language | Parser | LSP Server | Pattern |
|----------|--------|------------|---------|
| **TOML** | `toml` crate (Rust) | `taplo-lsp` | ✅ Same as Zolo |
| **Rust** | `rustc` parser | `rust-analyzer` | ✅ Same as Zolo |
| **YAML** | `yaml` (JS) | `yaml-language-server` | ✅ Same as Zolo |
| **Zolo** | `parser.py` | `zolo-lsp` | ✅ Pure LSP |

**We're in good company!**

## Roadmap

### ✅ Phase 1: Terminal-First (DONE)
- [x] Parser with string-first logic
- [x] LSP server wrapping parser
- [x] Vim LSP client configuration
- [x] Installation script
- [x] Documentation

### 🔜 Phase 2: VS Code (Future)
- [ ] VS Code extension (thin LSP client)
- [ ] Marketplace publishing
- [ ] Same LSP server, different client

### 🔜 Phase 3: Other Editors (Future)
- [ ] IntelliJ plugin
- [ ] Sublime Text
- [ ] Emacs

### 🔜 Phase 4: Advanced Features (Future)
- [ ] Go-to-definition
- [ ] Find references
- [ ] Rename refactoring
- [ ] Code actions

## Testing

```bash
# Run unit tests
pytest tests/

# Test parser
python3 -c "from zolo import loads; print(loads('key: value'))"

# Test LSP server
zolo-lsp --help

# Test in Vim
cd src/zolo/vim
./install.sh
nvim test.zolo
```

## Requirements

- **Python 3.8+**
- **pygls 1.3.0+** (LSP framework)
- **pyyaml 6.0+** (YAML compatibility)

For Vim:
- **Neovim 0.8+** (built-in LSP) OR
- **Vim 9+** with [vim-lsp](https://github.com/prabirshrestha/vim-lsp) plugin

## Documentation

- [`ARCHITECTURE.md`](ARCHITECTURE.md) - Detailed design docs
- [`src/zolo/vim/README.md`](src/zolo/vim/README.md) - Vim setup guide
- [`examples/`](examples/) - Example .zolo files

## Contributing

**Core principle:** Keep `parser.py` as the single source of truth.

- New syntax? → Add to `parser.py`
- New highlighting? → Update `tokenize()` in `parser.py`
- New LSP feature? → Add provider that calls `parser.py`

**Never:** Duplicate parsing logic in grammar files or LSP server.

## License

MIT License - See [LICENSE](LICENSE) for details.

## Credits

Inspired by:
- [taplo](https://github.com/tamasfe/taplo) - TOML LSP
- [rust-analyzer](https://github.com/rust-lang/rust-analyzer) - Rust LSP
- [yaml-language-server](https://github.com/redhat-developer/yaml-language-server) - YAML LSP

Built with:
- [pygls](https://github.com/openlawlibrary/pygls) - Python LSP framework
- [PyYAML](https://pyyaml.org/) - YAML parser
