mdka 2.2.2__tar.gz → 2.3.0__tar.gz

{mdka-2.2.2 → mdka-2.3.0}/.github/workflows/ci.yaml

@@ -46,14 +46,20 @@ jobs:
       - name: cargo fmt --check
         run: cargo fmt --check
 
+      # --keep-going (RFC 032): report every crate's lint failures, not just the
+      # first crate's. clippy --help does not list it, but clippy passes it to
+      # cargo check and it was seen to change the output. Keep it before `--`.
       - name: cargo clippy
-        run: cargo clippy --workspace --all-targets --all-features -- -D warnings
+        run: cargo clippy --workspace --all-targets --all-features --keep-going -- -D warnings
 
+      # --no-fail-fast (RFC 032): without it the first failing test binary stops
+      # the rest, so a failure in one binary hides failures in all later ones.
       - name: cargo test
-        run: cargo test --workspace --all-features --locked
+        run: cargo test --workspace --all-features --locked --no-fail-fast
 
+      # --keep-going (RFC 032): report every target that fails to compile.
       - name: cargo build
-        run: cargo build --workspace --locked
+        run: cargo build --workspace --locked --keep-going
 
   msrv:
     runs-on: ubuntu-latest
@@ -87,8 +93,10 @@ jobs:
       # --all-targets is deliberately omitted: bench dev-dependencies require a
       # newer toolchain and are advisory only, not part of the published MSRV.
       # --locked verifies the same dependency set the `rust` job saw.
+      # --keep-going (RFC 032): report every crate that fails to check on the
+      # MSRV toolchain, not just the first. Verified on 1.88.
       - name: cargo check
-        run: cargo check --workspace --locked
+        run: cargo check --workspace --locked --keep-going
 
   node:
     runs-on: ubuntu-latest
@@ -136,6 +144,14 @@ jobs:
   python:
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        # RFC 034: the declared floor (python/wheel-matrix.toml python-floor)
+        # and the newest stable CPython. The floor entry is asserted equal to
+        # python-floor below. When CI can no longer install the floor, this
+        # job goes red -- that is trigger 1 for raising it.
+        python: ["3.10", "3.x"]
 
     steps:
       - name: Checkout repository
@@ -144,7 +160,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
-          python-version: 3.x
+          python-version: ${{ matrix.python }}
 
       - name: Cache cargo dependencies and build
         uses: actions/cache@v5
@@ -153,9 +169,9 @@ jobs:
             ~/.cargo/registry
             ~/.cargo/git
             target
-          key: ${{ runner.os }}-cargo-python-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-cargo-python-${{ matrix.python }}-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: |
-            ${{ runner.os }}-cargo-python-
+            ${{ runner.os }}-cargo-python-${{ matrix.python }}-
 
       # python/pyproject.toml declares readme = "README.md" but the README lives
       # at the repository root. Required — omitting this fails the build (see
@@ -166,9 +182,27 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
 
+      # The script needs Python >= 3.11 (tomllib), so uv supplies one
+      # separately from the interpreter under test.
+      - name: Declared floor matches this matrix and the manifests
+        run: |
+          set -euo pipefail
+          check() {
+            uv run --no-project --python 3.13 --with packaging -- \
+              python .github/workflows/scripts/check-wheel-matrix.py "$@"
+          }
+          if [ "${{ matrix.python }}" != "3.x" ]; then
+            check floor-equals "ci.yaml python matrix" "${{ matrix.python }}"
+          fi
+          check floor-manifests
+
+      # `uv venv` alone may pick a different interpreter than the matrix one;
+      # name it explicitly and print what the venv actually runs.
       - name: Install maturin and pytest
         run: |
-          uv venv
+          uv venv --python "$(python -c 'import sys; print(sys.executable)')"
+          source .venv/bin/activate
+          python --version
           uv pip install maturin pytest
 
       - name: maturin develop
@@ -181,4 +215,5 @@ jobs:
         working-directory: python
         run: |
           source ../.venv/bin/activate
+          python --version
           python -m pytest test_mdka.py

mdka-2.3.0/.github/workflows/crates-package-gate.yaml

