Preflight

preflight

Single read-only preflight core shared by both batch_edit surfaces.

The rules themselves live in :mod:axm_edit.core.precheck (pure, in-memory) and :mod:axm_edit.core.precheck_fs (filesystem-resolving). This module owns no rule: it orchestrates them over a raw batch payload, merges their diagnostics into one deterministically ordered list, and partitions that list into a blocking / non-blocking report both tool surfaces can consume.

Strictly read-only: every path resolution is delegated to the checks (which go through resolve_safe), and nothing here opens a file for writing, creates a temporary file or takes a checkpoint.

collect_preflight_diagnostics(root, raw_ops)

Collect every preflight diagnostic for a raw batch, without writing.

Merges the key rules that need the payload as authored (unknown edit keys, rewrite payload shape) with the static and filesystem rules of :func:~axm_edit.core.precheck_fs.run_fs_checks.

Parameters:

Name	Type	Description	Default
root	Path	Project root the batch would be applied to.	required
raw_ops	Sequence[Mapping[str, object]]	Operations in batch order, as authored (raw mappings).	required

Returns:

Type	Description
list[CheckDiagnostic]	Every diagnostic, ordered by (op_index, rule family, message).

Source code in packages/axm-edit/src/axm_edit/core/preflight.py

def collect_preflight_diagnostics(
    root: Path,
    raw_ops: Sequence[Mapping[str, object]],
) -> list[CheckDiagnostic]:
    """Collect every preflight diagnostic for a raw batch, without writing.

    Merges the key rules that need the payload *as authored* (unknown edit
    keys, rewrite payload shape) with the static and filesystem rules of
    :func:`~axm_edit.core.precheck_fs.run_fs_checks`.

    Args:
        root: Project root the batch would be applied to.
        raw_ops: Operations in batch order, as authored (raw mappings).

    Returns:
        Every diagnostic, ordered by ``(op_index, rule family, message)``.
    """
    unknown_keys = _check_unknown_edit_keys(raw_ops)
    rewrite_keys = _check_rewrite_keys(raw_ops)
    sanitised = [_sanitised_op(raw_op) for raw_op in raw_ops]
    return merge_diagnostics(
        unknown_keys,
        rewrite_keys,
        run_fs_checks(root, sanitised),
    )

merge_diagnostics(*groups)

Merge diagnostic groups into one deterministically ordered list.

Parameters:

Name	Type	Description	Default
groups	Sequence[CheckDiagnostic]	One diagnostic sequence per rule layer, in any order.	()

Returns:

Type	Description
list[CheckDiagnostic]	Every diagnostic, ordered by (op_index, rule family, message);
list[CheckDiagnostic]	the same input always yields an equal list.

Source code in packages/axm-edit/src/axm_edit/core/preflight.py

def merge_diagnostics(
    *groups: Sequence[CheckDiagnostic],
) -> list[CheckDiagnostic]:
    """Merge diagnostic groups into one deterministically ordered list.

    Args:
        groups: One diagnostic sequence per rule layer, in any order.

    Returns:
        Every diagnostic, ordered by ``(op_index, rule family, message)``;
        the same input always yields an equal list.
    """
    return sorted(
        (diagnostic for group in groups for diagnostic in group),
        key=_sort_key,
    )

partition_diagnostics(diagnostics)

Split diagnostics into blocking errors and informative warnings.

Parameters:

Name	Type	Description	Default
diagnostics	Sequence[CheckDiagnostic]	Diagnostics in the order they should be reported.	required

Returns:

Name	Type	Description
A	PreflightReport	class:~axm_edit.models.check.PreflightReport whose errors
	PreflightReport	and warnings preserve the input order and whose blocking is
	PreflightReport	True iff at least one diagnostic blocks the batch.

Source code in packages/axm-edit/src/axm_edit/core/preflight.py

def partition_diagnostics(
    diagnostics: Sequence[CheckDiagnostic],
) -> PreflightReport:
    """Split *diagnostics* into blocking errors and informative warnings.

    Args:
        diagnostics: Diagnostics in the order they should be reported.

    Returns:
        A :class:`~axm_edit.models.check.PreflightReport` whose ``errors``
        and ``warnings`` preserve the input order and whose ``blocking`` is
        True iff at least one diagnostic blocks the batch.
    """
    ordered = list(diagnostics)
    errors = [item for item in ordered if _is_blocking(item.severity)]
    warnings = [item for item in ordered if not _is_blocking(item.severity)]
    return PreflightReport(
        diagnostics=ordered,
        errors=errors,
        warnings=warnings,
        blocking=bool(errors),
    )