axi-toolkit 0.2.0__tar.gz

axi_toolkit-0.2.0/.githooks/commit-msg

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+# Two things a commit message can get wrong, both invisible until much later.
+#
+# 1. It can publish library-specific data. File content and commit messages are
+#    separate channels; --staged only covers the former, and a message is just
+#    as public.
+# 2. It can be one release-please cannot parse. That one is worse, because it
+#    fails silently and green: the release workflow logs "commit could not be
+#    parsed" at debug level, considers zero commits, skips the release and exits
+#    0, and the fix sits on main unpublished. It has already cost one release
+#    here. See scripts/commitcheck.py for the exact grammar rule.
+#
+# Install with: scripts/install-hooks.sh
+set -e
+
+root=$(git rev-parse --show-toplevel)
+python=$(command -v python3 || command -v python || true)
+
+if [ -z "$python" ]; then
+  echo "commit-msg: no python interpreter found; cannot run the checks" >&2
+  exit 1
+fi
+
+"$python" "$root/scripts/leakcheck.py" --commit-msg "$1"
+"$python" "$root/scripts/commitcheck.py" --commit-msg "$1" --root "$root"

axi_toolkit-0.2.0/.githooks/pre-commit

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+# Block a commit that would publish installation-specific data.
+#
+# Install with: scripts/install-hooks.sh
+# The same scan runs in CI, so bypassing this hook only delays the failure.
+set -e
+
+root=$(git rev-parse --show-toplevel)
+python=$(command -v python3 || command -v python || true)
+
+if [ -z "$python" ]; then
+  echo "pre-commit: no python interpreter found; cannot run the leak check" >&2
+  echo "pre-commit: install python3, or run the scan manually before pushing" >&2
+  exit 1
+fi
+
+"$python" "$root/scripts/leakcheck.py" --staged --root "$root"

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

