3.17 · Guides
Rules: architecture you can check¶
Rules are optional, typed promises about your application that a tool checks and that fail with a stable ID, a location and an explanation. They are not a linter for style and not an AI prompt: each rule is a Python object with deterministic behaviour. Nothing runs unless you enable rules.
The built-in set is intentionally small: access declarations, atomic writes, response types, model responses, pagination, permissions, request text limits, table names, foreign-key indexes, schema exposure and import direction. Add a custom Rule only when a project has a concrete invariant that these checks cannot express.
Enable them (the blog and the tracker enable all of them)¶
# examples/blog/rules.py
blog_rules = RuleSet(
Actions.require_access(match="blog.*", except_=PUBLIC), # HNK-ACC-001
Actions.require_permissions(match="blog.*", except_=PUBLIC), # HNK-ACC-002
Actions.forbid_model_responses(match="blog.*"), # HNK-API-001
Actions.require_return_type(match="blog.*"), # HNK-API-002
Actions.require_pagination(match="blog.*"), # HNK-API-003
Transactions.require_atomic(except_=["blog.accounts.*.login"]), # HNK-TXN-001
Schemas.forbid_exposure("token", "password_hash"), # HNK-SCH-001
Schemas.require_string_limits(), # HNK-SCH-002
Models.require_explicit_table(match="blog.*"), # HNK-DB-001
Models.require_foreign_key_index(match="blog.*"), # HNK-DB-002
Imports.forbid(source="blog.models", target="blog.api"), # HNK-IMP-001
)
# examples/blog/main.py
app = Hinoki(..., rules=blog_rules) # startup rules fail the app if a promise is broken
| ID | Rule | Phase | Checks |
|---|---|---|---|
HNK-ACC-001 |
Actions.require_access(match, except_) |
startup | every matching action names an Access policy (public by default is the common hole) |
HNK-ACC-002 |
Actions.require_permissions(match, except_) |
startup | an action that names an Access policy names at least one permission, so "any authenticated caller" is never implicit |
HNK-TXN-001 |
Transactions.require_atomic(methods, match, except_) |
startup | state-changing actions use atomic=True (the admin's own routes are not checked: they open their own short transactions, so that no connection waits while a password is hashed) |
HNK-API-001 |
Actions.forbid_model_responses(match, except_) |
startup | no action returns a Model (or a list/page of them): responses are Schema classes |
HNK-API-002 |
Actions.require_return_type(match, except_) |
startup | every matching action annotates a concrete return type (not missing, Any or object; None is fine for a 204) |
HNK-API-003 |
Actions.require_pagination(match, except_) |
startup | a GET action never returns a plain list[...] (alone or in a union): it returns a Page |
HNK-SCH-001 |
Schemas.forbid_exposure(*fields) |
startup | named fields never appear in a response Schema, nested, in a subclass or in a variant of a discriminated union, as a field, an alias or a computed field; dict keys are runtime data and are not checked |
HNK-SCH-002 |
Schemas.require_string_limits() |
startup | every text field of a request Schema (nested ones and union variants included), and every text element of a list, set or tuple, or value of a dict[str, ...] field, and every text variant of a plain union, has max_length or one_of (an Enum or Literal field lists its values and passes); dict keys from clients are bounded by the validator |
HNK-DB-001 |
Models.require_explicit_table(match) |
startup | models whose module matches match pin their table with @db.table(...) or table=; a rename of the class then cannot change the physical table |
HNK-DB-002 |
Models.require_foreign_key_index(match) |
startup | every foreign-key column of a matching model leads an index, a primary key or a unique constraint |
HNK-IMP-001 |
Imports.forbid(source, target) |
static | modules under source never import target (read from the source files; dynamic imports are reported, not ignored) |
The model rules take match as an fnmatch pattern on the model's module (blog.*); a pattern that matches no model is reported as unverifiable.
match and except_ patterns on action rules use fnmatch on the action's full qualified name (pkg.api.Posts.create, named after the class it is mounted on). A bare name such as health matches nothing: write *.health.
Run them¶
The Blog target is part of the checked-in project in examples/. Run this from
that directory, using the locked environment in the parent directory:
cd examples
uv run --project .. hinoki check blog.main:create_app \
--rules blog.rules:blog_rules --package blog
# 11 rule(s): 0 violated, 0 unverifiable, 0 waived (exit 0)
A broken promise (a deliberately bad app from the tests):
tests/projects/rulesapp.py:7: HNK-ACC-001 [violated] GET /health (health) declares no access policy
tests/projects/rulesapp.py:12: HNK-ACC-001 [violated] POST /items (create) declares no access policy
tests/projects/rulesapp.py:12: HNK-TXN-001 [violated] POST /items (create) does not declare atomic=True
2 rule(s): 3 violated, 0 unverifiable, 0 waived (exit 1)
The other rules report the same way. This output comes from a small project whose api.py returns a Model, exposes token in a response Schema, and whose models.py imports api:
shop/api.py:13: HNK-API-001 [violated] GET /members/{member_id} (one) returns the model Member; return a Schema
fix: return a Schema (for example PostOut.from_model(row))
shop/api.py:7: HNK-SCH-001 [violated] MemberOut.token is exposed by GET /members
fix: remove the field from the response Schema, or return a Schema that does not carry it
shop/models.py:11: HNK-IMP-001 [violated] shop.models imports shop.api, which is forbidden for shop.models
fix: move the code to an allowed layer, or depend on it through the layer in between
3 rule(s): 3 violated, 0 unverifiable, 0 waived (exit 1)
--format json prints the same diagnostics as versioned data (schema_version, summary, and per diagnostic rule, severity, phase, status, message, location, explanation, subject, waiver) for CI, editors and agents. --phase static|startup selects a phase; exit codes are 0 clean, 1 violations, 2 the check could not run.
Statuses: violated (demonstrated), unverifiable (the check could not decide, for example a dynamic import, a rule that matched nothing, or a rule that crashed: this fails the build too, it is never a pass), waived.
Exceptions (waivers)¶
hinoki-rules.toml next to the project:
[[waiver]]
rule = "HNK-ACC-001"
target = "tests.projects.rulesapp.health" # fnmatch on the diagnostic's subject, bounded (not "*")
reason = "liveness probe is public by design"
owner = "platform-team"
expires = 2027-01-31 # optional
tests/projects/rulesapp.py:7: HNK-ACC-001 [waived] GET /health (health) declares no access policy
waived: liveness probe is public by design (platform-team, until 2027-01-31)
A waiver needs a reason, an owner and a bounded target; an expired one stops applying and says so; a waiver that matches nothing is reported. A diagnostic that means "the rule could not do its job" cannot be waived. Waivers are the owner's decision: the tools read the file and never write it (put it under CODEOWNERS); AGENTS.md in a generated project tells agents the same.
Your own rules¶
Subclass hinoki.rules.Rule with a stable id, a phase, an explanation and check(project) yielding Diagnostics (use self.diagnostic(message, location, subject=...)). A rule that needs side effects (runs code, files, network, a database) declares them in effects and only runs with check --allow-effects.
Seeing them from an agent¶
The development MCP (hinoki mcp) exposes project inspection and rule diagnostics as read-only tools. See development tools. Rules inspect declarations and source structure; they do not prove what every function body does.