context

Documentation

Overview

Package context provides hierarchical context discovery for hawk. It implements walk-up AGENTS.md discovery (pi-nested-agents-md pattern): when an agent reads a file, the discoverer traverses upward collecting convention files at each directory level with session-scoped deduplication.

Index

• Variables
• func MatchGlobs(globs []string, filePath string) bool
• func ShouldInject(fm *RuleFrontmatter, filePath string) bool
• type ConventionFile
• type InjectionCache
  • func NewInjectionCache() *InjectionCache
  • func (c *InjectionCache) Clear()
  • func (c *InjectionCache) IsSeen(path, hash string) bool
  • func (c *InjectionCache) Len() int
  • func (c *InjectionCache) Mark(path, hash string)
• type Rule
• type RuleDiscoverer
  • func NewRuleDiscoverer(projectRoot string) *RuleDiscoverer
  • func (rd *RuleDiscoverer) Cache() *InjectionCache
  • func (rd *RuleDiscoverer) Discover(filePath string) []Rule
• type RuleFrontmatter
  • func ParseFrontmatter(content string) (*RuleFrontmatter, string)
• type RuleSource
• type WalkUpDiscoverer
  • func NewWalkUpDiscoverer(projectRoot string) *WalkUpDiscoverer
  • func (d *WalkUpDiscoverer) Cache() *InjectionCache
  • func (d *WalkUpDiscoverer) Discover(filePath string) []ConventionFile
  • func (d *WalkUpDiscoverer) FlushPending() string
  • func (d *WalkUpDiscoverer) HandleCompact(ctx interface{}, envelope hooks.EventEnvelope) error
  • func (d *WalkUpDiscoverer) HandlePostTool(ctx interface{}, envelope hooks.EventEnvelope) error
  • func (d *WalkUpDiscoverer) WithFileNames(names []string) *WalkUpDiscoverer
  • func (d *WalkUpDiscoverer) WithMaxFileKB(kb int) *WalkUpDiscoverer
  • func (d *WalkUpDiscoverer) WithMaxTotalKB(kb int) *WalkUpDiscoverer

Variables

var DefaultConventionFiles = []string{
	"AGENTS.md", "HAWK.md", "CLAUDE.md", "CONTEXT.md",
}

DefaultConventionFiles lists the files to discover at each directory level.

var DefaultRuleSources = []RuleSource{
	{".agents/rules", 1, true},
	{".omo/rules", 2, true},
	{".claude/rules", 3, true},
	{".cursor/rules", 4, true},
	{".github/instructions", 5, true},
	{"AGENTS.md", 10, false},
	{"HAWK.md", 11, false},
	{"CLAUDE.md", 12, false},
	{"CONTEXT.md", 13, false},
	{".github/copilot-instructions.md", 14, false},
}

DefaultRuleSources lists rule sources in priority order.

Functions

func MatchGlobs

func MatchGlobs(globs []string, filePath string) bool

MatchGlobs checks if a file path matches any of the given glob patterns. Supports standard filepath.Match patterns plus ** for directory matching.

func ShouldInject

func ShouldInject(fm *RuleFrontmatter, filePath string) bool

ShouldInject determines whether a rule file should be injected for a given file path, based on its frontmatter configuration. Rules are injected when: - alwaysApply is true (or nil) - alwaysApply is false AND the file matches one of the globs If no frontmatter is present, the rule is always applied.

Types

type ConventionFile

type ConventionFile struct {
	Path     string
	Content  string
	Level    int    // 0 = project root, 1 = one level down, etc.
	FileName string // e.g., "AGENTS.md"
}

ConventionFile represents a discovered convention file.

type InjectionCache

type InjectionCache struct {
	// contains filtered or unexported fields
}

InjectionCache tracks which files have already been injected this session.

func NewInjectionCache

func NewInjectionCache() *InjectionCache

NewInjectionCache creates a new injection cache.

func (*InjectionCache) Clear

func (c *InjectionCache) Clear()

Clear removes all entries from the cache.

func (*InjectionCache) IsSeen

func (c *InjectionCache) IsSeen(path, hash string) bool

IsSeen returns true if the file at path with the given content hash has already been injected in this session.

func (*InjectionCache) Len

func (c *InjectionCache) Len() int

Len returns the number of cached entries.

func (*InjectionCache) Mark

