gabion 0.1.0__tar.gz

gabion-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

gabion-0.1.0/.github/ISSUE_TEMPLATE/sppf-node.yml

@@ -0,0 +1,76 @@
+name: "SPPF node"
+description: "Track a node from docs/sppf_checklist.md"
+title: "[SPPF] <node>"
+labels:
+  - "sppf-node"
+  - "planning"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form to track an item from `docs/sppf_checklist.md`.
+        Paste the exact checklist line so the linkage is unambiguous.
+  - type: input
+    id: checklist_entry
+    attributes:
+      label: Checklist entry
+      description: Paste the exact checklist line (including [ ] or [~]).
+      placeholder: "- [ ] Refactor engine: Signature rewriting (def foo(a, b) -> def foo(bundle))."
+    validations:
+      required: true
+  - type: input
+    id: checklist_section
+    attributes:
+      label: Checklist section
+      description: Section header containing the entry (e.g., "Phase 3: Refactoring & UX").
+      placeholder: "Phase 3: Refactoring & UX"
+    validations:
+      required: true
+  - type: dropdown
+    id: status
+    attributes:
+      label: Status
+      options:
+        - planned
+        - partial/heuristic
+    validations:
+      required: true
+  - type: input
+    id: dependencies
+    attributes:
+      label: Dependencies
+      description: Related issues or prerequisites (optional).
+      placeholder: "#123, #456"
+    validations:
+      required: false
+  - type: textarea
+    id: acceptance_criteria
+    attributes:
+      label: Acceptance criteria
+      description: What must be true for this node to be marked [x]?
+      placeholder: "List objective criteria and expected test evidence."
+    validations:
+      required: true
+  - type: textarea
+    id: test_plan
+    attributes:
+      label: Test plan
+      description: Tests or checks to validate completion (optional).
+      placeholder: "pytest tests/test_..."
+    validations:
+      required: false
+  - type: input
+    id: target_release
+    attributes:
+      label: Target release
+      description: Optional release tag or milestone.
+      placeholder: "v0.1.0-alpha"
+    validations:
+      required: false
+  - type: checkboxes
+    id: checklist_linkback
+    attributes:
+      label: Checklist linkage
+      options:
+        - label: "I will add the GH issue ID to the checklist entry after creation."
+          required: true

gabion-0.1.0/.github/actions/gabion/README.md

@@ -0,0 +1,30 @@
+## Gabion Composite Action
+
+This composite action installs and runs Gabion using the system Python.
+
+### Inputs
+- `version`: pip specifier (default: `gabion`)
+- `command`: subcommand to run (default: `check`)
+- `root`: project root (default: `.`)
+- `config`: path to gabion config (optional)
+- `report`: path to write a Markdown report (optional)
+- `args`: extra CLI args (optional)
+
+### Example
+```yaml
+name: gabion
+on:
+  pull_request:
+jobs:
+  gabion:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@<PINNED_SHA>
+      - uses: actions/setup-python@<PINNED_SHA>
+        with:
+          python-version: "3.11"
+      - uses: mikemol/gabion/.github/actions/gabion@<TAG_OR_SHA>
+        with:
+          command: "check"
+          args: "--fail-on-violations"
+```

gabion-0.1.0/.github/actions/gabion/action.yml

@@ -0,0 +1,40 @@
+name: "Gabion"
+description: "Run gabion check against a repository"
+inputs:
+  version:
+    description: "Gabion version specifier for pip (default: gabion)"
+    required: false
+    default: "gabion"
+  command:
+    description: "Gabion subcommand to run (default: check)"
+    required: false
+    default: "check"
+  root:
+    description: "Project root for gabion (default: .)"
+    required: false
+    default: "."
+  config:
+    description: "Path to gabion.toml or config file"
+    required: false
+    default: ""
+  report:
+    description: "Path for Markdown report (optional)"
+    required: false
+    default: ""
+  args:
+    description: "Additional CLI args"
+    required: false
+    default: ""
+runs:
+  using: "composite"
+  steps:
+    - name: Run Gabion
+      shell: bash
+      run: "${{ github.action_path }}/run.sh"
+      env:
+        GABION_VERSION: "${{ inputs.version }}"
+        GABION_COMMAND: "${{ inputs.command }}"
+        GABION_ROOT: "${{ inputs.root }}"
+        GABION_CONFIG: "${{ inputs.config }}"
+        GABION_REPORT: "${{ inputs.report }}"
+        GABION_ARGS: "${{ inputs.args }}"

