galaxy-tool-codemod 0.2.0__py3-none-any.whl

galaxy_tool_codemod/__init__.py

@@ -0,0 +1,12 @@
+"""LibCST-shaped framework for structural refactors of Galaxy tool XML.
+
+Tier 2 of the Galaxy tool refactoring architecture (see ``README.md``).
+Per dignified-python this package does not re-export from its
+submodules — import the symbols you need directly:
+
+    from galaxy_tool_codemod.parse import parse_module
+    from galaxy_tool_codemod.canonical import canonical_codemods
+    from galaxy_tool_codemod.module import Module
+    from galaxy_tool_codemod.cursor import Cursor
+    from galaxy_tool_codemod.codemod import CodemodCommand
+"""

galaxy_tool_codemod/_version.py

@@ -0,0 +1,21 @@
+"""Shared version-parse helper for the codemod tier.
+
+``packaging`` exposes no validity predicate, so a ``try``/``except`` over
+``Version`` is the sanctioned third-party boundary. Both the profile-semantics
+catalogue (``profile_semantics``) and the runtime-gated-fix crossing gate
+(``runtime_fixes``) need to place a possibly-unparseable profile string, so the
+helper lives here once rather than being mirrored in each (architecture audit
+2026-06-03, ``../../docs/architecture_audit.md``).
+"""
+
+from __future__ import annotations
+
+from packaging.version import InvalidVersion, Version
+
+
+def version_or_none(value: str, /) -> Version | None:
+    """Parse *value* as a ``Version``, or ``None`` if it is not one."""
+    try:
+        return Version(value)
+    except InvalidVersion:
+        return None

galaxy_tool_codemod/canonical.py

