galaxy-tool-refactor-rules 0.2.0__tar.gz

galaxy_tool_refactor_rules-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Machine-local scratch, never committed: the cloned corpus (.local/corpus,
+# seeded from corpus_sources.json) and external source clones for inspection
+# (e.g. .local/galaxy-src = a clone of galaxyproject/galaxy used to verify
+# Galaxy-internal behaviour locally).
+# No trailing slash: `.local/` matches only a directory, so an accidental
+# symlink at this path was committable (it happened once; removed in this branch).
+.local
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+
+# Local-only draft of the GCC poster abstract.
+gcc2026-abstract.txt
+
+# Claude Code session scratch (the tracked .claude/ settings + skills stay; this
+# runtime lock for scheduled wakeups is machine-local).
+.claude/scheduled_tasks.lock
+.claude/worktrees/

galaxy_tool_refactor_rules-0.2.0/CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repository.
+
+## Project
+
+`galaxy-tool-refactor-rules` is the **rule-metadata** tier (tier 0.5) of the
+Galaxy tool refactoring framework. It is a tiny, dependency-free package that the
+codemod (tier 2), fmt (tier 3), check (tier 3.5), and registry (tier 3.6) tiers
+depend on directly; the app tier (4) reaches it transitively through the facade:
+
+| Tier | Layer | Package |
+|---|---|---|
+| 0.5 | **rule metadata** | `galaxy-tool-refactor-rules` *(this repo)* |
+| 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 owns the shared rule **metadata + diagnostics** vocabulary — three things:
+
+- `meta.py` — the `RuleMeta` frozen dataclass (the GTR rule descriptor).
+- `violation.py` — the `Violation` frozen dataclass (the per-occurrence detect
+  result: `code`, `int` `sourceline`, `str` `xpath`, `message`). Pure primitives,
+  no lxml — the read-only counterpart to tier-2 `Change` / tier-3 `Edit`.
+- `reference.py` — `render_rule_reference_table`, a pure markdown renderer for
+  a rule glossary.
+
+**Invariant: stay dependency-free.** Do not import lxml, tier 1/2/3, or any
+runtime dependency here. The whole point of this package is to be a shared
+primitive that does not drag the tiers into each other — adding a dependency
+would defeat that and risk re-coupling fmt to codemod (see
+`galaxy-tool-fmt/docs/decisions.md` §D10). The behavioral rule/codemod base
+classes belong in their own tiers, not here.
+
+## Coding standards
+
+Hand-written code follows **dignified-python**, vendored at the workspace root
+`.claude/skills/dignified-python/`:
+
+- Absolute imports, no re-exports, no `__all__`.
+- Keyword-only arguments after the first.
+- No import-time side effects.
+- Type hints throughout; mypy strict.
+
+`optimized-python` (`.claude/skills/optimized-python/`) is a secondary
+reference; **dignified-python governs on conflict**.
+
+## Commands
+
+Run these from the **workspace root** (`galaxy-tool-refactor/`):
+
+- `uv sync` — install dependencies
+- `uv run --package galaxy-tool-refactor-rules pytest galaxy-tool-refactor-rules/tests/` — run tests
+- `uv run ruff check galaxy-tool-refactor-rules/src galaxy-tool-refactor-rules/tests` — lint
+- `uv run mypy --config-file galaxy-tool-refactor-rules/pyproject.toml galaxy-tool-refactor-rules/src` — type-check (strict)
+
+## Useful workspace references
+
+- `galaxy-tool-fmt/src/galaxy_tool_fmt/rules.py` — the tier-3 `Rule` ABC
+  that carries `meta: ClassVar[RuleMeta]`.
+- `galaxy-tool-codemod/src/galaxy_tool_codemod/catalog.py` — the tier-2
+  catalog of GTR-coded codemods.
+- `scripts/corpus_check.py` — the stat-page generator that renders the
+  cross-tier rule reference table via `render_rule_reference_table`.

galaxy_tool_refactor_rules-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,46 @@
+# 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/docs/decisions.md

@@ -0,0 +1,152 @@
+# Decisions — galaxy-tool-refactor-rules
+
+Each entry records a decision once it lands: a date, the decision, and the
+rationale. Mirrors the conventions of the sibling packages' `docs/decisions.md`.
+
+## D1 (2026-05-29) — Extract the shared `RuleMeta` into its own tier-0.5 package
+
+### Decision
+
+The `RuleMeta` descriptor (previously private to `galaxy-tool-fmt`) and a
+pure markdown rule-glossary renderer now live in a new, dependency-free package
+`galaxy-tool-refactor-rules`. Both tier 3 (`galaxy-tool-fmt`) and tier 2
+(`galaxy-tool-codemod`) depend on it; neither depends on the other.
+
+Only the *metadata* moved. The behavioral bases stayed in their tiers:
+`galaxy_tool_fmt.rules.Rule` (yields lxml `Edit`s) and
+`galaxy_tool_codemod.codemod.CodemodCommand` (cursor-walk visitor) have
+different execution contracts and are not unified.
+
+### Rationale
+
+- **A documented trigger, now met.** `galaxy-tool-fmt/docs/decisions.md` §D1
+  §Layout said a shared rule package would be extracted "only when a second
+  consumer materialises." Giving the codemod tier the same metadata vocabulary
+  (so the GTR rule registry spans both tiers) is that second consumer.
+- **Tier independence is preserved, not weakened.** The standing constraint
+  (fmt's library must not depend on codemod — §D10 there) is about not dragging
+  the *structural framework* into cosmetic-only installs. A metadata-only
+  package with **zero runtime dependencies** is a shared primitive like tier 1,
+  not the structural framework; both tiers can depend on it safely.
+- **Dependency-free by design.** Keeping lxml / edits / cursor out of this
+  package is what makes it a safe shared dependency. The package ships a
+  `py.typed` marker and is type-checked under mypy strict.
+
+### Scope
+
+`RuleMeta` fields at the time of this extraction were the fmt original (`code`,
+`summary`, `since`, `until`, `cite`, `order`); `detect_only` was added later in
+§D2. The cross-tier GTR registry at the time spanned GTR001–GTR012 (3 fmt rules,
+9 codemods); it later grew GTR013 (codemod §17) and the advisory codes
+(tier 3.5, `galaxy-tool-lint`). Codes are globally unique across the tiers
+(asserted by a test in `galaxy-tool-fmt`'s corpus-check suite, which can
+import both tiers).
+
+## D2 (2026-05-30) — Add the shared `Violation` diagnostic type
+
+### Decision
+
+A `Violation` frozen dataclass joins `RuleMeta` in this tier-0.5 package
+(`violation.py`). It is the per-occurrence result of a rule's **detect (lint)**
+phase: `code` (matching `RuleMeta.code`), `sourceline` (1-based `int`, `0` when
+the element has no source position), `xpath` (`str`), and `message`. It is the
+read-only counterpart to the mutating tier-2 `Change` and tier-3 `Edit`.
+
+This lands as part of the detect/fix rule-split effort (see
+`galaxy-tool-codemod/docs/decisions.md` §19; the effort, PR1–5, merged in
+#15). Tier-2 `Change` projects onto a `Violation` via `Change.to_violation()`.
+
+### Rationale
+
+- **One shared diagnostic vocabulary.** Both the codemod (tier 2) and formatter
+  (tier 3) detect phases, the future report-only `check` CLI (tier 4), and the
+  planned advisory check library all surface findings; a single `Violation`
+  type lets them do so without depending on one another — the same role
+  `RuleMeta` plays for the rule registry.
+- **Dependency-free is preserved.** The location is a plain `int` line plus a
+  `str` xpath, never an lxml handle, so this package stays free of lxml / tier
+  1/2/3 imports (the invariant from D1 and `galaxy-tool-fmt` §D10). Putting
+  `Violation` in tier 2 instead would have forced fmt to import codemod once fmt
+  surfaces its edits as violations — exactly the re-coupling the tier split
+  exists to prevent.
+
+### Scope
+
+`Violation` is pure data with no methods beyond the dataclass. A capability flag
+on `RuleMeta` (e.g. `detect_only`) is deferred until detect-only rules arrive
+(roadmap PR4), so the flag has a first non-default user when added.
+
+## D3 (2026-05-30) — `RuleMeta.applies_to` (document-kind applicability)
+
+### Decision
+
+`RuleMeta` gains `applies_to: frozenset[str]` (default `frozenset({"tool"})`) —
+the document kinds a rule operates on, a subset of `{"tool", "macro"}`. A generic
+XML rule (canonical indentation GTR001, empty-element shorthand GTR004) declares
+`{"tool", "macro"}`; a tool-structural rule (blank line between `<tool>` sections
+GTR003, attribute / element order, profile upgrades) keeps the default `{"tool"}`;
+a future macro-library rule declares `{"macro"}`. Consumers run a rule against a
+document only when the document's kind is in this set (fmt's `rules_for_kind`,
+and later the registry/codemod tiers).
+
+### Rationale
+
+- **One field drives fmt *and* codemods.** Phase 2 of the macro-aware effort
+  needs to run rules on macro-library files (`<macros>` root); rather than a
+  bespoke "is this rule macro-safe?" check per tier, applicability becomes rule
+  metadata, read uniformly wherever a document of a given kind is formatted or
+  codemodded.
+- **Default `{"tool"}` is conservative and churn-free.** Every existing rule is
+  tool-structural by history, so the default leaves them unchanged; only the two
+  generic whitespace rules are explicitly widened. A rule runs on a macro file
+  only when it opts in.
+- **A set, not a single `scope` enum.** "Applies to any XML" is just "both
+  kinds", so a `frozenset` avoids a special `"any"` value and extends cleanly if
+  another document kind ever appears. See `galaxy-tool-fmt/docs/decisions.md`
+  §D16 for the fmt-side consumption (`format_macro_document` / `rules_for_kind`).
+
+
+## D4 (2026-06-09) — `RuleMeta.rulesets` + the `Ruleset` catalog
+
+### Decision
+
+Add `rulesets: frozenset[str] = frozenset()` to `RuleMeta` and a dependency-free
+`rulesets.py` (a `Ruleset(name, description)` catalog + `DEFAULT_RULESET`). This is the
+maintainer-facing "mark which rules belong to which set" mechanism: a rule declares its
+set membership on its own meta, and the registry tier (3.6) derives `name → codes` by
+grouping rules by these names (registry D15). The catalog holds the names + descriptions
+because that is a property of the *set*, not of any member; names are plain strings so a
+rule in any tier can declare membership without a heavier import. `order` is now used by
+**both** the fmt and codemod families (each ordered independently) — its docstring was
+corrected accordingly, since the canonical pipeline's order moved off the old hardcoded
+`CANONICAL_CODEMODS` tuple onto `meta.order`. Staying dependency-free is preserved (only
+`dataclasses`). The default empty `rulesets` means "never independently selectable" (e.g.
+an upgrade-only codemod driven by `UpgradeToLatest`).
+
+### Reproduction
+
+```sh
+uv run --package galaxy-tool-refactor-rules pytest \
+  galaxy-tool-refactor-rules/tests/test_rulesets.py galaxy-tool-refactor-rules/tests/test_meta.py
+```
+
+## D5 (2026-06-09) — `RuleMeta.planemo_linters` (the planemo-name alias)
+
+### Decision
+
+Add `planemo_linters: frozenset[str] = frozenset()` to `RuleMeta`: the planemo
+(`galaxy.tool_util.lint`) linter class names a rule covers (e.g. GTR028 →
+`{"HelpMissing", "HelpEmpty"}`). One GTR rule may cover several planemo linters —
+planemo splits some single practices across linter classes, and our rule is the
+natural unit (a survey found 21 of 25 such bundles are one practice). Formalizing
+the mapping (previously only in docstrings + the hand-maintained parity table) on
+the rule makes it the single source of truth: the registry (D16) derives a
+`planemo name → GTR code` index for name-based selection and **generates** the
+parity table from it. Empty for our own rules with no planemo equivalent (the
+cosmetic fmt rules, the XSD-restoring repairs). Dependency-free (just strings).
+
+### Reproduction
+
+```sh
+uv run --package galaxy-tool-refactor-rules pytest galaxy-tool-refactor-rules/tests/test_meta.py
+```

galaxy_tool_refactor_rules-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "galaxy-tool-refactor-rules"
+version = "0.2.0"
+description = "Shared rule-metadata vocabulary for the galaxy-tool-refactor tiers (tier 0.5)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Richard Burhans" }]
+# Intentionally dependency-free: this package is a pure metadata descriptor plus
+# a markdown render helper. It must stay free of lxml / tier-2 / tier-3 imports
+# so both fmt and codemod can depend on it without coupling the tiers together.
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[tool.ruff]
+src = ["src"]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "PTH"]
+
+[tool.mypy]
+files = ["src"]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

