sheridan-diffract 1.0.1__tar.gz

sheridan_diffract-1.0.1/.github/workflows/bump.yaml

@@ -0,0 +1,99 @@
+name: Bump version
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  bump:
+    name: Commitizen bump
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Check for bump commit (infinite loop guard)
+        id: guard
+        env:
+          HEAD_MSG: ${{ github.event.head_commit.message }}
+        run: |
+          if [[ "$HEAD_MSG" == bump:* ]]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/checkout@v6
+        if: steps.guard.outputs.skip == 'false'
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.14
+        if: steps.guard.outputs.skip == 'false'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        if: steps.guard.outputs.skip == 'false'
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        if: steps.guard.outputs.skip == 'false'
+        run: uv sync --all-extras --dev
+
+      - name: Configure git identity
+        if: steps.guard.outputs.skip == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        if: steps.guard.outputs.skip == 'false'
+        id: bump
+        run: |
+          set +e
+          uv run cz bump --yes
+          code=$?
+          set -e
+          if [[ $code -eq 0 ]]; then
+            NEW_VERSION=$(uv run python -c "import tomllib; f=open('pyproject.toml','rb'); d=tomllib.load(f); print(d['project']['version'])")
+            echo "bumped=true" >> "$GITHUB_OUTPUT"
+            echo "new_version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+          elif [[ $code -eq 21 ]]; then
+            echo "No releasable commits — nothing to bump."
+            echo "bumped=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "cz bump failed with exit code $code."
+            exit $code
+          fi
+        env:
+          FORCE_COLOR: "1"
+
+      - name: Push bump branch
+        if: steps.guard.outputs.skip == 'false' && steps.bump.outputs.bumped == 'true'
+        env:
+          NEW_VERSION: ${{ steps.bump.outputs.new_version }}
+        run: |
+          git push origin --delete "chore/version-bump-$NEW_VERSION" || true
+          git checkout -b "chore/version-bump-$NEW_VERSION"
+          git push origin "chore/version-bump-$NEW_VERSION"
+
+      - name: Open and auto-merge version bump PR
+        if: steps.guard.outputs.skip == 'false' && steps.bump.outputs.bumped == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          NEW_VERSION: ${{ steps.bump.outputs.new_version }}
+        run: |
+          if gh pr list --head "chore/version-bump-$NEW_VERSION" --state open | grep -q .; then
+            echo "PR already open for chore/version-bump-$NEW_VERSION — skipping."
+          else
+            gh pr create \
+              --title "bump: $NEW_VERSION" \
+              --body "Automated version bump to $NEW_VERSION generated by Commitizen." \
+              --base main \
+              --head "chore/version-bump-$NEW_VERSION"
+            gh pr edit "chore/version-bump-$NEW_VERSION" --add-label automated || true
+            gh pr merge "chore/version-bump-$NEW_VERSION" --squash --auto
+          fi

sheridan_diffract-1.0.1/.github/workflows/ci.yaml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    name: All gates
+    runs-on: ubuntu-latest
+    if: |
+      !startsWith(github.event.head_commit.message, 'bump:') &&
+      !startsWith(github.head_ref, 'chore/version-bump-')
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Restore Dagger engine cache
+        id: cache-dagger
+        uses: actions/cache@v5
+        with:
+          path: /tmp/dagger-engine.tar
+          key: dagger-engine-v0.20.3
+
+      - name: Load Dagger engine image
+        if: steps.cache-dagger.outputs.cache-hit == 'true'
+        run: docker load -i /tmp/dagger-engine.tar
+
+      - name: Run CI pipeline
+        uses: dagger/dagger-for-github@v8.4.0
+        with:
+          version: "0.20.3"
+          call: check --source=.
+
+      - name: Save Dagger engine image
+        if: steps.cache-dagger.outputs.cache-hit != 'true'
+        run: docker save registry.dagger.io/engine:v0.20.3 -o /tmp/dagger-engine.tar

sheridan_diffract-1.0.1/.github/workflows/docs.yaml

@@ -0,0 +1,35 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.14
+      - run: pip install zensical "mkdocstrings[python]"
+      - run: cp README.md docs/index.md
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

sheridan_diffract-1.0.1/.github/workflows/pr-title.yaml

