gh-formatter 0.1.0__tar.gz

gh_formatter-0.1.0/.gh-formatter.yml

@@ -0,0 +1,229 @@
+# Comprehensive Configuration for gh-formatter
+# =============================================
+# This file controls all formatting options for GitHub Actions and Workflows.
+# All settings shown below are optional and use the defaults listed.
+
+# INDENTATION SETTINGS
+# ====================
+
+# Number of spaces to use for general indentation (default: 2)
+# Recommended values: 2 or 4
+indent: 2
+
+# Number of spaces to indent sequence (list) item content (default: 4)
+# Must be greater than sequence_offset.
+sequence_indent: 4
+
+# Indentation of the dash in sequence items (default: 2)
+# Controls how far the `-` is indented relative to its parent key.
+# Example with sequence_offset: 2 (default), sequence_indent: 4:
+#   steps:
+#     - name: item1
+#     - name: item2
+# Example with sequence_offset: 0, sequence_indent: 2:
+#   steps:
+#   - name: item1
+#   - name: item2
+sequence_offset: 2
+
+
+# NAMING CONVENTIONS
+# ==================
+
+# Casing convention for input names in actions and workflows
+# Options: "dash-case" or "snake_case"
+# Examples:
+#   dash-case:  my-input, debug-mode, run-tests
+#   snake_case: my_input, debug_mode, run_tests
+# Default: "dash-case"
+input_casing: "dash-case"
+
+# Casing convention for job names in workflows
+# Options: "snake_case" or "dash-case"
+# Examples:
+#   snake_case: build_job, run_tests, deploy_app
+#   dash-case:  build-job, run-tests, deploy-app
+# Default: "snake_case"
+job_casing: "snake_case"
+
+# How to treat env-var style names (SERVER_IMAGE, MM_ENV) when renaming
+# inputs and jobs:
+#   false (default): renamed to the configured casing like any other name
+#   true:            kept uppercase, separators normalized to underscores
+#                    (SERVER-IMAGE becomes SERVER_IMAGE)
+preserve_uppercase_names: false
+
+# Line endings for formatted files
+# Options: "preserve" (keep each file's existing endings) or "lf" (Unix)
+# Default: "preserve"
+line_endings: "preserve"
+
+
+# QUOTE STYLE
+# ===========
+
+# Quote character to enforce on already-quoted scalars.
+# Options: "double", "single", or "preserve"
+#   double:   normalize every quoted scalar to "..."  (default)
+#   single:   normalize every quoted scalar to '...'
+#   preserve: leave each scalar's existing quoting untouched
+# Plain (unquoted) values are never force-quoted, and ruamel falls back
+# to double quoting when a value cannot be single-quoted safely.
+quote_style: "double"
+
+
+# YAMLLINT INTEROP
+# ================
+
+# Make a yamllint config the source of truth for indentation so a format
+# never produces output yamllint would reject. Requires yamllint installed.
+# Options:
+#   false (default): ignore yamllint, use the indentation settings above
+#   true:            discover .yamllint(.yml/.yaml) in the working directory
+#   <path>:          read indentation from that explicit yamllint config
+# When enabled, the derived indent/sequence settings override the ones above.
+defer_to_yamllint: false
+
+
+# CALLER INPUTS
+# =============
+
+# How to handle a caller's with: keys that don't match a LOCAL reusable
+# workflow/action's declared inputs (uses: ./...). Marketplace actions are
+# never checked.
+# Options:
+#   "error" (default): report the mismatch as an error and fail the run
+#   "fix":             rename the caller's keys to match (at your own risk)
+#   "ignore":          leave caller inputs alone
+caller_inputs: "error"
+
+
+# ALPHABETICAL SORTING
+# ====================
+
+# Mapping blocks whose entries are sorted alphabetically (case-insensitive).
+# Entry order in these blocks never carries meaning, so sorting them makes
+# diffs and reviews predictable. Set to [] to disable sorting entirely, or
+# add further block names (e.g. "permissions").
+alphabetize:
+  - env
+  - inputs
+  - outputs
+  - secrets
+  - with
+
+
+# LIST FORMATTING STYLE
+# =====================
+
+# How to format trigger filter lists under `on:` (branches, tags, paths, ...)
+# Options: "flow" or "block"
+# flow:  [item1, item2, item3]
+# block: - item1
+#        - item2
+#        - item3
+# Default: "block"
+list_style: "block"
+
+# Which keys under `on:` are treated as filter lists. Single string values
+# are promoted to lists and the configured list_style is applied.
+# Default shown below.
+list_keys:
+  - branches
+  - branches-ignore
+  - tags
+  - tags-ignore
+  - paths
+  - paths-ignore
+  - types
+  - workflows
+
+
+# BLANK LINES
+# ===========
+
+# Insert a blank line between consecutive steps (default: true)
+blank_line_between_steps: true
+
+# Insert a blank line between job definitions (default: true)
+blank_line_between_jobs: true
+
+
+# RULE TOGGLES
+# ============
+
+# Disable individual rules or post-processors by id.
+# Run `gh-formatter --list-rules` to see all available ids.
+# All rules are enabled by default.
+rules: {}
+# Example:
+# rules:
+#   capitalize-names: false
+#   blank-lines: false
+
+
+# KEY ORDERING
+# ============
+
+# Order of keys for GitHub Actions workflow files (.github/workflows/*.yml)
+# Keys not listed here will be placed at the end in alphabetical order
+# Default order shown below (recommended for readability)
+key_order_workflow:
+  - name
+  - run-name
+  - "on"  # quoted so YAML 1.1 linters don't read it as the boolean true
+  - concurrency
+  - permissions
+  - env
+  - defaults
+  - jobs
+
+# Order of keys for GitHub Actions definition files (action.yml / action.yaml)
+# Keys not listed here will be placed at the end in alphabetical order
+# Default order shown below (recommended for readability)
+key_order_action:
+  - name
+  - description
+  - author
+  - inputs
+  - outputs
+  - runs
+  - branding
+
+# Order of keys inside each job definition
+# Default order shown below
+key_order_job:
+  - name
+  - if
+  - needs
+  - runs-on
+  - env
+  - uses
+  - with
+  - secrets
+  - permissions
+  - environment
+  - concurrency
+  - strategy
+  - container
+  - services
+  - outputs
+  - defaults
+  - timeout-minutes
+  - continue-on-error
+  - steps
+
+# Order of keys inside each step
+# Default order shown below
+key_order_step:
+  - name
+  - id
+  - if
+  - env
+  - uses
+  - continue-on-error
+  - run
+  - with
+  - working-directory
+  - shell
+  - timeout-minutes

