Skip to content

livery.extensions.coverage._tasks

livery.extensions.coverage._tasks

The coverage extension's verbs, loaded through the extension's entry point.

Importing this module registers the coverage group: coverage.leg, the entry the extension adds to each check leg, and coverage.union, the judge it adds to the gate point's verdict job, both placed by the extension's extension.toml; and coverage.enforce and coverage.accept, which a person runs. The base's plugin never imports this module.

Functions:

Name Description
coverage_leg

Leave this leg's suites' parts for its write, measuring the unrecorded first.

coverage_union

Union the run's legs' parts with the records' and enforce the floors.

coverage_enforce

Enforce every package's floor on the measured data here.

coverage_accept

Lower a package's coverage mark deliberately, with the reason on the record.

Attributes:

Name Type Description
coverage_group

coverage_group module-attribute

coverage_group = group('coverage', help='The measured union and its floors')

coverage_leg

coverage_leg() -> None

Leave this leg's suites' parts for its write, measuring the unrecorded first.

The check leg's entry, after the gate and before the leg's own write, ci.leg. When the gate ran narrowed or skipped, the suites no record can supply at their current closure run first, measured. Then each suite the leg ran gets its parts in the line format, the ones its measurer left and the ones the reductions make of the run's data, and they are left, with the scope the leg measured, for the leg's write, which puts them on the leg's per-run ref beside the timing row; each suite's size prints raw and gzipped. Refuses when a leg that ran its suites left no part of any, or a reduction refuses, and when the parts could not be left, so a leg that measured is never judged as an empty union.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_tasks.py
@coverage_group.task(name="leg", hidden=True)
def coverage_leg() -> None:
    """Leave this leg's suites' parts for its write, measuring the unrecorded first.

    The check leg's entry, after the gate and before the leg's own
    write, ``ci.leg``. When the gate ran narrowed or skipped, the
    suites no record can supply at their current closure run first,
    measured. Then each suite the leg ran gets its parts in the line
    format, the ones its measurer left and the ones the reductions make
    of the run's data, and they are left, with the scope the leg
    measured, for the leg's write, which puts them on the leg's per-run
    ref beside the timing row; each suite's size prints raw and
    gzipped. Refuses when a leg that ran its suites left no part of
    any, or a reduction refuses, and when the parts could not be left,
    so a leg that measured is never judged as an empty union.
    """
    from livery.extensions.coverage._leg import gather_leg, top_up
    from livery.workshop import leg_scope

    root = _root()
    packages = discover_packages(root)
    gather_leg(root, packages, marker=top_up(root, packages, leg_scope(root)))

coverage_union

coverage_union() -> None

Union the run's legs' parts with the records' and enforce the floors.

The gate job's judge: every check leg's parts are read from its per-run ref, every suite no leg ran is carried from a record on that leg at the suite's current closure, the parts merge by the line format's rules into the union file, and the union judges every package. On main's run the record is then written back. Refuses when no leg left its parts, when a leg the run runs left no ref, when a leg that ran its gate left no parts, and when a suite neither the run nor the record can supply, so nothing passes as a smaller union; the verdicts print, so the numbers on screen are the numbers enforced. The percentages are left as the coverage section of the run's row, which the collect after it folds into the run's file.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_tasks.py
@coverage_group.task(name="union", hidden=True)
def coverage_union() -> None:
    """Union the run's legs' parts with the records' and enforce the floors.

    The gate job's judge: every check leg's parts are read from its
    per-run ref, every suite no leg ran is carried from a record on
    that leg at the suite's current closure, the parts merge by the
    line format's rules into the union file, and the union judges
    every package. On main's run the record is then written back.
    Refuses when no leg left its parts, when a leg the run runs left
    no ref, when a leg that ran its gate left no parts, and when a
    suite neither the run nor the record can supply, so nothing passes
    as a smaller union; the verdicts print,
    so the numbers on screen are the numbers enforced. The percentages
    are left as the coverage section of the run's row, which the
    collect after it folds into the run's file.
    """
    from contextlib import nullcontext

    from livery.extensions.coverage._floors import enforce_coverage
    from livery.extensions.coverage._record import record_prefixes
    from livery.extensions.coverage._union import combine_union
    from livery.git import remote_snapshot
    from livery.workshop import ci_run, leave_section, state_store

    root = _root()
    run = ci_run()
    # The legs' per-run refs and the records the union reads, the head
    # branch's and main's: one listing and one fetch. Main's run reads
    # the record of the branch the verified row names, known only once
    # that row is read; its first read brings the record, every leg of
    # it, in one more fetch (`remote_snapshot` brings a ref's whole key
    # group), so it is not missing from the prefixes here.
    scope = (
        remote_snapshot(
            state_store(root),
            fetch=(f"run/{run.run_id}/", *record_prefixes(run.head_ref)),
        )
        if run is not None
        else nullcontext()
    )
    with scope:
        judged = combine_union(root, discover_packages(root))
    if judged:
        measured = enforce_coverage(root, judged)
        rounded = {path: round(value, 2) for path, value in measured.items()}
        print(f"  {leave_section(root, 'coverage', rounded, unit='%')}")

