django-spec-html 0.1.0__tar.gz

django_spec_html-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Artui

django_spec_html-0.1.0/.github/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security issues **privately** via GitHub's
+[Report a vulnerability](../../security/advisories/new) button rather than opening a public issue.
+I aim to acknowledge reports within 72 hours.
+
+Supported: the latest released version on the default branch.

django_spec_html-0.1.0/.github/dependabot.yml

@@ -0,0 +1,26 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # Dependabot already holds a new version for 3 days before proposing it; a
+    # week is the more useful threshold. A compromised release is typically
+    # yanked within days, so the gap between "published" and "found" is exactly
+    # the window an automatic upgrade walks into. This costs nothing in
+    # responsiveness that matters: cooldown covers version updates only, and
+    # security advisories are proposed immediately regardless.
+    cooldown:
+      default-days: 7
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      python:
+        patterns: ["*"]

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

@@ -0,0 +1,112 @@
+name: release
+
+# Main-triggered: every merge to `main` runs `release-publish-prepare`, which
+# short-circuits to a no-op unless the version in source has been bumped past
+# the most recent `vX.Y.Z` tag. The previous tag-trigger flow has been removed
+# — `make release-bump` + merge to main is now the only path.
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release-main
+  cancel-in-progress: false
+
+# Actions are pinned to a commit SHA rather than a tag: a tag is mutable, and an
+# action owner (or anyone who takes over the account) can silently repoint one at
+# new code that then runs with this workflow's token. The trailing version comment
+# is not decoration -- Dependabot reads it to know which release the SHA is, and
+# rewrites both together when a newer one ships.
+jobs:
+  release:
+    name: release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/django-spec-html
+    permissions:
+      id-token: write   # PyPI OIDC trusted publishing
+      contents: write   # tag push + gh release create
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --all-groups
+
+      - name: Prepare release (version check, test, build dist)
+        id: prepare
+        run: make release-publish-prepare
+
+      - name: Publish to PyPI
+        if: steps.prepare.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          # Idempotent on purpose. What gates a release is the git tag, not the
+          # index (see `prepare`), so re-running this job after a failure in a
+          # later step arrives here having already uploaded these files. Without
+          # this the upload is the step that makes that re-run impossible, and
+          # every recovery becomes manual — which is how one release lost its tag,
+          # its GitHub Release and its docs deploy to a single transient push
+          # failure, with the package already published.
+          # PyPI never lets a file be replaced, so skipping one cannot overwrite
+          # a published artefact.
+          skip-existing: true
+
+      - name: Tag + GitHub Release
+        if: steps.prepare.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: make release-publish-finalize
+
+      # On release commits we own the single gh-pages push: embed the
+      # coverage badge JSON into the docs build so mkdocs gh-deploy carries
+      # it alongside the site, and tests.yml's coverage-badge job
+      # short-circuits to avoid a second push (and a second built-in
+      # "pages build and deployment" run).
+      - name: Render coverage badge for the docs site
+        if: steps.prepare.outputs.released == 'true' && hashFiles('mkdocs.yml') != ''
+        run: |
+          set -euo pipefail
+          # release-publish-prepare's pytest run wrote .coverage to the
+          # workspace root; convert to coverage.xml so the same parser
+          # we use in tests.yml can score it.
+          uv run coverage xml -o coverage.xml
+          python - <<'PY'
+          import json
+          import xml.etree.ElementTree as ET
+
+          tree = ET.parse("coverage.xml")
+          pct = round(float(tree.getroot().attrib["line-rate"]) * 100, 1)
+          if pct >= 95:
+              color = "brightgreen"
+          elif pct >= 85:
+              color = "green"
+          elif pct >= 70:
+              color = "yellow"
+          else:
+              color = "red"
+          payload = {
+              "schemaVersion": 1,
+              "label": "coverage",
+              "message": f"{pct}%",
+              "color": color,
+          }
+          # docs/ is mkdocs' source dir; non-.md files are copied verbatim
+          # into site/, which lands at the gh-pages root after gh-deploy.
+          with open("docs/coverage.json", "w") as fh:
+              json.dump(payload, fh)
+              fh.write("\n")
+          print(json.dumps(payload))
+          PY
+
+      - name: Deploy docs + coverage badge to gh-pages
+        if: steps.prepare.outputs.released == 'true' && hashFiles('mkdocs.yml') != ''
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          DJANGO_SETTINGS_MODULE=tests.conftest_settings \
+            uv run mkdocs gh-deploy --force --clean --config-file mkdocs.yml

