Work Order API Reference

The headerkit.workorder module assigns every declaration in a parsed unit to a test tier and renders the generated test file and its markdown companions for a scaffolded project.

Tier 1 emits real, passing tests where the IR determines both the call and the expected result. Tiers 2 and 3 emit deliberately failing stubs for behaviour no header records. See the Test work orders guide for what each tier covers and why the exclusions are exclusions.

---

Classes

WorkOrder dataclass

WorkOrder(tier1=list(), stubs=list())

Everything the tiering pass derived from one source unit.

is_empty property

is_empty

True when there is nothing to emit for either tier.

Tier1Test dataclass

Tier1Test(name, kind, subject, description, values=(), width=None, all_distinct=False)

A test whose call and expected value are both derived from the IR.

Stub dataclass

Stub(name, symbol, signature, instruction, cases=(), enum_type=None)

A failing test standing in for behaviour no IR can describe.

tier property

tier

2 when the IR supplied the cases, 3 when it supplied nothing but the name.

---

Functions

analyze_work_order

analyze_work_order(unit)

Assign every declaration in unit to a tier.

A function reached by Tier 2 never also receives a Tier 3 stub, and records and enums never receive stubs at all, because Tier 1 tests them completely. Diluting the work order with items that are already covered is the way this feature fails: the reader stops reading it carefully.

Source code in headerkit/workorder.py

def analyze_work_order(unit: SourceUnit | Header) -> WorkOrder:
    """Assign every declaration in ``unit`` to a tier.

    A function reached by Tier 2 never also receives a Tier 3 stub, and records and
    enums never receive stubs at all, because Tier 1 tests them completely. Diluting
    the work order with items that are already covered is the way this feature fails:
    the reader stops reading it carefully.
    """
    decls = _declarations(unit)
    order = WorkOrder()

    # An enum whose name a target language cannot spell is excluded here as well as
    # from Tier 1: `_enum_param` hands this map's values to a Tier 2 stub, which emits
    # the type name verbatim as `parametrizedTest("use", ns::E)`. The Tier 1 guard
    # below does not reach that path.
    enums: dict[str, Enum] = {}
    for d in decls:
        if isinstance(d, Enum) and d.name and d.name.isidentifier():
            enums[d.name] = d

    for d in decls:
        # A Tier 1 test names its subject directly (``_bindings.Rec``, ``var obj: Rec``),
        # so a subject a target language cannot spell -- a qualified or operator name --
        # has no reference to emit. Skipping is the honest response; pasting it in
        # produces a module that does not parse, which takes the valid tests with it.
        if isinstance(d, Enum | Struct) and d.name and not d.name.isidentifier():
            continue
        if isinstance(d, Enum) and d.name:
            pairs = _enum_int_values(d)
            # `observed = {"E::A": _bindings.E::A}` is a SyntaxError. The test claims
            # *every* enumerator holds its declared value, so dropping the unspellable
            # ones would make its own description false: the whole test is skipped.
            if any(not name.isidentifier() for name, _ in pairs):
                pairs = []
            if len(pairs) >= 2:
                order.tier1.append(
                    Tier1Test(
                        name=f"test_enum_{d.name}_values",
                        kind="enum_coverage",
                        subject=d.name,
                        description=f"every enumerator of `enum {d.name}` is importable and holds its declared value",
                        values=tuple(pairs),
                        all_distinct=len({v for _, v in pairs}) == len(pairs),
                    )
                )
        elif isinstance(d, Struct) and d.name:
            if _roundtrip_fields(d):
                order.tier1.append(
                    Tier1Test(
                        name=f"test_{d.name}_field_roundtrip",
                        kind="struct_roundtrip",
                        subject=d.name,
                        description=f"every scalar field of `{d.name}` round-trips through the generated wrapper",
                        values=tuple(_roundtrip_fields(d)),
                    )
                )
            for fname, width in _bitfield_bounds(d):
                order.tier1.append(
                    Tier1Test(
                        name=f"test_{d.name}_{fname}_bitfield_bounds",
                        kind="bitfield_bounds",
                        subject=f"{d.name}.{fname}",
                        description=f"`{d.name}.{fname}` is {width} bits wide, so it holds {(1 << width) - 1} and truncates {1 << width}",
                        values=((fname, width),),
                        width=width,
                    )
                )

    functions = [d for d in decls if isinstance(d, Function) and d.name]
    by_name: dict[str, list[Function]] = {}
    for fn in functions:
        by_name.setdefault(fn.name, []).append(fn)

    for name, overloads in by_name.items():
        primary = overloads[0]
        signature = render_signature(primary)

        if len(overloads) >= 2:
            order.stubs.append(
                Stub(
                    name=f"test_{name}",
                    symbol=name,
                    signature="\n".join(render_signature(o) for o in overloads),
                    instruction=(
                        f"{WORK_ORDER_MARKER}: `{name}` is an overload set with {len(overloads)} overloads. "
                        f"Write one assertion per overload proving it resolves to the intended one. {DEFINITION_OF_DONE}"
                    ),
                    cases=tuple(f"overload_{i}" for i in range(len(overloads))),
                )
            )
            continue

        enum_case = _enum_param(primary, enums)
        if enum_case is not None:
            pname, enum = enum_case
            labels = tuple(v.name for v in enum.values)
            if labels:
                order.stubs.append(
                    Stub(
                        name=f"test_{name}",
                        symbol=name,
                        signature=signature,
                        instruction=(
                            f"{WORK_ORDER_MARKER}: call `{name}` with `{pname}` set to this enumerator and assert "
                            f"what it should do for that value. {DEFINITION_OF_DONE}"
                        ),
                        cases=labels,
                        enum_type=enum.name,
                    )
                )
                continue

        # A pointer parameter adds a NULL case; it does not replace the question of what
        # the function is FOR, which is the more valuable of the two. Emitting only the
        # NULL question would bury the real one under boilerplate, since nearly every C
        # function in a typical header takes a pointer.
        ptr = _pointer_param(primary)
        if ptr is not None:
            order.stubs.append(
                Stub(
                    name=f"test_{name}",
                    symbol=name,
                    signature=signature,
                    instruction=(
                        f"{WORK_ORDER_MARKER}: for the `behaviour` case, describe what `{name}` is for and "
                        f"assert it. For the `null_{ptr}` case, decide what it does when `{ptr}` is NULL -- "
                        f"an error, or undefined and therefore untestable? {DEFINITION_OF_DONE}"
                    ),
                    cases=("behaviour", f"null_{ptr}"),
                )
            )
            continue

        order.stubs.append(
            Stub(
                name=f"test_{name}",
                symbol=name,
                signature=signature,
                instruction=(
                    f"{WORK_ORDER_MARKER}: describe what `{name}` is for, then assert it. "
                    f"No IR can tell you this; read the header docs or the library source. {DEFINITION_OF_DONE}"
                ),
            )
        )

    return _disambiguated(order)

