Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-19069-review-preflight.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The PR reviewer now gets evidence the hive gathers before the review starts (refs #19069). New `review.preflight` block, overridable per repo at `repos.<repo>.review_preflight`: (1) **repository rules**, on by default, lists the repo's own rule documents (AGENTS.md, CLAUDE.md, CONTRIBUTING, DESIGN*/ARCHITECTURE* docs, ADRs, copilot and cursor rules, CODEOWNERS; patterns configurable, deterministic byte budget) and operator-defined named rules, and the reviewer must cite the rule it applied; (2) **dependency evidence**, off by default because it sends package names and versions to OSV and the package registries, checks added or bumped dependencies for advisories and release age across Go, npm/yarn/pnpm, Python, Rust, Java, Ruby, PHP, .NET and GitHub Actions, reports unsupported manifests as "not checked", degrades to an explicit "could not check: offline" (`offline: true` or `HIVE_REVIEW_PREFLIGHT_OFFLINE=true`), caches answers, and honors severity thresholds and an ignore list with reasons and expiry; (3) correctness-review guidance for outdated error and log messages and for sentinel values flowing into min, max and sum aggregates. See "Review preflight" in `src/docs/review-swarm.md`. Credit to Mike Spreitzer for the review-tool comparison that motivated this.
3 changes: 3 additions & 0 deletions src/cmd/hive/main_sweeps.go
Original file line number Diff line number Diff line change
Expand Up @@ -2568,6 +2568,9 @@ func planReviewDispatchWith(ctx context.Context, cfg *config.Config, actionable
// (review.bot_author_full_review_paths); fetched only for a listed
// bot's PR that is about to be reviewed.
item.ChangedFiles, item.ChangedFilesKnown = reviewBotRouteFilesFor(ctx, cfg, ghr, botRoute, artifact, state, fullRepo, pr.Number, pr.Author, pr.HeadSHA, pr.BodyDigest)
// Repository rules and dependency preflight (hivecommons/hive#19069),
// gathered once per head for a PR about to be reviewed.
item.PreflightSection = reviewPreflightFor(ctx, cfg, ghr, artifact, state, fullRepo, pr, logger)
prs = append(prs, item)
}
// PRs a review webhook just fired for go first, so the early eval cycle
Expand Down
87 changes: 87 additions & 0 deletions src/cmd/hive/review_preflight.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
package main

import (
"context"
"fmt"
"log/slog"
"sync"

"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/review"
"github.com/hivecommons/hive/pkg/reviewpreflight"
)

// maxPreflightMemo bounds the per-head evidence memo.
const maxPreflightMemo = 256

// reviewPreflightSource is what the evidence builder reads from GitHub. It is
// an optional capability of the planner's GitHub client: a client without it
// simply yields no evidence.
type reviewPreflightSource interface {
ReviewPreflightTree(ctx context.Context, repo, ref string) ([]reviewpreflight.TreeEntry, bool)
ReviewPreflightFiles(ctx context.Context, repo string, number int) ([]reviewpreflight.ChangedFile, bool)
}

var (
reviewPreflightClient = reviewpreflight.NewClient()
reviewPreflightMemoMu sync.Mutex
reviewPreflightMemoByHead = map[string]string{}
)

// reviewPreflightFor builds the evidence section for one PR, or "" when the
// checks are off, the PR is not about to be reviewed at this head, or the
// source is unavailable. The answer is memoized per repo, PR, head and
// effective settings, so the planner's repeated cycles cost one lookup.
func reviewPreflightFor(ctx context.Context, cfg *config.Config, ghr reviewPlannerGitHub, artifact review.Artifact, state review.DispatchState, repo string, pr github.PullRequest, logger *slog.Logger) string {
src, ok := ghr.(reviewPreflightSource)
if !ok || src == nil || cfg == nil || pr.HeadSHA == "" {
return ""
}
set := cfg.ReviewPreflightFor(repo)
if !set.RuleDocs && !set.Dependencies && len(set.Rules) == 0 {
return ""
}
if _, judged := artifact.AggregateForBody(repo, pr.Number, pr.HeadSHA, pr.BodyDigest); judged {
return ""
}
key := fmt.Sprintf("%s#%d@%s|%v", repo, pr.Number, pr.HeadSHA, set)
reviewPreflightMemoMu.Lock()
cached, hit := reviewPreflightMemoByHead[key]
reviewPreflightMemoMu.Unlock()
if hit {
return cached
}
if !state.PendingSince(repo, pr.Number, pr.HeadSHA).IsZero() {
// Already dispatched at this head: the kick is out, nothing to attach.
return ""
}
in := reviewpreflight.Input{Repo: repo}
if set.RuleDocs {
ref := pr.BaseSHA
if ref == "" {
ref = pr.HeadSHA
}
in.Ref = ref
in.Tree, in.TreeKnown = src.ReviewPreflightTree(ctx, repo, ref)
}
if set.Dependencies {
in.Files, in.FilesKnown = src.ReviewPreflightFiles(ctx, repo, pr.Number)
}
out := reviewpreflight.Build(ctx, reviewPreflightClient, set, in)
if logger != nil && out != "" {
logger.Info("review evidence attached", "repo", repo, "pr", pr.Number, "bytes", len(out),
"rule_docs", set.RuleDocs, "dependencies", set.Dependencies, "offline", set.Offline)
}
if (set.RuleDocs && !in.TreeKnown) || (set.Dependencies && !in.FilesKnown) {
// A failed read is retried next cycle rather than remembered.
return out
}
reviewPreflightMemoMu.Lock()
if len(reviewPreflightMemoByHead) >= maxPreflightMemo {
reviewPreflightMemoByHead = map[string]string{}
}
reviewPreflightMemoByHead[key] = out
reviewPreflightMemoMu.Unlock()
return out
}
83 changes: 83 additions & 0 deletions src/docs/review-swarm.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,9 @@ review:
delta_rereview: true # optional; re-review a PR already judged at an earlier head by its diff since that head (default on)
delta_trivial_lines: 20 # optional; a delta under this many lines in files the prior verdict passed re-stamps it without a model call (default 20; negative disables)
delta_max_age: 72h # optional; a changes_requested verdict with findings older than this anchors no delta, the PR is reviewed in full (default 72h)
preflight: # optional; repo rule documents and dependency evidence for the reviewer, see "Review preflight" below
rule_docs: true # default on; point the reviewer at the repo's own rule documents (GitHub API only, no new egress)
dependencies: false # default OFF; vulnerability and release-age lookups for added or bumped dependencies (sends package names and versions to OSV and the registries)
severity:
block_at: P2 # optional; P1 | P2 | P3, see "Blocking line" below
comment_below: true # default true
Expand Down Expand Up @@ -735,6 +738,86 @@ The review-feedback sweep (#19027) ignores bot comments so two agents can never

State lives in `/data/factcheck/state.json` (`HIVE_FACTCHECK_DIR` overrides it). A hive that cannot write it keeps counting in memory, and the marked reviews on the PR still bound the loop.

## Review preflight (`review.preflight`)

The reviewer reads the diff and the tree. Review preflight adds facts the hive gathers before the review starts, so a finding can rest on a rule the repository published or on an advisory id instead of on a hunch (hivecommons/hive#19069). It is a general mechanism: it works for any repository and language, and every part can be turned off.

Hive-wide defaults live under `review.preflight`; a repository overrides them under `repos.<repo>.review_preflight`. Precedence per field is repo, then hive-wide, then the default. Lists replace (the repo's list wins) except `rule_doc_paths`, `rules` and `ignore`, which add to the hive-wide entries (same `id`, or same `id` and `package`, is replaced by the repo's).

```yaml
review:
preflight:
rule_docs: true # default on
rule_doc_paths: ["handbook/**"] # added to the default patterns below
rule_doc_exclude: ["CODEOWNERS"] # documents matching these are never listed
rule_doc_budget_bytes: 60000 # total bytes of rule documents one review reads (default 60000)
rules: # short named rules the reviewer enforces
- id: no-sleep-in-tests
severity: medium # low | medium | high | critical (default medium)
text: Tests must not use fixed sleeps; wait on a condition.
dependencies: false # default OFF, see "What leaves the hive"
vulnerabilities: true # default on when dependencies is on; OSV lookup
release_age: true # default on when dependencies is on; registry publish date
offline: false # true (or HIVE_REVIEW_PREFLIGHT_OFFLINE=true) makes every lookup say "could not check: offline"
osv_url: https://api.osv.dev # point at an internal mirror if you run one
registry_urls: {npm: https://npm.mirror.example} # per ecosystem id, see the table below
min_release_age_days: 14 # a version published more recently is a supply-chain note (default 14; negative disables)
severity_floor: low # advisories below this are not listed (default low; unstated severity is always listed)
block_severity: high # advisories at or above this are in-scope blockers, lower ones are notes (default high)
cache_ttl: 6h # reuse registry and advisory answers (default 6h)
request_timeout: 10s # per outbound request (default 10s)
max_dependencies: 30 # lookups per PR; the rest are listed as not checked (default 30)
ignore: # accepted risks: a reason is required, expires is optional (YYYY-MM-DD)
- {id: GHSA-xxxx-xxxx-xxxx, package: example.com/lib, reason: "not reachable from our code", expires: "2027-03-01"}
repos:
widgets:
review_preflight:
dependencies: true
rules:
- {id: widgets-api, text: "Public handlers must validate input before use.", severity: high}
```

### Repository rules

With `rule_docs` on, the hive lists the repository at the PR's base commit and tells the reviewer which rule documents exist, how many bytes of each to read, and how to read them. The default patterns are matched case-insensitively (a pattern without a slash matches at the repository root; `dir/**` matches any text file below `dir`): `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING*`, `DESIGN*.md`, `ARCHITECTURE*.md`, `STYLE*.md`, `CODEOWNERS` (also under `.github/` and `docs/`), `.github/copilot-instructions.md`, `.cursor/rules/**`, `docs/design/**`, `docs/adr/**`, `docs/architecture/**`. Selection is deterministic: patterns in list order, then path order, each document capped at half the budget, documents past the budget listed as omitted. The reviewer must name the document and the rule it applied, and quote it; a finding that invokes a rule it did not read is a false positive.

`rules` are the operator's own named rules, for conventions no document states. The reviewer enforces them at the stated severity and cites the id.

### Dependency evidence

With `dependencies` on, the hive reads the PR's changed manifests and, for each dependency version the diff adds or bumps, queries the vulnerability database and the package registry. The reviewer receives advisory ids with a normalized severity and publish dates, nothing else from those services (no free text), and is told to report only what is listed and to cite the id. A line that says `not checked` or `could not check` means no data, never a clean result.

| Ecosystem id | Manifests | OSV ecosystem | Publish date from |
|---|---|---|---|
| `go` | `go.mod`, `go.sum` | Go | proxy.golang.org |
| `npm` | `package.json`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `pnpm-lock.yaml` | npm | registry.npmjs.org |
| `pypi` | `requirements*.txt`, `pyproject.toml` (exact pins), `poetry.lock`, `uv.lock` | PyPI | pypi.org |
| `crates` | `Cargo.lock` | crates.io | crates.io |
| `maven` | `pom.xml`, `gradle.lockfile` | Maven | search.maven.org |
| `rubygems` | `Gemfile.lock` | RubyGems | rubygems.org |
| `packagist` | `composer.lock` | Packagist | repo.packagist.org |
| `nuget` | `packages.lock.json` | NuGet | api.nuget.org |
| `actions` | `.github/workflows/*.yml` (`uses:` with a full version tag) | GitHub Actions | not looked up |
| `container` | `Dockerfile*`, compose files | none | not looked up |

A changed manifest of a kind that has no entry yet (Pipfile.lock, mix.lock, pubspec.lock, Package.resolved, Podfile.lock, bun and deno lockfiles, Chart.lock, flake.lock, Terraform and Bazel lockfiles, Conan, sbt) is reported as `Not checked`, as is a manifest whose patch GitHub withheld, an action pinned by SHA or a floating tag, and every dependency past `max_dependencies`. Only versions written in the diff are checked; transitive dependencies of a manifest without a lockfile are not resolved.

**Adding an ecosystem** is a table entry plus a test: append an `Ecosystem` to `Ecosystems` in `src/pkg/reviewpreflight/ecosystems.go` (manifest patterns, a parser over the patch lines, the OSV ecosystem id, and an `Age` lookup with its default registry URL), add a case to `TestEcosystemParsers`, and add a row to the table above.

**Noise control.** A vulnerable-dependency finding needs an advisory id from the list; an age note needs the publish date and is never a blocker on its own. `block_severity` decides which advisories are in-scope blockers (`changes_requested`) and which are notes; `severity_floor` hides low-severity noise. An accepted risk goes in `ignore` with a reason (required) and an expiry; an expired entry stops suppressing and the evidence says so. The id `release-age` with a `package` silences the release-age note for that package.

### What leaves the hive, and how to turn it off

- **Rule documents** use the GitHub API the hive already calls (one repository tree listing per PR head). Nothing new leaves. Turn off with `rule_docs: false`.
- **Dependency checks are off by default** because they contact third-party services about a repository that may be private. When on, per changed dependency the hive sends: to OSV (`osv_url`, default api.osv.dev) the package name, ecosystem and version; to the registry (see the table, overridable with `registry_urls`) a GET for that package or version. No token, credential, repository name, PR text or source code is sent, and requests carry no `Authorization` header. Requests follow the hive's upstream proxy settings (`network.upstream_proxy`, `HTTPS_PROXY`). The services see the hive's egress IP and the dependency names of the PRs it reviews.
- **Offline or air-gapped:** set `offline: true` or `HIVE_REVIEW_PREFLIGHT_OFFLINE=true`; no request is made and the evidence says `could not check: offline`. An unreachable service, a timeout, a 429 or a 5xx degrades the same way, per check, with the reason. Answers are cached in memory for `cache_ttl`, and a PR head is looked up once.
- **Internal mirrors:** set `osv_url` and `registry_urls` to your own endpoints.
- **Disable entirely:** `dependencies: false` (the default), per repo with `repos.<repo>.review_preflight.dependencies: false`.

### Two extra reviewer checks

The correctness perspective (and a combined review that includes it) now also asks for two defect classes a diff-only read tends to miss: error, log and test-failure messages and comments that stopped describing behavior after the change, and sentinel values (zero, -1, an unset marker) flowing into min, max, sum or comparison aggregates. Each finding must cite the line and a concrete input.

## Revising a recorded verdict

Dispatch skips any PR that already carries a verdict for its head SHA. That is the right default — it stops the reviewer re-reviewing unchanged code every sweep — but it also makes a review final the moment it is written, even when the reviewer itself was defective. Two settings, both required, re-open such verdicts narrowly:
Expand Down
11 changes: 11 additions & 0 deletions src/hive.yaml.example
Original file line number Diff line number Diff line change
Expand Up @@ -927,6 +927,17 @@ governor:
# # File: "kind: ReviewPerspectives" + "perspectives: [{name, focus}]". Names and
# # focus only; combined_perspectives, plan_match and max_perspectives_per_pr stay
# # here. Format: src/docs/review-swarm.md, "Live-linked perspectives".
# preflight: # facts gathered for the reviewer before it starts (#19069); per-repo
# # overrides under repos.<repo>.review_preflight. src/docs/review-swarm.md,
# # "Review preflight", lists every key and exactly what leaves the hive.
# rule_docs: true # default on: point the reviewer at the repo's own rule documents
# rules: [] # named operator rules: [{id, text, severity}]
# dependencies: false # default OFF: advisory and release-age lookups send package names
# # and versions to OSV and the package registries
# offline: false # or HIVE_REVIEW_PREFLIGHT_OFFLINE=true: no lookups, "could not check: offline"
# min_release_age_days: 14
# block_severity: high
# ignore: [] # accepted risks: [{id, package, reason, expires}]
# fixer_agent: "" # optional override; defaults to the PR lane, then scanner
# fixer_fallback_agents: [] # opt-in ordered repair lanes, e.g. [fixer, scanner-2]
# fixer_fallback_after_undeliverable: 3 # consecutive refusals before rerouting;
Expand Down
5 changes: 5 additions & 0 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -8805,6 +8805,11 @@ type ReviewConfig struct {
// reviewer's memory of it have both moved on. Empty means
// DefaultReviewDeltaMaxAge.
DeltaMaxAge string `yaml:"delta_max_age,omitempty" json:"delta_max_age,omitempty"`
// Evidence configures the facts the hive gathers before a review: the
// repository's own rule documents, named operator rules, and dependency
// vulnerability and release-age data (hivecommons/hive#19069). Per-repo
// overrides live at repos.<repo>.review_preflight.
Preflight ReviewPreflightConfig `yaml:"preflight,omitempty" json:"preflight,omitempty"`
// HumanDecisionLabel names an EXISTING repo label to apply when the review
// swarm holds a PR for a human. The review comment's in-body marker is
// always the primary signal and never depends on this: a label makes the
Expand Down
3 changes: 3 additions & 0 deletions src/pkg/config/repo_settings.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ type RepoSettings struct {
// hive auto-close is never re-closed under any value. YAML booleans
// true/false are accepted and read as the strings.
ParentAutoClose string `yaml:"parent_autoclose,omitempty" json:"parent_autoclose,omitempty"`
// ReviewPreflight overrides review.preflight for this repo
// (hivecommons/hive#19069). Unset fields inherit the hive-wide value.
ReviewPreflight ReviewPreflightConfig `yaml:"review_preflight,omitempty" json:"review_preflight,omitempty"`
}

// Parent auto-close policy values for RepoSettings.ParentAutoClose.
Expand Down
Loading
Loading