diff --git a/changelog.d/fixed-19135-review-rules-classifier-and-settings.md b/changelog.d/fixed-19135-review-rules-classifier-and-settings.md new file mode 100644 index 0000000000..9809bde138 --- /dev/null +++ b/changelog.d/fixed-19135-review-rules-classifier-and-settings.md @@ -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. diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 95e1bec11f..8458d8af56 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -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": [ diff --git a/src/cmd/hive/boot_knowledge_primer.go b/src/cmd/hive/boot_knowledge_primer.go index 762361e2e7..6e323e6f60 100644 --- a/src/cmd/hive/boot_knowledge_primer.go +++ b/src/cmd/hive/boot_knowledge_primer.go @@ -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() diff --git a/src/cmd/hive/review_feedback_rules_settings_test.go b/src/cmd/hive/review_feedback_rules_settings_test.go new file mode 100644 index 0000000000..11eb8c546d --- /dev/null +++ b/src/cmd/hive/review_feedback_rules_settings_test.go @@ -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") + } +} diff --git a/src/cmd/hive/review_feedback_wire.go b/src/cmd/hive/review_feedback_wire.go index 769ce48340..1f6e3f207c 100644 --- a/src/cmd/hive/review_feedback_wire.go +++ b/src/cmd/hive/review_feedback_wire.go @@ -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, "#") @@ -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) } @@ -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 { diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index 7a02fd4b8d..7d6e6b2fff 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -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` | diff --git a/src/docs/api-reference/configuration.md b/src/docs/api-reference/configuration.md index 68a1c163ee..e3f22de6dc 100644 --- a/src/docs/api-reference/configuration.md +++ b/src/docs/api-reference/configuration.md @@ -106,11 +106,13 @@ JSON, see [Editing `hive.yaml`](../editing-hive-yaml.md#view-yaml-or-export-effe | `PUT` | `/api/config/write-surface` | Owner only | Replace the lane write allowlist; `{"allowlist": {}}` clears it; unknown operation or bad lane name is a 400 with nothing changed | `pkg/dashboard/api.go:528` | | `GET` | `/api/config/reference-repos` | Owner only | `project.reference_repos` ([#18136](https://github.com/hivecommons/hive/issues/18136)): `reference_repos` (`{repo, write, write_token_file}` plus `derived_from` on a derived entry and, on every write entry, `credential_state`, `credential_reason` and `credential_login`, the GitHub account the writes appear under ([#18197](https://github.com/hivecommons/hive/issues/18197)), plus `credential_identity` (`bot`, `owner` or `token_file`) and `credential_note`, the one-line why ([#18516](https://github.com/hivecommons/hive/issues/18516)); always an array), `write_kinds`, `write_identity` (`project.remote_write_identity` with the default applied), `write_identities` and `bot_login` (the App bot login, when known) | `pkg/dashboard/api.go:558` | | `PUT` | `/api/config/reference-repos` | Owner only | Replace `project.reference_repos`; `{"reference_repos": []}` clears it. Refused with a 400 and nothing changed when the config loader would reject the list (bare name, repo also in `project.repos`, duplicate, unknown write kind, token file without write) or when a write entry has no credential boot would accept — the same message boot exits 22 with — or when an entry carries a `write_token_file` the config file does not already hold for that repo (the path is operator-only; a dashboard write opt-in writes as the hive owner's connected GitHub account). Entries with `derived_from` ([#18139](https://github.com/hivecommons/hive/issues/18139)) are the request issue's grant: echo them back as served; changing one's write set, leaving one out, sending one the hive did not derive or adding a hand-written entry for the same repo is a 409 naming the issue to change instead ([#18161](https://github.com/hivecommons/hive/issues/18161)). They are never stored: the saved list holds the hand-written entries and the derived set is merged back in memory after the save. 500 when the file could not be written (proxy restored, nothing changed). On success the GitHub proxy's reference policies are replaced without a restart; audited as `config_reference_repos` | `pkg/dashboard/api.go:559` | -| `PUT` | `/api/config/reference-repos/write-identity` | Owner only | Set `project.remote_write_identity` ([#18516](https://github.com/hivecommons/hive/issues/18516)): body `{"write_identity": "bot"}`, one of `bot`, `bot_only`, `owner`. 400 on an unknown value, or when a hand-written write entry would have no credential under the new value (the message boot exits 22 with); nothing is stored then. 500 when the file could not be written. On success the reference repos are re-resolved before the response, which is the same body as `GET /api/config/reference-repos`; audited as `config_remote_write_identity` with `previous` and `write_identity` | `pkg/dashboard/api.go:564` | +| `PUT` | `/api/config/reference-repos/write-identity` | Owner only | Set `project.remote_write_identity` ([#18516](https://github.com/hivecommons/hive/issues/18516)): body `{"write_identity": "bot"}`, one of `bot`, `bot_only`, `owner`. 400 on an unknown value, or when a hand-written write entry would have no credential under the new value (the message boot exits 22 with); nothing is stored then. 500 when the file could not be written. On success the reference repos are re-resolved before the response, which is the same body as `GET /api/config/reference-repos`; audited as `config_remote_write_identity` with `previous` and `write_identity` | `pkg/dashboard/api.go:567` | | `GET` | `/api/config/repos/parent-autoclose` | Owner only | `repos..parent_autoclose` for every monitored repo: the effective value (`true`, `epics_too`, `trackers_too` or `false`), whether the repo carries its own, the default and the four options the Settings editor offers ([#19070](https://github.com/hivecommons/hive/issues/19070)) | `pkg/dashboard/api.go:561` | | `PUT` | `/api/config/repos/parent-autoclose` | Owner only | Set one monitored repo's parent auto-close policy: `{"repo": "owner/name", "value": "true" \| "epics_too" \| "trackers_too" \| "false"}`. `true` is the default and clears the override. 400 for a missing repo or an invalid value, 404 for a repo that is not monitored, 500 when the file could not be written (previous value restored). Applies without a restart; audited as `config_repo_parent_autoclose`. Parents a person reopened and tracking issues are never auto-closed under any value | `pkg/dashboard/api.go:562` | -| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:573` | -| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:574` | +| `GET` | `/api/config/review-feedback/rules` | Owner only | Reviewer-stated rule capture settings ([#19135](https://github.com/hivecommons/hive/issues/19135)): `enabled`, `trusted_associations`, `extra_phrases` and `disabled_signals`, each with `saved`, `effective`, `source` (`settings`, `env` or `default`), `default`, `env_var` and `yaml_key`; plus `associations`, `signals` (built-in signal names with examples) and `max_phrases` | `pkg/dashboard/api.go:564` | +| `PUT` | `/api/config/review-feedback/rules` | Owner only | Replace `review_feedback.rules.*`: `{"enabled": bool, "trusted_associations": [], "extra_phrases": [], "disabled_signals": []}`; an absent or null field clears that saved value (back to its env var, then the default). 400 with nothing changed for an unknown association or signal, a phrase under 3 or over 80 characters, or more than 20 phrases; 500 when the file could not be written (previous values restored). Applies on the review-feedback sweep's next pass without a restart; audited as `config_review_feedback_rules` | `pkg/dashboard/api.go:565` | +| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:576` | +| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:577` | | `GET` | `/api/config/review` | Dashboard auth/session | Review Config Get | `pkg/dashboard/api.go:219` | | `PUT` | `/api/config/review` | Owner only | Review Config Set | `pkg/dashboard/api.go:222` | | `PUT` | `/api/config/governor/features` | Owner only | Governor Features | `pkg/dashboard/api.go:228` | diff --git a/src/docs/review-feedback-rules.md b/src/docs/review-feedback-rules.md index adfeb1b6e0..aa51e257c1 100644 --- a/src/docs/review-feedback-rules.md +++ b/src/docs/review-feedback-rules.md @@ -8,14 +8,21 @@ leaving it to the agent's discretion ([#19046](https://github.com/hivecommons/hi ## What happens -1. **Classify.** Each human comment on the PR is matched against fixed phrase signals. A comment with at least one is a rule; the rest - are corrections and are handled as before. The signals are `source-of-truth`, `authoritative`, `always` ("should always", "must always"), - `never` ("should never", "must never"), `going-forward` ("going forward", "from now on", "next time", "for future assessments"), - `capture-request` ("capture this", "document this", "record it"), `assessment-criteria` ("assessment criteria", "assessment knowledge") - and `knowledge-base`. Comment text is data: it is matched and quoted, never executed, fetched or followed. +1. **Classify.** Each human comment on the PR is matched against phrase signals. A comment with at least one is a rule; the rest are + corrections and are handled as before. The built-in signals are `source-of-truth`, `authoritative`, `always` ("should always", "must + always"), `never` ("should never", "must never"), `going-forward` ("going forward", "moving forward", "from now on", "in future", "next + time", "future assessments"), `capture-request` ("capture this", "document this", "record it"), `assessment-criteria` ("assessment + criteria", "assessment knowledge") and `knowledge-base`. The owner can switch built-in signals off and add plain phrases of their own (see + [Settings](#settings)). Block quotes (`>` lines), fenced code and questions never count: a reply that quotes the hive and asks "can the + hive add this to the knowledge base?" is not a rule ([#19135](https://github.com/hivecommons/hive/issues/19135)). Comment text is data: + it is matched and quoted, never executed, fetched or followed. 2. **Extract.** The rule text is the sentences that carry a signal, without clauses that only ask for the capture, bounded to 600 characters. + A short rule sentence that refers back ("we should consider this in future") is recorded with the rest of the comment, so the rule keeps + what "this" is. 3. **Gate on trust.** A rule changes what every later run is told, so only reviewers whose GitHub association is in - `HIVE_REVIEW_FEEDBACK_RULE_TRUSTED_ASSOCIATIONS` (default `OWNER,MEMBER,COLLABORATOR`) are captured at once. Any other reviewer's rule is + `review_feedback.rules.trusted_associations` (env `HIVE_REVIEW_FEEDBACK_RULE_TRUSTED_ASSOCIATIONS`, default `OWNER,MEMBER,COLLABORATOR`) + are captured at once. On a repo of an organisation the hive is not part of, an org member whose membership is private shows as + `CONTRIBUTOR`, so their rules are queued unless the owner trusts `CONTRIBUTOR`. Any other reviewer's rule is queued as a draft knowledge entry that a person approves. A trusted reviewer restating a queued rule activates it. 4. **Persist.** The rule gets an id (`R-1`, `R-2`, ...) and is written to the `review-rules` local knowledge channel as an entry tagged `pin`, with provenance: the PR, the comment id and URL (the entry's `source`), the reviewer, their association, the time, and whether the hive or @@ -77,10 +84,22 @@ neither kicks nor the dashboard wait for a restart. After a change, the primer r ## Settings +Which phrases count and whose rules are recorded at once are the owner's preferences, per hive. Edit them in **Settings, Features, Review, +Reviewer-stated rules** (owner only; applies on the sweep's next pass without a restart; audited as `config_review_feedback_rules`), or in +hive.yaml. A value saved there wins over its env var; an unsaved one keeps the env var, then the default. Changing a preference applies to +comments read from then on; a comment already read is not read again. + +| hive.yaml | Env var | Default | Meaning | +|---|---|---|---| +| `review_feedback.rules.enabled` | `HIVE_REVIEW_FEEDBACK_RULES` | on | Off stops rule capture; the sweep keeps running and recorded rules keep reaching agents until retracted. With the env var off at boot, a rule captured after switching on in Settings reaches kicks after the next restart. | +| `review_feedback.rules.trusted_associations` | `HIVE_REVIEW_FEEDBACK_RULE_TRUSTED_ASSOCIATIONS` | `OWNER,MEMBER,COLLABORATOR` | Associations whose rules are captured at once; others are queued. | +| `review_feedback.rules.extra_phrases` | `HIVE_REVIEW_FEEDBACK_RULE_EXTRA_PHRASES` (comma-separated) | none | Plain phrases (3 to 80 characters, at most 20) that also mark a rule, matched case-insensitively as whole words, for example "worth considering". | +| `review_feedback.rules.disabled_signals` | `HIVE_REVIEW_FEEDBACK_RULE_DISABLED_SIGNALS` (comma-separated) | none | Built-in signal names that no longer mark a rule. | + +These stay env-only: + | Variable | Default | Meaning | |---|---|---| -| `HIVE_REVIEW_FEEDBACK_RULES` | on | Set to `0`, `false`, `off` or `no` to stop rule capture. The sweep keeps running. | -| `HIVE_REVIEW_FEEDBACK_RULE_TRUSTED_ASSOCIATIONS` | `OWNER,MEMBER,COLLABORATOR` | Associations whose rules are captured at once; others are queued. | | `HIVE_REVIEW_FEEDBACK_RULES_MAX` | `200` | Bound on live (active or queued) rules. | | `HIVE_REVIEW_FEEDBACK_RULE_MERGE_THRESHOLD` | `0.8` | Text similarity at which same-scope rules merge. | | `HIVE_REVIEW_FEEDBACK_RULES_VAULT` | `/data/vaults/review-rules` | Knowledge channel the rules are written to. | diff --git a/src/docs/settings.md b/src/docs/settings.md index 3d6aa43d61..304218b51c 100644 --- a/src/docs/settings.md +++ b/src/docs/settings.md @@ -82,6 +82,7 @@ Optional capabilities, each off or inert until you turn it on. Where a feature h - Auto-merge: [App self-merge sweep](operator-reference.md#app-self-merge-sweep-auto_merge), [Trusted bot authors](hive-merge.md#trusted-bot-authors), and [Trusted-author auto-merge](hive-merge.md#trusted-author-auto-merge). - Review gate: [Review swarm](review-swarm.md#configuration), [Blocking line and backlog](review-swarm.md#blocking-line-reviewseverity-reviewbacklog), and [external review bot threads](review-bot-threads.md). - Trajectory review: [Trajectory-Review Lane](trajectory-review.md#configuration). +- Reviewer-stated rules: [Reviewer-stated rules from review feedback](review-feedback-rules.md#settings). A card under Review (owner only, `review_feedback.rules.*`) turns capture on or off, picks whose rules are recorded at once, adds phrases that count, and switches built-in signals off; each control shows its default and where the current value comes from. - Linear agent: [Linear agent integration](linear-agent.md). - Upstream watch: [Upstream watch](upstream-watch.md#configuration). diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index 0c9656ad71..1932a43f28 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -185,11 +185,16 @@ type Config struct { Runs RunsConfig `yaml:"runs,omitempty" json:"runs,omitempty"` // Meetings turns on hive as a live meeting participant through Quorum // (hivecommons/hive#18284). Zero value: off, no Quorum process. - Meetings MeetingsConfig `yaml:"meetings,omitempty" json:"meetings,omitempty"` - Swarm SwarmConfig `yaml:"swarm,omitempty" json:"swarm,omitempty"` - Autonomy AutonomyConfig `yaml:"autonomy,omitempty" json:"autonomy,omitempty"` - Review ReviewConfig `yaml:"review,omitempty" json:"review,omitempty"` - AutoMerge AutoMergeConfig `yaml:"auto_merge,omitempty" json:"auto_merge,omitempty"` + Meetings MeetingsConfig `yaml:"meetings,omitempty" json:"meetings,omitempty"` + Swarm SwarmConfig `yaml:"swarm,omitempty" json:"swarm,omitempty"` + Autonomy AutonomyConfig `yaml:"autonomy,omitempty" json:"autonomy,omitempty"` + Review ReviewConfig `yaml:"review,omitempty" json:"review,omitempty"` + // ReviewFeedback holds the owner's preferences for capturing rules that + // reviewers state on the hive's own PRs (hivecommons/hive#19135). Nil: + // every preference falls back to its env var, then its default. Read and + // written through ReviewRulesSettingsSnapshot / SetReviewRulesSettings. + ReviewFeedback *ReviewFeedbackConfig `yaml:"review_feedback,omitempty" json:"review_feedback,omitempty"` + AutoMerge AutoMergeConfig `yaml:"auto_merge,omitempty" json:"auto_merge,omitempty"` // Decisions tunes how decisions on needs-human items are recorded; its // `delegate` block gates the activity monitor's "Let hive decide" // action (default on). diff --git a/src/pkg/config/review_feedback.go b/src/pkg/config/review_feedback.go new file mode 100644 index 0000000000..a8bfff74df --- /dev/null +++ b/src/pkg/config/review_feedback.go @@ -0,0 +1,102 @@ +package config + +import ( + "strings" + "sync" +) + +// reviewFeedbackMu guards Config.ReviewFeedback: the dashboard's Settings card +// writes it while the review-feedback sweep reads it on the eval tick. +var reviewFeedbackMu sync.RWMutex + +// ReviewFeedbackConfig is the `review_feedback:` block of hive.yaml. +type ReviewFeedbackConfig struct { + // Rules are the preferences for capturing rules reviewers state on the + // hive's own PRs into its knowledge (hivecommons/hive#19046, + // hivecommons/hive#19135). + Rules ReviewRulesSettings `yaml:"rules,omitempty" json:"rules,omitempty"` +} + +// ReviewRulesSettings are the owner's preferences for reviewer-rule capture. +// Every field is optional: an unset field falls back to its environment +// variable, then to the built-in default, so a hive that never saved the +// Settings card behaves exactly as before. +type ReviewRulesSettings struct { + // Enabled turns capture on or off (HIVE_REVIEW_FEEDBACK_RULES; default on). + Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"` + // TrustedAssociations are the GitHub author associations whose rules are + // recorded at once; every other reviewer's rule is queued for a person + // (HIVE_REVIEW_FEEDBACK_RULE_TRUSTED_ASSOCIATIONS; default OWNER, MEMBER, + // COLLABORATOR). + TrustedAssociations []string `yaml:"trusted_associations,omitempty" json:"trusted_associations,omitempty"` + // ExtraPhrases are plain phrases that also mark a comment as a rule, on + // top of the built-in signals (HIVE_REVIEW_FEEDBACK_RULE_EXTRA_PHRASES; + // default none). + ExtraPhrases []string `yaml:"extra_phrases,omitempty" json:"extra_phrases,omitempty"` + // DisabledSignals are built-in signal names that no longer mark a rule + // (HIVE_REVIEW_FEEDBACK_RULE_DISABLED_SIGNALS; default none). + DisabledSignals []string `yaml:"disabled_signals,omitempty" json:"disabled_signals,omitempty"` +} + +// ReviewAssociations are the GitHub author associations an owner may trust, +// in the order the Settings card lists them. +var ReviewAssociations = []string{"OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "FIRST_TIME_CONTRIBUTOR", "FIRST_TIMER", "NONE"} + +// IsReviewAssociation reports whether a is one of ReviewAssociations +// (case-insensitive). +func IsReviewAssociation(a string) bool { + a = strings.ToUpper(strings.TrimSpace(a)) + for _, known := range ReviewAssociations { + if a == known { + return true + } + } + return false +} + +// ReviewRulesSettingsSnapshot returns a copy of the saved review-rule +// preferences (the zero value when none are saved). +func (c *Config) ReviewRulesSettingsSnapshot() ReviewRulesSettings { + if c == nil { + return ReviewRulesSettings{} + } + reviewFeedbackMu.RLock() + defer reviewFeedbackMu.RUnlock() + if c.ReviewFeedback == nil { + return ReviewRulesSettings{} + } + return c.ReviewFeedback.Rules.clone() +} + +// SetReviewRulesSettings replaces the saved review-rule preferences. Values are +// stored as given (the dashboard validates them first); an all-empty value +// removes the block, so hive.yaml only carries what the owner chose. It +// returns the previous value, for a rollback when the file cannot be written. +func (c *Config) SetReviewRulesSettings(s ReviewRulesSettings) ReviewRulesSettings { + reviewFeedbackMu.Lock() + defer reviewFeedbackMu.Unlock() + var prev ReviewRulesSettings + if c.ReviewFeedback != nil { + prev = c.ReviewFeedback.Rules.clone() + } + s = s.clone() + if s.Enabled == nil && len(s.TrustedAssociations) == 0 && len(s.ExtraPhrases) == 0 && len(s.DisabledSignals) == 0 { + c.ReviewFeedback = nil + return prev + } + c.ReviewFeedback = &ReviewFeedbackConfig{Rules: s} + return prev +} + +func (s ReviewRulesSettings) clone() ReviewRulesSettings { + out := ReviewRulesSettings{ + TrustedAssociations: append([]string(nil), s.TrustedAssociations...), + ExtraPhrases: append([]string(nil), s.ExtraPhrases...), + DisabledSignals: append([]string(nil), s.DisabledSignals...), + } + if s.Enabled != nil { + v := *s.Enabled + out.Enabled = &v + } + return out +} diff --git a/src/pkg/config/review_feedback_test.go b/src/pkg/config/review_feedback_test.go new file mode 100644 index 0000000000..0354c95e97 --- /dev/null +++ b/src/pkg/config/review_feedback_test.go @@ -0,0 +1,72 @@ +package config + +import ( + "strings" + "testing" + + "gopkg.in/yaml.v3" +) + +func TestReviewRulesSettingsRoundTrip(t *testing.T) { + var c Config + if got := c.ReviewRulesSettingsSnapshot(); got.Enabled != nil || len(got.TrustedAssociations) != 0 { + t.Fatalf("zero config: %+v", got) + } + var nilCfg *Config + if got := nilCfg.ReviewRulesSettingsSnapshot(); got.Enabled != nil { + t.Fatal("nil config") + } + off := false + prev := c.SetReviewRulesSettings(ReviewRulesSettings{Enabled: &off, TrustedAssociations: []string{"OWNER"}, ExtraPhrases: []string{"worth considering"}, DisabledSignals: []string{"never"}}) + if prev.Enabled != nil { + t.Fatalf("prev = %+v", prev) + } + got := c.ReviewRulesSettingsSnapshot() + if got.Enabled == nil || *got.Enabled || got.TrustedAssociations[0] != "OWNER" || got.ExtraPhrases[0] != "worth considering" || got.DisabledSignals[0] != "never" { + t.Fatalf("snapshot = %+v", got) + } + got.TrustedAssociations[0] = "NONE" + *got.Enabled = true + if again := c.ReviewRulesSettingsSnapshot(); again.TrustedAssociations[0] != "OWNER" || *again.Enabled { + t.Fatal("the snapshot is a copy") + } + + out, err := yaml.Marshal(&c) + if err != nil { + t.Fatal(err) + } + for _, want := range []string{"review_feedback:", "rules:", "enabled: false", "trusted_associations:", "extra_phrases:", "disabled_signals:"} { + if !strings.Contains(string(out), want) { + t.Errorf("yaml missing %q:\n%s", want, out) + } + } + var back Config + if err := yaml.Unmarshal(out, &back); err != nil { + t.Fatal(err) + } + if b := back.ReviewRulesSettingsSnapshot(); b.Enabled == nil || *b.Enabled || len(b.ExtraPhrases) != 1 { + t.Fatalf("reparsed = %+v", b) + } + + if prev := c.SetReviewRulesSettings(ReviewRulesSettings{}); prev.Enabled == nil { + t.Fatalf("prev = %+v", prev) + } + if c.ReviewFeedback != nil { + t.Fatal("an all-default value removes the block") + } + out, _ = yaml.Marshal(&c) + if strings.Contains(string(out), "review_feedback") { + t.Fatalf("yaml still carries the block:\n%s", out) + } +} + +func TestIsReviewAssociation(t *testing.T) { + for _, a := range []string{"owner", " MEMBER ", "NONE", "FIRST_TIMER"} { + if !IsReviewAssociation(a) { + t.Errorf("%q should be known", a) + } + } + if IsReviewAssociation("ADMIN") || IsReviewAssociation("") { + t.Fatal("unknown association accepted") + } +} diff --git a/src/pkg/config/review_feedback_vocab.go b/src/pkg/config/review_feedback_vocab.go new file mode 100644 index 0000000000..0cf61a6220 --- /dev/null +++ b/src/pkg/config/review_feedback_vocab.go @@ -0,0 +1,38 @@ +package config + +import "github.com/hivecommons/hive/pkg/reviewrules" + +// The review-rule vocabulary the Settings card needs, re-exported from the +// stdlib-only pkg/reviewrules leaf so the dashboard validates against the same +// table the sweep classifies with without importing another package +// (hivecommons/hive#19135). + +// ReviewRuleSignal is one built-in rule signal and its examples. +type ReviewRuleSignal = reviewrules.SignalInfo + +// Env vars and limits behind review_feedback.rules.*. +const ( + ReviewRulesEnabledEnvVar = reviewrules.DisableEnvVar + ReviewRulesTrustedEnvVar = reviewrules.TrustedAssociationsEnvVar + ReviewRulesExtraPhrasesEnvVar = reviewrules.ExtraPhrasesEnvVar + ReviewRulesDisabledSignalsEnvVar = reviewrules.DisabledSignalsEnvVar + ReviewRulesDefaultTrusted = reviewrules.DefaultTrustedAssociations + ReviewRulesMaxPhrases = reviewrules.MaxPhrases + ReviewRulesMaxPhraseRunes = reviewrules.MaxPhraseRunes +) + +// ReviewRuleSignals lists the built-in signals in table order. +func ReviewRuleSignals() []ReviewRuleSignal { return reviewrules.Signals() } + +// KnownReviewRuleSignal reports whether name is a built-in signal. +func KnownReviewRuleSignal(name string) bool { return reviewrules.KnownSignal(name) } + +// ValidateReviewRulePhrase says why an extra phrase is unusable, or "". +func ValidateReviewRulePhrase(p string) string { return reviewrules.ValidatePhrase(p) } + +// ReviewRulesEnvEnabled reports whether HIVE_REVIEW_FEEDBACK_RULES leaves +// capture on (the default). +func ReviewRulesEnvEnabled() bool { return reviewrules.Enabled() } + +// ParseReviewRulesList splits a comma-separated list into trimmed items. +func ParseReviewRulesList(list string) []string { return reviewrules.ParseList(list) } diff --git a/src/pkg/dashboard/api.go b/src/pkg/dashboard/api.go index 295a8ac3c0..f29ed08764 100644 --- a/src/pkg/dashboard/api.go +++ b/src/pkg/dashboard/api.go @@ -560,6 +560,9 @@ func (s *Server) RegisterAPI(deps *Dependencies) { // repos..parent_autoclose editor on the Repos tab (#19070, api_config_parent_autoclose.go). s.mux.HandleFunc("GET /api/config/repos/parent-autoclose", s.handleParentAutoCloseGet) s.mux.HandleFunc("PUT /api/config/repos/parent-autoclose", s.handleParentAutoClosePut) + // review_feedback.rules.* editor on the Features tab (#19135, api_config_review_rules.go). + s.mux.HandleFunc("GET /api/config/review-feedback/rules", s.handleReviewRulesGet) + s.mux.HandleFunc("PUT /api/config/review-feedback/rules", s.handleReviewRulesPut) // project.remote_write_identity on the same Settings section (#18516, api_config_remote_write_identity.go). s.mux.HandleFunc("PUT /api/config/reference-repos/write-identity", s.handleRemoteWriteIdentityPut) // The hive owner's GitHub identity for remote repos (#18197, diff --git a/src/pkg/dashboard/api_config_review_rules.go b/src/pkg/dashboard/api_config_review_rules.go new file mode 100644 index 0000000000..29a7613ed5 --- /dev/null +++ b/src/pkg/dashboard/api_config_review_rules.go @@ -0,0 +1,226 @@ +package dashboard + +import ( + "net/http" + "os" + "strings" + + "github.com/hivecommons/hive/pkg/config" +) + +// The reviewer-stated rules editor on the Settings Features tab +// (hivecommons/hive#19135). When a person reviewing one of the hive's own PRs +// states a rule or a source of truth, the review-feedback sweep records it in +// the review-rules knowledge channel (#19046). Which phrases count as a rule +// and whose rules are recorded at once are the owner's preferences: +// +// - review_feedback.rules.enabled (HIVE_REVIEW_FEEDBACK_RULES) +// - review_feedback.rules.trusted_associations[] (HIVE_REVIEW_FEEDBACK_RULE_TRUSTED_ASSOCIATIONS) +// - review_feedback.rules.extra_phrases[] (HIVE_REVIEW_FEEDBACK_RULE_EXTRA_PHRASES) +// - review_feedback.rules.disabled_signals[] (HIVE_REVIEW_FEEDBACK_RULE_DISABLED_SIGNALS) +// +// Both endpoints are OWNER-ONLY: the values change what every later agent run +// is told. A PUT is validated before anything changes, applies on the sweep's +// next pass without a restart, is audited, and is rolled back when the config +// file cannot be written. A saved value wins over its env var; clearing a +// field falls back to the env var, then to the default. + +// reviewRulesField is one preference: the saved value (nil when unsaved), the +// effective value, where it comes from and the built-in default. +type reviewRulesField[T any] struct { + Saved *T `json:"saved"` + Effective T `json:"effective"` + Source string `json:"source"` // "settings", "env" or "default" + Default T `json:"default"` + EnvVar string `json:"env_var"` + YAMLKey string `json:"yaml_key"` +} + +// reviewRulesResponse is the GET/PUT response body. +type reviewRulesResponse struct { + Enabled reviewRulesField[bool] `json:"enabled"` + TrustedAssociations reviewRulesField[[]string] `json:"trusted_associations"` + ExtraPhrases reviewRulesField[[]string] `json:"extra_phrases"` + DisabledSignals reviewRulesField[[]string] `json:"disabled_signals"` + // Associations are the values trusted_associations may hold. + Associations []string `json:"associations"` + // Signals are the built-in signals, with examples. + Signals []config.ReviewRuleSignal `json:"signals"` + // MaxPhrases bounds extra_phrases. + MaxPhrases int `json:"max_phrases"` +} + +func envList(name string) ([]string, bool) { + v := strings.TrimSpace(os.Getenv(name)) + if v == "" { + return nil, false + } + return config.ParseReviewRulesList(v), true +} + +func listField(saved []string, envVar, yamlKey string, def []string) reviewRulesField[[]string] { + f := reviewRulesField[[]string]{Default: def, EnvVar: envVar, YAMLKey: yamlKey, Effective: def, Source: "default"} + if f.Default == nil { + f.Default = []string{} + f.Effective = []string{} + } + if env, ok := envList(envVar); ok { + f.Effective, f.Source = env, "env" + } + if len(saved) > 0 { + s := append([]string(nil), saved...) + f.Saved, f.Effective, f.Source = &s, s, "settings" + } + return f +} + +func reviewRulesResponseFor(cfg *config.Config) reviewRulesResponse { + set := cfg.ReviewRulesSettingsSnapshot() + enabled := reviewRulesField[bool]{Default: true, Effective: config.ReviewRulesEnvEnabled(), Source: "default", + EnvVar: config.ReviewRulesEnabledEnvVar, YAMLKey: "review_feedback.rules.enabled"} + if strings.TrimSpace(os.Getenv(config.ReviewRulesEnabledEnvVar)) != "" { + enabled.Source = "env" + } + if set.Enabled != nil { + v := *set.Enabled + enabled.Saved, enabled.Effective, enabled.Source = &v, v, "settings" + } + return reviewRulesResponse{ + Enabled: enabled, + TrustedAssociations: listField(set.TrustedAssociations, config.ReviewRulesTrustedEnvVar, + "review_feedback.rules.trusted_associations", config.ParseReviewRulesList(config.ReviewRulesDefaultTrusted)), + ExtraPhrases: listField(set.ExtraPhrases, config.ReviewRulesExtraPhrasesEnvVar, "review_feedback.rules.extra_phrases", nil), + DisabledSignals: listField(set.DisabledSignals, config.ReviewRulesDisabledSignalsEnvVar, "review_feedback.rules.disabled_signals", nil), + Associations: append([]string(nil), config.ReviewAssociations...), + Signals: config.ReviewRuleSignals(), + MaxPhrases: config.ReviewRulesMaxPhrases, + } +} + +// reviewRulesPutBody is the PUT body. A field that is absent or null clears +// the saved value (back to the env var, then the default). +type reviewRulesPutBody struct { + Enabled *bool `json:"enabled"` + TrustedAssociations *[]string `json:"trusted_associations"` + ExtraPhrases *[]string `json:"extra_phrases"` + DisabledSignals *[]string `json:"disabled_signals"` +} + +// validateReviewRulesPut normalises the body into settings, or returns the +// first problem as a message for the owner. +func validateReviewRulesPut(body reviewRulesPutBody) (config.ReviewRulesSettings, string) { + var out config.ReviewRulesSettings + if body.Enabled != nil { + v := *body.Enabled + out.Enabled = &v + } + if body.TrustedAssociations != nil { + seen := map[string]bool{} + for _, a := range *body.TrustedAssociations { + a = strings.ToUpper(strings.TrimSpace(a)) + if a == "" || seen[a] { + continue + } + if !config.IsReviewAssociation(a) { + return out, "unknown association " + a + "; use one of " + strings.Join(config.ReviewAssociations, ", ") + } + seen[a] = true + out.TrustedAssociations = append(out.TrustedAssociations, a) + } + if len(*body.TrustedAssociations) > 0 && len(out.TrustedAssociations) == 0 { + return out, "trusted_associations needs at least one association, or leave it empty for the default" + } + } + if body.ExtraPhrases != nil { + seen := map[string]bool{} + for _, p := range *body.ExtraPhrases { + p = strings.Join(strings.Fields(p), " ") + if p == "" || seen[strings.ToLower(p)] { + continue + } + if why := config.ValidateReviewRulePhrase(p); why != "" { + return out, "phrase \"" + p + "\" " + why + } + seen[strings.ToLower(p)] = true + out.ExtraPhrases = append(out.ExtraPhrases, p) + } + if len(out.ExtraPhrases) > config.ReviewRulesMaxPhrases { + return out, "at most 20 extra phrases" + } + } + if body.DisabledSignals != nil { + seen := map[string]bool{} + for _, n := range *body.DisabledSignals { + n = strings.ToLower(strings.TrimSpace(n)) + if n == "" || seen[n] { + continue + } + if !config.KnownReviewRuleSignal(n) { + return out, "unknown signal " + n + } + seen[n] = true + out.DisabledSignals = append(out.DisabledSignals, n) + } + } + return out, "" +} + +// handleReviewRulesGet returns the reviewer-rule capture preferences. +func (s *Server) handleReviewRulesGet(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + if s.deps == nil || s.deps.Config == nil { + jsonError(w, "config unavailable", http.StatusServiceUnavailable) + return + } + jsonResponse(w, reviewRulesResponseFor(s.deps.Config)) +} + +// handleReviewRulesPut replaces the saved preferences. Body: +// {"enabled": true, "trusted_associations": ["OWNER"], "extra_phrases": ["..."], +// "disabled_signals": ["never"]}; an absent or null field clears that saved +// value. +func (s *Server) handleReviewRulesPut(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + if s.deps == nil || s.deps.Config == nil { + jsonError(w, "config unavailable", http.StatusServiceUnavailable) + return + } + var body reviewRulesPutBody + if err := decodeBody(r, &body); err != nil { + jsonError(w, "invalid body", http.StatusBadRequest) + return + } + next, problem := validateReviewRulesPut(body) + if problem != "" { + jsonError(w, problem, http.StatusBadRequest) + return + } + cfg := s.deps.Config + prev := cfg.SetReviewRulesSettings(next) + if err := s.saveConfig(); err != nil { + cfg.SetReviewRulesSettings(prev) + if s.logger != nil { + s.logger.Error("failed to persist config after review-rules update", "error", err) + } + jsonError(w, "failed to save config; reviewer-rule settings unchanged", http.StatusInternalServerError) + return + } + resp := reviewRulesResponseFor(cfg) + s.auditFromRequest(r, "config_review_feedback_rules", auditDetail( + "section", "features", + "enabled", boolString(resp.Enabled.Effective), + "trusted_associations", strings.Join(resp.TrustedAssociations.Effective, ","), + "extra_phrases", strings.Join(resp.ExtraPhrases.Effective, " | "), + "disabled_signals", strings.Join(resp.DisabledSignals.Effective, ","), + ), "") + if s.logger != nil { + s.logger.Info("reviewer-rule capture settings updated via runtime settings", + "enabled", resp.Enabled.Effective, "trusted_associations", resp.TrustedAssociations.Effective, + "extra_phrases", len(resp.ExtraPhrases.Effective), "disabled_signals", resp.DisabledSignals.Effective) + } + jsonResponse(w, resp) +} diff --git a/src/pkg/dashboard/api_config_review_rules_test.go b/src/pkg/dashboard/api_config_review_rules_test.go new file mode 100644 index 0000000000..2c460d3831 --- /dev/null +++ b/src/pkg/dashboard/api_config_review_rules_test.go @@ -0,0 +1,146 @@ +package dashboard + +import ( + "encoding/json" + "net/http" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" +) + +// hivecommons/hive#19135: the owner-only review_feedback.rules.* editor. + +const reviewRulesPath = "/api/config/review-feedback/rules" + +func decodeReviewRules(t *testing.T, body []byte) reviewRulesResponse { + t.Helper() + var got reviewRulesResponse + if err := json.Unmarshal(body, &got); err != nil { + t.Fatalf("decode: %v (%s)", err, body) + } + return got +} + +func clearReviewRulesEnv(t *testing.T) { + t.Helper() + for _, v := range []string{config.ReviewRulesEnabledEnvVar, config.ReviewRulesTrustedEnvVar, config.ReviewRulesExtraPhrasesEnvVar, config.ReviewRulesDisabledSignalsEnvVar} { + t.Setenv(v, "") + } +} + +func TestReviewRules_OwnerOnly(t *testing.T) { + s := covApiServer(t) + if rec := doGetNoRole(s, reviewRulesPath); rec.Code != http.StatusForbidden { + t.Fatalf("non-owner GET: expected 403, got %d", rec.Code) + } + if rec := doPutNoRole(s, reviewRulesPath, `{"enabled":false}`); rec.Code != http.StatusForbidden { + t.Fatalf("non-owner PUT: expected 403, got %d", rec.Code) + } + if s.deps.Config.ReviewFeedback != nil { + t.Fatal("a refused PUT changed the settings") + } +} + +func TestReviewRules_GetShowsDefaultsAndEnv(t *testing.T) { + clearReviewRulesEnv(t) + s := covApiServer(t) + rec := doOwnerGet(s, reviewRulesPath) + if rec.Code != http.StatusOK { + t.Fatalf("GET: %d %s", rec.Code, rec.Body.String()) + } + got := decodeReviewRules(t, rec.Body.Bytes()) + if !got.Enabled.Effective || got.Enabled.Source != "default" || got.Enabled.Saved != nil { + t.Fatalf("enabled = %+v", got.Enabled) + } + if strings.Join(got.TrustedAssociations.Effective, ",") != config.ReviewRulesDefaultTrusted || got.TrustedAssociations.Source != "default" { + t.Fatalf("trusted = %+v", got.TrustedAssociations) + } + if got.ExtraPhrases.Effective == nil || len(got.ExtraPhrases.Effective) != 0 || got.ExtraPhrases.YAMLKey != "review_feedback.rules.extra_phrases" { + t.Fatalf("phrases = %+v", got.ExtraPhrases) + } + if len(got.Signals) != len(config.ReviewRuleSignals()) || len(got.Associations) == 0 || got.MaxPhrases != config.ReviewRulesMaxPhrases { + t.Fatalf("vocabulary = %+v", got) + } + + t.Setenv(config.ReviewRulesTrustedEnvVar, "OWNER") + t.Setenv(config.ReviewRulesEnabledEnvVar, "off") + got = decodeReviewRules(t, doOwnerGet(s, reviewRulesPath).Body.Bytes()) + if got.TrustedAssociations.Source != "env" || strings.Join(got.TrustedAssociations.Effective, ",") != "OWNER" || got.Enabled.Effective || got.Enabled.Source != "env" { + t.Fatalf("env: %+v %+v", got.TrustedAssociations, got.Enabled) + } +} + +func TestReviewRules_PutAppliesAndAudits(t *testing.T) { + clearReviewRulesEnv(t) + s := covApiServer(t) + cfg := s.deps.Config + rec := doPut(s, reviewRulesPath, map[string]any{ + "enabled": false, + "trusted_associations": []string{"owner", "MEMBER", "member", "CONTRIBUTOR"}, + "extra_phrases": []string{" worth considering ", "Worth considering", "house rule"}, + "disabled_signals": []string{"Never"}, + }) + if rec.Code != http.StatusOK { + t.Fatalf("PUT: %d %s", rec.Code, rec.Body.String()) + } + set := cfg.ReviewRulesSettingsSnapshot() + if set.Enabled == nil || *set.Enabled || strings.Join(set.TrustedAssociations, ",") != "OWNER,MEMBER,CONTRIBUTOR" || + strings.Join(set.ExtraPhrases, "|") != "worth considering|house rule" || strings.Join(set.DisabledSignals, ",") != "never" { + t.Fatalf("saved = %+v", set) + } + got := decodeReviewRules(t, rec.Body.Bytes()) + if got.Enabled.Source != "settings" || got.Enabled.Effective || got.ExtraPhrases.Source != "settings" { + t.Fatalf("response = %+v", got) + } + if s.audit != nil { + found := false + for _, entry := range s.audit.Recent(50) { + if entry.Action == "config_review_feedback_rules" { + found = true + } + } + if !found { + t.Error("missing config_review_feedback_rules audit") + } + } + + // An empty body clears every saved value: back to the defaults. + if rec := doPut(s, reviewRulesPath, map[string]any{}); rec.Code != http.StatusOK { + t.Fatalf("PUT clear: %d %s", rec.Code, rec.Body.String()) + } + if cfg.ReviewFeedback != nil { + t.Fatalf("clear left %+v", cfg.ReviewFeedback) + } +} + +func TestReviewRules_PutValidation(t *testing.T) { + clearReviewRulesEnv(t) + s := covApiServer(t) + many := make([]string, config.ReviewRulesMaxPhrases+1) + for i := range many { + many[i] = "phrase number " + strings.Repeat("x", i+1) + } + cases := []struct { + name string + body map[string]any + }{ + {"unknown association", map[string]any{"trusted_associations": []string{"ADMIN"}}}, + {"only blanks", map[string]any{"trusted_associations": []string{" "}}}, + {"short phrase", map[string]any{"extra_phrases": []string{"ab"}}}, + {"long phrase", map[string]any{"extra_phrases": []string{strings.Repeat("a", config.ReviewRulesMaxPhraseRunes+1)}}}, + {"too many phrases", map[string]any{"extra_phrases": many}}, + {"unknown signal", map[string]any{"disabled_signals": []string{"sometimes"}}}, + } + for _, tc := range cases { + if rec := doPut(s, reviewRulesPath, tc.body); rec.Code != http.StatusBadRequest { + t.Errorf("%s: code %d, want 400 (%s)", tc.name, rec.Code, rec.Body.String()) + } + } + if rec := doPutNoRole(s, reviewRulesPath, `{`); rec.Code != http.StatusForbidden { + t.Errorf("malformed non-owner: %d", rec.Code) + } + if s.deps.Config.ReviewFeedback != nil { + t.Fatalf("a refused PUT stored %+v", s.deps.Config.ReviewFeedback) + } +} diff --git a/src/pkg/dashboard/audit.go b/src/pkg/dashboard/audit.go index d6942b6b36..883059bb8b 100644 --- a/src/pkg/dashboard/audit.go +++ b/src/pkg/dashboard/audit.go @@ -109,6 +109,7 @@ var auditSensitiveActions = map[string]bool{ "config_repo_parent_autoclose": true, "config_remote_write_identity": true, "config_review": true, + "config_review_feedback_rules": true, "config_write_surface": true, "contributor-tier-changed": true, "copilot_auth_logout": true, diff --git a/src/pkg/dashboard/static-src/js/config-features.js b/src/pkg/dashboard/static-src/js/config-features.js index 7586a67611..a43ece5e45 100644 --- a/src/pkg/dashboard/static-src/js/config-features.js +++ b/src/pkg/dashboard/static-src/js/config-features.js @@ -279,6 +279,8 @@ `; }).join(''); setTimeout(() => { if (rotationOn) loadRotationHeadroom(); }, 0); + /* Reviewer-stated rules (#19135): painted from their own owner-only endpoint. */ + setTimeout(() => { if (typeof loadReviewRulesSettings === 'function') loadReviewRulesSettings(); }, 0); // Status line: distinguish ON+running from ON+not-configured from OFF. let trajStatus, trajStatusColor; if (!trajOn) { trajStatus = 'Off'; trajStatusColor = 'var(--muted)'; } @@ -626,6 +628,10 @@
+
+
Reviewer-stated rules ${yamlHint('review_feedback.rules')} ${settingHelpMark('settings', 'features', 'Reviewer-stated rules', `When a person reviewing one of the hive's own PRs states a rule or a source of truth, the hive records it in its knowledge (the review-rules channel), replies on the PR with the rule id, and gives it to the authoring agent on its next run. Choose which phrases count and whose rules are recorded at once; others are queued for you.`)}
+
Loading…
+
Merge Recommendations ${settingHelpMark('settings', 'features', 'Merge Recommendations', `A digest of what is worth merging next, written into one issue per repository and rewritten in place each cycle. It is separate from the review gate above: the gate decides whether a PR may merge, while this only reports what already can. It never merges, approves, closes or labels anything.`)}
diff --git a/src/pkg/dashboard/static-src/js/config-review-rules.js b/src/pkg/dashboard/static-src/js/config-review-rules.js new file mode 100644 index 0000000000..c68616b57a --- /dev/null +++ b/src/pkg/dashboard/static-src/js/config-review-rules.js @@ -0,0 +1,210 @@ + /* Reviewer-stated rules editor (#19135): review_feedback.rules.enabled, + review_feedback.rules.trusted_associations, + review_feedback.rules.extra_phrases and + review_feedback.rules.disabled_signals, loaded from the owner-only + /api/config/review-feedback/rules endpoint and saved back to it. + Rendered with DOM nodes and textContent only, so a phrase or a signal + name is never parsed as markup. The server validates and applies the + values on the sweep's next pass without a restart; its error message is + shown as-is and nothing is saved on an error. */ + const REVIEW_RULES_HOST_ID = 'cfg-review-rules-host'; + + function reviewRulesNode(tag, className, text) { + const node = document.createElement(tag); + if (className) node.className = className; + if (text !== undefined) node.textContent = text; + return node; + } + + async function loadReviewRulesSettings() { + let host = null; + try { + const r = await fetch('/api/config/review-feedback/rules'); + host = document.getElementById(REVIEW_RULES_HOST_ID); + if (!host) return; + if (r.status === 403) { + host.textContent = ''; + host.appendChild(reviewRulesNode('div', 'fs-sm text-muted', 'Only the hive owner can view and edit reviewer-stated rule settings.')); + return; + } + if (!r.ok) throw new Error('HTTP ' + r.status); + renderReviewRulesPanel(host, await r.json()); + } catch (e) { + host = host || document.getElementById(REVIEW_RULES_HOST_ID); + if (!host) return; + host.textContent = ''; + host.appendChild(reviewRulesNode('div', 'fs-sm text-danger', 'Failed to load reviewer-stated rule settings: ' + e.message)); + } + } + + /* reviewRulesSourceText says where an effective value comes from. */ + function reviewRulesSourceText(field) { + if (!field) return ''; + if (field.source === 'settings') return 'saved here'; + if (field.source === 'env') return 'from ' + (field.env_var || 'the environment'); + return 'default'; + } + + /* renderReviewRulesPanel paints the four preferences, each with a one-line + explanation, its default and where the current value comes from. A + blank list falls back to the env var, then the default. */ + function renderReviewRulesPanel(host, data) { + if (!host) return; + data = data || {}; + const enabled = data.enabled || {}; + const trusted = data.trusted_associations || {}; + const phrases = data.extra_phrases || {}; + const disabled = data.disabled_signals || {}; + const associations = Array.isArray(data.associations) ? data.associations : []; + const signals = Array.isArray(data.signals) ? data.signals : []; + const list = v => (Array.isArray(v) ? v : []); + const state = { + enabled: enabled.saved === null || enabled.saved === undefined ? '' : (enabled.saved ? 'on' : 'off'), + trusted: new Set(list(trusted.saved === null || trusted.saved === undefined ? trusted.effective : trusted.saved)), + trustedSaved: Array.isArray(trusted.saved), + phrases: list(phrases.saved).join('\n'), + disabled: new Set(list(disabled.saved === null || disabled.saved === undefined ? disabled.effective : disabled.saved)), + disabledSaved: Array.isArray(disabled.saved), + }; + + host.textContent = ''; + host.appendChild(reviewRulesNode('p', 'config-help', + 'When a person reviewing one of the hive\'s own PRs states a rule or a source of truth ("X is the source of truth", "in future assessments, check Y"), ' + + 'the hive records it in its knowledge, replies "Recorded as rule R-n" on the PR, and gives it to the authoring agent on its next run. ' + + 'Retract a rule with hivectl knowledge state rule-r-N deprecated. Saving applies on the next sweep pass without a restart.')); + + const statusEl = reviewRulesNode('div', 'fs-sm'); + const setStatus = (msg, cls) => { statusEl.textContent = msg; statusEl.className = 'fs-sm ' + (cls || 'text-muted'); }; + const saveBtn = reviewRulesNode('button', 'hv-btn btn-primary btn-sm', 'Save reviewer-rule settings'); + const dirty = () => { saveBtn.disabled = false; setStatus(''); }; + + const yamlLine = key => { + const hint = reviewRulesNode('span', 'settings-yaml-hint', 'YAML '); + hint.appendChild(reviewRulesNode('code', '', key)); + return hint; + }; + const field = (label, help, yamlKey, now) => { + const box = reviewRulesNode('div', 'config-field mt-3'); + const l = reviewRulesNode('label', '', label + ' '); + l.appendChild(yamlLine(yamlKey)); + box.appendChild(l); + box.appendChild(reviewRulesNode('div', 'config-help', help)); + box.appendChild(reviewRulesNode('div', 'rt-inherit', now)); + host.appendChild(box); + return box; + }; + + /* Capture on/off */ + const enBox = field('Capture reviewer-stated rules', + 'On: rules reviewers state on the hive\'s PRs are recorded. Off: they are not recorded; the sweep still routes the feedback. Default: on.', + 'review_feedback.rules.enabled', + 'now: ' + (enabled.effective === false ? 'off' : 'on') + ' (' + reviewRulesSourceText(enabled) + ')'); + const enSelect = document.createElement('select'); + enSelect.title = 'Capture reviewer-stated rules'; + [['', 'Use default (' + (enabled.env_var || 'env') + ', else on)'], ['on', 'On'], ['off', 'Off']].forEach(([v, text]) => { + const opt = document.createElement('option'); + opt.value = v; + opt.textContent = text; + opt.selected = v === state.enabled; + enSelect.appendChild(opt); + }); + enSelect.addEventListener('change', () => { state.enabled = enSelect.value; dirty(); }); + enBox.appendChild(enSelect); + + /* Trusted associations */ + const trBox = field('Recorded at once for', + 'GitHub author associations whose rules are recorded at once; anyone else\'s rule is queued for you to confirm. ' + + 'An org member whose membership is private shows as CONTRIBUTOR. Default: ' + list(trusted.default).join(', ') + '.', + 'review_feedback.rules.trusted_associations[]', + 'now: ' + list(trusted.effective).join(', ') + ' (' + reviewRulesSourceText(trusted) + ')'); + const trRow = reviewRulesNode('div', 'config-list'); + associations.forEach(a => { + const lab = reviewRulesNode('label', 'config-list-item'); + const cb = document.createElement('input'); + cb.type = 'checkbox'; + cb.checked = state.trusted.has(a); + cb.addEventListener('change', () => { + if (cb.checked) state.trusted.add(a); else state.trusted.delete(a); + state.trustedSaved = true; + dirty(); + }); + lab.appendChild(cb); + lab.appendChild(reviewRulesNode('code', '', a)); + trRow.appendChild(lab); + }); + trBox.appendChild(trRow); + const trReset = reviewRulesNode('button', 'hv-btn btn-secondary btn-sm', 'Use default'); + trReset.addEventListener('click', () => { + state.trustedSaved = false; + state.trusted = new Set(list(trusted.default)); + trRow.querySelectorAll('input[type=checkbox]').forEach((cb, i) => { cb.checked = state.trusted.has(associations[i]); }); + dirty(); + }); + trBox.appendChild(trReset); + + /* Extra phrases */ + const phBox = field('Extra phrases that mark a rule', + 'One plain phrase per line, matched case-insensitively as whole words, on top of the built-in signals below (for example: worth considering). ' + + 'Quoted text and questions never count. At most ' + (data.max_phrases || 20) + '. Default: none.', + 'review_feedback.rules.extra_phrases[]', + 'now: ' + (list(phrases.effective).join(' | ') || 'none') + ' (' + reviewRulesSourceText(phrases) + ')'); + const ta = document.createElement('textarea'); + ta.rows = 3; + ta.value = state.phrases; + ta.placeholder = 'worth considering'; + ta.addEventListener('input', () => { state.phrases = ta.value; dirty(); }); + phBox.appendChild(ta); + + /* Built-in signals */ + const sgBox = field('Built-in signals', + 'Uncheck a signal to stop it marking a comment as a rule. Default: all on.', + 'review_feedback.rules.disabled_signals[]', + 'now off: ' + (list(disabled.effective).join(', ') || 'none') + ' (' + reviewRulesSourceText(disabled) + ')'); + const sgRow = reviewRulesNode('div', 'config-list'); + signals.forEach(sg => { + const lab = reviewRulesNode('label', 'config-list-item'); + const cb = document.createElement('input'); + cb.type = 'checkbox'; + cb.checked = !state.disabled.has(sg.name); + cb.addEventListener('change', () => { + if (cb.checked) state.disabled.delete(sg.name); else state.disabled.add(sg.name); + state.disabledSaved = true; + dirty(); + }); + lab.appendChild(cb); + lab.appendChild(reviewRulesNode('code', '', sg.name)); + lab.appendChild(reviewRulesNode('span', 'text-muted fs-sm', ' ' + (sg.examples || ''))); + sgRow.appendChild(lab); + }); + sgBox.appendChild(sgRow); + + const actions = reviewRulesNode('div', 'config-list-add'); + actions.appendChild(saveBtn); + actions.appendChild(statusEl); + host.appendChild(actions); + saveBtn.disabled = true; + + saveBtn.addEventListener('click', async () => { + const body = {}; + if (state.enabled) body.enabled = state.enabled === 'on'; + if (state.trustedSaved) body.trusted_associations = associations.filter(a => state.trusted.has(a)); + const ph = state.phrases.split('\n').map(s => s.trim()).filter(Boolean); + if (ph.length) body.extra_phrases = ph; + if (state.disabledSaved && state.disabled.size) body.disabled_signals = Array.from(state.disabled); + saveBtn.disabled = true; + setStatus('Saving…'); + try { + const res = await fetch('/api/config/review-feedback/rules', { + method: 'PUT', + headers: _inceptionAuthHeaders(), + body: JSON.stringify(body), + }); + if (!res.ok) throw new Error(await saveErrorMessage(res)); + renderReviewRulesPanel(host, await res.json()); + showToast('Reviewer-rule settings saved', 'success'); + } catch (e) { + saveBtn.disabled = false; + setStatus(e.message, 'text-danger'); + } + }); + } diff --git a/src/pkg/dashboard/static-src/manifest.txt b/src/pkg/dashboard/static-src/manifest.txt index 1eb9156157..ab348eb857 100644 --- a/src/pkg/dashboard/static-src/manifest.txt +++ b/src/pkg/dashboard/static-src/manifest.txt @@ -176,6 +176,7 @@ js/config-hub.js js/config-agent.js js/config-governor.js js/config-parent-autoclose.js +js/config-review-rules.js js/config-workflows.js js/config-workflows-handoff.js js/config-workflows-library.js diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 7334f6e6e3..3387db7636 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -73784,6 +73784,216 @@

Agent Watchdog

syncSave(); }); } + /* Reviewer-stated rules editor (#19135): review_feedback.rules.enabled, + review_feedback.rules.trusted_associations, + review_feedback.rules.extra_phrases and + review_feedback.rules.disabled_signals, loaded from the owner-only + /api/config/review-feedback/rules endpoint and saved back to it. + Rendered with DOM nodes and textContent only, so a phrase or a signal + name is never parsed as markup. The server validates and applies the + values on the sweep's next pass without a restart; its error message is + shown as-is and nothing is saved on an error. */ + const REVIEW_RULES_HOST_ID = 'cfg-review-rules-host'; + + function reviewRulesNode(tag, className, text) { + const node = document.createElement(tag); + if (className) node.className = className; + if (text !== undefined) node.textContent = text; + return node; + } + + async function loadReviewRulesSettings() { + let host = null; + try { + const r = await fetch('/api/config/review-feedback/rules'); + host = document.getElementById(REVIEW_RULES_HOST_ID); + if (!host) return; + if (r.status === 403) { + host.textContent = ''; + host.appendChild(reviewRulesNode('div', 'fs-sm text-muted', 'Only the hive owner can view and edit reviewer-stated rule settings.')); + return; + } + if (!r.ok) throw new Error('HTTP ' + r.status); + renderReviewRulesPanel(host, await r.json()); + } catch (e) { + host = host || document.getElementById(REVIEW_RULES_HOST_ID); + if (!host) return; + host.textContent = ''; + host.appendChild(reviewRulesNode('div', 'fs-sm text-danger', 'Failed to load reviewer-stated rule settings: ' + e.message)); + } + } + + /* reviewRulesSourceText says where an effective value comes from. */ + function reviewRulesSourceText(field) { + if (!field) return ''; + if (field.source === 'settings') return 'saved here'; + if (field.source === 'env') return 'from ' + (field.env_var || 'the environment'); + return 'default'; + } + + /* renderReviewRulesPanel paints the four preferences, each with a one-line + explanation, its default and where the current value comes from. A + blank list falls back to the env var, then the default. */ + function renderReviewRulesPanel(host, data) { + if (!host) return; + data = data || {}; + const enabled = data.enabled || {}; + const trusted = data.trusted_associations || {}; + const phrases = data.extra_phrases || {}; + const disabled = data.disabled_signals || {}; + const associations = Array.isArray(data.associations) ? data.associations : []; + const signals = Array.isArray(data.signals) ? data.signals : []; + const list = v => (Array.isArray(v) ? v : []); + const state = { + enabled: enabled.saved === null || enabled.saved === undefined ? '' : (enabled.saved ? 'on' : 'off'), + trusted: new Set(list(trusted.saved === null || trusted.saved === undefined ? trusted.effective : trusted.saved)), + trustedSaved: Array.isArray(trusted.saved), + phrases: list(phrases.saved).join('\n'), + disabled: new Set(list(disabled.saved === null || disabled.saved === undefined ? disabled.effective : disabled.saved)), + disabledSaved: Array.isArray(disabled.saved), + }; + + host.textContent = ''; + host.appendChild(reviewRulesNode('p', 'config-help', + 'When a person reviewing one of the hive\'s own PRs states a rule or a source of truth ("X is the source of truth", "in future assessments, check Y"), ' + + 'the hive records it in its knowledge, replies "Recorded as rule R-n" on the PR, and gives it to the authoring agent on its next run. ' + + 'Retract a rule with hivectl knowledge state rule-r-N deprecated. Saving applies on the next sweep pass without a restart.')); + + const statusEl = reviewRulesNode('div', 'fs-sm'); + const setStatus = (msg, cls) => { statusEl.textContent = msg; statusEl.className = 'fs-sm ' + (cls || 'text-muted'); }; + const saveBtn = reviewRulesNode('button', 'hv-btn btn-primary btn-sm', 'Save reviewer-rule settings'); + const dirty = () => { saveBtn.disabled = false; setStatus(''); }; + + const yamlLine = key => { + const hint = reviewRulesNode('span', 'settings-yaml-hint', 'YAML '); + hint.appendChild(reviewRulesNode('code', '', key)); + return hint; + }; + const field = (label, help, yamlKey, now) => { + const box = reviewRulesNode('div', 'config-field mt-3'); + const l = reviewRulesNode('label', '', label + ' '); + l.appendChild(yamlLine(yamlKey)); + box.appendChild(l); + box.appendChild(reviewRulesNode('div', 'config-help', help)); + box.appendChild(reviewRulesNode('div', 'rt-inherit', now)); + host.appendChild(box); + return box; + }; + + /* Capture on/off */ + const enBox = field('Capture reviewer-stated rules', + 'On: rules reviewers state on the hive\'s PRs are recorded. Off: they are not recorded; the sweep still routes the feedback. Default: on.', + 'review_feedback.rules.enabled', + 'now: ' + (enabled.effective === false ? 'off' : 'on') + ' (' + reviewRulesSourceText(enabled) + ')'); + const enSelect = document.createElement('select'); + enSelect.title = 'Capture reviewer-stated rules'; + [['', 'Use default (' + (enabled.env_var || 'env') + ', else on)'], ['on', 'On'], ['off', 'Off']].forEach(([v, text]) => { + const opt = document.createElement('option'); + opt.value = v; + opt.textContent = text; + opt.selected = v === state.enabled; + enSelect.appendChild(opt); + }); + enSelect.addEventListener('change', () => { state.enabled = enSelect.value; dirty(); }); + enBox.appendChild(enSelect); + + /* Trusted associations */ + const trBox = field('Recorded at once for', + 'GitHub author associations whose rules are recorded at once; anyone else\'s rule is queued for you to confirm. ' + + 'An org member whose membership is private shows as CONTRIBUTOR. Default: ' + list(trusted.default).join(', ') + '.', + 'review_feedback.rules.trusted_associations[]', + 'now: ' + list(trusted.effective).join(', ') + ' (' + reviewRulesSourceText(trusted) + ')'); + const trRow = reviewRulesNode('div', 'config-list'); + associations.forEach(a => { + const lab = reviewRulesNode('label', 'config-list-item'); + const cb = document.createElement('input'); + cb.type = 'checkbox'; + cb.checked = state.trusted.has(a); + cb.addEventListener('change', () => { + if (cb.checked) state.trusted.add(a); else state.trusted.delete(a); + state.trustedSaved = true; + dirty(); + }); + lab.appendChild(cb); + lab.appendChild(reviewRulesNode('code', '', a)); + trRow.appendChild(lab); + }); + trBox.appendChild(trRow); + const trReset = reviewRulesNode('button', 'hv-btn btn-secondary btn-sm', 'Use default'); + trReset.addEventListener('click', () => { + state.trustedSaved = false; + state.trusted = new Set(list(trusted.default)); + trRow.querySelectorAll('input[type=checkbox]').forEach((cb, i) => { cb.checked = state.trusted.has(associations[i]); }); + dirty(); + }); + trBox.appendChild(trReset); + + /* Extra phrases */ + const phBox = field('Extra phrases that mark a rule', + 'One plain phrase per line, matched case-insensitively as whole words, on top of the built-in signals below (for example: worth considering). ' + + 'Quoted text and questions never count. At most ' + (data.max_phrases || 20) + '. Default: none.', + 'review_feedback.rules.extra_phrases[]', + 'now: ' + (list(phrases.effective).join(' | ') || 'none') + ' (' + reviewRulesSourceText(phrases) + ')'); + const ta = document.createElement('textarea'); + ta.rows = 3; + ta.value = state.phrases; + ta.placeholder = 'worth considering'; + ta.addEventListener('input', () => { state.phrases = ta.value; dirty(); }); + phBox.appendChild(ta); + + /* Built-in signals */ + const sgBox = field('Built-in signals', + 'Uncheck a signal to stop it marking a comment as a rule. Default: all on.', + 'review_feedback.rules.disabled_signals[]', + 'now off: ' + (list(disabled.effective).join(', ') || 'none') + ' (' + reviewRulesSourceText(disabled) + ')'); + const sgRow = reviewRulesNode('div', 'config-list'); + signals.forEach(sg => { + const lab = reviewRulesNode('label', 'config-list-item'); + const cb = document.createElement('input'); + cb.type = 'checkbox'; + cb.checked = !state.disabled.has(sg.name); + cb.addEventListener('change', () => { + if (cb.checked) state.disabled.delete(sg.name); else state.disabled.add(sg.name); + state.disabledSaved = true; + dirty(); + }); + lab.appendChild(cb); + lab.appendChild(reviewRulesNode('code', '', sg.name)); + lab.appendChild(reviewRulesNode('span', 'text-muted fs-sm', ' ' + (sg.examples || ''))); + sgRow.appendChild(lab); + }); + sgBox.appendChild(sgRow); + + const actions = reviewRulesNode('div', 'config-list-add'); + actions.appendChild(saveBtn); + actions.appendChild(statusEl); + host.appendChild(actions); + saveBtn.disabled = true; + + saveBtn.addEventListener('click', async () => { + const body = {}; + if (state.enabled) body.enabled = state.enabled === 'on'; + if (state.trustedSaved) body.trusted_associations = associations.filter(a => state.trusted.has(a)); + const ph = state.phrases.split('\n').map(s => s.trim()).filter(Boolean); + if (ph.length) body.extra_phrases = ph; + if (state.disabledSaved && state.disabled.size) body.disabled_signals = Array.from(state.disabled); + saveBtn.disabled = true; + setStatus('Saving…'); + try { + const res = await fetch('/api/config/review-feedback/rules', { + method: 'PUT', + headers: _inceptionAuthHeaders(), + body: JSON.stringify(body), + }); + if (!res.ok) throw new Error(await saveErrorMessage(res)); + renderReviewRulesPanel(host, await res.json()); + showToast('Reviewer-rule settings saved', 'success'); + } catch (e) { + saveBtn.disabled = false; + setStatus(e.message, 'text-danger'); + } + }); + } // Workflow-model bindings (hivecommons/hive#17620, RFC phase 2). // // Each repo row on Settings → Repos carries a "Workflow" select: hive-default @@ -79006,6 +79216,8 @@