build_work_order_files

build_work_order_files(unit, package_name, language='python')

Build the tiered test file and its two markdown companions for a scaffolded project.

Every file returned is marked preserve_existing: these are the artifacts a human edits, and regeneration must not eat the work it asked for.

Source code in headerkit/workorder.py

def build_work_order_files(
    unit: SourceUnit | Header,
    package_name: str,
    language: str = "python",
) -> list[OutputFile]:
    """Build the tiered test file and its two markdown companions for a scaffolded project.

    Every file returned is marked ``preserve_existing``: these are the artifacts a
    human edits, and regeneration must not eat the work it asked for.
    """
    order = analyze_work_order(unit)
    if order.is_empty:
        return []

    files: list[OutputFile] = []
    if language == "nim":
        nim_suite = render_nim_tests(order, package_name)
        if nim_suite is None:
            # Nothing survives the Nim filter, so there is no suite to run and nothing
            # for the markdown to point at. An AGENTS.md telling the next session to
            # run a file that was never written is worse than no file at all.
            return []
        files.append(
            OutputFile(
                path="tests/workorder_dsl.nim",
                content=render_nim_dsl(),
                preserve_existing=True,
            )
        )
        files.append(
            OutputFile(
                path="tests/test_workorder.nim",
                content=nim_suite,
                preserve_existing=True,
            )
        )
    else:
        files.append(
            OutputFile(
                path="tests/test_workorder.py",
                content=render_python_tests(order, package_name),
                preserve_existing=True,
            )
        )

    files.append(
        OutputFile(
            path="WORK_ORDER.md",
            content=render_work_order_md(order, package_name, language),
            preserve_existing=True,
        )
    )
    files.append(
        OutputFile(
            path="SUGGESTIONS.md",
            content=render_suggestions_md(language),
            preserve_existing=True,
        )
    )
    files.append(
        OutputFile(
            path="AGENTS.md",
            content=render_agents_md(package_name, language),
            preserve_existing=True,
        )
    )
    return files

---

Constants

WORK_ORDER_MARKER opens every stub failure message, in both languages, so a reader can tell an unwritten stub from a genuine regression at a glance. DEFINITION_OF_DONE is repeated on every stub: call it and assert on the result; asserting that it does not raise is insufficient.

The rendering functions behind build_work_order_files are internal. Their output is described in the Test work orders guide.