@@ -0,0 +1,109 @@
+"""The bundled codemod pipelines — ordered contracts consumed by the app tier.
+
+Tier 2 (this package) and Tier 3 (``galaxy-tool-fmt``) are independent
+siblings of Tier 1 (``galaxy-tool-source``); neither runs the user-facing
+workflow. The orchestration — read a file, apply a pipeline, write the result
+via fmt's serializer — lives in the top-level app tier
+(``galaxy-tool-refactor-cli``). This module only declares *which* codemods run
+and *in what order*; the app consumes these tuples.
+
+Two pipelines, separated because profile upgrade is semantic and opt-in while
+canonicalisation is safe and idempotent:
+
+``canonical_codemods()`` — the structural canonical pipeline (the app's ``format``
+command, run before fmt's cosmetic rules), derived from the codemods that declare
+the ``"default"`` ruleset, ordered by ``meta.order``. Front-to-back:
+
+1. ``FixTypos`` — repair near-miss spelling typos. A no-op unless the tool
+   validates at no profile, so it only acts on broken tools; running it first
+   lets the rest of the pipeline see a validatable tree.
+2. ``NormalizeBooleanValues`` — canonicalize Python-style boolean attribute
+   values (``True``/``Yes``/…) to ``xs:boolean`` (``true``/``false``) on
+   schema-boolean attributes. Like ``FixTypos`` a no-op unless the tool validates
+   nowhere; behaviour-preserving and the sibling repair ``FixTypos`` cannot reach
+   (the lenient model accepts ``True``).
+3. ``RepairHelpRst`` — repair the deterministically-fixable invalid ``<help>``
+   reStructuredText (GTR089.1, the fixable half of the GTR089 partition) behind
+   tier 1's behaviour-preserving gate. A no-op on valid or macro-bearing help;
+   what it can't reach stays the ``GTR089.2`` advisory residual. See
+   ``docs/decisions.md`` §37.
+4. ``TrimAttributeWhitespace`` / ``ReplaceOutputElement`` /
+   ``DropRedundantParamName`` — the planemo-parity fixes (GTR035–GTR037):
+   value-level repairs that settle attribute *content* before the reorders tidy
+   attribute *order*.
+5. ``ReorderParamAttributes`` / ``ReorderToolAttributes`` — tidy attribute order
+   once the tree is settled.
+6. ``ReorderToolChildren`` — reorder the root ``<tool>``'s child elements to the
+   IUC convention (element-level tidying after attribute-level). Validity-safe:
+   the schema's ``<tool>`` content model is order-free (``xs:all``).
+7. ``WrapCommandCdata`` / ``WrapHelpCdata`` — wrap a pure-text ``<command>`` /
+   ``<help>`` body in ``<![CDATA[…]]>`` (IUC #34/#42). Behaviour-preserving — lxml
+   exposes the entity-unescaped text, so only the serialised bytes change, not the
+   value Galaxy runs/renders. Content-level tidying, so it runs after the
+   structural reorders; independent of them (it never touches child order). See
+   ``docs/decisions.md`` §29.
+8. ``SingleQuoteCommandVars`` — single-quote the *provably*-single-valued unquoted
+   Cheetah ``$var``\\ s in ``<command>`` (GTR020.1, the fixable half of the GTR020
+   partition).
+   Acts only on references whose value can never contain whitespace for a working
+   tool (bare single-token params, ``$__…__`` path built-ins, space-free attrs),
+   so it is behaviour-preserving like the CDATA wraps. It runs **after**
+   ``WrapCommandCdata`` so it sees the body already in its canonical CDATA form and
+   preserves it. Unlike the rest of this pipeline it changes the default ``format``
+   output for tools that were never previously rewritten — a deliberate, data-backed
+   reversal of the GTR020.2-stays-advisory stance (``docs/decisions.md`` §30). The
+   advisory ``GTR020.2`` check still reports the non-provable residual this skips.
+
+It deliberately does **not** change ``profile=`` or apply version migrations —
+that is the upgrade pipeline's job.
+
+``AUTO_UPGRADE_CODEMODS`` — the opt-in profile-upgrade pipeline (the app's
+``upgrade`` command). Front-to-back:
+
+1. ``FixTypos`` / ``NormalizeBooleanValues`` — repair first, so a broken-and-
+   outdated tool becomes validatable and therefore upgradable in one pass.
+2. ``UpgradeToLatest`` — iteratively upgrade the (now possibly repaired) tool
+   toward the latest profile, re-declaring its profile between steps. This
+   subsumes ``UpdateProfile`` (it runs it internally each round).
+
+``FixTypos`` / ``NormalizeBooleanValues`` intentionally appear in both pipelines;
+both are idempotent, so running them in whichever pipeline the user invokes is
+harmless.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+
+from galaxy_tool_codemod.catalog import coded_codemods
+from galaxy_tool_codemod.codemod import CodemodCommand
+from galaxy_tool_codemod.codemods.fix_typos import FixTypos
+from galaxy_tool_codemod.codemods.normalize_boolean_values import (
+    NormalizeBooleanValues,
+)
+from galaxy_tool_codemod.upgrades import UpgradeToLatest
+
+
+@cache
+def canonical_codemods() -> tuple[type[CodemodCommand], ...]:
+    """The structural canonical/``format`` pipeline — **derived, not hardcoded**.
+
+    Every codemod that declares the ``"default"`` ruleset, ordered by ``meta.order``.
+    Membership and application order now live on each codemod's ``RuleMeta``
+    (``rulesets`` / ``order``), so this is computed from the rules rather than being
+    a second hand-maintained source of truth. The front-to-back order it yields is
+    the one documented above (``FixTypos`` → … → ``SingleQuoteCommandVars``).
+    """
+    return tuple(
+        sorted(
+            (cls for cls in coded_codemods() if "default" in cls.meta.rulesets),
+            key=lambda cls: cls.meta.order,
+        )
+    )
+
+
+AUTO_UPGRADE_CODEMODS: tuple[type[CodemodCommand], ...] = (
+    FixTypos,
+    NormalizeBooleanValues,
+    UpgradeToLatest,
+)

galaxy_tool_codemod/catalog.py

@@ -0,0 +1,90 @@
+"""The full set of GTR-coded codemods, for documentation and registry use.
+
+Distinct from ``canonical_codemods()`` (``canonical.py``): that tuple is the
+*ordered pipeline* fmt's CLI runs, and it omits the single-step ``upgrade_vN``
+codemods because ``UpgradeToLatest`` drives them internally. This catalog lists
+*every* codemod that carries a ``RuleMeta`` GTR code, so a cross-tier rule
+registry (such as the corpus-format stat page) can enumerate them alongside the
+formatter tier's ``all_rules()``.
+"""
+
+from __future__ import annotations
+
+from galaxy_tool_codemod.codemod import CodemodCommand
+from galaxy_tool_codemod.codemods.convert_help_markdown import (
+    ConvertHelpToMarkdown,
+)
+from galaxy_tool_codemod.codemods.drop_redundant_param_name import (
+    DropRedundantParamName,
+)
+from galaxy_tool_codemod.codemods.fix_from_work_dir_whitespace import (
+    FixFromWorkDirWhitespace,
+)
+from galaxy_tool_codemod.codemods.fix_interpreter import FixInterpreter
+from galaxy_tool_codemod.codemods.fix_output_format_input import (
+    FixOutputFormatInput,
+)
+from galaxy_tool_codemod.codemods.fix_typos import FixTypos
+from galaxy_tool_codemod.codemods.normalize_boolean_values import (
+    NormalizeBooleanValues,
+)
+from galaxy_tool_codemod.codemods.reorder_param_attributes import (
+    ReorderParamAttributes,
+)
+from galaxy_tool_codemod.codemods.reorder_tool_attributes import (
+    ReorderToolAttributes,
+)
+from galaxy_tool_codemod.codemods.reorder_tool_children import (
+    ReorderToolChildren,
+)
+from galaxy_tool_codemod.codemods.repair_help_rst import RepairHelpRst
+from galaxy_tool_codemod.codemods.replace_output_element import (
+    ReplaceOutputElement,
+)
+from galaxy_tool_codemod.codemods.single_quote_command_vars import (
+    SingleQuoteCommandVars,
+)
+from galaxy_tool_codemod.codemods.tokenize_version import TokenizeVersion
+from galaxy_tool_codemod.codemods.trim_attribute_whitespace import (
+    TrimAttributeWhitespace,
+)
+from galaxy_tool_codemod.codemods.update_profile import UpdateProfile
+from galaxy_tool_codemod.codemods.upgrade_19_01 import Upgrade19_01
+from galaxy_tool_codemod.codemods.upgrade_21_09 import Upgrade21_09
+from galaxy_tool_codemod.codemods.upgrade_24_0 import Upgrade24_0
+from galaxy_tool_codemod.codemods.upgrade_24_1 import Upgrade24_1
+from galaxy_tool_codemod.codemods.upgrade_25_1 import Upgrade25_1
+from galaxy_tool_codemod.codemods.wrap_command_cdata import WrapCommandCdata
+from galaxy_tool_codemod.codemods.wrap_help_cdata import WrapHelpCdata
+from galaxy_tool_codemod.upgrades import UpgradeToLatest
+
+
+def coded_codemods() -> tuple[type[CodemodCommand], ...]:
+    """Return every GTR-coded codemod class, sorted by ``meta.code``."""
+    classes: list[type[CodemodCommand]] = [
+        FixTypos,
+        ReorderParamAttributes,
+        ReorderToolAttributes,
+        ReorderToolChildren,
+        UpdateProfile,
+        Upgrade19_01,
+        Upgrade21_09,
+        Upgrade24_0,
+        Upgrade24_1,
+        Upgrade25_1,
+        UpgradeToLatest,
+        FixFromWorkDirWhitespace,
+        FixOutputFormatInput,
+        FixInterpreter,
+        NormalizeBooleanValues,
+        RepairHelpRst,
+        WrapCommandCdata,
+        WrapHelpCdata,
+        SingleQuoteCommandVars,
+        TrimAttributeWhitespace,
+        ReplaceOutputElement,
+        DropRedundantParamName,
+        ConvertHelpToMarkdown,
+        TokenizeVersion,
+    ]
+    return tuple(sorted(classes, key=lambda cls: cls.meta.code))

galaxy_tool_codemod/certify.py

@@ -0,0 +1,47 @@
+"""The ``EditCertifier`` seam: a pluggable per-edit behaviour-preservation oracle.
+
+GTR020.1 (``SingleQuoteCommandVars``) decides, per occurrence, whether single-quoting
+a Cheetah ``$var`` in ``<command>`` preserves behaviour. By **default** it uses the
+tier-1 static policy ``galaxy_tool_source.shell_oracle.quote_is_behavior_preserving``
+— the
+bashlex shell-context classifier composed with the value-domain rule, degrading to the
+pure value-domain ``provably_quotable`` when the optional
+``galaxy-tool-source[shell-oracle]`` extra is absent.
+
+This Protocol reserves the seam (shipped consulting ``None`` = the static policy) for
+the Phase-2 CT3 *render* certifier (``--certify=render``): an ``EditCertifier`` injected
+into the codemod overrides the default and may only *narrow* the candidate set. The
+codemod calls ``should_quote`` with the same arguments as the static policy so the two
+are interchangeable. See
+``../../docs/upgrade_research/cheetah_bashlex_boundary_oracle.md`` §4.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from galaxy_tool_source.command_text import UnquotedVar
+
+
+@runtime_checkable
+class EditCertifier(Protocol):
+    """Certifies whether a single-quote edit on one ``<command>`` occurrence is safe."""
+
+    def should_quote(
+        self,
+        body: str,
+        /,
+        *,
+        occurrence: UnquotedVar,
+        kinds: dict[str, str],
+        structural: set[str],
+    ) -> bool:
+        """Whether single-quoting *occurrence* in ``<command>`` *body* keeps behaviour.
+
+        Signature-compatible with
+        ``galaxy_tool_source.shell_oracle.quote_is_behavior_preserving`` so a
+        certifier and
+        the default static policy are drop-in interchangeable.
+        """
+        ...

