tweak_store.hpp

Go to the documentation of this file.

// tweak_store.hpp — In-memory inspector tweak table and disk persistence.
//
// On-disk schema (mirrors @pulp/import-ir/src/tweaks.ts TweaksFile with
// Pulp's bypass, lock, version, and source-tag extensions):
//
//   {
//     "$schema": "pulp-tweaks://v1",
//     "version": 1,
//     "tweaks":   Record<anchor, Record<dottedPath, value>>,
//     "bypassed": Record<anchor, true | string[]>,
//     "locked":   string[]                                     // optional
//     "sources":  Record<anchor, Record<dottedPath, string>>   // optional
//   }
//
// Bypass is a sibling overlay, not `applied:false` mixed into the
// dotted-path tweak map. That preserves v1 backwards compatibility —
// old files with only `tweaks` still load.
//
// `locked` is a third sibling overlay — a flat list of anchor ids the
// user has marked as protected from bulk-clear / reimport. It mirrors
// the bypass overlay shape (anchor-keyed, additive, omitted entirely
// when empty) so old v1 files still load and a build that doesn't
// understand `locked` simply ignores it.
//
// Atomic-write contract: save_to_disk() writes to `<path>.tmp` then
// renames over the target so a crash mid-write never leaves a
// half-flushed file at the canonical path.
 
#pragma once
 
#include <choc/containers/choc_Value.h>
 
#include <cstddef>
#include <cstdint>
#include <mutex>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <unordered_set>
#include <variant>
#include <vector>
 
namespace pulp::inspect {

class TweakStore {
public:
    struct Record {
        std::string anchor_id;
        std::string property_path;  // dotted, e.g. "paint.backgroundColor"
        choc::value::Value value;
        std::string source;         // optional adapter / origin tag (free-form)
    };

    using BypassValue = std::variant<bool, std::vector<std::string>>;
 
    TweakStore() = default;
 
    // ── Mutation ────────────────────────────────────────────────────

    std::size_t apply_tweak(std::string_view anchor_id,
                            std::string_view property_path,
                            choc::value::Value value,
                            std::string_view source = {});

    struct BatchEntry {
        std::string property_path;  
        choc::value::Value value;
    };

    std::size_t apply_tweaks_batch(std::string_view anchor_id,
                                   std::vector<BatchEntry> entries,
                                   std::string_view source = {});

    bool remove_tweak(std::string_view anchor_id,
                      std::string_view property_path);

    std::size_t remove_anchor(std::string_view anchor_id);

    void clear();

    void set_bypass(std::string_view anchor_id, BypassValue value);

    void clear_bypass(std::string_view anchor_id);

    void set_locked(std::string_view anchor_id, bool locked);

    void clear_lock(std::string_view anchor_id);
 
    // ── Inspection ──────────────────────────────────────────────────

    std::size_t count() const;

    std::vector<Record> list_tweaks() const;

    std::optional<choc::value::Value>
    lookup(std::string_view anchor_id, std::string_view property_path) const;

    bool is_bypassed(std::string_view anchor_id,
                     std::string_view property_path) const;

    std::optional<BypassValue>
    bypass_for(std::string_view anchor_id) const;

    std::vector<std::string> bypassed_anchors() const;

    bool is_locked(std::string_view anchor_id) const;

    std::vector<std::string> locked_anchors() const;
 
    // ── Disk persistence ────────────────────────────────────────────

    static constexpr int kSchemaVersion = 1;

    struct DiskResult {
        bool ok = false;
        std::string error;
        std::size_t tweak_count = 0;
        std::size_t bypass_count = 0;
        std::string path;       // resolved path actually used
    };

    DiskResult load_from_disk(std::string_view path = {});

    DiskResult save_to_disk(std::string_view path = {}) const;

    void set_auto_save(bool enabled, std::string_view path = {});

    bool auto_save_enabled() const;

    std::string auto_save_path() const;

    static std::string default_tweaks_path();

    std::string to_json() const;

    DiskResult from_json(std::string_view json);
 
    // ── Drift detection ─────────────────────────────────────────────
    //
    // A tweak is keyed by (anchor_id, property_path). After a design
    // re-import the live view tree may no longer carry an anchor a
    // stored tweak references — that tweak is "orphaned" and silently
    // does nothing. The drift API surfaces these so the inspector
    // drawer + `pulp tweaks diff` CLI can warn the user.

    enum class DriftReason {
        anchor_not_found,    
        property_not_found,  
    };

    static const char* drift_reason_str(DriftReason reason);

    struct DriftedTweak {
        std::string anchor_id;
        std::string property_path;
        choc::value::Value value;
        std::string source;
        DriftReason reason = DriftReason::anchor_not_found;
    };

    struct DriftReport {
        std::vector<Record> clean;          
        std::vector<DriftedTweak> drifted;  
        std::vector<DriftedTweak> orphaned; 
 
        std::size_t total() const {
            return clean.size() + drifted.size() + orphaned.size();
        }
        bool has_drift() const {
            return !drifted.empty() || !orphaned.empty();
        }
    };

    struct DesignSnapshot {
        std::unordered_set<std::string> anchors;
        std::unordered_map<std::string, std::unordered_set<std::string>>
            properties;
    };

    DriftReport diff(const DesignSnapshot& design) const;

    DriftReport diff(const std::vector<std::string>& live_anchors) const;

    std::vector<DriftedTweak> find_drifted(const DesignSnapshot& design) const;

    std::vector<DriftedTweak>
    find_drifted(const std::vector<std::string>& live_anchors) const;

    static std::string drift_report_to_json(const DriftReport& report);
 
private:
    mutable std::mutex mtx_;
    // Outer key: anchor_id. Inner key: dotted property path.
    // Inner value: the most-recent assigned value + source.
    struct Entry {
        choc::value::Value value;
        std::string source;
        std::uint64_t sequence = 0;
    };
    std::unordered_map<std::string,
                       std::unordered_map<std::string, Entry>> tweaks_;
    std::unordered_map<std::string, BypassValue> bypassed_;
    // Anchor ids the user has marked as locked. A flat set means lock
    // has no per-path granularity — it protects a whole anchor.
    std::unordered_set<std::string> locked_;
    std::uint64_t next_sequence_ = 0;
 
    // Auto-save state. When `auto_save_` is true, every successful
    // mutation re-flushes the table to `auto_save_path_` after the
    // mutation completes. Both fields are guarded by `mtx_`.
    bool auto_save_ = false;
    std::string auto_save_path_;
 
    // Batch suspension depth. While > 0, maybe_auto_save_unlocked() is
    // a no-op so a multi-key batch flushes disk exactly once, after the
    // last key is written. Guarded by mtx_. A counter (not a bool)
    // keeps nested batches correct.
    int auto_save_suspend_depth_ = 0;
 
    // Helpers (assume mtx_ held by caller unless noted).
    std::string to_json_locked() const;
    DiskResult from_json_locked(std::string_view json);
    DiskResult save_locked(std::string_view path) const;
    // Auto-save trigger. Called by every mutating public method AFTER
    // it releases its lock; takes its own lock briefly to read auto-
    // save state. Returns silently if auto-save is off.
    void maybe_auto_save_unlocked() const;
};
 
}  // namespace pulp::inspect