Prune

def apply_prune(
    report: PruneReport,
    data_root: str | Path | None = None,
    *,
    include_orphans: bool = False,
    allow_empty_reference_set: bool = False,
) -> PruneReport:
    """Delete exactly the version directories a prior plan reported.

    The plan the caller showed and confirmed is the most that is deleted. A
    directory is removed only when the plan listed it as a target (superseded,
    or orphaned when ``include_orphans`` is set) and a fresh classification
    made by this call still does. A directory the plan showed in any other
    state is kept, even when the tree changed so that it now looks like a
    target, and so is a directory a manifest started to use between plan and
    apply. Every removal also re-checks its own guards at the moment it runs.

    Deletion is refused outright on a platform that cannot delete safely
    (see :func:`_delete_unsupported`), when the current reference-set state
    no longer permits it, or when the plan lists a directory outside this
    data root.

    Parameters
    ----------
    report : PruneReport
        The plan to act on, as returned by :func:`plan_prune`.
    data_root : str | Path | None
        Override for the data root; defaults to the resolved FWL_DATA tree. Must
        be the same root the plan was built against.
    include_orphans : bool
        Also remove the orphaned version directories in the plan.
    allow_empty_reference_set : bool
        Permit an orphan-including apply to proceed even when the current
        reference set declares no dataset.

    Returns
    -------
    PruneReport
        The plan, with each removed directory's entry rewritten to say so, and
        the reference-set error signals recomputed at apply time. ``ok`` is
        false, and ``apply_refusal`` names why, when the tree changed under
        this call into a state the plan could no longer delete from.

    Raises
    ------
    FileNotFoundError
        When the data root does not exist.
    """
    root = existing_data_root(data_root)
    unsupported = _delete_unsupported()
    if unsupported is not None:
        return _refused(report, unsupported)
    stray = next((c for c in report.candidates if not _inside(c.path, root)), None)
    if stray is not None:
        return _refused(
            report, f'the plan lists {stray.path}, outside {root}; it was built for another root'
        )
    build = _build(root, for_delete=True)
    current = build.report()
    refusal = current.deletion_refusal(
        include_orphans=include_orphans, allow_empty_reference_set=allow_empty_reference_set
    )
    if refusal:
        # The tree changed under us into a state the plan could not delete from.
        return _refused(current, refusal, candidates=report.candidates)
    targets = _target_states(include_orphans=include_orphans)
    # A candidate must be a target both in the plan the caller confirmed and
    # in this call's fresh build: the plan bounds what may go, and the fresh
    # state catches a directory that stopped being safe to remove since.
    fresh_by_dir = {fresh.path: fresh for fresh in build.candidates}
    results = []
    for c in report.candidates:
        fresh = fresh_by_dir.get(c.path)
        if fresh is None:
            fresh = next((f for f in build.candidates if _same_entry(f.path, c.path)), None)
        if fresh is None:
            if not os.path.lexists(c.path):
                results.append(replace(c, state=GONE, size=0, detail='no longer on disk'))
            elif c.state in targets:
                detail = 'no longer a version dir; not removed'
                results.append(replace(c, state=REFUSED, detail=detail))
            else:
                results.append(c)
            continue
        if c.state not in targets:
            results.append(fresh)
            continue
        if fresh.state not in targets:
            # Confirmed for deletion but no longer a target: kept, and not a clean run.
            detail = f'now {fresh.state}; not removed'
            results.append(replace(fresh, state=REFUSED, detail=detail))
            continue
        results.append(
            _remove_one(
                fresh,
                root,
                build.referenced,
                build.referenced_link_ids,
                case_insensitive=build.case_insensitive,
            )
        )
    return replace(current, candidates=tuple(results))

def human_bytes(count: int) -> str:
    """Render a byte count as a short human-readable size."""
    size = float(count)
    for unit in ('B', 'KiB', 'MiB', 'GiB', 'TiB'):
        if size < 1024 or unit == 'TiB':
            return f'{size:.0f} {unit}' if unit == 'B' else f'{size:.1f} {unit}'
        size /= 1024
    return f'{count} B'

def plan_prune(data_root: str | Path | None = None) -> PruneReport:
    """Report which version directories would be removed, touching nothing.

    Parameters
    ----------
    data_root : str | Path | None
        Override for the data root; defaults to the resolved FWL_DATA tree.

    Returns
    -------
    PruneReport
        One entry per ``r<record-id>`` directory found, classified against the
        installed manifests, with per-category reclaimable bytes.

    Raises
    ------
    FileNotFoundError
        When the data root does not exist. A plan never creates it.
    """
    return _build(existing_data_root(data_root)).report()

def prune_versions(
    data_root: str | Path | None = None,
    *,
    delete: bool = False,
    include_orphans: bool = False,
    allow_empty_reference_set: bool = False,
) -> PruneReport:
    """Plan a prune and, when ``delete`` is set, remove the proven-unreferenced set.

    A superseded version directory is removed by default. An orphaned one is
    removed only when ``include_orphans`` is set, because it cannot be proven
    unreferenced by manifests this environment cannot see. Deletion is refused
    outright on a platform that cannot delete safely (see
    :func:`_delete_unsupported`), when the reference set is incomplete, the
    tree cannot be fully read, a fetch lock is held or cannot be checked, or
    (for an orphan-including run) the reference set is empty and the override
    was not given.

    Parameters
    ----------
    data_root : str | Path | None
        Override for the data root; defaults to the resolved FWL_DATA tree.
    delete : bool
        Remove the target directories. When False this is a dry run.
    include_orphans : bool
        Also remove orphaned version directories. Has no effect without
        ``delete``.
    allow_empty_reference_set : bool
        Permit an orphan-including run to proceed even when no installed
        manifest declares any dataset. Has no effect without ``delete`` and
        ``include_orphans``.

    Returns
    -------
    PruneReport
        The plan, with each removed directory's entry rewritten to say so.

    Raises
    ------
    FileNotFoundError
        When the data root does not exist.
    """
    root = existing_data_root(data_root)
    unsupported = _delete_unsupported() if delete else None
    build = _build(root, for_delete=delete and unsupported is None)
    report = build.report()
    if unsupported is not None:
        return _refused(report, unsupported)
    if not delete or report.deletion_refusal(
        include_orphans=include_orphans, allow_empty_reference_set=allow_empty_reference_set
    ):
        # A dry run, or a run the reference set will not allow: report, do nothing.
        return report
    targets = _target_states(include_orphans=include_orphans)
    results = [
        _remove_one(
            c,
            root,
            build.referenced,
            build.referenced_link_ids,
            case_insensitive=build.case_insensitive,
        )
        if c.state in targets
        else c
        for c in build.candidates
    ]
    return replace(report, candidates=tuple(results))