@@ -0,0 +1,24 @@
+# Enforce Conventional Commits format on pull request titles.
+#
+# Uses pull_request_target so the workflow runs with repo permissions even for
+# forks. Only pull-requests: read is needed — no write access required.
+
+name: PR title
+
+on:
+  pull_request_target:
+    types: [opened, reopened, edited, synchronize]
+
+jobs:
+  lint-pr-title:
+    name: Lint PR title
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.event.pull_request.head.ref, 'chore/version-bump-')"
+    permissions:
+      pull-requests: read
+
+    steps:
+      - name: Validate conventional commit format
+        uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50  # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

sheridan_diffract-1.0.1/.github/workflows/publish.yaml

@@ -0,0 +1,68 @@
+# Publish sheridan-diffract to PyPI on version tag push.
+#
+# Prerequisites — register this repo as a trusted publisher on pypi.org:
+#   pypi.org → Account Settings → Publishing → Add a new pending publisher
+#     Owner:      andrewasheridan
+#     Repository: diffract
+#     Workflow:   publish.yaml
+#     Environment: pypi   (must match the `environment:` name on the publish job)
+#
+# Once registered, PyPI trusts GitHub's OIDC token — no API token secrets needed.
+#
+# Triggered by tag-on-merge.yaml pushing a v* tag. Using push.tags (not
+# workflow_call) so GitHub issues a first-party OIDC token — workflow_call
+# produces a reusable-workflow token that PyPI's trusted publisher rejects.
+
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:  # Allows manual re-runs via gh CLI or UI
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sheridan-diffract
+    permissions:
+      contents: read
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sheridan_diffract-1.0.1/.github/workflows/tag-on-merge.yaml

@@ -0,0 +1,51 @@
+# When a version-bump PR is squash-merged into main, create an annotated tag on
+# the merge commit. publish.yaml listens for the resulting tag push and handles
+# the PyPI release — workflow_call cannot be used because it produces a
+# reusable-workflow OIDC token that PyPI's trusted publisher rejects.
+#
+# RELEASE_TOKEN is passed to actions/checkout so that checkout's git credential
+# helper is wired to the PAT rather than GITHUB_TOKEN. Without this, the helper
+# installed by checkout overrides any credential embedded in the remote URL, the
+# push is attributed to GITHUB_TOKEN, and GitHub suppresses the push.tags event
+# that publish.yaml depends on.
+
+name: Tag on merge
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  tag-merge-commit:
+    name: Tag merge commit
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'chore/version-bump-')
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}   # wire credential helper to PAT so tag push triggers publish.yaml
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Extract version from branch name
+        id: extract
+        run: |
+          BRANCH="${{ github.event.pull_request.head.ref }}"
+          VERSION="${BRANCH#chore/version-bump-}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        env:
+          VERSION: ${{ steps.extract.outputs.version }}
+        run: |
+          git tag -a "v$VERSION" "${{ github.event.pull_request.merge_commit_sha }}" -m "Version $VERSION"
+          git push origin "v$VERSION"

sheridan_diffract-1.0.1/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing & coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+
+# uv
+uv.lock
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Claude
+.claude/worktrees/
+.claude/settings.local.json

sheridan_diffract-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.7
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        args: [--strict]
+        files: ^src/
+        additional_dependencies: [gitpython, sheridan-iceberg]
+
+  - repo: https://github.com/andrewasheridan/diffract
+    rev: v1.0.1  # diffract
+    hooks:
+      - id: diffract-validate

sheridan_diffract-1.0.1/.pre-commit-hooks.yaml

@@ -0,0 +1,23 @@
+# Pre-commit hook definitions for sheridan-diffract.
+#
+# To use these hooks in another project, add the following to your
+# .pre-commit-config.yaml:
+#
+#   repos:
+#     - repo: https://github.com/sheridan/diffract
+#       rev: v<VERSION>
+#       hooks:
+#         - id: diffract-validate
+
+- id: diffract-validate
+  name: diffract (validate commit message type)
+  description: >
+    Validates that the conventional commit type in the commit message matches
+    the API change diffract detects. Exits 0 on match or unrecognised type;
+    exits 1 on mismatch. Non-conventional commits (docs:, chore:, etc.) are
+    never blocked. Configure the source directory via diffract.toml or
+    pyproject.toml [tool.diffract] rather than hook args.
+  language: python
+  entry: diffract --validate-msg-file
+  pass_filenames: true
+  stages: [commit-msg]

