Architecture
miucr is one pure-Go static binary (CGO_ENABLED=0). The engine owns the parts
where correctness matters: file selection, context assembly, line anchoring,
gating, and dedupe. The model only finds bugs and proposes fixes.
Click the diagram for the interactive version.
Layers
Section titled “Layers”| Layer | Package | Job |
|---|---|---|
| Entry points | cmd/miucr, internal/cli, internal/serve, internal/mcpserver | Parse input, call one seam. No review logic. |
| Wire | internal/cli/wire | Inject engine, GitHub, and store into cli; discover and trust-tag rules; pick the store backend. |
| PR path | cli.PRReviewer.ReviewPR | Fetch the PR, call the engine, publish, dedupe, track resolution. Shared by review --pr, the Action, webhook, poll, and REST. |
| Engine | internal/engine | engine.Review: deterministic pipeline around the model call. No filesystem access for rules. |
| Store | store.Store, store.PRThreadStore | History and PR-thread state. SQLite by default, Postgres opt-in. |
cli sits below engine, agent, and github in the import graph; wire is
blank-imported by cmd/miucr and injects them at startup. internal/serve
depends only on cli, config, stdlib, and go-github webhook helpers.
Review pipeline
Section titled “Review pipeline”diff -> SelectFiles -> AssembleContext -> rules -> model -> ResolveLineNumbers -> drop unanchored -> dedupe -> gate -> publish- The diff carries its revision, so every later stage reads the same content.
- Line numbers from the model are discarded. Each finding is re-anchored from its
quoted code (hunk new side, old side, then full file). A finding still
unanchored after recovery is dropped and counted in
findings_dropped. - Dedupe key:
file + line + categoryplus a short hash of rationale and patch. - Gate order is
info < low < medium < high < critical. An unknown gate fails loudly. - Publish posts inline comments as a review and upserts one summary issue comment
found by its
<!-- miu-cr-review -->marker.
Per-stage detail: How it works.
Rules seam
Section titled “Rules seam”- Wire discovers rules from three layers: built-in defaults and
~/.config/miu/cr/rulesare Trusted, repo.miu/cr/rulesis Untrusted. - Wire passes
[]rules.RuleplusIsForkinengine.Request. The engine selects in memory afterSelectFiles, because selection needs the changed paths. - Untrusted rules are fenced as context only, byte-capped, and dropped entirely on fork PRs. They cannot override a Trusted stem. The finding-JSON contract stays in the cached system prompt, so rule prose cannot redefine the schema.
- Rules get their own token cap, reported as
stats.rules_appliedandrules_truncated.
Store seam
Section titled “Store seam”- Consumers (engine, cli, publish, MCP) see only the two interfaces.
- The backend factory lives in wire (
storefactory), since a factory insidestorewould import cycle with its backends. - Resolution:
MIUCR_STORE_BACKEND>[store] backend>sqlite. DSN:MIUCR_PG_DSN>[store] dsn, always redacted. - Postgres uses pgx/v5 through
database/sql, pure Go. SQL mirrors SQLite 1:1; a schema-parity test and a shared conformance suite run both backends in CI. - With
backend = postgres, a connect or auth failure is a typedstore.unavailableerror (exit 1), never a silent fallback.
Operator reference: Store backends.
serve request guards
Section titled “serve request guards”In order, for POST /webhook:
MaxBytesReader5 MB cap, before HMAC.- Event type must be
pull_request(or a supported reply event) beforeParseWebHook, which panics on unknown types. - HMAC check.
WEBHOOK_SECRETis required at startup. owner/repomust be in--repos, which stops a forged hook from cloning arbitrary repos.- Respond
200, then dispatch to a bounded worker pool that coalesces jobs on{owner, repo, number}. A full queue is logged and counted.
All serve errors pass through config.RedactString, since clone URLs embed the token.
Cross-push dedupe
Section titled “Cross-push dedupe”- Fingerprint, no DB.
path | category | sha256(quoted code), line-free, so a re-anchored finding keeps the same 16-hex marker in its comment. This is the path the stateless Action uses. - PR-thread store, opt-in.
MIUCR_PR_STOREenables apr_findingstable (posted/resolved). It is nil on the Action path. - Skip set = existing markers plus stored
posted, minus storedresolved, so a fixed finding that recurs is raised again. - Only findings actually submitted are recorded as
posted. A priorpostedfingerprint missing from the current run, on a path still in the diff, becomesresolved.
Write actions
Section titled “Write actions”Both default off and run only on review --pr --post.
--suggestemits a native suggestion only for a single-line finding whose quoted code matches the anchored line, with a non-empty, non-no-op patch at or above the severity floor (defaultmedium). Anything else becomes a plain hint. miucr never pushes to the PR branch.--approval clean|thresholdsubmitsAPPROVEonly when the policy passes and every precondition holds: gate clean, not a fork, trusted author, at least one file reviewed, head SHA unchanged right before submit, not already approved at that head. Any miss degrades toCOMMENT, never an error.serveinherits both off. The Action stays comment-only.- A PAT
APPROVEcounts toward branch-protection reviews. Use a bot identity or a GitHub App if you enable it.
Poll trigger
Section titled “Poll trigger”serve --poll builds the same serve.Job as the webhook and submits it to the
same pool.
- Sources: user notifications (default) or open PRs per allowlisted repo.
- Each new head SHA is one review. The cursor at
~/.config/miu/cr/poll-cursor.json(0600, atomic writes) records the head only after a successful review, so failures retry next tick. - Honors
X-Poll-Interval, sleeps onRateLimitError, backs off with jitter on transient errors, and never advances the cursor on error.
REST API and GitHub App auth
Section titled “REST API and GitHub App auth”MIUCR_API_TOKEN(env only) registers/v1/reviews. One bearer, one trust boundary, not multi-tenant. Empty tokens are rejected before the constant-time compare.POST /v1/reviewsreturns403off the allowlist, otherwise persists apendingrecord with a server-generatedcrypto/randid, queues it on the same pool, and returns202.GETreturns a whitelisted view (no clone path); stalependingrows are recovered tofailed.[github] mode = appmints an RS256 App JWT with stdlib crypto, exchanges it for an installation token, and caches it with refresh-before-expiry and single-flight per installation. The private key is read from a path at startup and never logged or persisted.
Operator reference: REST API & GitHub App.
