openxml-audit 0.2.0__tar.gz

openxml_audit-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: BramAlkema

openxml_audit-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: Bug report
+description: Report a validation issue or unexpected behavior
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened vs what you expected
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Command or code to reproduce the issue
+      render: bash
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "Output of: openxml-audit --version"
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: "Output of: python --version"
+  - type: dropdown
+    id: file-type
+    attributes:
+      label: File type
+      options:
+        - PPTX
+        - DOCX
+        - XLSX
+        - ODT
+        - ODS
+        - ODP
+        - Other

openxml_audit-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,16 @@
+name: Feature request
+description: Suggest a new validation rule or feature
+labels: [enhancement]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What would you like added or changed?
+    validations:
+      required: true
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: Why is this needed? What problem does it solve?

openxml_audit-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What
+
+<!-- Brief description of the change -->
+
+## Why
+
+<!-- Why is this change needed? -->
+
+## Testing
+
+- [ ] `pytest` passes
+- [ ] `ruff check src/ tests/` clean
+- [ ] `mypy src/openxml_audit` clean

openxml_audit-0.2.0/.github/workflows/calibrate-parity.yml

@@ -0,0 +1,112 @@
+name: Calibrate parity
+
+on:
+  workflow_dispatch:
+    inputs:
+      sdk_ref:
+        description: "Open XML SDK tag/branch to calibrate against"
+        required: true
+        default: "v3.4.1"
+  schedule:
+    - cron: "17 2 * * 1"
+
+jobs:
+  calibrate:
+    runs-on: ubuntu-latest
+    env:
+      SDK_REF: ${{ inputs.sdk_ref || 'v3.4.1' }}
+      SDK_REPO: https://github.com/dotnet/Open-XML-SDK.git
+      SDK_ROOT: /tmp/openxml-sdk-upstream
+      CORPUS_ROOT: /tmp/openxml-sdk-seed
+      RUNTIME_MANIFEST: /tmp/openxml-runtime-manifest.json
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Fetch Open XML SDK
+        run: |
+          rm -rf "$SDK_ROOT"
+          git clone --depth 1 --branch "$SDK_REF" "$SDK_REPO" "$SDK_ROOT"
+          git -C "$SDK_ROOT" rev-parse HEAD | tee /tmp/openxml-sdk-commit.txt
+          printf '%s\n' "$SDK_REF" > /tmp/openxml-sdk-ref.txt
+
+      - name: Materialize SDK corpus (runtime only)
+        run: |
+          rm -rf "$CORPUS_ROOT"
+          python scripts/corpus/import_sdk_assets.py \
+            --sdk-root "$SDK_ROOT" \
+            --output-root "$CORPUS_ROOT"
+
+      - name: Build runtime manifest with extracted expectations
+        run: |
+          cp data/corpus/sdk_seed/manifest.json "$RUNTIME_MANIFEST"
+          python scripts/corpus/extract_sdk_expectations.py \
+            --sdk-root "$SDK_ROOT" \
+            --manifest "$RUNTIME_MANIFEST" \
+            --output "$RUNTIME_MANIFEST"
+
+      - name: Run parity snapshot
+        run: |
+          mkdir -p reports
+          python scripts/corpus/run_parity_snapshot.py \
+            --manifest "$RUNTIME_MANIFEST" \
+            --files-root "$CORPUS_ROOT/files" \
+            --output reports/parity_snapshot.json
+
+      - name: Upload parity artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: parity-calibration
+          path: |
+            reports/parity_snapshot.json
+            /tmp/openxml-runtime-manifest.json
+
+      - name: Workflow summary
+        if: always()
+        run: |
+          python - <<'PY'
+          import json
+          from pathlib import Path
+
+          report = Path("reports/parity_snapshot.json")
+          if not report.exists():
+              print("No parity snapshot produced.")
+              raise SystemExit(0)
+
+          data = json.loads(report.read_text(encoding="utf-8"))
+          lines = [
+              "# Parity Calibration Summary",
+              f"- SDK ref: {Path('/tmp/openxml-sdk-ref.txt').read_text(encoding='utf-8').strip()}",
+              f"- SDK commit: {Path('/tmp/openxml-sdk-commit.txt').read_text(encoding='utf-8').strip()}",
+              f"- Checks total: {data.get('checks_total', 0)}",
+              f"- Matched: {data.get('checks_matched', 0)}",
+              f"- Mismatched: {data.get('checks_mismatched', 0)}",
+              f"- Match rate: {data.get('match_rate_percent', 0)}%",
+          ]
+
+          families = data.get("mismatch_families") or []
+          if families:
+              lines.append("")
+              lines.append("## Top mismatch families")
+              for row in families[:10]:
+                  lines.append(f"- {row.get('count', 0)}x {row.get('description', '')}")
+
+          Path("/tmp/parity_summary.md").write_text("\n".join(lines), encoding="utf-8")
+          PY
+          cat /tmp/parity_summary.md >> "$GITHUB_STEP_SUMMARY"

