The repository or configuration that created this release differ from a previous release. View details.
doc_revision: 58 reader_reintern: "Reader-only: re-intern if doc_revision changed since you last read this doc." doc_id: readme doc_role: readme doc_scope:
- repo
- overview
- tooling doc_authority: informative doc_requires:
- POLICY_SEED.md
- glossary.md
- AGENTS.md
- CONTRIBUTING.md doc_reviewed_as_of: POLICY_SEED.md: 28 glossary.md: 13 AGENTS.md: 12 CONTRIBUTING.md: 69 doc_change_protocol: "POLICY_SEED.md §6" doc_erasure:
- formatting
- typos doc_owner: maintainer
Gabion
Gabion is an architectural linter that stabilizes loose parameters into structural bundles. It discovers recurring argument groups in a Python codebase and guides their reification into dataclass-based Protocols.
This repo contains scaffolded infrastructure plus a prototype dataflow audit. Synthesis and refactoring exist as evolving prototypes and are intentionally conservative.
Why Gabion
- Find implicit structure: detect “dataflow grammar” bundles that repeatedly travel together across function boundaries.
- Refactor safely: promote bundles into explicit dataclass Protocols.
- Govern meaning: enforce semantics via a normative glossary.
Status
- CLI uses the LSP server as its semantic core.
- Dataflow grammar audit is implemented (prototype).
- Type-flow, constant-flow, and unused-argument smells are implemented (prototype).
- Refactor engine can rewrite signatures/call sites for targeted functions (prototype).
- Governance layer is active.
Versioning (pre-1.0)
Gabion is pre-1.0. Until a 1.0 release, minor version bumps (0.x) may include breaking changes; patch releases target fixes. Breaking changes will be called out in release notes.
Branching model
stageis the integration branch for routine pushes; CI runs onstagepushes.mainis protected and receives changes via PRs fromstage.- Merges to
mainare regular merge commits (no squash or rebase). stageaccumulates changes and may include merge commits frommainas it stays in sync.nextmirrorsmain(no unique commits) and is updated aftermainmerges.releasemirrorsnext(no unique commits) and is updated only aftertest-v*succeeds.- Tags are cut via the
release-tagworkflow onnext(test) andrelease(prod). nextandreleaseare automation-only branches;mirror-nextandpromote-releasekeep them in sync.
Convergence checklist
Bottom-up convergence targets live in docs/sppf_checklist.md.
Governance addenda (optional)
See docs/doer_judge_witness.md for optional role framing.
Non-goals (for now)
- Docflow is a repo-local convenience feature, not a Gabion product feature.
- Public-API compatibility shims for refactors are not yet implemented.
- Multi-language support is out of scope (Python-first).
Quick start
Install toolchain with mise (once):
mise install
Install from source (editable):
mise exec -- python -m pip install -e .
Dependencies are locked in requirements.lock (generated via uv).
CI installs from the lockfile inside an explicit venv to prevent drift.
Install git hooks (optional):
scripts/install_hooks.sh
Commands below assume the package is installed (editable) or PYTHONPATH=src.
Run the dataflow grammar audit (strict defaults):
mise exec -- python -m gabion check
gabion check enforces violations even without --report output.
Use --baseline path/to/baseline.txt to ratchet existing violations and
--baseline-write to generate/update the baseline file.
Run the dataflow grammar audit (prototype):
mise exec -- python -m gabion dataflow-audit path/to/project
Repo defaults are driven by gabion.toml (see [dataflow]).
By default, in/ (inspiration) is excluded from enforcement there.
Use --synthesis-plan to emit a JSON plan and --synthesis-report to append a
summary section to the Markdown report. Use --synthesis-protocols to emit
dataclass stubs (prototype) for review, or add
--synthesis-protocols-kind protocol for typing.Protocol stubs.
Use --refactor-plan to append a per-bundle refactoring schedule and
--refactor-plan-json to emit the JSON plan.
Generate protocol refactor edits (prototype):
mise exec -- python -m gabion refactor-protocol \
--protocol-name BundleProtocol \
--bundle a --bundle b \
--target-path path/to/module.py \
--target-function foo
Run audit + synthesis in one step (timestamped output under artifacts/synthesis):
mise exec -- python -m gabion synth path/to/project
Run the docflow audit (governance docs only):
mise exec -- python -m gabion docflow-audit
Note: docflow is a repo-local convenience feature. It is not a core Gabion capability and is not intended to generalize beyond this repository.
Generate a synthesis plan from a JSON payload (prototype scaffolding):
mise exec -- python -m gabion synthesis-plan --input path/to/payload.json --output plan.json
Example payload:
{
"bundles": [
{ "bundle": ["ctx", "config"], "tier": 2 }
],
"field_types": {
"ctx": "Context",
"config": "Config"
}
}
Payload schema: docs/synthesis_payload.md.
Capture an audit snapshot (reports + DOT graph under artifacts/):
scripts/audit_snapshot.sh
Snapshots now include a synthesis plan JSON and protocol stub file. Show the latest snapshot paths:
scripts/latest_snapshot.sh
Editor integration
The VS Code extension stub lives in extensions/vscode and launches the
Gabion LSP server over stdio. It is a thin wrapper only.
Quick commands (make)
make bootstrap
make check
make check-ci
make test
make test-logs
make clean-artifacts
make docflow
make dataflow
make lsp-smoke
make audit-snapshot
make audit-latest
CI
GitHub-hosted CI runs gabion check, docflow audit, and pytest using mise
as defined in .github/workflows/ci.yml.
If POLICY_GITHUB_TOKEN is set, the posture check also runs on pushes.
Allow-listed actions are defined in docs/allowed_actions.txt.
Pull requests also get a dataflow-grammar report artifact (and a comment on
same-repo PRs) via .github/workflows/pr-dataflow-grammar.yml.
GitHub Action (redistributable)
A composite action wrapper lives at .github/actions/gabion.
It installs Gabion via pip and runs gabion check (or another subcommand).
See .github/actions/gabion/README.md for usage and pinning guidance.
Example workflow (with pinned SHA placeholders):
docs/workflows/gabion_action_example.yml.
Pinning guide: docs/pinning_actions.md.
Architecture (planned shape)
- LSP-first: the language server is the semantic core; the CLI is a thin LSP client. Editor integrations remain thin wrappers over the same server. The server is the single source of truth for diagnostics and code actions.
- Analysis: import resolution, alias-aware identity tracking, fixed-point bundle propagation, and tiering. Type-flow, constant-flow, and unused-argument audits are part of the prototype coverage.
- Reports: Mermaid/DOT graph outputs and a violations list from the audit.
- Synthesis: Protocol generation, bundle-merge heuristics, and refactoring assistance (callee-first/topological schedule).
See in/ for design notes and the prototype audit script.
Governance
This repository is governed by two co-equal contracts:
POLICY_SEED.md(execution and CI safety)glossary.md(semantic meanings and commutation obligations)
LLM/agent behavior is governed by AGENTS.md.
Cross-references
CONTRIBUTING.mddefines workflow guardrails and dataflow grammar rules.AGENTS.mddefines LLM/agent obligations.POLICY_SEED.mddefines execution and CI safety constraints.glossary.mddefines semantic meanings, axes, and commutation obligations.
License
Apache-2.0. See LICENSE.
Metadata
Release files for gabion 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Change of provenance
The repository or configuration that created these release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gabion-0.1.5.tar.gz | 203.4 kB | With provenance | Details for gabion-0.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gabion-0.1.5-py3-none-any.whl | Python 3 | none | any | Details for gabion-0.1.5-py3-none-any.whl |
Total release size: 262.8 kB
Release files / gabion-0.1.5.tar.gz
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | gabion-0.1.5.tar.gz |
|---|---|
| Size | 203.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b9512fc2701294be12cd4506c1e61cc8a6079b11a8abec9fd8d317b111b9f62f
|
|
BLAKE2b-256 checksum How to use checksums |
0e8c78dec3c39c44c34329159f3de76f3fc86a7e2b55d8a0c81566c4a9402a22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.11
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 3, 2026.
Transparency logRelease files / gabion-0.1.5-py3-none-any.whl
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | gabion-0.1.5-py3-none-any.whl |
|---|---|
| Size | 59.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
728584f3cd559f56cbe472366eb45ca361ec49d49c707d65fe72abaedf68f298
|
|
BLAKE2b-256 checksum How to use checksums |
1fb6b16a31cc6dafd515f051c2007b9dc1d683bf1365363a88900fdc5213b7d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.11
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 3, 2026.
Transparency logSecurity for gabion 0.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Change of provenance
The configuration that created this release differs from a previous release.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Attestation for gabion-0.1.5.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.