qso-graph-lib 0.1.0__tar.gz

qso_graph_lib-0.1.0/.github/dependabot.yml

@@ -0,0 +1,37 @@
+# Dependabot: security updates only, grouped into one pull request.
+#
+# WHY THIS FILE EXISTS (2026-10-25). There was no dependabot.yml in any of the 22
+# servers. Without one Dependabot runs *security* updates only -- those need no
+# config -- and they are ungrouped by default: one advisory x one package x one
+# repository = one pull request. Four upgrades produced **57 open pull requests**
+# across the fleet, and KI7MT's objection was the right one: nobody could say
+# what 57 pull requests did. Measured, they were four dependency upgrades closing
+# 130 alerts, one of them CRITICAL. The volume was not noise, it was signal
+# nobody could read.
+#
+# `groups` with `applies-to: security-updates` collapses that to one pull request
+# per repository.
+#
+# open-pull-requests-limit: 0 disables *version* updates, which we do not want --
+# ci.yml audits the locked dependencies on every pull request and weekly, so a
+# stale lock already fails CI and does not need a bot to notice. Security updates
+# are unaffected by this limit: they have their own fixed limit of 10, which
+# cannot be configured. Checked against the Dependabot options reference rather
+# than assumed, because setting this wrong would silently switch off the thing
+# that found those 130 alerts.
+#
+# `uv` is the ecosystem for a uv.lock project, also checked against that
+# reference and not inferred from the file name.
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 0
+    groups:
+      security:
+        applies-to: security-updates
+        patterns:
+          - "*"

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