func (c *InjectionCache) Mark(path, hash string)

Mark records a file as injected.

type Rule

type Rule struct {
	Path     string
	Content  string
	Hash     string
	Source   string // e.g., ".agents/rules", "AGENTS.md"
	Local    bool   // true if found in the file's directory tree, false if global
	Distance int    // 0 = same directory, 1 = parent, etc.
	Priority int    // source priority
}

Rule represents a discovered rule file with precedence metadata.

type RuleDiscoverer

type RuleDiscoverer struct {
	// contains filtered or unexported fields
}

RuleDiscoverer discovers rule files using walk-up stack semantics with 4-level precedence: local vs global → distance → source priority → path.

func NewRuleDiscoverer

func NewRuleDiscoverer(projectRoot string) *RuleDiscoverer

NewRuleDiscoverer creates a rule discoverer for the given project.

func (*RuleDiscoverer) Cache

func (rd *RuleDiscoverer) Cache() *InjectionCache

Cache returns the injection cache.

func (*RuleDiscoverer) Discover

func (rd *RuleDiscoverer) Discover(filePath string) []Rule

Discover finds all applicable rules for a file path, ordered by precedence.

type RuleFrontmatter

type RuleFrontmatter struct {
	Description string   `yaml:"description"`
	Globs       []string `yaml:"globs"`
	AlwaysApply *bool    `yaml:"alwaysApply"`
}

RuleFrontmatter holds the YAML frontmatter parsed from a rule file.

func ParseFrontmatter

func ParseFrontmatter(content string) (*RuleFrontmatter, string)

ParseFrontmatter extracts YAML frontmatter from a markdown file. Returns the parsed frontmatter, the markdown body, and any error. If no frontmatter is present, returns nil frontmatter and the full content as body.

type RuleSource

type RuleSource struct {
	Name     string // directory or file name (e.g., ".agents/rules", "AGENTS.md")
	Priority int    // lower = higher priority
	IsDir    bool   // true = scan directory recursively for *.md files
}

RuleSource defines a source of rule files with precedence.

type WalkUpDiscoverer

type WalkUpDiscoverer struct {
	// contains filtered or unexported fields
}

WalkUpDiscoverer discovers convention files by walking up from a file's directory to the project root. It hooks into file read events and injects discovered conventions as additional context.

func NewWalkUpDiscoverer

func NewWalkUpDiscoverer(projectRoot string) *WalkUpDiscoverer

NewWalkUpDiscoverer creates a discoverer for the given project root.

func (*WalkUpDiscoverer) Cache

func (d *WalkUpDiscoverer) Cache() *InjectionCache

Cache returns the injection cache (for testing).

func (*WalkUpDiscoverer) Discover

func (d *WalkUpDiscoverer) Discover(filePath string) []ConventionFile

Discover walks up from filePath to projectRoot, collecting undiscovered convention files. Returns the content of newly discovered files (already deduplicated and truncated).

func (*WalkUpDiscoverer) FlushPending

func (d *WalkUpDiscoverer) FlushPending() string

FlushPending returns accumulated convention content and clears the pending buffer.

func (*WalkUpDiscoverer) HandleCompact

func (d *WalkUpDiscoverer) HandleCompact(ctx interface{}, envelope hooks.EventEnvelope) error

HandleCompact is a hook handler for EventPostCompact that clears the cache.

func (*WalkUpDiscoverer) HandlePostTool

func (d *WalkUpDiscoverer) HandlePostTool(ctx interface{}, envelope hooks.EventEnvelope) error

HandlePostTool is a hook handler for EventPostTool that discovers conventions when a file is read.

func (*WalkUpDiscoverer) WithFileNames

func (d *WalkUpDiscoverer) WithFileNames(names []string) *WalkUpDiscoverer

WithFileNames sets the convention file names to look for.

func (*WalkUpDiscoverer) WithMaxFileKB

func (d *WalkUpDiscoverer) WithMaxFileKB(kb int) *WalkUpDiscoverer

WithMaxFileKB sets the max size per convention file (default 32KB).

func (*WalkUpDiscoverer) WithMaxTotalKB

func (d *WalkUpDiscoverer) WithMaxTotalKB(kb int) *WalkUpDiscoverer

WithMaxTotalKB sets the max total injection size per event (default 128KB).