@@ -0,0 +1,183 @@
+# Local CI — the heavy validation matrix, on the maintainer's self-hosted runner.
+#
+# SECURITY (public repository + self-hosted runner): this workflow must NEVER
+# gain a `pull_request` trigger. The runner is the maintainer's own workstation,
+# and a job on it executes repository code as a real user with that user's files
+# and network. Every trigger below is reachable only by someone who already has
+# write access — a push to `main`, the schedule, or a manual dispatch — so
+# fork-submitted code cannot reach the machine. `pull_request` would hand any
+# contributor on the internet code execution on it, in one line and with no
+# other visible symptom. Add coverage for pull requests in `hygiene.yml`, which
+# is GitHub-hosted, or not at all.
+#
+# WHERE VALIDATION ACTUALLY HAPPENS: every change here goes through the local
+# no-mistakes gate — review, tests, lint, docs — before a PR is ever opened.
+# GitHub-hosted CI is not the primary quality signal for this repository and
+# should not be treated as one, which is why a pull request shows a single cheap
+# check (the leak scan, the one gate that must run before a human reads a diff)
+# rather than a matrix. This workflow is the full matrix; it runs on `main`,
+# nightly, and on demand.
+name: ci (self-hosted)
+
+on:
+  push:
+    branches: [main]
+  # Nightly. Deliberately not 08:17 or 09:41 UTC: two sibling projects hold
+  # those slots on the same workstation.
+  schedule:
+    - cron: '23 10 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  leakcheck:
+    name: leak check
+    runs-on: [self-hosted, linux]
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The workspace on a self-hosted runner outlives the job; do not leave
+          # a credential behind in its .git/config.
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # Prove the scanner still detects what it claims to before trusting it.
+      - name: Self-test against a synthetic dirty fixture
+        run: python3 scripts/leakcheck.py --demo
+      - name: Scan every tracked file
+        run: python3 scripts/leakcheck.py
+
+  # A commit message release-please cannot parse is dropped from the changelog
+  # and the version bump while the release workflow exits 0. `release.yml` fails
+  # on that too, but it only runs on `main`; here it also runs nightly, so an
+  # allowance that has outlived its cause surfaces without waiting for a merge.
+  commits:
+    name: commit messages are readable
+    runs-on: [self-hosted, linux]
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # A pull request body can replace a commit message entirely, so the audit
+      # reads it. Read-only.
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Self-test the checker
+        run: python3 scripts/commitcheck.py --demo
+      - name: Audit every commit since the last release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 scripts/commitcheck.py --since-release --pull-requests require
+
+  # EVERY job that needs third-party packages installs into a fresh `.venv` and
+  # calls the tools by path out of it. That is not ceremony. This runner runs as
+  # the maintainer's own user, so `~/.local/lib/python3.X/site-packages` and
+  # `~/.local/bin` are on the interpreter's path and ahead of it on `PATH` — a
+  # bare `pytest` or `ruff` resolves to whatever the maintainer happens to have
+  # installed, against `/usr/bin/python3.X` rather than the interpreter this job
+  # set up. A venv excludes the user site by construction, so a job sees only
+  # what it just installed.
+  lint:
+    name: lint
+    runs-on: [self-hosted, linux]
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # --clear because the workspace outlives the job on a self-hosted runner.
+      - run: python -m venv --clear .venv
+      - run: .venv/bin/python -m pip install --upgrade pip
+      - run: .venv/bin/pip install -e ".[dev]"
+      - run: .venv/bin/ruff check .
+      - run: .venv/bin/ruff format --check .
+
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: [self-hosted, linux]
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      # The runner's host provides only some of these; setup-python downloads
+      # the rest into the persistent tool cache, so only the first run pays.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m venv --clear .venv
+      - run: .venv/bin/python -m pip install --upgrade pip
+      - run: .venv/bin/pip install -e ".[dev]"
+      # No credentials, no source checkouts, no network. The conformance layer
+      # reads the committed capture, which is the property that lets the whole
+      # suite run here at all — and the floor is 3.9 precisely because the
+      # metadata toolchain (3.11+) is not needed to run what it generated.
+      - run: .venv/bin/pytest
+
+  # The declaration is the source of truth, so a generated file that no longer
+  # matches it is a failure rather than a stale artefact somebody will notice.
+  # Separate from `test` because the metadata toolchain's floor is 3.11 while
+  # the matrix goes down to 3.9: the generator needs it, the generated checks
+  # never do.
+  requirements:
+    name: requirements are current
+    runs-on: [self-hosted, linux]
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m venv --clear .venv
+      - run: .venv/bin/python -m pip install --upgrade pip
+      - run: .venv/bin/pip install -e ".[dev,reqgen]"
+      # Loads the declaration under the sealed-registry discipline and applies
+      # the binding rules — an invented attribute, a requirement with no check,
+      # a reference that no longer resolves, all fail here.
+      - run: .venv/bin/python scripts/reqgen.py list
+      - run: .venv/bin/python scripts/reqgen.py check
+
+  # Nothing watches a workflow that runs on main and overnight, so a failure has
+  # to come and find someone.
+  notify:
+    needs: [leakcheck, commits, lint, test, requirements]
+    if: always() && contains(needs.*.result, 'failure')
+    runs-on: [self-hosted, linux]
+    timeout-minutes: 5
+    steps:
+      - env:
+          # env-indirection: a commit message is untrusted text and must never be
+          # interpolated with ${{ }} directly into a script body.
+          HEAD_MSG: ${{ github.event.head_commit.message }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus"
+          notify-send -u critical "ci FAILED: axi-toolkit" \
+            "$(printf '%s' "$HEAD_MSG" | head -n1)
+          $RUN_URL" || echo "notify-send unavailable; GitHub email still fires"

axi_toolkit-0.2.0/.github/workflows/hygiene.yml

@@ -0,0 +1,91 @@
+# The one check a pull request gets on a GitHub-hosted runner.
+#
+# The leak scan takes seconds and it is the gate that must run before a human
+# looks at a diff: this repository is public and it is built by reading two
+# tools and the installations they were developed against, so an address, a
+# token or a real entity name in a diff is the failure that matters. Everything
+# heavier — lint, the Python matrix, the requirements gate — runs in `ci.yml` on
+# the maintainer's self-hosted runner, on `main` rather than on pull requests.
+#
+# That is not a reduction in rigour, and a thin-looking PR check should not be
+# read as one: every change goes through the local no-mistakes gate — review,
+# tests, lint, docs — before the PR exists. GitHub-hosted CI is not the primary
+# quality signal here. Keep this workflow to the one cheap job; adding the
+# matrix back would restore the duplicate-run waste it was split up to end.
+#
+# The two steps that read the pull request itself are the one exception to
+# that, and they are not coverage for their own sake: they check something
+# that exists ONLY on a pull request. A title and a body are in no checkout,
+# pass under no hook, and can be edited after every other check has run — so
+# `edited` is in the trigger list, and two separate guards depend on it
+# being there.
+#
+# The first is a leak scan of the title and body. This repository is public and
+# the pipeline's own document step writes into the body, pasting captured pytest
+# output that carries absolute paths on two lines: the header's `rootdir:` line,
+# and the warnings summary, which prints the site-packages path of the
+# interpreter that raised the warning — a path no choice of capture directory
+# moves. The first line published a home directory three times across two
+# sibling repositories, with every check green each time, because nothing
+# scanned the one artefact that is neither a tracked file nor a commit message.
+# The guard went in here from the first commit for exactly that, rather than
+# after this repository's first leak — which came anyway, through the second
+# line, in a body whose capture had been run from a scratch directory precisely
+# so the `rootdir:` line would read harmless. The guard caught it, and `edited`
+# re-ran it green on the fixed body. `edited` is what makes the check work at
+# all: the document step writes the evidence in *after* the pull request is
+# opened, so a check that fired only on `opened` would pass the empty original
+# body.
+#
+# The second is release-please's: a body that names the commit-override marker
+# replaces the merged commit message with whatever follows the word, and a
+# paragraph *about* the mechanism is enough to do it. It has already cost a
+# sibling project a release. Still one job, still seconds.
+name: hygiene
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: hygiene-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  leakcheck:
+    name: leak check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # Prove the scanner still detects what it claims to before trusting it: a
+      # scanner that quietly stopped matching would otherwise pass every diff.
+      - name: Self-test against a synthetic dirty fixture
+        run: python3 scripts/leakcheck.py --demo
+      - name: Scan every tracked file
+        run: python3 scripts/leakcheck.py
+      # The surface no hook and no checkout can reach. Fails closed: without a
+      # token, or on a fetch that does not answer, it fails the check rather than
+      # reporting a clean it cannot support. It reports the field, line and
+      # offset of a match and never the match itself — this log is public.
+      - name: Scan the pull request title and body
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 scripts/leakcheck.py --pull-request "${{ github.event.pull_request.number }}"
+      # Same discipline as the scan above: prove the checker still tells the
+      # shapes apart before believing its verdict on this pull request.
+      - name: Self-test the commit checker
+        run: python3 scripts/commitcheck.py --demo
+      - name: Check what a merge would hand release-please
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 scripts/commitcheck.py --pull-request "${{ github.event.pull_request.number }}"

axi_toolkit-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,162 @@
+name: release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # release-please reports success when it cannot read a commit. It catches the
+  # parse error, logs `commit could not be parsed` at debug level, carries on
+  # with whatever it *could* read, and exits 0 — so a message its parser chokes
+  # on is dropped from the changelog and from the version bump while the run goes
+  # green. That is not hypothetical here: it is how a merged fix sat on `main`
+  # unreleased while this workflow reported success, with `Considering: 0
+  # commits` buried in the log.
+  #
+  # Every commit since the last release tag has to be readable by the parser
+  # release-please actually runs — a byte-for-byte copy of it lives in
+  # `vendor/conventional-commits-parser/`, so this needs no npm install and no
+  # network. A commit it cannot read is one release-please silently dropped, and
+  # zero readable commits with commits waiting is the exact state that shipped
+  # nothing; both fail here instead of passing quietly. Nothing since the tag is
+  # the healthy no-op and still passes, which is the distinction the log did not
+  # make.
+  #
+  # `--pull-requests require` is the correction to the first version of this job,
+  # which passed — in the sibling project — while release-please dropped every
+  # commit in the range. The message a commit carries is not necessarily the
+  # message release-please reads: a pull request body that names the
+  # commit-override marker — a paragraph *about* the mechanism is enough —
+  # replaces the whole message with whatever follows the word. That artefact is
+  # on GitHub and not in the checkout, so the audit needs a token, and `require`
+  # makes a missing one fail rather than quietly send it back to checking the
+  # wrong string.
+  #
+  # This job deliberately does NOT `needs:` the one below. It has to fail on its
+  # own account, including on a run where release-please itself errored, and its
+  # verdict does not depend on the outcome it is auditing.
+  commit-audit:
+    name: every commit is readable
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # The pull request body can replace the commit message, so the audit has
+      # to read it. Read-only: this job never writes anything.
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The audit compares `main` against the last release tag, so it needs
+          # both the tags and the commits after them.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      # A checker that stopped detecting anything reads exactly like a checker
+      # with nothing to report, so prove it still works before trusting it.
+      - name: Self-test the checker
+        run: python3 scripts/commitcheck.py --demo
+      - name: Audit every commit since the last release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: python3 scripts/commitcheck.py --since-release --pull-requests require
+
+  # Drives version bumps and the changelog from conventional commits, and opens
+  # a release PR. Merging that PR is what cuts a release.
+  release-please:
+    name: release PR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # What the action decided, in the run summary rather than only in the log.
+      # "No release PR and no release" is a legitimate outcome and also what a
+      # silent parse failure looks like; `commit-audit` is what tells the two
+      # apart, so say here which one this run was.
+      - name: Say what release-please decided
+        env:
+          RELEASE_CREATED: ${{ steps.release.outputs.release_created }}
+          PRS_CREATED: ${{ steps.release.outputs.prs_created }}
+          TAG_NAME: ${{ steps.release.outputs.tag_name }}
+        run: |
+          {
+            echo "### release-please"
+            echo ""
+            echo "| | |"
+            echo "| --- | --- |"
+            echo "| release created | ${RELEASE_CREATED:-false} |"
+            echo "| release PR created or updated | ${PRS_CREATED:-false} |"
+            echo "| tag | ${TAG_NAME:-none} |"
+            echo ""
+            echo "A run with neither a release nor a release PR means nothing"
+            echo "releasable has landed. The \`every commit is readable\` job is"
+            echo "what proves that is the truth rather than a parse failure."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  # NOT YET REACHABLE, on purpose. The PyPI project does not exist: registering
+  # the name is a one-time account action only the maintainer can perform, and
+  # nothing here should attempt it. The job is written now and gated behind
+  # `release_created`, which is only true after a release PR merges, so it
+  # cannot fire before the name is claimed. Trusted publishing needs the
+  # `pypi` environment and a PyPI publisher configured for this repository
+  # before the first release; until then, merging a release PR would fail this
+  # job and nothing else.
+  publish:
+    name: publish to PyPI
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/axi-toolkit
+    permissions:
+      # The only credential involved: a short-lived OIDC token minted for this
+      # run. No long-lived PyPI token exists in this repository or anywhere else.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+
+      # Publishing a broken artifact is worse than not publishing. This package
+      # has no entry point to run, so the smoke test is the thing a consumer
+      # will actually do: install the wheel on its own, import every module, and
+      # run the vendored conformance rig out of the installed copy. That last
+      # part is why the fixtures ship inside the package — a wheel whose
+      # encoder and fixtures disagreed would go out green otherwise.
+      - name: Smoke-test the built wheel
+        run: |
+          python -m venv /tmp/verify
+          /tmp/verify/bin/pip install --quiet dist/*.whl
+          /tmp/verify/bin/python -c "
+          import axi_toolkit, axi_toolkit.errors, axi_toolkit.redact, axi_toolkit.envconfig
+          import axi_toolkit.toon, axi_toolkit.toon_spec
+          from axi_toolkit.render import cli, prose
+          report = axi_toolkit.toon_spec.run(axi_toolkit.toon.encode)
+          assert not report.failures, report.failures[:3]
+          assert not axi_toolkit.toon_spec.digest_mismatches()
+          print('axi-toolkit', axi_toolkit.__version__, 'TOON', report.score)
+          "
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

axi_toolkit-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+
+# Agent-local settings, which routinely contain absolute home paths. Keeping
+# this out of .git/info/exclude matters: that file is local to one clone and
+# never travels with the repository.
+.claude/
+.codex/

axi_toolkit-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}