gammonview 1.0.0__tar.gz

gammonview-1.0.0/.gitattributes

@@ -0,0 +1,21 @@
+# Normalise line endings to LF. Nothing tracked here contains a CRLF today, so
+# this is a no-op on the current tree; it exists so a clone with
+# core.autocrlf=true cannot start rewriting one, in a repo whose tests compare
+# fixtures exactly.
+* text=auto eol=lf
+
+# Binary fixtures, declared rather than detected. Git's heuristic would catch
+# every one of these (all carry NULs in the first bytes -- checked), but "would
+# detect" is the wrong guarantee for files a test compares as raw bytes: the
+# .gvab goldens that pin the format, and the .xg/.bgf sources the converters
+# are asserted against ply by ply. Declaring it also stops these showing up as
+# diff noise.
+*.gvab binary
+*.xg   binary
+*.bgf  binary
+*.png  binary
+
+# Generated lockfiles: collapsed in diffs on GitHub, and never worth reviewing
+# line by line. They are still tracked, and still reviewed as a version bump.
+uv.lock linguist-generated=true -diff
+gvformat-js/package-lock.json linguist-generated=true -diff

gammonview-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,127 @@
+# The cheap half of the suite, on every push and pull request.
+#
+# `tests/run_all.py --fast` skips the thirteen names in that file's ENGINE_BACKED
+# set -- the tests that need the `[engine]` extra and minutes of CPU. Those run
+# in engine.yml on a slower cadence. Splitting them is what keeps this workflow
+# a few seconds per row, so the matrix below can afford to be wide.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# A newer push to the same ref makes the older run's verdict worthless.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  codec:
+    name: codec (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # One red row should not hide the state of the others -- the usual reason
+      # to look at this matrix is to find out *which* versions broke.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          # Windows earns a row on its own merits: the suite compares .gvab
+          # goldens as raw bytes and reads .gva back with read_text(), which is
+          # precisely the sort of thing a line-ending or default-encoding
+          # difference breaks. .gitattributes is the other half of that defence.
+          - os: windows-latest
+            python: "3.13"
+          # macOS is the author's platform, so it is the configuration every
+          # change is written against; a row here says so out loud.
+          - os: macos-latest
+            python: "3.13"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      # Two flags, each load-bearing:
+      #
+      # `--python` is not optional. A tracked .python-version pins 3.13 and uv
+      # honours it, so without an explicit override every row of this matrix
+      # would quietly run 3.13 and the 3.10 row would prove nothing at all.
+      #
+      # `--no-dev` is the assertion, not a saving. The dev group carries bgsage
+      # and pyyaml; leaving it out means this job installs the project with zero
+      # third-party dependencies, which is the README's central claim about
+      # `gvformat`. If an import creeps in from the engine side, this goes red.
+      - name: fast suite, no engine
+        run: uv run --python ${{ matrix.python }} --no-dev python tests/run_all.py --fast
+
+  js:
+    name: gvformat-js (node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      # package.json declares `engines: node >=18`. Test the floor it promises
+      # and the current release; the versions between them are not where an ESM
+      # or TypedArray difference is going to appear.
+      matrix:
+        node: ["18", "24"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: gvformat-js/package-lock.json
+
+      # `npm ci`, not `npm install`: the one runtime dependency (pako) is
+      # pinned in the lockfile, and the lockfile is what the published tarball
+      # is built against. The only publishConfig here is `access: public`,
+      # which scoped packages need at publish time and which affects nothing
+      # about this install.
+      - run: npm ci
+        working-directory: gvformat-js
+
+      - run: npm test
+        working-directory: gvformat-js
+
+  build:
+    name: build (sdist + wheel)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags. A shallow clone has no
+          # tags and the build does not fail -- it quietly stamps 0.1.dev1+g...
+          # on the artifacts. Fetch everything, then print what it decided.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv build
+
+      - name: report the derived version
+        run: ls -l dist/
+
+      # The wheel's real test is whether the base install works on its own. No
+      # project, no extras, nothing from the lockfile: just the wheel and a
+      # bare interpreter. This is what `pip install gammonview` gets.
+      #
+      # It runs from outside the checkout on purpose. With the repo as cwd,
+      # `import gvformat` finds the source tree sitting right there and the
+      # check passes without the wheel being involved at all -- so the assert
+      # insists the module actually came out of a site-packages.
+      - name: the wheel imports with no extras
+        working-directory: ${{ runner.temp }}
+        run: |
+          uv run --isolated --no-project --with "$GITHUB_WORKSPACE"/dist/*.whl \
+            python -c 'import gvformat, pathlib; p = pathlib.Path(gvformat.__file__); print(p); assert "site-packages" in p.parts, p'

gammonview-1.0.0/.github/workflows/engine.yml

@@ -0,0 +1,70 @@
+# The engine-backed half of the suite: the thirteen names in run_all.py's
+# ENGINE_BACKED set. They need the `[engine]` extra -- bgsage, a large compiled
+# wheel, plus pyyaml -- and they analyze a whole match, so they cost minutes
+# where ci.yml costs seconds. That is the only reason they are split out; it is
+# a cadence decision, not a statement about how much they matter.
+#
+# One thing to know before reading this job's output: three of these tests
+# consume tests/golden/, and two compare engine output to it *exactly*.
+# test_ogxm_pipeline re-analyzes the corpus and requires the .gvab to match
+# byte-for-byte; test_luck_fill re-measures luck and requires identical floats,
+# on purpose ("not close, identical"). Those goldens were generated on macOS
+# arm64, and **bgsage does not reproduce them here**: measured 2026-09-13 on
+# this runner with the same bgsage build, one best move of 521 changed, one cube
+# verdict of 296 changed, and one match's PR moved 6.448 -> 6.246. It is not
+# rounding, and it is not a bug -- it is a different CPU.
+#
+# So those two comparisons are platform-gated: they skip by name wherever the
+# machine does not match tests/golden/PROVENANCE.json, and every structural
+# check in the same two files still runs. Expect a handful of SKIP lines here
+# and nothing red. The gate is in tests/fixtures.py:goldens_are_native; the
+# provenance file is stamped by regen_golden.py, so regenerating on a different
+# machine moves the gate rather than needing this comment edited.
+#
+# tests/regen_golden.py is genuinely not run: regenerating is a maintainer action
+# on the machine that owns the goldens, and CLAUDE.md explains why the diff wants
+# reading rather than accepting.
+name: engine
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    # Mondays, 06:00 UTC. This is the run that catches a bgsage release moving
+    # the numbers underneath us without anyone here touching a file.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: engine-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  full-suite:
+    name: full suite (py${{ matrix.python }})
+    # ubuntu-latest is x86_64 on purpose. bgsage publishes manylinux wheels for
+    # x86_64 only, so an arm64 runner would fall back to the sdist and spend the
+    # job compiling an engine instead of testing against one.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      # The floor and the version this repo develops on. The middle of the
+      # range is covered by ci.yml, which exercises the same source without
+      # the engine.
+      matrix:
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      # No --no-dev here: the dev group is exactly what these tests need. The
+      # runner reports skips separately from passes, so a suite that quietly
+      # stopped finding its fixtures does not read as green.
+      - name: full suite
+        run: uv run --python ${{ matrix.python }} python tests/run_all.py

gammonview-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,93 @@
+# Publish to PyPI via trusted publishing (OIDC). No API token exists anywhere:
+# PyPI is configured to trust *this workflow in this repository*, and mints a
+# short-lived credential for the job at run time. Nothing to store, leak, or
+# rotate, and a stolen repo secret cannot publish because there is no secret.
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/), which
+# must be done before the first run, because the project does not exist yet:
+#
+#     PyPI project name : gammonview
+#     Owner             : ngvlamis
+#     Repository name   : gammonview-analysis
+#     Workflow name     : publish.yml
+#     Environment name  : pypi
+#
+# That registers a "pending publisher"; the project is created by the first
+# successful upload.
+name: publish
+
+on:
+  # A tag is the release signal, matching how the version is derived: hatch-vcs
+  # reads it from git, so the tag *is* the version. Pushing v1.2.3 publishes
+  # 1.2.3 -- there is no number to bump anywhere else, and no way for the tag
+  # and the artifact to disagree.
+  push:
+    tags: ["v*"]
+  # Manual trigger, for a tag that already exists (as v1.0.0 did when this
+  # workflow was written) or to retry a failed upload.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, and a shallow clone has
+          # none. It does not fail -- it quietly stamps 0.1.dev1+g<sha> on the
+          # artifacts, which is the sort of thing you discover on PyPI.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - run: uv build
+
+      # Refuse to publish a version that git did not name. Without this, a run
+      # from an untagged commit uploads a dev version to PyPI, where it cannot
+      # be taken back.
+      - name: the artifacts carry a real release version
+        run: |
+          ls -l dist/
+          version=$(ls dist/*.whl | sed -E 's|.*/gammonview-([^-]+)-py3.*|\1|')
+          echo "derived version: $version"
+          case "$version" in
+            *dev*|*+*)
+              echo "::error::refusing to publish $version -- hatch-vcs found no tag on this commit"
+              exit 1 ;;
+          esac
+
+      - name: metadata renders on PyPI
+        run: uv run --isolated --no-project --with twine python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment is the approval gate: GitHub can require a manual review
+    # before the job runs, and PyPI's trusted publisher is bound to this name,
+    # so a workflow that does not declare it cannot publish.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gammonview
+    permissions:
+      # The OIDC token this mints is what PyPI trades for an upload credential.
+      # Without it the action fails with a confusing 403.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

gammonview-1.0.0/.gitignore

@@ -0,0 +1,40 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Test-runner scratch. The suite here is standalone scripts run by
+# tests/run_all.py, not pytest -- but contributors reach for pytest anyway, and
+# it leaves this behind.
+.pytest_cache/
+
+# Virtual environments
+.venv
+
+# JS mirror dependencies (installed by `npm install` in gvformat-js/)
+node_modules/
+
+# Agent instruction data -- covered by a global gitignore on the author's
+# machine, which a public clone obviously cannot rely on.
+.claude/
+
+# User-created preset overrides (built-in defaults live in presets.py)
+presets.yaml
+
+# Live OpenGammon API data for test-og.js's parity section: pulled from a real
+# account, so it carries real handles. Everything else under samples/ is
+# committed and anonymized -- this one directory is not.
+samples/og/
+
+# Instructions for non-Claude agents. Not part of the project.
+AGENTS.md
+
+# Local maintainer notes (NOTES.local.md and friends): superseded workflows,
+# host paths -- true and useful, but not public-repo material.
+*.local.md
+
+# Mac System files
+.DS_Store

gammonview-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13