galaxy-tool-refactor-rules 0.2.0__py3-none-any.whl

galaxy_tool_refactor_rules/__init__.py

@@ -0,0 +1,11 @@
+"""Shared rule-metadata vocabulary for the galaxy-tool-refactor tiers.
+
+Tier 0.5 of the refactoring framework: a dependency-free home for the
+``RuleMeta`` descriptor shared by the formatter (tier 3) and the codemod
+framework (tier 2), plus a pure markdown render helper for rule glossaries.
+
+Following the project's dignified-python conventions there are no re-exports;
+callers import ``RuleMeta`` from ``galaxy_tool_refactor_rules.meta`` and
+``render_rule_reference_table`` from ``galaxy_tool_refactor_rules.reference``
+directly.
+"""

galaxy_tool_refactor_rules/meta.py

@@ -0,0 +1,86 @@
+"""The ``RuleMeta`` descriptor shared across the refactor tiers.
+
+Both a tier-3 formatter rule (``galaxy_tool_fmt.rules.Rule``) and a tier-2
+codemod (``galaxy_tool_codemod.codemod.CodemodCommand``) carry a
+``meta: ClassVar[RuleMeta]`` so the two tiers expose one uniform vocabulary for
+the GTR rule registry. The descriptor is pure data — it deliberately knows
+nothing about lxml, edits, or the cursor walk, which keeps this package
+dependency-free and the tiers independent.
+
+Versioning convention: stability for consumers comes from pinning the owning
+tier's package version in their lockfile, not from this metadata. ``since`` /
+``until`` are documentary only — ``until`` stays ``None`` while a rule is active
+and is stamped (for the changelog) in the same commit that retires the rule.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RuleMeta:
+    """Metadata descriptor for a refactor rule (a fmt rule or a codemod).
+
+    Attributes:
+        code: Short unique rule identifier (e.g. ``"GTR001"``).
+        summary: One-line human-readable description.
+        since: Version in which this rule was introduced.
+        until: Version in which this rule was removed, or ``None`` if active.
+        cite: Optional reference URL or citation.
+        order: Application order; lower values run first. Each family is ordered
+            independently by this value — the formatter tier sequences its
+            cosmetic rules, and the codemod tier sequences its canonical codemods
+            (the registry's apply phase sorts each family by ``order``). An
+            upgrade-only or report-only rule leaves it at the default.
+        detect_only: Whether the rule only *reports* (a lint with no automatic
+            fix), as opposed to the fixable fmt rules and codemods. The advisory
+            check tier (``galaxy-tool-lint``) sets this ``True``; a
+            report-only consumer like the ``check`` CLI uses it to treat such
+            findings as informational rather than as a failing gate.
+        applies_to: The document kinds the rule operates on — a subset of
+            ``{"tool", "macro"}``. A generic XML rule (canonical indentation,
+            empty-element shorthand) applies to both; a tool-structural rule
+            (``<tool>`` child order, a blank line between ``<tool>`` sections,
+            attribute order, profile upgrades) applies only to ``"tool"``; a
+            macro-library rule applies only to ``"macro"``. The default
+            ``{"tool"}`` is the conservative choice — a rule runs on a macro
+            file only when it explicitly opts in. Consumers run a rule against a
+            document only when the document's kind is in this set.
+        parent: The code of the **partition parent** this rule is a sub-rule of,
+            or ``None`` for a standalone rule. A best-practice that splits into a
+            provably-fixable part and an advisory residual is modelled as a parent
+            practice code (e.g. ``"GTR020"``) with two sub-rules whose own ``code``
+            is dotted: ``"GTR020.1"`` (fixable) and ``"GTR020.2"`` (advisory). The
+            parent is a registry-level grouping (selectable, expands to its
+            children), not itself a rule; this field is what the registry derives
+            the groups from. See registry ``docs/decisions.md`` D10.
+        rulesets: The names of the rule-sets this rule belongs to (the catalog
+            lives in ``rulesets.py``). This is the maintainer-facing "mark which
+            rules belong to which set" mechanism: the registry groups rules by
+            these names into selectable sets, and the CLI ``--ruleset`` flag
+            selects the **union** of the named sets. The default empty set means
+            the rule is never independently selectable — e.g. an upgrade-only
+            codemod driven internally by ``UpgradeToLatest``. Every name used
+            here must appear in the ``rulesets.py`` catalog (guarded by a test).
+        planemo_linters: The names of the planemo (``galaxy.tool_util.lint``)
+            linter classes this rule covers, e.g. ``{"HelpMissing", "HelpEmpty"}``.
+            One GTR rule may cover several planemo linters (planemo splits some
+            single practices across linter classes). The registry derives a
+            ``planemo name → GTR code`` index from this so a planemo user can
+            select/find a rule by its planemo name (``--select HelpMissing``) and
+            so the parity table can be generated. Empty for our own rules with no
+            planemo equivalent (the cosmetic fmt rules, the XSD-restoring repairs).
+    """
+
+    code: str
+    summary: str
+    since: str
+    until: str | None = None
+    cite: str | None = None
+    order: int = 100
+    detect_only: bool = False
+    applies_to: frozenset[str] = frozenset({"tool"})
+    parent: str | None = None
+    rulesets: frozenset[str] = frozenset()
+    planemo_linters: frozenset[str] = frozenset()

galaxy_tool_refactor_rules/reference.py

@@ -0,0 +1,48 @@
+"""Render a cross-tier GTR rule glossary as GitHub-flavored markdown.
+
+A pure, dependency-free helper: it turns ``(RuleMeta, tier)`` pairs into the
+rows of a ``| Rule | Tier | What it does |`` table, sorted by code. It emits the
+table only — the caller owns any surrounding heading and intro prose, which is
+context-specific (the fmt stat page frames it differently than a standalone rule
+registry would).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from galaxy_tool_refactor_rules.meta import RuleMeta
+
+# Element names in a summary (``<param>``, ``<foo/>``) would be parsed as HTML
+# tags inside a markdown table cell and rendered as nothing; wrap them in
+# backticks so they survive as literal text.
+_ANGLE_TOKEN = re.compile(r"(<[^>]+>)")
+
+
+def _backtick_xml_tokens(text: str) -> str:
+    """Backtick-wrap angle-bracket tokens so GitHub renders them literally."""
+    return _ANGLE_TOKEN.sub(r"`\1`", text)
+
+
+def render_rule_reference_table(entries: Iterable[tuple[RuleMeta, str]]) -> list[str]:
+    """Render ``(meta, tier)`` pairs as a markdown reference table.
+
+    Args:
+        entries: ``(RuleMeta, tier_label)`` pairs, where ``tier_label`` names the
+            owning tier (e.g. ``"fmt"`` or ``"codemod"``).
+
+    Returns:
+        Markdown lines: a header row, the separator, then one row per rule
+        ordered by ``meta.code``.
+    """
+    rows = sorted(entries, key=lambda entry: entry[0].code)
+    lines = [
+        "| Rule | Tier | What it does |",
+        "|---|---|---|",
+    ]
+    lines.extend(
+        f"| {meta.code} | {tier} | {_backtick_xml_tokens(meta.summary)} |"
+        for meta, tier in rows
+    )
+    return lines

galaxy_tool_refactor_rules/rulesets.py

@@ -0,0 +1,84 @@
+"""The named rule-sets — the maintainer-facing vocabulary for grouping rules.
+
+A *ruleset* is a named, described bucket of rules. **Membership is declared per
+rule** (``RuleMeta.rulesets``): a maintainer marks a rule's set(s) right on the
+rule. This module is the authoritative catalog of the ruleset *names and
+descriptions* — the one property that belongs to the set itself, not to any
+member. The registry tier (3.6) derives ``name -> {codes}`` by grouping rules by
+their declared membership, and the CLI ``--ruleset`` flag selects the **union** of
+the named sets.
+
+Dependency-free, like the rest of tier 0.5 — ruleset names are plain strings, so a
+rule in any tier can declare membership (``RuleMeta(..., rulesets=frozenset({...}))``)
+without importing anything heavier. Adding a ruleset is a developer task (a new
+``Ruleset`` here + tagging the member rules); there are no user-defined rulesets.
+
+The catalog also defines the subset relationships informally via the seeded
+membership: ``cosmetic`` ⊆ ``default`` == ``iuc`` ⊆ ``strict`` today. ``default``
+is the set applied when the user names no ruleset; it reproduces the historical
+default ``format`` behaviour.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Ruleset:
+    """A named rule-set: a selectable bucket of rules.
+
+    Attributes:
+        name: The selection key (e.g. ``"default"``) — exactly as it appears in
+            ``RuleMeta.rulesets`` and on the CLI ``--ruleset`` flag.
+        description: A one-line human-readable summary.
+    """
+
+    name: str
+    description: str
+
+
+DEFAULT_RULESET = "default"
+"""The ruleset selected when the user names none (the no-argument ``format`` set)."""
+
+
+_CATALOG: tuple[Ruleset, ...] = (
+    Ruleset(
+        name="cosmetic",
+        description="Cosmetic whitespace only (indent, blank lines, shorthand).",
+    ),
+    Ruleset(
+        name="default",
+        description="The opinionated canonical formatter: structural repair + "
+        "attribute/element order + CDATA/quoting/help-RST fixes + cosmetic "
+        "formatting (the default).",
+    ),
+    Ruleset(
+        name="iuc",
+        description="Mirrors 'default' today; reserved for IUC-specific "
+        "divergence.",
+    ),
+    Ruleset(
+        name="strict",
+        description="Everything in 'default' plus the advisory best-practice "
+        "checks (report-only).",
+    ),
+)
+
+
+def rulesets_catalog() -> tuple[Ruleset, ...]:
+    """Return every defined ruleset, in display order."""
+    return _CATALOG
+
+
+def ruleset_names() -> tuple[str, ...]:
+    """Return the defined ruleset names, in display order."""
+    return tuple(ruleset.name for ruleset in _CATALOG)
+
+
+def ruleset_description(name: str, /) -> str | None:
+    """Return the one-line description for *name*, or ``None`` if undefined."""
+    for ruleset in _CATALOG:
+        if ruleset.name == name:
+            return ruleset.description
+    return None

galaxy_tool_refactor_rules/violation.py

@@ -0,0 +1,39 @@
+"""The ``Violation`` diagnostic descriptor shared across the refactor tiers.
+
+A ``Violation`` is the per-occurrence report a detect (lint) phase produces:
+which rule fired (``code``), where (``sourceline`` + ``xpath``), and a
+human-readable ``message``. It is the read-only counterpart to the mutating
+``Edit`` (tier 3) / ``Change`` (tier 2) types — those carry the fix; this carries
+the finding. Both the formatter (tier 3) and codemod (tier 2) detect phases, the
+``check`` CLI (tier 4), and the advisory check library surface diagnostics as
+``Violation``s, so the type lives here next to ``RuleMeta`` where every tier can
+reach it without depending on one another.
+
+Like ``RuleMeta`` this is pure data — the location is a plain ``int`` line plus a
+``str`` xpath, never an lxml handle — which keeps this package dependency-free
+(no lxml, no tier 1/2/3 imports). See ``docs/decisions.md`` § D1 for the
+shared-vocabulary rationale.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Violation:
+    """A single detected rule occurrence in a tool XML document.
+
+    Attributes:
+        code: The rule's identifier (e.g. ``"GTR002"``); matches ``RuleMeta.code``.
+        sourceline: 1-based line of the offending element, or ``0`` when the
+            element was synthesised and has no source position.
+        xpath: Absolute xpath to the offending element (e.g.
+            ``"/tool/inputs/param[1]"``).
+        message: One-line human-readable description of the finding.
+    """
+
+    code: str
+    sourceline: int
+    xpath: str
+    message: str

galaxy_tool_refactor_rules-0.2.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: galaxy-tool-refactor-rules
+Version: 0.2.0
+Summary: Shared rule-metadata vocabulary for the galaxy-tool-refactor tiers (tier 0.5).
+Author: Richard Burhans
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# galaxy-tool-refactor-rules
+
+Shared **rule-metadata vocabulary** for the Galaxy tool refactoring framework —
+a small, dependency-free "tier 0.5" package consumed by both higher tiers:
+
+| Tier | Layer | Package |
+|---|---|---|
+| 0.5 | **rule metadata** | `galaxy-tool-refactor-rules` *(this package)* |
+| 1 | parsing & validation | `galaxy-tool-source` |
+| 2 | structure | `galaxy-tool-codemod` |
+| 3 | formatting | `galaxy-tool-fmt` |
+| 3.5 | advisory checks | `galaxy-tool-lint` |
+| 3.6 | rule registry / rulesets | `galaxy-tool-refactor-registry` |
+| 4 | app / CLI | `galaxy-tool-refactor-cli` |
+
+It provides:
+
+- **`galaxy_tool_refactor_rules.meta.RuleMeta`** — a frozen dataclass describing
+  one GTR rule (`code`, `summary`, `since`, `until`, `cite`, `order`,
+  `detect_only`, `applies_to`). A tier-3 formatter `Rule`, a tier-2
+  `CodemodCommand`, and a tier-3.5 `CheckRule` each carry a
+  `meta: ClassVar[RuleMeta]`, so the tiers share one registry vocabulary.
+- **`galaxy_tool_refactor_rules.violation.Violation`** — a frozen dataclass for a
+  detect-phase finding (`code`, `sourceline`, `xpath`, `message`); the pure,
+  lxml-free, read-only counterpart to the mutating tier-2 `Change` / tier-3 `Edit`.
+- **`galaxy_tool_refactor_rules.reference.render_rule_reference_table`** — a pure
+  helper that renders `(RuleMeta, tier)` pairs as a GitHub-flavored markdown
+  glossary table.
+
+## Why a separate package
+
+The descriptor is the only thing the two tiers genuinely share — their
+*behavioral* bases differ (fmt yields lxml edits; codemod walks a cursor), so
+those stay in their own packages. Keeping `RuleMeta` here, with **zero runtime
+dependencies**, lets both fmt and codemod depend on it without depending on each
+other — preserving the tier independence documented in
+`galaxy-tool-fmt/docs/decisions.md` §D10. The extraction was anticipated in
+that package's §D1 ("a shared rule-engine package will be extracted only when a
+second consumer materialises"); the codemod tier is that consumer.
+
+## Install / test
+
+```bash
+uv sync   # from the workspace root
+uv run --package galaxy-tool-refactor-rules pytest galaxy-tool-refactor-rules/tests/
+```

galaxy_tool_refactor_rules-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+galaxy_tool_refactor_rules/__init__.py,sha256=Q0rYk_ovDHfo8JCPwqW1NK3gH599PSc6ArOfIITj2Go,535
+galaxy_tool_refactor_rules/meta.py,sha256=IQ9dvG2bnqk4sanBopvPsZnLoXq8g6ZmNfmpRJRVqIQ,5015
+galaxy_tool_refactor_rules/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+galaxy_tool_refactor_rules/reference.py,sha256=kfnBf1uYStiucwZZsqakMpnwjlCVnczRWmqwedlKcKA,1691
+galaxy_tool_refactor_rules/rulesets.py,sha256=TzsBGU6pMxSeh9pYrEiYWvfj19o_pHyTtnqj1FxhmXY,2968
+galaxy_tool_refactor_rules/violation.py,sha256=2HYnrxByc_6_8qSVwwo-EqIPzeJ8Y_rER-GjC6a0GFo,1610
+galaxy_tool_refactor_rules-0.2.0.dist-info/METADATA,sha256=urxww9kbIu0D6U3Mu9tSGeGjZbiS1ho1BiVssOqfZvU,2440
+galaxy_tool_refactor_rules-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+galaxy_tool_refactor_rules-0.2.0.dist-info/RECORD,,

galaxy_tool_refactor_rules-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any