coverage_enforce

coverage_enforce() -> None

Enforce every package's floor on the measured data here.

In the gate job, after its union, the data is the union file every leg's parts made; on a machine it is what the last measured run left. The same floors a machine's run of the tests previews, here judged on the cross-platform union.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_tasks.py
@coverage_group.task(name="enforce")
def coverage_enforce() -> None:
    """Enforce every package's floor on the measured data here.

    In the gate job, after its union, the data is the union file every
    leg's parts made; on a machine it is what the last measured run
    left. The same floors a machine's run of the tests previews, here
    judged on the cross-platform union.
    """
    from livery.extensions.coverage._floors import enforce_coverage

    root = _root()
    enforce_coverage(root, discover_packages(root))

coverage_accept

coverage_accept(package: Annotated[str, doc('the package path, as packages/forge')], value: Annotated[float, doc('the new mark, in percent')], reason: Annotated[str, doc('why the mark comes down; goes on the record')] = '') -> None

Lower a package's coverage mark deliberately, with the reason on the record.

The mark rises on its own when a run clears it; lowering it is a person's act, so this writes a dated row naming who and why, and the next gated run judges from it. Refuses without a reason, for a package not under auto-ratchet, at or above the current mark, or when the marks cannot be read.

Source code in packages/extensions/coverage/src/livery/extensions/coverage/_tasks.py
@coverage_group.task(name="accept")
def coverage_accept(
    package: Annotated[str, doc("the package path, as packages/forge")],
    value: Annotated[float, doc("the new mark, in percent")],
    reason: Annotated[str, doc("why the mark comes down; goes on the record")] = "",
) -> None:
    """Lower a package's coverage mark deliberately, with the reason on the record.

    The mark rises on its own when a run clears it; lowering it is a
    person's act, so this writes a dated row naming who and why, and
    the next gated run judges from it. Refuses without a reason, for
    a package not under auto-ratchet, at or above the current mark,
    or when the marks cannot be read.
    """
    import os

    from livery.extensions.coverage import _marks
    from livery.extensions.coverage._floors import coverage_policy
    from livery.git import config_get

    root = _root()
    if not reason.strip():
        fail(
            "a reason is required: --reason=<why the mark comes down> goes on the"
            " record beside the new mark"
        )
    packages = discover_packages(root)
    found = next((item for item in packages if item.path == package), None)
    if found is None:
        fail(
            f"no package at {package!r}; the packages are "
            + ", ".join(item.path for item in packages)
        )
    policy = coverage_policy(found)
    if policy is None or not policy.ratchet:
        fail(
            f"{package} is not under auto-ratchet: its workshop.toml sets its"
            " floor under [coverage], so change it there"
        )
    if not 0 <= value <= 100:
        fail(f"the mark is a percentage; {value!r} is not")
    current, why = _marks.marks(root)
    if current is None:
        fail(f"refusing: {why}; a write from an unread store would erase its rows")
    mark = current.get(package)
    if mark is None:
        fail(
            f"{package} has no mark yet: the next gated run records one, and"
            " there is nothing to lower"
        )
    if value >= mark.value:
        fail(
            f"{package}'s mark is {mark.value:.2f}%; {value:.2f}% does not lower"
            " it. Raising is the ratchet's own move, when a run clears the mark."
        )
    who = config_get(root, "user.name") or os.environ.get("USER", "unknown")
    written = _marks.write_mark(
        root,
        package=package,
        value=value,
        kind="accept",
        by=who,
        reason=reason.strip(),
    )
    if written:
        fail(f"the mark was not written: {written}")
    print(
        f"  coverage {package}: mark {mark.value:.2f}% -> {value:.2f}%"
        f" accepted by {who}"
    )
    print(f"    reason: {reason.strip()}")