@@ -0,0 +1,103 @@
+name: crates package gate
+
+# RFC 026 §4.2. The `rust` job in ci.yaml runs `cargo test` in-workspace,
+# where every path dependency resolves and every file is present. It cannot
+# see a crate that compiles here and fails standalone -- through a missing
+# `include`, a path dependency with no version, or a file absent from the
+# packaged .crate.
+#
+# `cargo package` (without --no-verify) packages each crate and then builds
+# from the extracted package, where path dependencies are stripped. That is
+# the consumer's build.
+#
+# RFC 030: this is ONE `--workspace` invocation, not four per-crate steps,
+# and that is deliberate. Packaging the dependents separately makes each
+# resolve `mdka` from crates.io -- but on main the workspace version is the
+# NEXT version, which is not published yet, so mdka-cli failed with
+# "failed to select a version for the requirement mdka = ^X.Y.Z" at every
+# release commit. Worse, that failure skipped mdka-node and mdka-python
+# entirely, so the red masked the gate's own coverage: across 2.2.2 and
+# 2.2.3 nothing verified that those two package and build standalone.
+#
+# `--workspace` builds a temporary local registry from the packaged members
+# (target/package/tmp-registry/) and resolves the dependents against it, so
+# it works whether or not the version is published. Do not "simplify" this
+# back into four steps.
+#
+# Its own workflow file, not ci.yaml -- see RFC 026 §3.5 and RFC 020's
+# correction record.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  crates-package-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Cache cargo dependencies and build
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-package-gate-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-package-gate-
+
+      # No --no-verify anywhere. Packaging without building the result would
+      # check that the tarball can be produced, not that it works -- which is
+      # the distinction this whole milestone is about.
+      #
+      # No --keep-going either, deliberately (RFC 032). cargo package --help
+      # lists it, but it changed nothing when tested: package verifies members
+      # one after another, and the flag only continues within a single build.
+      # A second broken crate is still reported only after the first is fixed.
+      - name: cargo package --workspace
+        run: cargo package --workspace --locked
+
+      # Scoped to the workspace's current version, and asserts there are four
+      # of them. target/ is restored from the cache, so an unfiltered glob
+      # lists every version packaged since the cache was last cold -- twelve
+      # .crate files across three versions, at the time of writing -- which
+      # reads as though this run produced them all. The count check also turns
+      # the listing from decoration into an assertion that every member was
+      # packaged.
+      - name: Show what each package actually contains
+        run: |
+          set -euo pipefail
+          version=$(cargo metadata --format-version 1 --no-deps \
+                    | python3 -c 'import json,sys; print(next(p["version"] for p in json.load(sys.stdin)["packages"] if p["name"] == "mdka"))')
+          echo "workspace version: $version"
+
+          mapfile -t crates < <(ls target/package/*-"$version".crate)
+          if [ "${#crates[@]}" -ne 4 ]; then
+            echo "::error::expected 4 .crate files at $version, found ${#crates[@]}"
+            printf '  %s\n' "${crates[@]}"
+            exit 1
+          fi
+
+          for crate in "${crates[@]}"; do
+            echo "=== $crate"
+            tar -tzf "$crate" | sed 's/^/    /'
+          done

{mdka-2.2.2 → mdka-2.3.0}/.github/workflows/docs-example-gate.yaml

@@ -60,9 +60,13 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-cargo-docs-gate-
 
-      # The TypeScript examples are checked against the generated
-      # declarations, so those must exist and be current.
-      - name: Generate the TypeScript declarations
+      # Builds the native binding as well as the declarations, and BOTH are
+      # used: TypeScript examples type-check against index.d.ts, and JavaScript
+      # examples are EXECUTED against the built binding (RFC 031) -- a syntax
+      # check alone passed an example that failed at load. Without this step
+      # every JS example is reported as a failure ("no built binding"), so the
+      # gate goes red rather than quietly skipping execution.
+      - name: Build the Node binding and its TypeScript declarations
         working-directory: node
         run: |
           npm ci
@@ -88,7 +92,7 @@ jobs:
           python -m venv "$RUNNER_TEMP/docs-venv"
           "$RUNNER_TEMP/docs-venv/bin/pip" install --no-index "$RUNNER_TEMP"/wheels/mdka-*.whl
 
-      - name: Check every runnable example in docs/src/
+      - name: Check every runnable example in docs/src/ and README.md
         run: |
           python .github/workflows/scripts/check-docs-examples.py \
             --python "$RUNNER_TEMP/docs-venv/bin/python"

{mdka-2.2.2 → mdka-2.3.0}/.github/workflows/docs.yaml

@@ -31,8 +31,13 @@ jobs:
         id: pages
         uses: actions/configure-pages@v6
 
+      # Pinned exactly (RFC 033). The docs example gate models this mdBook: its
+      # wrapping of Rust examples, its hidden-line rule, and its copy button,
+      # which omits hidden lines. Before moving the pin, re-check all three in
+      # .github/workflows/scripts/check-docs-examples.py. 0.5.4 is what `^0.5`
+      # resolved to when pinned.
       - name: Install mdBook
-        run: cargo install mdbook --no-default-features --features search --vers "^0.5" --locked
+        run: cargo install mdbook --no-default-features --features search --vers "=0.5.4" --locked
 
       - name: Build book
         run: mdbook build

mdka-2.3.0/.github/workflows/pypi-published-gate.yaml

@@ -0,0 +1,114 @@
+name: pypi published gate
+
+# RFC 034 §4.4. Checks what PyPI actually serves for the latest release, the
+# way the npm install gate checks npm:
+#
+#   1. the published file set equals python/wheel-matrix.toml -- the same
+#      script release-pypi.yaml runs before upload, so the two cannot disagree;
+#   2. the release installs FROM PyPI, wheel only, at the declared floor and
+#      at the newest stable CPython, and converts;
+#   3. installation.md states the declared floor.
+#
+# Its own workflow file, not ci.yaml: the release workflows gate on ci.yaml's
+# conclusion, so a gate there can block the release that would make it pass
+# (RFC 020's correction record).
+#
+# `pypi wheel gate` is a different check: it installs a wheel BUILT FROM THE
+# TREE. This one reports on the LAST PUBLISHED release, so it lags the tree --
+# a published artifact cannot be verified before it is published.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  schedule:
+    # Catch a registry-side change even when nobody pushes.
+    - cron: '0 6 * * 1'
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  file-set:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      version: ${{ steps.pypi.outputs.version }}
+      floor: ${{ steps.floor.outputs.floor }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+
+      - name: Install packaging
+        run: python -m pip install packaging
+
+      - name: Read the latest release from PyPI
+        id: pypi
+        run: |
+          set -euo pipefail
+          curl -fsSL https://pypi.org/pypi/mdka/json -o "$RUNNER_TEMP/pypi.json"
+          version=$(python -c "import json,sys; print(json.load(open(sys.argv[1]))['info']['version'])" "$RUNNER_TEMP/pypi.json")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Read the declared floor
+        id: floor
+        run: echo "floor=$(python .github/workflows/scripts/check-wheel-matrix.py floor)" >> "$GITHUB_OUTPUT"
+
+      # Before applies-from this prints a ::notice:: and passes: the policy
+      # never governed that release. It is not silent, and it ends by itself
+      # when the first release under the policy publishes.
+      - name: Published file set equals the declared matrix
+        run: python .github/workflows/scripts/check-wheel-matrix.py published "$RUNNER_TEMP/pypi.json"
+
+      - name: installation.md states the declared floor
+        run: python .github/workflows/scripts/check-wheel-matrix.py floor-doc docs/src/getting-started/installation.md
+
+  install:
+    needs: [file-set]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        # The declared floor comes from wheel-matrix.toml via file-set; "3.x"
+        # is the newest stable CPython.
+        python: [floor, "3.x"]
+
+    steps:
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python == 'floor' && needs.file-set.outputs.floor || matrix.python }}
+
+      # --only-binary :all: is the point of this step. The runner has a Rust
+      # toolchain: without the flag a missing wheel falls back to building
+      # the sdist, the install succeeds, and the gate passes on exactly the
+      # defect it exists to catch.
+      - name: Install the published wheel from PyPI and convert
+        env:
+          VERSION: ${{ needs.file-set.outputs.version }}
+        run: |
+          set -euo pipefail
+          python -m venv "$RUNNER_TEMP/venv"
+          source "$RUNNER_TEMP/venv/bin/activate"
+          python --version
+          cd "$RUNNER_TEMP"
+          python -m pip install --only-binary :all: --no-cache-dir "mdka==${VERSION}"
+          python -c "
+          import mdka
+          out = mdka.html_to_markdown('<h1>x</h1>')
+          assert '# x' in out, repr(out)
+          print('OK: mdka', mdka.version(), 'installs from a wheel and converts:', repr(out))
+          "

{mdka-2.2.2 → mdka-2.3.0}/.github/workflows/release-pypi.yaml

@@ -78,10 +78,24 @@ jobs:
         with:
           working-directory: python
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter
+          # RFC 034: no --find-interpreter. PyO3's abi3-py310 feature makes one
+          # cp310-abi3 wheel valid on every CPython >= 3.10, so each job builds
+          # exactly one wheel instead of one per interpreter the runner happens
+          # to carry. The declared set is python/wheel-matrix.toml.
+          args: --release --out dist
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
           manylinux: auto
 
+      - name: Require exactly one wheel
+        run: |
+          set -euo pipefail
+          ls -la python/dist
+          count=$(find python/dist -maxdepth 1 -name '*.whl' | wc -l)
+          if [ "$count" -ne 1 ]; then
+            echo "::error::expected exactly 1 wheel in python/dist, found $count"
+            exit 1
+          fi
+
       - name: Upload wheels
         uses: actions/upload-artifact@v7
         with:
@@ -126,10 +140,24 @@ jobs:
         with:
           working-directory: python
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter
+          # RFC 034: no --find-interpreter. PyO3's abi3-py310 feature makes one
+          # cp310-abi3 wheel valid on every CPython >= 3.10, so each job builds
+          # exactly one wheel instead of one per interpreter the runner happens
+          # to carry. The declared set is python/wheel-matrix.toml.
+          args: --release --out dist
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
           manylinux: musllinux_1_2
 
+      - name: Require exactly one wheel
+        run: |
+          set -euo pipefail
+          ls -la python/dist
+          count=$(find python/dist -maxdepth 1 -name '*.whl' | wc -l)
+          if [ "$count" -ne 1 ]; then
+            echo "::error::expected exactly 1 wheel in python/dist, found $count"
+            exit 1
+          fi
+
       - name: Upload wheels
         uses: actions/upload-artifact@v7
         with:
@@ -173,9 +201,23 @@ jobs:
         with:
           working-directory: python
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter
+          # RFC 034: no --find-interpreter. PyO3's abi3-py310 feature makes one
+          # cp310-abi3 wheel valid on every CPython >= 3.10, so each job builds
+          # exactly one wheel instead of one per interpreter the runner happens
+          # to carry. The declared set is python/wheel-matrix.toml.
+          args: --release --out dist
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
 
+      - name: Require exactly one wheel
+        run: |
+          set -euo pipefail
+          ls -la python/dist
+          count=$(find python/dist -maxdepth 1 -name '*.whl' | wc -l)
+          if [ "$count" -ne 1 ]; then
+            echo "::error::expected exactly 1 wheel in python/dist, found $count"
+            exit 1
+          fi
+
       - name: Upload wheels
         uses: actions/upload-artifact@v7
         with:
@@ -218,9 +260,23 @@ jobs:
         with:
           working-directory: python
           target: ${{ matrix.platform.target }}
-          args: --release --out dist --find-interpreter
+          # RFC 034: no --find-interpreter. PyO3's abi3-py310 feature makes one
+          # cp310-abi3 wheel valid on every CPython >= 3.10, so each job builds
+          # exactly one wheel instead of one per interpreter the runner happens
+          # to carry. The declared set is python/wheel-matrix.toml.
+          args: --release --out dist
           sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
 
+      - name: Require exactly one wheel
+        run: |
+          set -euo pipefail
+          ls -la python/dist
+          count=$(find python/dist -maxdepth 1 -name '*.whl' | wc -l)
+          if [ "$count" -ne 1 ]; then
+            echo "::error::expected exactly 1 wheel in python/dist, found $count"
+            exit 1
+          fi
+
       - name: Upload wheels
         uses: actions/upload-artifact@v7
         with:
@@ -263,6 +319,10 @@ jobs:
       contents: read
 
     steps:
+      # For python/wheel-matrix.toml, pyproject.toml and the check script.
+      # Checked out before the download, so it cannot clean the artifacts away.
+      - uses: actions/checkout@v6
+
       - name: Install uv
         uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
 
@@ -279,6 +339,22 @@ jobs:
           find artifacts -type f \( -name '*.whl' -o -name '*.tar.gz' \) -exec cp -f {} dist/ \;
           ls -la dist
 
+      # RFC 034 §4.3. The last point where a wrong file set can be prevented:
+      # a PyPI filename can never be re-uploaded. Runs on tags AND on
+      # workflow_dispatch, so a dry run exercises it. `cp -f` above would let a
+      # same-named file from one job overwrite another's; with one wheel per
+      # job that cannot happen, and if it ever does it shows up here as a
+      # missing file. The published gate runs the same script after upload.
+      - name: Check distributables against the declared wheel matrix
+        env:
+          TAG: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }}
+        run: |
+          set -euo pipefail
+          tag_args=()
+          if [ -n "$TAG" ]; then tag_args=(--tag "$TAG"); fi
+          uv run --no-project --python 3.13 --with packaging -- \
+            python .github/workflows/scripts/check-wheel-matrix.py files --dir dist "${tag_args[@]}"
+
       - name: Publish to PyPI
         if: ${{ startsWith(github.ref, 'refs/tags/') }}
         run: uv publish dist/*