martino/microhx

Fork 0

Files

T

martino 957b814f6f Initial commin (phase 1 and 2)

2026-03-19 17:36:18 +01:00

11 KiB

Raw Permalink Blame History

MicroHX Development State

Last Updated: 2026-03-17
Current Phase: Phase 2 Complete
Next Phase: Phase 3 (LSP + Tree-sitter)

Project Overview

MicroHX is a modern modal text editor written in Rust with:

Kakoune/Helix-style object-verb keybindings
Lua 5.4 scripting for configuration and plugins
Three UI modes: CLI (crossterm), TUI (ratatui), GUI (egui)
Built-in LSP and Tree-sitter (Phase 3+)
Static compilation support for portability

Current Implementation Status

✅ Phase 1: Core Foundation (COMPLETE)

Feature	Status	File	Notes
Buffer management	✅	`src/buffer.rs`	Ropey-based, 1350+ lines
Cursor/Position	✅	`src/cursor.rs`	Full movement API, 1550+ lines
Modal system	✅	`src/mode.rs`	Normal/Insert/Visual + user modes, 1200+ lines
Keybindings	✅	`src/keymap.rs`	Object-verb style, 1500+ lines
Lua config	✅	`src/config.rs`	mlua-based, 1100+ lines
CLI mode	✅	`src/cli.rs`	Crossterm rendering, 900+ lines
Editor core	✅	`src/editor.rs`	Command execution, 1500+ lines
Static build	✅	`build-static.sh`	musl/zig support

✅ Phase 2: Essential Features (COMPLETE)

Feature	Status	File	Notes
Undo/Redo	✅	`src/undo.rs`	Tree-based, 650+ lines
Search/Replace	✅	`src/buffer.rs`	Forward/backward, range replace
Enhanced Status Bar	✅	`src/cli.rs`	Mode colors, position, undo depth
Line Numbers	✅	`src/cli.rs`	Absolute and relative
User-Definable Modes	✅	`src/mode.rs`	ModeRegistry class
Command Palette	✅	`src/fuzzy.rs`	Fuzzy search, 400+ lines
Visible Cursor	✅	`src/cli.rs`	Block cursor, inverse colors

⏳ Phase 3: Built-in LSP + Tree-sitter (TODO)

Tree-sitter integration
Syntax highlighting engine
LSP client (tower-lsp)
Diagnostics display
Completions popup
Goto definition/hover

⏳ Phase 4: Advanced Editing (TODO)

Multiple selections
Macros
Marks
Registers
Split windows
TUI mode (ratatui)

⏳ Phase 5: Polish & Plugins (TODO)

Plugin system
Theme system
GUI mode (egui)
Performance optimization
CI/CD with static builds

Test Status

Library Tests: ✅ 302 PASSING

test result: ok. 302 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Doc Tests: ⚠️ 13 FAILING (Minor)

Most failures are due to ropey's newline handling in examples. Core functionality is unaffected.

Files with failing doc tests:

src/buffer.rs - Line content includes newlines
src/cursor.rs - Position clamping examples
src/editor.rs - Editor API examples
src/config.rs - Lua loading examples
src/keymap.rs - Key processing examples
src/undo.rs - API examples
src/fuzzy.rs - Scoring examples
src/lib.rs - Usage examples

To fix: Update expected values in doc examples to match ropey's behavior.

Build Status

Development Build

source $HOME/.cargo/env
cd /home/martino/Projects/microhx
cargo build          # ✅ Success
cargo test --lib     # ✅ 302 tests passing

Release Build

cargo build --release
# Output: target/release/microhx
# Size: ~8-12 MB (optimized)

Static Build (Linux)

./build-static.sh
# Or manually:
cargo build --release --target x86_64-unknown-linux-musl --features cli

Feature Flags

# CLI mode (default)
cargo build --features cli

# TUI mode (ratatui)
cargo build --features tui

# GUI mode (egui)
cargo build --features gui

# Lua scripting (default)
cargo build --features lua

# Without Lua (faster compile)
cargo build --no-default-features --features cli

File Structure