galaxy_tool_codemod/change.py

@@ -0,0 +1,63 @@
+"""``Change`` — one detected structural mutation, applied via a thunk.
+
+A codemod's **detect** phase yields ``Change``s without touching the tree: each
+carries the diagnostic data (``code``, ``sourceline``, ``xpath``, ``message`` —
+the same fields as a tier-0.5 ``Violation``) plus a zero-argument ``mutate``
+thunk that performs the mutation through the existing ``Cursor`` primitives. The
+detect list *is* the report; running ``apply_changes`` over it is the fix. One
+mutation site (the thunk body), one source of truth — the change a codemod
+reports is exactly the change it applies, with no risk of the two drifting.
+
+See ``galaxy-tool-fmt``'s ``edits.py`` for the cosmetic-tier analogue; the
+difference is that an ``Edit`` is a pure-data union dispatched by ``match/case``
+whereas a ``Change`` carries its mutation as a closure over a ``Cursor`` call
+(``docs/decisions.md`` § on the detect/fix split records why the structural tier
+reuses the cursor rather than re-enumerating every mutation kind).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+
+from galaxy_tool_refactor_rules.violation import Violation
+
+
+@dataclass(frozen=True)
+class Change:
+    """One structural mutation a codemod detected, with the thunk that applies it.
+
+    Attributes:
+        code: The codemod's ``RuleMeta.code`` (e.g. ``"GTR002"``).
+        sourceline: 1-based source line of the affected element, or ``0``.
+        xpath: Absolute xpath of the affected element.
+        message: One-line human-readable description of the change.
+        mutate: Zero-argument thunk that performs the mutation when called.
+            Excluded from equality and ``repr`` — two changes are equal when
+            their diagnostic data matches, independent of closure identity.
+    """
+
+    code: str
+    sourceline: int
+    xpath: str
+    message: str
+    mutate: Callable[[], None] = field(compare=False, repr=False)
+
+    def to_violation(self) -> Violation:
+        """Project the change's diagnostic data onto a tier-0.5 ``Violation``."""
+        return Violation(
+            code=self.code,
+            sourceline=self.sourceline,
+            xpath=self.xpath,
+            message=self.message,
+        )
+
+
+def apply_changes(changes: Iterable[Change], /) -> None:
+    """Apply every change by invoking its ``mutate`` thunk, in iteration order.
+
+    The single dispatch site for structural mutation: callers that only want
+    the report iterate ``detect`` directly and never reach here.
+    """
+    for change in changes:
+        change.mutate()

