658 lines
36 KiB
Markdown
658 lines
36 KiB
Markdown
# Tasks: Tally - Cross-Platform Calculator
|
|
|
|
## References
|
|
|
|
- #[[file:.kiro/specs/calculator/requirements.md]]
|
|
- #[[file:.kiro/specs/calculator/design.md]]
|
|
|
|
---
|
|
|
|
## Phase 1: Project Scaffolding & Engine Foundation
|
|
|
|
### Task 1.1: Initialize workspace build structure [DONE]
|
|
- Create `.mise.toml` declaring Zig version (pin to specific release)
|
|
- Create top-level `build.zig` with module declarations for engine, cli, tui
|
|
- Add Android cross-compilation targets to `build.zig` (`-Dtarget=aarch64-linux-android`, `-Dtarget=x86_64-linux-android`)
|
|
- Create `engine/build.zig` producing static lib and shared lib targets
|
|
- Create `cli/build.zig` linking engine
|
|
- Create `tui/build.zig` linking engine + libvaxis dependency
|
|
- Add `.gitignore`, `README.md` (minimal), `LICENSE`
|
|
- Verify: `mise install` provisions Zig, `zig build` compiles without errors on empty main files
|
|
|
|
NOTE: Actual structure diverged from spec - single binary at `src/main.zig`
|
|
(CLI + TUI combined), engine as static lib + shared lib. No separate cli/ or
|
|
tui/ build files. kcov-based coverage wired in via `build/Coverage.zig`.
|
|
|
|
### Task 1.2: Implement core types module [DONE]
|
|
- Create `engine/src/types.zig`
|
|
- Define `Value` union, `Integer` struct, `BitWidth`, `Signedness`, `Endianness` enums
|
|
- Define `MultiBaseResult` struct
|
|
- Define `CalcError` error set and `ErrorInfo` struct
|
|
- Define `Mode` enum (standard, programmer, financial)
|
|
- Verify: compiles, types are importable from other engine modules
|
|
|
|
### Task 1.3: Implement tokenizer [DONE]
|
|
- Create `engine/src/tokenizer.zig`
|
|
- Token types: numbers (dec, hex `0x`, oct `0o`, bin `0b`), operators, parens, identifiers, comma, semicolon, EOF
|
|
- Handle implicit multiplication detection (emit synthetic `*` token)
|
|
- Handle multi-character operators: `**`, `<<`, `>>`, `>>>`, `rol`, `ror`
|
|
- Support `_` and `,` as digit separators in number literals (e.g., `1_000_000`, `1,000,000`)
|
|
- Verify: unit tests for tokenizing expressions in all bases, edge cases (negative numbers, adjacent tokens for implicit mult)
|
|
|
|
NOTE: Implicit multiplication handled in parser rather than tokenizer.
|
|
Comma-as-separator only consumed when followed by a digit (avoids eating
|
|
function arg commas).
|
|
|
|
### Task 1.4: Implement Pratt parser [DONE]
|
|
- Create `engine/src/ast.zig` with AST node definitions
|
|
- Create `engine/src/parser.zig`
|
|
- Implement Pratt parser with precedence table from design doc
|
|
- Accept `Mode` parameter to resolve `^` ambiguity (power vs XOR)
|
|
- Handle function calls: `name(arg1, arg2, ...)`
|
|
- Handle variable assignment: `X = expr`
|
|
- Handle implicit multiplication
|
|
- Verify: unit tests parsing complex expressions, operator precedence, all bases, function calls, mode-dependent `^`
|
|
|
|
### Task 1.5: Implement standard mode evaluator [DONE]
|
|
- Create `engine/src/evaluator.zig`
|
|
- Environment struct with variables, history, config (in evaluator.zig, not separate file)
|
|
- Evaluate AST to `f64` for standard mode
|
|
- Implement built-in functions: sin, cos, tan, asin, acos, atan, log, ln, sqrt, cbrt, abs, ceil, floor, round, factorial
|
|
- Implement constants: pi, e, tau
|
|
- Implement variable storage and `Ans`
|
|
- Implement history recording
|
|
- Verify: unit tests for arithmetic, precedence, functions, variables, history recall
|
|
|
|
### Task 1.6: Implement programmer mode evaluator [DONE]
|
|
- Create `engine/src/programmer.zig`
|
|
- All operations on `Integer` (u64 storage, masked to bit_width)
|
|
- Implement bitwise operators: AND, OR, XOR, NOT, shifts, rotates
|
|
- Implement base conversion output (produce `MultiBaseResult`)
|
|
- Implement bit_pattern array generation
|
|
- Handle overflow/truncation per configured bit_width
|
|
- Signed vs unsigned interpretation
|
|
- Verify: unit tests for bitwise ops at all widths, base conversions, overflow behavior, sign extension
|
|
|
|
### Task 1.7: Implement number display formatter [DONE]
|
|
- Create `engine/src/formatter.zig`
|
|
- Define `FormattedValue` struct with `display` (human-readable) and `raw` (clipboard) strings
|
|
- Decimal formatting: comma-separated groups of 3 (`4,294,967,295`)
|
|
- Scientific notation only when value > 10^15 or < 10^-15 or > 15 significant digits
|
|
- Hex formatting: underscore per 16-bit word for value view (`0xFFFF_FFFF`), space per byte for memory view (`FF FF FF FF`)
|
|
- Binary formatting: space per nibble (`1111 1111 1111 1111`)
|
|
- Octal formatting: underscore per 3-digit group (`0o37_777_777_777`)
|
|
- All formatters produce both `display` and `raw` variants
|
|
- Respect bit width (don't show leading zeros beyond the configured width in short-form contexts)
|
|
- Verify: unit tests for all bases at all bit widths, edge cases (0, max values, negative signed values), scientific notation threshold
|
|
|
|
---
|
|
|
|
## Phase 2: Struct Layout & Financial Engines
|
|
|
|
### Task 2.0: Exact numeric model (Rational + Number union) [NOT STARTED]
|
|
Design: see design.md 2.7. Requirements: NFR-9.
|
|
|
|
Motivation (all reproducible today): `0.1 + 0.2` = `0.30000000000000004`,
|
|
`9007199254740993` silently becomes `9.007199254740992e15`, `2^53 + 1` collapses,
|
|
`12 in in ft` = `0.9999999999999998`, `factorial(171)` reports "unknown function".
|
|
|
|
Sequenced as four reviewable commits so structural churn never mixes with
|
|
behavioral change (rationale in design.md 2.7.9):
|
|
|
|
#### 2.0a: Add the types, wired to nothing [DONE]
|
|
- `engine/src/rational.zig`: `Rational` over `std.math.big.int.Managed`, always
|
|
reduced, `q > 0`. add, sub, mul, div, negate, abs, `powInt` (negative exponents
|
|
take the exact reciprocal), `sqrtExact` (null for non-perfect-squares so the
|
|
caller can fall back), order/eql, `parseDecimal` (exact: `0.1` -> `1/10`),
|
|
`isTerminating`, `denBitCount`, `toFloat`, `toFractionString`,
|
|
`toDecimalString`. 55 tests.
|
|
- `engine/src/number.zig`: `Number = union(enum) { exact: Rational, inexact: f64 }`
|
|
with the contagion rule and the `max_denominator_bits = 4096` demotion cap.
|
|
30 tests.
|
|
- Exposed via `engine.zig` (two lines) so the tests run under `zig build test`.
|
|
Nothing else is wired: the evaluator is untouched.
|
|
- Notable implementation points:
|
|
- `toFloat` scales the numerator to ~72 significant bits before dividing, so
|
|
the result is a single correct rounding rather than a quotient of two
|
|
separately-rounded floats (which would lose precision twice and overflow for
|
|
large values).
|
|
- `toDecimalString` does long division, prints terminating expansions exactly,
|
|
and rounds half-up at the digit budget while reporting `exact = false`.
|
|
- `big.int`'s `sqrt` truncates, so `sqrtExact` squares the root back and
|
|
compares to decide exactness.
|
|
- Test gotcha worth remembering: Zig folds float literals at comptime as
|
|
`comptime_float`, so `0.1 + 0.2 != 0.3` is FALSE at comptime. Comparisons meant
|
|
to demonstrate f64 error must use runtime-known values (`var x: f64 = 0.1; _ = &x;`).
|
|
- Verify: 487 tests pass (was 402), zig fmt and zlint clean, existing tests
|
|
untouched.
|
|
|
|
#### 2.0b: Evaluator internals become exact, `evalString` still returns f64
|
|
- Exact/inexact boundary per design.md 2.7.4. Per-evaluation, not per-function:
|
|
`sqrt(4)` exact, `sqrt(2)` inexact. Deliberately not a CAS.
|
|
- `NumberValue` and the AST number node GAIN an exact field rather than replacing
|
|
`float`/`int_value`, so tokenizer and parser tests keep compiling.
|
|
- ALL existing tests must still pass unchanged.
|
|
- Payoff is visible through the f64 boundary because a single final rounding
|
|
avoids today's accumulated error: `0.1 + 0.2` -> `0.3`, `1.1 + 2.2` -> `3.3`,
|
|
`0.1 * 3` -> `0.3`, `12 in in ft` -> `1`.
|
|
- Verify: existing suite green, plus new tests for the four fixes above.
|
|
|
|
#### 2.0c: `evalString` and the display path move to `Number`
|
|
- Mechanical signature churn through evaluator/formatter/CLI/TUI tests. This is
|
|
the commit where `main.zig`'s output assertions get reviewed.
|
|
- Lift the limits this removes: `formatter.is_integer`'s `< 2^53` gate and
|
|
`evaluator.factorial`'s `x > 170` rejection (also the source of the misleading
|
|
"unknown function" error).
|
|
- Rewrite `tokenizer` test "parseNumber huge decimal falls back to float", whose
|
|
premise becomes false once big integers are exact.
|
|
- Verify: existing suite green after signature updates, no expected-value changes
|
|
beyond the three items above.
|
|
|
|
#### 2.0d: Exactness tests only the `Number` API can express
|
|
- `9007199254740993` round-trips (currently unguarded, and the one bug the f64
|
|
boundary cannot fix), `2^53 + 1`, `1/3` retained exactly, `(1/3) * 3` = 1,
|
|
unbounded `factorial`, contagion, demotion at the denominator cap.
|
|
|
|
Out of scope: arbitrary-precision transcendentals (the inexact tier is `f64`
|
|
because that is the precision we can justify; see design.md 2.7.8 for why f128 is
|
|
NOT the upgrade path), and any change to programmer mode's `u128` semantics or the
|
|
IEEE 754 float view.
|
|
|
|
### Task 2.1: Implement struct DSL tokenizer and parser
|
|
- Create `engine/src/struct_layout.zig`
|
|
- Tokenize: `struct`, `{`, `}`, `;`, type names, identifiers, `[`, `]`, numbers (for arrays)
|
|
- Parse into a list of `FieldDef` structs: `{ name, type, array_count? }`
|
|
- Support types: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64, bool, ptr
|
|
- Verify: unit tests parsing valid structs, error messages for malformed input
|
|
|
|
### Task 2.2: Implement ABI profile interface and x86-64 System V profile
|
|
- Define `AbiProfile` struct with function pointers/vtable (field_layout, struct_alignment, tail_padding, pointer_size)
|
|
- Implement `x86_64_sysv` profile:
|
|
- u8/i8/bool -> size 1, align 1
|
|
- u16/i16 -> size 2, align 2
|
|
- u32/i32/f32 -> size 4, align 4
|
|
- u64/i64/f64/ptr -> size 8, align 8
|
|
- Struct alignment = max of field alignments
|
|
- Tail padding to struct alignment boundary
|
|
- Implement `packed` profile (all alignment = 1, no padding)
|
|
- Verify: unit tests matching `pahole` output for known structs
|
|
|
|
### Task 2.3: Implement layout computation
|
|
- Implement `compute_layout(fields, abi) -> StructLayoutResult`
|
|
- Generate per-field: offset, size, alignment, padding_before
|
|
- Generate byte-level map (`[]ByteInfo`) for visualization
|
|
- Compute totals: size, alignment, total padding bytes, padding percentage
|
|
- Compute "packed comparison" size
|
|
- Verify: unit tests with structs of varying complexity, compare against known C compiler layouts
|
|
|
|
### Task 2.4: Implement endianness display
|
|
- Given a `StructLayoutResult` and a set of field values (optional), show byte ordering
|
|
- Little-endian (default): LSB at lowest address
|
|
- Big-endian: MSB at lowest address
|
|
- This affects the byte-map visualization labels, not the layout computation itself
|
|
- Verify: unit test showing a u32 value's bytes in both endiannesses
|
|
|
|
### Task 2.5: Implement financial module
|
|
- Create `engine/src/financial.zig`
|
|
- Implement CAGR: `(end/start)^(1/n) - 1`
|
|
- Implement compound interest (future value): `PV * (1 + r/m)^(m*t)`
|
|
- Implement present value: `FV / (1 + r/m)^(m*t)`
|
|
- Implement TVM solver:
|
|
- Closed-form for FV, PV, PMT, N
|
|
- Newton-Raphson for I/Y (rate) with convergence check, max 1000 iterations, tolerance 1e-10
|
|
- Return step-by-step formula string alongside numeric result
|
|
- Verify: unit tests against known financial calculation results (textbook examples)
|
|
|
|
### Task 2.6: Implement unit conversion engine [DONE]
|
|
- Created `engine/src/units.zig`
|
|
- `UnitCategory` enum (12 categories) with `label()` and `baseUnit()`
|
|
- `UnitDef` struct (name, aliases, category, to_base_factor, to_base_offset) with
|
|
`toBase()`, `fromBase()`, `isLinear()`
|
|
- Conversion tables for all 12 categories: length, mass, temperature, time,
|
|
digital storage, speed, area, volume, energy, pressure, data rate, angle
|
|
- `convert(value, from_name, to_name) -> ConvertResult` and
|
|
`convertUnits(value, from, to) -> f64`
|
|
- Temperature is the only affine category (F/K/R need offsets); base is Celsius
|
|
- `findUnit`: exact case-sensitive match first, case-insensitive fallback, so
|
|
`K`/`B`/`kB` keep their meaning while `KM` and `Celsius` still resolve
|
|
- `parseRequest`: recognizes free-form `<value> <unit> to <unit>` text so
|
|
conversion is plain expression input, not a special command (see Task 4.4).
|
|
Returns null with no `to` keyword so callers fall through to normal evaluation.
|
|
- DESIGN CHANGE from the original spec: only the to-base mapping is stored and
|
|
the inverse is derived in `fromBase()`, instead of storing a second
|
|
factor/offset pair. One source of truth per unit means a table entry cannot
|
|
disagree with its own reverse (see design.md 4.1)
|
|
- 100 unit tests: known-answer conversions per category, temperature offsets and
|
|
the -40 crossover, alias resolution, error paths, request parsing (glued
|
|
values, expression values, longest-suffix and token-boundary rules), plus
|
|
invariant tests (every unit round-trips, every within-category pair
|
|
round-trips, base units are identity, names unique, no zero factors)
|
|
- Verify: `zig build test` passes; CLI spot-checks match reference values
|
|
(5280 ft/mi, 1024 MiB/GiB, 14.6959 psi/atm, 1 c = 1079252848.8 km/h)
|
|
|
|
---
|
|
|
|
## Phase 3: Engine Public API & C ABI
|
|
|
|
### Task 3.1: Implement engine public API
|
|
- Create `engine/src/engine.zig`
|
|
- `pub fn evaluate(env: *Environment, input: []const u8) !Value`
|
|
- `pub fn computeStructLayout(definition: []const u8, abi: AbiProfile, endian: Endianness) !StructLayoutResult`
|
|
- `pub fn computeCagr(start: f64, end: f64, periods: f64) !f64`
|
|
- `pub fn solveTvm(params: TvmParams) !TvmResult`
|
|
- `pub fn convert(value: f64, from_unit: []const u8, to_unit: []const u8) !ConvertResult`
|
|
- `pub fn formatMultiBase(integer: Integer) MultiBaseResult`
|
|
- Verify: integration tests exercising the full pipeline (string in -> result out)
|
|
|
|
### Task 3.2: Implement C API
|
|
- Create `engine/src/c_api.zig`
|
|
- Define `CalcString` (ptr + len) and `CalcResult` (json ptr/len + error ptr/len) extern structs
|
|
- `export fn tally_eval(expr_ptr, expr_len, mode, config_ptr, config_len) CalcResult`
|
|
- `export fn tally_struct_layout(def_ptr, def_len, abi_ptr, abi_len, endian) CalcResult`
|
|
- `export fn tally_convert(value, from_ptr, from_len, to_ptr, to_len) CalcResult`
|
|
- `export fn tally_result_free(result) void`
|
|
- `export fn tally_version(out_len) [*]const u8`
|
|
- **No null-terminated strings** - all inputs are (ptr, len) pairs
|
|
- JSON serialization for all result types
|
|
- Input length validation (reject > max expression length)
|
|
- Verify: build shared library, write a C test program that calls the API with known inputs and validates JSON output
|
|
|
|
### Task 3.3: Cross-compilation verification
|
|
- Verify `zig build` produces binaries for:
|
|
- `x86_64-linux-gnu`
|
|
- `aarch64-linux-gnu`
|
|
- `x86_64-macos`
|
|
- `aarch64-macos`
|
|
- `x86_64-windows-gnu`
|
|
- Verify `zig build` produces .so for Android targets:
|
|
- `aarch64-linux-android`
|
|
- `x86_64-linux-android`
|
|
- All targets invocable from the same `build.zig` via `-Dtarget=<triple>`
|
|
- Verify mise-provisioned Zig handles all targets without additional toolchain installs
|
|
- Document any target-specific issues or workarounds needed
|
|
|
|
---
|
|
|
|
## Phase 4: CLI Frontend
|
|
|
|
### Task 4.1: Implement CLI argument parsing [DONE]
|
|
- Single binary at `src/main.zig` (not separate cli/)
|
|
- Parse args: positional expression (multi-arg joined with spaces), `-p`/`--programmer`, `--help`, `--version`
|
|
- Subcommand `convert` IMPLEMENTED: `tally convert <value> <from> [to] <to>`,
|
|
including the glued form `tally convert 100km to mi` (numeric prefix split from
|
|
the unit suffix, with `e`/`E` only treated as an exponent when followed by a
|
|
digit or sign so `5eV` parses as 5 eV)
|
|
- Subcommands (`struct`, `cagr`, `tvm`) NOT YET IMPLEMENTED
|
|
- Verify: unit tests for arg parsing; `--help` prints usage
|
|
|
|
NOTE: Multi-arg joining implemented (`tally 2 + 2` works same as `tally "2+2"`).
|
|
Remaining subcommands deferred until their engine modules exist.
|
|
|
|
### Task 4.2: Implement CLI output formatting [DONE]
|
|
- Standard mode: print result with comma formatting
|
|
- Programmer mode: print multi-base table (dec signed, dec unsigned, hex, bin)
|
|
- Convert: `formatConversion` prints `100 km = 62.13711922373339 mi`, resolving
|
|
aliases to canonical names
|
|
- Struct mode: NOT YET IMPLEMENTED
|
|
- Financial mode: NOT YET IMPLEMENTED
|
|
- `--json` flag: NOT YET IMPLEMENTED
|
|
- Verify: unit tests for evaluate and formatConversion output
|
|
|
|
### Task 4.3: CLI integration and error handling [DONE]
|
|
- Wire arg parser -> engine calls -> output formatter
|
|
- Map `CalcError` to user-friendly stderr messages
|
|
- Set exit codes: 0 success, 1 error
|
|
- Verify: unit tests for error paths
|
|
|
|
|
|
### Task 4.4: Bare-expression unit conversion [DONE]
|
|
- `tally 32F in C` and `tally 100 km to mi` work without any subcommand; the
|
|
`convert` subcommand remains as an explicit alias for scripting
|
|
- Both `to` and `in` act as separators
|
|
- Implemented in the engine (`units.parseRequest`) rather than the CLI, so the TUI
|
|
standard mode gets the same behavior: typing `100 km to mi` at the prompt
|
|
converts and records it in history
|
|
- Value may be a full expression (`2*3 kg to lb`), evaluated by the normal
|
|
evaluator before conversion
|
|
- `in` doubles as the name for inches, so candidate separators are tried
|
|
last-to-first and the first valid reading wins: `5 in in cm`, `100 mm in in`,
|
|
`1 in in in`, and `60 min in h` all resolve correctly
|
|
- Detection is conservative: only a standalone whitespace-delimited separator
|
|
triggers it, unit suffixes must start at a token boundary, and no separator
|
|
means normal evaluation. Verified no regression on `2 + 3 * 4`, `sqrt(144)`,
|
|
`e`, `min(3, 7)`, `sin(0)`, `0o777 - 0x0f`
|
|
- 30 request-parsing tests plus 7 CLI-level tests
|
|
- Verify: bare conversions, expression values, inch ambiguity, error paths, and
|
|
unchanged behavior for ordinary expressions all confirmed by running the binary
|
|
|
|
---
|
|
|
|
## Phase 5: TUI Frontend
|
|
|
|
### Task 5.1: Set up TUI skeleton [DONE]
|
|
- Single binary at `src/main.zig` + `src/tui.zig` (not separate tui/)
|
|
- libvaxis vxfw.App with custom Widget (eventHandler + drawFn)
|
|
- No args launches TUI; with args runs CLI
|
|
- Molokai color theme
|
|
- Verify: TUI launches, responds to Ctrl-C (quit)
|
|
|
|
### Task 5.2: Implement standard mode TUI view [DONE]
|
|
- Expression input via vxfw.TextField (gap buffer)
|
|
- Result display in scrollable history panel
|
|
- History navigation with up/down arrows (saves/restores current input)
|
|
- Ctrl-L clears history
|
|
- ? shows help overlay (keybindings, functions, constants, operators)
|
|
- Variables persist across expressions (assignment + Ans)
|
|
- Verify: can type expressions, see results, browse history
|
|
|
|
### Task 5.2.1: Inline multi-base result in standard mode [DONE]
|
|
- Engine: added `evalStringInfo` returning value + `has_nondecimal_literal` flag
|
|
(walks AST via `hasNonDecimalLiteral` to detect any hex/oct/bin number literal)
|
|
- Added `BitWidth.smallestFor(value)` helper
|
|
- CLI: when flag is true and result is a non-negative integer, shows hex/oct/bin below decimal
|
|
- TUI: history entries carry optional `details` lines; drawHistory reworked to
|
|
render variable-height entries (flat line list, newest anchored at bottom)
|
|
- Uses smallest standard bit width that holds the value
|
|
- Does NOT change evaluation (still f64, `^` still power) - display only
|
|
- Fractional/negative results show decimal only
|
|
- Verify: `0o777 - 0x0f` shows 496 plus hex/oct/bin; `3.14` decimal only;
|
|
`2 + 2` decimal only; `0xFF / 2` = 127.5 decimal only
|
|
|
|
### Task 5.3: Implement programmer mode TUI view - expression & base display [PARTIAL]
|
|
- Programmer mode accessible via Tab key
|
|
- Multi-base result display (dec signed, unsigned, hex, oct, bin)
|
|
- Bit grid with navigation (arrows) and toggling (Space)
|
|
- Width toggle (Ctrl-W cycles 8->16->32->64)
|
|
- Ctrl-B toggles focus between input and bit grid
|
|
- Expression evaluation through programmer engine
|
|
- DONE: basic passive display + expression input + bit grid toggling
|
|
- NOT DONE: editable fields (see Task 5.3.1)
|
|
|
|
### Task 5.3.1: Programmer mode editable fields rework [DONE]
|
|
- Replaced `bit_grid_active: bool` with `prog_field: ProgField` enum tracking focused field
|
|
- Up/Down arrows navigate between fields (bits, dec_signed, dec_unsigned, hex, oct, bin, expression)
|
|
- When a text field is focused, the input line shows the field label as prompt (e.g. "HEX> ")
|
|
- Enter in a non-expression field parses input as that base and updates prog_value
|
|
- Bit grid: left/right navigates bits, space toggles, up/down exits to adjacent field when at grid edge
|
|
- Focused field is visually highlighted (label gets inverse color)
|
|
- Removed Ctrl-B (field navigation replaces it)
|
|
- Expression field works as before (full programmer-mode expression evaluation)
|
|
- ASCII row under HEX (read-only, xxd-style, aligned column-for-column)
|
|
- Endianness toggle (Ctrl-E): flips HEX and ASCII byte order, header shows LE/BE.
|
|
Default big-endian so HEX reads as the number (matching DEC/OCT/BIN); LE is the
|
|
opt-in x86-64 memory-layout view. DEC/OCT/BIN and the hex `raw`/clipboard form
|
|
are unaffected. Covered by formatter unit tests (BE and LE for hex and ascii).
|
|
- Verify: can arrow between fields, type hex value and see all fields update, toggle bits
|
|
|
|
### Task 5.3.2: Implement text/ASCII literal parsing [DONE]
|
|
- Added single-quote string token to the tokenizer (`'hello'`)
|
|
- Parser recognizes string literals as a new AST node type
|
|
- Programmer evaluator packs ASCII bytes into u128 value (BE packing: first char -> MSB)
|
|
- Standard evaluator also supports it (returns f64)
|
|
- Enforces max length = bit_width / 8 (Overflow error if too many chars)
|
|
- Rejects non-ASCII characters (> 0x7F)
|
|
- 128-bit width also added (u64 -> u128 throughout engine)
|
|
- Verify: `'A'` = 0x41, `'ELF'` = 0x454C46, overflow on too-long strings
|
|
|
|
### Task 5.3.3: Implement IEEE 754 float interpretation [DONE]
|
|
- Engine module `engine/src/float_interp.zig`:
|
|
- `FloatFormat` (f32/f64) with total/exponent/significand bit counts + bias
|
|
- `decompose(format, bits)` -> `FloatInfo` (sign, raw+unbiased exponent,
|
|
significand, class, value, ULP)
|
|
- Classifies normal, denormal, zero, infinity, quiet NaN, signaling NaN
|
|
- `reinterpretValue` reinterprets low bits as the float value (exact f32->f64)
|
|
- `nearestBits(format, value)` finds the closest representable pattern and
|
|
reports whether rounding occurred (detectable for f32)
|
|
- ULP computed from the exponent (2^(unbiased - significand_bits); subnormals
|
|
step by the smallest positive subnormal); NaN for inf/NaN
|
|
- 21 unit tests: 0x3F800000=1.0, special values, denormals, ULP, decimal
|
|
rounding (3.14 rounds in f32), overflow to inf, NaN handling, round trips
|
|
- TUI overlay (`src/tui/float_view.zig`, toggled with Ctrl-F in programmer mode):
|
|
- Color-coded bit grid: sign=pink, exponent=cyan, significand=green
|
|
- Shows value, classification, formula ((-1)^s x 2^e x mantissa), ULP, and
|
|
raw fields (sign, biased/unbiased exponent + bias, significand hex)
|
|
- Ctrl-W toggles f32/f64 and auto-snaps the bit width (32/64)
|
|
- Typing a decimal float (e.g. `3.14`) stores its nearest bit pattern and
|
|
notes rounding; non-float input falls back to the integer expression engine
|
|
- Auto-entry: Tab into programmer mode with a non-integer (or inf/NaN) `ans`
|
|
opens the float view on the exact f64 bit pattern; integer `ans` uses the
|
|
integer views
|
|
- Bit toggling in the grid updates the interpretation live
|
|
- Verify: `0x3F800000` shows 1.0 (f32), special values classify correctly,
|
|
`3.14` shows nearest representation with rounding note
|
|
|
|
### Task 5.4: Implement programmer mode TUI view - bit grid [DONE - merged into 5.3]
|
|
- Bit grid widget: 8 bits per group, groups separated by space
|
|
- Arrow key navigation (left/right moves cursor across bits, up/down between rows for 32/64-bit)
|
|
- Space/Enter toggles the bit under cursor
|
|
- Bit changes immediately reflected in all base displays
|
|
- Typing a value in the expression input updates the grid
|
|
- Toggling bits updates the expression/result displays
|
|
- Verify: can navigate grid, toggle bits, see values change in real-time
|
|
|
|
### Task 5.5: Implement struct visualizer TUI view
|
|
- Create `tui/src/views/struct_viz.zig`
|
|
- Text input for struct definition (multi-line mini editor or single-line with parsing)
|
|
- Live-updating field table (offset, size, align, padding)
|
|
- Memory map visualization (byte grid with color-coded fields and padding)
|
|
- ABI toggle (`a` key), endian toggle (`e` key)
|
|
- "Packed comparison" shown at bottom
|
|
- Transition: from programmer mode, press a key (e.g., `S`) to enter struct sub-view, Esc to return
|
|
- Verify: can enter struct definition, see layout update, toggle ABI/endian
|
|
|
|
### Task 5.6: Implement financial mode TUI view
|
|
- Create `tui/src/views/financial.zig`
|
|
- Form-style interface: labeled input fields for each financial function
|
|
- Sub-mode selector: CAGR, Compound Interest, TVM
|
|
- For TVM: 5 input fields, leave one empty to solve
|
|
- Result display with formula breakdown
|
|
- Verify: can input values, compute results, see formula steps
|
|
|
|
### Task 5.7: Implement unit conversion TUI view [DONE]
|
|
- Created `src/tui/convert.zig`; convert is now a third top-level mode and Tab
|
|
cycles Standard -> Programmer -> Convert
|
|
- Category chips wrap to the terminal width, selected chip highlighted
|
|
- From/To unit columns list every unit in the category with the selection marked
|
|
- Live result plus a conversion-factor line (or an "affine conversion" note for
|
|
temperature, where no single factor applies)
|
|
- Value comes from the shared input line; a bare number is used directly and
|
|
anything else is evaluated as a standard expression first (so `2*3.5` works)
|
|
- Backtick toggles input/selection zone (same convention as programmer mode);
|
|
arrows navigate columns and selections with wrapping; Ctrl-S swaps units
|
|
- Changing category resets the unit pair to that category's defaults
|
|
- Graceful degradation: if the terminal is too short, shows "... N more"
|
|
- Fully mouse-clickable (see Task 5.9)
|
|
- Verify: category switching filters units, selection updates the live result,
|
|
swap works, conversions match the CLI
|
|
|
|
### Task 5.9: TUI mouse support [DONE]
|
|
- Requirement documented as FR-7.11 (mouse is first-class, with keyboard parity
|
|
still required by FR-7.7); architecture in design.md 8.0
|
|
- `RegionSet` in `src/tui.zig`: fixed 512-entry table of `{row, col, len, action}`
|
|
rebuilt every frame during drawing, so hit targets cannot drift out of sync
|
|
with what is displayed. Newest-registered region wins, letting views layer a
|
|
row-wide fallback under finer per-digit targets.
|
|
- `Action` union covers mode tabs, programmer field focus (with optional bit
|
|
cursor), bit toggling, input focus, help dismissal, float overlay + format,
|
|
width/endian/signedness toggles, and all convert-mode selections
|
|
- Only left button press is acted on, so one click fires exactly one action
|
|
- Wired into every view: mode tabs, standard mode input, programmer mode (bit
|
|
grid, HEX/OCT digit cursor placement, BIN bit flipping, DEC row focus,
|
|
Bits/Signed/Endian labels), float view (bits, format/exit hints), convert mode
|
|
(category chips, both unit columns), and the help overlay
|
|
- Click semantics follow the data: a bit grid cell and a BIN digit are one bit so
|
|
clicking flips them; a HEX nibble or OCT digit spans several bits with no single
|
|
meaningful toggle, so clicking places the cursor for typing
|
|
- Extracted shared state helpers (`setMode`, `cycleBitWidth`, `toggleEndian`,
|
|
`toggleSignedness`, `toggleFloatFormat`, `setConvCategory`, `swapConvUnits`) so
|
|
keyboard and mouse paths cannot diverge
|
|
- `build.zig`: added a `tui_tests` target rooted at `src/tui.zig`. The CLI test
|
|
target roots at `src/main.zig`, which only reaches `tui.zig` from `main()`, and
|
|
`main()` is never analyzed in test mode, so TUI tests were being silently
|
|
skipped
|
|
- 12 unit tests for the pure logic: region hit/miss boundaries, newest-wins
|
|
layering, clear, zero-length rejection, budget exhaustion, action payloads,
|
|
`wrapIndex` wrapping/clamping, and `defaultUnitIndices` invariants
|
|
- Verify: `zig build test` runs the TUI tests (366 total); interactive clicking
|
|
needs a manual pass since the overlay is terminal-only
|
|
|
|
### Task 5.8: TUI polish and keybindings [PARTIAL]
|
|
- DONE: `?` help overlay showing keybindings, mouse actions, functions, operators
|
|
- DONE: mouse support (see Task 5.9): clicking tabs, bits, digits, config labels,
|
|
convert categories/units, and the input line
|
|
- DONE: Molokai color theme
|
|
- NOT DONE: vi-style input mode (optional: Esc for normal mode, i for insert)
|
|
- NOT DONE: mouse wheel scrolling for history
|
|
- Verify: help overlay works, mouse interactions work, looks reasonable in 80x24 terminal
|
|
|
|
---
|
|
|
|
## Phase 6: Android App
|
|
|
|
### Task 6.1: Set up Android project structure
|
|
- Create `android/` directory with Gradle project (Kotlin DSL)
|
|
- Configure for Compose, minimum SDK 26 (Android 8.0), Material 3
|
|
- Create JNI bridge class `TallyEngine.kt` with `external fun` declarations
|
|
- Set up `jniLibs/` directory structure for arm64-v8a, x86_64
|
|
- Native .so files produced by `zig build -Dtarget=aarch64-linux-android` (etc.) - Gradle does not invoke Zig, it consumes prebuilt artifacts
|
|
- Set up bottom navigation bar (Standard, Programmer, Financial, Convert)
|
|
- Verify: `zig build -Dtarget=aarch64-linux-android` produces libtally.so; Gradle project builds and empty app launches with nav bar
|
|
|
|
### Task 6.2: Implement JNI bridge
|
|
- Kotlin side: `TallyEngine.evaluate(expr, mode, config): String` (returns JSON)
|
|
- Kotlin side: `TallyEngine.structLayout(definition, abi, endian): String`
|
|
- Kotlin side: `TallyEngine.convert(value, fromUnit, toUnit): String`
|
|
- JSON deserialization into Kotlin data classes (Value, MultiBaseResult, StructLayoutResult, ConvertResult, etc.)
|
|
- Error handling: parse error JSON, surface to UI
|
|
- Verify: unit tests calling native functions with known inputs, validating deserialized results
|
|
|
|
### Task 6.3: Implement standard calculator screen
|
|
- Compose UI: expression display at top (scrollable, natural format), live result preview
|
|
- Button grid: digits, operators, functions (swipeable function row for sin/cos/log/etc.)
|
|
- History peek below expression (last 2-3 results), pull-down for full history
|
|
- ViewModel: manages expression state, calls engine, stores history
|
|
- Long-press `=` to copy result, tap history items to recall
|
|
- Verify: can perform calculations, see results, scroll history
|
|
|
|
### Task 6.4: Implement programmer mode screen
|
|
- Compose UI: segmented control for bit width (8/16/32/64)
|
|
- Value display cards: DEC, HEX, OCT, BIN, signed/unsigned (tappable to switch primary input base)
|
|
- Bit grid: custom Canvas composable, tappable cells with bit index labels, haptic on toggle
|
|
- Operator button row: AND, OR, XOR, NOT, <<, >>, ROL, ROR
|
|
- Hex digit buttons (A-F) + numeric keypad + base prefix buttons (0x, 0b)
|
|
- All displays update instantly on bit toggle or expression entry
|
|
- FAB/toolbar button navigating to struct layout sub-screen
|
|
- Verify: bit toggling works, base displays update, expressions evaluate
|
|
|
|
### Task 6.5: Implement struct visualizer screen
|
|
- Navigation: accessed from programmer mode via toolbar button
|
|
- Form-based struct builder: type dropdown + name field per row, add/remove/reorder fields
|
|
- Toggle for raw DSL text input (for power users / copy-paste from code)
|
|
- Memory map: custom Canvas composable with color-coded byte bar, tappable segments highlighting field info
|
|
- Summary card: total size, alignment, padding bytes/percentage, packed comparison
|
|
- ABI dropdown selector, endian dropdown selector
|
|
- Verify: can add fields visually, see layout update, toggle between form and raw DSL
|
|
|
|
### Task 6.6: Implement financial calculator screen
|
|
- Compose UI: scrollable chip row for function selection (CAGR, TVM, Compound Interest, Present Value)
|
|
- Card-based input form adapting to selected function
|
|
- For TVM: 5 labeled input fields, user leaves one blank to indicate solve target
|
|
- Compute button, result card with animated appearance
|
|
- Expandable formula breakdown section
|
|
- Long-press result to copy
|
|
- Verify: all financial calculations produce correct results, formula display works
|
|
|
|
### Task 6.7: Implement unit conversion screen
|
|
- Compose UI: scrollable category chip row at top
|
|
- Large editable number input (top), from-unit selector dropdown
|
|
- Swap button (animated rotation) between from/to
|
|
- Live result display (bottom), to-unit selector dropdown
|
|
- Numeric keypad (no expression input needed - just digits, decimal, sign)
|
|
- Unit selectors open searchable bottom sheets
|
|
- Conversion updates live as user types (no "calculate" button)
|
|
- Verify: live conversion works, category switching filters units, swap works
|
|
|
|
### Task 6.8: Android polish
|
|
- Material 3 theming (dynamic color on Android 12+)
|
|
- Tablet layout: two-pane (input left, results/visualization right)
|
|
- Landscape orientation: adapted layouts (wider bit grid, side-by-side panels)
|
|
- Haptic feedback on bit toggle and button presses
|
|
- Screen rotation state preservation
|
|
- App icon, splash screen
|
|
- Verify: looks correct on phone and tablet, handles rotation, haptics fire
|
|
|
|
---
|
|
|
|
## Phase 7: Testing & Release
|
|
|
|
### Task 7.1: Comprehensive engine test suite [DONE]
|
|
- **Target: >= 80% line coverage on engine code** -- ACHIEVED: 99.69% (1607/1612 lines)
|
|
- 222 unit tests passing across engine + CLI modules (208 in the engine coverage run)
|
|
- Tokenizer tests: all bases, underscores/commas/spaces separators, string literals,
|
|
invalid/unrecognized characters, bare `<`/`>`, lone dot, huge-decimal float fallback
|
|
- Parser tests: precedence/associativity, unary ops, function calls (incl. unmatched
|
|
paren in args), keyword operators, assignment, error paths, infix-position identifier
|
|
- Evaluator tests: arithmetic, precedence, functions, variables/Ans, string literals in
|
|
standard mode (ASCII packing + non-ASCII rejection), zero/two/three-arg unknown fns, rand()
|
|
- Programmer tests: bitwise/shift/rotate at all widths, two's-complement negation, ASCII
|
|
literal packing + overflow, float-literal truncation, shift-amount >= width clamping
|
|
- Formatter tests: all bases, all bit widths, scientific notation threshold boundaries
|
|
- Coverage measured via `zig build coverage` (kcov-based)
|
|
- Remaining 5 uncovered lines are unreachable defensive branches (parser `tokenToBinaryOp`/
|
|
`keywordBinaryOp` fallbacks, gated by `infixPrecedence`) and `or` short-circuits inside
|
|
test assertions -- not worth contorting the code to reach
|
|
- Verify: coverage report shows 99.69% on engine modules (well above the >= 80% gate)
|
|
|
|
### Task 7.2: Integration tests
|
|
- CLI end-to-end tests (run binary, check stdout/stderr/exit code)
|
|
- TUI smoke tests (script key sequences, verify screen output via libvaxis test mode if available)
|
|
- Android instrumented tests for JNI bridge
|
|
|
|
### Task 7.3: CI/CD setup
|
|
- Forgejo Actions workflow (at `git.lerch.org/lobo/tally`):
|
|
- Use mise to provision toolchains (same `.mise.toml` as local dev)
|
|
- Build + test on Linux, macOS, Windows
|
|
- Enforce >= 80% engine coverage (fail CI if below)
|
|
- Cross-compile all targets
|
|
- Build Android .so files
|
|
- Release workflow: produce platform binaries as Forgejo release artifacts
|
|
- Android: produce signed APK/AAB
|
|
|
|
### Task 7.4: Documentation
|
|
- `README.md`: project overview, build instructions, usage examples
|
|
- `CONTRIBUTING.md`: dev setup, architecture overview, how to add an ABI profile
|
|
- CLI `--help` text finalized
|
|
- Struct DSL syntax reference (in README or separate doc)
|
|
|
|
---
|
|
|
|
## Dependency Graph
|
|
|
|
```
|
|
Phase 1 (foundation) --> Phase 2 (struct + financial) --> Phase 3 (API)
|
|
|
|
|
+---------------+---------------+
|
|
v v v
|
|
Phase 4 (CLI) Phase 5 (TUI) Phase 6 (Android)
|
|
| | |
|
|
+---------------+---------------+
|
|
v
|
|
Phase 7 (Testing & Release)
|
|
```
|
|
|
|
Phases 4, 5, and 6 can be worked on in parallel once Phase 3 is complete.
|
|
|
|
---
|
|
|
|
## Estimated Effort
|
|
|
|
| Phase | Effort | Notes |
|
|
|-------|--------|-------|
|
|
| Phase 1 | 2-3 days | Core parsing + eval is the most algorithmic work |
|
|
| Phase 2 | 2-3 days | Struct layout, financial formulas, unit conversion tables |
|
|
| Phase 3 | 1 day | Thin wrappers + cross-compile verification |
|
|
| Phase 4 | 1 day | Straightforward CLI, most logic in engine |
|
|
| Phase 5 | 3-4 days | TUI widgets, bit grid interaction, struct viz, convert view |
|
|
| Phase 6 | 4-5 days | Android project setup, Compose UI (5 screens), JNI, polish |
|
|
| Phase 7 | 2 days | Testing infra, CI, docs |
|
|
| **Total** | **~15-19 days** | For a single developer working focused |
|