pr-policy 0.1.0__tar.gz

pr_policy-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: A check reports the wrong result, or the tool misbehaves
+title: ''
+labels: bug
+---
+
+**What happened**
+
+<!-- Which check was wrong, and what did it say? -->
+
+**What you expected**
+
+**How to reproduce**
+
+<!-- The smallest directory layout that shows the problem is ideal:
+
+     my-repo/
+       LICENSE
+       docs/CONTRIBUTING.md
+-->
+
+**Output**
+
+```
+$ repo-ready . --format json
+paste the output here
+```
+
+**Environment**
+
+- repo-ready version (`repo-ready --version`):
+- Python version (`python --version`):
+- OS:

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

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/rodny90/pr-policy/security/advisories/new
+    about: Please report security issues privately, not in a public issue.

pr_policy-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: New check or feature
+about: Suggest a check to add, or another way to use the output
+title: ''
+labels: enhancement
+---
+
+**What should it check, or what should it do**
+
+**Why it matters to a maintainer**
+
+<!-- A check earns its place if a project failing it is meaningfully worse off.
+     What goes wrong for a repo that doesn't have this? -->
+
+**What should count as passing**
+
+<!-- Which filenames, locations or contents? Remember that checks are filesystem-only:
+     repo-ready makes no network calls and has no dependencies. -->
+
+**Roughly what should it be worth**
+
+<!-- Weights total 100, so a new check means taking points from somewhere. -->

pr_policy-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What this changes
+
+<!-- Describe the change and why it is needed. Replace this comment. -->
+
+## Generative AI
+
+This project asks you to say whether AI tools were involved. Either answer is
+fine — we route on the disclosure, we do not judge it.
+
+- [ ] I did not use generative AI tools for this change
+- [ ] I used generative AI tools, and I have reviewed and understood the result
+
+If you used a coding agent, record it in the commit with
+`Assisted-by: <tool>:<model>`. Sign-off, where used, stays human.
+
+## Checks
+
+- [ ] `pytest` passes
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] New behaviour has a test

pr_policy-0.1.0/.github/pr-policy.yml

@@ -0,0 +1,40 @@
+# pr-policy configuration, generated by `pr-policy init` on 2026-09-12.
+#
+# Rules switched on by inference quote the line that justified them, so you can
+# check the reasoning rather than take it on trust. Everything here is a
+# starting point — edit it freely.
+#
+# Severities are `error`, `warn` or `info`. Nothing fails a build while
+# `enforce` is false: pr-policy reports signals and leaves the decision to you.
+
+version: 1
+enforce: false
+
+rules:
+
+  attribution:
+    enabled: true
+    severity: "warn"
+    forbid_agent_sign_off: true
+    prefer_assisted_by: true
+    require_signed_off: false
+
+  disclosure:
+    # CONTRIBUTING.md:38 — "You may use AI tools here."
+    enabled: true
+    severity: "warn"
+
+  template:
+    enabled: true
+    severity: "warn"
+    min_body_chars: 30
+
+  linked_issue:
+    enabled: false
+    severity: "warn"
+
+  size:
+    enabled: true
+    severity: "info"
+    max_lines: 1000
+    max_files: 100

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

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        include:
+          # One run per other platform catches path and encoding bugs.
+          - os: windows-latest
+            python-version: "3.12"
+          - os: macos-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: |
+          ruff check .
+          ruff format --check .
+
+  self-audit:
+    name: self-audit (repo-ready grades itself)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: python -m pip install -e .
+      - name: Audit this repository
+        run: repo-ready . --min-score 100
+
+  self-policy:
+    name: self-policy (pr-policy checks its own pull requests)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # pr-policy reads commit trailers, so it needs the branch history.
+          fetch-depth: 0
+      - name: Check this pull request against our own policy
+        uses: ./
+        with:
+          comment: "true"

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

