Skip to content

SPEC.md

Latest commit

 

History

History
79 lines (61 loc) · 3.06 KB

SPEC.md

File metadata and controls

79 lines (61 loc) · 3.06 KB
Raw

EarPatch MVP specification

Status: accepted for implementation on 2026-08-24.

Goal

Make Git patches independently reviewable without relying on color, side-by- side layout, or punctuation-only cues.

Users

  • Developers who use screen readers.
  • Developers with low vision or color-vision deficiency.
  • Anyone who wants a compact, deterministic diff representation for an agent, CI job, or text-only interface.

First vertical slice

Given a unified diff file, standard input, or a local Git working tree, EarPatch must parse each file and hunk once, then emit one of these views:

  • text: a screen-reader-first narrative.
  • html: a keyboard-navigable document with semantic headings and explicit line labels.
  • json: a stable machine-readable representation.

Locked decisions

  • Python 3.10+ and no runtime dependencies.
  • No network calls, telemetry, model calls, or shell invocation.
  • Git is called through an argument array with external diff helpers disabled.
  • Git mode requires explicit repository trust; patch-input mode does not load repository configuration.
  • Text is the default output.
  • Output describes evidence in the patch. It does not infer intent.
  • MIT license.

Functional requirements

  1. Parse modified, added, deleted, renamed, and binary file records.
  2. Parse omitted hunk counts, multiple hunks, and the no-newline marker.
  3. Track old and new line numbers.
  4. Group adjacent removals and additions into a change block.
  5. Report file and patch totals.
  6. Support summary, changes, and full verbosity for text.
  7. Escape all patch content in HTML.
  8. Return useful nonzero exit codes for bad input and Git failures.
  9. Preserve code locally unless the user explicitly redirects output.
  10. Make terminal and bidirectional controls visible rather than executable.
  11. Bound input size, hunk numbers, and Git run time.
  12. Refuse to overwrite output unless the user supplies --force.

Accessibility requirements

  • Do not depend on red/green color, +/- alone, or a two-column layout.
  • Start with a patch summary.
  • Announce file position, status, totals, and change-block position.
  • Announce the old and new line number for each changed line.
  • In HTML, use one main, a level-one title, level-two file headings, and level-three change headings.
  • Include a visible-on-focus skip link and strong focus styling.
  • Keep the DOM order identical to the reading order.

Acceptance tests

  • A one-file replacement is narrated as "changed", with old and new text.
  • Pure additions and removals are announced explicitly.
  • HTML contains escaped code and a valid heading hierarchy.
  • JSON totals agree with the sum of file totals.
  • A temporary Git repository can be read without invoking a shell.
  • The complete test suite passes on Python 3.12.

Later work, not MVP

  • User testing with blind developers and revisions based on that feedback.
  • Localization and customizable spoken labels.
  • Structural narration through optional tree-sitter adapters.
  • GitHub Action and editor integrations.
  • Audio earcons. These must remain optional and never replace text.