microhx/
├── Cargo.toml              # Dependencies & build config
├── Cargo.lock              # Locked dependencies
├── SPECIFICATION.md        # Full specification document
├── DEVELOPMENT_STATE.md    # This file
├── README.md               # User documentation
├── build-static.sh         # Static build script
├── .cargo/
│   └── config.toml         # Cargo configuration (musl, etc.)
├── .gitignore
├── src/
│   ├── lib.rs              # Library root & re-exports
│   ├── main.rs             # CLI entry point
│   ├── main_tui.rs         # TUI entry point (stub)
│   ├── main_gui.rs         # GUI entry point (stub)
│   ├── buffer.rs           # Text buffer (ropey) + undo + search
│   ├── cursor.rs           # Position, Cursor, movement
│   ├── editor.rs           # Main editor state & commands
│   ├── mode.rs             # Modal system + ModeRegistry
│   ├── keymap.rs           # Key bindings + object-verb
│   ├── config.rs           # Lua configuration
│   ├── cli.rs              # Terminal rendering (crossterm)
│   ├── undo.rs             # Tree-based undo/redo
│   └── fuzzy.rs            # Fuzzy search + command palette
└── tests/                  # Integration tests (empty)

Key Architecture Decisions

1. Rope-Based Buffer

Library: ropey v1.6
Why: O(log n) insertions/deletions, efficient for large files
Note: Line content includes trailing newlines (ropey behavior)

2. Object-Verb Keybindings

Style: Kakoune/Helix (select then act)
Why: Selection visible before action, better for multi-cursor
Example: w selects word, d deletes selection

3. Tree-Based Undo

Structure: UndoTree with branching support
Why: Supports undo + new change = new branch (like Vim)
Implementation: Nodes with parent/children relationships

4. Lua Scripting

Library: mlua v0.10 with Lua 5.4
Feature: Optional (--features lua)
Why: Familiar to Neovim users, sandboxed

5. Three UI Modes

CLI: Crossterm (default, minimal deps)
TUI: Ratatui (full terminal UI)
GUI: Egui (native window)
Why: Same core, different rendering backends

6. Static Compilation

Targets: musl-libc, zig
Why: Portability, old Linux/glibc compatibility
Script: build-static.sh

Known Issues & Technical Debt

High Priority

Doc tests failing - 13 tests need example updates
Undo tree edge cases - Single-action redo behavior
Cursor positioning - Allow position after last char (fixed)

Medium Priority

TUI mode - Stub implementation only
GUI mode - Stub implementation only
LSP integration - Not started

Low Priority

Performance - No benchmarks yet
Memory usage - Not optimized for very large files
Plugin API - Basic structure only

Dependencies

Core

ropey = "1.6"           # Text buffer
thiserror = "2.0"       # Error handling
anyhow = "1.0"          # Error handling
tokio = "1.42"          # Async runtime

Scripting

mlua = { version = "0.10", features = ["lua54", "send", "vendored", "serialize"] }

UI

crossterm = "0.28"      # CLI (default)
ratatui = "0.29"        # TUI (optional)
eframe = "0.30"         # GUI (optional)
egui = "0.30"           # GUI (optional)

Serialization

serde = "1.0"           # Serialization
serde_json = "1.0"      # JSON
toml = "0.8"            # TOML

Utilities

unicode-segmentation = "1.12"
unicode-width = "0.2"
dirs = "5.0"
tracing = "0.1"

Development Guidelines

Code Style

Follow existing patterns in each module
Add /// doc comments for public APIs
Include examples in doc comments
Write unit tests for new functions

Testing

# Run all library tests
cargo test --lib

# Run specific module tests
cargo test buffer
cargo test undo

# Run with output
cargo test -- --nocapture

# Run doc tests
cargo test --doc

Building

# Debug build (fast)
cargo build

# Release build (optimized)
cargo build --release

# Static build (portable)
./build-static.sh

# Check without building
cargo check

# Format code
cargo fmt

# Lint
cargo clippy -- -D warnings

Adding New Features

Create module in src/
Add to src/lib.rs
Write tests in module
Update SPECIFICATION.md if needed
Update DEVELOPMENT_STATE.md

Next Steps (Phase 3)

1. Tree-sitter Integration

// Planned API
pub struct SyntaxHighlighter {
    parser: Parser,
    tree: Option<Tree>,
    highlights: Vec<HighlightRange>,
}

Tasks:

Add tree-sitter and tree-sitter-* crates
Create src/syntax/ module
Implement incremental parsing
Add theme-based highlighting

2. LSP Client

// Planned API
pub struct LspClient {
    server: LanguageServer,
    capabilities: ServerCapabilities,
    diagnostics: Vec<Diagnostic>,
}