align

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package align provides post-ship spec-to-reality alignment checking.

Alignment compares the reconciled spec.md against the actual implementation to identify discrepancies between what was specified and what was built. This enables continuous validation that the shipped product matches the spec.

Package align provides drift resolution workflow capabilities.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RenderResult 

func RenderResult(result *AlignmentResult, format OutputFormat) (string, error)

RenderResult renders an alignment result in the specified format.

Types

type AlignOptions 

type AlignOptions struct {
	MinSeverity      Severity   // Only report items at or above this severity
	Categories       []Category // Only report items in these categories (empty = all)
	ExcludeTypes     []DiscrepancyType
	IncludeEvidence  bool // Include evidence snippets
	MaxDiscrepancies int  // Limit results (0 = unlimited)
}

AlignOptions configures alignment checking.

func DefaultAlignOptions 

func DefaultAlignOptions() AlignOptions

DefaultAlignOptions returns sensible defaults.

type Aligner 

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

Aligner performs alignment checking.

func NewAligner 

func NewAligner() *Aligner

NewAligner creates a new alignment checker.

func (*Aligner) Align 

func (a *Aligner) Align(specContent string, ctx *context.AggregatedContext, opts AlignOptions) (*AlignmentResult, error)

Align compares spec content against codebase context.

type AlignmentCoverage 

type AlignmentCoverage struct {
	TotalRequirements  int     `json:"total_requirements"`
	ImplementedCount   int     `json:"implemented_count"`
	PartialCount       int     `json:"partial_count"`
	MissingCount       int     `json:"missing_count"`
	CoveragePercentage float64 `json:"coverage_percentage"`
	UndocumentedCount  int     `json:"undocumented_count"` // Code without spec
}

AlignmentCoverage tracks spec coverage metrics.

type AlignmentResult 

type AlignmentResult struct {
	Project       string            `json:"project"`
	GeneratedAt   time.Time         `json:"generated_at"`
	SpecPath      string            `json:"spec_path"`
	ContextSource string            `json:"context_source,omitempty"`
	Discrepancies []Discrepancy     `json:"discrepancies"`
	Summary       AlignmentSummary  `json:"summary"`
	Coverage      AlignmentCoverage `json:"coverage"`
	Metadata      map[string]any    `json:"metadata,omitempty"`
}

AlignmentResult contains the full alignment analysis.

func (*AlignmentResult) FilterByCategory 

func (r *AlignmentResult) FilterByCategory(categories ...Category) []Discrepancy

FilterByCategory returns items in the given categories.

func (*AlignmentResult) FilterBySeverity 

func (r *AlignmentResult) FilterBySeverity(minSeverity Severity) []Discrepancy

FilterBySeverity returns items at or above the given severity.

func (*AlignmentResult) FilterByType 

func (r *AlignmentResult) FilterByType(types ...DiscrepancyType) []Discrepancy

FilterByType returns items of the given types.

func (*AlignmentResult) HasBlockers 

func (r *AlignmentResult) HasBlockers() bool

HasBlockers returns true if there are critical or high severity issues.

func (*AlignmentResult) HasDiscrepancies 

func (r *AlignmentResult) HasDiscrepancies() bool

HasDiscrepancies returns true if any discrepancies were found.

type AlignmentSummary 

type AlignmentSummary struct {
	TotalDiscrepancies int                     `json:"total_discrepancies"`
	ByType             map[DiscrepancyType]int `json:"by_type"`
	BySeverity         map[Severity]int        `json:"by_severity"`
	ByCategory         map[Category]int        `json:"by_category"`
	CriticalCount      int                     `json:"critical_count"`
	HighCount          int                     `json:"high_count"`
	AlignmentScore     float64                 `json:"alignment_score"` // 0.0 to 1.0
	IsAligned          bool                    `json:"is_aligned"`      // True if no critical/high issues
}

AlignmentSummary provides aggregate statistics.

type Category 

type Category string

Category groups discrepancies by functional area. 

