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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Pinned reviewer rules now reach every kick their scope admits ([#19094](https://github.com/hivecommons/hive/issues/19094)). A kick with no issues or no extractable keywords used to return before the knowledge primer ran, so it got no pinned rules; it now gets them, and ranked knowledge still needs keywords. On a host without a vaults directory, the `review-rules` channel the review-feedback sweep creates on its first capture used to wait for a restart before its rules were primed or listed; the primer now registers the channel by path at boot, opens it on the first kick after it appears and connects it to the knowledge API then.
56 changes: 38 additions & 18 deletions src/cmd/hive/boot_knowledge_primer.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package main

import (
"fmt"
"log/slog"
"os"
"path/filepath"
"strings"
Expand Down Expand Up @@ -67,34 +68,53 @@ func (b *boot) registerKnowledgeStores(p *knowledge.Primer) {
// with p as a pinned store: an approved rule whose scope admits a kick reaches
// that kick whatever its keywords are. The channel shows in the dashboard's
// knowledge list like any other, with each rule's source comment and reviewer.
//
// When the channel does not exist yet and cannot be created beside the hive's
// other vaults (a host with no vaults directory), the sweep creates it on its
// first capture. It is then registered by path (#19094): the primer opens it
// 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() {
return
}
dir := reviewrules.VaultDir()
store := api.GetVaultStore(dir)
if store == nil {
// Create the channel only beside the hive's other vaults. A host
// with no vaults directory gets the channel on the first capture
// and connects it at the next boot.
if _, err := os.Stat(filepath.Dir(dir)); err != nil {
if _, derr := os.Stat(dir); derr != nil {
if store := api.GetVaultStore(dir); store != nil {
p.AddPinnedFileStore(reviewrules.VaultName, store, knowledge.LayerProject)
return
}
if _, err := os.Stat(dir); err == nil || parentExists(dir) {
if err := os.MkdirAll(dir, 0o755); err == nil {
if err := api.ConnectVault(dir, reviewrules.VaultName); err != nil {
b.logger.Warn("review-rule vault not connected; registering it by path", "dir", dir, "error", err)
} else if store := api.GetVaultStore(dir); store != nil {
p.AddPinnedFileStore(reviewrules.VaultName, store, knowledge.LayerProject)
return
}
}
if err := os.MkdirAll(dir, 0o755); err != nil {
b.logger.Debug("review-rule vault not created; reviewer rules are not primed", "dir", dir, "error", err)
return
}
if err := api.ConnectVault(dir, reviewrules.VaultName); err != nil {
b.logger.Warn("review-rule vault not connected; reviewer rules are not primed", "dir", dir, "error", err)
return
}
store = api.GetVaultStore(dir)
}
if store != nil {
p.AddPinnedFileStore(reviewrules.VaultName, store, knowledge.LayerProject)
p.AddPinnedDir(reviewrules.VaultName, dir, knowledge.LayerProject, func(*knowledge.FileStore) {
connectReviewRuleVault(api, dir, b.logger)
})
}

// parentExists reports whether dir's parent directory exists.
func parentExists(dir string) bool {
info, err := os.Stat(filepath.Dir(dir))
return err == nil && info.IsDir()
}

// connectReviewRuleVault connects the review-rules channel to the knowledge API
// once it exists, so people can browse and retract its rules.
func connectReviewRuleVault(api *knowledge.KnowledgeAPI, dir string, logger *slog.Logger) {
if api.GetVaultStore(dir) != nil {
return
}
if err := api.ConnectVault(dir, reviewrules.VaultName); err != nil {
logger.Warn("review-rule vault not connected to the dashboard", "dir", dir, "error", err)
return
}
logger.Info("review-rule vault connected after its first capture", "dir", dir)
}

// knowledgeRestartReason names what a live-registered primer cannot apply
Expand Down
107 changes: 107 additions & 0 deletions src/cmd/hive/boot_review_rule_vault_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
package main

import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"time"

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

func reviewRuleVaultFixture(t *testing.T, vault string) (*boot, *knowledge.KnowledgeAPI, *knowledge.Primer) {
t.Helper()
t.Setenv(reviewrules.VaultEnvVar, vault)
t.Setenv(reviewrules.DisableEnvVar, "")
logger := discardLogger()
api := knowledge.NewKnowledgeAPI(nil, knowledge.KnowledgeConfig{Enabled: true, Engine: "file"}, logger)
p := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger)
b := &boot{logger: logger}
b.registerReviewRuleVault(api, p)
return b, api, p
}

func captureFixtureRule(t *testing.T, vault string) {
t.Helper()
rs, err := reviewrules.Open(t.TempDir(), vault, reviewrules.Config{})
if err != nil {
t.Fatal(err)
}
if res := rs.CaptureComment(reviewrules.Comment{Repo: "cncf/techdocs", PR: 424, CommentID: "inline:1001", URL: fixtureCommentURL,
Reviewer: "nate-double-u", Association: "OWNER", Lane: "quality", Body: maintainersFixture}, time.Now()); res.Outcome != reviewrules.OutcomeCaptured {
t.Fatalf("capture = %+v", res)
}
}

func primedFor(p *knowledge.Primer, lane string) string {
out, _ := p.PrimeForKick(context.Background(), nil, knowledge.KickContext{Lane: lane}, nil).Render()
return out
}

// A host with no vaults directory: the channel does not exist at boot, the
// sweep creates it on the first capture, and its rule is primed and the
// channel connected on the next kick, with no restart (#19094).
func TestRegisterReviewRuleVault_CreatedOnFirstCaptureIsPrimedWithoutRestart(t *testing.T) {
vault := filepath.Join(t.TempDir(), "no-vaults-dir", "review-rules")
_, api, p := reviewRuleVaultFixture(t, vault)
if !p.HasPinned() {
t.Fatal("the channel must be registered by path even before it exists")
}
if _, err := os.Stat(vault); err == nil {
t.Fatal("boot must not create a vaults directory the host does not have")
}
if api.GetVaultStore(vault) != nil {
t.Fatal("nothing to connect before the first capture")
}
if got := primedFor(p, "quality"); got != "" {
t.Fatalf("no rules yet, got:\n%s", got)
}

captureFixtureRule(t, vault)

if got := primedFor(p, "quality"); !strings.Contains(got, maintainersRuleText) {
t.Fatalf("a rule captured after boot must reach the next quality kick:\n%s", got)
}
if api.GetVaultStore(vault) == nil {
t.Fatal("the channel must be connected for the dashboard once it exists")
}
if got := primedFor(p, "quality"); strings.Count(got, maintainersRuleText) != 1 {
t.Fatalf("the rule is primed once per kick:\n%s", got)
}
}

// Beside the hive's other vaults the channel is created and connected at boot.
func TestRegisterReviewRuleVault_CreatedBesideOtherVaultsAtBoot(t *testing.T) {
vault := filepath.Join(t.TempDir(), "review-rules")
_, api, p := reviewRuleVaultFixture(t, vault)
if api.GetVaultStore(vault) == nil || !p.HasPinned() {
t.Fatal("an existing vaults directory gets the channel connected and pinned at boot")
}
captureFixtureRule(t, vault)
api.GetVaultStore(vault).Reindex()
if got := primedFor(p, "quality"); !strings.Contains(got, maintainersRuleText) {
t.Fatalf("quality kick:\n%s", got)
}
}

func TestRegisterReviewRuleVault_DisabledRegistersNothing(t *testing.T) {
t.Setenv(reviewrules.VaultEnvVar, filepath.Join(t.TempDir(), "review-rules"))
t.Setenv(reviewrules.DisableEnvVar, "off")
logger := discardLogger()
api := knowledge.NewKnowledgeAPI(nil, knowledge.KnowledgeConfig{Enabled: true, Engine: "file"}, logger)
p := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25}, logger)
(&boot{logger: logger}).registerReviewRuleVault(api, p)
if p.HasPinned() {
t.Fatal("capture off: nothing pinned")
}
}

func TestParentExists(t *testing.T) {
dir := t.TempDir()
if !parentExists(filepath.Join(dir, "x")) || parentExists(filepath.Join(dir, "missing", "x")) {
t.Fatal("parentExists")
}
}
9 changes: 6 additions & 3 deletions src/docs/review-feedback-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ leaving it to the agent's discretion ([#19046](https://github.com/hivecommons/hi
source comment and how to retract it, so the reviewer sees it was captured and can object. The agent's brief lists the recorded rules, tells
it not to record them again, and asks it to name the ids in its reply.
6. **Load.** The kick primer carries every approved `pin` entry whose scope admits the kick, whatever the kick's keywords are, ahead of ranked
knowledge and exempt from the max-facts trim (at most 20 pinned entries per kick). A rule applies to the authoring agent's lane by default,
knowledge and exempt from the max-facts trim (at most 20 pinned entries per kick). This holds for a kick with no issues or no extractable
keywords too: it gets its pinned rules and nothing else, since ranked knowledge still needs keywords. A rule applies to the authoring agent's lane by default,
so the quality agent receives its rules on its next kick; a rule scoped to a workflow reaches the lane or workflow model of that name. The
usual lifecycle filter and `knowledge.agent_scopes` still apply, so drafts, retracted rules and out-of-scope agents never see a rule.

Expand Down Expand Up @@ -59,8 +60,10 @@ source comment, so a maintainer can place it. It is posted once and retried on a

Rules are ordinary knowledge entries in the `review-rules` channel (`/data/vaults/review-rules`, override with
`HIVE_REVIEW_FEEDBACK_RULES_VAULT`), so the dashboard's knowledge list shows each rule with its source and the provenance lines in its body.
The rule index lives in the sweep's state directory (`HIVE_REVIEW_FEEDBACK_DIR`, file `rules.json`). The channel is connected at boot when the
vaults directory exists; the primer reads it within the vault's usual refresh interval after a change.
The rule index lives in the sweep's state directory (`HIVE_REVIEW_FEEDBACK_DIR`, file `rules.json`). At boot the channel is created and
connected when it or the vaults directory exists. On a host without a vaults directory the sweep creates the channel on its first capture;
the primer is registered with its path at boot, opens it on the first kick after it appears and connects it to the knowledge API then, so
neither kicks nor the dashboard wait for a restart. After a change, the primer reads the channel within the vault's usual refresh interval.

- Retract a rule: `hivectl knowledge state rule-r-1 deprecated`. Deleting the entry file does the same. The sweep reconciles on its next pass
(every five minutes) and records the change in its log.
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/knowledge/primer.go
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ type Context7Suggester func(ctx context.Context, keyword string) string
type Primer struct {
layers []layerClient
fileStores []localStore
pinned []localStore
pinned []*pinnedSource
graphStore *GraphStore
config PrimerConfig
logger *slog.Logger
Expand Down
63 changes: 58 additions & 5 deletions src/pkg/knowledge/primer_pinned.go
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
package knowledge

import (
"os"
"sort"
"strings"
"sync"
)

const (
Expand All @@ -22,30 +24,81 @@ const (
maxPinnedFacts = 20
)

// pinnedSource is one pinned vault: an open store, or a directory the primer
// opens the first time it exists (AddPinnedDir).
type pinnedSource struct {
name string
dir string
layer LayerType
onOpen func(*FileStore)

mu sync.Mutex
store *FileStore
}

// open returns the source's store, opening its directory when it has appeared
// since the last kick. A directory that is still missing yields nil.
func (ps *pinnedSource) open(p *Primer) *FileStore {
ps.mu.Lock()
defer ps.mu.Unlock()
if ps.store != nil || ps.dir == "" {
return ps.store
}
if info, err := os.Stat(ps.dir); err != nil || !info.IsDir() {
return nil
}
store, err := NewFileStore(ps.dir, ps.name, p.logger)
if err != nil {
p.logger.Warn("primer: pinned directory not opened", "name", ps.name, "dir", ps.dir, "error", err)
return nil
}
ps.store = store
p.logger.Info("primer: pinned directory opened", "name", ps.name, "dir", ps.dir)
if ps.onOpen != nil {
ps.onOpen(store)
}
return store
}

// AddPinnedFileStore registers a vault whose entries tagged PinTag are always
// primed when their scope admits the kick (FactScope.Admits; an entry without
// a scope admits every kick). The usual lifecycle filter and the agent's
// knowledge scope still apply, so a draft, deprecated or out-of-scope entry is
// never pinned. Like AddFileStore it is not safe for concurrent use with Prime.
func (p *Primer) AddPinnedFileStore(name string, store *FileStore, layer LayerType) {
p.pinned = append(p.pinned, localStore{layerType: layer, store: store, name: name})
p.pinned = append(p.pinned, &pinnedSource{name: name, layer: layer, store: store})
p.logger.Info("primer: added pinned file store", "name", name, "layer", layer)
}

// AddPinnedDir is AddPinnedFileStore for a directory that may not exist yet
// (#19094): the review-feedback sweep creates the review-rules channel on its
// first capture, and its rules must reach kicks without a restart. The
// directory is opened on the first kick after it appears, and onOpen (when
// set) is called once with the opened store, so the caller can also connect it
// where people browse knowledge.
func (p *Primer) AddPinnedDir(name, dir string, layer LayerType, onOpen func(*FileStore)) {
p.pinned = append(p.pinned, &pinnedSource{name: name, dir: dir, layer: layer, onOpen: onOpen})
p.logger.Info("primer: added pinned directory", "name", name, "dir", dir, "layer", layer)
}

// HasPinned reports whether any pinned store is registered.
func (p *Primer) HasPinned() bool { return p != nil && len(p.pinned) > 0 }

// pinnedFacts returns the pinned entries a kick must carry, oldest slug first
// so the result is stable. Bodies are read in full.
func (p *Primer) pinnedFacts(scope *TOCScope, kc KickContext, draftAuthors []string) []Fact {
var out []Fact
for _, ls := range p.pinned {
for _, f := range ls.store.ListPages(PinTag) {
full, err := ls.store.ReadPage(f.Slug)
for _, ps := range p.pinned {
store := ps.open(p)
if store == nil {
continue
}
for _, f := range store.ListPages(PinTag) {
full, err := store.ReadPage(f.Slug)
if err != nil || full == nil {
continue
}
full.Layer = ls.layerType
full.Layer = ps.layer
full.Type = PinnedFactType
out = append(out, *full)
}
Expand Down
50 changes: 50 additions & 0 deletions src/pkg/knowledge/primer_pinned_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ package knowledge
import (
"context"
"fmt"
"os"
"path/filepath"
"sort"
"strings"
"testing"
Expand Down Expand Up @@ -175,3 +177,51 @@ func TestWithPinned(t *testing.T) {
t.Fatal("nil primer has nothing pinned")
}
}

// A pinned directory that does not exist at registration is opened on the
// first kick after it appears (#19094), and onOpen runs once.
func TestPinnedDirIsOpenedWhenItAppears(t *testing.T) {
dir := filepath.Join(t.TempDir(), "review-rules")
opened := 0
p := NewPrimer(nil, PrimerConfig{MaxFacts: 25}, fileStoreTestLogger())
p.AddPinnedDir("review-rules", dir, LayerProject, func(s *FileStore) {
if s == nil || s.RootDir() != dir {
t.Errorf("onOpen store = %v", s)
}
opened++
})
if !p.HasPinned() {
t.Fatal("a registered directory counts as pinned before it exists")
}
kc := KickContext{Lane: "quality"}
if got := p.PrimeForKick(context.Background(), nil, kc, nil); len(got.Facts) != 0 || opened != 0 {
t.Fatalf("missing dir: facts=%d opened=%d", len(got.Facts), opened)
}
if err := os.WriteFile(dir, []byte("not a dir"), 0o644); err != nil {
t.Fatal(err)
}
if got := p.PrimeForKick(context.Background(), nil, kc, nil); len(got.Facts) != 0 || opened != 0 {
t.Fatalf("a file at the path is not opened: facts=%d opened=%d", len(got.Facts), opened)
}
if err := os.Remove(dir); err != nil {
t.Fatal(err)
}
if err := os.MkdirAll(dir, 0o755); err != nil {
t.Fatal(err)
}
writeLifecycleFact(t, dir, "rule-r-1", "title: R-1 quality rule\ntype: reviewer-rule\ntags: [review-rule, pin]\nscope:\n lanes: [quality]\n", "Use the maintainers file.")
for i := 0; i < 2; i++ {
got := p.PrimeForKick(context.Background(), nil, kc, nil)
if slugsOf(got.Facts) != "rule-r-1" {
t.Fatalf("pass %d: pinned = %s, want rule-r-1", i, slugsOf(got.Facts))
}
}
if opened != 1 {
t.Fatalf("onOpen ran %d times, want once", opened)
}
nilHook := NewPrimer(nil, PrimerConfig{MaxFacts: 25}, fileStoreTestLogger())
nilHook.AddPinnedDir("review-rules", dir, LayerProject, nil)
if got := nilHook.PrimeForKick(context.Background(), nil, kc, nil); slugsOf(got.Facts) != "rule-r-1" {
t.Fatalf("without a hook: %s", slugsOf(got.Facts))
}
}
Loading
Loading