mdka 2.2.0__tar.gz → 2.2.2__tar.gz

mdka-2.2.2/.github/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+## ✨ Contributing
+
+We’re happy to receive feedback, bug reports, and questions via GitHub Issues.  
+Pull requests are also welcome — though please note that we may not always be able to accept them.
+
+This project is maintained as a labor of love. We welcome community participation, but:
+
+- Issues that are respectful and constructive are appreciated.
+- Pull requests are reviewed, but acceptance is not guaranteed.
+- We do not engage in long debates or vision disagreements.
+- If you have a different direction in mind, please fork freely, provided proper licensing is respected.
+
+Thanks for understanding the scope and spirit of the project.
+
+## Documentation examples
+
+Every fenced code block in `docs/src/` whose info string names `rust`,
+`python`, `js` or `ts` is **checked in CI** by the `docs example gate`
+workflow. Rust blocks are compiled against the crate, TypeScript blocks are
+type-checked against the generated `node/index.d.ts`, JavaScript blocks are
+parsed, and Python blocks are syntax-checked with every `mdka` symbol they
+name resolved against the installed package.
+
+A block that is deliberately **not** runnable on its own — a signature
+display, a type declaration, or a snippet that relies on a variable
+introduced in the surrounding prose — must say so in its info string:
+
+````markdown
+```rust,fragment
+pub fn html_to_markdown(html: &str) -> String
+```
+````
+
+**The marker is what excludes a block.** There is no list of exceptions kept
+somewhere else, because such a list drifts out of step with the documents it
+describes. Rust's own `ignore` and `no_run` are honoured for the same
+purpose. A block with no info string at all — which is how sample *output*
+is written — is never checked.
+
+If a block is genuinely runnable, do not mark it as a fragment to quiet the
+gate; fix the example. That gate exists because two shipped examples failed
+on their first line.

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

@@ -50,7 +50,7 @@ jobs:
         run: cargo clippy --workspace --all-targets --all-features -- -D warnings
 
       - name: cargo test
-        run: cargo test --workspace --locked
+        run: cargo test --workspace --all-features --locked
 
       - name: cargo build
         run: cargo build --workspace --locked

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

@@ -0,0 +1,78 @@
+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, resolving dependencies from the registry
+# rather than from the workspace. That is the consumer's build.
+#
+# 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-
+
+      # mdka first: the other three depend on it, and their verification
+      # builds resolve it from the registry.
+      #
+      # 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.
+      - name: cargo package -p mdka
+        run: cargo package -p mdka --locked
+
+      - name: cargo package -p mdka-cli
+        run: cargo package -p mdka-cli --locked
+
+      - name: cargo package -p mdka-node
+        run: cargo package -p mdka-node --locked
+
+      - name: cargo package -p mdka-python
+        run: cargo package -p mdka-python --locked
+
+      - name: Show what each package actually contains
+        run: |
+          set -euo pipefail
+          for crate in target/package/*.crate; do
+            echo "=== $crate"
+            tar -tzf "$crate" | sed 's/^/    /'
+          done

{mdka-2.2.0 → mdka-2.2.2}/.github/workflows/create-release.yaml

@@ -64,8 +64,23 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          gh release create "${{ github.ref_name }}" \
-            --title "${{ github.ref_name }}" \
+          tag="${{ github.ref_name }}"
+          link="https://github.com/${{ github.repository }}/blob/${tag}/CHANGELOG.md"
+
+          # Point at this version's CHANGELOG section. GitHub's heading anchor
+          # includes the release date ("## [2.2.1] - 2026-09-01" -> #221---2026-09-01),
+          # so it has to be derived from the heading rather than the version alone.
+          # If the heading is not found, the link degrades to the file itself --
+          # never to a broken anchor.
+          heading=$(grep -m1 "^## \[${tag}\]" CHANGELOG.md || true)
+          if [ -n "$heading" ]; then
+            anchor=$(printf '%s' "$heading" | sed 's/^## //' | tr -d '[].' | tr ' ' '-' | tr 'A-Z' 'a-z')
+            link="${link}#${anchor}"
+          fi
+
+          gh release create "${tag}" \
+            --title "${tag}" \
+            --notes "📖 [Changelog for ${tag}](${link})" \
             --generate-notes
 
       - name: Start the publishing workflows

mdka-2.2.2/.github/workflows/docs-example-gate.yaml

@@ -0,0 +1,94 @@
+name: docs example gate
+
+# RFC 026 §4.3. Nothing has ever executed the examples in docs/src/. D-12
+# and D-13 shipped examples that fail on their first line -- a duplicate
+# `const`, and a TypeScript import of a type the bindings never exported.
+#
+# Every fenced block whose info string names a language we can check is
+# checked. A block that is deliberately a fragment carries a `fragment`
+# marker, and the marker is what excludes it: there is no list of exceptions
+# kept elsewhere that can drift out of step with the documents. The
+# convention is documented in CONTRIBUTING.md.
+#
+# Its own workflow file, not ci.yaml -- see RFC 026 §3.5.
+
+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:
+  docs-example-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Cache cargo dependencies and build
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-docs-gate-${{ hashFiles('**/Cargo.lock') }}
+          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
+        working-directory: node
+        run: |
+          npm ci
+          npm run build
+
+      # Python examples resolve their `mdka` symbols against the installed
+      # package, so a documented function that does not exist is caught.
+      - name: Stage README for maturin
+        run: cp -f README.md python/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Build and install the wheel into a venv
+        run: |
+          set -euo pipefail
+          uv venv
+          uv pip install maturin
+          cd python
+          source ../.venv/bin/activate
+          maturin build --out "$RUNNER_TEMP/wheels"
+          cd ..
+          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/
+        run: |
+          python .github/workflows/scripts/check-docs-examples.py \
+            --python "$RUNNER_TEMP/docs-venv/bin/python"