const (
	CategoryAPI      Category = "api"      // API endpoints, contracts
	CategoryData     Category = "data"     // Data models, schemas
	CategoryUI       Category = "ui"       // User interface
	CategoryBehavior Category = "behavior" // Business logic
	CategoryInfra    Category = "infra"    // Infrastructure
	CategorySecurity Category = "security" // Security features
	CategoryPerf     Category = "perf"     // Performance characteristics
	CategoryOther    Category = "other"    // Uncategorized
)

type Comparator 

type Comparator struct{}

Comparator compares specs against implementations.

func NewComparator 

func NewComparator() *Comparator

NewComparator creates a new comparator.

func (*Comparator) Compare 

func (c *Comparator) Compare(requirements []Requirement, implementations []Implementation, includeEvidence bool) []Discrepancy

Compare finds discrepancies between requirements and implementations.

func (*Comparator) ExtractImplementations 

func (c *Comparator) ExtractImplementations(ctx *context.AggregatedContext) []Implementation

ExtractImplementations parses context to extract implementations.

func (*Comparator) ExtractRequirements 

func (c *Comparator) ExtractRequirements(specContent string) []Requirement

ExtractRequirements parses spec content to extract requirements.

type CurrentTruth 

type CurrentTruth struct {
	Project        string         `json:"project"`
	GeneratedAt    time.Time      `json:"generated_at"`
	SpecVersion    string         `json:"spec_version,omitempty"`
	AlignmentScore float64        `json:"alignment_score"`
	Status         TruthStatus    `json:"status"`
	Sections       []TruthSection `json:"sections"`
	Summary        TruthSummary   `json:"summary"`
	NextActions    []string       `json:"next_actions,omitempty"`
}

CurrentTruth represents the current state of implementation relative to spec.

func GenerateCurrentTruth 

func GenerateCurrentTruth(result *AlignmentResult) *CurrentTruth

GenerateCurrentTruth creates a CurrentTruth document from an alignment result.

func ParseCurrentTruth 

func ParseCurrentTruth(content string) (*CurrentTruth, error)

ParseCurrentTruth parses a current-truth.md file back into a struct. This is useful for tracking changes over time.

func (*CurrentTruth) RenderMarkdown 

func (t *CurrentTruth) RenderMarkdown() (string, error)

RenderMarkdown renders the CurrentTruth as a markdown document.

type Discrepancy 

type Discrepancy struct {
	ID          string          `json:"id"`
	Type        DiscrepancyType `json:"type"`
	Severity    Severity        `json:"severity"`
	Category    Category        `json:"category"`
	Description string          `json:"description"`
	SpecRef     string          `json:"spec_ref,omitempty"` // Reference to spec section/line
	CodeRef     string          `json:"code_ref,omitempty"` // Reference to code file:line
	Expected    string          `json:"expected,omitempty"` // What spec says
	Actual      string          `json:"actual,omitempty"`   // What code does
	Suggestion  string          `json:"suggestion,omitempty"`
	Evidence    []Evidence      `json:"evidence,omitempty"`
}

Discrepancy represents a single alignment finding.

type DiscrepancyType 

type DiscrepancyType string

DiscrepancyType categorizes the type of discrepancy detected. 

const (
	// DiscrepancyMissingFeature indicates a specified feature not found in code.
	DiscrepancyMissingFeature DiscrepancyType = "missing_feature"

	// DiscrepancyUndocumentedCode indicates code functionality without spec coverage.
	DiscrepancyUndocumentedCode DiscrepancyType = "undocumented_code"

	// DiscrepancyDiverged indicates both spec and code exist but have diverged.
	DiscrepancyDiverged DiscrepancyType = "diverged"

	// DiscrepancyPartialImplementation indicates feature is partially implemented.
	DiscrepancyPartialImplementation DiscrepancyType = "partial_implementation"

	// DiscrepancyBehaviorMismatch indicates behavior differs from spec.
	DiscrepancyBehaviorMismatch DiscrepancyType = "behavior_mismatch"
)

type Evidence 

type Evidence struct {
	Type    string `json:"type"`    // "spec_excerpt", "code_snippet", "test_result"
	Content string `json:"content"` // The evidence content
	Source  string `json:"source"`  // Where it came from
}

