struct-frame 0.8.4__tar.gz → 0.9.0__tar.gz

struct_frame-0.9.0/.github/workflows/api-stability.yml

@@ -0,0 +1,39 @@
+name: API Stability
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: api-stability-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  api-stability:
+    name: Public API compatibility
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+      - name: Install Python dependencies
+        run: pip install proto-schema-parser
+      - name: Run Python API stability
+        run: PYTHONPATH=src python tests/api_stability/python/test_api_stability.py
+      - name: Run npm API scaffold
+        run: node tests/api_stability/npm/check_api.js
+      - name: Run NuGet API scaffold
+        run: python tests/api_stability/nuget/check_api.py
+      - name: Run crates.io API scaffold
+        run: python tests/api_stability/crates/check_api.py

struct_frame-0.9.0/.github/workflows/benchmark-regression.yml

@@ -0,0 +1,48 @@
+name: Benchmark Regression
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: benchmark-regression-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  benchmark-regression:
+    name: Benchmark regression smoke
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc g++ build-essential
+      - name: Install Python dependencies
+        run: pip install proto-schema-parser
+      - name: Install TypeScript dependencies
+        run: npm ci
+        working-directory: tests/ts
+      - name: Run benchmark smoke
+        run: python tests/benchmarks/run_all.py --quick
+      - name: Check regressions
+        run: python tests/benchmarks/check_regression.py --allow-missing-baseline
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: tests/benchmarks/results/

struct_frame-0.9.0/.github/workflows/coverage.yml

@@ -0,0 +1,55 @@
+name: Coverage
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: coverage-${{ github.sha }}
+  cancel-in-progress: true
+
+# Tier C item 1: coverage instrumentation.  This workflow lands the Codecov
+# plumbing using Python (`coverage.py`) as the first language; gcov+lcov,
+# c8/nyc, coverlet, and cargo-llvm-cov plug into the same `codecov-action`
+# step in follow-up PRs.
+
+jobs:
+  python-coverage:
+    name: Python (coverage.py)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install proto-schema-parser coverage hypothesis pytest
+      - name: Generate code (required by property tests)
+        run: python test_all.py --only-generate --skip-lang csharp --skip-lang rust
+      - name: Run Python suite under coverage
+        # Coverage focuses on the generator (src/struct_frame), which is what
+        # Python tooling can instrument end-to-end.  The generated message
+        # modules under tests/generated/py are imported by the property test
+        # and contribute incidentally.  Failures here propagate so Codecov's
+        # `fail_ci_if_error: false` is the only suppression knob.
+        run: |
+          coverage run --source=src/struct_frame --branch \
+              -m pytest tests/test_property_roundtrip.py -v
+          coverage run --source=src/struct_frame --branch --append \
+              tests/test_generator_validation.py
+          coverage xml -o coverage.xml
+          coverage report --skip-covered --skip-empty
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          flags: python
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

struct_frame-0.9.0/.github/workflows/doc-samples.yml

@@ -0,0 +1,39 @@
+name: Documentation Samples
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: doc-samples-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  doc-samples:
+    name: Doctest-style sample compilation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc g++ build-essential
+      - name: Install TypeScript dependencies
+        run: npm ci
+        working-directory: tests/ts
+      - name: Extract samples
+        run: python tests/docs/extract_samples.py
+      - name: Compile documentation samples
+        run: python tests/docs/run_samples.py --quick

struct_frame-0.9.0/.github/workflows/fuzz.yml

