Class: Rigor::Cache::IncrementalSnapshot

Inherits:
Object
  • Object
show all
Defined in:
lib/rigor/cache/incremental_snapshot.rb

Overview

ADR-46 — disk persistence for the incremental analyzer’s per-file state, so a ‘–incremental` session survives across processes (one `rigor check` invocation reads the prior run’s per-file diagnostics + dependency graph, re-analyzes only the changed closure, and serves the rest from disk).

Unlike ADR-45’s whole-run cache (record-and-validate ONE entry, invalidated by any analyzed-file change), this snapshot is loaded UNCONDITIONALLY when the global fingerprint matches — the per-file digests inside it drive the incremental re-analysis decision; they do not gate the load. The fingerprint captures the inputs whose change requires a full rebuild — the resolved configuration, the RBS environment, the engine version — but NOT the analyzed source contents. A fingerprint mismatch (config / gem / version change) drops the snapshot and forces a full re-analysis, the conservative direction.

Every operation is fault-tolerant: a missing, unreadable, schema- mismatched, fingerprint-mismatched, or corrupt snapshot loads as nil (→ a cold full run), and a write failure is swallowed (→ the next run is cold). A cache must never break a run (the ADR-45 invariant).

Defined Under Namespace

Classes: Payload

Constant Summary collapse

SCHEMA =

Bump when the on-disk shape changes so stale snapshots are ignored rather than mis-deserialized.

4

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(root:) ⇒ IncrementalSnapshot

Returns a new instance of IncrementalSnapshot.



97
98
99
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 97

def initialize(root:)
  @path = File.join(root.to_s, "incremental", "snapshot.bin")
end

Instance Attribute Details

#path ⇒ Object (readonly)

Returns the value of attribute path.



101
102
103
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 101

def path
  @path
end

Class Method Details

.fingerprint(configuration:, roots:) ⇒ Object

The global fingerprint that gates a snapshot load: a digest of the inputs whose change requires a full rebuild — the engine version + schema, the resolved configuration, the analysis roots (the path arguments, e.g. ‘[“lib”]`, NOT the expanded file list — so a snapshot is keyed to an invocation’s roots but adding / removing a file under them is handled incrementally by the session, not a full rebuild), the resolved gem set (‘Gemfile.lock` / `rbs_collection`), and the project’s own RBS (‘signature_paths` file contents). Built WITHOUT constructing the RBS environment so the warm path can gate the load cheaply, before the costly env build. The `–verify-incremental` gate is the safety net for any under-capture (it would surface as an incremental-vs-full mismatch). Returns nil on any error → the caller falls back to a non-persisted run.



63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 63

def self.fingerprint(configuration:, roots:)
  parts = [
    "engine:#{Rigor::VERSION}:#{SCHEMA}",
    "config:#{Digest::SHA256.hexdigest(Marshal.dump(configuration.to_h))}",
    "roots:#{Array(roots).map(&:to_s).sort.join("\n")}",
    "gems:#{digest_file_if_present('Gemfile.lock')}",
    "rbs_collection:#{digest_file_if_present('rbs_collection.lock.yaml')}",
    "sig:#{digest_signature_paths(configuration.signature_paths)}"
  ]
  Digest::SHA256.hexdigest(parts.join("\x00"))
rescue StandardError
  nil
end

Instance Method Details

#load(fingerprint:) ⇒ Object

The stored Payload, or nil when absent / unreadable / schema or fingerprint mismatch / corrupt. Never raises.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 105

def load(fingerprint:)
  data = Marshal.load(File.binread(@path)) # rubocop:disable Security/MarshalLoad
  return nil unless data.is_a?(Hash) && data[:schema] == SCHEMA && data[:fingerprint] == fingerprint

  Payload.new(
    cache: data[:cache], sources: data[:sources],
    digests: data[:digests], analyzed: data[:analyzed],
    symbol_sources: data[:symbol_sources] || {},
    ancestry_sources: data[:ancestry_sources] || {},
    symbol_fingerprints: data[:symbol_fingerprints] || {},
    missing: data[:missing] || {},
    class_decls: data[:class_decls] || {}
  )
rescue StandardError
  nil
end

#save(fingerprint:, payload:) ⇒ Object

Persist ‘payload` under `fingerprint`. Writes via a temp file + atomic rename so a concurrent reader never sees a half-written snapshot. Returns true on success, false on any failure (never raises).



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 126

def save(fingerprint:, payload:)
  FileUtils.mkdir_p(File.dirname(@path))
  blob = Marshal.dump(
    schema: SCHEMA, fingerprint: fingerprint,
    cache: payload.cache, sources: payload.sources,
    digests: payload.digests, analyzed: payload.analyzed,
    symbol_sources: payload.symbol_sources,
    ancestry_sources: payload.ancestry_sources,
    symbol_fingerprints: payload.symbol_fingerprints,
    missing: payload.missing,
    class_decls: payload.class_decls
  )
  tmp = "#{@path}.#{Process.pid}.tmp"
  File.binwrite(tmp, blob)
  File.rename(tmp, @path)
  true
rescue StandardError
  false
end