On-disk gadget cache (#23, part 1)

[ricardojrdez]

First part of #23 (scalability). Adds an opt-in on-disk cache; parallel scanning will follow in a second PR, so this does not close the issue yet.

--cache / --cache-dir

With --cache, the raw (vaddr, bytes) gadget records discovered for a binary are stored on disk and reused on later runs over the same file and options, skipping the scan. --cache-dir overrides the location (default: $XDG_CACHE_HOME/rop3).

The cache key binds the file content hash plus every parameter that affects the record set (depth, flags, arch slice, badchars, badchar-bytes, section layout, which captures --base). A changed binary or option misses cleanly.

Design notes

• Capstone decode objects are not serialisable, so only the raw (vaddr, bytes) records are cached; decodes and the nearest-symbol annotation are always rebuilt locally.
• The scan is split from gadget construction. _scan does a single disassembly pass, so the default (non-cached) path has no extra work; on a warm cache the scan is skipped entirely and gadgets are rebuilt from the records.
• Writes are atomic (os.replace) and best-effort (a write failure logs a warning, never aborts).
• Wired through GadFinder, the Rop3 API (cache=, cache_dir=) and the CLI.

Testing

• 90 tests pass on Python 3.11 and 3.13 (+5).
• test_cache.py covers key invalidation (content and params), store/load round-trip, and that a warm cache yields the same gadgets as a cold scan and as the uncached path.
• End-to-end verified: cold vs warm output identical, cached vs uncached identical, distinct options produce distinct cache entries.

Part of #23.