galaxy-linting

Persona: You are a senior Galaxy developer specializing in code quality, style enforcement, and CI compliance. Arguments: - $ARGUMENTS - Optional task specifier: "check", "fix", "python", "client", "mypy", "full" Examples: "", "check", "fix", "python", "mypy" Parse $ARGUMENTS to determine which guidance to provide. --- ## Quick Reference: Galaxy Linting & Formatting Galaxy uses multiple linting tools enforced through CI: - **Python:** ruff (lint + format), black, isort, flake8, darker (incremental formatting), mypy (type checking) - **Client:** ESLint, Prettier - **CI commands:** `tox -e lint`, `tox -e format`, `tox -e mypy`, `tox -e lint_docstring_include_list` ### Tools Overview | Tool | Purpose | Config File | Check Command | Fix Command | |------|---------|-------------|---------------|-------------| | **ruff** | Fast Python linter + formatter | `pyproject.toml` | `ruff check .` | `ruff check --fix .` | | **black** | Python code formatter | `pyproject.toml` | `black --check .` | `black .` | | **isort** | Python import sorter | `pyproject.toml` | `isort --check .` | `isort .` | | **flake8** | Python linter (legacy) | `.flake8` | `flake8 .` | N/A (manual) | | **darker** | Incremental formatter | N/A | N/A | `make diff-format` | | **autoflake** | Remove unused imports | N/A | N/A | `make remove-unused-imports` | | **pyupgrade** | Modernize Python syntax | N/A | N/A | `make pyupgrade` | | **mypy** | Type checker | `pyproject.toml` | `tox -e mypy` | N/A (manual) | | **ESLint** | JavaScript/TypeScript linter | `client/.eslintrc.js` | `make client-lint` | `make client-format` | | **Prettier** | JS/TS/CSS formatter | `client/.prettierrc.yml` | `make client-lint` | `make client-format` | --- ## If $ARGUMENTS is empty or "check": Quick Lint Check **Run the fastest feedback loop to catch most issues:** ```bash # 1. Check formatting (fast - shows what would change) tox -e format # 2. Check linting (catches style violations) tox -e lint ``` **What these check:** - **`tox -e format`**: Runs black, isort checks (no changes, just reports) - **`tox -e lint`**: Runs ruff and flake8 (reports violations) **If you see errors**, use `/galaxy-linting fix` to auto-fix, or `/galaxy-linting python` for detailed guidance. **Note:** These commands run in tox environments, which may take ~10-20 seconds to set up on first run. Subsequent runs are faster. --- ## If $ARGUMENTS is "fix": Auto-Fix Formatting Galaxy provides multiple ways to auto-fix formatting issues. ### Recommended: Incremental Formatting (Faster) **Fix only changed lines** using darker (via Makefile): ```bash # Fix formatting for uncommitted changes only make diff-format ``` **What it does:** - Runs black and isort only on lines you modified - Compares against `origin/dev` branch - Much faster than formatting entire codebase - Recommended for daily development ### Full Formatting (Comprehensive) **Format entire codebase:** ```bash # Format all Python files make format ``` **What it does:** - Runs black on all Python files - Runs isort on all Python imports - Takes longer but ensures full compliance - Recommended before final commit ### Specific Fixes **Fix ruff auto-fixable issues:** ```bash ruff check --fix . ``` **Remove unused imports:** ```bash make remove-unused-imports ``` **Modernize Python syntax (pyupgrade):** ```bash make pyupgrade ``` Converts old-style Python patterns to Python 3.8/3.9 idioms (e.g., `typing.List` → `list`, adds walrus operators where appropriate). Skips vendored/generated paths. **Fix client-side formatting:** ```bash make client-format ``` ### Workflow Recommendation ```bash # During development (fast): make diff-format # Before committing (thorough): make format tox -e lint # Verify no remaining issues ``` --- ## If $ARGUMENTS is "python": Python Linting Details Galaxy's Python linting stack consists of multiple tools, each with a specific purpose. ### Ruff (Primary Linter) **Fast, modern Python linter** that replaces many tools. **Check for issues:** ```bash ruff check . ``` **Auto-fix issues:** ```bash ruff check --fix . ``` **Configuration:** `pyproject.toml` under `[tool.ruff]` and `[tool.ruff.lint]` **Key rule categories:** - **F**: Pyflakes errors (undefined names, unused imports) - **E, W**: PEP 8 style violations - **I**: Import sorting (isort-compatible) - **N**: Naming conventions - **UP**: Modernization (e.g., use `list[int]` instead of `List[int]`) - **B**: Bugbear (likely bugs) - **A**: Avoid shadowing builtins **Common errors and fixes:** - `F401` - Unused import → Remove import or use `# noqa: F401` - `F841` - Unused variable → Remove or rename to `_` - `E501` - Line too long (>120 chars) → Break into multiple lines - `UP` - Use modern syntax → Let ruff auto-fix with `--fix` ### Black (Code Formatter) **Opinionated code formatter** - ensures consistent style. **Check what would change:** ```bash black --check . ``` **Format files:** ```bash black . ``` **Configuration:** `pyproject.toml` under `[tool.black]` - Line length: 120 characters - Target version: Python 3.9+ **Common scenarios:** - **"black would reformat"** error in CI → Run `black .` locally - String formatting → Black enforces double quotes - Multiline expressions → Black has strong opinions on line breaks ### isort (Import Sorter) **Sorts and organizes imports** into groups. **Check import order:** ```bash isort --check . ``` **Fix import order:** ```bash isort . ``` **Configuration:** `pyproject.toml` under `[tool.isort]` - Profile: "black" (compatible with black formatting) - Line length: 120 **Import groups (in order):** 1. Standard library imports 2. Third-party imports 3. Local application imports **Example:** ```python # Standard library import os from typing import Optional # Third-party from fastapi import APIRouter from pydantic import BaseModel # Local from galaxy.managers.workflows import WorkflowsManager from galaxy.schema.schema import WorkflowSummary ``` ### Flake8 (Legacy Linter) **Traditional Python linter** - still used alongside ruff. **Run flake8:** ```bash flake8 . ``` **Configuration:** `.flake8` file in repository root **Note:** Ruff covers most flake8 checks. Galaxy maintains flake8 for specific rules not yet in ruff. ### Darker (Incremental Formatter) **Applies black/isort only to changed lines.** **Format changed code:** ```bash make diff-format ``` **How it works:** - Compares working tree to `origin/dev` - Runs black and isort only on modified lines - Much faster than full formatting - Ideal for daily development **Use when:** - Working on large files with many unchanged lines - Want fast formatting feedback - Developing features incrementally ### CI Integration **GitHub Actions runs these checks:** - `.github/workflows/lint.yaml` defines CI linting pipeline - Four tox environments: `format`, `lint`, `mypy`, `lint_docstring_include_list` **To match CI locally:** ```bash tox -e format # Check formatting tox -e lint # Check linting ``` ### Configuration Files **Python linting configuration:** - `pyproject.toml` - ruff, black, isort, mypy config - `.flake8` - flake8 rules and exclusions - `tox.ini` - tox environment definitions **Read these files** to understand specific rules: ```bash # View ruff config grep -A 20 '\[tool.ruff\]' pyproject.toml # View black config grep -A 10 '\[tool.black\]' pyproject.toml # View flake8 config cat .flake8 ``` --- ## If $ARGUMENTS is "client": Client-Side Linting Galaxy's client-side code (Vue.js, TypeScript) uses ESLint and Prettier. ### Prerequisites **Ensure Node.js dependencies are installed:** ```bash make client-node-deps ``` This installs ESLint, Prettier, and related packages in `client/node_modules/`. ### ESLint (JavaScript/TypeScript Linter) **Check for linting issues:** ```bash make client-lint ``` **Configuration:** `client/.eslintrc.js` **Rules enforced:** - Vue.js best practices - TypeScript type safety - Unused variables - Console statements (warnings) - Naming conventions **Common issues:** - Unused variables → Remove or prefix with `_` - Missing types → Add TypeScript type annotations - Vue template issues → Check component syntax - Console.log statements → Remove or justify with comments ### Prettier (Code Formatter) **Format client code:** ```bash make client-format ``` **Configuration:** `client/.prettierrc.yml` **Formats:** - JavaScript/TypeScript files - Vue single-file components - CSS/SCSS files - JSON files **Integration with ESLint:** - Prettier handles formatting (indentation, quotes, line breaks) - ESLint handles code quality (unused vars, type safety) - ESLint config includes `prettier` plugin to avoid conflicts ### Granular Makefile Targets Galaxy's Makefile provides fine-grained control over client linting: **Run only ESLint (no Prettier check):** ```bash make client-eslint ``` **Run only Prettier check (no ESLint):** ```bash make client-format-check ``` **Auto-fix ESLint errors with --fix (no Prettier):** ```bash make client-lint-autofix ``` **Pre-commit hook linting (for specific file paths):** ```bash make client-eslint-precommit ``` This is used by Git hooks and operates on specific file paths rather than glob patterns. **Important distinctions:** - `make client-lint` = `make client-eslint` + `make client-format-check` (runs both tools) - `make client-format` = `make client-lint-autofix` + Prettier write (auto-fixes everything) ### Manual Commands **Run ESLint directly:** ```bash cd client npm run eslint ``` **Run Prettier directly:** ```bash cd client npm run prettier:check # Check npm run prettier:write # Fix ``` ### Client Lint Workflow ```bash # 1. Install dependencies (if needed) make client-node-deps # 2. Check for issues make client-lint # 3. Auto-fix formatting make client-format # 4. Manually fix remaining ESLint issues # (Edit files based on lint output) # 5. Verify fixed make client-lint ``` --- ## If $ARGUMENTS is "mypy": Type Checking Galaxy uses **mypy** for static type checking with strict mode enabled. ### Running Type Checks **Check types across codebase:** ```bash tox -e mypy ``` **Check specific file or directory:** ```bash mypy lib/galaxy/managers/workflows.py mypy lib/galaxy/schema/ ``` **Configuration:** `pyproject.toml` under `[tool.mypy]` **Strict mode enabled:** - `disallow_untyped_defs` - All functions must have type hints - `disallow_any_generics` - Must specify generic types (e.g., `List[str]` not `List`) - `warn_return_any` - Warn on returning `Any` - `warn_unused_ignores` - Warn on unnecessary `# type: ignore` comments ### Common Type Errors