state

package
v1.4.1 Latest Latest
Warning

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

 Go to latest Published: Feb 22, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package state manages persisted scan state for delta scanning.

When --delta is active, stringer saves a record of all signal hashes produced by a scan. On subsequent runs, this state is loaded and used to filter output to only new signals.

Index

Constants

View Source 
const DefaultWindowSize = 5

DefaultWindowSize is the default number of entries to compare for trends.

Variables

View Source 
var FS testable.FileSystem = testable.DefaultFS

FS is the file system implementation used by this package. Override in tests with a testable.MockFileSystem.

View Source 
var GitOpener testable.GitOpener = testable.DefaultGitOpener

GitOpener is the opener used to access git repositories in the state package. Defaults to testable.DefaultGitOpener. Tests can replace this to inject mocks.

Functions

func BuildResolvedTodoSignals added in v0.5.0 

func BuildResolvedTodoSignals(repoPath string, removed []SignalMeta) []signal.RawSignal

BuildResolvedTodoSignals converts removed TODO signals into closed RawSignals. When delta scanning detects that a TODO has disappeared, this function creates a pre-closed signal representing the resolved work item.

func CollectorsMatch 

func CollectorsMatch(prev *ScanState, current []string) bool

CollectorsMatch returns true if the previous state's collector list matches the current list (order-independent).

func FilterNew 

func FilterNew(signals []signal.RawSignal, prev *ScanState) []signal.RawSignal

FilterNew returns only the signals whose hashes are not present in prev. If prev is nil, all signals are considered new. The order of signals is preserved.

func FormatDiff 

func FormatDiff(diff *DiffResult, repoPath string, w io.Writer) error

FormatDiff writes a human-readable diff summary to w. The output uses +/- notation similar to git diff.

func Save 

func Save(repoPath string, s *ScanState) error

Save writes the scan state to <repoPath>/.stringer/last-scan.json. It creates the .stringer directory if it does not exist.

func SaveHistory added in v1.3.0 

func SaveHistory(repoPath string, h *ScanHistory) error

SaveHistory writes the scan history to <repoPath>/.stringer/scan-history.json. It creates the .stringer directory if it does not exist.

func SaveHistoryWorkspace added in v1.3.0 

func SaveHistoryWorkspace(repoPath, workspace string, h *ScanHistory) error

SaveHistoryWorkspace writes the scan history for a specific workspace. When workspace is empty, it writes to <repoPath>/.stringer/scan-history.json. When set, it writes to <repoPath>/.stringer/<workspace>/scan-history.json.

func SaveWorkspace added in v1.0.0 

func SaveWorkspace(repoPath, workspace string, s *ScanState) error

SaveWorkspace writes the scan state for a specific workspace. When workspace is empty, it writes to <repoPath>/.stringer/last-scan.json. When set, it writes to <repoPath>/.stringer/<workspace>/last-scan.json.

func SortedKeys added in v1.3.0 

func SortedKeys(m map[string]int) []string

SortedKeys returns the sorted keys from a map[string]int.

Types

type AnnotatedSignal 

type AnnotatedSignal struct {
	SignalMeta
	Resolution string // "file_deleted", "moved", or ""
}

AnnotatedSignal extends SignalMeta with resolution context.

func AnnotateRemovedSignals 

func AnnotateRemovedSignals(repoPath string, removed []SignalMeta) []AnnotatedSignal

AnnotateRemovedSignals marks removed signals with resolution context. Signals referring to deleted files are marked as "file_deleted". This helps users distinguish between resolved work vs stale signals.

type DiffResult 

type DiffResult struct {
	Added   []SignalMeta  // signals in current but not previous
	Removed []SignalMeta  // signals in previous but not current
	Moved   []MovedSignal // signals with same title/kind but different location
}

DiffResult holds the comparison between two scans.

func ComputeDiff 

func ComputeDiff(prev, current *ScanState) *DiffResult

ComputeDiff compares previous and current scan states. It categorizes signals as added, removed, or moved. Moved detection: if a removed and added signal share the same Title+Kind but differ in FilePath or Line, they are treated as moved rather than added/removed.

type Direction added in v1.3.0 

type Direction string

Direction describes whether a metric is improving, stable, or degrading. 

const (
	Improving Direction = "improving"
	Stable    Direction = "stable"
	Degrading Direction = "degrading"
)