@@ -0,0 +1,105 @@
+name: Release
+
+on:
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: python -m pip install --quiet build ".[dev]"
+
+      - name: The tag must match the packaged version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python -c "import importlib.metadata as m; print(m.version('pr-policy'))")
+          if [ "$tag" != "$version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match package version $version" >&2
+            exit 1
+          fi
+          echo "Releasing $version"
+
+      - name: Test before shipping
+        run: |
+          pytest -q
+          ruff check .
+          repo-ready . --min-score 100
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pr-policy
+    permissions:
+      id-token: write # trusted publishing; no API token is stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Publish the GitHub release
+    needs: publish
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes "See [CHANGELOG.md](CHANGELOG.md) for what changed."
+
+  major-tag:
+    name: Move the major version tag
+    needs: publish
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Point v<major> at this release
+        run: |
+          set -euo pipefail
+          # `uses: rodny90/pr-policy@v1` should follow the newest 1.x release,
+          # which is the convention every published action uses.
+          major="${GITHUB_REF_NAME%%.*}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -f "$major"
+          git push -f origin "$major"

pr_policy-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+.env
+.DS_Store
+
+# Written into the workspace by the pr-policy action
+policy-comment.md
+policy-findings.json

pr_policy-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-12
+
+First release. Two commands: `pr-policy`, which checks pull requests against the
+policy a project wrote down, and `repo-ready`, which checks that the policy was
+written down at all.
+
+### Added — pr-policy
+
+- **`attribution`** — enforces the [Linux kernel's AI attribution
+  policy](https://docs.kernel.org/process/coding-assistants.html) on commit trailers:
+  a coding agent must never add `Signed-off-by:` (only a human can certify the DCO),
+  tool assistance belongs in `Assisted-by:` rather than `Co-authored-by:`, and
+  optionally every commit must be signed off. Matching is on identities an agent
+  writes about itself, never on the code.
+- **`disclosure`** — checks that the project's AI-disclosure checkbox was answered.
+  Either answer passes; the rule fires only when the question was ignored.
+- **`template`** — checks the description is not empty and that the template's
+  `<!-- ... -->` prompts were replaced.
+- **`linked_issue`** — checks the body references an issue with a closing keyword.
+- **`size`** — reports diffs over the project's line and file guidelines.
+- **`pr-policy init`** — generates a starter config by reading `CONTRIBUTING.md`,
+  the pull request template and `AGENTS.md`, quoting the line behind every
+  inference so the maintainer can check the reasoning. Inference works over
+  sentences, skips prohibitions ("agents must never sign off" is not a sign-off
+  policy), and requires requirement-shaped language before enabling a rule.
+- Reporting-only by default: nothing fails a build until `enforce: true` or `--strict`.
+- Three output formats: `text` (coloured on a terminal, honouring `NO_COLOR`),
+  `json`, and `markdown` for posting as a pull request comment.
+- A composite GitHub Action that posts a single sticky comment and updates it on
+  each push. It resolves the base branch with an explicit refspec, so it works on
+  the default shallow checkout rather than only with `fetch-depth: 0`.
+- Rules that read the pull request body are skipped, not failed, when no title or
+  body is available — an absent body is not an empty one.
+- Strict configuration validation: unknown rules and unknown options are errors,
+  so a typo never quietly disables a rule.
+
+### Added — release tooling
+
+- A tag-driven release workflow publishing to PyPI through
+  [trusted publishing](https://docs.pypi.org/trusted-publishers/), so no API token
+  is stored in the repository. It refuses to publish when the tag and the packaged
+  version disagree, and runs the full suite before building.
+- The `v<major>` tag moves to each new release, so `uses: rodny90/pr-policy@v0`
+  follows the newest 0.x.
+- The action's shell logic is covered by tests that lift the `run:` block out of
+  `action.yml` and execute it, rather than leaving CI to run it first.
+
+### Added — repo-ready
+
+- Twelve weighted repository readiness checks, an A–F grade, and a concrete
+  suggested fix for every failure, ordered by weight.
+- `--min-score N` to gate CI, plus `json` and `markdown` output.
+- Case-insensitive file lookup that also searches `.github/` and `docs/`, and skips
+  vendored directories so a dependency's tests cannot make a repository look tested.
+
+[Unreleased]: https://github.com/rodny90/pr-policy/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rodny90/pr-policy/releases/tag/v0.1.0

pr_policy-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing these standards and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers by opening a report through [GitHub's private reporting](https://github.com/rodny90/pr-policy/security/advisories/new) or contacting a maintainer directly. All complaints will be reviewed and investigated promptly and fairly, and the privacy and security of the reporter will be respected.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

pr_policy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to pr-policy
+
+Thanks for taking the time. Bug reports, new checks and documentation fixes are all welcome.
+
+## Getting set up
+
+```bash
+git clone https://github.com/rodny90/pr-policy
+cd pr-policy
+python -m pip install -e ".[dev]"
+```
+
+## Running the checks locally
+
+```bash
+pytest                          # the test suite
+ruff check .                    # lint
+ruff format --check .
+repo-ready . --min-score 100    # repo-ready audits this repository
+pr-policy check --base origin/main   # pr-policy checks your own branch
+```
+
+CI runs exactly these four commands, so a clean local run means a green pull request.
+
+## Adding a rule to pr-policy
+
+Rules live in `src/pr_policy/rules.py`. Each is a function taking a `PullRequest`
+and a `RuleConfig` and yielding `Finding` objects.
+
+1. Write the function, then register it in `RULES` and add its defaults to
+   `DEFAULTS` in `src/pr_policy/config.py`.
+2. If the rule reads the pull request title or body, add it to `NEEDS_METADATA`
+   so it is skipped rather than failed when no body is available.
+3. **Keep it deterministic.** A rule may check whether a trailer exists, whether a
+   box is ticked, whether a reference resolves. A rule may never try to infer
+   whether a human or a model wrote something. That boundary is the project.
+4. Default new rules to `warn`, and default anything project-specific to
+   `enabled: false` until `pr-policy init` can infer it from documentation.
+5. Add tests for the passing and the failing case, and a row to the rules table
+   in `README.md`.
+
+## Adding a check to repo-ready
+
+Checks live in `src/repo_ready/checks.py`. Each one is a function taking a `Repo` and returning `(passed, detail)`, registered as a `Check` in the `CHECKS` tuple.
+
+1. Write the function. Keep it filesystem-only — `repo-ready` makes no network calls and has no dependencies, and both of those are deliberate.
+2. Add a `Check(...)` entry with an `id`, a `title`, a `weight` and a `fix`. The `fix` is what the user reads when the check fails, so make it a concrete instruction rather than a restatement of the problem.
+3. **Weights must still total 100.** Adjust the existing weights in the same pull request and say why in the description; `test_weights_sum_to_one_hundred` will fail otherwise.
+4. Add tests for both the passing and the failing case.
+5. Add a row to the check table in `README.md`, and a line to `CHANGELOG.md`.
+
+A check should earn its weight. Ask whether a maintainer who fails it is meaningfully worse off — if not, it is probably a lint rule rather than a readiness check.
+
+## AI-assisted contributions
+
+You may use AI tools here. We ask two things, both of which this project's own
+tooling checks:
+
+1. **Disclose it.** The pull request template has a checkbox. Tick whichever
+   option is true — either answer is accepted, the box only needs an answer.
+2. **Attribute it correctly.** Record tool assistance with an `Assisted-by:`
+   trailer, following the [Linux kernel's
+   convention](https://docs.kernel.org/process/coding-assistants.html):
+
+   ```
+   Assisted-by: Claude:claude-opus-5
+   ```
+
+   An agent must never add a `Signed-off-by:` trailer. Only a human can certify
+   the Developer Certificate of Origin, and only a human can take
+   responsibility for a change.
+
+Whoever opens the pull request is responsible for the code in it, however it
+was written.
+
+## Pull requests
+
+- One logical change per pull request.
+- Keep the public output formats stable: the JSON shape is something people script against, so a change to it needs a note in `CHANGELOG.md` under a new version.
+- Describe the behaviour change, not the diff.
+
+## Reporting bugs
+
+Open an issue using the bug report template. A repository that reproduces the wrong result is worth more than a description of it — even a three-file example is enough.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

pr_policy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rodny90
+
+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.