${esc(s.title)}

`; }).join(''); setTimeout(() => { if (rotationOn) loadRotationHeadroom(); }, 0); + /* Reviewer-stated rules (#19135): painted from their own owner-only endpoint. */ + setTimeout(() => { if (typeof loadReviewRulesSettings === 'function') loadReviewRulesSettings(); }, 0); // Status line: distinguish ON+running from ON+not-configured from OFF. let trajStatus, trajStatusColor; if (!trajOn) { trajStatus = 'Off'; trajStatusColor = 'var(--muted)'; } @@ -79353,6 +79565,10 @@

${esc(s.title)}

+
+
Reviewer-stated rules ${yamlHint('review_feedback.rules')} ${settingHelpMark('settings', 'features', 'Reviewer-stated rules', `When a person reviewing one of the hive's own PRs states a rule or a source of truth, the hive records it in its knowledge (the review-rules channel), replies on the PR with the rule id, and gives it to the authoring agent on its next run. Choose which phrases count and whose rules are recorded at once; others are queued for you.`)}
+
Loading…
+
Merge Recommendations ${settingHelpMark('settings', 'features', 'Merge Recommendations', `A digest of what is worth merging next, written into one issue per repository and rewritten in place each cycle. It is separate from the review gate above: the gate decides whether a PR may merge, while this only reports what already can. It never merges, approves, closes or labels anything.`)}
diff --git a/src/pkg/reviewrules/classify.go b/src/pkg/reviewrules/classify.go index 9bf229994b..75c673c79c 100644 --- a/src/pkg/reviewrules/classify.go +++ b/src/pkg/reviewrules/classify.go @@ -52,6 +52,9 @@ const ( SignalCaptureRequest = "capture-request" SignalCriteria = "assessment-criteria" SignalKnowledgeBase = "knowledge-base" + // SignalOperatorPhrase is the signal an owner-configured extra phrase + // (review_feedback.rules.extra_phrases) reports. + SignalOperatorPhrase = "operator-phrase" ) type signal struct { @@ -61,18 +64,129 @@ type signal struct { // ruleSignals are the phrases that mark a comment as a rule. Matching is // case-insensitive and on word boundaries; adding a phrase means adding a row -// here and a row to the table test. +// here, a row to SignalInfo and a row to the table test. var ruleSignals = []signal{ {SignalSourceOfTruth, regexp.MustCompile(`(?i)\bsources?[- ]of[- ]truth\b`)}, {SignalAuthoritative, regexp.MustCompile(`(?i)\bauthoritative\b`)}, {SignalAlways, regexp.MustCompile(`(?i)\b(?:should|must|needs? to|has to|have to) always\b`)}, {SignalNever, regexp.MustCompile(`(?i)\b(?:should|must) never\b`)}, - {SignalGoingForward, regexp.MustCompile(`(?i)\b(?:going forward|from now on|in (?:the )?future|for the future|moving forward|next time|for future (?:analys[ie]s|assessments?|reviews?|runs|prs|work))\b`)}, + {SignalGoingForward, regexp.MustCompile(`(?i)\b(?:going forward|moving forward|from now on|in (?:the )?future|for (?:the )?future|next time|future (?:analys[ie]s|assessments?|reviews?|runs|prs|work))\b`)}, {SignalCaptureRequest, regexp.MustCompile(`(?i)\b(?:capture|record|document|write down|remember)\s+(?:this|that|it)\b`)}, {SignalCriteria, regexp.MustCompile(`(?i)\bassessment (?:criteria|rubric|knowledge|guidance)\b`)}, {SignalKnowledgeBase, regexp.MustCompile(`(?i)\bknowledge[- ]?base\b`)}, } +// SignalInfo names a built-in signal and gives the examples the Settings card +// and the docs show for it. +type SignalInfo struct { + Name string `json:"name"` + Examples string `json:"examples"` +} + +// Signals lists the built-in signals in table order. +func Signals() []SignalInfo { + return []SignalInfo{ + {SignalSourceOfTruth, `"source of truth", "sources of truth"`}, + {SignalAuthoritative, `"authoritative"`}, + {SignalAlways, `"should always", "must always", "needs to always"`}, + {SignalNever, `"should never", "must never"`}, + {SignalGoingForward, `"going forward", "moving forward", "from now on", "in future", "next time", "future assessments"`}, + {SignalCaptureRequest, `"capture this", "document this", "record it", "remember that"`}, + {SignalCriteria, `"assessment criteria", "assessment rubric", "assessment knowledge"`}, + {SignalKnowledgeBase, `"knowledge base", "knowledge-base"`}, + } +} + +// KnownSignal reports whether name is a built-in signal. +func KnownSignal(name string) bool { + for _, s := range ruleSignals { + if s.name == name { + return true + } + } + return false +} + +// Phrase limits for owner-configured extra phrases. +const ( + MinPhraseRunes = 3 + MaxPhraseRunes = 80 + MaxPhrases = 20 +) + +// ValidatePhrase reports why an owner-configured extra phrase is unusable, or +// "" when it is fine. A phrase is plain text, matched case-insensitively on +// word boundaries; it is quoted into a pattern, never compiled as one. +func ValidatePhrase(p string) string { + n := utf8.RuneCountInString(strings.TrimSpace(p)) + switch { + case n < MinPhraseRunes: + return "is shorter than 3 characters" + case n > MaxPhraseRunes: + return "is longer than 80 characters" + } + for _, r := range p { + if r < 0x20 || r == 0x7f { + return "contains a control character" + } + } + return "" +} + +// phraseSignal builds the matcher for one extra phrase: the literal text, +// case-insensitive, with any run of spaces matching any whitespace, bounded by +// word boundaries where the phrase starts or ends with a word character. +func phraseSignal(p string) (signal, bool) { + p = strings.Join(strings.Fields(p), " ") + if ValidatePhrase(p) != "" { + return signal{}, false + } + quoted := strings.ReplaceAll(regexp.QuoteMeta(p), " ", `\s+`) + pre, post := "", "" + if isWordRune(rune(p[0])) { + pre = `\b` + } + if isWordRune(rune(p[len(p)-1])) { + post = `\b` + } + re, err := regexp.Compile(`(?i)` + pre + quoted + post) + if err != nil { + return signal{}, false + } + return signal{SignalOperatorPhrase, re}, true +} + +func isWordRune(r rune) bool { + return r == '_' || (r >= '0' && r <= '9') || (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') +} + +// Classifier matches comments against a set of signals: the built-in table +// minus any disabled signal, plus owner-configured extra phrases. +type Classifier struct { + signals []signal +} + +// NewClassifier builds a classifier. disabled names built-in signals to +// ignore; extra are plain phrases that also mark a rule. Invalid phrases are +// skipped (the Settings API refuses them before they get here). +func NewClassifier(extra []string, disabled map[string]bool) Classifier { + var c Classifier + for _, s := range ruleSignals { + if !disabled[s.name] { + c.signals = append(c.signals, s) + } + } + for _, p := range extra { + if s, ok := phraseSignal(p); ok { + c.signals = append(c.signals, s) + } + } + return c +} + +// defaultClassifier is the built-in table with no extras. +var defaultClassifier = NewClassifier(nil, nil) + // foreignHomeHint matches wording that puts the rule's proper home in the // reviewed project's own repository (its docs or criteria files), which the // hive does not write to. @@ -85,45 +199,69 @@ var metaClause = regexp.MustCompile(`(?i)^\s*(?:please\s+|and\s+)?(?:capture|rec var sentenceSplit = regexp.MustCompile(`[.!?]+\s+|\n+`) -// minRuleRunes is the shortest rule sentence that can stand alone. A shorter -// one ("Going forward.") is meaningless without the comment around it, so the +// quoteLine matches a Markdown block-quote line: text the reviewer quoted, +// typically the hive's own earlier reply, which is not the reviewer's rule. +var quoteLine = regexp.MustCompile(`^\s{0,3}>`) + +// fenceLine opens or closes a fenced code block. +var fenceLine = regexp.MustCompile("^\\s{0,3}(?:```|~~~)") + +// anaphor matches a word that refers back to something said elsewhere, so a +// short rule sentence carrying one does not stand on its own. +var anaphor = regexp.MustCompile(`(?i)\b(?:this|that|these|those|it)\b`) + +// minStandaloneWords is the length under which a rule sentence that refers +// back ("we should consider this in future") is recorded with the rest of the +// comment, so the rule keeps what "this" is. +const minStandaloneWords = 8 + +// minRuleRunes is the shortest rule text that can stand alone. A shorter one +// ("Going forward.") is meaningless without the comment around it, so the // whole comment is kept instead. const minRuleRunes = 20 -// stripNoise removes what is not the reviewer's own statement: quoted lines -// (a leading ">"), fenced code blocks and questions. A question asks, it does -// not state, so a phrase inside one is not a rule. -func stripNoise(body string) string { - var lines []string - fenced := false +// StripQuoted removes block-quoted lines and fenced code blocks from body: +// what the reviewer quoted is not what the reviewer stated. +func StripQuoted(body string) string { + var kept []string + inFence := false for _, line := range strings.Split(body, "\n") { - t := strings.TrimSpace(line) - if strings.HasPrefix(t, "```") || strings.HasPrefix(t, "~~~") { - fenced = !fenced + if fenceLine.MatchString(line) { + inFence = !inFence continue } - if fenced || strings.HasPrefix(t, ">") { + if inFence || quoteLine.MatchString(line) { continue } - lines = append(lines, line) - } - text := strings.Join(lines, "\n") - var out strings.Builder - last := 0 - keep := func(seg string) { - if !strings.HasSuffix(strings.TrimSpace(seg), "?") { - out.WriteString(seg) - } + kept = append(kept, line) } - for _, loc := range sentenceSplit.FindAllStringIndex(text, -1) { - seg := text[last:loc[1]] - if !strings.Contains(text[loc[0]:loc[1]], "?") { - out.WriteString(seg) + return strings.Join(kept, "\n") +} + +type sentence struct { + text string + question bool +} + +// sentences splits body into sentences, remembering which ones end in a +// question mark. A dot inside a token (".project/maintainers.yaml") does not +// split: a sentence ends at punctuation followed by whitespace, or a newline. +func sentences(body string) []sentence { + var out []sentence + start := 0 + add := func(text, delim string) { + if strings.TrimSpace(text) == "" { + return } - last = loc[1] + q := strings.Contains(delim, "?") || strings.HasSuffix(strings.TrimSpace(text), "?") + out = append(out, sentence{text: text, question: q}) + } + for _, loc := range sentenceSplit.FindAllStringIndex(body, -1) { + add(body[start:loc[0]], body[loc[0]:loc[1]]) + start = loc[1] } - keep(text[last:]) - return out.String() + add(body[start:], "") + return out } // Classification is Classify's verdict. @@ -133,51 +271,72 @@ type Classification struct { Signals []string } +// Classify says whether body states a rule for future work with the built-in +// signals. See Classifier.Classify. +func Classify(body string) Classification { return defaultClassifier.Classify(body) } + // Classify says whether body states a rule for future work. It is a pure -// function of the text: every signal is an explicit phrase from ruleSignals. -func Classify(body string) Classification { - body = stripNoise(body) - var hit []string - for _, s := range ruleSignals { - if s.re.MatchString(body) { - hit = append(hit, s.name) +// function of the text: every signal is an explicit phrase. Quoted lines and +// code blocks are ignored, and so are questions: "is there a way to add this +// to the knowledge base?" asks about capture, it does not state a rule. +func (c Classifier) Classify(body string) Classification { + hit := map[string]bool{} + for _, sent := range sentences(StripQuoted(body)) { + if sent.question { + continue + } + for _, s := range c.signals { + if s.re.MatchString(sent.text) { + hit[s.name] = true + } } } if len(hit) == 0 { return Classification{Kind: KindCorrection} } - return Classification{Kind: KindRule, Signals: hit} + var names []string + seen := map[string]bool{} + for _, s := range c.signals { + if hit[s.name] && !seen[s.name] { + seen[s.name] = true + names = append(names, s.name) + } + } + return Classification{Kind: KindRule, Signals: names} } // ForeignHomeHint reports whether body asks for the rule to live in the // reviewed project's own repository. -func ForeignHomeHint(body string) bool { return foreignHomeHint.MatchString(body) } +func ForeignHomeHint(body string) bool { return foreignHomeHint.MatchString(StripQuoted(body)) } + +// ExtractRuleText returns the rule a comment states with the built-in signals. +// See Classifier.ExtractRuleText. +func ExtractRuleText(body string) string { return defaultClassifier.ExtractRuleText(body) } // ExtractRuleText returns the rule a comment states: the sentences that carry a // signal, without the clauses that only ask for the capture, normalised and -// bounded. A comment with no signal yields its whole body, bounded. -func ExtractRuleText(body string) string { - clean := stripNoise(body) +// bounded. Quoted text and questions are never part of it. A comment with no +// signal yields its whole (unquoted) body, bounded, and so does one whose rule +// sentence is short and refers back to something else in the comment. +func (c Classifier) ExtractRuleText(body string) string { + own := StripQuoted(body) + if strings.TrimSpace(own) == "" { + own = body + } var kept []string - for _, sent := range sentenceSplit.Split(clean, -1) { - if strings.TrimSpace(sent) == "" { - continue - } - if Classify(sent).Kind == KindRule { - kept = append(kept, sent) + for _, sent := range sentences(own) { + if !sent.question && c.Classify(sent.text).Kind == KindRule { + kept = append(kept, sent.text) } } - if len(kept) == 0 || utf8.RuneCountInString(NormalizeText(strings.Join(kept, " "))) < minRuleRunes { - kept = []string{clean} - if strings.TrimSpace(clean) == "" { - kept = []string{body} - } + if len(kept) == 0 { + kept = []string{own} } var clauses []string for _, sent := range kept { - for _, c := range strings.Split(sent, ";") { - if !metaClause.MatchString(c) { - clauses = append(clauses, c) + for _, cl := range strings.Split(sent, ";") { + if !metaClause.MatchString(cl) { + clauses = append(clauses, cl) } } } @@ -185,6 +344,10 @@ func ExtractRuleText(body string) string { clauses = kept } text := NormalizeText(strings.Join(clauses, "; ")) + if utf8.RuneCountInString(text) < minRuleRunes || + (len(strings.Fields(text)) < minStandaloneWords && anaphor.MatchString(text)) { + text = NormalizeText(own) + } return truncateRunes(text, MaxRuleRunes) } diff --git a/src/pkg/reviewrules/classify_future_test.go b/src/pkg/reviewrules/classify_future_test.go new file mode 100644 index 0000000000..5ebce42793 --- /dev/null +++ b/src/pkg/reviewrules/classify_future_test.go @@ -0,0 +1,113 @@ +package reviewrules + +import ( + "strings" + "testing" +) + +// The comment a maintainer left on the techdocs analysis PR, verbatim +// (hivecommons/hive#19135). +const maintainersInline = "The project's `.project/maintainers.yaml` is the source of truth for project ownership and maintainership. Please capture this in the assessment knowledge base; it isn't yet documented in the assessment criteria.\n\n" + + "That roster lists five maintainers. Docs `OWNERS` names only one maintainer, while `CODEOWNERS` also names someone who isn't on the roster. Reframe the recommendation around reconciling these files with the official roster, rather than simply adding a second approver.\n\n" + + "https://github.com/hivecommons/.project/blob/5eba57f/maintainers.yaml#L15-L25" + +// The same maintainer's later PR comment: it quotes the hive's reply and asks +// a question about the knowledge base. Neither part is the maintainer's rule. +const quotesAndAsks = "> On the knowledge-base request: I attempted it. The rule I would record: maintainers.yaml is the source of truth for ownership.\n\n" + + "@operator, is there a way to, from these review conversations, have the hive agent add to the knowledge-base? Some of the assessment is more like an unwritten constitution than a codified one, so being able to add to the corpus may be helpful" + +func TestClassify_FutureLookingPhrasings(t *testing.T) { + tests := []struct { + name string + body string + kind Kind + signals []string + }{ + {"in future", "We should consider this in future.", KindRule, []string{SignalGoingForward}}, + {"in the future", "In the future, check the roster first.", KindRule, []string{SignalGoingForward}}, + {"future assessments", "Future assessments should check the roster file.", KindRule, []string{SignalGoingForward}}, + {"in future assessments", "In future assessments, read the roster.", KindRule, []string{SignalGoingForward}}, + {"moving forward", "Moving forward, cite the roster.", KindRule, []string{SignalGoingForward}}, + {"for the future", "Worth keeping for the future.", KindRule, []string{SignalGoingForward}}, + {"add this to the knowledge base", "Please add this to the knowledge base.", KindRule, []string{SignalKnowledgeBase}}, + {"worth considering alone is not a default signal", "Worth considering a different heading.", KindCorrection, nil}, + {"a question is not a rule", "Should this always be the case?", KindCorrection, nil}, + {"quoted text is not the reviewer's rule", "> the lockfile is the source of truth\n\nThanks, fixed.", KindCorrection, nil}, + {"code is not the reviewer's rule", "```\nsource of truth\n```\nlooks fine", KindCorrection, nil}, + {"real inline comment", maintainersInline, KindRule, []string{SignalSourceOfTruth, SignalCaptureRequest, SignalCriteria, SignalKnowledgeBase}}, + {"quote plus question", quotesAndAsks, KindCorrection, nil}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got := Classify(tc.body) + if got.Kind != tc.kind || strings.Join(got.Signals, ",") != strings.Join(tc.signals, ",") { + t.Fatalf("got %q %v, want %q %v", got.Kind, got.Signals, tc.kind, tc.signals) + } + }) + } +} + +func TestExtractRuleText_QuotesQuestionsAndShortReferences(t *testing.T) { + tests := []struct{ name, body, want string }{ + {"real inline comment", maintainersInline, + "The project's `.project/maintainers.yaml` is the source of truth for project ownership and maintainership; it isn't yet documented in the assessment criteria"}, + {"a short sentence that refers back keeps the comment", "The roster check is missing here. We should consider this in future.", + "The roster check is missing here. We should consider this in future."}, + {"quoted lines never enter the rule", "> the hive said X is authoritative\nGoing forward, the roster file is the source of truth for ownership.", + "Going forward, the roster file is the source of truth for ownership."}, + {"questions never enter the rule", "Is the lockfile authoritative? The roster file must always be cited for ownership claims.", + "The roster file must always be cited for ownership claims."}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + if got := ExtractRuleText(tc.body); got != tc.want { + t.Fatalf("text = %q, want %q", got, tc.want) + } + }) + } +} + +func TestClassifier_ExtraPhrasesAndDisabledSignals(t *testing.T) { + c := NewClassifier([]string{"worth considering", " house rule ", "x"}, map[string]bool{SignalAuthoritative: true}) + if got := c.Classify("Worth considering a different heading."); got.Kind != KindRule || strings.Join(got.Signals, ",") != SignalOperatorPhrase { + t.Fatalf("extra phrase: %+v", got) + } + if got := c.Classify("A HOUSE\nRULE: cite commits"); got.Kind != KindCorrection { + // a newline ends a sentence, so the phrase does not span it + t.Fatalf("phrase split across sentences: %+v", got) + } + if got := c.Classify("This is a house rule: cite commits."); got.Kind != KindRule { + t.Fatalf("normalised phrase: %+v", got) + } + if got := c.Classify("That registry is authoritative for names."); got.Kind != KindCorrection { + t.Fatalf("disabled signal still matched: %+v", got) + } + if got := c.Classify("worth consideringly"); got.Kind != KindCorrection { + t.Fatalf("phrase must match on word boundaries: %+v", got) + } + if got := c.ExtractRuleText("Nice. Worth considering for every assessment that cites a roster."); got != "Worth considering for every assessment that cites a roster." { + t.Fatalf("extract with extra phrase: %q", got) + } + if got := NewClassifier([]string{"(a+)+$"}, nil).Classify("(a+)+$ is literal"); got.Kind != KindRule { + t.Fatalf("a phrase is quoted, never compiled as a pattern: %+v", got) + } +} + +func TestValidatePhraseAndSignals(t *testing.T) { + for p, want := range map[string]bool{"ok phrase": true, "ab": false, strings.Repeat("a", MaxPhraseRunes+1): false, "bad\x01": false} { + if got := ValidatePhrase(p) == ""; got != want { + t.Errorf("ValidatePhrase(%q) ok = %v, want %v", p, got, want) + } + } + if len(Signals()) != len(ruleSignals) { + t.Fatalf("Signals() lists %d, table has %d", len(Signals()), len(ruleSignals)) + } + for _, s := range Signals() { + if !KnownSignal(s.Name) || s.Examples == "" { + t.Errorf("signal %+v", s) + } + } + if KnownSignal("nope") || KnownSignal(SignalOperatorPhrase) { + t.Fatal("unknown names are not signals") + } +} diff --git a/src/pkg/reviewrules/store.go b/src/pkg/reviewrules/store.go index 717201a6f6..af3cc1cb8e 100644 --- a/src/pkg/reviewrules/store.go +++ b/src/pkg/reviewrules/store.go @@ -43,6 +43,14 @@ const ( // MergeThresholdEnvVar overrides how similar two rules' texts must be to // merge, as a fraction between 0 and 1. MergeThresholdEnvVar = "HIVE_REVIEW_FEEDBACK_RULE_MERGE_THRESHOLD" + // ExtraPhrasesEnvVar lists extra plain phrases, comma-separated, that mark + // a comment as a rule. hive.yaml's review_feedback.rules.extra_phrases + // wins when set. + ExtraPhrasesEnvVar = "HIVE_REVIEW_FEEDBACK_RULE_EXTRA_PHRASES" + // DisabledSignalsEnvVar lists built-in signal names, comma-separated, that + // no longer mark a rule. hive.yaml's review_feedback.rules.disabled_signals + // wins when set. + DisabledSignalsEnvVar = "HIVE_REVIEW_FEEDBACK_RULE_DISABLED_SIGNALS" // DefaultMergeThreshold is the token-overlap (Jaccard) at which two rules // of the same scope are the same rule. DefaultMergeThreshold = 0.8 @@ -179,6 +187,23 @@ type Config struct { MaxRules int // MergeThreshold is the text similarity at which same-scope rules merge. MergeThreshold float64 + // ExtraPhrases are owner-chosen plain phrases that also mark a comment as + // a rule (review_feedback.rules.extra_phrases, hivecommons/hive#19135). + ExtraPhrases []string + // DisabledSignals are built-in signal names that no longer mark a rule + // (review_feedback.rules.disabled_signals). + DisabledSignals map[string]bool +} + +// ParseList splits a comma-separated list into trimmed, non-empty items. +func ParseList(list string) []string { + var out []string + for _, a := range strings.Split(list, ",") { + if a = strings.TrimSpace(a); a != "" { + out = append(out, a) + } + } + return out } // ConfigFromEnv reads the knobs, falling back to the Default* constants. @@ -195,6 +220,13 @@ func ConfigFromEnv() Config { if f, err := strconv.ParseFloat(strings.TrimSpace(os.Getenv(MergeThresholdEnvVar)), 64); err == nil && f > 0 && f <= 1 { cfg.MergeThreshold = f } + cfg.ExtraPhrases = ParseList(os.Getenv(ExtraPhrasesEnvVar)) + if names := ParseList(os.Getenv(DisabledSignalsEnvVar)); len(names) > 0 { + cfg.DisabledSignals = map[string]bool{} + for _, n := range names { + cfg.DisabledSignals[strings.ToLower(n)] = true + } + } return cfg } @@ -255,6 +287,7 @@ type Store struct { dir string vault string cfg Config + cls Classifier st index // Reindex, when set, is called after the vault changed so the primer's // view is current without waiting for its periodic refresh. @@ -265,7 +298,8 @@ type Store struct { // is an empty store; an unreadable one is returned with the error and still // usable in memory. func Open(dir, vault string, cfg Config) (*Store, error) { - s := &Store{dir: dir, vault: vault, cfg: cfg.Normalized()} + s := &Store{dir: dir, vault: vault} + s.applyConfig(cfg) s.st = newIndex() b, err := os.ReadFile(filepath.Join(dir, indexFile)) if err != nil { @@ -287,6 +321,20 @@ func newIndex() index { return index{Next: 1, Comments: map[string]string{}, Seen: map[string]seenComment{}, Replies: map[string]time.Time{}, Evaluated: map[string]time.Time{}} } +func (s *Store) applyConfig(cfg Config) { + s.cfg = cfg.Normalized() + s.cls = NewClassifier(s.cfg.ExtraPhrases, s.cfg.DisabledSignals) +} + +// SetConfig replaces the capture policy (trust, phrases, signals, limits) +// without reopening the store, so a Settings change applies on the next pass +// (hivecommons/hive#19135). Comments already evaluated are not read again. +func (s *Store) SetConfig(cfg Config) { + s.mu.Lock() + defer s.mu.Unlock() + s.applyConfig(cfg) +} + func (s *Store) fillMaps() { if s.st.Next < 1 { s.st.Next = 1 @@ -449,16 +497,16 @@ func (s *Store) Remember(c Comment, now time.Time) error { // It is idempotent per comment: a comment id that was captured, queued or // merged before returns OutcomeDuplicate and changes nothing. func (s *Store) CaptureComment(c Comment, now time.Time) Result { - cl := Classify(c.Body) + s.mu.Lock() + defer s.mu.Unlock() + cl := s.cls.Classify(c.Body) if cl.Kind != KindRule { return Result{Outcome: OutcomeNotRule} } - s.mu.Lock() - defer s.mu.Unlock() if id, ok := s.st.Comments[c.key()]; ok { return Result{Outcome: OutcomeDuplicate, Rule: s.copyOf(s.resolve(s.byID(id))), Signals: cl.Signals} } - text := ExtractRuleText(c.Body) + text := s.cls.ExtractRuleText(c.Body) if text == "" { return Result{Outcome: OutcomeRefused, Signals: cl.Signals, Err: errors.New("the comment has no text to record")} } diff --git a/src/pkg/reviewrules/store_config_test.go b/src/pkg/reviewrules/store_config_test.go new file mode 100644 index 0000000000..ce92b540c3 --- /dev/null +++ b/src/pkg/reviewrules/store_config_test.go @@ -0,0 +1,33 @@ +package reviewrules + +import "testing" + +// SetConfig changes trust and phrases for comments read from then on +// (hivecommons/hive#19135). +func TestStore_SetConfigAppliesToLaterComments(t *testing.T) { + s, _, _ := openStore(t, Config{}) + body := "Worth considering for every roster-based assessment you write." + if res := s.CaptureComment(cmt("inline:1", "CONTRIBUTOR", body), t0); res.Outcome != OutcomeNotRule { + t.Fatalf("default phrases: %+v", res) + } + s.SetConfig(Config{Trusted: ParseAssociations("OWNER,MEMBER,COLLABORATOR,CONTRIBUTOR"), ExtraPhrases: []string{"worth considering"}}) + if res := s.CaptureComment(cmt("inline:2", "CONTRIBUTOR", body), t0); res.Outcome != OutcomeCaptured { + t.Fatalf("extra phrase and trusted contributor: %+v", res) + } + s.SetConfig(Config{DisabledSignals: map[string]bool{SignalGoingForward: true}}) + if res := s.CaptureComment(cmt("inline:3", "OWNER", "Going forward, cite the scorecard with a pinned link."), t0); res.Outcome != OutcomeNotRule { + t.Fatalf("disabled signal: %+v", res) + } +} + +func TestParseListAndConfigFromEnv(t *testing.T) { + if got := ParseList(" a, ,b ,"); len(got) != 2 || got[0] != "a" || got[1] != "b" { + t.Fatalf("ParseList = %q", got) + } + t.Setenv(ExtraPhrasesEnvVar, "worth considering, house rule") + t.Setenv(DisabledSignalsEnvVar, "Authoritative") + cfg := ConfigFromEnv() + if len(cfg.ExtraPhrases) != 2 || !cfg.DisabledSignals[SignalAuthoritative] { + t.Fatalf("cfg = %+v", cfg) + } +}