openxml_audit-0.2.0/.github/workflows/odf-reference-calibration.yml

@@ -0,0 +1,151 @@
+name: ODF reference calibration
+
+on:
+  workflow_dispatch:
+    inputs:
+      odf_toolkit_ref:
+        description: "ODF Toolkit git ref to build."
+        required: false
+        default: "v0.13.0"
+      opf_ref:
+        description: "OPF validator git ref to build."
+        required: false
+        default: "v0.20-alpha-2"
+  schedule:
+    # Quarterly: 1st of Jan, Apr, Jul, Oct at 03:00 UTC
+    - cron: "0 3 1 1,4,7,10 *"
+
+jobs:
+  odf-reference-drift:
+    runs-on: ubuntu-latest
+    env:
+      BASELINE_COMPARE: data/odf/reference_baseline/2026-03-09/mismatch_report.json
+      POLICY_FILE: data/odf/reference_baseline/2026-03-09/drift_policy.json
+      WAIVERS_FILE: data/odf/reference_baseline/2026-03-09/waivers.json
+      RUN_REPORT: reports/odf/reference_runs.json
+      COMPARE_REPORT: reports/odf/reference_compare.json
+      COMPARE_SUMMARY: reports/odf/reference_compare.md
+      TRIAGE_REPORT: reports/odf/mismatch_triage.md
+      DRIFT_REPORT: reports/odf/reference_drift.json
+      DRIFT_SUMMARY: /tmp/odf_reference_drift.md
+      ODF_TOOLKIT_REF: ${{ github.event.inputs.odf_toolkit_ref || 'v0.13.0' }}
+      OPF_REF: ${{ github.event.inputs.opf_ref || 'v0.20-alpha-2' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Install Maven
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y maven
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Prepare reports directory
+        run: mkdir -p reports/odf
+
+      - name: Bootstrap reference validators
+        id: bootstrap
+        run: |
+          python scripts/odf/bootstrap_reference_validators.py \
+            --work-root /tmp/openxml_audit_odf_reference_tools \
+            --odf-toolkit-ref "$ODF_TOOLKIT_REF" \
+            --opf-ref "$OPF_REF" \
+            --output-json /tmp/odf_reference_tools.json
+
+          cp /tmp/odf_reference_tools.json reports/odf/reference_tooling.json
+
+          python - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          payload = json.loads(Path("/tmp/odf_reference_tools.json").read_text(encoding="utf-8"))
+          output_path = Path(os.environ["GITHUB_OUTPUT"])
+          with output_path.open("a", encoding="utf-8") as fh:
+            for key, value in {
+              "odf_toolkit_cmd": payload["odf_toolkit_cmd"],
+              "opf_cmd": payload["opf_cmd"],
+              "odf_toolkit_repo": payload["odf_toolkit"]["repo"],
+              "odf_toolkit_ref": payload["odf_toolkit"]["ref"],
+              "opf_repo": payload["opf"]["repo"],
+              "opf_ref": payload["opf"]["ref"],
+            }.items():
+              fh.write(f"{key}<<EOF\n{value}\nEOF\n")
+          PY
+
+      - name: Run ODF reference validators
+        run: |
+          python scripts/odf/run_reference_validators.py \
+            --corpus-manifest data/odf/reference_corpus/manifest.json \
+            --output "$RUN_REPORT" \
+            --odf-toolkit-cmd "${{ steps.bootstrap.outputs.odf_toolkit_cmd }}" \
+            --opf-cmd "${{ steps.bootstrap.outputs.opf_cmd }}"
+
+      - name: Compare reference results
+        run: |
+          python scripts/odf/compare_reference_results.py \
+            --input "$RUN_REPORT" \
+            --output "$COMPARE_REPORT" \
+            --summary "$COMPARE_SUMMARY"
+
+      - name: Build mismatch triage
+        run: |
+          python scripts/odf/build_mismatch_triage.py \
+            --compare "$COMPARE_REPORT" \
+            --runs "$RUN_REPORT" \
+            --output "$TRIAGE_REPORT"
+
+      - name: Enforce reference drift policy
+        run: |
+          python scripts/odf/check_reference_drift.py \
+            --baseline "$BASELINE_COMPARE" \
+            --current "$COMPARE_REPORT" \
+            --policy "$POLICY_FILE" \
+            --waivers "$WAIVERS_FILE" \
+            --output "$DRIFT_REPORT" \
+            --summary "$DRIFT_SUMMARY"
+
+      - name: Upload reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: odf-reference-calibration
+          path: reports/odf
+
+      - name: Workflow summary
+        if: always()
+        run: |
+          {
+            echo "# ODF Reference Calibration";
+            echo "- ODF Toolkit: ${{ steps.bootstrap.outputs.odf_toolkit_repo }} @ ${{ steps.bootstrap.outputs.odf_toolkit_ref }}";
+            echo "- OPF: ${{ steps.bootstrap.outputs.opf_repo }} @ ${{ steps.bootstrap.outputs.opf_ref }}";
+            echo "";
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          if [ -f "$DRIFT_SUMMARY" ]; then
+            cat "$DRIFT_SUMMARY" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "No ODF drift summary produced." >> "$GITHUB_STEP_SUMMARY"
+          fi
+          if [ -f "$TRIAGE_REPORT" ]; then
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            cat "$TRIAGE_REPORT" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "No ODF mismatch triage report produced." >> "$GITHUB_STEP_SUMMARY"
+          fi

openxml_audit-0.2.0/.github/workflows/pages.yml

@@ -0,0 +1,90 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "README.md"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build site
+        run: |
+          mkdir -p _site
+          cp README.md _site/index.md
+          cp -r docs/* _site/
+
+          # Convert markdown to HTML with a minimal template
+          pip install markdown
+          python - <<'PY'
+          import markdown
+          from pathlib import Path
+
+          site = Path("_site")
+          template = """<!DOCTYPE html>
+          <html><head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>{title} - openxml-audit</title>
+          <style>
+          body {{ max-width: 800px; margin: 40px auto; padding: 0 20px; font-family: -apple-system, sans-serif; line-height: 1.6; color: #333; }}
+          pre {{ background: #f5f5f5; padding: 16px; overflow-x: auto; border-radius: 4px; }}
+          code {{ background: #f5f5f5; padding: 2px 6px; border-radius: 3px; font-size: 0.9em; }}
+          pre code {{ background: none; padding: 0; }}
+          table {{ border-collapse: collapse; width: 100%; }}
+          th, td {{ border: 1px solid #ddd; padding: 8px; text-align: left; }}
+          th {{ background: #f5f5f5; }}
+          a {{ color: #0366d6; }}
+          nav {{ margin-bottom: 2em; padding-bottom: 1em; border-bottom: 1px solid #eee; }}
+          nav a {{ margin-right: 1em; }}
+          </style>
+          </head><body>
+          <nav><a href="./">Home</a><a href="./parity_contract.html">OOXML Parity</a><a href="./odf_validation_contract.html">ODF Contract</a><a href="./odf_security_policy.html">ODF Security</a></nav>
+          {content}
+          </body></html>"""
+
+          md = markdown.Markdown(extensions=["tables", "fenced_code"])
+          for f in site.glob("*.md"):
+              html = md.convert(f.read_text(encoding="utf-8"))
+              title = f.stem.replace("_", " ").title()
+              if f.name == "index.md":
+                  title = "openxml-audit"
+              out = site / f"{f.stem}.html"
+              out.write_text(template.format(title=title, content=html), encoding="utf-8")
+              md.reset()
+              f.unlink()
+          PY
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

openxml_audit-0.2.0/.github/workflows/parity-gate.yml

@@ -0,0 +1,147 @@
+name: Parity gate
+
+on:
+  pull_request:
+    paths:
+      - "src/**"
+      - "scripts/corpus/**"
+      - "data/corpus/**"
+      - ".github/workflows/parity-gate.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "src/**"
+      - "scripts/corpus/**"
+      - "data/corpus/**"
+      - ".github/workflows/parity-gate.yml"
+  workflow_dispatch:
+    inputs:
+      corpus_archive_url:
+        description: "Optional URL for parity corpus tar.zst (overrides repo variable)."
+        required: false
+        default: ""
+
+jobs:
+  parity:
+    runs-on: ubuntu-latest
+    env:
+      SDK_REF: v3.4.1
+      SDK_REPO: https://github.com/dotnet/Open-XML-SDK.git
+      BASELINE_SNAPSHOT: data/corpus/parity_baseline/v3.4.1/parity_snapshot.json
+      WAIVERS_FILE: data/corpus/parity_baseline/v3.4.1/waivers.json
+      PERF_BUDGET_FILE: data/corpus/parity_baseline/v3.4.1/perf_budget.json
+      CURRENT_SNAPSHOT: reports/parity_current.json
+      COMPARE_REPORT: reports/parity_compare.json
+      SUMMARY_REPORT: /tmp/parity_compare.md
+      PERF_SUMMARY_REPORT: /tmp/parity_perf.md
+      CORPUS_ARCHIVE_URL: ${{ github.event.inputs.corpus_archive_url || vars.PARITY_CORPUS_ARCHIVE_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Prepare reports directory
+        run: mkdir -p reports
+
+      - name: Resolve corpus files root
+        id: corpus
+        run: |
+          set -euo pipefail
+
+          # 1. Local files checked into the repo
+          local_root="$GITHUB_WORKSPACE/data/corpus/sdk_seed/files"
+          if [ -d "$local_root" ]; then
+            echo "Using local corpus files at $local_root"
+            echo "files_root=$local_root" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # 2. Pre-built archive from repo variable
+          if [ -n "${CORPUS_ARCHIVE_URL:-}" ]; then
+            work_root="/tmp/openxml-parity-corpus"
+            archive_path="/tmp/openxml-parity-corpus.tar.zst"
+            rm -rf "$work_root"
+            mkdir -p "$work_root"
+            echo "Downloading corpus archive from configured URL"
+            curl -fsSL "$CORPUS_ARCHIVE_URL" -o "$archive_path"
+            tar --zstd -xf "$archive_path" -C "$work_root"
+            files_root="$work_root/files"
+            if [ ! -d "$files_root" ]; then
+              echo "::error::Corpus archive does not contain expected 'files/' directory."
+              exit 2
+            fi
+            echo "files_root=$files_root" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # 3. Build corpus from upstream SDK
+          echo "Building corpus from upstream SDK ($SDK_REF)"
+          sdk_root="/tmp/openxml-sdk-upstream"
+          corpus_root="/tmp/openxml-sdk-seed"
+          rm -rf "$sdk_root" "$corpus_root"
+          git clone --depth 1 --branch "$SDK_REF" "$SDK_REPO" "$sdk_root"
+          python scripts/corpus/import_sdk_assets.py \
+            --sdk-root "$sdk_root" \
+            --output-root "$corpus_root"
+          echo "files_root=$corpus_root/files" >> "$GITHUB_OUTPUT"
+
+      - name: Run parity snapshot
+        run: |
+          python scripts/corpus/run_parity_snapshot.py \
+            --manifest data/corpus/sdk_seed/manifest.json \
+            --files-root "${{ steps.corpus.outputs.files_root }}" \
+            --output "$CURRENT_SNAPSHOT"
+
+      - name: Compare against baseline
+        run: |
+          python scripts/corpus/compare_to_baseline.py \
+            --baseline "$BASELINE_SNAPSHOT" \
+            --current "$CURRENT_SNAPSHOT" \
+            --waivers "$WAIVERS_FILE" \
+            --output "$COMPARE_REPORT" \
+            --summary "$SUMMARY_REPORT" \
+            --max-mismatch-growth 0 \
+            --max-new-families 0 \
+            --max-match-rate-drop 0.0 \
+            --max-missing-files 0
+
+      - name: Enforce parity performance budget
+        run: |
+          python scripts/corpus/check_perf_budget.py \
+            --report "$CURRENT_SNAPSHOT" \
+            --budget "$PERF_BUDGET_FILE" \
+            --output reports/parity_perf.json \
+            --summary "$PERF_SUMMARY_REPORT"
+
+      - name: Upload parity reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: parity-gate-reports
+          path: reports
+
+      - name: Workflow summary
+        if: always()
+        run: |
+          if [ -f "$SUMMARY_REPORT" ]; then
+            cat "$SUMMARY_REPORT" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "No parity summary produced." >> "$GITHUB_STEP_SUMMARY"
+          fi
+          if [ -f "$PERF_SUMMARY_REPORT" ]; then
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            cat "$PERF_SUMMARY_REPORT" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "No parity performance summary produced." >> "$GITHUB_STEP_SUMMARY"
+          fi

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

@@ -0,0 +1,90 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          # Get previous tag
+          prev_tag=$(git tag --sort=-v:refname | head -2 | tail -1)
+          if [ -z "$prev_tag" ]; then
+            echo "body=Initial release" >> "$GITHUB_OUTPUT"
+          else
+            changelog=$(git log --pretty=format:"- %s" "$prev_tag"..HEAD -- src/ scripts/ | head -50)
+            # Write multiline output
+            {
+              echo "body<<EOF"
+              echo "$changelog"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.body }}
+          files: dist/*
+          generate_release_notes: true