fuaran-py 0.2.0__tar.gz

fuaran_py-0.2.0/.gitattributes

@@ -0,0 +1,31 @@
+# Pin canonical text-file line endings to LF.
+#
+# `text=auto` lets git detect text vs. binary; `eol=lf` pins the
+# canonical in-repo line ending. On a Windows checkout, files stay LF
+# on disk (no autocrlf round-trip churn), eliminating the recurring
+# "LF will be replaced by CRLF the next time Git touches it" warnings
+# and phantom "modified" churn on tool-regenerated files.
+
+* text=auto eol=lf
+
+# Explicit binary types — git's auto-detection is usually correct
+# but spell out the common ones to be safe.
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.ico   binary
+*.svg   binary
+*.dll   binary
+*.exe   binary
+*.pdb   binary
+*.nupkg binary
+*.snupkg binary
+*.zip   binary
+*.tar   binary
+*.gz    binary
+*.pdf   binary
+*.woff  binary
+*.woff2 binary
+*.ttf   binary
+*.eot   binary

fuaran_py-0.2.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+# Dependabot — the other half of SHA-pinning a GitHub Action.
+#
+# A digest pin removes the "a moved tag silently changed the credential-bearing
+# code in my publish job" hazard, and replaces it with "the pin is now frozen at
+# whatever was current the day it was written". This config is what keeps the
+# second from becoming permanent: Dependabot proposes each bump as a reviewable
+# PR carrying the new digest and the release notes behind it, so an upgrade is a
+# decision somebody made rather than one that happened.
+#
+# Scope is `github-actions` only. The language ecosystems in this repository are
+# pinned and reviewed through their own lockfiles/props and are deliberately not
+# on Dependabot's schedule here.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: ci

