aboutsummaryrefslogtreecommitdiff
path: root/docs/requirements/hlr.md
diff options
context:
space:
mode:
authorrottedfm <rottedfm@proton.me>2026-08-19 11:21:47 -0400
committerrottedfm <rottedfm@proton.me>2026-08-19 11:21:47 -0400
commitea0bd36167b684c0accdb5ce2b2e21b8d84aeb25 (patch)
treebe1267972b5de2f1ae592577dfabce67f1fe6e87 /docs/requirements/hlr.md
parent8c0b4c53b130555f040884c1f52b90f16b23e241 (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.md151
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.