Evidence provides supporting details for a discrepancy.

type Implementation 

type Implementation struct {
	ID          string   `json:"id"`
	Type        string   `json:"type"` // "function", "endpoint", "model", etc.
	Name        string   `json:"name"`
	Description string   `json:"description"`
	FilePath    string   `json:"file_path"`
	LineNumber  int      `json:"line_number"`
	Keywords    []string `json:"keywords"`
}

Implementation represents a code implementation.

type OutputFormat 

type OutputFormat string

OutputFormat specifies the output format. 

const (
	OutputFormatText     OutputFormat = "text"
	OutputFormatJSON     OutputFormat = "json"
	OutputFormatMarkdown OutputFormat = "markdown"
)

type PrioritizedAction 

type PrioritizedAction struct {
	Order         int                `json:"order"`
	DiscrepancyID string             `json:"discrepancy_id"`
	Strategy      ResolutionStrategy `json:"strategy"`
	Priority      string             `json:"priority"` // critical, high, medium, low
	Effort        string             `json:"effort"`   // small, medium, large
	Description   string             `json:"description"`
	Blockers      []string           `json:"blockers,omitempty"`
}

PrioritizedAction represents a prioritized resolution action.

type Requirement 

type Requirement struct {
	ID          string   `json:"id"`
	Type        string   `json:"type"` // "feature", "api", "data", "behavior", etc.
	Description string   `json:"description"`
	Section     string   `json:"section"`     // Spec section path
	LineNumber  int      `json:"line_number"` // Line in spec
	Priority    string   `json:"priority"`    // "must", "should", "could"
	Keywords    []string `json:"keywords"`    // Key terms for matching
}

Requirement represents an extracted spec requirement.

type Resolution 

type Resolution struct {
	DiscrepancyID string             `json:"discrepancy_id"`
	Strategy      ResolutionStrategy `json:"strategy"`
	Description   string             `json:"description,omitempty"`
	AssignedTo    string             `json:"assigned_to,omitempty"`
	DueDate       *time.Time         `json:"due_date,omitempty"`
	Status        ResolutionStatus   `json:"status"`
	CreatedAt     time.Time          `json:"created_at"`
	ResolvedAt    *time.Time         `json:"resolved_at,omitempty"`
	Notes         string             `json:"notes,omitempty"`
	LinkedTasks   []string           `json:"linked_tasks,omitempty"`
}

Resolution represents a resolution decision for a discrepancy.

type ResolutionEngine 

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

ResolutionEngine generates resolution plans from alignment results.

func NewResolutionEngine 

func NewResolutionEngine() *ResolutionEngine

NewResolutionEngine creates a new resolution engine with default strategies.

func (*ResolutionEngine) GeneratePlan 

func (e *ResolutionEngine) GeneratePlan(result *AlignmentResult) *ResolutionPlan

GeneratePlan creates a resolution plan from an alignment result.

type ResolutionPlan 

type ResolutionPlan struct {
	ProjectName string              `json:"project_name"`
	GeneratedAt time.Time           `json:"generated_at"`
	AlignmentID string              `json:"alignment_id,omitempty"`
	Resolutions []Resolution        `json:"resolutions"`
	Summary     ResolutionSummary   `json:"summary"`
	Priorities  []PrioritizedAction `json:"priorities,omitempty"`
}

ResolutionPlan contains a complete resolution plan for an alignment result.

func (*ResolutionPlan) GetPendingResolutions 

func (p *ResolutionPlan) GetPendingResolutions() []Resolution

GetPendingResolutions returns all pending resolutions.

func (*ResolutionPlan) GetProgress 

func (p *ResolutionPlan) GetProgress() float64

GetProgress returns the completion percentage.

func (*ResolutionPlan) RenderMarkdown 

func (p *ResolutionPlan) RenderMarkdown() string

RenderMarkdown outputs the resolution plan as Markdown.

func (*ResolutionPlan) UpdateResolution 

func (p *ResolutionPlan) UpdateResolution(discID string, status ResolutionStatus, notes string) error