gh_formatter-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Code owners for gh-formatter
+#
+# The owner(s) listed here are automatically requested for review on every PR
+# and — combined with the "Require review from Code Owners" branch ruleset —
+# are the ONLY accounts whose approval can satisfy the required review.
+#
+# Keep this list to the repository admin(s) only. Anyone added here who also
+# has Write access can approve & merge, so do not add external contributors.
+
+* @nimpsch

gh_formatter-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,91 @@
+name: Bug report
+description: Report incorrect or unexpected formatting behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+- type: markdown
+  attributes:
+    value: |
+      Thanks for taking the time to report a bug! A minimal reproduction
+      makes fixing it dramatically faster.
+
+- type: textarea
+  id: what-happened
+  attributes:
+    label: What happened?
+    description: A clear description of the bug.
+    placeholder: gh-formatter changed X into Y, but it should have ...
+  validations:
+    required: true
+
+- type: textarea
+  id: input-yaml
+  attributes:
+    label: Input YAML
+    description: >
+      The smallest workflow/action snippet that reproduces the problem.
+      This will be rendered as YAML, no backticks needed.
+    render: yaml
+    placeholder: |
+      name: ci
+      on: push
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+  validations:
+    required: true
+
+- type: textarea
+  id: command
+  attributes:
+    label: Command
+    description: The exact command you ran.
+    render: shell
+    placeholder: gh-formatter .github/workflows/ci.yml
+  validations:
+    required: true
+
+- type: textarea
+  id: expected
+  attributes:
+    label: Expected output
+    description: What you expected gh-formatter to produce.
+    render: yaml
+  validations:
+    required: true
+
+- type: textarea
+  id: actual
+  attributes:
+    label: Actual output
+    description: What gh-formatter actually produced.
+    render: yaml
+  validations:
+    required: true
+
+- type: textarea
+  id: config
+  attributes:
+    label: Configuration
+    description: >
+      Your `.gh-formatter.yml` / `[tool.gh-formatter]` config, if any.
+    render: yaml
+  validations:
+    required: false
+
+- type: input
+  id: version
+  attributes:
+    label: gh-formatter version
+    description: Output of `pip show gh-formatter` (the Version line).
+    placeholder: 0.1.0
+  validations:
+    required: true
+
+- type: input
+  id: python-version
+  attributes:
+    label: Python version
+    placeholder: "3.12"
+  validations:
+    required: true