gabion-0.1.0/.github/actions/gabion/run.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v python >/dev/null 2>&1; then
+  echo "python is required to run gabion" >&2
+  exit 2
+fi
+
+python -m pip install --upgrade pip >/dev/null
+python -m pip install "${GABION_VERSION}"
+
+cmd=("${GABION_COMMAND}")
+if [[ -n "${GABION_ROOT}" ]]; then
+  cmd+=("--root" "${GABION_ROOT}")
+fi
+if [[ -n "${GABION_CONFIG}" ]]; then
+  cmd+=("--config" "${GABION_CONFIG}")
+fi
+if [[ -n "${GABION_REPORT}" ]]; then
+  cmd+=("--report" "${GABION_REPORT}")
+fi
+if [[ -n "${GABION_ARGS}" ]]; then
+  # shellcheck disable=SC2206
+  cmd+=(${GABION_ARGS})
+fi
+
+python -m gabion "${cmd[@]}"

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

@@ -0,0 +1,63 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - stage
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    if: github.event_name != 'workflow_dispatch' || github.ref == 'refs/heads/stage'
+    runs-on: ubuntu-latest
+    env:
+      MISE_TRUSTED_CONFIG_PATHS: ${{ github.workspace }}
+    steps:
+      # Allow-listed actions: actions/checkout, jdx/mise-action
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - name: Install mise
+        uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8
+      - name: Install toolchain
+        run: mise install
+      - name: Install package
+        run: mise exec -- python -m pip install -e .
+      - name: Install test deps
+        run: mise exec -- python -m pip install pytest
+      - name: Policy check (workflows)
+        run: |
+          mise exec -- python -m pip install pyyaml
+          mise exec -- python scripts/policy_check.py --workflows
+      - name: Policy check (posture)
+        if: github.event_name == 'push'
+        env:
+          POLICY_GITHUB_TOKEN: ${{ secrets.POLICY_GITHUB_TOKEN }}
+        run: |
+          if [ -z "${POLICY_GITHUB_TOKEN:-}" ]; then
+            echo "POLICY_GITHUB_TOKEN not set; skipping posture check."
+            exit 0
+          fi
+          mise exec -- python scripts/policy_check.py --posture
+      - name: Dataflow audit
+        run: mise exec -- python -m gabion check
+      - name: Docflow audit
+        run: mise exec -- python scripts/docflow_audit.py --root . --fail-on-violations
+      - name: Tests
+        run: |
+          mkdir -p artifacts/test_runs
+          mise exec -- python -m pytest \
+            --junitxml artifacts/test_runs/junit.xml \
+            --log-file artifacts/test_runs/pytest.log \
+            --log-file-level=INFO
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: test-runs
+          path: artifacts/test_runs

gabion-0.1.0/.github/workflows/pr-dataflow-grammar.yml

