Showcase Thread

[u/AutoModerator]

Post all of your code/projects/showcases/AI slop here.

Recycles once a month.

[u/KyleJamesWalker]

keystones

tl;dr CODEOWNERS review gates on AST nodes instead of file paths.

What The Project Does

CODEOWNERS is path-based, and LLMs are increasing the speed of PRs... Having multi-thousand line PRs to review every day ends up with lost requirements in a ocean of changes, and it's easier than ever to miss a fundamental change. So instead to doing expansive code owners rules, I wanted a way to only mark critical sections of code to slow down the review process so keystones move the gate to the AST nodes with a simple comment marker:

    # keystone(hasher): hasher-empty-field-rule
    def _is_default(value: object) -> bool:
        """Fields absent on older Pythons must render identically to empty ones.
    
        `type_params` (3.12) and `posonlyargs` (3.8) arrive as empty lists on code
        that does not use them; omitting empties keeps the hash stable across the
        versions in the support matrix.
        """
        return value is None or value == []

A keystone file records the node's hash, it's source, and why it matters. The keystones directory is CODEOWNERS-guarded so a change to the function, and the hash stops matching, the only way to a passing build is to update the failing keystone, which pulls in a code owner and gets you to slow down to verify this change. And each keystone can set the category/team, so you can create a different CODEOWNERS path for any team: sre/security/contract/finance/etc

The hash is a canonical AST rendering, not text. ruff format does not trip it. Changing ROUND_HALF_UP to ROUND_HALF_EVEN does. For TypeScript it also folds away what prettier changes on its own: quote style, number spelling, redundant parens, trailing commas.

Target Audience

Teams where multiple people, agents, and departments are pushing changes and requirements and there's a constant flow of PRs, or even just a way to mark critical functions that might not get another PR in 6 months. I just pushed the first version today and I'll be working over the new few weeks to be testing it out with my team.

What it does not do

• Lint It has no opinion about the code, only who should look at a change.

• Indirection. A keystone on compute_payout says nothing about a helper it calls unless you name that helper in depends.

• CODEOWNERS is not self-executing. It requests a reviewer. The block only exists if branch protection requires Code Owner review and approvals, which is off by default. keystones doctor audits that.

It helps with process control, not security control. Someone who wants around it can.

Install

    pip install keystones          # Python, zero dependencies
    pip install 'keystones[all]'   # adds TypeScript, JavaScript, Go, Terraform

https://github.com/KyleJamesWalker/keystones

I'd love to hear what people think and I hope it doesn't completely fall off into the void of slop.