File Fingerprinting & Up-to-Date Checks for Actions#

// pkg/fingerprint/fingerprint.go

package fingerprint

import "context"

// Result holds the comparison outcome for an action's sources and generates.
type Result struct {
    // Stale is true when the action should be re-executed.
    Stale bool

    // CurrentHash is the SHA-256 hash of current source files.
    CurrentHash string

    // PreviousHash is the stored hash of sources from last successful run (empty on first run).
    PreviousHash string

    // GeneratesHash is the SHA-256 hash of current generated files.
    GeneratesHash string

    // PreviousGeneratesHash is the stored hash of generates from last successful run.
    PreviousGeneratesHash string

    // Reason provides a human-readable explanation.
    Reason Reason
}

// Reason categorizes why an action is stale or up-to-date.
type Reason string

const (
    ReasonFirstRun          Reason = "first run"
    ReasonSourcesChanged    Reason = "sources changed"
    ReasonGeneratesModified Reason = "generates modified"
    ReasonGeneratesMissing  Reason = "generates missing"
    ReasonUpToDate          Reason = "up-to-date"
)

// pkg/fingerprint/fingerprint.go

// Checker evaluates whether an action's sources/generates have changed since the last run.
type Checker interface {
    // Check compares current file fingerprints against stored state.
    // baseDir is the working directory for resolving relative globs.
    Check(ctx context.Context, actionName string, sources, generates []string, baseDir string) (*Result, error)

    // Record stores the current fingerprint (sources + generates) after a successful action.
    Record(ctx context.Context, actionName string, sources, generates []string, baseDir string) error
}

// pkg/fingerprint/hash.go

// HashFiles computes a deterministic SHA-256 hash over the contents of all
// files matching the given glob patterns, resolved relative to baseDir.
// Files are sorted lexicographically before hashing for determinism.
// Returns empty string and nil error if patterns is empty.
func HashFiles(baseDir string, patterns []string) (string, error)

// pkg/fingerprint/glob.go

// ExpandGlobs resolves glob patterns against the filesystem, returning
// a sorted, deduplicated list of matching file paths (relative to baseDir).
// Supports ** for recursive matching.
func ExpandGlobs(baseDir string, patterns []string) ([]string, error)

// pkg/fingerprint/state.go

// SourcesKey returns the state entry key for an action's source fingerprint.
// Format: "__fingerprint:<actionName>:sources"
func SourcesKey(actionName string) string

// GeneratesKey returns the state entry key for an action's generates fingerprint.
// Format: "__fingerprint:<actionName>:generates"
func GeneratesKey(actionName string) string

// LoadHash retrieves a previously stored hash from state.
func LoadHash(stateData *state.Data, key string) string

// SaveHash stores a hash into state data for persistence.
func SaveHash(stateData *state.Data, key, hash string)

// In pkg/action/types.go, added to Action struct:

// Sources declares glob patterns for input files this action depends on.
// When provided (and state is enabled), the action is skipped if source
// files haven't changed and generated files haven't been externally modified
// since the last successful run.
Sources []string `json:"sources,omitempty" yaml:"sources,omitempty" doc:"Glob patterns for input file dependencies" maxItems:"100"`

// Generates declares glob patterns for output files this action produces.
// If all generated files exist and their checksums match the stored hashes
// from the last successful run, the action is skipped. Manual edits to
// generated files will trigger re-execution.
Generates []string `json:"generates,omitempty" yaml:"generates,omitempty" doc:"Glob patterns for output files" maxItems:"100"`

// Fingerprint controls fingerprint behavior for up-to-date checks.
// By default (scope: all), both file hashes and resolved input hashes are checked.
// Set scope to "files" to skip input hashing when inputs contain volatile values.
// Requires sources to be set.
Fingerprint *FingerprintConfig `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty" doc:"Fingerprint configuration for up-to-date checks"`

// FingerprintScope controls which data is included in up-to-date fingerprint checks.
type FingerprintScope string // "all" (default) | "files"

// FingerprintConfig controls fingerprint behavior for an action.
type FingerprintConfig struct {
    Scope FingerprintScope `json:"scope,omitempty" yaml:"scope,omitempty"`
}

// In pkg/action/types.go:

// SkipReasonUpToDate indicates the action was skipped because its source
// fingerprint and generates fingerprint both match stored state.
SkipReasonUpToDate SkipReason = "up-to-date"