galaxy_tool_refactor_rules-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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/tests/test_dependency_free.py

@@ -0,0 +1,67 @@
+"""Guard: tier 0.5 (``galaxy-tool-refactor-rules``) must stay dependency-free.
+
+The whole point of this tier is to be a shared primitive that the codemod and fmt
+tiers can each carry without depending on each other (ARCHITECTURE.md §2; rules
+``docs/decisions.md`` §D1). A single third-party or higher-tier import here would
+re-couple the tiers it exists to keep apart. The invariant was prose-only — the
+architecture audit (2026-06-03, `docs/architecture_audit.md`) flagged it as
+unguarded — so this test enforces it: every import in the package's ``src`` must
+resolve to the standard library or the package itself. A future commit that adds,
+say, an ``lxml`` import fails here loudly.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+import galaxy_tool_refactor_rules
+
+_PACKAGE = "galaxy_tool_refactor_rules"
+_PACKAGE_DIR = Path(galaxy_tool_refactor_rules.__file__).parent
+# Top-level module names an import in this tier may reference: the standard
+# library, ``__future__``, and the package itself. Nothing else.
+_ALLOWED_ROOTS = set(sys.stdlib_module_names) | {_PACKAGE, "__future__"}
+
+
+def _imported_roots(source: str, /) -> set[str]:
+    """The top-level module names *source* imports absolutely.
+
+    Relative imports (``from . import x``) are internal and carry no external
+    coupling, so they are ignored.
+    """
+    roots: set[str] = set()
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.Import):
+            roots.update(alias.name.split(".")[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            roots.add(node.module.split(".")[0])
+    return roots
+
+
+def test_rules_tier_imports_only_stdlib_and_self() -> None:
+    offenders: dict[str, set[str]] = {}
+    for path in sorted(_PACKAGE_DIR.rglob("*.py")):
+        external = _imported_roots(path.read_text(encoding="utf-8")) - _ALLOWED_ROOTS
+        if external:
+            offenders[str(path.relative_to(_PACKAGE_DIR))] = external
+    assert not offenders, (
+        "tier 0.5 must stay dependency-free (ARCHITECTURE.md §2), but these files "
+        f"import non-stdlib, non-self modules: {offenders}"
+    )
+
+
+def test_guard_detects_a_planted_violation() -> None:
+    """The scan would actually catch a forbidden import (not a vacuous pass)."""
+    assert _imported_roots("import lxml.etree") == {"lxml"}
+    assert _imported_roots("from galaxy_tool_source.binding import load_tool") == {
+        "galaxy_tool_source"
+    }
+    # stdlib + self + a relative import are all allowed (subtract to empty).
+    allowed = _imported_roots(
+        "import sys\nfrom dataclasses import dataclass\n"
+        "from galaxy_tool_refactor_rules.meta import RuleMeta\n"
+        "from . import violation\n"
+    )
+    assert allowed - _ALLOWED_ROOTS == set()

galaxy_tool_refactor_rules-0.2.0/tests/test_meta.py

@@ -0,0 +1,62 @@
+"""Tests for the shared ``RuleMeta`` descriptor."""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from galaxy_tool_refactor_rules.meta import RuleMeta
+
+
+def test_rule_meta_is_frozen() -> None:
+    meta = RuleMeta(code="GTR001", summary="Do a thing.", since="0.1.0")
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        meta.code = "GTR999"  # type: ignore[misc]
+
+
+def test_rule_meta_defaults() -> None:
+    meta = RuleMeta(code="GTR001", summary="Do a thing.", since="0.1.0")
+    assert meta.until is None
+    assert meta.cite is None
+    assert meta.order == 100
+    assert meta.detect_only is False
+    assert meta.applies_to == frozenset({"tool"})
+    assert meta.parent is None
+    assert meta.rulesets == frozenset()
+    assert meta.planemo_linters == frozenset()
+
+
+def test_rule_meta_partition_child_carries_parent() -> None:
+    meta = RuleMeta(
+        code="GTR020.1", summary="Fix the provable part.", since="0.1.0",
+        parent="GTR020",
+    )
+    assert meta.code == "GTR020.1"
+    assert meta.parent == "GTR020"
+
+
+def test_rule_meta_applies_to_can_widen_to_macro() -> None:
+    meta = RuleMeta(
+        code="GTR001",
+        summary="Generic XML rule.",
+        since="0.1.0",
+        applies_to=frozenset({"tool", "macro"}),
+    )
+    assert meta.applies_to == frozenset({"tool", "macro"})
+
+
+def test_rule_meta_carries_supplied_values() -> None:
+    meta = RuleMeta(
+        code="GTR021",
+        summary="Do a thing.",
+        since="0.1.0",
+        until="0.4.0",
+        cite="https://example.invalid/spec",
+        order=10,
+        detect_only=True,
+    )
+    assert meta.until == "0.4.0"
+    assert meta.cite == "https://example.invalid/spec"
+    assert meta.order == 10
+    assert meta.detect_only is True

galaxy_tool_refactor_rules-0.2.0/tests/test_reference.py

@@ -0,0 +1,44 @@
+"""Tests for the markdown rule-reference table renderer."""
+
+from __future__ import annotations
+
+from galaxy_tool_refactor_rules.meta import RuleMeta
+from galaxy_tool_refactor_rules.reference import render_rule_reference_table
+
+
+def test_header_and_separator() -> None:
+    lines = render_rule_reference_table([])
+    assert lines == ["| Rule | Tier | What it does |", "|---|---|---|"]
+
+
+def test_rows_are_sorted_by_code() -> None:
+    entries = [
+        (RuleMeta(code="GTR003", summary="Three.", since="0.1.0"), "fmt"),
+        (RuleMeta(code="GTR001", summary="One.", since="0.1.0"), "fmt"),
+        (RuleMeta(code="GTR002", summary="Two.", since="0.0.1"), "codemod"),
+    ]
+    rows = render_rule_reference_table(entries)[2:]
+    codes = [line.split("|")[1].strip() for line in rows]
+    assert codes == ["GTR001", "GTR002", "GTR003"]
+
+
+def test_tier_label_is_emitted() -> None:
+    entries = [(RuleMeta(code="GTR002", summary="Two.", since="0.0.1"), "codemod")]
+    assert render_rule_reference_table(entries)[2] == "| GTR002 | codemod | Two. |"
+
+
+def test_angle_bracket_tokens_are_backtick_wrapped() -> None:
+    entries = [
+        (
+            RuleMeta(
+                code="GTR004",
+                summary="Collapse empty leaves to <foo/> form for <tool> children.",
+                since="0.1.0",
+            ),
+            "fmt",
+        ),
+    ]
+    row = render_rule_reference_table(entries)[2]
+    assert "`<foo/>`" in row
+    assert "`<tool>`" in row
+    assert "<foo/> " not in row.replace("`<foo/>`", "")

galaxy_tool_refactor_rules-0.2.0/tests/test_rulesets.py

@@ -0,0 +1,49 @@
+"""Tests for the named-ruleset catalog."""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from galaxy_tool_refactor_rules.rulesets import (
+    DEFAULT_RULESET,
+    Ruleset,
+    ruleset_description,
+    ruleset_names,
+    rulesets_catalog,
+)
+
+
+def test_ruleset_is_frozen() -> None:
+    ruleset = Ruleset(name="default", description="default")
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        ruleset.name = "other"  # type: ignore[misc]
+
+
+def test_catalog_has_the_seeded_rulesets() -> None:
+    assert ruleset_names() == ("cosmetic", "default", "iuc", "strict")
+
+
+def test_default_ruleset_is_in_the_catalog() -> None:
+    assert DEFAULT_RULESET == "default"
+    assert DEFAULT_RULESET in ruleset_names()
+
+
+def test_descriptions_resolve_for_every_name() -> None:
+    for name in ruleset_names():
+        description = ruleset_description(name)
+        assert description is not None
+        assert description != ""
+        # A description equal to the name is a placeholder, not a description
+        # (the user-facing `rulesets` command / MCP `list_rulesets` shows it).
+        assert description != name
+
+
+def test_unknown_ruleset_description_is_none() -> None:
+    assert ruleset_description("nope") is None
+
+
+def test_catalog_names_are_unique() -> None:
+    names = [ruleset.name for ruleset in rulesets_catalog()]
+    assert len(names) == len(set(names))

galaxy_tool_refactor_rules-0.2.0/tests/test_violation.py

@@ -0,0 +1,36 @@
+"""Tests for the shared ``Violation`` diagnostic descriptor."""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from galaxy_tool_refactor_rules.violation import Violation
+
+
+def test_violation_is_frozen() -> None:
+    violation = Violation(
+        code="GTR001", sourceline=12, xpath="/tool", message="needs a fix"
+    )
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        violation.code = "GTR999"  # type: ignore[misc]
+
+
+def test_violation_carries_supplied_values() -> None:
+    violation = Violation(
+        code="GTR002",
+        sourceline=7,
+        xpath="/tool/inputs/param[1]",
+        message="<param> attributes are not in IUC order",
+    )
+    assert violation.code == "GTR002"
+    assert violation.sourceline == 7
+    assert violation.xpath == "/tool/inputs/param[1]"
+    assert violation.message == "<param> attributes are not in IUC order"
+
+
+def test_violation_equality_is_by_value() -> None:
+    one = Violation(code="GTR001", sourceline=1, xpath="/tool", message="m")
+    two = Violation(code="GTR001", sourceline=1, xpath="/tool", message="m")
+    assert one == two