Ownerloom

Keep CODEOWNERS readable as your repository grows. Ownerloom groups literal paths by directory, removes redundant rules, and preserves the order that decides who owns each path. One Python package replaces copied formatting scripts across projects.

Table of contents

• Quick start
• Why Ownerloom
• Examples
• Architecture
• Inputs and results
• Integrations and development
• License and provenance

Quick start

With Python 3.12+ and Git available, run inside your existing repository:

python -m pip install ownerloom
ownerloom --check
ownerloom --write
git diff -- .github/CODEOWNERS

Review and stage the result yourself. Ownerloom never commits, pushes or changes repository permissions. Python 3.14.1 is excluded by the NetworkX dependency.

Why Ownerloom

• Readable policy: keep related directories together without moving an override ahead of the rule it overrides.
• Conservative changes: preserve comments, GitLab sections, wildcard rules and unfamiliar syntax as boundaries. Retained syntax still needs provider validation.
• Reviewable automation: check the exact committed file and tree before push, rather than allowing an unstaged fix to mask stale committed policy.
• Reusable integration: the same typed library powers the CLI, pre-commit and CI. Normal compilation is offline and does not execute repository hooks or source.

Examples

These examples use tracked paths and placeholder team handles. Expand each case to see the policy before and after compilation.

/pkg/api/routes.py @acme/api
/docs/usage.md @acme/docs
/pkg/ @acme/platform
/pkg/core.py @acme/platform
/pkg/api/ @acme/api
/docs/ @acme/docs
/pkg/api/models.py @acme/api

/docs/ @acme/docs
/pkg/ @acme/platform
/pkg/api/ @acme/api

/pkg/billing/tax.py @acme/payments
/pkg/catalog/search.py @acme/catalog
/pkg/billing/invoice.py @acme/payments
/pkg/billing/refunds.py @acme/payments

/pkg/billing/ @acme/payments
/pkg/catalog/search.py @acme/catalog

Architecture

flowchart LR
    A[CODEOWNERS text] --> C[Literal runs and opaque boundaries]
    B[Tracked Git inventory] --> C
    C --> D[Remove shadowed and inherited rules]
    D --> E[Precedence DAG]
    E --> F[Deterministic tree order]
    F --> G[Compilation result]
    G --> H[Check or atomic write]
    classDef input fill:#829B85,stroke:#647D8B,color:#243746
    classDef pass fill:#C4AC70,stroke:#647D8B,color:#243746
    class A,B input
    class C,D,E,F,G,H pass

The pure compiler accepts explicit text and paths. The CLI owns Git reads and atomic writes. NetworkX orders the precedence graph; it does not interpret provider policy. See the compiler contract for supported syntax, consolidation and failure behavior.

Inputs and results

Exit status is 0 for normalized or written content, 1 for formatting drift, and 2 for invalid inputs or operational errors. Runtime use requires no credentials. Release jobs use the repository secrets PYPI_API_TOKEN, COSIGN_PRIVATE_KEY and COSIGN_PASSWORD, plus the trusted COSIGN_PUBLIC_KEY_SHA256 variable. GitHub supplies the repository, source SHA, tag and job token. See release setup for these administrator-managed inputs.

from ownerloom import compile_owners

result = compile_owners("/z @team\n/a @team\n", frozenset({"a", "z"}))
assert result.text == "/a @team\n/z @team\n"

Integrations and development

Use the pre-commit and migration guide to replace local copies. Keep a provider-aware syntax/path linter alongside Ownerloom; formatting does not establish account eligibility or enforce required reviews.

See contributing, security reporting, development, release verification, CI permissions, and the portable SKILL.md (browse online). The implementation follows RFC #94.

License and provenance

The runtime compiler is Apache-2.0, copyright Astrivant LLC. The extraction manifest binds its source to Polyad's merged compiler and records the owner's licensing choice. Development helpers retain their separate notices; they are excluded from the wheel.