@@ -0,0 +1,72 @@
+name: Fuzz (short)
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: fuzz-${{ github.sha }}
+  cancel-in-progress: true
+
+# Short per-push smoke fuzzer: 60 seconds per harness, intended only to catch
+# regressions that surface immediately.  Long-running corpus growth happens
+# upstream once the project is submitted to OSS-Fuzz (tracked as a follow-up).
+
+jobs:
+  fuzz-c-parser:
+    name: libFuzzer / C accumulating-reader
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - name: Install clang
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang llvm
+      - name: Build C fuzz harness
+        run: |
+          mkdir -p tests/c/build
+          clang -O1 -g -fsanitize=fuzzer,address,undefined \
+                -fno-sanitize-recover=all \
+                -I src/struct_frame/boilerplate/c \
+                tests/c/fuzz_parser.c -o tests/c/build/fuzz_parser
+      - name: Run libFuzzer for 60 s
+        env:
+          ASAN_OPTIONS: "abort_on_error=1:halt_on_error=1"
+          UBSAN_OPTIONS: "print_stacktrace=1:halt_on_error=1"
+        run: |
+          mkdir -p tests/c/build/fuzz_corpus
+          tests/c/build/fuzz_parser -max_total_time=60 -max_len=4096 \
+                                    tests/c/build/fuzz_corpus
+      - name: Upload corpus and any crashes
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fuzz-c-corpus
+          path: |
+            tests/c/build/fuzz_corpus
+            crash-*
+            leak-*
+            timeout-*
+          if-no-files-found: ignore
+          retention-days: 7
+
+  fuzz-py-parser:
+    name: atheris / Python AccumulatingReader
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - name: Install atheris
+        # atheris ships a wheel for cpython 3.11 on linux/x86_64.
+        run: pip install atheris
+      - name: Run atheris for 60 s
+        run: python tests/py/fuzz_parser.py -max_total_time=60 -max_len=4096

struct_frame-0.9.0/.github/workflows/sanitizers.yml

