xsdkit 0.1.0__tar.gz

xsdkit-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# The fixture is a verbatim copy of a published W3C schema, and its diagnostics
+# carry line numbers into it. A checkout that rewrites LF to CRLF would not
+# shift those, but keeping the file byte-identical across platforms means a
+# failure on Windows is a real failure rather than a checkout artefact.
+tests/fixtures/** text eol=lf

xsdkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,198 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "develop"]
+  pull_request:
+    branches: ["main", "develop"]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check:
+    name: Check & Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - uses: Swatinem/rust-cache@v2
+      # Both workspaces: the fuzz crate has its own manifest, so the root
+      # `cargo fmt` does not see it.
+      - name: Format check
+        run: cargo fmt --check && cargo fmt --check --manifest-path fuzz/Cargo.toml
+      - name: Clippy
+        run: cargo clippy --all-targets -- -D warnings
+      # The bindings are behind a feature, so the default lint run never sees
+      # them. CI is the only thing that will.
+      - name: Clippy (python feature)
+        run: cargo clippy --all-targets --features python -- -D warnings
+      - name: Clippy (serde feature)
+        run: cargo clippy --all-targets --features serde -- -D warnings
+      # The fuzz crate is a separate workspace calling the public API
+      # directly, so it rots on any rename — and `--all-targets` above does
+      # not reach it. The fuzz job does compile it, but only after installing
+      # cargo-fuzz and building with sanitizers, minutes in. This is the same
+      # failure in about a second.
+      - name: Check the fuzz targets still build against the API
+        run: cargo check --manifest-path fuzz/Cargo.toml --bins
+
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Run tests
+        run: cargo test --all-targets
+      # `--all-targets` skips doctests, and the README-shaped examples in the
+      # crate docs are the first thing a new user copies.
+      - name: Run doctests
+        run: cargo test --doc
+      # The round trip is only checked when the feature is on, and a compiled
+      # schema is a graph of interned ids — exactly the thing a wire format
+      # can reorder without anyone noticing.
+      - name: Run tests (serde feature)
+        run: cargo test --all-targets --features serde
+      - name: Run doctests (serde feature)
+        run: cargo test --doc --features serde
+
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # Intra-doc links that point at private or renamed items are a warning,
+      # not an error, so they accumulate silently. Two had already crept in
+      # before this job existed. `-D warnings` makes them a failure.
+      - name: Build docs with warnings denied
+        env:
+          RUSTDOCFLAGS: -D warnings
+        run: cargo doc --no-deps --features serde
+      # `cargo test --doc` only sees the examples inside `src/`. The ones on
+      # the website and in the README had drifted for a whole afternoon after
+      # a rename before anything noticed.
+      - name: Check the Rust snippets in the Markdown docs
+        run: python3 scripts/check-doc-snippets.py
+
+  python:
+    name: Python (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # `pip install .` goes through the maturin backend, which turns on the
+      # `extension-module` feature. Installing the wheel rather than using
+      # `maturin develop` keeps this identical to what a user gets.
+      - name: Build and install the wheel
+        run: pip install .
+      # IPython is a test dependency: the notebook-rendering tests format
+      # through its own `DisplayFormatter` rather than trusting `_repr_html_`.
+      - name: Run the Python tests
+        run: pip install pytest ipython && pytest python/tests -q
+      # The Python examples on the website all run against
+      # `docs/examples/report.xsd`, so they can be run rather than merely
+      # parsed. Several of them did not, for want of an `import`.
+      - name: Run the Python snippets in the Markdown docs
+        run: python3 scripts/check-doc-snippets-python.py
+
+  semver:
+    name: Semver
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # Compares the working tree against the newest version on crates.io, so
+      # it had nothing to say until 0.1.0 was published. It catches the
+      # breaking change nobody meant to make — a field added to one of the
+      # component structs, which are public on purpose because this is a model
+      # to be read, and are therefore breaking to construct by literal.
+      #
+      # Deliberate breakage is fine and expected before 1.0: bump the minor
+      # version, which under Cargo's 0.x rules is the major, and this passes.
+      #
+      # Not `all-features`: that would turn on `extension-module`, which links
+      # libpython and is only correct when building a wheel. The published API
+      # surface is the default one plus `serde`, which is what docs.rs builds.
+      - uses: obi1kenobi/cargo-semver-checks-action@v2
+        with:
+          feature-group: only-explicit-features
+          features: serde
+
+  msrv:
+    name: MSRV
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      # `rust-version` in Cargo.toml is a promise to anyone whose toolchain is
+      # older than ours. Nothing enforces it at publish time, so a claim that is
+      # never compiled is a claim that is wrong sooner or later.
+      - name: Read rust-version from Cargo.toml
+        id: msrv
+        run: |
+          version=$(grep -m1 '^rust-version' Cargo.toml | cut -d'"' -f2)
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "MSRV is $version"
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ steps.msrv.outputs.version }}
+      - uses: Swatinem/rust-cache@v2
+      # Check rather than test: the MSRV promise covers compiling the crate,
+      # and dev-dependencies routinely need a newer toolchain than the library.
+      - name: Check on the declared MSRV
+        run: cargo check --all-targets
+
+  fuzz:
+    name: Fuzz (smoke)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: |
+            . -> target
+            fuzz -> fuzz/target
+      - name: Install cargo-fuzz
+        run: cargo install cargo-fuzz --locked
+      # The check job compiles these too, and faster; this builds them with
+      # sanitizers, which is a different thing and can fail on its own. The
+      # short run is a bonus, and finds nothing subtle
+      # because the corpus is not vendored (it is derived from the W3C suite,
+      # which is 231 MB). Real campaigns are run locally for minutes to hours.
+      - name: Build the fuzz targets
+        run: cargo fuzz build
+      - name: Smoke-run each target
+        run: |
+          for t in $(cargo fuzz list); do
+            echo "::group::$t"
+            cargo fuzz run "$t" -- -max_total_time=30 -timeout=10 -rss_limit_mb=4096
+            echo "::endgroup::"
+          done
+
+# Two gates are deliberately absent until they would say something:
+#
+#   public-api — a checked-in API snapshot is the right gate for a stable
+#                crate. This one changes shape every phase through P6, so the
+#                snapshot would be noise that trains people to ignore it.
+#                Add it at 1.0.
+#   codspeed   — there are no benchmarks yet. Add it with the first one, which
+#                will most likely be schema compilation on a large schema.

xsdkit-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  # So the site can be republished without an empty commit.
+  workflow_dispatch:
+
+# One in-flight deployment at a time, and let a newer commit win rather than
+# queueing a site nobody wants any more.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build the site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      # The Python reference is generated from the built extension module, not
+      # from the type stub alone: the stub has the annotations and the compiled
+      # module has the prose. Both halves have to be present.
+      - name: Build and install the wheel
+        run: pip install .
+
+      - name: Install the docs toolchain
+        run: pip install -r docs/requirements.txt
+
+      # `--strict` inside the script turns a broken link into a failed build,
+      # and RUSTDOCFLAGS=-D warnings does the same for the Rust half.
+      - name: Build
+        run: ./scripts/build-docs.sh
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to Pages
+    # A pull request should prove the site still builds without publishing it.
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,162 @@
+name: Release
+
+# Tagging is the trigger, and the tag is the version: `pyproject.toml` takes
+# its version dynamically from `Cargo.toml`, so there is one number to bump
+# and the guard below refuses a tag that disagrees with it.
+#
+# `workflow_dispatch` builds every wheel without publishing anything, which is
+# how you check a platform matrix change before it is attached to a version
+# that can never be reused.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  guard:
+    name: Tag matches Cargo.toml
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      # A tag that does not match the manifest publishes a wheel whose
+      # filename disagrees with its own metadata, and the version is burned
+      # either way: PyPI and crates.io both refuse to reuse one.
+      - name: Compare the tag with the manifest
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          manifest=$(grep -m1 '^version' Cargo.toml | cut -d'"' -f2)
+          echo "tag: $tag   Cargo.toml: $manifest"
+          if [ "$tag" != "$manifest" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match Cargo.toml version $manifest"
+            exit 1
+          fi
+
+  sdist:
+    name: Source distribution
+    needs: guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-sdist
+          path: dist
+
+  wheels:
+    name: Wheel (${{ matrix.label }})
+    needs: guard
+    runs-on: ${{ matrix.os }}
+    # Every row above finishes in under three minutes. This bounds a hung
+    # build, not a queued one — waiting for a runner is not job time, and
+    # GitHub alone decides when to give up on that.
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      # One wheel per platform, not per platform *and* Python version: the
+      # extension is built against the stable ABI (`abi3-py39`), so a single
+      # wheel serves 3.9 through whatever ships next.
+      # `native: true` marks the rows whose wheel the runner can actually
+      # install. The cross-compiled and musl rows cannot run where they are
+      # built, so they are proven by building, and by whoever installs them.
+      #
+      # Both macOS wheels are built on the arm64 runner. There is no hosted
+      # free Intel macOS image any more — `macos-13` was retired, and a job
+      # asking for it does not fail, it queues until GitHub gives up, which
+      # is how it cost this release 45 minutes. Cross-compiling to
+      # `x86_64-apple-darwin` needs no second runner: one Xcode SDK carries
+      # both slices.
+      matrix:
+        include:
+          - { label: linux-x86_64, os: ubuntu-latest, target: x86_64, manylinux: auto, native: true }
+          - { label: linux-aarch64, os: ubuntu-latest, target: aarch64, manylinux: auto, native: false }
+          - { label: musl-x86_64, os: ubuntu-latest, target: x86_64, manylinux: musllinux_1_2, native: false }
+          - { label: musl-aarch64, os: ubuntu-latest, target: aarch64, manylinux: musllinux_1_2, native: false }
+          - { label: macos-x86_64, os: macos-latest, target: x86_64, manylinux: auto, native: false }
+          - { label: macos-aarch64, os: macos-latest, target: aarch64, manylinux: auto, native: true }
+          - { label: windows-x64, os: windows-latest, target: x64, manylinux: auto, native: true }
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux }}
+          args: --release --out dist
+          sccache: "true"
+      # Building a wheel proves it links, not that it works. The suite is in
+      # the checkout and the wheel is the thing users install, so run one
+      # against the other. The cross-compiled and musl rows cannot execute
+      # here; they are proven by building, and by whoever installs them.
+      - name: Test the wheel it just built
+        if: matrix.native
+        shell: bash
+        run: |
+          python -m pip install --find-links dist --no-index xsdkit
+          python -m pip install pytest ipython
+          # From a directory that is not the repo root, so the import resolves
+          # to the installed wheel and not to `python/xsdkit`, which holds the
+          # sources without the compiled extension.
+          cd "$RUNNER_TEMP"
+          python -c "import xsdkit; print('testing', xsdkit.__version__, 'from', xsdkit.__file__)"
+          python -m pytest "$GITHUB_WORKSPACE/python/tests" -q
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ matrix.label }}
+          path: dist
+
+  pypi:
+    name: Publish to PyPI
+    # Only a tag publishes. A manual run stops at the artifacts above, which
+    # is the point of being able to trigger it manually.
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [sdist, wheels]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/xsdkit
+    permissions:
+      # Trusted Publishing: the job mints a short-lived OIDC token per run and
+      # there is no API token stored anywhere to leak.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-*
+          merge-multiple: true
+          path: dist
+      - run: ls -la dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub release
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-*
+          merge-multiple: true
+          path: dist
+      # `pyproject.toml` advertises this page as the changelog, so it has to
+      # exist and has to carry the artifacts.
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+
+# The crate is published by hand: `cargo publish` is irreversible — a version
+# can be yanked but never deleted, and the name is claimed for good — so the
+# first one gets a human. See the release checklist in AGENTS.md.

xsdkit-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+/target
+**/*.rs.bk
+*.pdb
+.DS_Store
+/python/dist
+/python/.venv
+__pycache__/
+
+# Python
+/.venv
+/python/xsdkit/*.so
+/python/xsdkit/*.pyd
+.pytest_cache/
+*.egg-info/
+
+# Staged rustdoc, mounted into the docs site by scripts/build-docs.sh
+docs/rust/
+site/
+
+# Written and deleted by scripts/check-doc-snippets.py; only exists while it runs.
+/examples/doc_snippets.rs