state

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

• Variables
• func BuildResolvedTodoSignals(repoPath string, removed []SignalMeta) []signal.RawSignal
• func CollectorsMatch(prev *ScanState, current []string) bool
• func FilterNew(signals []signal.RawSignal, prev *ScanState) []signal.RawSignal
• func FormatDiff(diff *DiffResult, repoPath string, w io.Writer) error
• func Save(repoPath string, s *ScanState) error
• func SaveWorkspace(repoPath, workspace string, s *ScanState) error
• type AnnotatedSignal
  • func AnnotateRemovedSignals(repoPath string, removed []SignalMeta) []AnnotatedSignal
• type DiffResult
  • func ComputeDiff(prev, current *ScanState) *DiffResult
• type MovedSignal
• type ScanState
  • func Build(repoPath string, collectors []string, signals []signal.RawSignal) *ScanState
  • func Load(repoPath string) (*ScanState, error)
  • func LoadWorkspace(repoPath, workspace string) (*ScanState, error)
• type SignalMeta

Variables

var FS testable.FileSystem = testable.DefaultFS

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

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

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 SaveWorkspace

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.

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 MovedSignal

type MovedSignal struct {
	Previous SignalMeta
	Current  SignalMeta
}

MovedSignal tracks a signal that moved between scans.

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

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.