@@ -0,0 +1,158 @@
+name: Sanitizers
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: sanitizers-${{ github.sha }}
+  cancel-in-progress: true
+
+# All jobs run the full test suite via `python test_all.py`.  C/C++ compile
+# commands in tests/run_tests.py honor $CC/$CXX/$CFLAGS/$CXXFLAGS/$LDFLAGS, so
+# the only thing each job has to do is export the right toolchain + flags.
+#
+# We deliberately skip language slices that have nothing to do with the
+# instrumented C/C++ binaries (Rust/.NET) using --skip-lang to keep wall time
+# manageable and avoid noise from unrelated toolchains.
+
+jobs:
+  asan-ubsan:
+    name: AddressSanitizer + UndefinedBehaviorSanitizer (C / C++)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      CC: clang
+      CXX: clang++
+      # -fno-sanitize-recover so any UB aborts the test process with a
+      # non-zero status and is reported by run_tests.py.
+      CFLAGS: "-O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined -fno-sanitize-recover=all"
+      CXXFLAGS: "-O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined -fno-sanitize-recover=all"
+      LDFLAGS: "-fsanitize=address,undefined"
+      ASAN_OPTIONS: "detect_leaks=1:abort_on_error=1:halt_on_error=1:strict_string_checks=1:detect_stack_use_after_return=1"
+      UBSAN_OPTIONS: "print_stacktrace=1:halt_on_error=1"
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - name: Install toolchain
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang llvm
+          pip install proto-schema-parser
+          (cd tests/ts && npm ci)
+      - name: Run C / C++ suite under ASan + UBSan
+        run: python test_all.py --skip-lang csharp --skip-lang rust
+
+  tsan:
+    name: ThreadSanitizer (C++ SDK)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      CC: clang
+      CXX: clang++
+      CFLAGS:   "-O1 -g -fno-omit-frame-pointer -fsanitize=thread"
+      CXXFLAGS: "-O1 -g -fno-omit-frame-pointer -fsanitize=thread"
+      LDFLAGS:  "-fsanitize=thread"
+      TSAN_OPTIONS: "halt_on_error=1:second_deadlock_stack=1"
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - name: Install toolchain
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang llvm
+          pip install proto-schema-parser
+          (cd tests/ts && npm ci)
+      - name: Run C / C++ suite under TSan
+        # TSan is mutually exclusive with ASan; the SDK subscribe / streaming
+        # tests are where the threading races would surface.
+        run: python test_all.py --skip-lang csharp --skip-lang rust
+
+  valgrind-c:
+    name: Valgrind memcheck (C only)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      CC: gcc
+      # No sanitizer flags — Valgrind instruments at run time.  -O0 -g keeps
+      # the line numbers in error reports useful.
+      CFLAGS: "-O0 -g"
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - name: Install Valgrind
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y valgrind gcc build-essential
+          pip install proto-schema-parser
+      - name: Build C binaries (compile only, no run)
+        # --only-compile produces all language artifacts; we only execute the
+        # C ones below under Valgrind.  Other languages' compile failures are
+        # not relevant to this job, so we tolerate a non-zero exit here and
+        # rely on the subsequent "no C binaries produced" guard to fail loudly
+        # if the C portion didn't build.
+        run: python test_all.py --only-compile || echo "non-C languages may have failed; continuing"
+      - name: Run C binaries under Valgrind
+        # Run every produced C test binary under memcheck.  --error-exitcode=1
+        # converts any leak / invalid-access into a non-zero CI status.
+        run: |
+          set -e
+          shopt -s nullglob
+          found=0
+          tmp_dir="$(mktemp -d)"
+          trap 'rm -rf "$tmp_dir"' EXIT
+          for exe in tests/c/build/test_*; do
+            [ -x "$exe" ] || continue
+            found=1
+            echo "=== valgrind $exe ==="
+            case "$(basename "$exe")" in
+              test_standard|test_standard.exe)
+                valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all \
+                         --errors-for-leak-kinds=definite,possible \
+                         --track-origins=yes "$exe" encode standard "$tmp_dir/standard.bin"
+                valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all \
+                         --errors-for-leak-kinds=definite,possible \
+                         --track-origins=yes "$exe" decode standard "$tmp_dir/standard.bin"
+                ;;
+              test_extended|test_extended.exe)
+                valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all \
+                         --errors-for-leak-kinds=definite,possible \
+                         --track-origins=yes "$exe" encode bulk "$tmp_dir/extended.bin"
+                valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all \
+                         --errors-for-leak-kinds=definite,possible \
+                         --track-origins=yes "$exe" decode bulk "$tmp_dir/extended.bin"
+                ;;
+              test_variable_flag|test_variable_flag.exe)
+                valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all \
+                         --errors-for-leak-kinds=definite,possible \
+                         --track-origins=yes "$exe" encode bulk "$tmp_dir/variable.bin"
+                valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all \
+                         --errors-for-leak-kinds=definite,possible \
+                         --track-origins=yes "$exe" decode bulk "$tmp_dir/variable.bin"
+                ;;
+              *)
+                valgrind --error-exitcode=1 --leak-check=full --show-leak-kinds=all \
+                         --errors-for-leak-kinds=definite,possible \
+                         --track-origins=yes "$exe"
+                ;;
+            esac
+          done
+          if [ "$found" -eq 0 ]; then
+            echo "No C test binaries were built; nothing to check." >&2
+            exit 1
+          fi

struct_frame-0.9.0/.github/workflows/test.yml