type HistoryEntry added in v1.3.0 

type HistoryEntry struct {
	Timestamp       time.Time      `json:"timestamp"`
	GitHead         string         `json:"git_head"`
	TotalSignals    int            `json:"total_signals"`
	CollectorCounts map[string]int `json:"collector_counts"`
	KindCounts      map[string]int `json:"kind_counts"`
}

HistoryEntry captures summary metrics from a single scan.

func BuildHistoryEntry added in v1.3.0 

func BuildHistoryEntry(repoPath string, result *signal.ScanResult) HistoryEntry

BuildHistoryEntry creates a HistoryEntry from a scan result.

type MovedSignal 

type MovedSignal struct {
	Previous SignalMeta
	Current  SignalMeta
}

MovedSignal tracks a signal that moved between scans.

type ScanHistory added in v1.3.0 

type ScanHistory struct {
	Version string         `json:"version"`
	Entries []HistoryEntry `json:"entries"`
}

ScanHistory stores a time-series of scan summary entries.

func AppendEntry added in v1.3.0 

func AppendEntry(h *ScanHistory, entry HistoryEntry) *ScanHistory

AppendEntry adds an entry to the history and enforces the FIFO cap.

func LoadHistory added in v1.3.0 

func LoadHistory(repoPath string) (*ScanHistory, error)

LoadHistory reads the scan history file from <repoPath>/.stringer/scan-history.json. If the file does not exist, it returns (nil, nil).

func LoadHistoryWorkspace added in v1.3.0 

func LoadHistoryWorkspace(repoPath, workspace string) (*ScanHistory, error)

LoadHistoryWorkspace reads the scan history file for a specific workspace. When workspace is empty, it reads from <repoPath>/.stringer/scan-history.json. When set, it reads from <repoPath>/.stringer/<workspace>/scan-history.json.

type ScanState 

type ScanState struct {
	Version       string       `json:"version"`
	ScanTimestamp time.Time    `json:"scan_timestamp"`
	GitHead       string       `json:"git_head"`
	Collectors    []string     `json:"collectors"`
	SignalHashes  []string     `json:"signal_hashes"`
	SignalMetas   []SignalMeta `json:"signal_metas,omitempty"`
	SignalCount   int          `json:"signal_count"`
}

ScanState represents persisted state from a previous scan.

func Build 

func Build(repoPath string, collectors []string, signals []signal.RawSignal) *ScanState

Build creates a new ScanState from the current scan results. It captures the git HEAD (if available) and hashes of all signals.

func Load 

func Load(repoPath string) (*ScanState, error)

Load reads the scan state file from <repoPath>/.stringer/last-scan.json. If the file does not exist, it returns (nil, nil).

func LoadWorkspace added in v1.0.0 

func LoadWorkspace(repoPath, workspace string) (*ScanState, error)

LoadWorkspace reads the scan state file for a specific workspace. When workspace is empty, it reads from <repoPath>/.stringer/last-scan.json. When set, it reads from <repoPath>/.stringer/<workspace>/last-scan.json.

type SignalMeta 

type SignalMeta struct {
	Hash     string `json:"hash"`
	Source   string `json:"source"`
	Kind     string `json:"kind"`
	FilePath string `json:"file_path"`
	Line     int    `json:"line,omitempty"`
	Title    string `json:"title"`
}

SignalMeta stores metadata about a signal for diff output.

type TrendLine added in v1.3.0 

type TrendLine struct {
	Current   int       `json:"current"`
	Previous  int       `json:"previous"`
	Delta     int       `json:"delta"`
	Direction Direction `json:"direction"`
}

TrendLine captures the directional change for a single metric.

type TrendResult added in v1.3.0 

type TrendResult struct {
	TotalTrend      TrendLine            `json:"total_trend"`
	CollectorTrends map[string]TrendLine `json:"collector_trends"`
	KindTrends      map[string]TrendLine `json:"kind_trends"`
	WindowSize      int                  `json:"window_size"`
	DataPoints      int                  `json:"data_points"`
}

TrendResult holds computed trends across all metrics.

func ComputeTrends added in v1.3.0 

func ComputeTrends(h *ScanHistory, windowSize int) *TrendResult

ComputeTrends analyzes a scan history and produces directional trends. It compares the oldest and newest entries within the window. Returns nil if fewer than 2 data points are available.

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.