test: property-check display-width clustering and parseKey totality - #598

Summary

• Adds a fast-check property suite for the layer beneath test: property-check table formatter alignment under unicode content #595: lib/ui/display-width.ts (the ui-02 column-measurement implementation with grapheme clustering) and lib/ui/ansi.ts's parseKey (raw stdin bytes → key action, which must be total).

What Changed

New test/property/display-width.property.test.ts (6 properties):

display-width — generated over an adversarial alphabet that includes every cluster mechanic the implementation special-cases (ZWJ, variation selector-16, combining keycap, combining accents, skin-tone modifiers, regional indicators, CJK, emoji):

1. Totality and bounds — displayWidth returns a non-negative integer bounded by two columns per code point, for any combination including pathological joiner/modifier soup.
2. Plain-alphabet oracle — with no joiners/modifiers present, width equals the per-character sum and concatenation is exactly additive — the standing assumption the table formatter's geometry rests on (deliberately not asserted for the adversarial alphabet, where VS-16 promotion makes concatenation legitimately non-additive).
3. Truncation contract — truncateToWidth returns a prefix whose reported width is displayWidth of the kept text (self-consistency between the two exports), never exceeds the budget, stops early only when the remaining gap is 0–1 columns (clusters max out at 2, so a 2-column gap proves the next cluster would have fit), and is idempotent.
4. Budget monotonicity — widening the budget only ever extends the kept prefix.

parseKey:

5. Totality — arbitrary byte buffers always produce a member of the KeyAction union; no input throws.
6. Table fidelity — all 16 recognized ANSI sequences map to their documented actions, and every other generated string maps to null.

No SUT bugs found.

Validation

• npm test -- test/property/display-width.property.test.ts test/display-width.test.ts test/ansi.test.ts — 25/25 (new 6 + existing suites untouched)
• npm run typecheck (also via pre-commit hook)
• npx eslint test/property/display-width.property.test.ts --max-warnings=0

Docs and Governance Checklist

• Test-only; no behavior or docs surface changed

Risk and Rollback

• Risk level: minimal — additive test file; conventions match the existing test/property/ suites.
• Rollback plan: revert the single commit.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

adds six fast-check property tests for lib/ui/display-width.ts and lib/ui/ansi.ts#parseKey. the suite covers totality/bounds over an adversarial grapheme-cluster alphabet, a plain-text additive-width oracle, truncation self-consistency / maximality / idempotence, budget monotonicity with an embedded cluster-granularity guard, and parseKey totality + known-sequence table fidelity. no SUT bugs were found during the review.

• display-width properties (4): adversarial alphabet exercises every cluster mechanic (ZWJ, VS-16, keycap, skin-tone, regional indicators, CJK, emoji); the monotonicity property doubles as a ≤2-column-per-cluster enforcement check via the step.width - narrow.width ≤ 2 assertion.
• parseKey properties (2): totality test uses fc.uint8Array → Buffer to probe raw bytes; table-fidelity test covers all 16 recognized ANSI escape sequences and asserts unknown strings map to null.
• risk: test-only, purely additive; no production code paths are changed.

Confidence Score: 5/5

purely additive test file with no changes to production code — safe to merge

the change is a single new test file exercising well-understood pure functions with no side effects; the properties are logically sound, the adversarial alphabet covers all cluster mechanics the SUT special-cases, and there are no changes to library code, configuration, or any auth/token path

no files require special attention

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[arbAdversarialText\nfc.array of grapheme cluster atoms] --> P1[Property 1\ndisplayWidth totality + bounds]
    B[arbPlainText\nfc.array of plain chars] --> P2[Property 2\nplain-text width oracle]
    A --> P3[Property 3\ntruncation self-consistency\nmaximality · idempotence]
    A --> P4[Property 4\nmonotonicity + cluster-granularity\nstep.width − narrow.width ≤ 2]

    C[fc.uint8Array maxLength 12] --> P5[Property 5\nparseKey totality\nKEY_ACTIONS.includes result]
    D[16 literal ANSI sequences] --> P6a[Table fidelity\nknown sequences → correct action]
    E[fc.string maxLength 6\nfiltered by pre] --> P6b[Unrecognized → null]

    P6a --> SUT2[parseKey\nBuffer → KeyAction]
    P6b --> SUT2
    P5 --> SUT2

    P1 --> SUT1[displayWidth\nstring → number]
    P2 --> SUT1
    P3 --> SUT3[truncateToWidth\nstring × budget → text × width]
    P4 --> SUT3

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[arbAdversarialText\nfc.array of grapheme cluster atoms] --> P1[Property 1\ndisplayWidth totality + bounds]
    B[arbPlainText\nfc.array of plain chars] --> P2[Property 2\nplain-text width oracle]
    A --> P3[Property 3\ntruncation self-consistency\nmaximality · idempotence]
    A --> P4[Property 4\nmonotonicity + cluster-granularity\nstep.width − narrow.width ≤ 2]

    C[fc.uint8Array maxLength 12] --> P5[Property 5\nparseKey totality\nKEY_ACTIONS.includes result]
    D[16 literal ANSI sequences] --> P6a[Table fidelity\nknown sequences → correct action]
    E[fc.string maxLength 6\nfiltered by pre] --> P6b[Unrecognized → null]

    P6a --> SUT2[parseKey\nBuffer → KeyAction]
    P6b --> SUT2
    P5 --> SUT2

    P1 --> SUT1[displayWidth\nstring → number]
    P2 --> SUT1
    P3 --> SUT3[truncateToWidth\nstring × budget → text × width]
    P4 --> SUT3

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
test/property/display-width.property.test.ts:57-66
**`KEY_ACTIONS` not exhaustiveness-checked against the union type**

`KEY_ACTIONS: readonly KeyAction[]` is a widened annotation — TypeScript doesn't require it to contain every member of `KeyAction`. if a new variant (e.g. `"left"`) is added to the union and `parseKey` begins returning it, the totality test fails at runtime with a confusing "false is not true" message rather than a compile-time error. annotating the constant with a pattern that enforces exhaustion (e.g. typing it as a `readonly [KeyAction, ...KeyAction[]]` and using a mapped-type helper, or simply adding a compile-time `satisfies` tuple) would surface the gap the moment the type grows.

_{Reviews (3): Last reviewed commit: "Merge branch 'main' into claude/audit-79..." | Re-trigger Greptile}