gh_formatter-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,7 @@
+blank_issues_enabled: false
+contact_links:
+- name: Question or discussion
+  url: https://github.com/nimpsch/gh-formatter/discussions
+  about: >
+    Ask a question or discuss an idea. For bugs and concrete feature
+    requests, please use the issue templates instead.

gh_formatter-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,50 @@
+name: Feature request
+description: Suggest a new rule, option, or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+- type: markdown
+  attributes:
+    value: |
+      Thanks for suggesting an improvement! Please describe the problem you
+      are trying to solve, not only the solution you have in mind.
+
+- type: textarea
+  id: problem
+  attributes:
+    label: Problem / motivation
+    description: What are you trying to achieve? What is painful today?
+    placeholder: >
+      When formatting reusable workflows, I want ... because ...
+  validations:
+    required: true
+
+- type: textarea
+  id: proposal
+  attributes:
+    label: Proposed solution
+    description: >
+      How might this work? If it is a new formatting rule or option,
+      show a before/after example.
+    render: yaml
+  validations:
+    required: true
+
+- type: textarea
+  id: alternatives
+  attributes:
+    label: Alternatives considered
+    description: Other approaches you thought about, and why you ruled them out.
+  validations:
+    required: false
+
+- type: dropdown
+  id: contribute
+  attributes:
+    label: Would you be willing to contribute this?
+    options:
+    - "Yes, I'd like to open a PR"
+    - "Maybe, with some guidance"
+    - "No, just suggesting"
+  validations:
+    required: false

gh_formatter-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+<!--
+Thanks for contributing! Please keep PRs focused on one logical change.
+The title becomes the squashed commit subject — make it descriptive and
+write it in the imperative ("Add ...", "Fix ...").
+-->
+
+## What does this PR do?
+
+<!-- A short description of the change. -->
+
+## Why?
+
+<!-- The motivation / the problem this solves. Link the issue if there is one. -->
+
+Fixes #
+
+## How was it tested?
+
+<!--
+Describe the tests you added and/or the manual verification you did.
+For formatting changes, a before/after YAML example is very helpful.
+-->
+
+## Checklist
+
+<!--
+No need to tick off formatting, linting, type-checking, or test runs:
+CI runs black, ruff, mypy, pytest, and yamllint (via pre-commit) on every PR.
+-->
+
+- [ ] Tests added or updated (bug fixes include a regression test)
+- [ ] Docs updated (README / `.gh-formatter.yml`) if behavior or options changed
+- [ ] This PR is one focused change

gh_formatter-0.1.0/.github/dependabot.yml

