KeysetFit

Prove a real keycap kit covers a real keyboard layout.

KeysetFit is an offline command-line tool that assigns each physical keycap in a declared inventory to each physical key in a Keyboard Layout Editor (KLE) layout. It maximizes coverage, reports the exact reason for every gap, and writes reviewable JSON, CSV, and standalone HTML evidence.

简体中文 · Inventory schema · Architecture · Research

Why it exists

A product page saying “supports 65% keyboards” is not proof that a kit contains the right 1.75u Shift, two 1.25u Alt caps, the correct sculpted rows, or an ISO Enter. Preset checkers also cannot describe a one-off keyboard or a mixed box of spare caps.

KeysetFit takes the two things you actually have:

• an arbitrary KLE raw JSON layout;
• a finite JSON inventory where each string is one physical cap.

It then performs deterministic maximum-cardinality matching across size, secondary shape, stepped state, homing state, sculpted row, legend, and quantity.

Quick start

Download the archive for your operating system from Releases, or build with Rust 1.85 or newer:

cargo build --locked --release

Validate both inputs without writing reports:

keysetfit validate --layout examples/ansi-68.kle.json --keyset examples/ansi-68-full.keyset.json

Check coverage and write all three artifacts:

keysetfit check --layout examples/ansi-68.kle.json --keyset examples/ansi-68-full.keyset.json --out build/full

Expected output:

complete: matched 68/68; reports: build/full

The intentionally incomplete fixture is a useful failure-path demo:

keysetfit check --layout examples/ansi-68.kle.json --keyset examples/ansi-68-incomplete.keyset.json --out build/incomplete

It exits with code 3 after writing reports for the 65 matched keys and three missing keys.

Inventory in 30 seconds

{
  "schema_version": 1,
  "name": "Small uniform kit",
  "profile": "DSA",
  "sculpted": false,
  "groups": [
    {
      "id": "alpha",
      "caps": ["A", "B", "C", "*"]
    },
    {
      "id": "space",
      "caps": ["Space"],
      "width": 6.25
    }
  ]
}

Each item in caps is one physical cap, so duplicates express quantity. * is an explicit legend wildcard. An empty string represents a blank cap and matches only an unlabeled key. See the schema reference for compound shapes, homing keys, stepped keys, and sculpted rows.

Reports

Covered and incomplete checks both create exactly:

• coverage.json — stable assignments and reason-coded gaps;
• placement.csv — one row per layout key; formula-like cells are quoted and prefixed as text;
• report.html — a script-free keyboard map that can be opened locally.

KLE and inventory strings are treated as untrusted input. HTML/SVG is escaped, spreadsheet-formula prefixes are neutralized in CSV, and exact source strings remain available in JSON. The tool never uploads a layout, contacts a vendor, or adds telemetry.

Exit codes

Code	Meaning
0	Inputs are valid and every physical key is covered
1	A report could not be created or written
2	CLI usage or input data is invalid
3	Inputs are valid, reports were written, but coverage is incomplete

What it does not claim

KeysetFit proves coverage only against the geometry, traits, legends, and inventory you declare. It does not verify switch stems, stabilizers, manufacturer tolerances, color, material, interference, or product-page accuracy.

Development and repair

Run the same acceptance gate used by CI:

./scripts/check.ps1

./scripts/check.sh

If the gate fails, start with the first failed command; the scripts stop immediately and preserve its output. Common repairs:

• formatting: run cargo fmt, then rerun the gate;
• lint or test: fix the reported source/test failure; do not suppress the gate;
• missing Rust component: run rustup component add rustfmt clippy;
• Windows link.exe missing: install Visual Studio Build Tools, or install the GNU target with rustup target add x86_64-pc-windows-gnu; the PowerShell gate automatically uses a working installed target;
• example mismatch: run the failing keysetfit check command shown above and inspect coverage.json.

See CONTRIBUTING.md for the change workflow, docs/releasing.md for release and failure repair, and SECURITY.md for private vulnerability reporting.

License

MIT