galaxy_tool_codemod/codemod.py

@@ -0,0 +1,136 @@
+"""``CodemodCommand`` base class and the detect-dispatch harness.
+
+A structural codemod subclasses ``CodemodCommand`` and defines one or more
+``detect_<TagPascalCase>`` methods. ``detect(module)`` walks the lxml tree in
+document order; for each element it looks up ``detect_<TagPascalCase>`` and, if
+present, yields the ``Change``s it returns — **without mutating the tree**. The
+yielded change list *is* the lint report. ``apply(module)`` is derived: it
+materialises ``detect(module)`` and runs each change's ``mutate`` thunk, so the
+change a codemod reports is exactly the change it applies. Comment and
+ProcessingInstruction nodes are skipped by ``Cursor.children()`` so detectors
+only see real elements.
+
+Validation-driven codemods (``FixTypos``, ``UpgradeToLatest`` and the per-step
+upgrades) cannot pre-compute a static change list — they branch on
+re-validation — so they override ``apply`` with bespoke logic and supply a
+**coarse** ``detect`` (see ``codemods._coarse_detect``).
+
+Dispatch is by **tag name** (``<param>`` → ``detect_Param``,
+``<change_format>`` → ``detect_ChangeFormat``). The architecture targets
+typed-model class names long-term — these coincide with PascalCase tags
+for unambiguous elements like ``<param>`` and ``<tool>``, and diverge
+only for elements with multiple per-context typed classes (``<when>``).
+Per-context dispatch is deferred until a codemod needs it.
+
+**Macro-mode handling is not yet implemented.** A future milestone will
+add a per-codemod declaration of how macros should be treated (expand /
+strip / skip / leave as-is) and a harness that honours it. Codemods
+written today operate on the source tree as-parsed; do not assume any
+macro-aware behaviour.
+
+See ``docs/architecture.md`` § Cursor-walk constraint and
+``PLAN.md`` § M3 for the design notes.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from typing import TYPE_CHECKING, ClassVar
+
+from galaxy_tool_codemod.change import Change, apply_changes
+from galaxy_tool_codemod.cursor import Cursor
+from galaxy_tool_codemod.eligibility import corpus_test_profile
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    from galaxy_tool_refactor_rules.meta import RuleMeta
+    from galaxy_tool_source.document import ToolDocument
+
+    from galaxy_tool_codemod.module import Module
+
+
+@cache
+def _detect_method_name(tag: str) -> str:
+    """Convert an XML tag to its detector method name.
+
+    ``"param"`` → ``"detect_Param"``;
+    ``"change_format"`` → ``"detect_ChangeFormat"``.
+    """
+    parts = tag.split("_")
+    pascal = "".join(part[:1].upper() + part[1:] for part in parts)
+    return f"detect_{pascal}"
+
+
+class CodemodCommand:
+    """Base class for structural-refactor codemods.
+
+    Every bundled codemod carries a ``meta: ClassVar[RuleMeta]`` GTR descriptor
+    (shared with the formatter tier via ``galaxy-tool-refactor-rules``) so the
+    two tiers expose one uniform rule registry. The enumerated set of coded
+    codemods is ``catalog.coded_codemods()``.
+    """
+
+    meta: ClassVar[RuleMeta]
+
+    def detect(self, module: Module, /) -> Iterable[Change]:
+        """Yield the ``Change``s this codemod would make, without mutating.
+
+        Walks ``module``'s lxml tree in document order, dispatching
+        ``detect_<Tag>`` for each element and yielding the changes it returns.
+        The default walk drives the structural (cursor-walk) codemods;
+        validation-driven codemods override this with a coarse detector.
+        """
+        yield from self._detect_dispatch(Cursor(module.document.root))
+
+    def _detect_dispatch(self, cursor: Cursor) -> Iterator[Change]:
+        method_name = _detect_method_name(cursor.tag)
+        detector = getattr(self, method_name, None)
+        if detector is not None:
+            yield from detector(cursor)
+        for child in cursor.children():
+            yield from self._detect_dispatch(child)
+
+    def apply(self, module: Module, /) -> None:
+        """Apply this codemod by running every detected change's thunk.
+
+        Detection is materialised first (all reads complete before any
+        mutation), then ``apply_changes`` runs the thunks. Mutations apply
+        immediately to the underlying tree; atomicity (deep-copy snapshot) is
+        the responsibility of whatever harness invokes ``apply`` — for the
+        canonical-pipeline CLI that's the app tier; for sweep tooling that's
+        the relevant subcommand.
+        """
+        apply_changes(list(self.detect(module)))
+
+    def upgrade_steps_applied(self) -> tuple[str, ...]:
+        """From-versions whose upgrade the last ``apply`` advanced the tool past.
+
+        Empty for every codemod except an upgrade orchestrator like
+        ``UpgradeToLatest``; the corpus sweep reads it to keep per-step upgrade
+        statistics (how many tools each ``upgrade_vN`` codemod advanced).
+        """
+        return ()
+
+    @classmethod
+    def corpus_eligible(cls, document: ToolDocument, /) -> bool:
+        """Whether a corpus sweep should run this codemod on *document*.
+
+        Default: eligible iff the codemod-sweep policy can pick a test profile
+        (i.e. the tool validates somewhere). A codemod that targets a different
+        population — e.g. ``FixTypos``, which repairs tools that validate
+        nowhere — overrides this. Evaluated on the pre-codemod document.
+        """
+        return corpus_test_profile(document) is not None
+
+    @classmethod
+    def corpus_validation_profile(cls, document: ToolDocument, /) -> str | None:
+        """The profile to validate the post-codemod document at.
+
+        Default mirrors the sweep policy. The sweep evaluates this *after*
+        ``apply``; for the structural codemods that leave the validating-profile
+        set unchanged it equals the pre-codemod choice, so behaviour is the same
+        as validating at the policy profile. Codemods that change which profiles
+        validate (``FixTypos``) override this to report the post-repair profile.
+        """
+        return corpus_test_profile(document)

galaxy_tool_codemod/codemods/__init__.py

@@ -0,0 +1,7 @@
+"""Codemod implementations bundled with the framework.
+
+Each module here defines one codemod (verb-noun name) — see
+``canonical.py`` for the set fmt's CLI runs to produce conformant output.
+Underscore-prefixed modules (e.g. ``_attribute_ordering``) are shared
+helpers, not codemods.
+"""

galaxy_tool_codemod/codemods/_attribute_ordering.py

@@ -0,0 +1,24 @@
+"""Shared helper for attribute-reordering codemods.
+
+Given an element's current attribute names and a priority map (attribute
+name → integer; lower runs first), returns the canonical order:
+priority-ascending, with unknown attributes sorting alphabetically after
+the known ones. Originally lived in ``galaxy-tool-fmt`` as
+``attribute_ordering``; moved here when the attribute-reorder rules
+became structural codemods.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+_UNKNOWN_PRIORITY = 100
+
+
+def canonical_order(
+    names: Iterable[str], priority: Mapping[str, int]
+) -> tuple[str, ...]:
+    """Return *names* sorted by *priority*; unknowns alphabetical at the end."""
+    return tuple(
+        sorted(names, key=lambda name: (priority.get(name, _UNKNOWN_PRIORITY), name))
+    )

