markkit 0.1.1__tar.gz

markkit-0.1.1/.agents/skills/process-issues/SKILL.md

@@ -0,0 +1,52 @@
+Process open GitHub issues and resolve them via merged pull requests.
+
+## Qualifying Issues
+
+Only process issues created by authorized users or containing approval
+comments from those users.
+
+## Core Principle
+
+One issue = one PR. No bundling. No skipping.
+
+## Process Per Issue
+
+### 1. Understand & Scope
+- Read the issue thoroughly
+- Classify: bug, feature, docs, refactor
+- Identify affected crates and files
+- Create branch: `fix/issue-{N}-{short-slug}`
+
+### 2. Test First
+- For bugs: create a failing test that reproduces the issue
+- For features: scaffold validation tests
+- Place tests alongside existing test modules
+
+### 3. Implement
+- Make minimal, focused changes
+- Cover positive and negative test cases
+- Consider security implications for parsing changes
+
+### 4. Ship
+- Use the `/ship` skill for:
+  - Spec updates
+  - Quality gates
+  - PR creation
+  - CI verification
+  - Merge
+
+### 5. Return to Main
+```bash
+git checkout main && git pull origin main
+```
+Then proceed to next issue.
+
+## Post-Resolution
+
+After all issues are resolved, identify any `#[ignore]` tests
+that now pass and un-ignore them in a single PR.
+
+## Arguments
+
+Optional: specific issue numbers or labels.
+Default: process all qualifying open issues.

markkit-0.1.1/.agents/skills/ship/SKILL.md

@@ -0,0 +1,61 @@
+Run the full ship flow: verify quality, ensure test coverage, update
+artifacts, smoke test, then push, create PR, address review comments,
+and merge only when CI is green, all threads resolved, and user confirms.
+
+## Phases
+
+### 1. Pre-flight
+- Verify on a feature branch (not main)
+- Check for uncommitted changes
+- Fetch latest main and rebase if needed
+
+### 2. Test Coverage
+- Identify changed code paths
+- Ensure tests exist for:
+  - Positive cases (happy path)
+  - Negative cases (errors, edge cases)
+  - Security scenarios (malicious input)
+- Add missing tests
+
+### 3. Artifact Updates
+- Update specs if behavior changed
+- Update CHANGELOG.md for user-facing changes
+- Update documentation for API changes
+
+### 4. Simplification
+- Remove dead code introduced by changes
+- Reduce duplication
+- Simplify where possible without changing behavior
+
+### 5. Security Review
+- Check for injection risks in new parsing code
+- Verify resource limits are enforced
+- Review input validation
+
+### 6. Smoke Test
+- Run `just test` for full test suite
+- Run `just lint` for code quality
+- Build CLI and verify basic extraction works
+
+### 7. Quality Gates
+- `cargo fmt --all -- --check`
+- `cargo clippy --workspace -- -D warnings`
+- `cargo deny check`
+
+### 8. Push & PR
+- Push branch to remote
+- Create or update PR with summary
+- Wait for CI to pass
+
+### 9. Review & Merge
+- Check for unresolved review comments — address or reply to each
+- Ensure all review threads are resolved
+- Confirm no changes-requested reviews remain outstanding
+- Ask the user whether to merge now or wait for reviewer feedback
+- Only merge when: CI green, no unresolved threads, no pending change requests
+
+**IMPORTANT**: Phases 2-5 (tests, artifacts, simplification, security review,
+smoke testing) are the quality core — do NOT skip them.
+
+**IMPORTANT**: Never auto-merge without confirming with the user. PRs should
+have time for human review before merging.

markkit-0.1.1/.claude/commands/maintain.md

@@ -0,0 +1,49 @@
+Run pre-release maintenance checks on the markkit codebase.
+
+Each section below is an outcome to achieve, not a script to follow.
+Use whatever tools and approaches make sense to verify and fix.
+
+Fix issues as you find them — don't just report. Use conventional
+commit messages for any fixes.
+
+Sections (run all unless $ARGUMENTS specifies a subset):
+
+## 1. Dependencies
+- Run `cargo update` and verify tests pass
+- Check for outdated dependencies
+- Review Dependabot PRs if any
+
+## 2. Security
+- Run `cargo audit` for vulnerabilities
+- Run `cargo deny check` for license compliance
+- Review any new advisories
+
+## 3. Tests
+- Run full test suite: `just test`
+- Check coverage isn't regressing
+- Identify any `#[ignore]` tests that should be re-enabled
+
+## 4. Documentation
+- Verify README is current
+- Check rustdoc builds without warnings
+- Ensure specs match implementation
+
+## 5. Examples
+- Verify examples compile and run
+- Update examples for any API changes
+
+## 6. Specs
+- Review specs/ for accuracy
+- Update implementation status
+
+## 7. Simplification
+- Look for dead code, unused dependencies
+- Identify duplication opportunities
+- Reduce complexity where possible
+
+## 8. CI Health
+- Check recent GitHub Actions runs
+- Verify nightly builds are passing
+- Review any flaky tests
+
+Deliver a summary of findings and actions taken.