fuaran_py-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,168 @@
+# Build, test and wire-format conformance gate for the Python host.
+#
+# ── Layout ───────────────────────────────────────────────────────────────────
+# The conformance corpus is its own public repository. The test suite resolves
+# it as a SIBLING of this repo root (tests/_corpus.py walks to
+# `<container>/wire-format-fixtures`), so this repo is checked out into a
+# subdirectory and the corpus beside it:
+#
+#     $GITHUB_WORKSPACE/
+#     ├── fuaran-py/               ← this repo
+#     └── wire-format-fixtures/    ← the corpus (fuaran-ui/fuaran-ui-specification)
+#
+# The corpus repository is PUBLIC, so the checkout is anonymous — no token.
+#
+# ── Why the corpus assertion below is not optional ───────────────────────────
+# When the corpus is absent, tests/_corpus.py does NOT fail — it silently falls
+# back to the committed offline snapshot under conformance/corpus/. A layout
+# drift would therefore leave the suite certifying against a stale local copy of
+# the spec while the job stayed green, which is the one failure mode a
+# conformance gate must never have. The assertion turns that into a hard stop.
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  # ── QUARANTINE ──────────────────────────────────────────────────────────────────────────
+  # Cases that fail on a clean tree are excluded from the blocking gate here, so
+  # that a NEW regression is caught while known drift stays visible. An entry is
+  # not a judgement that a case is wrong — it is a record of known, understood,
+  # outstanding work, and the list SHRINKS TO EMPTY as the decoder catches up.
+  # Delete entries as they start passing; do not add to it to make a red build
+  # green without a root-cause note — a new failure here is the regression this
+  # gate exists to catch.
+  #
+  # EMPTY as of 2026-08-13: the Toggle/Now/Switch vocabulary landed
+  # (3ac3c87/8e9fac3), the offline corpus snapshot was re-synced (392abd6), and
+  # every formerly quarantined case passes against the current corpus —
+  # verified by the full suite at 1627 passed with zero deselections AND each
+  # former entry re-run by node ID (24 passed). The machinery stays armed; a
+  # future corpus advance repopulates the list the same way.
+  QUARANTINE: ""
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.12 is the declared floor (pyproject requires-python); 3.13 stays as the
+        # workspace's own interpreter. Both must pass, or the floor is a claim.
+        python-version: ['3.12', '3.13']
+        # The `live-host` extra carries what `samples/fastapi-host/` needs to be
+        # TESTED. Both rows are needed and they prove different things: with the
+        # extra, `tests/test_fastapi_host.py` gates — the sample's credential
+        # containment is asserted rather than assumed; without it, the suite is
+        # proven to skip CLEANLY, which is what lets `fuaran-py` claim to be
+        # dependency-light. Before this axis existed only the second arrangement
+        # ever ran, so the sample's tests skipped on every run in a green job.
+        extras: ['dev', 'dev,live-host']
+    name: "Test (py${{ matrix.python-version }}, ${{ matrix.extras }})"
+    defaults:
+      run:
+        working-directory: fuaran-py
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: fuaran-py
+
+      # Deliberately UNPINNED: the corpus is the shared conformance authority
+      # every host certifies against, and one current spec for all hosts is the
+      # point of giving it a single home. Pinning here would let this host drift
+      # from the spec without anything going red.
+      - name: Check out the wire-format conformance corpus
+        uses: actions/checkout@v4
+        with:
+          repository: fuaran-ui/fuaran-ui-specification
+          path: wire-format-fixtures
+
+      - name: Assert the corpus is where the tests resolve it
+        run: test -f ../wire-format-fixtures/manifest.json
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[${{ matrix.extras }}]"
+
+      - name: Lint (ruff check)
+        run: python -m ruff check .
+
+      - name: Format check (ruff format)
+        run: python -m ruff format --check .
+
+      - name: Type check (mypy)
+        run: python -m mypy
+
+      # Print what this gate does NOT cover, on every run. A cap nobody can see
+      # reads as "covered everything".
+      - name: Report the conformance quarantine
+        run: |
+          if [ -n "$QUARANTINE" ]; then
+            echo "The blocking gate below EXCLUDES these known-failing cases:"
+            echo "$QUARANTINE" | tr ' ' '\n' | grep -v '^--deselect$' | sed 's/^/  - /'
+          else
+            echo "Quarantine EMPTY — the blocking gate covers the full conformance suite."
+          fi
+          echo
+          echo "ALSO NOT GATED HERE — inert rather than quarantined (see the skip"
+          echo "summary that -rs prints under each test run below):"
+          echo "  - the reference-renderer parity tests read the reference host's source"
+          echo "    from a sibling checkout this workflow does not make, so they skip."
+          echo "    A skip here does NOT mean the path they look in is right: it was"
+          echo "    wrong for months (the host was renamed) and this note read as the"
+          echo "    explanation. What proves the path now is"
+          echo "    test_reference_host_resolves_in_a_cross_host_checkout, which never"
+          echo "    skips and fails in any checkout that HAS sibling hosts but no"
+          echo "    reference host. It passes here because this job is genuinely a"
+          echo "    single-host checkout — the one shape in which skipping is honest."
+          echo "  - the FastAPI sample-host tests, on the rows that install [dev] ALONE."
+          echo "    fastapi is a sample-only dependency, so the skip there is honest and is"
+          echo "    itself the evidence that this package is dependency-light. The [dev,live-host]"
+          echo "    rows install it and those tests GATE — read the matrix row name to know"
+          echo "    which arrangement this run is."
+          {
+            echo "### Conformance quarantine (excluded from the blocking gate)"
+            echo
+            if [ -n "$QUARANTINE" ]; then
+              echo '```'
+              echo "$QUARANTINE" | tr ' ' '\n' | grep -v '^--deselect$'
+              echo '```'
+            else
+              echo "Empty — the blocking gate covers the full conformance suite."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # Non-blocking: runs the FULL suite so the size of the existing drift is
+      # measured on every run rather than inferred from the quarantine list.
+      - name: Conformance drift (reported, non-blocking)
+        continue-on-error: true
+        run: |
+          set +e
+          python -m pytest -q -rs > drift.log 2>&1
+          status=$?
+          tail -40 drift.log
+          {
+            echo "### Full suite, including quarantined cases (non-blocking)"
+            echo
+            echo '```'
+            grep -E '^[0-9]+ (failed|passed)|failed,|passed,' drift.log | tail -3
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit 0
+
+      # THE GATE. Everything the suite currently passes, including every
+      # conformance case outside the quarantine above.
+      - name: Test (gated)
+        run: python -m pytest -q -rs $QUARANTINE

fuaran_py-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,131 @@
+# Publish fuaran-py to PyPI on a version tag, via PyPI Trusted Publishing (OIDC — no stored token).
+#
+# Trigger: a `v*` tag push only. A branch push reaches no publish job.
+# Prerequisites (one-time, on pypi.org): register this repository as the project's trusted
+# publisher — owner `fuaran-ui`, repository `fuaran-py`, workflow `publish-pypi.yml`,
+# environment `pypi` — then create the `pypi` environment on this repository.
+# The tag must equal the version in pyproject.toml; the gate below refuses otherwise, so a
+# mistyped tag never publishes a mismatched release.
+#
+# WHAT THIS WORKFLOW REFUSES TO PUBLISH, and why each refusal exists:
+#   * a tag whose version does not match pyproject.toml — the `build` job's version gate;
+#   * a tree whose suite is red — the `test` job below, which `publish` `needs`. Until it
+#     existed, a `v*` tag published whatever was at that commit having run no test, no lint
+#     and no type check: the ONLY gate on the released artefact was that it built. CI runs
+#     the same checks on a branch push, but a tag push is a different event on a different
+#     ref, so "CI was green on main" was never a statement about the tagged commit;
+#   * a version PyPI already serves — `skip-existing` is deliberately absent. With it, a
+#     re-tag of an already-published version exited 0 having uploaded nothing, so a release
+#     that silently did not happen was indistinguishable from one that did. Without it the
+#     run fails, by name, and the fix is to cut a new version.
+name: publish-pypi
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # The gate on the TAGGED tree. Mirrors ci.yml's blocking steps — the corpus
+  # checkout it certifies against, the lint/format/type checks, and the suite —
+  # on the release interpreter. Its failure is what stops `publish` below.
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: fuaran-py
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: fuaran-py
+
+      # Deliberately UNPINNED, for the reason ci.yml states: the corpus is the
+      # shared conformance authority and one current spec for all hosts is the
+      # point of giving it a single home.
+      - name: Check out the wire-format conformance corpus
+        uses: actions/checkout@v4
+        with:
+          repository: fuaran-ui/fuaran-ui-specification
+          path: wire-format-fixtures
+
+      # Every corpus-dependent test skips when the corpus is absent, so a layout
+      # drift would retire the conformance leg and still report green. Assert it.
+      - name: Assert the corpus is where the tests resolve it
+        run: test -f ../wire-format-fixtures/manifest.json
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]"
+
+      - name: Lint (ruff check)
+        run: python -m ruff check .
+
+      - name: Format check (ruff format)
+        run: python -m ruff format --check .
+
+      - name: Type check (mypy)
+        run: python -m mypy
+
+      - name: Test (gated)
+        run: python -m pytest -q -rs
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Version gate — tag must equal pyproject version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          ver="$(python - <<'PY'
+          import tomllib
+          print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])
+          PY
+          )"
+          if [ "$tag" != "$ver" ]; then
+            echo "tag v$tag does not match pyproject version $ver" >&2
+            exit 1
+          fi
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    # BOTH, not just `build`: a green build says the artefact assembles, which is
+    # not a statement about whether the code in it works.
+    needs: [test, build]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      # SHA-PINNED, not tag-pinned: this step holds the OIDC-minted publishing
+      # identity, so a moved `release/v1` is credential-bearing code nobody
+      # reviewed. `# v1.14.2` records which release the digest is; Dependabot's
+      # `github-actions` schedule proposes the bumps as reviewable PRs.
+      #
+      # `skip-existing` is deliberately ABSENT — see the header. A re-tag of an
+      # already-published version must fail, not exit 0 having uploaded nothing.
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

fuaran_py-0.2.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# The synced corpus snapshot (conformance/corpus/) IS committed — it makes
+# fuaran-py standalone-testable offline and gives the drift guard
+# (tests/test_corpus_sync.py) a committed baseline to pin against the authority.
+# Re-sync + re-commit it whenever the authoritative corpus regenerates
+# (python conformance/sync_corpus.py), per the §11 forward-coupling rule.