galaxy_tool_codemod/codemods/_cdata.py

@@ -0,0 +1,46 @@
+"""Shared CDATA-wrapping detect logic for ``WrapCommandCdata`` / ``WrapHelpCdata``.
+
+Galaxy ``<command>`` and ``<help>`` bodies are best written inside a
+``<![CDATA[…]]>`` section so shell operators (``&&``, ``<``, ``|``) and markup
+stay literal — the IUC ``tool_xml`` best practices (#34 for ``<command>``, #42 for
+``<help>``). When a body is *pure text* — non-whitespace, no child nodes, not
+already CDATA-wrapped, and free of the ``]]>`` terminator that can't live inside a
+single section — wrapping it is **behaviour-preserving**: lxml already exposes the
+entity-unescaped text, so only the serialised bytes change (entities become literal
+inside CDATA), not the value Galaxy ultimately runs or renders.
+
+Mixed-content bodies (text interleaved with child elements or comments) and
+already-wrapped bodies are left untouched; the advisory sub-rules GTR018.2 / GTR019.2
+flag the rare residual these fix sub-rules deliberately skip.
+"""
+
+from __future__ import annotations
+
+from galaxy_tool_source.cdata import cdata_wrappable
+
+from galaxy_tool_codemod.change import Change
+from galaxy_tool_codemod.cursor import Cursor
+
+
+def cdata_wrap_change(cursor: Cursor, /, *, code: str, element: str) -> Change | None:
+    """Return a Change wrapping *cursor*'s body in CDATA, or ``None`` if unwrappable.
+
+    Eligibility is the shared tier-1 ``cdata_wrappable`` predicate (so the advisory
+    GTR018.2 / GTR019.2 residual — ``needs_cdata and not cdata_wrappable`` — can never
+    drift from what this fix accepts). Unwrappable cases each left for the advisory
+    sub-rule: a whitespace-only body, a mixed-content body (any child node), an
+    already-wrapped body, or a body containing ``]]>`` (which cannot be expressed in
+    one CDATA section).
+    """
+    if not cdata_wrappable(cursor.element):
+        return None
+    text = cursor.text
+    if text is None:  # cdata_wrappable guarantees non-None; keeps mypy + LBYL happy
+        return None
+    return Change(
+        code=code,
+        sourceline=cursor.sourceline,
+        xpath=cursor.xpath,
+        message=f"<{element}> body is not wrapped in CDATA",
+        mutate=lambda: cursor.set_text(text, cdata=True),
+    )

