H3 Index Audit

Build a reporting helper that inspects candidate H3 index strings and surfaces validation plus metadata grounded in the library's system totals.

Capabilities

Validate candidates

• With input ["89283082e6bffff", "not-a-cell", "119283082e6bffff"] and target resolution 9, the report returns the first value as the only valid cell (preserving order), puts the other two in invalid_tokens, groups resolutions as {9: 1}, classifies no pentagons, and keeps the original target_resolution in the output. @test

Extract cell metadata

• For every accepted cell, the report records whether the cell is a pentagon and whether its orientation is Class III, exposing both sets as pentagon_cells and class_III_cells alongside the resolution histogram. The metadata for 89283082e6bffff shows it is a Class III hexagon. @test

Base system coverage

• Using the first two resolution-0 cells returned by the dependency (one pentagon, one hexagon) with target resolution 0, the report treats both as valid, marks exactly one pentagon in pentagon_cells, includes all 122 resolution-0 cells and all 12 resolution-0 pentagons in res0_cells and res0_pentagons, and still surfaces the invalid-token bucket as empty. @test

Resolution summary

• Given cells ["85283473fffffff", "89283082e6bffff"] and target resolution 2, the report groups resolutions as {5: 1, 9: 1}, records both cells as Class III hexagons, leaves pentagon_cells empty, and sets expected_total_at_target to the dependency's total cell count at resolution 2 (5882). @test

Implementation

@generates

API

from typing import Iterable, TypedDict

class IndexReport(TypedDict):
    valid_cells: list[str]
    invalid_tokens: list[str]
    by_resolution: dict[int, int]
    pentagon_cells: list[str]
    class_III_cells: list[str]
    res0_cells: list[str]
    res0_pentagons: list[str]
    target_resolution: int
    expected_total_at_target: int

def build_index_report(candidates: Iterable[str], target_resolution: int) -> IndexReport:
    """Return validation and metadata about the provided H3 candidate indexes."""

Dependencies { .dependencies }

h3 { .dependency }

Provides cell validation helpers, metadata lookups, and system-wide totals.

@satisfied-by