markkit-0.1.1/.claude/hooks/fix-git-identity.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# SessionStart hook: override agent-like git identity with real user
+
+set -euo pipefail
+
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+source "$REPO_ROOT/scripts/lib/common.sh"
+
+configure_commit_git_identity_if_needed 2>/dev/null || true

markkit-0.1.1/.claude/settings.json

@@ -0,0 +1,20 @@
+{
+  "gitAttribution": false,
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/fix-git-identity.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

markkit-0.1.1/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  # Rust dependencies
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      rust-dependencies:
+        patterns:
+          - "*"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(ci)"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

markkit-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -Dwarnings
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+      - name: Build docs
+        run: cargo doc --workspace --no-deps
+        env:
+          RUSTDOCFLAGS: -Dwarnings
+
+  audit:
+    name: Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-audit
+        run: cargo install cargo-audit
+      - name: Install cargo-deny
+        run: cargo install cargo-deny
+      - name: Security audit
+        run: cargo audit
+      - name: License and dependency check
+        run: cargo deny check
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Run tests
+        run: cargo test --workspace
+      - name: Run tests (all features)
+        run: cargo test --workspace --all-features
+      - name: Run tests (office formats, no HTTP client)
+        run: |
+          cargo test -p markkit --no-default-features --features docx,spreadsheet
+          if cargo tree -p markkit --no-default-features --features docx,spreadsheet -e normal | grep -E 'reqwest|hyper'; then
+            echo "HTTP client leaked into the docx,spreadsheet feature set"
+            exit 1
+          fi
+
+  check:
+    name: Check
+    needs: [lint, audit, test]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: All jobs passed
+        run: |
+          if [[ "${{ needs.lint.result }}" != "success" ]] || \
+             [[ "${{ needs.audit.result }}" != "success" ]] || \
+             [[ "${{ needs.test.result }}" != "success" ]]; then
+            echo "One or more jobs failed"
+            exit 1
+          fi

markkit-0.1.1/.github/workflows/coverage.yml

@@ -0,0 +1,25 @@
+name: Coverage
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  coverage:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Install cargo-tarpaulin
+        run: cargo install cargo-tarpaulin
+      - name: Generate coverage
+        run: cargo tarpaulin --workspace --out xml
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: cobertura.xml
+          fail_ci_if_error: false

markkit-0.1.1/.github/workflows/js.yml

@@ -0,0 +1,38 @@
+name: JavaScript
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "crates/markkit-js/**"
+      - "crates/markkit/**"
+  pull_request:
+    branches: [main]
+    paths:
+      - "crates/markkit-js/**"
+      - "crates/markkit/**"
+
+jobs:
+  build:
+    name: Build Node.js bindings
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24.22.1"
+      - name: Install dependencies
+        run: cd crates/markkit-js && npm install --ignore-scripts --audit=false --fund=false
+      - name: Build
+        run: cd crates/markkit-js && npx --no-install napi build --release --platform
+      - name: Verify build preserved the patched lockfile
+        run: git diff --exit-code -- Cargo.lock
+      - name: Verify installed npm package
+        run: |
+          cd crates/markkit-js
+          npm pack --ignore-scripts --json > "$RUNNER_TEMP/markkit-pack.json"
+          node -e 'const p=require(process.argv[1])[0]; const files=p.files.map(f=>f.path); if(!files.includes("index.js") || !files.some(f=>f.endsWith(".node"))) throw Error("npm package must contain its loader and native binary")' "$RUNNER_TEMP/markkit-pack.json"
+          TARBALL=$(node -e 'console.log(require(process.argv[1])[0].filename)' "$RUNNER_TEMP/markkit-pack.json")
+          npm install --prefix "$RUNNER_TEMP/markkit-npm-smoke" --ignore-scripts --audit=false --fund=false "$PWD/$TARBALL"
+          node -e 'const m=require(process.argv[1]); if(m.extractHtmlSync("<h1>Smoke</h1>").trim()!=="# Smoke") throw Error("native extraction smoke failed")' "$RUNNER_TEMP/markkit-npm-smoke/node_modules/@everruns/markkit"

markkit-0.1.1/.github/workflows/nightly.yml

@@ -0,0 +1,21 @@
+name: Nightly
+
+on:
+  schedule:
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+jobs:
+  nightly:
+    name: Nightly checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Build on nightly
+        run: cargo build --workspace
+      - name: Test on nightly
+        run: cargo test --workspace

markkit-0.1.1/.github/workflows/publish-js.yml

@@ -0,0 +1,49 @@
+name: Publish JavaScript
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Dry run"
+        required: false
+        default: "true"
+
+jobs:
+  publish:
+    name: Publish npm package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24.22.1"
+          registry-url: "https://registry.npmjs.org"
+      - name: Require npm publisher credential
+        if: inputs.dry_run != 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "$NODE_AUTH_TOKEN" ]; then
+            echo "::error::NPM_TOKEN is unavailable for this publisher"
+            exit 1
+          fi
+      - name: Install dependencies
+        run: cd crates/markkit-js && npm install --ignore-scripts --audit=false --fund=false
+      - name: Build
+        run: cd crates/markkit-js && npx --no-install napi build --release --platform
+      - name: Verify build preserved the patched lockfile
+        run: git diff --exit-code -- Cargo.lock
+      - name: Verify installed npm package
+        run: |
+          cd crates/markkit-js
+          npm pack --ignore-scripts --json > "$RUNNER_TEMP/markkit-pack.json"
+          node -e 'const p=require(process.argv[1])[0]; const files=p.files.map(f=>f.path); if(!files.includes("index.js") || !files.some(f=>f.endsWith(".node"))) throw Error("npm package must contain its loader and native binary")' "$RUNNER_TEMP/markkit-pack.json"
+          TARBALL=$(node -e 'console.log(require(process.argv[1])[0].filename)' "$RUNNER_TEMP/markkit-pack.json")
+          npm install --prefix "$RUNNER_TEMP/markkit-npm-smoke" --ignore-scripts --audit=false --fund=false "$PWD/$TARBALL"
+          node -e 'const m=require(process.argv[1]); if(m.extractHtmlSync("<h1>Smoke</h1>").trim()!=="# Smoke") throw Error("native extraction smoke failed")' "$RUNNER_TEMP/markkit-npm-smoke/node_modules/@everruns/markkit"
+      - name: Publish
+        if: inputs.dry_run != 'true'
+        run: cd crates/markkit-js && npm publish --ignore-scripts
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

