Poka parsers scorecard

Generated by scripts/scorecard.py. Do not edit by hand: python3 scripts/scorecard.py rewrites it, and python3 scripts/scorecard.py --check fails when it is stale.

Generated file. Do not edit it by hand. Run python3 scripts/scorecard.py to rewrite it; --check (pre-push) fails when this copy is stale.

The README headline counts manifests. This page says what sits behind them. It reads only committed files in this repo, so it is the same on every machine: no corpus, no network, no clock. The tier rules are in section 7, with what each tier does and does not prove.

Every row has a basis. measured: counted from files in this tree. estimated: inferred from them; the row says what from, and it is not a claim about the parsers' behaviour.

1. Format census

Counted by scripts/format-stats.py, the single source for the format count, except where a row says otherwise.

2. Depth tiers

Every manifest is in exactly one tier. Counts are measured; what a tier means is the estimate, and section 7 says how far it can be trusted.

Hex stubs split three ways: 0 in parsers/unsupported.toml, 0 other routes that run poka-hex, and 0 crates of their own whose viewer is poka-hex-viewer (measured).

Alias-only routes by the module they run (measured, top 10):

3. What the headline counts

scripts/kpi-stats.py counts every enabled manifest as supported except the unsupported.toml stubs and routes to poka-hex. That includes crates that only hex-dump a file, because they have a source file of their own. The scorecard moves those to T5.

4. Viewer usage

Enabled manifests by the viewer they name (measured). A standalone parser names none.

5. Test presence by tier

Crates under parsers/ that have each file or marker (measured). Presence is not a pass: tests/samples.rs needs the poka-samples corpus, so it runs locally (scripts/corpus-tests.py), never in CI. Alias-only routes have no crate, so they are not in this table.

Unit tests means a #[cfg(test)] module under src/. Quarantined crates are listed in build/unit-test-quarantine.txt and skipped by the unit-test gate (0 listed).

6. Never-crash lint adoption

The root Cargo.toml has no [workspace.lints.clippy] table that denies panicking constructs, and no crate sets [lints] workspace = true, so no crate is held to the never-crash rule by a lint (measured). The rule is written in docs/how-to/make-a-parser-fast.md, "Never panic", and is exercised by the robustness sweep (scripts/quality-gates.py), not enforced by clippy. This section will report adoption by tier once there is a lint table and crates opt in.

7. How the tiers are derived

First match wins, in this order: disabled, hex stub, alias-only route, standalone, metadata card, shared viewer. Everything comes from plugin.json, parsers/aliases.toml, parsers/unsupported.toml and the module a route names; no source file is parsed for meaning.

T1 Parser with a shared viewer. A plugin.json crate, not disabled, whose viewer is a shared viewer other than poka-hex-viewer and poka-metadata-card-viewer.

• Shows: The crate has its own source and emits a typed AST (tree, table, text, image, 3D, vector, workbook and so on) for a viewer poka-viewers ships.
• Does not show: How much of the format it reads. A tree of a few top-level keys and a full decoder of a binary container both land here. Depth is shown only by a corpus test (section 5) and the module's own documentation.

T2 Standalone parser. A plugin.json crate, not disabled, with no viewer. SPEC.md section 2: it writes a complete PreviewResponse itself (3D scenes, PDF, media, archives).

• Shows: The crate has its own source and renders its own result.
• Does not show: That the result is complete, or that it is not a dump in another wrapper. Nothing in the manifest says what the response holds.

T3 Metadata card. A plugin.json crate, not disabled, whose viewer is poka-metadata-card-viewer. This is the tier of the generic-container and identification shells.

• Shows: The crate reads the file far enough to fill a titled list of key and value entries.
• Does not show: That there is more than identification. A card can carry a rich header or a single magic-number line; the manifest does not tell them apart.

T4 Alias-only route. An entry in parsers/aliases.toml that is not disabled and does not run poka-hex: no crate of its own, another module's wasm under a new id, name and extension.

• Shows: A host routes the extension to a module that is a real parser of something.
• Does not show: That the module understands this specific format. The parser tutorial asks for a corpus sample to be run first; the scorecard cannot see whether it was.

T5 Hex stub (backlog). Any manifest, not disabled, that is listed in parsers/unsupported.toml, runs the retired poka-hex module, or names the retired poka-hex-viewer as its viewer. Both are gone, so this tier is a guard against hex shells coming back.

• Shows: The extension is recognised and a file opens as a hex dump.
• Does not show: Any parsing. This is the pre-support state: kpi-stats.py reports the unsupported.toml stubs as a backlog, not coverage, but counts own-crate hex shells as full parsers; the scorecard does not.

T6 Disabled. disabled: true in a crate's plugin.json, or a disabled_reason on an aliases.toml route (SPEC.md section 2).

• Shows: Nothing: the host skips registration. Kept for the id and as a record.
• Does not show: Whatever depth the source has, it is not reachable.

What no depth tier can see: whether a parser's output is correct, how much of the format it decodes, and whether a poka-hex-viewer shell hides behind another viewer's name. For how much of the format is decoded, section 8 gives the breadth tier of the formats reviewed so far; for the rest, read the crate's module documentation and its tests/samples.rs.

8. Breadth tiers

A depth tier (section 2) says what kind of parser reads a format. A breadth tier says how much of the format Poka reads. It is not derived from the manifests: a reviewer assigns it from the parser source, its tests, the corpus and the format's own documentation, and writes it into the format's entry in docs/data/format-metadata/. Only formats that have a format page can be assessed, so this section covers those and says nothing about the rest of the registry. Counts are measured from those files; what a tier means is the reviewer's judgement, and docs/explanation/breadth-tiers.md says how far it can be trusted.

379 of 379 documented formats are assessed (100.0%).

By group: one row per file in docs/data/format-metadata/, the formats it documents counted by breadth tier. A group with few formats has few format pages, not necessarily shallow parsers.