context

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 1, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package context provides context aggregation from multiple sources for grounding spec synthesis in reality.

Sources include git repositories, graphize graphs, MCP servers, and local files. The aggregated context is used by synthesis and alignment commands to generate specs that reflect actual codebases and external tool state.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateCodeSummary 

func GenerateCodeSummary(code *CodeContext) string

GenerateCodeSummary creates a summary for a single code context.

func GenerateGraphSummary 

func GenerateGraphSummary(graph *GraphContext) string

GenerateGraphSummary creates a summary for a single graph context.

func RenderTreeToString 

func RenderTreeToString(node *TreeNode, prefix string, isLast bool) string

RenderTreeToString renders a tree node to a string representation.

func SaveSnapshot 

func SaveSnapshot(ac *AggregatedContext, path string) error

SaveSnapshot saves an aggregated context to a file.

Types

type APIRoute 

type APIRoute struct {
	Method      string `json:"method"`
	Path        string `json:"path"`
	Summary     string `json:"summary,omitempty"`
	OperationID string `json:"operation_id,omitempty"`
}

APIRoute represents an API endpoint.

type APISchema 

type APISchema struct {
	Path   string     `json:"path"`
	Format string     `json:"format"` // "openapi", "graphql", "proto"
	Title  string     `json:"title,omitempty"`
	Routes []APIRoute `json:"routes,omitempty"`
}

APISchema represents a detected API schema file.

type AggregatedContext 

type AggregatedContext struct {
	// Project name
	Project string `json:"project"`

	// When gathering completed
	GatheredAt time.Time `json:"gathered_at"`

	// Total time to gather all sources
	Duration time.Duration `json:"duration"`

	// Individual source data
	Sources []*ContextData `json:"sources"`

	// Combined summary for LLM consumption
	Summary string `json:"summary"`

	// Quick access flags
	HasCode     bool `json:"has_code"`
	HasGraph    bool `json:"has_graph"`
	HasExternal bool `json:"has_external"`
	HasFiles    bool `json:"has_files"`

	// Error count across all sources
	ErrorCount int `json:"error_count"`
}

AggregatedContext combines data from all sources.

func FromJSON 

func FromJSON(data []byte) (*AggregatedContext, error)

FromJSON deserializes an aggregated context from JSON.

func LoadSnapshot 

func LoadSnapshot(path string) (*AggregatedContext, error)

LoadSnapshot loads an aggregated context from a file.

func (*AggregatedContext) AllAPIs 

func (ac *AggregatedContext) AllAPIs() []APISchema

AllAPIs returns API schemas from all code contexts.

func (*AggregatedContext) AllDecisions 

func (ac *AggregatedContext) AllDecisions() []Decision

AllDecisions returns decisions from all graph contexts.

func (*AggregatedContext) AllDependencies 

func (ac *AggregatedContext) AllDependencies() []Dependency

AllDependencies returns dependencies from all code contexts.

func (*AggregatedContext) AllRequirements 

func (ac *AggregatedContext) AllRequirements() []Requirement

AllRequirements returns requirements from all graph contexts.

func (*AggregatedContext) CodeContexts 

func (ac *AggregatedContext) CodeContexts() []*CodeContext

CodeContexts returns all code contexts from sources.

func (*AggregatedContext) ExternalContexts 

func (ac *AggregatedContext) ExternalContexts() []*ExternalContext

ExternalContexts returns all external contexts from sources.

func (*AggregatedContext) FileContexts 

func (ac *AggregatedContext) FileContexts() []*FileContext

FileContexts returns all file contexts from sources.

func (*AggregatedContext) GenerateSummary 

func (ac *AggregatedContext) GenerateSummary() string

GenerateSummary creates an LLM-friendly summary from aggregated context.

func (*AggregatedContext) GraphContexts 

func (ac *AggregatedContext) GraphContexts() []*GraphContext

GraphContexts returns all graph contexts from sources.

func (*AggregatedContext) ToJSON 

func (ac *AggregatedContext) ToJSON() ([]byte, error)

ToJSON serializes the aggregated context to JSON.

type Aggregator 

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

Aggregator fetches and combines context from multiple sources.

func NewAggregator 

func NewAggregator(projectName string, cfg *Config) *Aggregator

NewAggregator creates an aggregator from configuration. Sources are created based on the config but not yet fetched.

func (*Aggregator) AddSource 

func (a *Aggregator) AddSource(src Source)

AddSource adds a source to the aggregator.

func (*Aggregator) ClearCache 

func (a *Aggregator) ClearCache()

ClearCache clears the context cache.

func (*Aggregator) Gather 

func (a *Aggregator) Gather(ctx context.Context) (*AggregatedContext, error)

Gather fetches context from all sources concurrently.

func (*Aggregator) GatherWithTimeout 

