ruohki
af0fe03f12
- Add 02-01-SUMMARY.md with full execution record and deviation documentation - Update STATE.md: Phase 2 Plan 1 complete, resume at 02-02-PLAN.md - Update REQUIREMENTS.md: mark REND-03, REND-10, NAV-06, NAV-07 complete
94 lines
4.5 KiB
Markdown
94 lines
4.5 KiB
Markdown
---
|
|
phase: 02-vault-core-and-rendering
|
|
plan: 01
|
|
subsystem: vault-and-highlighter
|
|
tags: [cargo, dependencies, file-io, syntax-highlighting, cga-colors]
|
|
dependency_graph:
|
|
requires: []
|
|
provides: [vault-file-loading, syntect-initialization, cga-color-mapping, highlight-code]
|
|
affects: [02-02-renderer, 02-03-app-integration]
|
|
tech_stack:
|
|
added:
|
|
- pulldown-cmark 0.13.1
|
|
- syntect 5.3 (default-fancy, pure-Rust engine)
|
|
- syntect-tui 3.0
|
|
patterns:
|
|
- OnceLock for one-time syntect initialization
|
|
- Euclidean RGB-to-CGA quantization
|
|
- Owned String Spans for Vec<Line<'static>> output
|
|
key_files:
|
|
created:
|
|
- Cargo.toml (modified - 3 new deps added)
|
|
- src/vault.rs
|
|
- src/highlighter.rs
|
|
modified: []
|
|
decisions:
|
|
- "Used LinesWithNewlines iterator to preserve trailing \\n for syntect grammar correctness"
|
|
- "Removed mod declarations from main.rs after compile verification - Plan 03 handles wiring"
|
|
- "syntect-tui pulled onig_sys via transitive dep but cargo check succeeds cleanly"
|
|
metrics:
|
|
duration_seconds: 102
|
|
completed: 2026-02-28
|
|
tasks_completed: 2
|
|
files_changed: 3
|
|
---
|
|
|
|
# Phase 02 Plan 01: Vault Core and Highlighter Summary
|
|
|
|
**One-liner:** pulldown-cmark/syntect/syntect-tui dependencies added with VaultDocument file-loading enum and OnceLock-based CGA-mapped syntax highlighter.
|
|
|
|
## What Was Built
|
|
|
|
### Task 1: Dependencies and vault file-loading module
|
|
Added three new dependencies to `Cargo.toml`:
|
|
- `pulldown-cmark = "0.13.1"` — markdown event parser
|
|
- `syntect = { version = "5.3", default-features = false, features = ["default-fancy"] }` — syntax highlighting with pure-Rust regex engine
|
|
- `syntect-tui = "3.0"` — bridge between syntect and ratatui
|
|
|
|
Created `src/vault.rs` with:
|
|
- `VaultDocument` enum: `Loaded { path, content }`, `Missing { path }`, `ReadError { path, reason }`
|
|
- `load_document(vault_path: &Path, relative: &str) -> VaultDocument` using `std::fs::read_to_string` with proper `ErrorKind::NotFound` discrimination
|
|
|
|
### Task 2: Syntax highlighter module with CGA color mapping
|
|
Created `src/highlighter.rs` with:
|
|
- `static SYNTAX_SET: OnceLock<SyntaxSet>` and `static THEME_SET: OnceLock<ThemeSet>` for one-time initialization
|
|
- `init_highlighter()` — call once before `App::new()`
|
|
- `syntax_set()` and `theme_set()` accessor functions with expect panics on uninitialized state
|
|
- `syntect_color_to_cga(c: Color) -> ratatui::style::Color` — Euclidean distance RGB-to-CGA 16-color quantization across the full classic CGA palette
|
|
- `highlight_code(code: &str, lang: &str) -> Vec<Line<'static>>` — full pipeline: syntax lookup by token/name/fallback, `base16-ocean.dark` theme, per-line `HighlightLines::highlight_line()`, CGA color mapping, owned String Spans
|
|
- `LinesWithNewlines` private iterator that preserves trailing `\n` per line for correct syntect grammar matching
|
|
|
|
## Verification
|
|
|
|
1. `cargo build` succeeds with all new dependencies (53 packages locked)
|
|
2. `src/vault.rs` contains `VaultDocument` enum with `Loaded`, `Missing`, `ReadError` variants
|
|
3. `src/vault.rs` contains `load_document()` function using `std::fs::read_to_string`
|
|
4. `src/highlighter.rs` contains `init_highlighter()`, `highlight_code()`, `syntect_color_to_cga()`
|
|
5. No changes to existing Phase 1 files (app.rs, main.rs, config.rs, signals.rs, terminal.rs)
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 2 - Missing Critical Functionality] Added LinesWithNewlines iterator**
|
|
- **Found during:** Task 2
|
|
- **Issue:** syntect's `highlight_line()` expects lines to include their trailing `\n` terminator so language grammars can match end-of-line anchors. Using `str::lines()` strips newlines, causing grammar state machine errors in some syntect definitions.
|
|
- **Fix:** Added a private `LinesWithNewlines` iterator that yields substrings including the `\n` terminator, with correct handling for the final line without a trailing newline.
|
|
- **Files modified:** src/highlighter.rs
|
|
- **Commit:** 8d45a7c
|
|
|
|
## Commits
|
|
|
|
| Hash | Task | Description |
|
|
|------|------|-------------|
|
|
| 7622d41 | Task 1 | feat(02-01): add Phase 2 deps and vault file-loading module |
|
|
| 8d45a7c | Task 2 | feat(02-01): add syntax highlighter module with CGA color mapping |
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- [x] src/vault.rs exists and contains VaultDocument, load_document
|
|
- [x] src/highlighter.rs exists and contains init_highlighter, syntect_color_to_cga, highlight_code
|
|
- [x] Cargo.toml contains pulldown-cmark, syntect, syntect-tui
|
|
- [x] Commits 7622d41 and 8d45a7c exist in git log
|
|
- [x] cargo build succeeds
|