repo-standards
repo-standards measures pull-request review size without executing repository code. Its
repository rules are available for review but remain disabled until individually approved
and explicitly activated by a consumer.
Where rules belong
- Exact tracked-tree facts—filenames, placement, topology, migrations, pull-request size, ownership, delivery/GitHub state, and repository-wide API/document sets—belong here.
- Source and configuration semantics for Python, TypeScript, SQL, Terraform/HCL, Markdown,
YAML, JSON, and shell belong in
sarj-ai/code-standards. - If a path alone is sufficient to produce the finding, use Repo Standards. If source content is necessary, use Code Standards.
After a rule is approved, activate its stable ID in .repo-standards/repository.toml:
enabled_rules = ["repository/artifacts/bespoke-iac-verifiers"]
The locked Repo Standards release supplies the current reviewed implementation. Manifests never
select historical rule versions; --enable-rule <rule-id>@<version> remains available only for
legacy manifests and calibration runs.
Run it
Use the current release without installing it:
uvx --from repo-standards repo-standards pull-request size . --base origin/main
For a persistent user installation:
uv tool install repo-standards
repo-standards pull-request size . --base origin/main
Upgrade with uv tool upgrade repo-standards. Automation should pin the package version or
the GitHub Action's full commit SHA.
Pull-request commit policy
pull-request commits is strict by default and defaults to five non-merge pull-request commits.
A pull request above that limit passes only when every commit subject begins with the complete,
exact ASCII series (1/N) through (N/N) , unless a trusted transition exemption is verified.
Indices must be unique, totals must match the actual commit count, and zero-padded or partial
markers do not pass.
Authoritative CI must fetch complete history and pass the provider's exact pull-request base and
head SHAs. Exit status 1 means the history violates policy; 2 means required evidence was
incomplete. For example:
repo-standards pull-request commits . \
--base "$PR_BASE_SHA" \
--head "$PR_HEAD_SHA"
Local hooks should use --advisory: findings and incomplete local history remain visible but do
not block a commit. The CI result remains authoritative.
repo-standards pull-request commits . \
--base "$(git merge-base origin/dev HEAD)" \
--head HEAD \
--advisory
When a series is not intentional, prefer one reviewable commit:
git rebase -i "$(git merge-base origin/dev HEAD)"
Trusted promotion/synchronization workflows may provide narrowly scoped transition exemptions. An exemption matches an exact repository, destination ref, automation branch prefix, source ref, and immutable source-SHA suffix. The PR head must equal that captured source snapshot, which must still belong to the configured source history. Any manual or conflict-resolution commit removes the exemption. Use remote-tracking source refs in CI, never configure exemptions in local hooks, and protect the automation branch namespace; never exempt by title, label, or a broad author match. Merge commits are excluded while their unique non-merge ancestors are counted, preventing routine synchronization merges from creating developer-facing noise.
Each repeated --transition-exemption value is a trusted JSON object. The caller must also pass
the exact PR head repository as --repository-id, plus --base-ref and --head-ref, from the
pull-request provider. Using the base repository identity here would incorrectly exempt forks:
--transition-exemption '{"id":"dev-preview","repository_id":"owner/repo","source_ref":"origin/dev","base_ref":"preview","head_prefix":"automation/promote-dev-","sha_prefix_length":12}'
GitHub Action
The Action measures size only. It enables no repository lint rules and needs no inputs on a
pull_request event.
name: Pull-request size
on:
pull_request:
permissions:
contents: read
jobs:
size:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
fetch-depth: 0
persist-credentials: false
- uses: sarj-ai/repo-standards@b6d3f7e2bc2a236ac62ca81eb76b5ccc504cf378 # v5.9.0
The Action emits counted, excluded, and total line counts plus canonical JSON. Tests are recognized across Python, JavaScript/TypeScript, Go, JVM, Android, Xcode/Swift, .NET, Ruby, and Bats conventions. Mark generated or machine-owned artifacts in the trusted base revision:
path/to/generated/** pr-size-excluded
Thresholds, labels, comments, and approval requirements remain consumer policy. Use
pull_request, never pull_request_target; this metric is not a security gate.
Safety model
- Repository contents come from one exact Git tree.
- Workflow YAML and API descriptions are parsed as inert data.
- Missing required evidence produces an inconclusive result rather than a false pass.
- Advisory commit-history analysis reports incomplete evidence without blocking local commits.
- The linter has no autofix or repository mutation mode.
Development
uv sync --locked
uv run pytest
uv run ruff check .
uv run basedpyright
uvx --no-config --isolated --python 3.14 \
--from sarj-standards-bootstrap==2.0.0 \
code-standards check --trust-repository-code
Build the same wheel and source distribution used by publishing:
uv build --no-sources
Releases are reconcilable. The protected workflow independently repairs a missing PyPI publication or GitHub Release from the same verified source revision.
1 maintainer
Release files for repo-standards 5.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| repo_standards-5.9.0.tar.gz | 102.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| repo_standards-5.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 220.7 kB
Release files / repo_standards-5.9.0.tar.gz
| Download URL | repo_standards-5.9.0.tar.gz |
|---|---|
| Size | 102.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
66c3d6d0821457e053197f0522d6f53db78ede59d9ca1cc4c5d78d2a3e3190f0
|
|
BLAKE2b-256 checksum How to use checksums |
ecfeaf70c59aa5e7d56e95c3cb9ee179f7cc075c777ac2ac9c10a70e03184518
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 4, 2026.
Transparency logRelease files / repo_standards-5.9.0-py3-none-any.whl
| Download URL | repo_standards-5.9.0-py3-none-any.whl |
|---|---|
| Size | 118.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8ad3f8c56e06bf9d2d2501830665a9fc8b14d8c83272675eec6b0b48e05fdf68
|
|
BLAKE2b-256 checksum How to use checksums |
a5ddfce0cbd93fcdfcccb74e47258ff633321b36ad5665966d2c20e854d15cc1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 4, 2026.
Transparency log