mdka-2.2.2/.github/workflows/npm-install-gate.yaml

@@ -0,0 +1,68 @@
+name: npm install gate
+
+# RFC 020 / RFC 026. This gate must NOT live in ci.yaml: release-npm.yaml and
+# create-release.yaml gate on ci.yaml's conclusion, so a red gate there blocks
+# the very release that would make it pass. See RFC 020's correction record.
+#
+# It installs the PUBLISHED package from the registry, the way a consumer does.
+#
+# It deliberately does not pack and install the local tarball. That was the
+# original design and it could never pass: `optionalDependencies` are injected
+# by `napi pre-publish` at release time, so a locally packed tarball has none,
+# resolves no per-platform package, and always fails to load. It was testing an
+# artifact that is not the one published.
+#
+# Consequence, stated rather than hidden: this gate reports on the LAST
+# PUBLISHED release, not on the current working tree. That lag is inherent --
+# a published artifact cannot be verified before it is published. What it buys
+# is an alarm that would have been red for all twelve broken 2.x releases.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  schedule:
+    # Catch a registry-side regression even when nobody pushes.
+    - cron: '0 6 * * 1'
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  npm-install-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Install the published package from the registry and require it
+        run: |
+          set -euo pipefail
+          install_dir="$RUNNER_TEMP/npm-install-gate"
+          mkdir -p "$install_dir"
+          cd "$install_dir"
+          npm init -y >/dev/null
+
+          published=$(npm view mdka version)
+          echo "Testing published mdka@${published}"
+          npm install "mdka@${published}"
+
+          node -e "
+            const m = require('mdka');
+            const out = m.htmlToMarkdown('<h1>x</h1>');
+            if (!out.includes('# x')) {
+              console.error('unexpected output: ' + JSON.stringify(out));
+              process.exit(1);
+            }
+            console.log('OK: mdka@${published} installs and converts:', JSON.stringify(out));
+          "

mdka-2.2.2/.github/workflows/pypi-wheel-gate.yaml

