sela-core 1.0.6 → 1.0.7

package/dist/services/HealingCacheService.d.ts

@@ -0,0 +1,135 @@
+import type { SmartChainSegment, SelectorSegment } from "./LLMService";
+export type HealCacheMode = "action" | "assertion";
+export interface CacheKeyInput {
+    /** Absolute or project-relative spec path containing the failing locator. */
+    filePath: string;
+    /** 1-based line of the failing call site — paired with filePath as a fingerprint. */
+    line: number;
+    /**
+     * Stable content hash of the DNA snapshot used to drive the heal. When the
+     * DNA rewrites, this changes — every cached entry for the old DNA
+     * silently stops matching and ages out via TTL.
+     */
+    dnaContentHash: string;
+    /** The original broken selector. */
+    brokenSelector: string;
+    /** Heal mode the cached fix was produced under. */
+    mode: HealCacheMode;
+}
+export interface HealingCacheEntry {
+    /** Full SHA1 of the CacheKeyInput tuple. */
+    key: string;
+    filePath: string;
+    line: number;
+    dnaContentHash: string;
+    brokenSelector: string;
+    mode: HealCacheMode;
+    healedSelector: string;
+    chainSegments?: SmartChainSegment[];
+    segments?: SelectorSegment[];
+    confidence?: number;
+    contentChange?: {
+        oldText: string;
+        newText: string;
+    };
+    explanation?: string;
+    alternatives?: string[];
+    /**
+     * True when SafetyGuard cleared this fix in the originating session
+     * (SAFE or REQUIRES_REVIEW). Unsafe entries are never replayed.
+     */
+    safe: boolean;
+    createdAt: string;
+    /** ISO timestamp after which the entry is considered expired and ignored. */
+    ttlExpiresAt: string;
+    lastHitAt?: string;
+    hitCount: number;
+}
+interface CacheFile {
+    schemaVersion: 1;
+    entries: Record<string, HealingCacheEntry>;
+}
+export interface HealingCacheSetInput extends CacheKeyInput {
+    healedSelector: string;
+    chainSegments?: SmartChainSegment[];
+    segments?: SelectorSegment[];
+    confidence?: number;
+    contentChange?: {
+        oldText: string;
+        newText: string;
+    };
+    explanation?: string;
+    alternatives?: string[];
+    safe: boolean;
+    /** Optional override for entry-level TTL (ms). Defaults to env / 7d. */
+    ttlMs?: number;
+}
+export declare function computeCacheKey(input: CacheKeyInput): string;
+/**
+ * Convenience helper — fingerprint the JSON form of a DNA snapshot so
+ * the cache key changes whenever the DNA is rewritten.
+ */
+export declare function hashDnaContent(dna: unknown): string;
+export declare class HealingCacheService {
+    private readonly cacheDir;
+    private readonly filename;
+    private readonly lockDir;
+    private readonly tmpSuffix;
+    private readonly bakSuffix;
+    private inFlight;
+    constructor(opts?: {
+        cacheDir?: string;
+        filename?: string;
+    });
+    /**
+     * Read-only lookup. Bumps `hitCount` / `lastHitAt` IN-MEMORY only on
+     * the returned entry reference — never persisted on the get() path.
+     * This eliminates the read-write race where parallel workers each
+     * call get() and serialise full entries-map snapshots back to disk,
+     * overwriting peer set() operations.
+     */
+    get(input: CacheKeyInput): HealingCacheEntry | null;
+    /**
+     * Persist a new cache entry. Serialises against in-process writers
+     * AND across processes via the mkdir lock. The in-process chain
+     * isolates each `await` so a rejected upstream Promise never
+     * deadlocks downstream callers.
+     */
+    set(input: HealingCacheSetInput): Promise<void>;
+    /** Synchronous variant — used by teardown / CLI paths. */
+    setSync(input: HealingCacheSetInput): void;
+    /** Wipe every entry. Used by tests and the (forthcoming) `sela cache clear` CLI. */
+    clear(): void;
+    /** Returns the parsed cache file (or an empty shell on failure). */
+    read(): CacheFile;
+    /** Absolute path of the on-disk cache file. */
+    filePath(): string;
+    /**
+     * Prunes expired entries. Cheap O(n) scan — intended for engine
+     * startup. Returns the number of entries removed.
+     */
+    pruneExpired(): number;
+    private isExpired;
+    private lockedWrite;
+    private buildEntry;
+    /**
+     * Reads + parses the cache file. Tolerates every realistic failure
+     * (missing, empty, malformed, wrong schema version) by returning a
+     * fresh empty shell — the contract is "cache misses are silent".
+     */
+    private safeRead;
+    /**
+     * Atomic write: write to `<file>.tmp`, copy current to `<file>.bak`,
+     * then rename `<file>.tmp` → `<file>`. The rename is the single
+     * commit point — a crash between bak and rename leaves the bak file
+     * intact for future recovery.
+     */
+    private atomicWrite;
+    private acquireLockWithBackoff;
+    private tryAcquireLock;
+    private withFileLockSync;
+    private releaseLock;
+}
+export declare const sharedHealingCache: HealingCacheService;
+export {};
+//# sourceMappingURL=HealingCacheService.d.ts.map