func (a *Aggregator) GatherWithTimeout(timeout time.Duration) (*AggregatedContext, error)

GatherWithTimeout fetches context with a timeout.

func (*Aggregator) Refresh 

func (a *Aggregator) Refresh(ctx context.Context) (*AggregatedContext, error)

Refresh clears the cache and re-fetches all sources.

func (*Aggregator) SourceCount 

func (a *Aggregator) SourceCount() int

SourceCount returns the number of sources.

func (*Aggregator) Sources 

func (a *Aggregator) Sources() []Source

Sources returns all registered sources.

type Cache 

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

Cache provides a simple in-memory cache with TTL.

func NewCache 

func NewCache(ttl time.Duration) *Cache

NewCache creates a new cache with the given TTL.

func (*Cache) Cleanup 

func (c *Cache) Cleanup()

Cleanup removes expired entries.

func (*Cache) Clear 

func (c *Cache) Clear()

Clear removes all entries from the cache.

func (*Cache) Get 

func (c *Cache) Get(key string) *ContextData

Get retrieves a cached entry if it exists and hasn't expired.

func (*Cache) Set 

func (c *Cache) Set(key string, data *ContextData)

Set stores a value in the cache.

func (*Cache) Size 

func (c *Cache) Size() int

Size returns the number of cached entries.

type CodeContext 

type CodeContext struct {
	// Repository path (local or URL)
	RepoPath string `json:"repo_path"`

	// Current branch name
	Branch string `json:"branch,omitempty"`

	// Current commit hash (short)
	Commit string `json:"commit,omitempty"`

	// Directory structure tree
	Structure *TreeNode `json:"structure,omitempty"`

	// Extracted dependencies
	Dependencies []Dependency `json:"dependencies,omitempty"`

	// Detected API schemas
	APIs []APISchema `json:"apis,omitempty"`

	// Lines of code by language
	Languages map[string]int `json:"languages,omitempty"`

	// README content (truncated if large)
	README string `json:"readme,omitempty"`
}

CodeContext holds git repository analysis results.

type Config 

type Config struct {
	// Project name (from parent config)
	ProjectName string `yaml:"-"`

	// Git repositories to analyze
	Repositories []RepositoryConfig `yaml:"repositories,omitempty"`

	// Standalone graphize graphs
	Graphize []GraphizeConfig `yaml:"graphize,omitempty"`

	// MCP servers for external context
	MCPServers map[string]MCPServerConfig `yaml:"mcp_servers,omitempty"`

	// Local files to include
	Files []FileConfig `yaml:"files,omitempty"`

	// Cache TTL for context data (default: 5m)
	CacheTTL time.Duration `yaml:"cache_ttl,omitempty"`
}

Config holds the context configuration from visionspec.yaml.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func (*Config) HasSources 

func (c *Config) HasSources() bool

HasSources returns true if any context sources are configured.

func (*Config) SourceCount 

func (c *Config) SourceCount() int

SourceCount returns the total number of configured sources.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks the configuration for errors.

type Constraint 

type Constraint struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	Type        string `json:"type,omitempty"` // "technical", "business", "regulatory"
	SourceSpec  string `json:"source_spec,omitempty"`
}

Constraint represents a constraint node.

type ContextData 

type ContextData struct {
	// Source identifier
	Source string `json:"source"`

	// Type of source
	Type SourceType `json:"type"`

	// When the data was fetched
	FetchedAt time.Time `json:"fetched_at"`

	// How long the fetch took
	Duration time.Duration `json:"duration"`

	// Type-specific data (one populated based on Type)
	Code     *CodeContext     `json:"code,omitempty"`
	Graph    *GraphContext    `json:"graph,omitempty"`
	External *ExternalContext `json:"external,omitempty"`
	File     *FileContext     `json:"file,omitempty"`

	// LLM-friendly summary (generated from the data)
	Summary string `json:"summary"`

	// Errors encountered during fetch (partial results may still be present)
	Errors []string `json:"errors,omitempty"`
}

ContextData holds data from a single source.

type Decision 

type Decision struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Status      string   `json:"status,omitempty"` // "proposed", "accepted", "deprecated"
	Date        string   `json:"date,omitempty"`
	Tags        []string `json:"tags,omitempty"`
}

Decision represents an architectural decision node.

type Dependency 

type Dependency struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	Type    string `json:"type"`   // "direct" or "indirect"
	Source  string `json:"source"` // "go.mod", "package.json", etc.
}

Dependency represents a project dependency.

type Document 

type Document struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Type    string `json:"type,omitempty"` // doc, sheet, slide
	Content string `json:"content,omitempty"`
	Updated string `json:"updated,omitempty"`
	URL     string `json:"url,omitempty"`
}

Document represents a document from Google Docs, Office 365, etc.