@@ -0,0 +1,233 @@
+name: Test Suite
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: test-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  # Primary job: full suite on Ubuntu / pinned tool versions.  Acts as the
+  # gating check and produces the canonical `test-results` artifact.
+  test:
+    name: Run Test Suite (ubuntu / py3.11 / node20 / dotnet10)
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Set up .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "10.0.x"
+          dotnet-quality: "preview"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc g++ build-essential
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install proto-schema-parser
+
+      - name: Install Node.js dependencies
+        run: npm ci
+        working-directory: tests/ts
+
+      - name: Run test suite
+        run: python test_all.py
+
+      - name: Check generated-file determinism
+        run: python tests/check_determinism.py --verbose
+
+      - name: Check wire-format goldens
+        run: python tests/check_golden.py --verbose
+
+      - name: Check test-coverage doc is up to date
+        run: python tests/gen_test_coverage.py --check
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: |
+            tests/generated/
+            tests/c/build/
+            tests/cpp/build/
+            tests/py/build/
+          retention-days: 5
+
+  # Cross-OS matrix: confirm the suite is portable to macOS.  Each runner
+  # only exercises languages whose toolchains are present out of the box,
+  # so we drop .NET on macOS to avoid spending the matrix on installer flakes.
+  # Windows is intentionally not in the matrix — `tests/run_tests.py` uses
+  # POSIX-style shell quoting and many compile invocations would need
+  # individual debugging.  Tracked as a follow-up.
+  os-matrix:
+    name: ${{ matrix.os }} (py3.11)
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - name: Install Python deps
+        run: pip install proto-schema-parser
+      - name: Install Node deps
+        run: npm ci
+        working-directory: tests/ts
+      - name: Run test suite (skip C# — no .NET 10 SDK on macOS runner)
+        run: python test_all.py --skip-lang csharp
+
+  # Python version matrix: catch interpreter-specific regressions.  We skip
+  # the heavier compiled-language phases via --skip-lang to keep wall time
+  # to ~ the time of the Python phase itself.
+  python-matrix:
+    name: python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - name: Install Python deps
+        run: pip install proto-schema-parser
+      - name: Install Node deps
+        run: npm ci
+        working-directory: tests/ts
+      - name: Run Python + C suite
+        run: python test_all.py --skip-lang csharp --skip-lang rust
+
+  # Node version matrix: focused JS/TS validation against supported LTS lines.
+  node-matrix:
+    name: node ${{ matrix.node }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ["18", "20", "22"]
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install Python deps
+        run: pip install proto-schema-parser
+      - name: Install Node deps
+        run: npm ci
+        working-directory: tests/ts
+      - name: Run JS + TS suite
+        run: python test_all.py --skip-lang csharp --skip-lang rust
+
+  # .NET SDK matrix: 8 (LTS) and 10 (preview, current dev target).
+  dotnet-matrix:
+    name: dotnet ${{ matrix.dotnet }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - dotnet: "8.0.x"
+            quality: "ga"
+          - dotnet: "10.0.x"
+            quality: "preview"
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ matrix.dotnet }}
+          dotnet-quality: ${{ matrix.quality }}
+      - name: Install Python deps
+        run: pip install proto-schema-parser
+      - name: Run C# slice
+        # The .NET 8 run will fail if any generated csproj pins net10.0
+        # exclusively — this matrix exists precisely to surface that.
+        # Allowed to fail today via continue-on-error; flip when the gap
+        # documented in test-coverage.md §8 is closed.
+        continue-on-error: ${{ matrix.dotnet == '8.0.x' }}
+        run: python test_all.py --skip-lang rust
+
+  # Compiler matrix: GCC vs Clang for the C / C++ binaries.
+  compiler-matrix:
+    name: ${{ matrix.cc }} / ${{ matrix.cxx }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - cc: gcc
+            cxx: g++
+            pkg: gcc
+          - cc: clang
+            cxx: clang++
+            pkg: clang
+    env:
+      CC: ${{ matrix.cc }}
+      CXX: ${{ matrix.cxx }}
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - name: Install compiler
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ${{ matrix.pkg }} build-essential
+          pip install proto-schema-parser
+          (cd tests/ts && npm ci)
+      - name: Run C / C++ suite under ${{ matrix.cc }}
+        run: python test_all.py --skip-lang csharp --skip-lang rust

struct_frame-0.9.0/.github/workflows/wireshark-dissector.yml

@@ -0,0 +1,29 @@
+name: Wireshark Dissector
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: wireshark-dissector-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  wireshark:
+    name: Golden pcap dissection
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with: { submodules: true }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - name: Install tshark
+        run: |
+          sudo apt-get update
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y tshark
+      - name: Run dissector tests
+        run: python wireshark/test_dissector.py