@@ -0,0 +1,136 @@
+name: CI
+
+# A pull request is tested whatever it targets, and deliberately has no branch
+# filter. `main` is the one long-lived branch now, so `push` names it; but a filter
+# here would mean a pull request into any other branch ran no ruff, no mypy and no
+# pytest while still reporting green.
+on:
+  pull_request:
+  push:
+    branches: [main]
+  # Weekly, because an advisory is published against a lockfile that has not
+  # changed, and no pull-request-or-push trigger fires for that.
+  schedule:
+    - cron: "17 6 * * 1"
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Lint and types, once rather than per Python: both read the source, and
+  # neither answer changes with the interpreter running them (qso-graph-devel#66).
+  lint:
+    name: ruff and mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.11.18"
+          enable-cache: true
+
+      - name: Install (locked)
+        run: uv sync --group dev --frozen
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Type-check (mypy)
+        run: uv run mypy src
+
+  test:
+    name: pytest (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Patch versions, not minor ones. Asked for "3.12", uv takes whatever
+        # copy the runner already has -- Ubuntu 24.04's 3.12.3, twelve patches
+        # behind -- and nothing says so. These are the releases that reject the
+        # compromised eMudhra intermediate CAs (2026-10).
+        python-version: ["3.11.18", "3.12.16", "3.13.18"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install (locked)
+        run: uv sync --group dev --frozen
+
+      - name: Unit tests
+        run: uv run pytest tests --ignore=tests/test_security.py -v
+
+      - name: Security tests
+        run: uv run pytest tests/test_security.py -v
+
+  # Audits the LOCKED environment, which is a different question from the one the
+  # release gate asks. publish.yml runs `pip-audit --strict --desc on .` -- the
+  # project's *declared* dependencies, resolved fresh -- which protects the people
+  # who `pip install` this package and cannot see uv.lock at all.
+  #
+  # This job syncs `--frozen` and audits what that produced, so a stale lock cannot
+  # sit unnoticed. On 2026-10-25 five MCP servers carried a CRITICAL certifi
+  # advisory in their lockfiles that Dependabot never opened a pull request for.
+  audit:
+    name: audit (locked dependencies)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12.16"
+          enable-cache: true
+
+      - name: Install (locked)
+        run: uv sync --group dev --frozen
+
+      - name: No known vulnerability in the locked dependencies
+        # No --strict, deliberately. --strict fails on any distribution it
+        # could not audit, and `uv sync` installs the project itself -- so the
+        # moment a release bumps the version to one not yet on PyPI, pip-audit
+        # cannot look the project up and --strict turns that into a failure.
+        # It blocked every version bump in all 23 repositories, which is how it
+        # was found: the first real release, dxe-mcp 0.0.3, went red on it with
+        #   "dxe-mcp: Dependency not found on PyPI and could not be audited"
+        # while the lockfile was perfectly clean.
+        #
+        # Without --strict, pip-audit still exits 1 when it FINDS a
+        # vulnerability, which is the whole job. An unauditable local project is
+        # reported as skipped, with its reason, and does not fail the run.
+        #
+        # Verified in both directions against a lock holding certifi 2026.7.22
+        # with the version bumped past PyPI: it reports PYSEC-2026-4320 and
+        # exits 1; with the lock current it reports no vulnerabilities, names the
+        # project as skipped, and exits 0.
+        run: uv run --with pip-audit pip-audit
+
+  ci-all-green:
+    name: ci-all-green
+    needs: [lint, test, audit]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Verify required jobs all succeeded
+        run: |
+          if [[ "${{ needs.lint.result }}" != "success" ]]; then
+            echo "FAIL: ruff or mypy did not pass (result=${{ needs.lint.result }})"
+            exit 1
+          fi
+          if [[ "${{ needs.test.result }}" != "success" ]]; then
+            echo "FAIL: test matrix did not all succeed (result=${{ needs.test.result }})"
+            exit 1
+          fi
+          if [[ "${{ needs.audit.result }}" != "success" ]]; then
+            echo "FAIL: the locked dependencies have a known vulnerability (result=${{ needs.audit.result }})"
+            exit 1
+          fi
+          echo "All required CI jobs passed."

qso_graph_lib-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,306 @@
+name: Publish to PyPI
+
+# A release happens on purpose, not as a side effect of merging (KI7MT, 2026-10-25).
+# qso-graph-lib is a library: PyPI only, no MCP Registry entry, no server.json.
+# This file is qso-graph-auth's, the org's other PyPI-only package, so the two release
+# the same way.
+#
+# `main` is the one working branch. Merging into it builds and tests and publishes
+# nothing; a release is Actions -> Publish to PyPI -> Run workflow, with the version typed
+# in. Typed, because it is a decision: it must match what the tree already says.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "The version to publish, e.g. 0.1.7 — must match pyproject.toml"
+        required: true
+        type: string
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  security:
+    name: Security gates
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: read
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      package: ${{ steps.version.outputs.package }}
+      # "true" when this version is on PyPI with no tag: an interrupted
+      # release being finished, not a new one being made.
+      resume: ${{ steps.version.outputs.resume }}
+    steps:
+      - uses: actions/checkout@v5
+
+      # workflow_dispatch offers a branch picker, so unlike the old push trigger this
+      # workflow can be started from anywhere. The lock is the pypi Environment's
+      # deployment branch rule (main only); this is the same rule stated where a failed
+      # run can show it, because an Environment rejection does not say what was wrong.
+      - name: This runs from main
+        run: |
+          if [ "$GITHUB_REF" != "refs/heads/main" ]; then
+            echo "FAIL: a release is published from main only (this is $GITHUB_REF)"
+            exit 1
+          fi
+
+      # Merging no longer publishes, so nothing else guarantees that what is about to be
+      # released is the code CI passed on. Under the old trigger the release PR had to be
+      # green before the merge that published it; this restores that property.
+      - name: CI passed on the commit being published
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PASSED="$(gh api \
+            "repos/${GITHUB_REPOSITORY}/commits/${GITHUB_SHA}/check-runs?check_name=ci-all-green" \
+            --jq '[.check_runs[] | select(.conclusion == "success")] | length')"
+          if [ "${PASSED:-0}" -lt 1 ]; then
+            echo "FAIL: ci-all-green has not passed on ${GITHUB_SHA}"
+            exit 1
+          fi
+          echo "ci-all-green passed on ${GITHUB_SHA}"
+
+      # A release publishes a version that is not out yet. Computed once; every later job
+      # uses it. The gate fails closed: anything it cannot confirm stops the release.
+      - name: The version is the one asked for, and new
+        id: version
+        env:
+          # Through the environment rather than interpolated into the script: a ${{ }}
+          # expansion inside run: is substituted before the shell sees it, so the input
+          # would be script rather than data. Only a writer can dispatch this, and the
+          # rule is still input validation on every supplied string.
+          ASKED: ${{ inputs.version }}
+        run: |
+          VERSION="$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
+          PACKAGE="$(grep -m1 '^name' pyproject.toml | cut -d'"' -f2)"
+          if ! printf '%s' "$ASKED" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([a-z0-9.-]*)$'; then
+            echo "FAIL: '$ASKED' is not a version"
+            exit 1
+          fi
+          # Typed by the person releasing, so a slip names a version that is not here
+          # rather than shipping whatever happens to be on main.
+          if [ "$ASKED" != "$VERSION" ]; then
+            echo "FAIL: asked to publish ${ASKED}, but this tree is ${VERSION}"
+            exit 1
+          fi
+          echo "${PACKAGE} ${VERSION}"
+          # Only a 404 means "not published yet"; unreachable or 5xx is not a yes.
+          CODE="$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/${PACKAGE}/${VERSION}/json")"
+          # Read with the tag below, not alone. This refused on PyPI 200 full
+          # stop, so a failure in verify or tag -- both of which run after the
+          # upload -- left the version on PyPI, immutable and untagged, with no
+          # recovery but abandoning it. Three releases went that way across the
+          # fleet before 2026-10-27.
+          case "$CODE" in
+            404|200) : ;;
+            *) echo "FAIL: PyPI returned ${CODE}; cannot tell whether ${VERSION} is published"; exit 1 ;;
+          esac
+          # git ls-remote --exit-code: 2 means no such tag; anything else (0, 128) stops.
+          set +e
+          git ls-remote --exit-code --tags origin "refs/tags/v${VERSION}" > /dev/null
+          RC=$?
+          set -e
+          case "$RC" in
+            0) TAGGED=yes ;;
+            2) TAGGED=no ;;
+            *) echo "FAIL: could not check tags (git ls-remote exited ${RC})"; exit 1 ;;
+          esac
+
+          RESUME=false
+          if [ "$CODE" = 404 ] && [ "$TAGGED" = no ]; then
+            echo "PyPI: ${PACKAGE} ${VERSION} is new, tag v${VERSION} is free"
+          elif [ "$CODE" = 200 ] && [ "$TAGGED" = no ]; then
+            RESUME=true
+            echo "NOTE: ${PACKAGE} ${VERSION} is already on PyPI with no tag."
+            echo "      A previous run uploaded it and did not finish. Resuming:"
+            echo "      the upload is skipped, verify and tag complete the release."
+          elif [ "$CODE" = 200 ] && [ "$TAGGED" = yes ]; then
+            echo "FAIL: ${PACKAGE} ${VERSION} is on PyPI and tagged — already released."
+            exit 1
+          else
+            echo "FAIL: tag v${VERSION} exists but PyPI has no ${VERSION}."
+            echo "      Not a state this workflow creates; stopping rather than guessing."
+            exit 1
+          fi
+          echo "resume=${RESUME}" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "package=${PACKAGE}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12.16"
+
+      # pip loads its own vendored certifi as well as the system store, with no
+      # way to turn that off, so a current certifi in uv.lock does nothing for
+      # pip itself. 26.2.2 is the release past the eMudhra advisory.
+      - name: Current pip
+        run: |
+          python -m pip install --upgrade "pip>=26.2.2"
+          python -m pip --version
+
+      - name: Install test dependencies
+        run: pip install pytest pip-audit
+
+      - name: Run security test suite
+        run: python -m pytest tests/test_security.py -v
+
+      - name: Audit dependencies for vulnerabilities
+        # Audits this package's declared dependencies (it has none today), and can fail: a known CVE stops the release.
+        # A finding with no fix yet is excepted only explicitly: --ignore-vuln ID, with a reason and date.
+        run: pip-audit --strict --desc on .
+
+      - name: Grep check — no subprocess/shell
+        run: |
+          if grep -rn 'subprocess\.\|os\.system\|shell=True' src/; then
+            echo "FAIL: subprocess/shell found in source"
+            exit 1
+          fi
+
+      - name: Grep check — no plaintext http://
+        run: |
+          # Tests the output rather than the pipeline's exit status, because the output is
+          # what this gate is actually asking about: are there any plaintext URLs. The old
+          # form here printed nothing when it failed, and answered through whichever grep
+          # was on PATH.
+          #
+          # This fix landed on `develop` as #16 and never reached `main`, which is where the
+          # release gate runs -- so every release since went out through the old check. That
+          # is the "fixed on develop is not fixed" case in .claude/rules/security.md, and
+          # retiring develop is what finally carries it across.
+          hits="$(grep -rn 'http://' src/ | grep -v 'localhost\|127\.0\.0\.1\|::1' || true)"
+          if [ -n "$hits" ]; then
+            echo "$hits"
+            echo "FAIL: non-HTTPS URL found in source"
+            exit 1
+          fi
+
+      - name: Grep check — no credential logging
+        run: |
+          if grep -rn -i 'print.*password\|print.*api_key\|logging.*password\|logging.*api_key' src/; then
+            echo "FAIL: credential logging found in source"
+            exit 1
+          fi
+
+  publish:
+    name: Build and publish to PyPI
+    needs: security
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12.16"
+
+      - name: Install build dependencies
+        if: needs.security.outputs.resume != 'true'
+        run: |
+          python -m pip install --upgrade "pip>=26.2.2"
+          python -m pip --version
+          pip install build
+
+      - name: Build package
+        if: needs.security.outputs.resume != 'true'
+        run: python -m build
+
+      - name: Publish to PyPI
+        if: needs.security.outputs.resume != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Already on PyPI — resuming
+        if: needs.security.outputs.resume == 'true'
+        run: |
+          echo "skipped the upload: this version is already on PyPI"
+
+  # ---------------------------------------------------------------------------
+  # Done when PyPI serves the version (verify); then tag the released commit. A workflow's
+  # own tag push triggers nothing. If tagging fails after PyPI serves it, the
+  # release IS published: re-running the job is safe.
+  # ---------------------------------------------------------------------------
+  verify:
+    name: Verify PyPI
+    needs: [security, publish]
+    runs-on: ubuntu-latest
+    steps:
+      - name: PyPI serves the released version
+        run: |
+          VERSION="${{ needs.security.outputs.version }}"
+          PACKAGE="${{ needs.security.outputs.package }}"
+          for i in $(seq 1 40); do
+            if [ "$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/${PACKAGE}/${VERSION}/json")" = "200" ]; then
+              echo "PyPI serves ${PACKAGE} ${VERSION}"
+              exit 0
+            fi
+            sleep 15
+          done
+          echo "FAIL: PyPI never served ${PACKAGE} ${VERSION}"
+          exit 1
+
+  tag:
+    name: Tag the release
+    needs: [security, verify]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Create and push vX.Y.Z
+        run: |
+          VERSION="${{ needs.security.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${VERSION}" -m "${GITHUB_REPOSITORY#*/} ${VERSION}" "$GITHUB_SHA"
+          git push origin "v${VERSION}"
+
+      # The tag alone left every Releases page in this org empty. The body is
+      # this version's own CHANGELOG section, extracted by heading rather than
+      # by line count, because the fleet has three heading styles:
+      #   ## [0.4.0] — date    ## [2.0.0] - date    ## 0.2.0 (date)
+      # It stops at the next "## " heading, and returns nothing for a version
+      # it cannot find -- so a missing section falls back to GitHub's own
+      # generated notes rather than publishing the whole changelog.
+      #
+      # After `verify` by construction: a Release only ever describes a version
+      # already confirmed on PyPI.
+      - name: Create the GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          VERSION="${{ needs.security.outputs.version }}"
+          python3 - "$VERSION" CHANGELOG.md > /tmp/notes.md <<'EXTRACT'
+          import re, sys, pathlib
+          ver, path = sys.argv[1], sys.argv[2]
+          text = pathlib.Path(path).read_text()
+          start = re.search(r'(?m)^##\s+\[?%s\]?\b.*$' % re.escape(ver), text)
+          if not start:
+              raise SystemExit(0)
+          rest = text[start.end():]
+          nxt = re.search(r'(?m)^##\s', rest)
+          print((rest[:nxt.start()] if nxt else rest).strip())
+          EXTRACT
+
+          # A version with a suffix (0.2.1rc1) is a pre-release, not Latest.
+          PRE=""
+          case "$VERSION" in
+            *[!0-9.]*) PRE="--prerelease" ;;
+          esac
+
+          if [ -s /tmp/notes.md ]; then
+            echo "release notes: this version's CHANGELOG section ($(wc -l < /tmp/notes.md) lines)"
+            gh release create "v${VERSION}" --verify-tag --title "v${VERSION}" \
+              --notes-file /tmp/notes.md $PRE
+          else
+            echo "release notes: no CHANGELOG section for ${VERSION}; using generated notes"
+            gh release create "v${VERSION}" --verify-tag --title "v${VERSION}" \
+              --generate-notes $PRE
+          fi

qso_graph_lib-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

qso_graph_lib-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `qso-graph-lib` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-29
+
+### Added
+
+- **`qso_graph_lib.jt`**: WSJT-X's UDP protocol for the JT family (`protocol`), encoded and decoded
+  to `NetworkMessage.hpp`, schema 3, and WSJT-X's `ALL.TXT` reader (`alltxt`). Moved from
+  qso-graph-sim, so it and jt-mcp share one implementation.