protokit 0.7.0__tar.gz

protokit-0.7.0/.github/workflows/buf-release-watch.yml

@@ -0,0 +1,210 @@
+# D6a U8 Phase B+C — buf release watcher.
+#
+# Scheduled workflow that monitors `bufbuild/buf` for newer stable
+# releases than the version pinned in
+# `src/protokit/schema/lint/cli.py` via `_BUF_PARITY_PIN`. When the
+# upstream stable tag is ahead of the pin, opens (or updates) a
+# tracking issue titled exactly `"buf parity pin behind upstream"`.
+#
+# ----- Rationale (KTD-11 of the U8 plan) -----
+#
+# The parity job (in ci.yml) is advisory and runs against a pinned
+# buf version. Buf may ship a new release at any time with deprecated
+# / renamed / added BASIC rules; without surveillance, the pin would
+# silently rot. This watcher decouples buf's release cadence from PR
+# throughput: pin bumps become discrete tasks (a "buf parity pin
+# upgrade" PR a maintainer lands), not pressure on the current PR's
+# reviewers.
+#
+# ----- Schedule + dispatch -----
+#
+# Weekly cron on Mondays at 13:00 UTC (early Pacific morning,
+# mid-day European working hours). `workflow_dispatch` lets a
+# maintainer trigger the watcher manually after a known upstream
+# release.
+#
+# ----- Permissions -----
+#
+# `issues: write` to create / edit the tracking issue.
+# `contents: read` to read the constant from cli.py.
+# Uses the default `GITHUB_TOKEN`; no secrets needed.
+
+name: buf-release-watch
+
+on:
+  schedule:
+    # Mondays 13:00 UTC.
+    - cron: '0 13 * * 1'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  contents: read
+
+# Two simultaneous workflow_dispatch invocations would otherwise both
+# pass the "no open issue" check and both create a tracking issue —
+# yielding duplicates. Serializing via concurrency-group makes the
+# check + create + edit pipeline atomic relative to other watcher runs.
+concurrency:
+  group: buf-release-watch
+  cancel-in-progress: false
+
+jobs:
+  check-buf-release:
+    runs-on: ubuntu-latest
+
+    # Cap the job: gh API calls can stall at the TCP layer (connection
+    # accepted, no response) which set -euo pipefail cannot detect.
+    # 10 minutes is generous for a few gh REST calls + grep + jq.
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Query upstream latest stable release
+        id: upstream
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        # `gh release list` returns the 5 most recent releases with
+        # the isLatest / isPrerelease metadata. `jq` filters to the
+        # one tagged latest AND not a pre-release. If buf has shipped
+        # only pre-releases recently, this returns empty and the
+        # subsequent step exits cleanly without opening an issue.
+        run: |
+          set -euo pipefail
+          gh release list \
+            -R bufbuild/buf \
+            --limit 5 \
+            --json tagName,isLatest,isPrerelease,publishedAt \
+            > releases.json
+          latest_tag=$(
+            jq -r '.[] | select(.isLatest == true and .isPrerelease == false) | .tagName' \
+              releases.json | head -n 1
+          )
+          published=$(
+            jq -r '.[] | select(.isLatest == true and .isPrerelease == false) | .publishedAt' \
+              releases.json | head -n 1
+          )
+          if [ -z "$latest_tag" ]; then
+            echo "no stable release found in last 5 entries; nothing to do"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "latest_tag=$latest_tag" >> "$GITHUB_OUTPUT"
+          echo "published=$published" >> "$GITHUB_OUTPUT"
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+
+      - name: Read pinned buf version from cli.py
+        id: pinned
+        if: steps.upstream.outputs.skip != 'true'
+        # Greps `_BUF_PARITY_PIN: <ANNOTATION> = "v1.69.0"` and
+        # extracts the quoted version. The annotation segment uses
+        # ``[^=]+`` so the grep tolerates any shape between ``:`` and
+        # ``=`` (str, Final[str], etc.) — matches the regex in
+        # tests/test_buf_parity_pin_drift.py so both consumers agree
+        # on the same line shape.
+        run: |
+          set -euo pipefail
+          pin=$(
+            grep -E '^_BUF_PARITY_PIN\s*:[^=]+=\s*"v[^"]+"' \
+              src/protokit/schema/lint/cli.py \
+              | head -n 1 \
+              | sed -E 's/^[^"]*"(v[^"]+)".*/\1/'
+          )
+          if [ -z "$pin" ]; then
+            echo "could not extract _BUF_PARITY_PIN from cli.py; aborting"
+            exit 1
+          fi
+          echo "pin=$pin" >> "$GITHUB_OUTPUT"
+
+      - name: Compare pin against upstream
+        id: compare
+        if: steps.upstream.outputs.skip != 'true'
+        # Route step outputs through ``env:`` rather than inlining
+        # ``${{ }}`` expressions into the shell script. GH Actions
+        # evaluates ``${{ }}`` at YAML template expansion time
+        # BEFORE bash sees the script — surrounding single quotes
+        # are bash quoting, not GH-template quoting, so a value
+        # containing a single quote would break out of the shell
+        # context and inject commands. Today's `pin` (regex-
+        # constrained source) and `latest` (git tag name) cannot
+        # contain single quotes in practice, but the ``env:``
+        # pattern is the canonical GH Actions mitigation and matches
+        # what the "Find or create" step below already does.
+        env:
+          PIN: ${{ steps.pinned.outputs.pin }}
+          LATEST: ${{ steps.upstream.outputs.latest_tag }}
+        run: |
+          set -euo pipefail
+          if [ "$PIN" = "$LATEST" ]; then
+            echo "pin ($PIN) matches upstream ($LATEST); no action needed"
+            echo "behind=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "pin ($PIN) is behind upstream latest ($LATEST)"
+            echo "behind=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Find or create tracking issue
+        if: steps.upstream.outputs.skip != 'true' && steps.compare.outputs.behind == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PIN: ${{ steps.pinned.outputs.pin }}
+          LATEST: ${{ steps.upstream.outputs.latest_tag }}
+          PUBLISHED: ${{ steps.upstream.outputs.published }}
+        # GitHub search (`in:title`) is full-text and case-insensitive,
+        # not strict-equality. So we query, then POST-FILTER in jq for
+        # an exact title match before deciding create-vs-update. This
+        # avoids accidentally matching an issue titled
+        # `"buf parity pin behind upstream (manual override)"` or
+        # similar variant.
+        run: |
+          set -euo pipefail
+          title='buf parity pin behind upstream'
+          body=$(cat <<EOF
+          The pinned buf version is behind the latest upstream stable release.
+
+          - **Current pin**: \`$PIN\` (in \`src/protokit/schema/lint/cli.py\` and \`.github/workflows/ci.yml\`)
+          - **Latest stable**: \`$LATEST\` (released \`$PUBLISHED\`)
+          - **Release notes**: <https://github.com/bufbuild/buf/releases/tag/$LATEST>
+
+          ## Bump procedure
+
+          1. Update \`_BUF_PARITY_PIN\` in \`src/protokit/schema/lint/cli.py\` to \`$LATEST\`.
+          2. Update the curl URLs in \`.github/workflows/ci.yml\`'s parity job
+             (\`releases/download/$LATEST/buf-Linux-x86_64.tar.gz\` + \`sha256.txt\`).
+          3. Run \`tests/test_buf_parity_pin_drift.py\` locally — it asserts
+             both sites reference the same version.
+          4. Inspect buf's release notes for BASIC rule deprecations / renames / additions:
+             - Run \`buf config ls-lint-rules --version v2 --include-deprecated --format json\`
+               against the new buf binary and compare against the harness's
+               \`_BUF_DEPRECATED_RULES\` set in \`tests/parity/conftest.py\`.
+             - Update \`_BUF_DEPRECATED_RULES\` if any rule we ship parity for has been
+               deprecated, and add a docstring annotation on the corresponding protokit
+               rule per the upstream-rule-deprecation discipline.
+             - Refresh \`tests/parity/fixtures/\` if any rule was renamed.
+          5. Land the bump as a single PR with the CHANGELOG entry.
+
+          This issue is auto-generated by \`.github/workflows/buf-release-watch.yml\` and will
+          be updated in place on subsequent runs while the pin remains behind upstream.
+          Close it after the bump PR merges.
+          EOF
+          )
+
+          # gh issue list returns JSON; jq post-filters for exact title.
+          existing=$(
+            gh issue list \
+              --state open \
+              --search "in:title \"$title\"" \
+              --json number,title \
+              | jq -r --arg title "$title" '.[] | select(.title == $title) | .number' \
+              | head -n 1
+          )
+
+          if [ -n "$existing" ]; then
+            echo "updating existing tracking issue #$existing"
+            gh issue edit "$existing" --body "$body"
+          else
+            echo "opening new tracking issue"
+            gh issue create --title "$title" --body "$body"
+          fi

protokit-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,261 @@
+# protokit CI — initial workflow landed 2026-05-01.
+#
+# Matrix axes:
+#
+#   - python: 3.10 (project floor) and 3.12 (project ceiling). 3.11 is
+#     intentionally NOT in the matrix — the only currently-load-bearing
+#     distinction (tomllib stdlib branch) is shared with 3.12. Adding
+#     3.11 later when a 3.11-specific issue surfaces is a one-line change
+#     to this file.
+#
+#   - has_protoxy: true installs the optional `[compiler]` extra
+#     (protoxy 0.7+); false skips it. Tests that integration-test the
+#     protoxy backend gate via `pytest.mark.skipif(not _has_protoxy())`
+#     (see tests/test_cli_utils.py header for the convention).
+#     System protoc is installed on EVERY cell so the protoc-only path
+#     always runs; the `has_protoxy` axis only controls protoxy.
+#
+# Apt-shipped protoc on ubuntu-latest is currently 3.21.x — sufficient
+# for proto3 fixtures. If a future release introduces Edition 2023
+# fixtures, switch this step to a binary download from the protocolbuffers
+# release bucket pinned to v25+.
+
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    # Explicit job-level cap as a secondary safety net beyond the
+    # 30s per-subprocess guard in
+    # tests/_buf_helpers.py:run_buf_subprocess. Empirical timing:
+    # full suite ~15s. 30 minutes leaves ~120x the empirical wall-
+    # time, with headroom for cold CI runners while guarding against
+    # future deadlock scenarios.
+    timeout-minutes: 30
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.12"]
+        has_protoxy: [true, false]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install system protoc
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler
+
+      - name: Install package + dev deps (with protoxy)
+        if: matrix.has_protoxy
+        run: pip install -e ".[compiler,dev]"
+
+      - name: Install package + dev deps (without protoxy)
+        if: ${{ !matrix.has_protoxy }}
+        run: pip install -e ".[dev]"
+
+      - name: Sanity — protoxy must be ABSENT on has_protoxy=false cells
+        # Cheap insurance against the matrix collapsing to an effective
+        # single cell. If a dev dep transitively pulled protoxy in, the
+        # has_protoxy=false cell would silently exercise both backends,
+        # defeating the matrix.
+        if: ${{ !matrix.has_protoxy }}
+        run: |
+          if pip list --format=freeze | grep -i '^protoxy='; then
+            echo "FAIL: protoxy is installed on a has_protoxy=false cell;"
+            echo "      a dev dep is transitively pulling it in."
+            exit 1
+          fi
+          echo "OK: protoxy absent on has_protoxy=false cell"
+
+      - name: Cold-import smoke test
+        # Validates the cold-import contract for `protokit compat`:
+        # importing `protokit.schema` MUST NOT transitively load
+        # `protokit.schema.lint`, `protokit.schema.compile`, OR
+        # `protokit.formatters._builtin_lint`. The compile module's
+        # placement (LintCompileDiagnostic lives there rather than
+        # in lint/model.py per S2-2) only preserves the contract if
+        # `protokit.schema` itself doesn't pull compile in eagerly.
+        # The `_builtin_lint` module lives under `protokit.formatters`
+        # (not `protokit.schema.lint`) so the substring match below
+        # would miss it without the explicit exact-match — it
+        # registers all four lint formatters at module load time and
+        # MUST stay quarantined behind the lint subcommand entry
+        # point per the lint-quarantine invariant. A regression in any future
+        # delivery that adds an eager import of any of these surfaces
+        # here.
+        #
+        # NOTE: this is a SNAPSHOT of today's transitive imports; future
+        # deliveries that add eager imports may need to update this
+        # assertion target. Mirrored in
+        # tests/schema/lint/test_cold_import_extended.py for
+        # local feedback before push.
+        run: |
+          python -c "
+          import protokit.schema
+          import sys
+          eager = sorted(
+              k for k in sys.modules
+              if 'protokit.schema.lint' in k
+              or k == 'protokit.schema.compile'
+              or k == 'protokit.formatters._builtin_lint'
+          )
+          assert not eager, f'lazy-load contract broken: {eager}'
+          print('cold-import OK')
+          "
+
+      - name: Run mypy (scoped to ratcheted surface)
+        # Strict-mode mypy is configured in pyproject.toml but the
+        # broader codebase has ~30 pre-existing strict-mode errors.
+        # This step gates ONLY the modules currently in
+        # tests/test_static_analysis.py:_TYPE_CHECK_PATHS — the lockstep
+        # is enforced by that test (any divergence between this list
+        # and the ratchet trips the ratchet test). Future deliveries
+        # widen the scope by extending BOTH the path list here AND
+        # _TYPE_CHECK_PATHS in tests/test_static_analysis.py.
+        run: |
+          python -m mypy \
+            src/protokit/_cli_utils.py \
+            src/protokit/formatters/_builtin_lint.py \
+            src/protokit/schema/compile.py \
+            src/protokit/schema/lint/
+
+      - name: Run test suite
+        run: pytest tests/ -v
+
+  # =====================================================================
+  # Parity job — buf v1.69.0 cross-tool parity checks.
+  # =====================================================================
+  #
+  # Runs every buf-equivalent protokit lint rule's fixture through both
+  # `protokit lint` and `buf lint` and asserts equivalent findings.
+  # See tests/parity/conftest.py for the harness; the parity-test
+  # infrastructure design is documented in the project's design notes.
+  #
+  # ----- Advisory posture (DO NOT add to required-checks) -----
+  #
+  # This job is INTENTIONALLY ADVISORY per D6a U8 plan KTD-9 / J2. When
+  # branch protection is configured for `main`, the parity job MUST NOT
+  # be included in any required-checks rule. Buf releases independently
+  # of protokit and can deprecate / rename rules on its own cadence;
+  # a parity divergence is a signal to file as a follow-up (handled by
+  # buf-release-watch.yml), not a blocker on the current PR.
+  #
+  # GitHub's branch-protection UI defaults to listing every check that
+  # has run, so a contributor enabling protection may include `parity`
+  # by accident. If you're configuring branch protection, explicitly
+  # uncheck this job.
+  #
+  # ----- Pin discipline -----
+  #
+  # The buf version pinned below MUST match `_BUF_PARITY_PIN` in
+  # src/protokit/schema/lint/cli.py. The default test suite contains
+  # tests/test_buf_parity_pin_drift.py which fails locally and in CI
+  # before the parity job runs if either pin is bumped without the
+  # other.
+  parity:
+    runs-on: ubuntu-latest
+
+    # Cap the whole job: per-subprocess timeouts in
+    # tests/parity/conftest.py guard only the pytest phase; the setup
+    # steps (apt, pip, curl) are unprotected. 15 minutes covers a
+    # cold runner + slow CDN + full test pass with headroom; a hung
+    # step gets killed cleanly without burning a 6-hour default slot.
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install system protoc
+        # Mirrors the protoc install in the `test` job above. The
+        # parity tests invoke `protokit lint --proto` which compiles
+        # .proto source via protoxy (primary) or protoc (fallback);
+        # apt-shipped protoc on ubuntu-latest is sufficient for the
+        # proto3 fixtures in tests/parity/fixtures/.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y protobuf-compiler
+
+      - name: Install package + dev deps (with compiler extra)
+        run: pip install -e ".[compiler,dev]"
+
+      - name: Download buf v1.69.0 tarball + checksum
+        # Asset name is `buf-Linux-x86_64.tar.gz` (capital L) and the
+        # combined checksum file is `sha256.txt` (one file listing all
+        # release assets). The downloaded tarball MUST be saved under
+        # the canonical filename — `sha256sum -c -` reads filenames
+        # from the .sha256 line and re-hashes from CWD, so a mismatched
+        # local name would fail the verification step with
+        # "buf-Linux-x86_64.tar.gz: No such file or directory".
+        #
+        # `-f` fails on HTTP errors (404 from a stale tag fails the
+        # step rather than writing an HTML 404 body into the tarball);
+        # `-sS` quiet but surface errors; `-L` follow redirects (the
+        # GitHub release CDN redirects); `--connect-timeout 30` caps
+        # the TCP handshake; `--max-time 120` bounds the full transfer
+        # so a stalled CDN connection fails cleanly rather than holding
+        # the step open until the job-level timeout-minutes fires.
+        #
+        # When bumping the version: update BOTH this curl URL AND
+        # _BUF_PARITY_PIN in src/protokit/schema/lint/cli.py. The
+        # tests/test_buf_parity_pin_drift.py drift-check enforces this.
+        run: |
+          curl -fsSL --connect-timeout 30 --max-time 120 \
+            -o buf-Linux-x86_64.tar.gz \
+            https://github.com/bufbuild/buf/releases/download/v1.69.0/buf-Linux-x86_64.tar.gz
+          curl -fsSL --connect-timeout 30 --max-time 60 \
+            -o sha256.txt \
+            https://github.com/bufbuild/buf/releases/download/v1.69.0/sha256.txt
+
+      - name: Verify buf SHA-256 checksum
+        # NON-OPTIONAL supply-chain hardening. A skipped or commented-out
+        # checksum step is a P1 review block: a compromised GitHub
+        # release artifact would otherwise ship arbitrary code into
+        # this CI runner. The grep filter selects the line matching the
+        # canonical filename; sha256sum reads that line from stdin and
+        # re-hashes the local file with the matching name.
+        #
+        # ``--strict`` exits non-zero on improperly-formatted lines.
+        # Without it, a future buf release that changes sha256.txt
+        # format (different separator, missing hash column) could
+        # produce a line that matches the grep anchor but fails
+        # parsing — sha256sum emits a WARNING and exits 0, silently
+        # bypassing the verification. ``--strict`` makes the malformed-
+        # line case a hard failure.
+        run: |
+          grep " buf-Linux-x86_64.tar.gz$" sha256.txt | sha256sum --strict -c -
+
+      - name: Extract and install buf
+        run: |
+          tar -xzf buf-Linux-x86_64.tar.gz
+          sudo mv buf/bin/buf /usr/local/bin/buf
+          sudo chmod +x /usr/local/bin/buf
+
+      - name: Sanity — buf invocation succeeds
+        # Fail fast if the install is broken (e.g., wrong arch tarball,
+        # missing libc, etc.) before pytest starts.
+        run: buf --version
+
+      - name: Run parity tests
+        env:
+          BUF_BINARY: /usr/local/bin/buf
+        run: pytest tests/parity/ -m parity -v

protokit-0.7.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+*.so
+*.bak
+.env
+**/.DS_Store
+
+# compound-engineering workflow artifacts and per-run state —
+# not part of the codebase
+.context/
+.claude/
+
+# Internal planning artifacts live in marc-chiesa/protokit-internal
+# (private). These paths are listed here so `git add .` cannot
+# accidentally re-add them to the public repo.
+TODOS.md
+CLAUDE.md
+CHANGELOG-DRAFT.md
+docs/brainstorms/
+docs/plans/