UpdateResolution updates a resolution in the plan.

type ResolutionStatus 

type ResolutionStatus string

ResolutionStatus indicates the current state of a resolution. 

const (
	StatusPending    ResolutionStatus = "pending"
	StatusInProgress ResolutionStatus = "in_progress"
	StatusResolved   ResolutionStatus = "resolved"
	StatusDeferred   ResolutionStatus = "deferred"
	StatusIgnored    ResolutionStatus = "ignored"
)

type ResolutionStrategy 

type ResolutionStrategy string

ResolutionStrategy defines how to resolve a discrepancy. 

const (
	// StrategyUpdateSpec updates the specification to match implementation.
	StrategyUpdateSpec ResolutionStrategy = "update_spec"
	// StrategyUpdateCode updates the implementation to match specification.
	StrategyUpdateCode ResolutionStrategy = "update_code"
	// StrategyAddSpec adds missing specification for undocumented code.
	StrategyAddSpec ResolutionStrategy = "add_spec"
	// StrategyRemoveCode removes undocumented/deprecated code.
	StrategyRemoveCode ResolutionStrategy = "remove_code"
	// StrategyDefer defers resolution to a later time.
	StrategyDefer ResolutionStrategy = "defer"
	// StrategyIgnore explicitly ignores the discrepancy.
	StrategyIgnore ResolutionStrategy = "ignore"
)

type ResolutionSummary 

type ResolutionSummary struct {
	TotalDiscrepancies int `json:"total_discrepancies"`
	UpdateSpec         int `json:"update_spec"`
	UpdateCode         int `json:"update_code"`
	AddSpec            int `json:"add_spec"`
	RemoveCode         int `json:"remove_code"`
	Deferred           int `json:"deferred"`
	Ignored            int `json:"ignored"`
	Pending            int `json:"pending"`
	Resolved           int `json:"resolved"`
}

ResolutionSummary provides aggregate statistics.

type Severity 

type Severity string

Severity indicates how critical the discrepancy is. 

const (
	SeverityCritical Severity = "critical" // Blocking issue, must fix
	SeverityHigh     Severity = "high"     // Significant deviation
	SeverityMedium   Severity = "medium"   // Notable but not blocking
	SeverityLow      Severity = "low"      // Minor discrepancy
	SeverityInfo     Severity = "info"     // Informational only
)

type TruthItem 

type TruthItem struct {
	Requirement string   `json:"requirement"`
	Status      string   `json:"status"` // "done", "partial", "missing", "diverged"
	CodeRefs    []string `json:"code_refs,omitempty"`
	Notes       string   `json:"notes,omitempty"`
}

TruthItem represents a single requirement's truth status.

type TruthSection 

type TruthSection struct {
	Name        string      `json:"name"`
	Path        string      `json:"path"` // Section path in spec
	Status      TruthStatus `json:"status"`
	Score       float64     `json:"score"`
	Implemented []TruthItem `json:"implemented,omitempty"`
	Partial     []TruthItem `json:"partial,omitempty"`
	Missing     []TruthItem `json:"missing,omitempty"`
	Notes       string      `json:"notes,omitempty"`
}

TruthSection represents a spec section's truth status.

type TruthStatus 

type TruthStatus string

TruthStatus indicates overall alignment status. 

const (
	TruthStatusAligned  TruthStatus = "aligned"  // Spec and code match
	TruthStatusDrifted  TruthStatus = "drifted"  // Minor deviations
	TruthStatusDiverged TruthStatus = "diverged" // Significant misalignment
	TruthStatusUnknown  TruthStatus = "unknown"  // Unable to determine
)

type TruthSummary 

type TruthSummary struct {
	TotalRequirements int     `json:"total_requirements"`
	Implemented       int     `json:"implemented"`
	Partial           int     `json:"partial"`
	Missing           int     `json:"missing"`
	CoveragePercent   float64 `json:"coverage_percent"`
	AlignmentPercent  float64 `json:"alignment_percent"`
}

TruthSummary provides aggregate truth metrics.

Source Files

View all Source files

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.