@@ -0,0 +1,113 @@
+name: pr-dataflow-grammar
+
+on:
+  pull_request:
+    paths:
+      - "scripts/**"
+      - "src/**"
+      - "gabion.toml"
+      - ".github/workflows/pr-dataflow-grammar.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  dataflow-grammar:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    env:
+      MISE_TRUSTED_CONFIG_PATHS: ${{ github.workspace }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - name: Install mise
+        uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8
+      - name: Install toolchain
+        run: mise install
+      - name: Install package
+        run: mise exec -- python -m pip install -e .
+      - name: Render dataflow grammar report
+        run: |
+          mkdir -p artifacts/dataflow_grammar
+          mise exec -- python -m gabion dataflow-audit . \
+            --root . \
+            --report artifacts/dataflow_grammar/report.md \
+            --dot artifacts/dataflow_grammar/dataflow_graph.dot \
+            --type-audit-report
+      - name: Upload dataflow artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: dataflow-grammar
+          path: artifacts/dataflow_grammar
+      - name: Comment on PR with report
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          RUN_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import json
+          import os
+          import pathlib
+          import urllib.request
+
+          token = os.environ["GITHUB_TOKEN"]
+          repo = os.environ["REPO"]
+          issue = os.environ["PR_NUMBER"]
+          run_url = os.environ["RUN_URL"]
+          marker = "<!-- dataflow-grammar -->"
+          report_path = pathlib.Path("artifacts/dataflow_grammar/report.md")
+          if report_path.exists():
+              report = report_path.read_text()
+          else:
+              report = f"{marker}\nDataflow grammar report generated.\n"
+          if marker not in report:
+              report = f"{marker}\n{report}"
+          footer = f"\n\n- Artifact: dataflow-grammar\n- Download: {run_url}\n"
+          body = report + footer
+          if len(body) > 60000:
+              body = body[:60000] + "\n\n(truncated)\n" + footer
+
+          def request(url, method="GET", payload=None):
+              data = None if payload is None else json.dumps(payload).encode("utf-8")
+              req = urllib.request.Request(
+                  url,
+                  data=data,
+                  headers={
+                      "Authorization": f"Bearer {token}",
+                      "Accept": "application/vnd.github+json",
+                      "Content-Type": "application/json",
+                  },
+                  method=method,
+              )
+              with urllib.request.urlopen(req) as resp:
+                  return json.loads(resp.read().decode("utf-8"))
+
+          comments = []
+          page = 1
+          while True:
+              url = (
+                  f"https://api.github.com/repos/{repo}/issues/{issue}/comments"
+                  f"?per_page=100&page={page}"
+              )
+              batch = request(url)
+              if not batch:
+                  break
+              comments.extend(batch)
+              page += 1
+
+          existing = next(
+              (c for c in comments if marker in (c.get("body") or "")),
+              None,
+          )
+          if existing:
+              request(existing["url"], method="PATCH", payload={"body": body})
+          else:
+              url = f"https://api.github.com/repos/{repo}/issues/{issue}/comments"
+              request(url, method="POST", payload={"body": body})
+          PY

gabion-0.1.0/.github/workflows/release-test.yml

@@ -0,0 +1,34 @@
+name: release-test
+
+on:
+  push:
+    tags:
+      - "test-v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/gabion/
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: "3.11"
+      - name: Build artifacts
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e
+        with:
+          repository-url: https://test.pypi.org/legacy/

gabion-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/gabion/
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: "3.11"
+      - name: Build artifacts
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e

gabion-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+artifacts/*
+!artifacts/.gitkeep

gabion-0.1.0/AGENTS.md

@@ -0,0 +1,66 @@
+---
+doc_revision: 9
+reader_reintern: "Reader-only: re-intern if doc_revision changed since you last read this doc."
+doc_id: agents
+doc_role: agent
+doc_scope:
+  - repo
+  - agents
+  - tooling
+doc_authority: normative
+doc_requires:
+  - README.md
+  - CONTRIBUTING.md
+  - POLICY_SEED.md
+  - glossary.md
+doc_change_protocol: "POLICY_SEED.md §6"
+doc_invariants:
+  - read_policy_glossary_first
+  - refuse_on_conflict
+  - tier2_reification
+  - tier3_documentation
+  - lsp_first_invariant
+doc_erasure:
+  - formatting
+  - typos
+doc_owner: maintainer
+---
+
+# AGENTS.md
+
+This repository is governed by `POLICY_SEED.md`. Treat it as authoritative.
+Semantic correctness is governed by `glossary.md` (co-equal contract).
+
+## Cross-references (normative pointers)
+- `README.md` defines project scope, status, and entry points.
+- `CONTRIBUTING.md` defines human+machine workflow guardrails.
+- `POLICY_SEED.md` defines execution and CI safety constraints.
+- `glossary.md` defines semantic meanings, axes, and commutation obligations.
+
+## Required behavior
+- Read `POLICY_SEED.md` and `glossary.md` before proposing or applying changes.
+- If a request conflicts with `POLICY_SEED.md`, stop and ask for guidance.
+- Do not weaken or bypass self-hosted runner protections.
+- Keep workflow actions pinned to full commit SHAs and allow-listed.
+- When changing workflows, run the policy checks (once the scripts exist) and
+  surface any violations explicitly.
+- Preserve the LSP-first invariant: the server is the semantic core and the
+  CLI remains a thin LSP client.
+- Use `mise exec -- python` for repo-local tooling to ensure the pinned
+  interpreter and dependencies are used.
+- Treat docflow as repo-local convenience only; do not project it as a
+  general Gabion feature without explicit policy change.
+
+## Dataflow grammar invariant
+- Recurring parameter bundles are type-level obligations.
+- Any bundle that crosses function boundaries must be promoted to a Protocol
+  (dataclass config/local bundle) or explicitly documented with a
+  `# dataflow-bundle:` marker.
+- Tier-2 bundles must be reified before merge (see `glossary.md`).
+- Tier-3 bundles must be documented or reified (see `glossary.md`).
+
+## Doc hygiene
+- Markdown docs include a YAML front-matter block with `doc_revision`.
+- Bump `doc_revision` for conceptual changes.
+
+If unsure, prefer refusal over unsafe compliance.