1. Previous state exists for this action
2. Sources hash == stored sources hash         (inputs unchanged)
3. All generates files exist                   (outputs present)
4. Generates hash == stored generates hash     (outputs not modified externally)

1. Check when: condition → skip with SkipReasonCondition if false
2. Check fingerprint (sources + generates) → skip with SkipReasonUpToDate if up-to-date
3. Resolve inputs
4. Execute action
5. On success: record new fingerprints (sources + generates)

// pkg/fingerprint/errors.go

var (
    // ErrNoMatches is returned when a glob pattern matches zero files.
    ErrNoMatches = errors.New("glob pattern matched no files")

    // ErrPatternInvalid is returned for malformed glob patterns.
    ErrPatternInvalid = errors.New("invalid glob pattern")
)

apiVersion: scafctl/v1
kind: Solution
metadata:
  name: go-build
  version: 1.0.0

state:
  enabled: true
  backend:
    provider: file
    inputs:
      path: ".scafctl/state.json"

spec:
  resolvers:
    app-name:
      value: myapp

  workflow:
    actions:
      build:
        description: Build the Go binary
        provider: exec
        inputs:
          command:
            tmpl: "go build -o dist/{{ .app-name }} ./cmd/{{ .app-name }}"
        sources:
          - "cmd/**/*.go"
          - "pkg/**/*.go"
          - "internal/**/*.go"
          - go.mod
          - go.sum
        generates:
          - "dist/myapp"

      test:
        description: Run unit tests
        provider: exec
        inputs:
          command: go test ./...
        sources:
          - "**/*_test.go"
          - "pkg/**/*.go"
          - "internal/**/*.go"

Phase 1 (CheckFiles) -- before input resolution:
  1. Hash source files
  2. Hash generated files
  3. Compare against stored hashes
  4. If files changed -> stale (skip Phase 2, proceed to execute)

Phase 2 (CheckInputs) -- after input resolution:
  1. Hash resolved inputs (JSON-serialized, SHA-256)
  2. Compare against stored inputs hash
  3. If inputs changed -> stale (proceed to execute)
  4. If inputs unchanged -> up-to-date (skip action)

// pkg/fingerprint/fingerprint.go

const ReasonInputsChanged Reason = "inputs changed"

// Result now includes:
type Result struct {
    // ... existing fields ...
    InputsHash         string  // SHA-256 of current resolved inputs
    PreviousInputsHash string  // Stored hash from last run
}

// Check is split into two methods:
func (c *Checker) CheckFiles(actionName string, sources, generates []string, baseDir string) (*Result, error)
func (c *Checker) CheckInputs(actionName string, resolvedInputs map[string]any) (*Result, error)

// Record now accepts resolved inputs:
func (c *Checker) Record(actionName string, sources, generates []string, baseDir string, resolvedInputs map[string]any) error

// pkg/fingerprint/hash.go

// HashInputs computes a deterministic SHA-256 hash of resolved action inputs.
// Uses JSON marshaling for deterministic serialization (Go's encoding/json
// sorts map keys). Returns empty string for nil or empty inputs.
func HashInputs(inputs map[string]any) (string, error)

// pkg/fingerprint/state.go

// State key format: "__fingerprint:<action>:inputs"
func inputsKey(actionName string) string
func LoadInputsHash(stateData *state.Data, actionName string) string
// SaveHashes now stores inputs hash alongside sources and generates hashes.
func SaveHashes(stateData *state.Data, actionName, sourcesHash, generatesHash, inputsHash string)

// Phase 1: File-based check (cheap, before input resolution)
fpResult, err := fpChecker.CheckFiles(actionName, action.Sources, action.Generates, cwd)
if fpResult.Stale {
    // Files changed -- must re-execute, resolve inputs and run
    resolvedInputs := resolveInputs(...)
    callProvider(...)
    fpChecker.Record(actionName, sources, generates, cwd, resolvedInputs)
    return
}

// Phase 2: Input-based check (after resolver evaluation)
resolvedInputs := resolveInputs(...)
inputResult, err := fpChecker.CheckInputs(actionName, resolvedInputs)
if inputResult.Stale {
    // Inputs changed -- re-execute
    callProvider(...)
    fpChecker.Record(actionName, sources, generates, cwd, resolvedInputs)
    return
}

// Both files and inputs match -- skip
skip(SkipReasonUpToDate)