markkit-0.1.1/.github/workflows/publish-python.yml

@@ -0,0 +1,128 @@
+name: Publish Python
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build and verify without publishing"
+        required: false
+        default: "true"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify Python distributions
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.metadata.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install packaging tools
+        run: python -m pip install maturin==1.15.0 twine==7.0.0
+      - name: Build from source distribution
+        run: maturin build --release --locked --sdist
+      - name: Verify build preserved the patched lockfile
+        run: git diff --exit-code -- Cargo.lock
+      - name: Inspect distribution identity
+        id: metadata
+        run: |
+          python <<'PYTHON'
+          import email.parser
+          import os
+          import pathlib
+          import zipfile
+          wheels = list(pathlib.Path("target/wheels").glob("*.whl"))
+          assert len(wheels) == 1
+          with zipfile.ZipFile(wheels[0]) as wheel:
+              metadata = email.parser.BytesParser().parsebytes(wheel.read(next(name for name in wheel.namelist() if name.endswith(".dist-info/METADATA"))))
+          assert metadata["Name"] == "markkit"
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              print(f"version={metadata['Version']}", file=output)
+          print(f"markkit {metadata['Version']} from {os.environ['GITHUB_SHA']}")
+          PYTHON
+      - name: Verify distributions and native import
+        run: |
+          python -m twine check --strict target/wheels/*.whl target/wheels/*.tar.gz
+          python -m venv "$RUNNER_TEMP/markkit-wheel-smoke"
+          "$RUNNER_TEMP/markkit-wheel-smoke/bin/python" -m pip install --no-deps target/wheels/*.whl
+          "$RUNNER_TEMP/markkit-wheel-smoke/bin/python" -c 'import importlib.metadata, importlib.util, markkit; assert importlib.metadata.metadata("markkit")["Name"] == "markkit"; assert importlib.util.find_spec("markkit_python") is None; assert markkit.extract_html_sync("<h1>Smoke</h1>").strip() == "# Smoke"'
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: python-distributions
+          path: |
+            target/wheels/*.whl
+            target/wheels/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish Python package with OIDC
+    needs: build
+    if: inputs.dry_run != 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: python-distributions
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          packages-dir: dist/
+
+  verify:
+    name: Verify public PyPI installation
+    needs: [build, publish]
+    runs-on: ubuntu-latest
+    env:
+      MARKKIT_VERSION: ${{ needs.build.outputs.version }}
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: python-distributions
+          path: dist
+      - name: Download the published wheel
+        run: |
+          for attempt in 1 2 3 4 5; do
+            if python -m pip download --no-cache-dir --only-binary=:all: --no-deps --dest registry "markkit==$MARKKIT_VERSION"; then
+              break
+            fi
+            if [ "$attempt" -eq 5 ]; then exit 1; fi
+            sleep 10
+          done
+      - name: Verify public files match the build
+        run: |
+          python <<'PYTHON'
+          import hashlib
+          import json
+          import os
+          import pathlib
+          import urllib.request
+          version = os.environ["MARKKIT_VERSION"]
+          with urllib.request.urlopen(f"https://pypi.org/pypi/markkit/{version}/json") as response:
+              published = json.load(response)
+          assert published["info"]["name"] == "markkit"
+          assert published["info"]["version"] == version
+          digests = {entry["filename"]: entry["digests"]["sha256"] for entry in published["urls"]}
+          for artifact in pathlib.Path("dist").iterdir():
+              assert digests[artifact.name] == hashlib.sha256(artifact.read_bytes()).hexdigest()
+          for wheel in pathlib.Path("registry").glob("*.whl"):
+              assert digests[wheel.name] == hashlib.sha256(wheel.read_bytes()).hexdigest()
+          print(f"Public markkit {version} distributions match the build")
+          PYTHON
+      - name: Install and smoke-test the public wheel
+        run: |
+          python -m venv "$RUNNER_TEMP/markkit-public-smoke"
+          "$RUNNER_TEMP/markkit-public-smoke/bin/python" -m pip install --no-index --no-deps registry/*.whl
+          "$RUNNER_TEMP/markkit-public-smoke/bin/python" -c 'import importlib.metadata, importlib.util, markkit; assert importlib.metadata.version("markkit") == __import__("os").environ["MARKKIT_VERSION"]; assert importlib.util.find_spec("markkit_python") is None; assert markkit.extract_html_sync("<h1>Published smoke</h1>").strip() == "# Published smoke"; print("Public markkit import and native extraction PASS")'

markkit-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish
+
+# Decisions:
+# - Runs from a release tag (dispatched by release.yml, or manually from a tag).
+# - Idempotent: a crate whose version is already on crates.io is skipped, so
+#   re-running a release never fails on an already-published crate.
+# - Each crate is verified with a dry run before the credentialed upload.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  publish:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Verify tag and version
+        id: version
+        run: |
+          if [[ ! "$GITHUB_REF" =~ ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Error: publish must run from a release tag (vX.Y.Z), got $GITHUB_REF"
+            exit 1
+          fi
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          CARGO_VERSION=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          if [ "$TAG_VERSION" != "$CARGO_VERSION" ]; then
+            echo "Error: tag version ($TAG_VERSION) does not match Cargo.toml ($CARGO_VERSION)"
+            exit 1
+          fi
+          git fetch --no-tags origin main:refs/remotes/origin/main
+          if ! git merge-base --is-ancestor HEAD origin/main; then
+            echo "Error: publish source is not reachable from origin/main"
+            exit 1
+          fi
+          echo "version=$CARGO_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Publish crates
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: |
+          published() {
+            curl -sf -A "markkit-release (github.com/everruns/markkit)" \
+              "https://crates.io/api/v1/crates/$1/$VERSION" > /dev/null
+          }
+          # Dependency order: markkit-cli depends on markkit.
+          for crate in markkit markkit-cli; do
+            if published "$crate"; then
+              echo "$crate $VERSION already on crates.io; skipping"
+              continue
+            fi
+            cargo publish --dry-run -p "$crate"
+            cargo publish --no-verify -p "$crate"
+          done

markkit-0.1.1/.github/workflows/python.yml

@@ -0,0 +1,32 @@
+name: Python
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "crates/markkit-python/**"
+      - "crates/markkit/**"
+  pull_request:
+    branches: [main]
+    paths:
+      - "crates/markkit-python/**"
+      - "crates/markkit/**"
+
+jobs:
+  build:
+    name: Build Python bindings
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install maturin
+        run: pip install maturin
+      - name: Build
+        run: maturin build
+      - name: Test import
+        run: |
+          pip install target/wheels/*.whl
+          python -c 'from importlib.metadata import metadata; import markkit; assert metadata("markkit")["Name"] == "markkit"; assert markkit.extract_html_sync("<h1>Smoke</h1>").strip() == "# Smoke"; print("Distribution and import OK")'