sheridan_diffract-1.0.1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `sheridan-diffract` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## ['0.1.0'] - Initial release
+
+### Added
+
+- Initial project structure

sheridan_diffract-1.0.1/CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md — sheridan-diffract
+
+## Project overview
+
+`sheridan-diffract` detects how a Python package's public API changed between two git commits and classifies that change as a conventional commit type. It has no AST logic of its own — it delegates API surface extraction entirely to `sheridan-iceberg`.
+
+## Commands
+
+```bash
+task check          # full gate: lint, format, typecheck, tests (run before every commit)
+task lint           # ruff check --fix
+task lint:check     # ruff check (read-only, used in CI)
+task format         # ruff format
+task format:check   # ruff format --check (read-only, used in CI)
+task typecheck      # mypy --strict src/
+task test           # pytest --cov (coverage ≥ 90% required)
+task install        # uv sync --all-extras --dev
+```
+
+## Architecture
+
+```
+src/sheridan/diffract/
+├── __init__.py      # Public re-exports; __version__ from importlib.metadata
+├── enums.py         # CommitType, ChangeKind (StrEnum)
+├── exceptions.py    # DiffractError → GitError / SurfaceError
+├── models.py        # NameChange, ApiDiff, DiffractResult (frozen dataclasses)
+├── differ.py        # diff_surfaces() — set-diff two iceberg API surfaces
+├── classifier.py    # classify() — maps ApiDiff → CommitType + summary
+├── git_utils.py     # get_repo(), get_api_at_ref(), has_python_changes(), get_api_at_index(), has_python_changes_index()
+├── checker.py       # check() — orchestrates git → iceberg → diff → classify; check_staged() — HEAD vs index
+├── config.py        # load_config() — DiffractConfig from diffract.toml / pyproject.toml
+└── cli.py           # argparse CLI: `diffract [BASE] [HEAD] [--src] [--json] [--exit-code] [--validate-msg-file]`
+```
+
+### Key dependency: sheridan-iceberg
+
+```python
+from sheridan.iceberg import get_public_api
+# get_public_api(path: Path | str) -> dict[str, list[str]]
+# Returns: {"module.qualified.name": ["PublicName1", "ClassFoo", ...], ...}
+```
+
+`diffract` calls `get_public_api` twice (once per ref), then diffs the two dicts.
+
+### Classification rules (in priority order)
+
+1. Any public name **removed** → `feat!` (breaking)
+2. Any public name **added** (no removals) → `feat`
+3. No name changes, but `.py` files changed → `refactor`
+4. No changes detected → `fix`
+
+## Code conventions
+
+- **Python ≥ 3.14** — use modern syntax freely (`X | Y`, `match`, etc.)
+- **`from __future__ import annotations`** at top of every file
+- **`__all__`** declared in every module
+- **Frozen dataclasses** for all result/model types
+- **`StrEnum`** for enumerations
+- **Google-style docstrings** on all public functions, classes, and methods
+- **Line length**: 120 characters (ruff enforced)
+- **Import order**: stdlib → third-party → local (isort via ruff)
+
+## Testing conventions
+
+- **pytest** only — never `unittest.TestCase`
+- **pytest-mock** for patching: use the `mocker` fixture, not `unittest.mock.patch`
+- **`monkeypatch`** for environment/`sys.argv` modification
+- **No `MagicMock` as fixture arguments** — construct them inline with `MagicMock()`
+- Shared fixtures live in `tests/conftest.py`
+- One test file per source module: `test_<module>.py`
+- Coverage threshold: **≥ 90%** (enforced by pytest-cov)
+
+## Dependencies
+
+- **Runtime**: `sheridan-iceberg`, `gitpython`
+- **Dev**: `ruff`, `mypy`, `pytest`, `pytest-cov`, `pytest-mock`, `commitizen`, `pre-commit`, `bandit`, `zensical`, `mkdocstrings`
+
+### Adding dependencies
+
+Always run the dependency auditor before adding a new runtime dependency. Context matters: the automated auditor rejected `gitpython` on security grounds, but human review approved it (see ADR-002) because the CVEs are patched, inputs are controlled, and it handles git hook environment variables correctly.
+
+## Commit format (Conventional Commits via commitizen)
+
+```
+feat:     add new public API
+feat!:    remove or rename a public API (breaking)
+fix:      correct a bug with no API change
+refactor: internal restructuring, no API change
+docs:     documentation only
+test:     add or update tests
+chore:    maintenance (deps, config, tooling)
+```
+
+## GitHub Actions workflows
+
+Workflow files live in `.github/workflows/` and use the **`.yaml` extension** (not `.yml`).
+
+## Architecture Decision Records
+
+Significant decisions are documented in `docs/decisions/`. Use the `adr` skill to add new ones.
+
+## Configuration
+
+diffract reads `src` from the first config file found in the repo root:
+
+| File | Key |
+|---|---|
+| `diffract.toml` | `src = "python/src"` |
+| `pyproject.toml` | `[tool.diffract]` → `src = "python/src"` |
+
+If neither file is present, `--src` CLI flag is used, falling back to `src/`.
+
+Priority: `--src` flag > `diffract.toml` > `pyproject.toml` > default (`src/`)
+
+## CLI flags
+
+```
+diffract [BASE] [HEAD]            # defaults: HEAD~1, HEAD
+  --src PATH                      # source directory (default: src); use --src . for flat layouts
+  --json                          # output JSON instead of human-readable text
+  --exit-code                     # exit 1 (breaking), 2 (any API change), 0 (no change)
+  --validate-msg-file MSGFILE     # validate conventional commit type against detected API change
+```
+
+When `--validate-msg-file` is used **without** explicit `BASE`/`HEAD` refs (the standard commit-msg hook invocation), diffract automatically compares `HEAD` against the **git staging area** rather than `HEAD~1 → HEAD`. This ensures the hook validates what is actually being committed, not what was committed last. Pass explicit refs to override (e.g. for CI use with `diffract base.sha head.sha --validate-msg-file …`).
+
+## pre-commit hooks
+
+One hook is exported from `.pre-commit-hooks.yaml`:
+
+| Hook id | Stage | Purpose |
+|---|---|---|
+| `diffract-validate` | commit-msg | Fails if the commit message type doesn't match the detected API change |
+
+The hook reads `src` from `diffract.toml` or `pyproject.toml` automatically:
+
+```yaml
+- id: diffract-validate
+```
+
+## What diffract does NOT do
+
+- No AST logic — all API surface extraction is delegated to `sheridan-iceberg`
+- No signature diffing — only name-level additions/removals are detected
+- No automatic commit rewriting — diffract only reports and optionally fails CI

