confkit 2.1.1__tar.gz → 3.0.0__tar.gz

confkit-3.0.0/.github/actions/setup/action.yml

@@ -0,0 +1,34 @@
+name: Set up uv and the project
+description: Install uv and a Python version, then sync the locked dependency groups.
+
+inputs:
+  python-version:
+    description: Python version to install.
+    default: "3.13"
+  sync-args:
+    description: Extra arguments for `uv sync`, such as `--group dev`.
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+
+    - name: Set up Python ${{ inputs.python-version }}
+      shell: bash
+      run: uv python install ${{ inputs.python-version }}
+
+    - name: Install dependencies
+      shell: bash
+      run: uv sync --locked --python ${{ inputs.python-version }} ${{ inputs.sync-args }}
+
+    # Without these, a later `uv run` follows .python-version back to 3.11
+    # and re-syncs only the default groups, dropping the ones synced above.
+    - name: Keep later uv commands on this environment
+      shell: bash
+      run: |
+        echo "UV_PYTHON=${{ inputs.python-version }}" >> "$GITHUB_ENV"
+        echo "UV_NO_SYNC=1" >> "$GITHUB_ENV"

confkit-3.0.0/.github/ci-filters.yml

@@ -0,0 +1,51 @@
+# Inputs for each check that ci.yml runs. A check only runs when one of its
+# inputs changed. Editing CI itself reruns every check.
+ci: &ci
+  - .github/workflows/ci.yml
+  - .github/ci-filters.yml
+  - .github/actions/setup/**
+deps: &deps
+  - pyproject.toml
+  - uv.lock
+
+test:
+  - *ci
+  - *deps
+  - .github/workflows/test.yml
+  - src/**
+  - tests/**
+
+lint:
+  - *ci
+  - *deps
+  - .github/workflows/lint.yml
+  - ruff.toml
+  - src/**
+  - tests/**
+  - examples/**
+
+lint-public:
+  - *ci
+  - *deps
+  - .github/workflows/lint.yml
+  - ruff.toml
+  - src/**
+  - examples/**
+
+coverage:
+  - *ci
+  - *deps
+  - .github/workflows/coverage.yml
+  - src/**
+  - tests/**
+  - examples/**
+
+docs:
+  - *ci
+  - *deps
+  - .github/workflows/docs.yml
+  - .github/workflows/docs-publish.yml
+  - zensical.toml
+  - mkdocs.yml
+  - src/**
+  - docs/**

confkit-3.0.0/.github/workflows/bump-version-by-labels.yml

@@ -0,0 +1,32 @@
+name: Bump Version By Labels
+
+# Called from ci.yml once all-checks passes on a push to master. The action
+# looks up the merged PR for the pushed commit and opens a bump PR from its
+# Major, Minor or Patch label. Merging the bump PR runs CI again, and that
+# run's release job publishes the new version.
+on:
+  workflow_call:
+
+jobs:
+  bump-version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      # v4.1.0 is the first release that reads labels on push events.
+      - name: Bump by labels
+        uses: HEROgold/bump-by-label@v4.1.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          command: "uv version --bump"
+          validate: "uv version"
+          base_branch: master

confkit-3.0.0/.github/workflows/ci.yml

@@ -0,0 +1,147 @@
+name: CI
+
+# One entry point for every check. The changes job compares the push or PR
+# against .github/ci-filters.yml, and each check only runs when its inputs
+# changed. On pushes to master the chain continues once all-checks passes.
+# Bump opens a version bump PR, then release tags and publishes any version
+# that has no tag yet. Coverage stays outside the chain.
+#
+# The master ruleset requires none of these checks. To require them, require
+# the all-checks job only. A called workflow's check names change with whether
+# it ran ("test / test (3.13)") or was skipped ("test"), so neither name works
+# as a required check on its own.
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+    # closed only removes the docs preview.
+    types: [opened, synchronize, reopened, closed]
+  workflow_dispatch:
+
+# A newer push to a PR cancels its older run. Pushes to master each get their
+# own group, because GitHub keeps only one pending run per group and would
+# drop a merge's run, along with its version bump.
+concurrency:
+  group: ${{ github.event_name == 'push' && github.run_id || format('ci-{0}', github.ref) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  changes:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      # A manual run checks everything.
+      test: ${{ github.event_name == 'workflow_dispatch' || steps.filter.outputs.test == 'true' }}
+      lint: ${{ github.event_name == 'workflow_dispatch' || steps.filter.outputs.lint == 'true' }}
+      lint-public: ${{ github.event_name == 'workflow_dispatch' || steps.filter.outputs.lint-public == 'true' }}
+      coverage: ${{ github.event_name == 'workflow_dispatch' || steps.filter.outputs.coverage == 'true' }}
+      docs: ${{ github.event_name == 'workflow_dispatch' || steps.filter.outputs.docs == 'true' }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: dorny/paths-filter@v3
+        id: filter
+        if: github.event_name != 'workflow_dispatch'
+        with:
+          filters: .github/ci-filters.yml
+
+  test:
+    needs: changes
+    if: needs.changes.outputs.test == 'true'
+    uses: ./.github/workflows/test.yml
+
+  lint:
+    needs: changes
+    if: needs.changes.outputs.lint == 'true'
+    uses: ./.github/workflows/lint.yml
+    with:
+      cache-prefix: lint
+      tools: >-
+        [
+          {"tool": "ruff", "args": "check ."},
+          {"tool": "ty", "args": "check . --ignore no-matching-overload"},
+          {"tool": "undersort", "args": ". --check"}
+        ]
+
+  lint-public:
+    needs: changes
+    if: needs.changes.outputs.lint-public == 'true'
+    uses: ./.github/workflows/lint.yml
+    with:
+      cache-prefix: lint-public
+      tools: >-
+        [
+          {"tool": "ruff", "args": "check ./examples"},
+          {"tool": "ty", "args": "check ./examples --ignore no-matching-overload"},
+          {"tool": "pyrefly", "args": "check ./examples"},
+          {"tool": "zuban", "args": "check ./examples"},
+          {"tool": "mypy", "args": "./examples"},
+          {"tool": "pyright", "args": "./examples"}
+        ]
+
+  gitleaks:
+    if: github.event.action != 'closed'
+    uses: ./.github/workflows/gitleaks.yml
+
+  docs:
+    needs: changes
+    if: needs.changes.outputs.docs == 'true'
+    uses: ./.github/workflows/docs.yml
+
+  # Not a check, so all-checks doesn't wait on it. Each PR and master get their
+  # own group. A newer run waiting in the group replaces an older waiting one,
+  # so the newest docs always win.
+  docs-publish:
+    needs: docs
+    # Always runs on closed, so the preview gets removed even when no docs input changed.
+    if: always() && (github.event.action == 'closed' || needs.docs.result == 'success')
+    concurrency:
+      group: gh-pages-${{ github.event.pull_request.number || 'master' }}
+    uses: ./.github/workflows/docs-publish.yml
+    permissions:
+      contents: write
+      pull-requests: write
+
+  coverage:
+    needs: changes
+    if: github.event_name == 'push' && needs.changes.outputs.coverage == 'true'
+    uses: ./.github/workflows/coverage.yml
+    secrets:
+      COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+
+  # Passes when every check passed or was skipped because its inputs didn't
+  # change. Coverage is informational, so it isn't listed.
+  all-checks:
+    if: always() && github.event.action != 'closed'
+    needs: [changes, test, lint, lint-public, gitleaks, docs]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail if a check failed or was cancelled
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1
+
+  # always() is needed even though all-checks passed. Without it, GitHub's
+  # implicit success() also looks at the checks all-checks needs, and skips
+  # this job whenever one of them was skipped.
+  bump:
+    needs: all-checks
+    if: always() && github.event_name == 'push' && needs.all-checks.result == 'success'
+    uses: ./.github/workflows/bump-version-by-labels.yml
+    permissions:
+      contents: write
+      pull-requests: write
+
+  release:
+    needs: bump
+    if: always() && needs.bump.result == 'success'
+    uses: ./.github/workflows/release.yml
+    permissions:
+      contents: write
+    secrets: inherit

confkit-3.0.0/.github/workflows/coverage.yml

@@ -0,0 +1,55 @@
+name: Coverage
+
+# Called from ci.yml on pushes to master. Informational, so nothing waits on it.
+on:
+  workflow_call:
+    secrets:
+      COVERALLS_REPO_TOKEN:
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  coveralls-upload:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # A hit means coverage for these exact inputs is already on Coveralls.
+      - name: Cache coverage result
+        id: cache-coverage
+        uses: actions/cache@v4
+        with:
+          path: .coverage_cache
+          key: ${{ runner.os }}-coverage-${{ hashFiles('src/**', 'tests/**', 'examples/**', 'pyproject.toml', 'uv.lock', '.github/workflows/coverage.yml', '.github/actions/setup/**') }}
+
+      - name: Set up the project
+        if: steps.cache-coverage.outputs.cache-hit != 'true'
+        uses: ./.github/actions/setup
+        with:
+          sync-args: --group dev
+
+      - name: Run tests with coverage
+        if: steps.cache-coverage.outputs.cache-hit != 'true'
+        run: uv run coverage run --source=. -m pytest tests/
+
+      - name: Upload coverage data to coveralls.io
+        if: steps.cache-coverage.outputs.cache-hit != 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+          COVERALLS_SERVICE_NAME: github-actions
+          COVERALLS_PARALLEL: true
+        run: uvx coveralls --service=github
+
+      - name: Coveralls Finished
+        if: steps.cache-coverage.outputs.cache-hit != 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
+        run: uvx coveralls --finish
+
+      - name: Record the upload
+        if: steps.cache-coverage.outputs.cache-hit != 'true'
+        run: mkdir -p .coverage_cache && touch .coverage_cache/done

confkit-3.0.0/.github/workflows/docs-publish.yml

@@ -0,0 +1,81 @@
+name: Publish documentation
+
+# Called from ci.yml after the docs build. Pages serves the gh-pages branch.
+# Master publishes to its root, and each PR from this repo gets a preview under
+# pr-previews/pr-<n>/. Fork PRs get no preview, because their token can't push
+# to gh-pages. Both actions fetch and rebase when another run pushed first.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  preview:
+    if: >-
+      github.event_name == 'pull_request'
+      && github.event.action != 'closed'
+      && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: site
+          path: site
+
+      - name: Deploy the PR preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: site
+          preview-branch: gh-pages
+          umbrella-dir: pr-previews
+          action: deploy
+
+  remove-preview:
+    if: >-
+      github.event_name == 'pull_request'
+      && github.event.action == 'closed'
+      && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Remove the PR preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          preview-branch: gh-pages
+          umbrella-dir: pr-previews
+          action: remove
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: site
+          path: site
+
+      # Only the root needs .nojekyll. In a preview it would outlive the
+      # preview's removal, which skips hidden files.
+      - name: Keep Pages from running Jekyll
+        run: touch site/.nojekyll
+
+      - name: Publish to the gh-pages root
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: site
+          branch: gh-pages
+          clean-exclude: pr-previews

confkit-3.0.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Documentation
+
+# Called from ci.yml. Builds the site and uploads it as the "site" artifact.
+# docs-publish.yml publishes it, so a cancelled publish never fails this check.
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # A hit means the site for these exact inputs is already built.
+      - name: Cache the built site
+        id: cache-site
+        uses: actions/cache@v4
+        with:
+          path: site
+          key: ${{ runner.os }}-site-${{ hashFiles('src/**', 'docs/**', 'zensical.toml', 'mkdocs.yml', 'pyproject.toml', 'uv.lock', '.github/workflows/docs.yml', '.github/actions/setup/**') }}
+
+      - name: Set up the project
+        if: steps.cache-site.outputs.cache-hit != 'true'
+        uses: ./.github/actions/setup
+        with:
+          sync-args: --group docs
+
+      - name: Build the site
+        if: steps.cache-site.outputs.cache-hit != 'true'
+        run: |
+          uv run pdoc confkit -o docs/api
+          uv run zensical build --clean
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: site
+

{confkit-2.1.1 → confkit-3.0.0}/.github/workflows/gitleaks.yml

@@ -1,14 +1,10 @@
 name: Gitleaks
 
+# Called from ci.yml on every push and PR, with no path filter, because a
+# leaked secret can land in any file.
 on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-  workflow_dispatch:
   workflow_call:
-
-concurrency: gitleaks-${{ github.ref }}
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -18,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 

confkit-3.0.0/.github/workflows/lint.yml

@@ -0,0 +1,52 @@
+name: Lint
+
+# Called from ci.yml twice: once for the package and once for the public API
+# as the examples use it.
+on:
+  workflow_call:
+    inputs:
+      cache-prefix:
+        description: Cache key prefix that keeps the two callers apart.
+        required: true
+        type: string
+      tools:
+        description: JSON list of {"tool", "args"} objects, one matrix entry each.
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(inputs.tools) }}
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # The lint group in uv.lock pins every tool, so a tool upgrade changes
+      # the key. A hit means this tool already passed on these exact inputs.
+      - name: Cache lint result
+        id: cache-lint
+        uses: actions/cache@v4
+        with:
+          path: .lint_cache
+          key: ${{ runner.os }}-${{ inputs.cache-prefix }}-${{ matrix.tool }}-${{ hashFiles('src/**', 'tests/**', 'examples/**', 'pyproject.toml', 'uv.lock', 'ruff.toml', '.github/workflows/ci.yml', '.github/workflows/lint.yml', '.github/actions/setup/**') }}
+
+      - name: Set up the project
+        if: steps.cache-lint.outputs.cache-hit != 'true'
+        uses: ./.github/actions/setup
+        with:
+          sync-args: --group dev --group lint
+
+      - name: Run ${{ matrix.tool }}
+        if: steps.cache-lint.outputs.cache-hit != 'true'
+        run: uv run ${{ matrix.tool }} ${{ matrix.args }}
+
+      - name: Record the pass
+        if: steps.cache-lint.outputs.cache-hit != 'true'
+        run: mkdir -p .lint_cache && touch ".lint_cache/${{ matrix.tool }}"

{confkit-2.1.1 → confkit-3.0.0}/.github/workflows/pypi.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v4
+      uses: actions/checkout@v7
       with:
         persist-credentials: false
     

{confkit-2.1.1 → confkit-3.0.0}/.github/workflows/release.yml

@@ -1,11 +1,9 @@
 name: Auto-release
 
+# Called from ci.yml after the version bump, on pushes to master. A push
+# that merged a bump PR has an untagged version, so this run releases it.
 on:
-  workflow_run:
-    workflows: ["Test"]
-    branches: [master]
-    types:
-      - completed
+  workflow_call:
   workflow_dispatch:
 
 jobs:
@@ -13,12 +11,11 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
-    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
     outputs:
       version_changed: ${{ steps.version-check.outputs.version_changed }}
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0  # Needed to get all tags for version comparison
 
@@ -28,9 +25,7 @@ jobs:
         python-version: "3.*"
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v4
-      with:
-        version: "latest"
+      uses: astral-sh/setup-uv@v7
 
     - name: Check if version changed
       id: version-check

{confkit-2.1.1 → confkit-3.0.0}/.github/workflows/test.yml

@@ -1,14 +1,9 @@
 name: Test
 
+# Called from ci.yml, which decides whether the inputs below changed.
 on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-  workflow_dispatch:
   workflow_call:
-
-concurrency: test-${{ github.sha }}
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -18,32 +13,27 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
       fail-fast: false
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
+      # A hit means these exact inputs already passed on this Python version.
+      # The cache only saves when the job succeeds, so a failure never hits.
       - name: Cache pytest results
         id: cache-pytest
         uses: actions/cache@v4
         with:
           path: .pytest_cache
-          key: ${{ runner.os }}-pytest-${{ matrix.python-version }}-${{ hashFiles('**/tests/**/*.py', 'src/**') }}
+          key: ${{ runner.os }}-pytest-${{ matrix.python-version }}-${{ hashFiles('src/**', 'tests/**', 'pyproject.toml', 'uv.lock', '.github/workflows/test.yml', '.github/actions/setup/**') }}
 
-      - name: Install uv
+      - name: Set up the project
         if: steps.cache-pytest.outputs.cache-hit != 'true'
-        uses: astral-sh/setup-uv@v7
+        uses: ./.github/actions/setup
         with:
-          enable-cache: true
-
-      - name: Set up Python ${{ matrix.python-version }}
-        if: steps.cache-pytest.outputs.cache-hit != 'true'
-        run: uv python install ${{ matrix.python-version }}
-
-      - name: Install dependencies
-        if: steps.cache-pytest.outputs.cache-hit != 'true'
-        run: uv sync --group dev
+          python-version: ${{ matrix.python-version }}
+          sync-args: --group dev
 
       - name: Run tests
         if: steps.cache-pytest.outputs.cache-hit != 'true'
@@ -55,7 +45,7 @@ jobs:
   clean-install:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7