type Epic 

type Epic struct {
	Issue
	ChildKeys []string `json:"child_keys,omitempty"`
}

Epic represents an epic with child issues.

type ExternalContext 

type ExternalContext struct {
	// Server identifier
	ServerName string `json:"server_name"`

	// Server type (jira, confluence, google, etc.)
	ServerType string `json:"server_type"`

	// Issue tracker data
	Issues []Issue `json:"issues,omitempty"`
	Epics  []Epic  `json:"epics,omitempty"`

	// Documentation data
	Pages     []Page     `json:"pages,omitempty"`
	Documents []Document `json:"documents,omitempty"`
}

ExternalContext holds data from MCP servers (Jira, Confluence, etc.).

type FileConfig 

type FileConfig struct {
	// Path to the file
	Path string `yaml:"path"`

	// Type of content: architecture, api_spec, readme, diagram
	Type string `yaml:"type,omitempty"`

	// Maximum content size to include (default: 50KB)
	MaxSize int64 `yaml:"max_size,omitempty"`
}

FileConfig configures a local file source.

type FileContext 

type FileContext struct {
	Path    string `json:"path"`
	Type    string `json:"type"` // architecture, api_spec, readme, diagram
	Content string `json:"content"`
	Format  string `json:"format,omitempty"` // markdown, yaml, json
}

FileContext holds data from local files.

type GraphContext 

type GraphContext struct {
	// Path to the .graphize directory
	GraphPath string `json:"graph_path"`

	// Raw graph data
	Nodes []GraphNode `json:"nodes,omitempty"`
	Edges []GraphEdge `json:"edges,omitempty"`

	// Node counts by type
	NodeCount        int `json:"node_count"`
	EdgeCount        int `json:"edge_count"`
	RequirementCount int `json:"requirement_count"`
	CodeCount        int `json:"code_count"`
	TestCount        int `json:"test_count"`

	// Coverage metrics
	LinkedRequirements int     `json:"linked_requirements"`
	TestedRequirements int     `json:"tested_requirements"`
	CodeCoverage       float64 `json:"code_coverage"`
	TestCoverage       float64 `json:"test_coverage"`

	// Metadata
	Version string `json:"version,omitempty"`
	Tool    string `json:"tool,omitempty"`

	// Extracted typed nodes (optional, for higher-level analysis)
	Requirements []Requirement `json:"requirements,omitempty"`
	Decisions    []Decision    `json:"decisions,omitempty"`
	Constraints  []Constraint  `json:"constraints,omitempty"`
	UserStories  []UserStory   `json:"user_stories,omitempty"`

	// Extracted edges
	Traceability []TraceLink `json:"traceability,omitempty"`

	// Graph statistics
	Stats GraphStats `json:"stats"`
}

GraphContext holds graphize graph analysis results.

type GraphEdge 

type GraphEdge struct {
	Source string `json:"source"`
	Target string `json:"target"`
	Type   string `json:"type"`
}

GraphEdge represents an edge in the graphize graph.

type GraphNode 

