diff options
| author | rottedfm <rottedfm@proton.me> | 2026-08-19 11:21:47 -0400 |
|---|---|---|
| committer | rottedfm <rottedfm@proton.me> | 2026-08-19 11:21:47 -0400 |
| commit | ea0bd36167b684c0accdb5ce2b2e21b8d84aeb25 (patch) | |
| tree | be1267972b5de2f1ae592577dfabce67f1fe6e87 /docs/requirements/hlr.md | |
| parent | 8c0b4c53b130555f040884c1f52b90f16b23e241 (diff) | |
feat: implement Helix-style modal buffer under DO-178C DAL-C
The repository was an unmodified ratatui component template: no editor
code, JSON5 config, and placeholder widgets. This establishes the first
working baseline — `moji <file>` opens a file into a ropey rope and edits
it with Helix selection-first semantics.
Requirements, implementation and tests land together because they must:
the traceability check rejects requirements with no implementation and
tests naming requirements that do not exist, so neither half is a valid
commit on its own.
Package renamed to mojibake-editor (mojibake was taken on crates.io);
binary is moji, library target stays mojibake.
Class: New behaviour
Requirements: MJB-HLR-001..019, MJB-LLR-001..205
Derived: MJB-DR-001..007 (DR-001 resolved, six open for review)
Verified: cargo build; clippy --all-targets -D warnings clean;
cargo test 294 passing; ./scripts/check-trace.sh 98/98/98;
cargo package clean
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Diffstat (limited to 'docs/requirements/hlr.md')
| -rw-r--r-- | docs/requirements/hlr.md | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/docs/requirements/hlr.md b/docs/requirements/hlr.md new file mode 100644 index 0000000..0db3d34 --- /dev/null +++ b/docs/requirements/hlr.md @@ -0,0 +1,151 @@ +# mojibake — High-Level Requirements + +Software Level: **DAL-C** (DO-178C) +Scope: the file buffer component, its configuration, and the removal of the +template widgets. + +ID scheme: `MJB-HLR-nnn`. Low-level requirements deriving from these are in +[llr.md](llr.md); requirements the implementation needed that these did not +anticipate are in [derived.md](derived.md). Traceability is in +[../traceability/trace.md](../traceability/trace.md). + +--- + +## File loading and representation + +**MJB-HLR-001 — File load from command line** +The editor shall accept an optional file path as a positional command-line +argument and load its contents into the buffer. When no path is supplied the +editor shall present an empty buffer. When the path does not exist the editor +shall present an empty buffer associated with that path, so that a subsequent +write creates the file. + +**MJB-HLR-002 — Character encoding and byte order mark** +The editor shall detect a byte order mark on load, decode the file contents +using the detected encoding, and record both the encoding and the presence of +the BOM so that a subsequent write reproduces them. In the absence of a BOM the +editor shall decode as UTF-8. + +Where the encoding is declared by a byte order mark and is not UTF-8, byte +sequences invalid in that encoding shall be decoded to replacement characters +and shall not terminate the editor; the declared encoding makes such a +substitution reproducible on write. + +**UTF-8 is an exception to the preceding paragraph.** Content decoded as UTF-8, +whether declared by a byte order mark or assumed in its absence, shall be +validated strictly. A file containing an invalid UTF-8 sequence shall be +**refused**, with a diagnostic identifying the offset at which validation +failed, and shall leave the file unmodified. Repairing such content would write +the repair back over the user's data on the next save. + +**MJB-HLR-003 — Line ending detection and preservation** +The editor shall detect the predominant line ending of a loaded file (LF, CRLF +or CR), record it, and reproduce that line ending on write. A file whose line +ending cannot be determined shall use the platform default. + +**MJB-HLR-004 — Rope text storage** +The editor shall hold buffer text in a rope structure indexed by byte offset, +such that insertion and deletion cost does not scale with total file size. + +## Selection and cursor + +**MJB-HLR-005 — Selection model** +The editor shall represent the cursor as a selection range with an anchor and a +head, both byte offsets into the rope. Ranges shall be half-open — inclusive of +the lower bound and exclusive of the upper bound — regardless of whether the +head precedes or follows the anchor. The visible block cursor shall occupy one +grapheme cluster inward from the head. + +## Motion + +**MJB-HLR-006 — Character and line motions** +The editor shall provide, in normal mode, motions by one grapheme cluster left +and right and by one line up and down, bound by default to `h`, `l`, `k` and +`j`. Motions shall not move outside the buffer bounds. + +**MJB-HLR-007 — Word motions select** +The editor shall provide next-word-start, previous-word-start and +next-word-end motions bound by default to `w`, `b` and `e`. Consistent with +Helix and unlike Vim, each shall leave a selection spanning the traversed text +rather than a collapsed cursor, so that a subsequent operator acts on that +selection without operator-pending state. + +**MJB-HLR-008 — Goto commands** +The editor shall provide goto commands for start of file, end of file, start of +line and end of line, bound by default to the two-key sequences `gg`, `ge`, +`gh` and `gl`. Multi-key sequences shall resolve deterministically and shall not +depend on the interval between keystrokes. + +## Modification + +**MJB-HLR-009 — Insert-mode entry** +The editor shall enter insert mode via commands that place the cursor before the +selection, after the selection, at the first character of the line, at the end +of the line, and on a newly opened line below or above the current line — bound +by default to `i`, `a`, `I`, `A`, `o` and `O`. + +**MJB-HLR-010 — Text modification** +The editor shall delete the current selection on `d` and shall delete the +current selection and enter insert mode on `c`. In insert mode the editor shall +insert typed printable characters at the cursor and shall delete the preceding +character on backspace. + +**MJB-HLR-011 — Undo and redo** +The editor shall express every buffer modification as a transaction and shall +retain the inverse of each applied transaction, such that `u` reverts the most +recent modification and `U` reapplies it. Undo when no modification remains and +redo when no reverted modification remains shall be no-ops and shall not be +errors. + +## Presentation + +**MJB-HLR-012 — Viewport pagination** +The editor shall render only those lines intersecting the visible viewport. The +work performed per frame shall be proportional to the viewport height and shall +not scale with the number of lines in the buffer. + +**MJB-HLR-013 — Scrolling and paging** +The editor shall keep the cursor within the viewport, maintaining a configurable +scroll-off margin from the top and bottom edges, clamped so that the margin +never exceeds half the viewport. The editor shall provide half-viewport paging +bound by default to `Ctrl-u` and `Ctrl-d` and full-viewport paging bound by +default to `Ctrl-b` and `Ctrl-f`; each shall move the cursor together with the +viewport. + +**MJB-HLR-019 — Single-widget presentation** +The buffer shall be the only widget the editor presents. The frame-rate counter +and the placeholder widget inherited from the application template shall be +removed, together with their registrations and configuration, leaving no +unreachable code. + +## Configuration and input + +**MJB-HLR-014 — TOML configuration** +The editor shall read its configuration from TOML. No other configuration format +shall be accepted, and no parser for another format shall remain in the +dependency graph. + +**MJB-HLR-015 — Config-driven modal keymap** +Key bindings shall be defined in configuration and scoped by editor mode, with +the bindings required by MJB-HLR-006 through MJB-HLR-013 supplied as built-in +defaults that user configuration overrides per binding. The keymap shall support +multi-key sequences, and shall support modes in which an unbound printable key +carries a default meaning rather than being discarded. + +**MJB-HLR-016 — Command mode** +The editor shall provide a command line entered with `:` supporting at minimum +write, quit, write-and-quit, force-quit and force-write, using the command names +and aliases of Helix. + +## Robustness + +**MJB-HLR-017 — File write** +The editor shall write buffer contents to the associated path on command. The +write shall preserve a symbolic link target rather than replacing the link, +shall preserve file permissions, shall refuse to write a read-only path, and +shall restore the previous contents if the write fails partway. + +**MJB-HLR-018 — Error handling** +The editor shall not terminate abnormally in response to malformed input, +malformed configuration, or a failed file operation. Such conditions shall be +reported to the user and the editor shall remain usable. |
