Skip to content
Merged
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Reviewer-stated rules: quotes and questions no longer count, more future-looking phrasings do, and the preferences have a Settings card ([#19135](https://github.com/hivecommons/hive/issues/19135)).** Block quotes, fenced code and questions are no longer read as the reviewer's rule, so a reply that quotes the hive and asks "can the hive add this to the knowledge base?" is not recorded under the reviewer's name. A short rule sentence that refers back ("we should consider this in future") keeps the rest of the comment, and `going-forward` now matches "future assessments", "moving forward" and "for the future". Whether capture runs, which associations are recorded at once, extra phrases that count and built-in signals to switch off are `review_feedback.rules.*` keys with an owner-only card under Settings, Features, Review (env vars still work; a saved value wins), audited and applied on the next sweep pass without a restart.
137 changes: 137 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -8425,6 +8425,143 @@
}
}
},
"/api/config/review-feedback/rules": {
"get": {
"tags": [
"System"
],
"summary": "Reviewer-stated rule capture settings",
"description": "Returns review_feedback.rules.* (enabled, trusted_associations, extra_phrases, disabled_signals): for each, the saved value, the effective value, its source (settings, env or default), the default, its env var and YAML key; plus the associations an owner may trust, the built-in signals with examples, and the phrase limit. Owner only.",
"responses": {
"200": {
"description": "Current reviewer-rule capture settings",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "object"
},
"trusted_associations": {
"type": "object"
},
"extra_phrases": {
"type": "object"
},
"disabled_signals": {
"type": "object"
},
"associations": {
"type": "array",
"items": {
"type": "string"
}
},
"signals": {
"type": "array",
"items": {
"type": "object"
}
},
"max_phrases": {
"type": "integer"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"System"
],
"summary": "Set reviewer-stated rule capture settings",
"description": "Replaces the saved review_feedback.rules.* values. An absent or null field clears that saved value, falling back to its env var, then the default. Validated before anything changes; applies on the review-feedback sweep's next pass without a restart. Audited as config_review_feedback_rules. Owner only.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"trusted_associations": {
"type": "array",
"items": {
"type": "string"
}
},
"extra_phrases": {
"type": "array",
"items": {
"type": "string"
}
},
"disabled_signals": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Current settings (same body as GET)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "object"
},
"trusted_associations": {
"type": "object"
},
"extra_phrases": {
"type": "object"
},
"disabled_signals": {
"type": "object"
},
"associations": {
"type": "array",
"items": {
"type": "string"
}
},
"signals": {
"type": "array",
"items": {
"type": "object"
}
},
"max_phrases": {
"type": "integer"
}
}
}
}
}
},
"400": {
"description": "Unknown association or signal, or an invalid phrase; nothing was stored"
},
"500": {
"description": "The config file could not be written; the previous values are restored"
}
}
}
},
"/api/config/reference-repos": {
"get": {
"tags": [
Expand Down
2 changes: 1 addition & 1 deletion src/cmd/hive/boot_knowledge_primer.go
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ func (b *boot) registerKnowledgeStores(p *knowledge.Primer) {
// on the first kick after it appears and connects it to the knowledge API, so
// neither the kick nor the dashboard waits for a restart.
func (b *boot) registerReviewRuleVault(api *knowledge.KnowledgeAPI, p *knowledge.Primer) {
if !reviewrules.Enabled() {
if !reviewRulesEnabled(b.cfg) {
return
}
dir := reviewrules.VaultDir()
Expand Down
73 changes: 73 additions & 0 deletions src/cmd/hive/review_feedback_rules_settings_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
package main

import (
"context"
"strings"
"testing"
"time"

"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/reviewrules"
)

// A plain PR comment that states a rule counts even though it does not address
// the hive; one that quotes the hive and asks a question does not.
func TestReviewFeedbackSweep_ConversationCommentsAreRuleCandidates(t *testing.T) {
h := newRuleHarness(t, reviewrules.Config{})
ask := github.FeedbackItem{ID: "conversation:6990", Kind: github.PRCommentConversation, Author: "nate-double-u", AuthorAssociation: "MEMBER",
Body: "> The rule I would record: maintainers.yaml is the source of truth.\n\n@operator, is there a way to have the hive add to the knowledge-base?",
URL: "https://github.com/cncf/techdocs/pull/424#issuecomment-6990", CreatedAt: time.Now().Add(-time.Hour)}
state := github.FeedbackItem{ID: "conversation:7001", Kind: github.PRCommentConversation, Author: "nate-double-u", AuthorAssociation: "MEMBER",
Body: "In future assessments, the project's security contact comes from SECURITY.md, not the README.",
URL: "https://github.com/cncf/techdocs/pull/424#issuecomment-7001", CreatedAt: time.Now().Add(-time.Hour)}
fb := openDraftFeedback()
fb.Items = nil
fb.RuleCandidates = []github.FeedbackItem{ask, state}
h.src.byKey[feedbackTestKey] = fb

res := h.sweep(t).run(context.Background(), parseReviewFeedbackKey)
rules := h.rules.List()
if res.RulesCaptured != 1 || len(rules) != 1 {
t.Fatalf("res = %+v rules = %+v", res, rules)
}
if rules[0].Provenance[0].CommentID != "conversation:7001" || !strings.Contains(rules[0].Text, "SECURITY.md") {
t.Fatalf("rule = %+v", rules[0])
}
}

// The owner's saved preferences win over the env knobs; unsaved ones keep the
// env value or default.
func TestReviewRulesPolicy(t *testing.T) {
t.Setenv(reviewrules.DisableEnvVar, "")
t.Setenv(reviewrules.TrustedAssociationsEnvVar, "OWNER")
t.Setenv(reviewrules.ExtraPhrasesEnvVar, "env phrase")
t.Setenv(reviewrules.DisabledSignalsEnvVar, "")

cfg := &config.Config{}
rc, on := reviewRulesPolicy(cfg)
if !on || !rc.Trusted["OWNER"] || rc.Trusted["MEMBER"] || len(rc.ExtraPhrases) != 1 || rc.ExtraPhrases[0] != "env phrase" {
t.Fatalf("env only: on=%v cfg=%+v", on, rc)
}

off := false
cfg.SetReviewRulesSettings(config.ReviewRulesSettings{Enabled: &off, TrustedAssociations: []string{"member", "CONTRIBUTOR"},
ExtraPhrases: []string{"worth considering"}, DisabledSignals: []string{"Never"}})
rc, on = reviewRulesPolicy(cfg)
if on || rc.Trusted["OWNER"] || !rc.Trusted["MEMBER"] || !rc.Trusted["CONTRIBUTOR"] || rc.ExtraPhrases[0] != "worth considering" || !rc.DisabledSignals[reviewrules.SignalNever] {
t.Fatalf("settings: on=%v cfg=%+v", on, rc)
}
if activeRuleStore(&reviewrules.Store{}, false) != nil || activeRuleStore(nil, true) != nil {
t.Fatal("activeRuleStore")
}

t.Setenv(reviewrules.DisableEnvVar, "off")
if reviewRulesEnabled(&config.Config{}) || reviewRulesEnabled(nil) {
t.Fatal("env off, nothing saved: capture off")
}
on2 := true
cfg.SetReviewRulesSettings(config.ReviewRulesSettings{Enabled: &on2})
if !reviewRulesEnabled(cfg) {
t.Fatal("a saved on wins over the env")
}
}
50 changes: 47 additions & 3 deletions src/cmd/hive/review_feedback_wire.go
Original file line number Diff line number Diff line change
Expand Up @@ -350,6 +350,47 @@ func (s reviewFeedbackSweep) proposeRuleHome(ctx context.Context, repo string, n
return true
}

// activeRuleStore is the store the sweep captures into: nil while capture is
// switched off, so the sweep runs exactly as without capture.
func activeRuleStore(st *reviewrules.Store, on bool) *reviewrules.Store {
if !on {
return nil
}
return st
}

// reviewRulesEnabled reports whether rule capture runs: the Settings value
// (review_feedback.rules.enabled) when the owner saved one, else
// HIVE_REVIEW_FEEDBACK_RULES (default on).
func reviewRulesEnabled(cfg *config.Config) bool {
if set := cfg.ReviewRulesSettingsSnapshot(); set.Enabled != nil {
return *set.Enabled
}
return reviewrules.Enabled()
}

// reviewRulesPolicy merges the owner's saved preferences over the env knobs
// (hivecommons/hive#19135): each preference saved in hive.yaml
// (review_feedback.rules.*) wins; an unsaved one keeps its env value or
// default. The limits (max rules, merge threshold) stay env-only.
func reviewRulesPolicy(cfg *config.Config) (reviewrules.Config, bool) {
rc := reviewrules.ConfigFromEnv()
set := cfg.ReviewRulesSettingsSnapshot()
if len(set.TrustedAssociations) > 0 {
rc.Trusted = reviewrules.ParseAssociations(strings.Join(set.TrustedAssociations, ","))
}
if len(set.ExtraPhrases) > 0 {
rc.ExtraPhrases = append([]string(nil), set.ExtraPhrases...)
}
if len(set.DisabledSignals) > 0 {
rc.DisabledSignals = map[string]bool{}
for _, n := range set.DisabledSignals {
rc.DisabledSignals[strings.ToLower(strings.TrimSpace(n))] = true
}
}
return rc, reviewRulesEnabled(cfg)
}

// parseReviewFeedbackKey splits "owner/repo#n".
func parseReviewFeedbackKey(key string) (string, int, bool) {
i := strings.LastIndex(key, "#")
Expand Down Expand Up @@ -386,14 +427,17 @@ func sweepReviewFeedback(ctx context.Context, cfg *config.Config, client *github
}
reviewFeedbackStore = st
}
if reviewRuleStore == nil && reviewrules.Enabled() {
rs, err := reviewrules.Open(reviewrules.Dir(), reviewrules.VaultDir(), reviewrules.ConfigFromEnv())
rulesCfg, rulesOn := reviewRulesPolicy(cfg)
if reviewRuleStore == nil && rulesOn {
rs, err := reviewrules.Open(reviewrules.Dir(), reviewrules.VaultDir(), rulesCfg)
if err != nil {
logger.Warn("review feedback: rule index unreadable or not writable; rules kept in memory only", "dir", reviewrules.Dir(), "error", err)
}
reviewRuleStore = rs
}
if reviewRuleStore != nil {
// Settings changes apply on the next pass, without a restart.
reviewRuleStore.SetConfig(rulesCfg)
for _, line := range reviewRuleStore.Reconcile(now) {
logger.Info("review feedback: rule changed by an operator", "change", line)
}
Expand All @@ -410,7 +454,7 @@ func sweepReviewFeedback(ctx context.Context, cfg *config.Config, client *github
Cursor: reviewFeedbackCursor,
Now: now,
Logger: logger,
Rules: reviewRuleStore,
Rules: activeRuleStore(reviewRuleStore, rulesOn),
Lane: cfg.BaseAgentName,
Managed: cfg.IsManagedRepo,
Route: func(owner string) reviewFeedbackRoute {
Expand Down
8 changes: 4 additions & 4 deletions src/docs/api-reference/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1808` |
| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1809` |
| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1810` |
| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:567` |
| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:568` |
| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:569` |
| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:570` |
| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:570` |
| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:571` |
| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:572` |
| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:573` |
Loading
Loading