type GraphNode struct {
	ID       string            `json:"id"`
	Type     string            `json:"type"`
	Label    string            `json:"label"`
	Path     string            `json:"path,omitempty"`
	Line     int               `json:"line,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

GraphNode represents a generic node in the graphize graph.

type GraphStats 

type GraphStats struct {
	RequirementCount int            `json:"requirement_count"`
	DecisionCount    int            `json:"decision_count"`
	ConstraintCount  int            `json:"constraint_count"`
	UserStoryCount   int            `json:"user_story_count"`
	TraceabilityPct  float64        `json:"traceability_pct"` // % of requirements with traces
	NodesByType      map[string]int `json:"nodes_by_type"`
	EdgesByType      map[string]int `json:"edges_by_type"`
}

GraphStats holds statistics about the graph.

type GraphizeConfig 

type GraphizeConfig struct {
	// Path to .graphize directory
	Path string `yaml:"path"`

	// Human-readable name
	Name string `yaml:"name,omitempty"`

	// Node types to include (empty = all)
	IncludeNodes []string `yaml:"include_nodes,omitempty"`

	// Edge types to include (empty = all)
	IncludeEdges []string `yaml:"include_edges,omitempty"`
}

GraphizeConfig configures a standalone graphize source.

type Issue 

type Issue struct {
	Key         string   `json:"key"`
	Type        string   `json:"type"` // epic, story, task, bug
	Summary     string   `json:"summary"`
	Description string   `json:"description,omitempty"`
	Status      string   `json:"status"`
	Priority    string   `json:"priority,omitempty"`
	Assignee    string   `json:"assignee,omitempty"`
	Labels      []string `json:"labels,omitempty"`
	Created     string   `json:"created,omitempty"`
	Updated     string   `json:"updated,omitempty"`
}

Issue represents an issue from Jira or similar.

type MCPServerConfig 

type MCPServerConfig struct {
	// Command to start the server
	Command string `yaml:"command"`

	// Arguments to the command
	Args []string `yaml:"args,omitempty"`

	// Environment variables
	Env map[string]string `yaml:"env,omitempty"`

	// Server-specific configuration
	Config map[string]any `yaml:"config,omitempty"`

	// Timeout for server operations (default: 30s)
	Timeout time.Duration `yaml:"timeout,omitempty"`
}

MCPServerConfig configures an MCP server source.

type Page 

type Page struct {
	ID      string   `json:"id"`
	Title   string   `json:"title"`
	Space   string   `json:"space,omitempty"`
	Content string   `json:"content,omitempty"` // Truncated if large
	Labels  []string `json:"labels,omitempty"`
	Version int      `json:"version,omitempty"`
	Updated string   `json:"updated,omitempty"`
	URL     string   `json:"url,omitempty"`
}

Page represents a wiki/documentation page.

type RepositoryConfig 

type RepositoryConfig struct {
	// Path to local repository
	Path string `yaml:"path,omitempty"`

	// URL for remote repository (clone if not exists)
	URL string `yaml:"url,omitempty"`

	// Branch to checkout (default: default branch)
	Branch string `yaml:"branch,omitempty"`

	// Sparse checkout paths (for large repos)
	Sparse []string `yaml:"sparse,omitempty"`

	// Include patterns for file analysis
	Include []string `yaml:"include,omitempty"`

	// Exclude patterns
	Exclude []string `yaml:"exclude,omitempty"`

	// What to analyze: structure, dependencies, api_schemas, readme
	Analyze []string `yaml:"analyze,omitempty"`

	// Graphize detection: "auto", "true", "false"
	Graphize string `yaml:"graphize,omitempty"`

	// Maximum depth for directory tree (default: 5)
	MaxDepth int `yaml:"max_depth,omitempty"`
}

RepositoryConfig configures a git repository source.

type Requirement 

type Requirement struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Priority    string   `json:"priority,omitempty"`
	Status      string   `json:"status,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	SourceSpec  string   `json:"source_spec,omitempty"` // e.g., "prd"
}

Requirement represents a requirement node from graphize.

type Snapshot 

type Snapshot struct {
	// Version of the snapshot format
	Version string `json:"version"`

	// The aggregated context
	Context *AggregatedContext `json:"context"`
}

Snapshot represents a saved context state.

type Source 

type Source interface {
	// Name returns a unique identifier for this source.
	Name() string

	// Type returns the source type.
	Type() SourceType

	// Fetch retrieves context data from the source.
	Fetch(ctx context.Context) (*ContextData, error)

	// String returns a human-readable description.
	String() string
}

Source represents a context source that can be fetched.

type SourceType 

type SourceType string

SourceType identifies the type of context source. 

const (
	// SourceTypeGit represents a git repository source.
	SourceTypeGit SourceType = "git"

	// SourceTypeGraphize represents a graphize graph source.
	SourceTypeGraphize SourceType = "graphize"

	// SourceTypeMCP represents an MCP server source.
	SourceTypeMCP SourceType = "mcp"

	// SourceTypeFile represents a local file source.
	SourceTypeFile SourceType = "file"
)
type TraceLink struct {
	FromID   string `json:"from_id"`
	FromType string `json:"from_type"`
	ToID     string `json:"to_id"`
	ToType   string `json:"to_type"`
	Relation string `json:"relation"` // traces_to, derived_from, depends_on, conflicts_with
}

TraceLink represents a traceability edge between nodes.

type TreeNode 

type TreeNode struct {
	Name     string      `json:"name"`
	Type     string      `json:"type"` // "file" or "dir"
	Size     int64       `json:"size,omitempty"`
	Children []*TreeNode `json:"children,omitempty"`
}

TreeNode represents a file or directory in the code structure.

type UserStory 

type UserStory struct {
	ID             string   `json:"id"`
	Title          string   `json:"title"`
	AsA            string   `json:"as_a,omitempty"`
	IWant          string   `json:"i_want,omitempty"`
	SoThat         string   `json:"so_that,omitempty"`
	AcceptanceCrit []string `json:"acceptance_criteria,omitempty"`
}

UserStory represents a user story node.

Source Files

View all Source files

Directories

Path Synopsis
Package file provides local file context source.
 Package file provides local file context source.
Package git provides git repository context source.
 Package git provides git repository context source.
Package graphize provides graphize requirement traceability context source.
 Package graphize provides graphize requirement traceability context source.
Package mcp provides MCP client for external context sources.
 Package mcp provides MCP client for external context sources.
Package sources provides factory functions to create context sources.
 Package sources provides factory functions to create context sources.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.