engine

Documentation

Overview

Package engine provides scan and cleanup orchestration decoupled from the CLI layer. It is used by both the cobra CLI commands and the IPC server.

Package engine provides scan and cleanup orchestration decoupled from the CLI layer. It is used by both the cobra CLI commands and the IPC server.

Index

• Constants
• func FilterSkipped(results []scan.CategoryResult, skip map[string]bool) []scan.CategoryResult
• func RegisterDefaults(e *Engine)
• type CancelledError
  • func (e *CancelledError) Error() string
• type CleanupDone
• type CleanupEvent
• type Engine
  • func New() *Engine
  • func (e *Engine) Categories() []ScannerInfo
  • func (e *Engine) Cleanup(ctx context.Context, token ScanToken, categoryIDs []string) (<-chan CleanupEvent, <-chan CleanupDone)
  • func (e *Engine) Register(s Scanner)
  • func (e *Engine) Run(ctx context.Context, scannerID string) ([]scan.CategoryResult, error)
  • func (e *Engine) ScanAll(ctx context.Context, skip map[string]bool) (<-chan ScanEvent, <-chan ScanResult)
• type ScanError
  • func (e *ScanError) Error() string
  • func (e *ScanError) Unwrap() error
• type ScanEvent
• type ScanResult
• type ScanToken
• type Scanner
  • func NewScanner(info ScannerInfo, fn func() ([]scan.CategoryResult, error)) Scanner
• type ScannerInfo
• type SubCategoryInfo
• type TokenError
  • func (e *TokenError) Error() string

Constants

const (
	EventScannerStart = "scanner_start"
	EventScannerDone  = "scanner_done"
	EventScannerError = "scanner_error"
)

Scan event types.

const (
	EventCleanupCategoryStart = "cleanup_category_start"
	EventCleanupEntry         = "cleanup_entry"
	EventCleanupDone          = "cleanup_done"
	EventCleanupError         = "cleanup_error"
)

Cleanup event types.

Functions

func FilterSkipped

func FilterSkipped(results []scan.CategoryResult, skip map[string]bool) []scan.CategoryResult

FilterSkipped removes categories matching the skip set from results. It returns the input unchanged if skip is empty.

func RegisterDefaults

func RegisterDefaults(e *Engine)