@@ -0,0 +1,36 @@
+version: 2
+updates:
+  # Python packages declared in pyproject.toml.
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    # Bump the declared requirement itself (not just a lockfile) so update
+    # PRs are still raised for ">=" requirements. Note: for a package that
+    # is published to PyPI, Dependabot treats it as a library and may leave
+    # an unbounded ">=" requirement alone when the newest release already
+    # satisfies it -- add an upper bound (e.g. ">=1,<2") if you want those.
+    versioning-strategy: increase
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  # Bumps the `rev:` of each hook in .pre-commit-config.yaml.
+  - package-ecosystem: pre-commit
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      pre-commit:
+        patterns:
+          - "*"

gh_formatter-0.1.0/.github/rulesets/README.md

@@ -0,0 +1,50 @@
+# Repository rulesets
+
+These JSON files are importable [repository rulesets](https://docs.github.com/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/managing-rulesets-for-a-repository).
+They are kept in the repo for version control; GitHub does **not** apply them
+automatically — you must import them once (and re-import after edits).
+
+## How to import
+
+1. Go to **Settings → Rules → Rulesets** in the repository.
+2. Click **New ruleset → Import a ruleset**.
+3. Select the JSON file and click **Create**.
+4. Repeat for each file.
+
+## Files
+
+| File | What it does |
+| ---- | ------------ |
+| `main-branch-protection.json` | Protects the default branch: requires a PR with 1 Code Owner approval, passing CI, linear history, blocks force-push and deletion. |
+| `branch-naming.json` | Enforces a naming convention on all non-default branches pushed to this repo. |
+
+## Who can approve & merge
+
+- **Approve:** Only accounts in [`.github/CODEOWNERS`](../CODEOWNERS) that also have
+  Write+ access satisfy the required review. Today that is only `@nimpsch`.
+  External contributors fork the repo and have read-only access, so their reviews
+  are non-binding.
+- **Merge:** Only accounts with Write+ access can click merge. On a public repo,
+  forkers never have write, so they can never merge. Keep yourself the sole
+  admin/collaborator and you remain the only person who can merge.
+
+The default-branch ruleset lists **Repository admin (`actor_id: 5`)** as a bypass
+actor so you can merge your own PRs (a PR author cannot approve their own PR).
+Remove the `bypass_actors` entry if you want the review requirement to apply to
+you as well.
+
+## Branch naming convention
+
+Non-default branches must match:
+
+```
+^(feature|fix|hotfix|chore|docs|refactor|test|ci|build|perf|release|dependabot)/[a-z0-9._/-]+$
+```
+
+Examples that pass: `feature/yaml-anchors`, `fix/issue-42`, `docs/readme-badges`,
+`dependabot/pip/black-25.1.0`.
+
+> **Note:** Branch-name rules apply only to branches created in *this* repo.
+> A fork is a separate repository, so this rule cannot constrain the head-branch
+> name of a PR opened from someone else's fork — it governs your own branches and
+> any direct collaborators.

gh_formatter-0.1.0/.github/workflows/build_and_test.yml

@@ -0,0 +1,82 @@
+name: Build and Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+  lint:
+    name: Lint and type-check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      # gh-formatter must be importable for its (system) pre-commit hook;
+      # pre-commit manages the envs for black, ruff, mypy, and yamllint.
+      - name: Install package and pre-commit
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" pre-commit
+
+      # Single entry point: black, ruff, mypy, the gh-formatter self-check,
+      # and yamllint all run through pre-commit (see .pre-commit-config.yaml).
+      - name: Run pre-commit
+        run: pre-commit run --all-files --show-diff-on-failure
+
+  build:
+    name: Verify package builds
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*

gh_formatter-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    name: Run linting and tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Check formatting
+        run: gh-formatter --check .
+
+      - name: Run tests
+        run: pytest
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(python -c "import re, pathlib; print(re.search(r'__version__ = \"(.+?)\"', pathlib.Path('src/gh_formatter/__init__.py').read_text()).group(1))")"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match package version ($PKG_VERSION)" >&2
+            exit 1
+          fi
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:  # Required for PyPI Trusted Publishing (OIDC)
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gh-formatter
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github_release:
+    name: Create GitHub release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release with artifacts
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true