django_spec_html-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,374 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+# Actions are pinned to a commit SHA rather than a tag: a tag is mutable, and an
+# action owner (or anyone who takes over the account) can silently repoint one at
+# new code that then runs with this workflow's token. The trailing version comment
+# is not decoration -- Dependabot reads it to know which release the SHA is, and
+# rewrites both together when a newer one ships.
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --all-groups
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format check
+        run: uv run ruff format --check --diff .
+      - name: ty
+        run: uv run ty check django_spec_html
+
+  docs:
+    name: docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+      - name: Install with docs group
+        run: uv sync --all-groups
+      - name: mkdocs build --strict
+        # mkdocstrings imports the package, and a Django package can read
+        # ``django.conf.settings`` at import time. Pointing at the test settings
+        # module keeps the build hermetic rather than dependent on whether any
+        # module happens to do so today.
+        run: DJANGO_SETTINGS_MODULE=tests.conftest_settings uv run mkdocs build --strict
+
+  floor:
+    name: lowest declared versions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+      # A floor is a claim about the *oldest* version that works, and a lockfile
+      # can only ever check the newest. Development and CI both resolve the
+      # newest in-range dependency, so every gate passes while a consumer whose
+      # own constraints pull an older one gets a package that does not import.
+      #
+      # `lowest-direct` pins every *declared* dependency to the bottom of its
+      # window while letting transitives resolve normally, so this asserts the
+      # floors mean what they say. A per-PR gate rather than a scheduled job,
+      # because a floor stops being true the moment someone imports a newer
+      # upstream symbol -- a code change, not the passage of time.
+      #
+      # Pinned to the oldest supported Python rather than whatever interpreter
+      # the runner exposes. The floor claim is about the oldest configuration
+      # we support, so that is the one to install, and leaving the choice to
+      # the image makes the answer drift when the image does.
+      - name: Install Python 3.10
+        run: uv python install 3.10
+      # `--refresh` on both resolutions below. This job's whole claim is "what a
+      # consumer resolving from scratch would get", and the runner's uv cache is
+      # shared across runs: without it the answer comes from whatever package
+      # list that cache happens to hold, which can be hours behind the index.
+      - name: Resolve every declared dependency at its floor
+        run: uv lock --resolution lowest-direct --refresh
+      # `--frozen` here and `--no-sync` below, not a bare `uv sync` / `uv run`.
+      # uv records the resolution mode in the lockfile and silently discards one
+      # resolved in a different mode, so a plain `uv sync` re-resolves at
+      # `highest` and undoes the step above -- the job would then measure the
+      # newest versions twice while reporting that it tested the oldest.
+      - name: Install
+        run: uv sync --frozen --all-groups --all-extras --python 3.10
+      - name: Name the versions that produced
+        run: uv pip list
+      - name: Test
+        run: uv run --no-sync pytest
+
+      # The step above installs every group, and a group can hold a shared
+      # dependency *above* the floor being claimed -- the dev group's
+      # ``django-service-specs[filter]`` does -- masking the lie rather than
+      # exposing it. So the floor claim is also checked on the install shape
+      # with the fewest constraints: the package alone, no dev group. That
+      # shape is what a Django project adding a page actually gets.
+      - name: Import the package installed alone, at its floors
+        run: |
+          uv venv --python 3.10 .venv-floor
+          uv pip install --python .venv-floor/bin/python --resolution lowest-direct --refresh -e .
+          uv pip list --python .venv-floor/bin/python
+          .venv-floor/bin/python - <<'PY'
+          import django
+          from django.conf import settings
+
+          # The package defines no models and needs no app listed: a project
+          # imports its views from a URLconf, after django.setup() against
+          # configured settings, so it is imported that way here.
+          settings.configure(
+              SECRET_KEY="x",
+              INSTALLED_APPS=[
+                  "django.contrib.contenttypes",
+                  "django.contrib.auth",
+              ],
+              DATABASES={"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}},
+          )
+          django.setup()
+
+          import sys
+
+          import django_spec_html
+
+          # The kernel it serves exists for dispatch without DRF, and a
+          # plain-Django view is one of the transports that needs none, so the
+          # install that proves the floors also proves neither package reaches
+          # for it. Nothing here installs DRF, so an import of it would already
+          # fail above; this names the claim.
+          assert "rest_framework" not in sys.modules, "the package imported DRF"
+
+          print("BASE IMPORT OK", django_spec_html.__version__, django.get_version())
+          PY
+
+  test:
+    name: ${{ matrix.python-version }} / Django ${{ matrix.django-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        django-version: ["4.2", "5.0", "5.1", "5.2", "6.0", "6.1"]
+        exclude:
+          # Django 4.2 supports Python 3.8–3.12
+          - python-version: "3.13"
+            django-version: "4.2"
+          - python-version: "3.14"
+            django-version: "4.2"
+          # Django 5.0 supports Python 3.10–3.12
+          - python-version: "3.13"
+            django-version: "5.0"
+          - python-version: "3.14"
+            django-version: "5.0"
+          # Django 5.1 supports Python 3.10–3.13
+          - python-version: "3.14"
+            django-version: "5.1"
+          # Django 6.0 supports Python 3.12+
+          - python-version: "3.10"
+            django-version: "6.0"
+          - python-version: "3.11"
+            django-version: "6.0"
+          # Django 6.1 requires Python 3.12+
+          - python-version: "3.10"
+            django-version: "6.1"
+          - python-version: "3.11"
+            django-version: "6.1"
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: true
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Sync dev deps
+        run: uv sync --all-groups --python ${{ matrix.python-version }}
+      - name: Pin Django ${{ matrix.django-version }}
+        run: uv pip install --reinstall-package django "django~=${{ matrix.django-version }}.0"
+      - name: pytest
+        run: |
+          uv run --no-sync pytest \
+            --cov-report=xml:coverage.xml \
+            --cov-report=html:htmlcov
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: coverage-py${{ matrix.python-version }}-django${{ matrix.django-version }}
+          path: |
+            coverage.xml
+            htmlcov/
+          if-no-files-found: ignore
+
+  coverage-badge:
+    # Publishes a shields.io-compatible coverage.json to gh-pages so the README
+    # badge reflects reality. Runs only on push to main, after the matrix has
+    # produced an artifact we can read from.
+    name: coverage badge
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # Need the parent commit so the gate step below can diff
+          # version.py against ${{ github.event.before }}. The default
+          # shallow checkout (depth 1) would make `git show "$before:…"`
+          # fail with exit 128 and turn the whole job red.
+          fetch-depth: 2
+      # release.yml runs in parallel on the same push and owns gh-pages
+      # publishing on release commits (it bundles coverage.json into the
+      # mkdocs gh-deploy). If we also push here we get a second built-in
+      # "pages build and deployment" run that the first one cancels. The
+      # version-diff against ${{ github.event.before }} is the reliable
+      # signal — release.yml's tag isn't pushed until after PyPI publish,
+      # so a tag-existence check would race.
+      - name: Skip when release.yml owns this push
+        id: gate
+        run: |
+          set -euo pipefail
+          before="${{ github.event.before }}"
+          if [[ -z "$before" || "$before" =~ ^0+$ ]]; then
+              # First push to main on a brand-new repo — no prior state to diff.
+              echo "skip=false" >> "$GITHUB_OUTPUT"
+              exit 0
+          fi
+          # `before` may not be in the local object DB if the push
+          # contained more than one commit (fetch-depth: 2 only guarantees
+          # HEAD + 1 parent). Try to fetch just that commit; if it's not
+          # reachable, fall back to "don't skip" — better to double-push
+          # to gh-pages once than to turn the pipeline red.
+          if ! git cat-file -e "$before^{commit}" 2>/dev/null; then
+              git fetch --depth=1 origin "$before" 2>/dev/null || true
+          fi
+          old=""
+          if git cat-file -e "$before:django_spec_html/version.py" 2>/dev/null; then
+              old="$(git show "$before:django_spec_html/version.py" \
+                     | awk -F'"' '/^__version__/ { print $2; exit }')"
+          fi
+          new="$(awk -F'"' '/^__version__/ { print $2; exit }' \
+                 django_spec_html/version.py)"
+          if [[ -n "$old" && "$old" != "$new" ]]; then
+              echo "Version bumped $old → $new; release.yml will deploy gh-pages."
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+              echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Download canonical coverage artifact
+        if: steps.gate.outputs.skip != 'true'
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          # Pin to one cell of the matrix — coverage is the same shape across
+          # all cells and we only need one number.
+          name: coverage-py3.13-django5.2
+          path: coverage-artifact/
+      - name: Render coverage.json
+        if: steps.gate.outputs.skip != 'true'
+        run: |
+          python - <<'PY'
+          import json
+          import xml.etree.ElementTree as ET
+
+          tree = ET.parse("coverage-artifact/coverage.xml")
+          pct = round(float(tree.getroot().attrib["line-rate"]) * 100, 1)
+          if pct >= 95:
+              color = "brightgreen"
+          elif pct >= 85:
+              color = "green"
+          elif pct >= 70:
+              color = "yellow"
+          else:
+              color = "red"
+          payload = {
+              "schemaVersion": 1,
+              "label": "coverage",
+              "message": f"{pct}%",
+              "color": color,
+          }
+          with open("coverage.json", "w") as fh:
+              json.dump(payload, fh)
+              fh.write("\n")
+          print(json.dumps(payload))
+          PY
+      - name: Publish coverage.json to gh-pages
+        if: steps.gate.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+
+          tmp="$(mktemp -d)"
+          cp coverage.json "$tmp/coverage.json"
+
+          git fetch origin gh-pages --depth=1 2>/dev/null || true
+          if git rev-parse --verify origin/gh-pages >/dev/null 2>&1; then
+              git worktree add gh-pages origin/gh-pages
+              cp "$tmp/coverage.json" gh-pages/coverage.json
+              cd gh-pages
+              if [[ -n "$(git status --porcelain coverage.json)" ]]; then
+                  git add coverage.json
+                  git commit -m "coverage badge: update from ${GITHUB_SHA::7}"
+                  git push origin HEAD:gh-pages
+              else
+                  echo "coverage.json unchanged, skipping push"
+              fi
+          else
+              # First run before docs deploy. Lay down an orphan gh-pages with
+              # just the badge file; the docs deploy will overwrite the rest.
+              git worktree add --detach gh-pages
+              cd gh-pages
+              git checkout --orphan gh-pages
+              git rm -rf . >/dev/null 2>&1 || true
+              cp "$tmp/coverage.json" coverage.json
+              git add coverage.json
+              git commit -m "coverage badge: initial publish from ${GITHUB_SHA::7}"
+              git push origin gh-pages
+          fi
+
+  secrets:
+    name: secret scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Install gitleaks
+        run: |
+          curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz | tar -xz gitleaks
+          sudo mv gitleaks /usr/local/bin/
+      - name: Scan repo + history
+        run: gitleaks git --redact --no-banner .
+
+  tests-passed:
+    name: tests
+    # always(), never !cancelled(): a skipped job reports a skipped check, and
+    # branch protection counts a skipped required check as passing.
+    if: always()
+    needs: [lint, docs, floor, test]
+    runs-on: ubuntu-latest
+    steps:
+      # Pass on an exact `success` from every job above, rather than failing on
+      # a list of bad results: such a list passes whatever it does not name, and
+      # GitHub reports a result it does not document. A job no hosted runner
+      # ever picks up ("The job was not acquired by Runner of type hosted even
+      # after multiple attempts") shows as cancelled on its own check but
+      # reaches `needs` as `abandoned`, and a gate that failed only on `failure`
+      # and `cancelled` went green over exactly that while the jobs it guards
+      # never ran. A matrix reaches `needs` as one result, and one cell that did
+      # not succeed is enough to make it something other than `success`.
+      #
+      # None of the jobs above has an `if:`, so `skipped` can only mean one of
+      # them never ran, and it fails like any other result. A job that gains a
+      # legitimate skip gets an exception naming it, never `skipped` accepted
+      # from all of them.
+      #
+      # The results come in through `env` rather than being spliced into the
+      # script, and every one is printed, so a red gate says which job and what
+      # GitHub reported for it.
+      - name: Verify every required job succeeded
+        env:
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          echo "$NEEDS" | jq -r 'to_entries[] | "\(.key): \(.value.result)"'
+          not_ok="$(echo "$NEEDS" | jq -r '[to_entries[] | select(.value.result != "success") | "\(.key)=\(.value.result)"] | join(" ")')"
+          if [ -n "$not_ok" ]; then
+            echo "::error::required jobs did not succeed: $not_ok"
+            exit 1
+          fi

django_spec_html-0.1.0/.github/workflows/upstream-drift.yml

@@ -0,0 +1,149 @@
+# What a fresh install would get today, run on a schedule.
+#
+# ``uv.lock`` is what every other job resolves against, so a dependency can be
+# unconstrained in ``pyproject.toml`` and still frozen everywhere it is actually
+# tested. That gap is why the Django 6.1 break was invisible while the matrix
+# was green: the cell that found it installed unpinned and resolved 6.1 by
+# accident.
+#
+# This job closes it deliberately. It ignores the lock, resolves the newest
+# versions ``pyproject.toml`` allows, and runs the suite — so an upstream
+# release that breaks us is found by a scheduled run rather than by a consumer.
+#
+# It is also the control that makes dropping dependency ceilings safe. A
+# ceiling is a guess about which future versions will break; this is a
+# measurement of which ones do. Do not delete it to quieten a noisy week
+# without replacing what it measures.
+name: upstream drift
+
+on:
+  schedule:
+    # Mondays, 06:00 UTC. Weekly rather than nightly: the failure this guards
+    # against is an upstream release, which is measured in weeks, and six repos
+    # running nightly is six chances a day to learn nothing.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: upstream-drift-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  issues: write
+
+# Actions are pinned to a commit SHA rather than a tag: a tag is mutable, and an
+# action owner (or anyone who takes over the account) can silently repoint one at
+# new code that then runs with this workflow's token. The trailing version comment
+# is not decoration -- Dependabot reads it to know which release the SHA is, and
+# rewrites both together when a newer one ships.
+jobs:
+  resolve-latest:
+    name: resolve unpinned + test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: false
+
+      # One cell, not the matrix. The matrix answers "does this combination
+      # work"; this answers "has an upstream moved under us", and the newest
+      # supported Python is where a new release lands first.
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Resolve the newest versions pyproject allows
+        run: uv lock --upgrade
+
+      - name: Report what changed against the committed lock
+        # Informational, and the most useful line in the log when this fails:
+        # it names the upgrade that broke the build.
+        run: git --no-pager diff --stat uv.lock || true
+
+      - name: Install
+        id: install
+        run: uv sync --all-groups --all-extras
+
+      - name: Show the resolved versions
+        run: uv pip list
+
+      # A resolve can succeed by backing off. When the newest release of a
+      # direct dependency conflicts with something else this project requires,
+      # uv takes the newest version that does resolve and logs an ordinary
+      # "Updated" line, so the suite below passes against a release nobody
+      # chose. That is how django-ag-ui's run went green with pydantic-ai-slim
+      # at 2.46 and 2.54 out: from 2.47 its [ag-ui] extra caps ag-ui-protocol
+      # below the 1.0 django-ag-ui requires. This compares every direct
+      # dependency with PyPI, fails on one held below a release that has been
+      # out longer than the Dependabot cooldown, and asks uv what holds it. A
+      # ceiling declared in pyproject.toml is honoured, which is how a hold is
+      # accepted on purpose. One copy for every repo, pinned like any action.
+      - name: Check no direct dependency is held back
+        id: held-back
+        uses: Artui/held-back-check@b64bbb88fd63c9c96675caba477cce13714de93e # v0.1.0
+
+      # Runs whether or not the check above failed: they answer different
+      # questions, and a hold is no reason to stop measuring what did resolve.
+      - name: Test
+        id: test
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: uv run pytest
+
+      - name: Open or update an issue on failure
+        # Main only. A dispatch on any other branch is a trial of that branch's
+        # manifest, and an issue saying the unpinned resolve is failing would be
+        # filed against the wrong tree.
+        if: failure() && github.ref == 'refs/heads/main'
+        env:
+          HELD_BACK: ${{ steps.held-back.outcome }}
+          TESTS: ${{ steps.test.outcome }}
+          REPORT: ${{ steps.held-back.outputs.report }}
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const fs = require("fs");
+            const title = "upstream drift: the unpinned resolve is failing";
+            const run = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const sections = [];
+            if (process.env.TESTS === "failure") {
+              sections.push([
+                "The weekly unpinned resolve failed. A dependency released a version",
+                "that `pyproject.toml` admits and the suite does not survive.",
+                "",
+                "The `git diff --stat uv.lock` step in that run names what moved.",
+              ].join("\n"));
+            }
+            if (process.env.HELD_BACK === "failure") {
+              sections.push(fs.existsSync(process.env.REPORT)
+                ? fs.readFileSync(process.env.REPORT, "utf8")
+                : "The held-back check failed before writing its report; the run's log says why.");
+            }
+            if (!sections.length) {
+              sections.push("A step before the suite failed; the run's log names it.");
+            }
+            const body = [
+              ...sections,
+              "",
+              `Run: ${run}`,
+              "",
+              "Fix forward (adopt the new version) or add a floor/ceiling that says",
+              "why, but do not silence the job — it is the control that lets this",
+              "repo declare open-ended dependency windows.",
+            ].join("\n");
+            const existing = await github.rest.issues.listForRepo({
+              owner: context.repo.owner, repo: context.repo.repo,
+              state: "open", labels: "upstream-drift",
+            });
+            if (existing.data.length) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                issue_number: existing.data[0].number, body,
+              });
+            } else {
+              await github.rest.issues.create({
+                owner: context.repo.owner, repo: context.repo.repo,
+                title, body, labels: ["upstream-drift"],
+              });
+            }