sheridan_diffract-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to sheridan-diffract
+
+Thank you for considering a contribution!
+
+## Setup
+
+```bash
+task install
+pre-commit install
+```
+
+## Workflow
+
+1. Create a feature branch from `main`
+2. Write your code and tests (coverage must remain ≥ 90%)
+3. Run `task check` — all gates must pass
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/) format
+5. Open a pull request
+
+## Running checks
+
+```bash
+task check        # all gates: lint, format, typecheck, test
+task lint         # ruff check + autofix
+task format       # ruff format
+task typecheck    # mypy --strict
+task test         # pytest with coverage
+```
+
+## Commit format
+
+This project uses [Commitizen](https://commitizen-tools.github.io/commitizen/) with Conventional Commits:
+
+```
+feat: add new feature
+fix: correct a bug
+docs: update documentation
+chore: maintenance tasks
+refactor: code restructuring without behavior change
+test: add or update tests
+```
+
+## Adding dependencies
+
+- Propose new runtime dependencies in a PR with a clear justification
+- Keep the runtime dependency list minimal
+- Dev dependencies go under `[project.optional-dependencies] dev`
+
+## Architecture Decision Records
+
+Significant decisions are recorded as ADRs in `docs/decisions/`.
+Use the `docs/decisions/` directory to document any non-obvious choices.
+
+## CI pipeline
+
+The full CI pipeline runs via Dagger:
+
+```bash
+task ci-init   # first time only
+task ci        # run all gates in containers
+```
+
+Individual gates: `task lint:check`, `task format:check`, `task typecheck`, `task test`.

sheridan_diffract-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sheridan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.