package/dist/services/HealingCacheService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HealingCacheService.d.ts","sourceRoot":"","sources":["../../src/services/HealingCacheService.ts"],"names":[],"mappings":"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"}

package/dist/services/HealingCacheService.js

@@ -0,0 +1,460 @@
+"use strict";
+// src/services/HealingCacheService.ts
+//
+// Local healing cache — short-circuits the LLM round-trip when an
+// identical heal-context has been resolved successfully in a prior
+// session.
+//
+// Cache key (matches DX MVP Phase 6 plan):
+//   SHA1(filePath + ":" + line + "::" + dnaContentHash + "::" + brokenSelector + "::" + mode)
+//   Including `dnaContentHash` means a DNA rewrite automatically
+//   invalidates every entry keyed against that fingerprint — old
+//   entries simply stop matching and age out via TTL.
+//
+// Cache value:
+//   `{ chainSegments, segments, confidence, contentChange, explanation,
+//      alternatives, safe, createdAt, ttlExpiresAt, hitCount, lastHitAt }`.
+//   TTL defaults to 7 days; overridable via `SELA_CACHE_TTL_DAYS`.
+//
+// Storage:
+//   `.sela-cache.json` in process.cwd() by default (configurable via the
+//   constructor for tests). Single-file map of SHA1 keys → entry.
+//   Schema-versioned (`schemaVersion: 1`).
+//
+// Concurrency model (three layers, identical to the plan):
+//
+//   1. In-process mutex
+//      `inFlight: Promise<void>` chain. Concurrent setters in the SAME
+//      Node process queue behind one another via the chained Promise.
+//      Any rejection on the chain is swallowed before the next call
+//      awaits it, so a single bad write CANNOT deadlock subsequent
+//      callers.
+//
+//   2. Cross-process file lock
+//      Playwright workers run as separate processes — atomic
+//      `mkdir <cacheDir>/.sela-cache.lock` is used as the mutex. Second
+//      process gets `EEXIST`, polls with exponential backoff
+//      (50ms → 800ms, max 6 retries ≈ 3.15 s ceiling). Lock is held
+//      only across the read-modify-write window, never during reads.
+//
+//   3. Atomic write via temp + rename
+//      Write to `.sela-cache.json.tmp`, copy the previous file to
+//      `.sela-cache.json.bak`, then `fs.renameSync(tmp, target)` —
+//      atomic on POSIX and on Windows (Node ≥14) when source and
+//      target share a volume (always true here).
+//
+// Read path:
+//   memory check → file check (no lock) → on miss the caller (SelaEngine)
+//   acquires the LLM via the normal path; cache writes happen post-success.
+//
+// `get()` is strictly read-only on disk: hit-count / lastHitAt are
+// bumped IN-MEMORY only — they never trigger a disk write. This avoids
+// the documented bug where concurrent worker `get()` calls would
+// overwrite valid `set()` operations from peer workers.
+//
+// Failure tolerance: any read failure (missing, malformed JSON, wrong
+// schema, EACCES, …) returns "no entries" instead of throwing. The
+// cache is a latency optimisation — never a hard dependency of the
+// heal pipeline.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedHealingCache = exports.HealingCacheService = void 0;
+exports.computeCacheKey = computeCacheKey;
+exports.hashDnaContent = hashDnaContent;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+// ═══════════════════════════════════════════════════════════════════
+// KEY HASH
+// ═══════════════════════════════════════════════════════════════════
+const KEY_SEPARATOR = "::";
+const DEFAULT_TTL_DAYS = 7;
+function defaultTtlMs() {
+    const raw = process.env.SELA_CACHE_TTL_DAYS;
+    if (!raw)
+        return DEFAULT_TTL_DAYS * 24 * 60 * 60 * 1000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        return DEFAULT_TTL_DAYS * 24 * 60 * 60 * 1000;
+    }
+    return n * 24 * 60 * 60 * 1000;
+}
+function computeCacheKey(input) {
+    // Normalise filePath separators so a cache entry written from a Windows
+    // worker is still found from a POSIX worker hitting the same repo.
+    const normPath = path.resolve(input.filePath).split(path.sep).join("/");
+    return (0, crypto_1.createHash)("sha1")
+        .update([
+        normPath + ":" + input.line,
+        input.dnaContentHash,
+        input.brokenSelector,
+        input.mode,
+    ].join(KEY_SEPARATOR))
+        .digest("hex");
+}
+/**
+ * Convenience helper — fingerprint the JSON form of a DNA snapshot so
+ * the cache key changes whenever the DNA is rewritten.
+ */
+function hashDnaContent(dna) {
+    try {
+        const json = typeof dna === "string" ? dna : JSON.stringify(dna ?? {});
+        return (0, crypto_1.createHash)("sha1").update(json).digest("hex");
+    }
+    catch {
+        return "no-dna";
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// HealingCacheService
+// ═══════════════════════════════════════════════════════════════════
+class HealingCacheService {
+    cacheDir;
+    filename;
+    lockDir;
+    tmpSuffix = ".tmp";
+    bakSuffix = ".bak";
+    // In-process serialisation. Every new set() chains onto the prior
+    // tail Promise. The chain is fault-tolerant — see `set()` below.
+    inFlight = Promise.resolve();
+    constructor(opts) {
+        this.cacheDir = opts?.cacheDir ?? process.cwd();
+        this.filename = opts?.filename ?? ".sela-cache.json";
+        this.lockDir = path.join(this.cacheDir, ".sela-cache.lock");
+    }
+    // ─────────────────────────────────────────────────────────────
+    // PUBLIC API
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Read-only lookup. Bumps `hitCount` / `lastHitAt` IN-MEMORY only on
+     * the returned entry reference — never persisted on the get() path.
+     * This eliminates the read-write race where parallel workers each
+     * call get() and serialise full entries-map snapshots back to disk,
+     * overwriting peer set() operations.
+     */
+    get(input) {
+        const key = computeCacheKey(input);
+        const file = this.safeRead();
+        const entry = file.entries[key];
+        if (!entry)
+            return null;
+        if (!entry.safe)
+            return null;
+        if (this.isExpired(entry))
+            return null;
+        // In-memory only — DO NOT write back. Hit-count drift across workers
+        // is acceptable; corrupting peer writes is not.
+        entry.hitCount = (entry.hitCount ?? 0) + 1;
+        entry.lastHitAt = new Date().toISOString();
+        return entry;
+    }
+    /**
+     * Persist a new cache entry. Serialises against in-process writers
+     * AND across processes via the mkdir lock. The in-process chain
+     * isolates each `await` so a rejected upstream Promise never
+     * deadlocks downstream callers.
+     */
+    async set(input) {
+        if (DryRunGuard_1.DryRunGuard.active()) {
+            // Don't pollute the cache during a SELA_DRY_RUN session.
+            return;
+        }
+        // Chain onto the previous tail, but swallow rejections via a
+        // `.catch(noop)` adapter. Without this, an earlier rejected set()
+        // would propagate through every subsequent `await prev` and either
+        // throw at the wrong caller or — worse — leak through the finally
+        // block without releasing the queue. The wrapper guarantees the
+        // queue is FIFO and rejection-safe.
+        const prev = this.inFlight.catch(() => {
+            /* swallow — upstream failure handled by its own caller */
+        });
+        let release;
+        const myTurn = new Promise((res) => {
+            release = res;
+        });
+        this.inFlight = myTurn;
+        try {
+            await prev;
+            await this.lockedWrite(input);
+        }
+        finally {
+            // Always release — even on throw — so the next queued caller
+            // unblocks. Errors still propagate up to *this* caller normally.
+            release();
+        }
+    }
+    /** Synchronous variant — used by teardown / CLI paths. */
+    setSync(input) {
+        if (DryRunGuard_1.DryRunGuard.active())
+            return;
+        this.withFileLockSync(() => {
+            const file = this.safeRead();
+            const key = computeCacheKey(input);
+            file.entries[key] = this.buildEntry(key, input, file.entries[key]);
+            this.atomicWrite(file);
+        });
+    }
+    /** Wipe every entry. Used by tests and the (forthcoming) `sela cache clear` CLI. */
+    clear() {
+        this.withFileLockSync(() => {
+            const target = path.join(this.cacheDir, this.filename);
+            const bak = target + this.bakSuffix;
+            const tmp = target + this.tmpSuffix;
+            for (const f of [target, bak, tmp]) {
+                try {
+                    if (fs.existsSync(f))
+                        fs.unlinkSync(f);
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        });
+    }
+    /** Returns the parsed cache file (or an empty shell on failure). */
+    read() {
+        return this.safeRead();
+    }
+    /** Absolute path of the on-disk cache file. */
+    filePath() {
+        return path.join(this.cacheDir, this.filename);
+    }
+    /**
+     * Prunes expired entries. Cheap O(n) scan — intended for engine
+     * startup. Returns the number of entries removed.
+     */
+    pruneExpired() {
+        let removed = 0;
+        this.withFileLockSync(() => {
+            const file = this.safeRead();
+            for (const [k, e] of Object.entries(file.entries)) {
+                if (this.isExpired(e)) {
+                    delete file.entries[k];
+                    removed++;
+                }
+            }
+            if (removed > 0)
+                this.atomicWrite(file);
+        });
+        return removed;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // INTERNAL — read / write / lock
+    // ─────────────────────────────────────────────────────────────
+    isExpired(entry) {
+        if (!entry.ttlExpiresAt)
+            return false;
+        const t = Date.parse(entry.ttlExpiresAt);
+        if (!Number.isFinite(t))
+            return false;
+        return t <= Date.now();
+    }
+    async lockedWrite(input) {
+        const acquired = await this.acquireLockWithBackoff();
+        if (!acquired) {
+            console.warn(`[HealingCache] ⚠️  Could not acquire lock at ${this.lockDir} — write skipped`);
+            return;
+        }
+        try {
+            const file = this.safeRead();
+            const key = computeCacheKey(input);
+            file.entries[key] = this.buildEntry(key, input, file.entries[key]);
+            this.atomicWrite(file);
+        }
+        finally {
+            this.releaseLock();
+        }
+    }
+    buildEntry(key, input, prev) {
+        const now = new Date().toISOString();
+        const ttlMs = input.ttlMs ?? defaultTtlMs();
+        const ttlExpiresAt = new Date(Date.now() + ttlMs).toISOString();
+        return {
+            key,
+            filePath: input.filePath,
+            line: input.line,
+            dnaContentHash: input.dnaContentHash,
+            brokenSelector: input.brokenSelector,
+            mode: input.mode,
+            healedSelector: input.healedSelector,
+            chainSegments: input.chainSegments,
+            segments: input.segments,
+            confidence: input.confidence,
+            contentChange: input.contentChange,
+            explanation: input.explanation,
+            alternatives: input.alternatives,
+            safe: input.safe,
+            createdAt: prev?.createdAt ?? now,
+            ttlExpiresAt,
+            lastHitAt: prev?.lastHitAt,
+            hitCount: prev?.hitCount ?? 0,
+        };
+    }
+    /**
+     * Reads + parses the cache file. Tolerates every realistic failure
+     * (missing, empty, malformed, wrong schema version) by returning a
+     * fresh empty shell — the contract is "cache misses are silent".
+     */
+    safeRead() {
+        const target = path.join(this.cacheDir, this.filename);
+        let raw;
+        try {
+            raw = fs.readFileSync(target, "utf8");
+        }
+        catch {
+            return { schemaVersion: 1, entries: {} };
+        }
+        if (!raw || raw.trim().length === 0) {
+            return { schemaVersion: 1, entries: {} };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            console.warn(`[HealingCache] ⚠️  Corrupt cache file at ${target} — starting fresh (${err.message})`);
+            return { schemaVersion: 1, entries: {} };
+        }
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed) ||
+            parsed.schemaVersion !== 1 ||
+            typeof parsed.entries !== "object" ||
+            parsed.entries === null ||
+            Array.isArray(parsed.entries)) {
+            console.warn(`[HealingCache] ⚠️  Unknown cache schema at ${target} — starting fresh`);
+            return { schemaVersion: 1, entries: {} };
+        }
+        return parsed;
+    }
+    /**
+     * Atomic write: write to `<file>.tmp`, copy current to `<file>.bak`,
+     * then rename `<file>.tmp` → `<file>`. The rename is the single
+     * commit point — a crash between bak and rename leaves the bak file
+     * intact for future recovery.
+     */
+    atomicWrite(file) {
+        if (!fs.existsSync(this.cacheDir)) {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+        }
+        const target = path.join(this.cacheDir, this.filename);
+        const tmp = target + this.tmpSuffix;
+        const bak = target + this.bakSuffix;
+        const json = JSON.stringify(file, null, 2);
+        fs.writeFileSync(tmp, json, "utf8");
+        if (fs.existsSync(target)) {
+            try {
+                fs.copyFileSync(target, bak);
+            }
+            catch (err) {
+                console.warn(`[HealingCache] ⚠️  Failed to write backup ${bak}: ${err.message}`);
+            }
+        }
+        fs.renameSync(tmp, target);
+    }
+    // ─────────────────────────────────────────────────────────────
+    // FILE LOCK — atomic mkdir as a cross-process mutex
+    // ─────────────────────────────────────────────────────────────
+    async acquireLockWithBackoff() {
+        const delaysMs = [50, 100, 200, 400, 800, 800];
+        for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
+            if (this.tryAcquireLock())
+                return true;
+            if (attempt === delaysMs.length)
+                break;
+            await sleep(delaysMs[attempt]);
+        }
+        return false;
+    }
+    tryAcquireLock() {
+        if (!fs.existsSync(this.cacheDir)) {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+        }
+        try {
+            fs.mkdirSync(this.lockDir);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return false;
+            console.warn(`[HealingCache] ⚠️  Lock acquire failed: ${err.message}`);
+            return false;
+        }
+    }
+    withFileLockSync(fn) {
+        const delaysMs = [10, 25, 50, 100];
+        for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
+            if (this.tryAcquireLock()) {
+                try {
+                    fn();
+                }
+                finally {
+                    this.releaseLock();
+                }
+                return;
+            }
+            if (attempt === delaysMs.length)
+                break;
+            sleepBusy(delaysMs[attempt]);
+        }
+        console.warn(`[HealingCache] ⚠️  Lock acquire failed (sync) — operation skipped`);
+    }
+    releaseLock() {
+        try {
+            fs.rmdirSync(this.lockDir);
+        }
+        catch {
+            // best-effort
+        }
+    }
+}
+exports.HealingCacheService = HealingCacheService;
+// ═══════════════════════════════════════════════════════════════════
+// Utilities
+// ═══════════════════════════════════════════════════════════════════
+function sleep(ms) {
+    return new Promise((res) => setTimeout(res, ms));
+}
+function sleepBusy(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // intentional spin
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// Module-level singleton — engines reuse the same cache file by default
+// ═══════════════════════════════════════════════════════════════════
+exports.sharedHealingCache = new HealingCacheService();

package/dist/services/InitializerUpdater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InitializerUpdater.d.ts","sourceRoot":"","sources":["../../src/services/InitializerUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAiB,MAAM,UAAU,CAAC;AAY3D,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,kBAAkB;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACV,SAAS,EAAE,IAAI,EACf,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,GACf,iBAAiB,GAAG,IAAI;CAqB5B"}
+{"version":3,"file":"InitializerUpdater.d.ts","sourceRoot":"","sources":["../../src/services/InitializerUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAiB,MAAM,UAAU,CAAC;AAc3D,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,kBAAkB;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACV,SAAS,EAAE,IAAI,EACf,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,GACf,iBAAiB,GAAG,IAAI;CAsC5B"}

package/dist/services/InitializerUpdater.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InitializerUpdater = void 0;
 const ts_morph_1 = require("ts-morph");
 const TemplateDiffService_js_1 = require("./TemplateDiffService.js");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+const WorkspaceSnapshotService_1 = require("./WorkspaceSnapshotService");
 class InitializerUpdater {
     /**
      * Mutate a StringLiteral or NoSubstitutionTemplateLiteral node to
@@ -22,7 +24,24 @@ class InitializerUpdater {
             else {
                 return null;
             }
-            sourceFile.saveSync();
+            // Centralised write gate — mirrors ASTSourceUpdater._persistChanges.
+            // InitializerUpdater is the canonical write-head for definition-site
+            // mutations (SemanticDispatch → tracer-resolved identifier / property
+            // access / cross-file paths all converge here), so the Clean-Room
+            // snapshot ledger and DryRunGuard MUST be enforced here too.
+            // Without this, an upstream-traced fix (e.g. global StringLiteral at
+            // top of file) writes to disk but `WorkspaceSnapshotService` never
+            // sees it — `getMutatedSnapshots()` returns empty and PR automation
+            // skips the heal entirely.
+            const fp = sourceFile.getFilePath();
+            if (DryRunGuard_1.DryRunGuard.active()) {
+                DryRunGuard_1.DryRunGuard.logSkippedWrite("saveSync", fp);
+            }
+            else {
+                WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.preWrite(fp);
+                sourceFile.saveSync();
+                WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.postWrite(fp);
+            }
             return {
                 lineUpdated: valueNode.getStartLineNumber() - 1,
                 healedLocatorString: newValue,

package/dist/services/IntentAuditor.d.ts

@@ -1,3 +1,4 @@
+import Anthropic from "@anthropic-ai/sdk";
 import { AncestorNode, AnchorInfo } from "../types";
 export interface AuditRequest {
     dnaText: string;
@@ -27,10 +28,26 @@ export interface AuditVerdict {
         bonus: number;
     };
 }
+/**
+ * Constructor options for IntentAuditor.
+ *
+ * - `anthropic`: pre-built Anthropic client to use. Pass `null` explicitly
+ *   to force the auditor into its disabled state (useful in tests that
+ *   want to assert the SUSPICIOUS fallback path without touching env vars).
+ *   Pass `undefined` (default) to fall back to env-based construction.
+ * - `apiKey`: override the ANTHROPIC_API_KEY env var (DI-friendly).
+ * - `model`: override the Haiku model id (lets tests pin the SDK call).
+ */
+export interface IntentAuditorOptions {
+    anthropic?: Anthropic | null;
+    apiKey?: string;
+    model?: string;
+}
 export declare class IntentAuditor {
     private anthropic;
     private readonly disabled;
-    constructor();
+    private readonly model;
+    constructor(opts?: IntentAuditorOptions);
     auditIntent(req: AuditRequest): Promise<AuditVerdict>;
     computeAncestryPenalty(dnaPath: AncestorNode[], livePath: AncestorNode[]): number;
     computeAnchorBonus(dnaAnchors: AnchorInfo | null | undefined, liveAnchors: AnchorInfo | null | undefined): number;

package/dist/services/IntentAuditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IntentAuditor.d.ts","sourceRoot":"","sources":["../../src/services/IntentAuditor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAOpD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,WAAW,GAAG,QAAQ,CAAC;IAEjC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;IAC7B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,qEAAqE;IACrE,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,cAAc,GAAG,YAAY,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,IAAI,CAAC;IACzE,yEAAyE;IACzE,cAAc,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5E;AAkED,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;;IAgB7B,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IA4G3D,sBAAsB,CACpB,OAAO,EAAE,YAAY,EAAE,EACvB,QAAQ,EAAE,YAAY,EAAE,GACvB,MAAM;IA4CT,kBAAkB,CAChB,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACzC,WAAW,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GACzC,MAAM;IAmCT,OAAO,CAAC,YAAY;CA8CrB"}
+{"version":3,"file":"IntentAuditor.d.ts","sourceRoot":"","sources":["../../src/services/IntentAuditor.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAOpD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,WAAW,GAAG,QAAQ,CAAC;IAEjC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;IAC7B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,qEAAqE;IACrE,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,cAAc,GAAG,YAAY,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,IAAI,CAAC;IACzE,yEAAyE;IACzE,cAAc,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5E;AAkED;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,IAAI,GAAE,oBAAyB;IA+BrC,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IA4G3D,sBAAsB,CACpB,OAAO,EAAE,YAAY,EAAE,EACvB,QAAQ,EAAE,YAAY,EAAE,GACvB,MAAM;IA4CT,kBAAkB,CAChB,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACzC,WAAW,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GACzC,MAAM;IAmCT,OAAO,CAAC,YAAY;CA8CrB"}