galaxy-tool-codemod 0.2.0__tar.gz

galaxy_tool_codemod-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+# Build / dist artifacts
+build/
+dist/
+*.egg-info/
+
+# Python bytecode
+__pycache__/
+*.pyc
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# uv
+.venv/
+uv.lock
+
+# Editor
+.idea/
+.vscode/
+*.swp

galaxy_tool_codemod-0.2.0/CLAUDE.md

@@ -0,0 +1,155 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repository.
+
+## Project
+
+`galaxy-tool-codemod` is the **structure** tier of the Galaxy tool
+refactoring framework — one of seven tiers (this package depends only on tier 1
+and the shared tier-0.5 rules metadata):
+
+| Tier | Layer | Package | What it owns |
+|---|---|---|---|
+| 0.5 | **rule metadata** | `galaxy-tool-refactor-rules` | shared `RuleMeta` + `Violation` |
+| 1 | **parsing & validation** | `galaxy-tool-source` | parsing, profile-aware XSD validation, typed views |
+| 2 | **structure** | `galaxy-tool-codemod` *(this repo)* | structural mutations (attribute order, element shape) |
+| 3 | **formatting** | `galaxy-tool-fmt` | whitespace / indentation / shorthand; the only tier that serialises canonical output XML |
+| 3.5 | **advisory checks** | `galaxy-tool-lint` | detect-only IUC best-practice checks |
+| 3.6 | **rule registry / rulesets** | `galaxy-tool-refactor-registry` | unified rule registry + rulesets; library-first facade |
+| 4 | **app / CLI** | `galaxy-tool-refactor-cli` | composes the tiers via the facade (`format`/`upgrade`/`check`) |
+
+This package supplies the **structural-refactor framework**: a
+``CodemodCommand`` **detect-primitive** base with tag-PascalCase dispatch
+(``detect_Param``, ``detect_Tool``, …) whose ``apply`` is derived from
+``detect`` (each rule has a non-mutating detect phase + a fix phase), an
+``lxml``-backed ``Cursor``
+with typed mutation primitives (``set_attribute``, ``delete_attribute``,
+``rename_attribute``, ``rename_tag``, ``reorder_attributes``,
+``reorder_children``, ``remove``, ``add_child``, ``attribute_names``,
+``set_text`` — the token-aware ``@PROFILE@`` rewrite, §21), a
+``Module`` wrapper (over a tier-1 ``ToolDocument``), a ``parse_module`` entry
+point (plus ``MacroModule`` / ``parse_macro_module`` — the macro-file
+counterparts wrapping a tier-1 ``MacroDocument``; ``Cursor`` is generic, so its
+mutators work on a ``<macros>`` tree unchanged. The ``CodemodCommand`` base
+stays tool-only until a macro-subject codemod needs it — see ``docs/decisions.md``
+§20), and the bundled codemods exposed via two ordered pipeline
+contracts in ``canonical.py``:
+
+- ``canonical_codemods()`` = ``FixTypos`` → ``NormalizeBooleanValues`` →
+  ``RepairHelpRst`` → ``TrimAttributeWhitespace`` → ``ReplaceOutputElement`` →
+  ``DropRedundantParamName`` → ``ReorderParamAttributes`` →
+  ``ReorderToolAttributes`` → ``ReorderToolChildren`` → ``WrapCommandCdata`` →
+  ``WrapHelpCdata`` → ``SingleQuoteCommandVars`` (the safe canonical/format
+  pipeline; ``TrimAttributeWhitespace`` / ``ReplaceOutputElement`` /
+  ``DropRedundantParamName`` = GTR035.1/GTR036/GTR037, the planemo-parity fixes
+  (GTR035 partitioned: the name-trim residual is the GTR035.2 advisory, §33);
+  ``ReorderToolChildren`` = GTR013, IUC #52 element order, validity-safe because
+  ``<tool>`` is ``xs:all``; ``WrapCommandCdata`` / ``WrapHelpCdata`` =
+  GTR018.1/GTR019.1, IUC #34/#42, wrap a pure-text ``<command>``/``<help>`` body in
+  CDATA — behaviour-preserving, ``docs/decisions.md`` §29;
+  ``SingleQuoteCommandVars`` = GTR020.1, IUC #36, single-quote the *provably*-
+  single-valued Cheetah vars in ``<command>`` — behaviour-preserving but the first
+  canonical codemod to shift default-``format`` bytes vs the pre-partition output,
+  ``docs/decisions.md`` §30; ``RepairHelpRst`` = GTR089.1, repair
+  deterministically-fixable invalid ``<help>`` reStructuredText behind a
+  render-equivalence gate, ``docs/decisions.md`` §37. The five
+  ``Wrap…``/``SingleQuote…``/``RepairHelpRst``/``TrimAttributeWhitespace`` codemods
+  are the fixable ``.1`` half of a partition practice — their advisory ``.2`` residual lives in the check tier;
+  registry ``docs/decisions.md`` D10).
+- ``AUTO_UPGRADE_CODEMODS`` = ``FixTypos`` → ``NormalizeBooleanValues`` →
+  ``UpgradeToLatest`` (the opt-in profile-upgrade pipeline).
+
+``ConvertHelpToMarkdown`` (GTR092, ``docs/decisions.md`` §38) is in neither
+pipeline: the first of the catalog's **opt-in-command-only** codemods (no ruleset; applied
+solely by the app's ``convert-help``) — the RST → Markdown ``<help>`` conversion
+behind tier-1 ``rst_markdown``'s render-equivalence gate + the profile ≥ 24.2 XSD
+gate. Its sibling ``TokenizeVersion`` (GTR094, §43) is the second:
+the @TOOL_VERSION@/@VERSION_SUFFIX@ extraction behind the expansion-equality
+gate, applied solely by ``tokenize-version``.
+
+``FixTypos``, ``NormalizeBooleanValues`` (GTR017 — boolean-case repair, the
+``True``/``False`` → ``true``/``false`` fix ``FixTypos`` cannot reach), and
+``UpgradeToLatest`` (which loops ``UpdateProfile`` + single-step ``upgrade_vN``
+codemods from ``upgrades.py``) are validation-driven and override ``apply``. The upgrade registry is grown
+empirically from ``corpus_check codemod`` discovery sweeps; see
+``docs/decisions.md`` §11–14, §16 for the canonical/upgrade split, and
+§17–18 for the element-order codemod (GTR013) + the `codemod` sweep's
+`--source combined` default.
+
+**Tier independence:** this package does not depend on fmt. The
+orchestration — running these pipelines and writing output through fmt's
+serializer — lives in the tier-3.6 registry facade
+(``galaxy-tool-refactor-registry``), which consumes ``canonical_codemods()``
+(its ``run`` / the app's ``format``) and ``AUTO_UPGRADE_CODEMODS`` (its
+``upgrade``); the tier-4 app CLI (``galaxy-tool-refactor-cli``) is a thin
+front-end over that facade. fmt's own CLI is cosmetic-only and does not
+consume these contracts (see ``galaxy-tool-fmt/docs/decisions.md``
+§D12).
+
+The architecture rationale lives in `docs/architecture.md` (a working
+copy forked from `galaxy-tool-source/docs/codemod-architecture.md` —
+predates the M1-M3.5 implementation; the current shape is recorded in
+`docs/decisions.md`). Milestone status and remaining work are in
+`PLAN.md`.
+
+## Coding standards
+
+Hand-written code follows **dignified-python**, vendored at the workspace root
+`.claude/skills/dignified-python/`:
+
+- LBYL over `try/except`. Exceptions only at the CLI error boundary
+  (chained `from e`) and at third-party API boundaries with no LBYL form.
+- `pathlib.Path` with explicit `encoding="utf-8"` on text I/O.
+- Keyword-only arguments after the first.
+- Absolute imports, no re-exports, no `__all__`.
+- No import-time side effects (`@cache` for module state).
+
+`optimized-python` (`.claude/skills/optimized-python/`) is a secondary
+reference; **dignified-python governs on conflict**.
+
+## Workflow
+
+- **Test-driven development.** New code lands tests-first (failing test,
+  then minimum code to pass). One test module per source module under
+  `tests/`.
+- **Plan-driven**: major changes get a written plan (either under
+  `~/.claude/plans/` for agent state, or in `PLAN.md` for repo-scoped
+  plans) before implementation.
+- **Empirical claims must be backed by data.** Use the workspace corpus
+  artifacts (`../docs/corpus_data/`), `../scripts/measure.py`, and the
+  `corpus_check.py codemod` subcommand when answering questions about
+  real-world tool XML.
+- **Decisions are recorded** in `docs/decisions.md` once they land
+  (mirror the parent's `docs/decisions.md` conventions: §-numbered,
+  each entry citing date and a reproduction command when relevant).
+- See `galaxy-tool-source/docs/decisions.md` §9 for the three-tier
+  rationale.
+
+## Commands
+
+Run these from the **workspace root** (`galaxy-tool-refactor/`):
+
+- `uv sync` — install dependencies
+- `uv run --package galaxy-tool-codemod pytest galaxy-tool-codemod/tests/` — run tests
+- `uv run ruff check galaxy-tool-codemod/src galaxy-tool-codemod/tests` — lint
+- `uv run mypy --config-file galaxy-tool-codemod/pyproject.toml galaxy-tool-codemod/src` — type-check (strict)
+- `uv run python -m scripts.corpus_check codemod <dotted.module>:<ClassName>` — sweep a codemod across the corpus, retain failures as fixtures
+  - e.g. `uv run python -m scripts.corpus_check codemod galaxy_tool_codemod.codemods.reorder_param_attributes:ReorderParamAttributes`
+
+## Useful workspace references
+
+- `galaxy-tool-source/README.md` — tier-1 public API
+- `galaxy-tool-source/docs/decisions.md` §3 (trivia contract), §6 (corpus
+  stats), §9 (three-tier vision)
+- `galaxy-tool-source/docs/codemod-architecture.md` — the original tier-2 design
+- `galaxy-tool-refactor-registry/src/galaxy_tool_refactor_registry/apply.py` —
+  the tier-3.6 facade that runs ``canonical_codemods()`` order (consumed by
+  ``run`` / the app's ``format``); `rulesets.py` derives the `default` ruleset from
+  per-rule ``RuleMeta.rulesets`` membership
+- `canonical.py` — the public ``canonical_codemods()`` and
+  ``AUTO_UPGRADE_CODEMODS`` pipeline contracts the registry facade consumes
+- `codemods/` — bundled codemod implementations (verb-noun module names)
+- `eligibility.py` — corpus-sweep profile-selection policy
+- `../docs/corpus_data/combined_corpus_data.json` — every swept Galaxy
+  tool, indexed for ad-hoc analysis
+- `../scripts/measure.py` — master script for empirical corpus queries

galaxy_tool_codemod-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Burhans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

galaxy_tool_codemod-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: galaxy-tool-codemod
+Version: 0.2.0
+Summary: Structural-refactor framework for Galaxy tool XML — tier 2 of the galaxy-tool-source ecosystem.
+Author: Richard Burhans
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: galaxy-tool-refactor-rules==0.2.0
+Requires-Dist: galaxy-tool-source==0.2.0
+Requires-Dist: lxml>=5
+Requires-Dist: packaging>=23
+Description-Content-Type: text/markdown
+
+# galaxy-tool-codemod
+
+A LibCST-shaped framework for structural refactors of Galaxy tool XML.
+The **structure** tier of the Galaxy refactoring architecture:
+
+| Tier | Layer | Package | Role |
+|---|---|---|---|
+| 0.5 | **rule metadata** | `galaxy-tool-refactor-rules` | shared `RuleMeta` descriptor |
+| 1 | **parsing & validation** | `galaxy-tool-source` | parse · profile-aware validate · typed view |
+| 2 | **structure** | **`galaxy-tool-codemod`** *(this repo)* | structural refactors |
+| 3 | **formatting** | `galaxy-tool-fmt` | cosmetic `black`-like formatter |
+| 3.5 | **advisory checks** | `galaxy-tool-lint` | detect-only checks |
+| 3.6 | **rule registry / rulesets** | `galaxy-tool-refactor-registry` | unified rules + rulesets (facade) |
+| 4 | **app / CLI** | `galaxy-tool-refactor-cli` | composes the tiers via the facade (`format` / `upgrade` / `check`) |
+
+## Status
+
+M1–M3.5 shipped: framework primitives (`Module`, `Cursor`,
+`CodemodCommand`), the `corpus_check.py codemod` sweep (retains failures
+as regression fixtures), and two ordered pipeline contracts run by the
+tier-4 app (`galaxy-tool-refactor-cli`):
+
+- **`canonical_codemods()`** = `FixTypos → NormalizeBooleanValues → RepairHelpRst →
+  TrimAttributeWhitespace → ReplaceOutputElement → DropRedundantParamName →
+  ReorderParamAttributes → ReorderToolAttributes → ReorderToolChildren →
+  WrapCommandCdata → WrapHelpCdata → SingleQuoteCommandVars` — the safe
+  canonical/format pipeline (the app's `format` command), **derived** from the codemods
+  declaring the `"default"` ruleset and ordered by `meta.order` (no hardcoded tuple,
+  §36). Never changes `profile=`.
+- **`AUTO_UPGRADE_CODEMODS`** = `FixTypos → NormalizeBooleanValues →
+  UpgradeToLatest` — the opt-in profile-upgrade pipeline (the app's `upgrade`
+  command).
+
+The codemods:
+
+- `FixTypos` — repair near-miss spelling typos so a
+  well-formed-but-globally-invalid tool validates (in both pipelines);
+- `NormalizeBooleanValues` — rewrite Python-style boolean attribute values
+  (`True`/`Yes`/…) to canonical `xs:boolean` so a globally-invalid tool
+  validates; schema-type-aware and behaviour-preserving (in both pipelines);
+- `UpgradeToLatest` — loop `UpdateProfile` (declare the newest profile the
+  tool validates at, bump-up-only) + single-step `upgrade_vN` codemods from
+  `upgrades.py` to bring a tool to the latest profile (`UpdateProfile` is a
+  building block run *inside* this loop, not a separate pipeline entry);
+- `ReorderParamAttributes` / `ReorderToolAttributes` — IUC `<param>` and
+  documented `<tool>` attribute order;
+- `ReorderToolChildren` — IUC `<tool>` child-element order (best-practice #52);
+  validity-safe because the `<tool>` content model is order-free (`xs:all`).
+
+Every bundled codemod carries a `RuleMeta` GTR code; `catalog.coded_codemods()` is the
+authoritative enumeration (the prose list above is illustrative — `format` also runs the
+planemo-parity fixers GTR035–037 and the partition `.1` fixers GTR018.1/019.1/020.1 and
+GTR089.1 `RepairHelpRst`). See `docs/decisions.md` §15–37.
+
+The upgrade registry is grown empirically: the `corpus_check codemod`
+sweep reports `STICKING POINT` versions still needing an `upgrade_vN`, and
+each `upgrade_vN`'s advance count. Upgrades shipped: `Upgrade24_1`
+(24.1 → 24.2), `Upgrade25_1` (25.1 → 26.0). See `docs/decisions.md` §11–14.
+
+M4 (matcher language) and M5 (Cheetah reference resolver) are not yet
+implemented — see `PLAN.md`.
+
+## Public API
+
+```python
+from pathlib import Path
+
+from galaxy_tool_codemod.parse import parse_module
+from galaxy_tool_codemod.canonical import canonical_codemods
+
+module = parse_module(Path("tool.xml"))
+for codemod_cls in canonical_codemods():
+    codemod_cls().apply(module)
+# module.document.tree now reflects the canonical structural form
+```
+
+| Symbol | Purpose |
+|---|---|
+| `parse.parse_module(source)` | Entry point — accepts `Path \| bytes \| ToolDocument`. |
+| `module.Module` | Frozen wrapper carrying `document`, `model`, `cursor`. |
+| `cursor.Cursor` | lxml-backed view with read + typed mutation primitives. |
+| `codemod.CodemodCommand` | Base for user-authored codemods (tag-PascalCase dispatch). |
+| `codemods.fix_typos.FixTypos` | Repair near-miss typos until a globally-invalid tool validates (canonical, runs first). |
+| `codemods.normalize_boolean_values.NormalizeBooleanValues` | Normalize Python-style boolean values (`True`/`Yes`/…) to `xs:boolean` until a globally-invalid tool validates (canonical, GTR017). |
+| `codemods.repair_help_rst.RepairHelpRst` | Repair deterministically-fixable invalid `<help>` reStructuredText behind a render-equivalence gate (canonical, GTR089.1; the fix half of the GTR089 partition). |
+| `upgrades.UpgradeToLatest` | In `AUTO_UPGRADE_CODEMODS`. Loop UpdateProfile + single-step upgrades to reach the latest profile. |
+| `codemods.update_profile.UpdateProfile` | Declare the newest profile the tool validates at, bump-up-only. Building block run *inside* `UpgradeToLatest` — not itself a pipeline member. |
+| `upgrades.UPGRADE_CODEMODS` | Registry: sticking version → its single-step upgrade codemod. |
+| `codemods.upgrade_24_1.Upgrade24_1` | Single-step 24.1 → 24.2 (normalize `format` / `ftype`). |
+| `codemods.upgrade_25_1.Upgrade25_1` | Single-step 25.1 → 26.0 (drop obsolete `<trackster_conf>`). |
+| `codemods.reorder_param_attributes.ReorderParamAttributes` | IUC `<param>` attribute order. |
+| `codemods.reorder_tool_attributes.ReorderToolAttributes` | Documented `<tool>` attribute prefix. |
+| `codemods.reorder_tool_children.ReorderToolChildren` | IUC `<tool>` child-element order (#52). |
+| `canonical.canonical_codemods()` | Ordered canonical/format pipeline (the app's `format` command). |
+| `canonical.AUTO_UPGRADE_CODEMODS` | Ordered opt-in upgrade pipeline (the app's `upgrade` command). |
+| `catalog.coded_codemods` | Every GTR-coded codemod, sorted by code (for the rule registry). |
+| `eligibility.corpus_test_profile` | Codemod-sweep validation-profile policy (sweep default). |
+
+## Setup
+
+From the workspace root:
+
+```sh
+uv sync
+uv run --package galaxy-tool-codemod pytest galaxy-tool-codemod/tests/
+```
+
+## Relationship to fmt and the app
+
+Neither `galaxy-tool-fmt`'s library nor its CLI depends on this
+package — fmt is cosmetic-only. Orchestration lives one tier up: the
+`galaxy-tool-refactor` app CLI (`galaxy-tool-refactor-cli`) hard-depends
+on this package and on fmt, runs `canonical_codemods()` (its `format`
+command) or `AUTO_UPGRADE_CODEMODS` (its `upgrade` command), and writes
+the result through fmt's serializer.
+
+## Coding standards
+
+Hand-written code follows **dignified-python** (vendored at
+`.claude/skills/dignified-python/`). See `CLAUDE.md`.