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. 5: the blob is zlib-deflated (ADR-54 WD2 parity with ‘Store` entries — the snapshot is the one cache artefact that does not go through `Store`); a raw pre-5 blob fails the inflate and loads as nil, the usual fault-tolerant cold-run path.

5

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(root:) ⇒ IncrementalSnapshot

Returns a new instance of IncrementalSnapshot.



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

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.



106
107
108
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 106

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.



68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 68

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.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 110

def load(fingerprint:)
  data = Marshal.load(Zlib::Inflate.inflate(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).



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/rigor/cache/incremental_snapshot.rb', line 131

def save(fingerprint:, payload:)
  FileUtils.mkdir_p(File.dirname(@path))
  raw = 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
  )
  blob = Zlib::Deflate.deflate(raw)
  tmp = "#{@path}.#{Process.pid}.tmp"
  File.binwrite(tmp, blob)
  File.rename(tmp, @path)
  true
rescue StandardError
  false
end