galaxy_tool_codemod/codemods/_coarse_detect.py

@@ -0,0 +1,65 @@
+"""Coarse detection for validation-driven codemods.
+
+The structural reorderers compute a per-occurrence change list directly. The
+validation-driven codemods (``FixTypos``, ``UpdateProfile``, ``UpgradeToLatest``
+and the per-step upgrades) cannot: they branch on re-validation, so there is no
+static change list to pre-compute. Their detect phase is therefore **coarse** —
+it answers only "would applying this codemod change the tool?" by running the
+codemod on a throwaway copy and comparing the serialised tree. When the answer
+is yes it yields a single ``Change`` located at the root ``<tool>`` whose thunk
+runs the real ``apply``; otherwise it yields nothing.
+
+This keeps detect/apply parity (detect yields ⇔ apply mutates) for the sweep's
+parity gate without pretending to a precision these codemods cannot offer; the
+per-occurrence lint value concentrates in the structural and detect-only rules.
+See ``docs/decisions.md`` § on the detect/fix split.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Iterator
+
+from galaxy_tool_source.document import ToolDocument
+from lxml import etree
+
+from galaxy_tool_codemod.change import Change
+from galaxy_tool_codemod.codemod import CodemodCommand
+from galaxy_tool_codemod.module import Module
+
+
+def coarse_detect(
+    codemod: CodemodCommand, module: Module, /, *, message: str
+) -> Iterator[Change]:
+    """Yield one root-level ``Change`` iff applying *codemod* would alter *module*.
+
+    Runs a fresh instance of *codemod* on a deep copy of *module* and compares
+    the serialised tree before and after. Both snapshots come from the copy, so
+    any representation shift introduced by ``deepcopy`` cancels out and only a
+    real mutation registers. The yielded change is located on the *original*
+    tree's root and its thunk applies *codemod* to the original module.
+
+    The copy keeps the original's ``source_path`` so the validation-driven
+    codemods resolve macro ``<import>``s the same way they do on the real
+    document — without it the copy would validate differently and detect would
+    drift from apply.
+    """
+    work = Module(
+        ToolDocument(
+            copy.deepcopy(module.document.tree),
+            source_path=module.document.source_path,
+        )
+    )
+    before = etree.tostring(work.document.tree)
+    type(codemod)().apply(work)
+    after = etree.tostring(work.document.tree)
+    if after == before:
+        return
+    root = module.cursor
+    yield Change(
+        code=codemod.meta.code,
+        sourceline=root.sourceline,
+        xpath=root.xpath,
+        message=message,
+        mutate=lambda: codemod.apply(module),
+    )