RegisterDefaults registers all built-in scanner groups with the engine. Each scanner wraps an existing pkg/*/Scan() function via the adapter pattern.

Types

type CancelledError

type CancelledError struct {
	Operation string // "scan" or "cleanup"
}

CancelledError indicates the operation was cancelled via context.

func (*CancelledError) Error

func (e *CancelledError) Error() string

type CleanupDone

type CleanupDone struct {
	Result cleanup.CleanupResult
	Err    error
}

CleanupDone holds the final outcome of a Cleanup operation.

type CleanupEvent

type CleanupEvent struct {
	// Type is one of the EventCleanup* constants.
	Type string
	// Category is the human-readable category description.
	Category string
	// EntryPath is the filesystem path being cleaned (empty for category-start events).
	EntryPath string
	// Current is the 1-based item index across all categories.
	Current int
	// Total is the overall item count.
	Total int
}

CleanupEvent reports progress during a cleanup operation.

type Engine

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

Engine orchestrates scanning and cleanup operations. It holds the scanner registry and token store. Safe for concurrent use.

func New

func New() *Engine

New creates an Engine with an empty scanner registry.

func (*Engine) Categories

func (e *Engine) Categories() []ScannerInfo

Categories returns metadata for all registered scanners.

func (*Engine) Cleanup

func (e *Engine) Cleanup(ctx context.Context, token ScanToken, categoryIDs []string) (<-chan CleanupEvent, <-chan CleanupDone)

Cleanup removes files for the given categories from a prior scan. The token must match a prior ScanAll call and is consumed (one-time use). If categoryIDs is empty, all categories from the scan are cleaned. Returns an events channel for progress and a done channel for the final result.

func (*Engine) Register

func (e *Engine) Register(s Scanner)

Register adds a scanner to the engine's registry.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, scannerID string) ([]scan.CategoryResult, error)

Run executes a single scanner synchronously and returns its results. Returns an error if the scanner ID is not found, the context is cancelled, or the scanner itself fails.

func (*Engine) ScanAll

func (e *Engine) ScanAll(ctx context.Context, skip map[string]bool) (<-chan ScanEvent, <-chan ScanResult)

ScanAll runs all registered scanners sequentially, streaming events through the returned channel. The done channel receives exactly one ScanResult when all scanners complete (or context is cancelled). The skip set filters category IDs from the final output.

type ScanError

type ScanError struct {
	ScannerID string
	Err       error
}

ScanError wraps a scanner-level error with the scanner ID. It supports errors.As() for typed error handling by the server.

func (*ScanError) Error

func (e *ScanError) Error() string

func (*ScanError) Unwrap

func (e *ScanError) Unwrap() error

type ScanEvent

type ScanEvent struct {
	// Type is one of "scanner_start", "scanner_done", "scanner_error".
	Type string
	// ScannerID identifies which scanner group emitted the event.
	ScannerID string
	// Label is the human-readable scanner group name.
	Label string
	// Results is populated on "scanner_done" events.
	Results []scan.CategoryResult
	// Err is populated on "scanner_error" events.
	Err error
}

ScanEvent reports progress during a scan operation.

type ScanResult

type ScanResult struct {
	Results []scan.CategoryResult
	Token   ScanToken
}

ScanResult holds the final aggregated output of ScanAll.

type ScanToken

type ScanToken string

ScanToken is an opaque identifier linking a cleanup to a prior scan.

type Scanner

type Scanner interface {
	// Scan executes the scan and returns category results.
	Scan() ([]scan.CategoryResult, error)
	// Info returns metadata about this scanner.
	Info() ScannerInfo
}

Scanner is the interface all scanners implement. It provides both scan execution and metadata access.

func NewScanner

func NewScanner(info ScannerInfo, fn func() ([]scan.CategoryResult, error)) Scanner

NewScanner creates a Scanner from metadata and a scan function. This adapter pattern wraps existing pkg/*/Scan() functions without modifying their signatures.

type ScannerInfo

type ScannerInfo struct {
	// ID is a machine-readable identifier (e.g. "system", "browser").
	ID string
	// Name is a human-readable label (e.g. "System Caches").
	Name string
	// Description explains what this scanner group covers.
	Description string
	// CategoryIDs lists the category identifiers this scanner can produce.
	CategoryIDs []string
	// SkipFlag is the group-level skip flag name (e.g. "system-caches").
	SkipFlag string
	// SubCategories provides rich metadata for each sub-category.
	SubCategories []SubCategoryInfo
	// RiskLevel is the dominant risk level for the group (may be empty
	// when risk is per-category rather than per-group).
	RiskLevel string
}

ScannerInfo holds metadata about a scanner group. It provides the information needed by the server's "categories" method without extra mapping.

type SubCategoryInfo

type SubCategoryInfo struct {
	// ID is the category identifier (e.g. "system-caches", "browser-chrome").
	ID string
	// Label is a human-readable display name (e.g. "User App Caches").
	Label string
	// SkipFlag is the individual skip flag name (e.g. "chrome").
	// Empty string if no individual skip flag exists.
	SkipFlag string
	// RiskLevel is the deletion risk ("safe", "moderate", "risky").
	RiskLevel string
}

SubCategoryInfo holds metadata about a single sub-category within a scanner group. It is used by the server's "categories" response to provide rich per-category data to clients.

type TokenError

type TokenError struct {
	Token  ScanToken
	Reason string
}

TokenError indicates an invalid or expired scan token.

func (*TokenError) Error

func (e *TokenError) Error() string