@@ -0,0 +1,112 @@
+name: pypi wheel gate
+
+# RFC 026 §4.1. The `python` job in ci.yaml runs `maturin develop` + pytest,
+# which imports the project from the workspace. That cannot see anything
+# missing from the *wheel* -- the artifact `pip install mdka` actually
+# fetches. This gate builds the wheel, installs it into a venv outside the
+# workspace, and imports it from there.
+#
+# Its own workflow file, not ci.yaml: release-npm.yaml and
+# create-release.yaml gate on ci.yaml's conclusion, so an artifact gate
+# living there can block the very release that would make it pass. That
+# deadlocked 2.2.1. See RFC 020's correction record and RFC 026 §3.5.
+#
+# It does NOT assert py.typed. RFC 023 decided to remove that claim rather
+# than ship the marker: every public symbol comes from a compiled PyO3
+# module with no .pyi stubs, so shipping py.typed would silence a type
+# checker without giving it anything to check. See RFC 023.
+
+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:
+  pypi-wheel-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+
+      - name: Cache cargo dependencies and build
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-wheel-gate-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-wheel-gate-
+
+      # python/pyproject.toml declares readme = "README.md" but the README
+      # lives at the repository root. Same staging the `python` job does.
+      - name: Stage README for maturin
+        run: cp -f README.md python/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Install maturin
+        run: |
+          uv venv
+          uv pip install maturin
+
+      # `maturin build`, never `maturin develop`. develop is the blind spot
+      # this gate exists to close.
+      - name: Build the wheel
+        working-directory: python
+        run: |
+          source ../.venv/bin/activate
+          maturin build --out "$RUNNER_TEMP/wheels"
+
+      - name: Install the wheel outside the workspace and use it
+        run: |
+          set -euo pipefail
+          venv="$RUNNER_TEMP/wheel-gate-venv"
+          python -m venv "$venv"
+          wheel=$(ls "$RUNNER_TEMP"/wheels/mdka-*.whl)
+          echo "Installing $wheel"
+          "$venv/bin/pip" install --no-index "$wheel"
+
+          # cd out of the workspace so `import mdka` cannot resolve to the
+          # source tree instead of the installed package.
+          cd "$RUNNER_TEMP"
+          "$venv/bin/python" - <<'PY'
+          import mdka, pathlib, sys
+
+          # Prove we imported the installed package, not a source checkout.
+          where = pathlib.Path(mdka.__file__).resolve()
+          print("imported from:", where)
+          assert "site-packages" in where.parts, f"not the installed package: {where}"
+
+          out = mdka.html_to_markdown("<h1>x</h1>")
+          assert "# x" in out, f"unexpected output: {out!r}"
+
+          # The compiled binding must be inside the wheel, not merely
+          # importable because something else built it.
+          so = list(where.parent.glob("mdka_python*.so"))
+          assert so, f"native binding missing from the installed package: {list(where.parent.iterdir())}"
+
+          print("OK:", repr(out), "| binding:", so[0].name, "| version:", mdka.__version__)
+          PY

{mdka-2.2.0 → mdka-2.2.2}/.github/workflows/release-npm.yaml

@@ -167,7 +167,32 @@ jobs:
         run: |
           npx napi create-npm-dirs
           npx napi artifacts
-      
+
+      # RFC 020: this step was missing entirely, which is why `npm install
+      # mdka` produced an unusable package for the whole 2.x line -- the
+      # per-platform packages were never published past 1.6.9, and the main
+      # package's manifest never carried optionalDependencies at all.
+      #
+      # --no-gh-release is required, not optional: `napi pre-publish`
+      # defaults --gh-release to true and would otherwise attempt to create
+      # a second GitHub release for a tag create-release.yaml already
+      # released, which fails (non-fatally -- it's caught and logged -- but
+      # there is no reason to invite the noise).
+      - name: napi pre-publish (publish per-platform packages, inject optionalDependencies)
+        working-directory: node
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx napi pre-publish --no-gh-release
+
+      # No `npm ci` here. The `napi pre-publish` step above rewrites
+      # package.json to add optionalDependencies for the per-platform
+      # packages, which puts it out of sync with package-lock.json --
+      # `npm ci` refuses to run in that state and fails the publish. It was
+      # also redundant: the "Install dependencies" step above already ran
+      # `npm install`, and `npm publish` does not need node_modules.
+      # Removed 2026-09-01 after it blocked the 2.2.1 npm publish, which is
+      # the first release in which pre-publish ever ran.
       - name: Publish
         working-directory: node
         env:
@@ -175,5 +200,4 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           cp -f ../README.md .
-          npm ci
           npm publish