engine

Documentation

Overview

Package engine implements the pipeline orchestrator that runs extractors, classify, rules, status, metrics, and renderers in sequence. Port interfaces (Extractor, PatternProvider, SymbolResolver, Renderer) live in internal/ports.

Index

• func PairEvidence(g *graph.Graph, mm config.ModuleMap, wanted map[string]struct{}) map[string]string
• func Run(ctx context.Context, in RunInput) (diagnostic.Diagnostic, error)
• type Mode
• type RunInput

Functions

func PairEvidence

func PairEvidence(g *graph.Graph, mm config.ModuleMap, wanted map[string]struct{}) map[string]string

PairEvidence computes the current evidence hash per module pair (keyed by labels.Key): HashItems over "fromPath\x00toPath\x00kind" for every import-graph edge whose endpoints resolve to that ordered pair. Only pairs in wanted are hashed (pairs of interest are few; the graph can be large).

Exported because enrich (cmd) must stamp drafts with EXACTLY the hash the engine will later verify — one computation, two callers.

func Run

func Run(ctx context.Context, in RunInput) (diagnostic.Diagnostic, error)

Run executes the full archfit pipeline and returns the assembled Diagnostic.

Pipeline stages:

1. Run each extractor sequentially; apply symbol resolution to edges; merge Facts; build graph.
2. Run PatternProvider to gather structural matches; build per-file evidence index.
3. Classify edges: classify.Run → coupling.Index.
4. Apply rules: rule.Check(g, Evidence{PatternMatches}) per rule → raw findings (flattened).
5. Assign statuses: status.Assign → lifecycle-tagged findings.
6. Compute metrics: build CollectedSignals, run each metric → MetricResult slice.
7. Resolve evidence: join module labels and severity onto findings.
8. Collect advisory findings: coupling edges with Severity != "" + staleness.Check.
9. Assemble Diagnostic: fill Summary, compute verdict, attach structural facts. Advisory findings included only when mode.Advisory. Return (Diagnostic, nil) on success; (Diagnostic, error) on hard error.

Rendering is the caller's responsibility (cmd renders to deps.Stdout).

Types

type Mode

type Mode struct {
	Base       string   // git ref to diff against (empty = none)
	Head       string   // git ref of the current HEAD (empty = working tree)
	Full       bool     // if true, full-repo mode (no diff filter)
	Advisory   bool     // if true, include advisory findings (bc/imbalanced_coupling, map/staleness) in Findings and Summary.Warnings
	ReportOnly bool     // report-only: metric regressions are non-blocking
	Formats    []string // output formats to render (e.g. ["json", "console"])
}

Mode controls how the engine run behaves.

type RunInput

type RunInput struct {
	Mode        Mode
	Scope       scope.Scope
	Classify    config.ClassifyConfig
	Staleness   config.StalenessConfig
	Waivers     config.WaiverSet
	Extractors  []ports.Extractor
	Patterns    ports.PatternProvider
	PatternCfg  config.PatternConfig
	Resolver    ports.SymbolResolver
	Syntax      ports.SyntaxProvider // syntactic declaration/route provider; nil = Nop
	SyntaxCfg   config.SyntaxConfig  // derived from ForSyntax(); Enabled gates the call
	Rules       []rules.Rule
	Metrics     []metrics.Metric
	Accepted    status.AcceptedSet
	BaseMetrics diagnostic.MetricSnapshot // baseline metric snapshot; nil = no baseline
	Labels      []labels.Label            // pinned coupling labels; nil = none
	Signals     signal.RunSignals
	Now         time.Time
	// PrimaryExtractorTools names the per-language file extractors whose coverage
	// the scorecard treats as load-bearing (see diagnostic.Diagnostic). Supplied by
	// the composition root from the language registry; attached to the Diagnostic so
	// the score package needs no hardcoded tool list. Empty = score's default set.
	PrimaryExtractorTools []string
	// ConfigHash is the sha256 hex digest of the raw .archfit.yaml bytes,
	// computed by the caller before parsing. Empty when no config file was loaded.
	// Attached to the Diagnostic for reproducibility: same config + same repo → same hash.
	ConfigHash string
}

RunInput carries everything a pipeline run needs. Fields mirror the pipeline stages; all are required unless noted.