sela-core 1.0.6 → 1.0.8

package/dist/services/SourceUpdater.js

@@ -38,6 +38,23 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const ASTSourceUpdater_1 = require("./ASTSourceUpdater");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+const WorkspaceSnapshotService_1 = require("./WorkspaceSnapshotService");
+const SelaError_1 = require("../errors/SelaError");
+// Centralised write gate - every disk-mutating `fs.writeFileSync` call in
+// this module routes through `persistFile` so the SELA_DRY_RUN bypass is
+// enforced in one place, and the Clean-Room WorkspaceSnapshotService
+// records contentBefore/contentAfter for isolated in-memory diffing.
+function persistFile(filePath, content) {
+    if (DryRunGuard_1.DryRunGuard.active()) {
+        DryRunGuard_1.DryRunGuard.logSkippedWrite("writeFileSync", filePath);
+        return false;
+    }
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.preWrite(filePath);
+    fs.writeFileSync(filePath, content, "utf8");
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.postWrite(filePath);
+    return true;
+}
 // ─────────────────────────────────────────────────────────────────
 // QUOTE MANAGEMENT
 // ─────────────────────────────────────────────────────────────────
@@ -293,21 +310,28 @@ function updateTemplateLiteralPreservingVars(line, oldSelector, newSelector, dom
 // GIT HELPER  (used by branch strategy and autoCommit)
 //
 // Design goals:
-//   • Lean — no stash, no branch-switching, no complex state management.
-//   • Commit-based — write first (inPlace), then commit.  If git fails,
+//   • Lean - no stash, no branch-switching, no complex state management.
+//   • Commit-based - write first (inPlace), then commit.  If git fails,
 //     the fix is still on disk (silent inPlace fallback).
-//   • Detached HEAD aware — skips silently in CI environments that check
+//   • Detached HEAD aware - skips silently in CI environments that check
 //     out a specific SHA without a branch ref.
 // ─────────────────────────────────────────────────────────────────
 function runGitOperations(absoluteFilePath, createBranch, relativeFilePath) {
     const filename = path.basename(relativeFilePath);
+    // Dry-run gate - suppress branch creation, `git add`, and auto-commit.
+    // Mirrors the persistFile() skip so a dry run is fully observable in CI
+    // without ever producing a commit.
+    if (DryRunGuard_1.DryRunGuard.active()) {
+        console.log(`[SourceUpdater] 🌵 Dry Run - skip git operations for ${filename}`);
+        return;
+    }
     try {
         // Bail out if HEAD is detached (CI SHA checkout, rebase mid-flight, etc.)
         try {
             (0, child_process_1.execSync)("git symbolic-ref HEAD", { stdio: "pipe" });
         }
         catch {
-            console.warn(`[SourceUpdater] ⚠️  Detached HEAD — git operations skipped (fix is saved to disk)`);
+            console.warn(`[SourceUpdater] ⚠️  Detached HEAD - git operations skipped (fix is saved to disk)`);
             return;
         }
         if (createBranch) {
@@ -322,7 +346,7 @@ function runGitOperations(absoluteFilePath, createBranch, relativeFilePath) {
         console.log(`[SourceUpdater] ✅ Auto-committed fix in: ${filename}`);
     }
     catch (err) {
-        console.warn(`[SourceUpdater] ⚠️  Git operation failed: ${err.message} — fix written to disk (inPlace fallback)`);
+        console.warn(`[SourceUpdater] ⚠️  Git operation failed: ${err.message} - fix written to disk (inPlace fallback)`);
     }
 }
 class SourceUpdater {
@@ -352,7 +376,7 @@ class SourceUpdater {
         return result;
     }
     // ─────────────────────────────────────────────────────────────
-    // commentOnly helper — inserts a TODO comment above the failing
+    // commentOnly helper - inserts a TODO comment above the failing
     // call site and returns success:false so the engine knows the
     // source was NOT rewritten (no retry suppression needed).
     // ─────────────────────────────────────────────────────────────
@@ -367,7 +391,7 @@ class SourceUpdater {
             const indent = lines[lineIdx].match(/^(\s*)/)?.[1] ?? "";
             const comment = `${indent}// TODO [Sela]: replace "${oldSelector}" with "${newSelector}"`;
             lines.splice(lineIdx, 0, comment);
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] 💬 Comment-only: inserted TODO at line ${caller.line} in ${path.basename(filePath)}`);
             return {
                 success: false,
@@ -378,12 +402,12 @@ class SourceUpdater {
         catch (err) {
             return {
                 success: false,
-                reason: `COMMENT_ONLY: write failed — ${err.message}`,
+                reason: `COMMENT_ONLY: write failed - ${err.message}`,
             };
         }
     }
     // ─────────────────────────────────────────────────────────────
-    // CORE UPDATE — Layered Healing (AST primary, Regex fallback)
+    // CORE UPDATE - Layered Healing (AST primary, Regex fallback)
     // Called by update(); never call directly from outside the class.
     // ─────────────────────────────────────────────────────────────
     static _coreUpdate(caller, oldSelector, newSelector, domContext, dnaAttrHint, fullSelectorContext, aiSegments, contentChange, smartChainSegments, originalChainHint) {
@@ -418,7 +442,7 @@ class SourceUpdater {
             if (astResult.success) {
                 console.log(`[SourceUpdater] ✅ AST Strategy ${astResult.strategy} SUCCESS` +
                     (astResult.lineUpdated !== undefined
-                        ? ` — line ${astResult.lineUpdated + 1}`
+                        ? ` - line ${astResult.lineUpdated + 1}`
                         : ""));
                 return {
                     success: true,
@@ -434,13 +458,21 @@ class SourceUpdater {
             // PROPERTY_ACCESS / TEMPLATE_LITERAL) but could not safely resolve the new
             // value.  Regex cannot do better and will corrupt the definition site.
             if (astResult.strategy === "semantic-guard") {
-                console.warn(`[SourceUpdater] 🛑 Regex blocked — semantic guard fired. ` +
+                console.warn(`[SourceUpdater] 🛑 Regex blocked - semantic guard fired. ` +
                     `Source unchanged. Reason: ${astResult.reason}`);
                 return { success: false, reason: astResult.reason };
             }
             console.log(`[SourceUpdater] ⚠️ AST engine exhausted (${astResult.reason}), falling back to Regex`);
         }
         catch (astError) {
+            // Developer pinned the failing statement with `// sela-fail-fast` -
+            // propagate the directive instead of swallowing into the Regex
+            // fallback chain (which would defeat the whole point of the gate).
+            if ((0, SelaError_1.isSelaErrorFrom)(astError, "ASTUpdater") &&
+                astError.code ===
+                    SelaError_1.AST_UPDATER_CODES.HEAL_DISABLED_BY_DIRECTIVE) {
+                throw astError;
+            }
             console.warn(`[SourceUpdater] ⚠️ AST engine error: ${astError.message}. Falling back to Regex`);
         }
         // ── 2. Regex Fallback ──────────────────────────────────────────
@@ -448,11 +480,11 @@ class SourceUpdater {
         const raw = fs.readFileSync(filePath, "utf8");
         const lines = raw.split(/\r?\n/);
         if (caller.line <= 0) {
-            console.log(`[SourceUpdater] ⚠️  line ${caller.line} invalid — running Regex Strategy G only`);
+            console.log(`[SourceUpdater] ⚠️  line ${caller.line} invalid - running Regex Strategy G only`);
             if (contentChange) {
                 const assertResult = SourceUpdater.strategyAssertionHealing(lines, 1, contentChange, true);
                 if (assertResult.success) {
-                    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                    persistFile(filePath, lines.join("\n"));
                     console.log(`[SourceUpdater] ✅ Regex Strategy G (Assertion Healing) SUCCESS`);
                     return assertResult;
                 }
@@ -479,8 +511,8 @@ class SourceUpdater {
             const layeredResult = SourceUpdater.strategyLayeredHealing(lines, callerLine, oldSelector, aiSegments, fullSelectorContext);
             if (layeredResult.success) {
                 tryAssertionHealing();
-                fs.writeFileSync(filePath, lines.join("\n"), "utf8");
-                console.log(`[SourceUpdater] ✅ Strategy 0 (Layered Healing) SUCCESS — line ${layeredResult.lineUpdated + 1}`);
+                persistFile(filePath, lines.join("\n"));
+                console.log(`[SourceUpdater] ✅ Strategy 0 (Layered Healing) SUCCESS - line ${layeredResult.lineUpdated + 1}`);
                 return layeredResult;
             }
         }
@@ -488,7 +520,7 @@ class SourceUpdater {
         const chainCollapseResult = SourceUpdater.strategyChainCollapse_Regex(lines, callerLine, oldSelector, effectiveNewSelector);
         if (chainCollapseResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy F (Chain Collapse) SUCCESS`);
             return chainCollapseResult;
         }
@@ -496,7 +528,7 @@ class SourceUpdater {
         const chainResult = SourceUpdater.strategyChainCollapse(lines, callerLine, oldSelector, effectiveNewSelector);
         if (chainResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 1 (Chain Collapse) SUCCESS`);
             return chainResult;
         }
@@ -504,7 +536,7 @@ class SourceUpdater {
         const directResult = SourceUpdater.strategyDirectLiteral(lines, callerLine, oldSelector, effectiveNewSelector);
         if (directResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 2 (Direct Literal) SUCCESS`);
             return directResult;
         }
@@ -512,7 +544,7 @@ class SourceUpdater {
         const varResult = SourceUpdater.strategyUpstreamVariable(lines, callerLine, oldSelector, effectiveNewSelector);
         if (varResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 3 (Upstream Variable) SUCCESS`);
             return varResult;
         }
@@ -520,7 +552,7 @@ class SourceUpdater {
         const chainDedupResult = SourceUpdater.strategyChainedLocator(lines, callerLine, oldSelector, effectiveNewSelector);
         if (chainDedupResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 4 (Chained Dedup) SUCCESS`);
             return chainDedupResult;
         }
@@ -528,7 +560,7 @@ class SourceUpdater {
         const fnResult = SourceUpdater.strategyFunctionReturn(lines, callerLine, oldSelector, effectiveNewSelector, domContext, dnaAttrHint);
         if (fnResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 5 (Function Return) SUCCESS`);
             return fnResult;
         }
@@ -536,7 +568,7 @@ class SourceUpdater {
         const scanResult = SourceUpdater.strategyGlobalScan(lines, oldSelector, effectiveNewSelector);
         if (scanResult.success) {
             tryAssertionHealing();
-            fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+            persistFile(filePath, lines.join("\n"));
             console.log(`[SourceUpdater] ✅ Strategy 6 (Global Scan) SUCCESS`);
             return scanResult;
         }
@@ -544,7 +576,7 @@ class SourceUpdater {
         if (contentChange) {
             const assertResult = SourceUpdater.strategyAssertionHealing(lines, callerLine, contentChange);
             if (assertResult.success) {
-                fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                persistFile(filePath, lines.join("\n"));
                 console.log(`[SourceUpdater] ✅ Strategy G (Assertion Healing) SUCCESS`);
                 return assertResult;
             }
@@ -556,7 +588,7 @@ class SourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY F (Regex) — Full Chain Collapsing
+    // STRATEGY F (Regex) - Full Chain Collapsing
     // ─────────────────────────────────────────────────────────────
     static strategyChainCollapse_Regex(lines, callerLine, oldSelector, newSelector) {
         console.log(`[Strategy-F] ⛓️  Starting Regex Chain Collapse...`);
@@ -607,7 +639,7 @@ class SourceUpdater {
         return { success: false, reason: "chain detected but could not replace" };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY G (Regex) — Assertion Healing
+    // STRATEGY G (Regex) - Assertion Healing
     // ─────────────────────────────────────────────────────────────
     static strategyAssertionHealing(lines, callerLine, contentChange, wholeFile = false) {
         const { oldText, newText } = contentChange;
@@ -662,7 +694,7 @@ class SourceUpdater {
         return { success: false, reason: "no assertions to heal" };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY 0 — Layered Healing (Upstream Variable Tracing)
+    // STRATEGY 0 - Layered Healing (Upstream Variable Tracing)
     // ─────────────────────────────────────────────────────────────
     static strategyLayeredHealing(lines, callerLine, oldElementSelector, aiSegments, fullSelectorContext) {
         console.log(`[SourceUpdater] 🧠 Strategy 0: Starting Layered Healing...`);
@@ -715,7 +747,7 @@ class SourceUpdater {
         return null;
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY 1 — Chain Collapse (leaf-only precision replacement)
+    // STRATEGY 1 - Chain Collapse (leaf-only precision replacement)
     // ─────────────────────────────────────────────────────────────
     static strategyChainCollapse(lines, callerLine, oldSelector, newSelector) {
         const oldLeaf = oldSelector
@@ -757,7 +789,7 @@ class SourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY 2 — Direct Literal
+    // STRATEGY 2 - Direct Literal
     // ─────────────────────────────────────────────────────────────
     static strategyDirectLiteral(lines, callerLine, oldSelector, newSelector) {
         const windowSize = 10;
@@ -790,7 +822,7 @@ class SourceUpdater {
         return { success: false, reason: "no direct literal" };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY 3 — Upstream Variable/Const
+    // STRATEGY 3 - Upstream Variable/Const
     // ─────────────────────────────────────────────────────────────
     static strategyUpstreamVariable(lines, callerLine, oldSelector, newSelector) {
         const callBlock = lines
@@ -827,7 +859,7 @@ class SourceUpdater {
         return { success: false, reason: "no upstream variable" };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY 4 — Chained Locator Dedup
+    // STRATEGY 4 - Chained Locator Dedup
     // ─────────────────────────────────────────────────────────────
     static strategyChainedLocator(lines, callerLine, oldSelector, newSelector) {
         const blockStart = Math.max(0, callerLine - 10);
@@ -854,7 +886,7 @@ class SourceUpdater {
         return { success: false, reason: "dedup found but literal not replaced" };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY 5 — Function/Template with Variable Preservation
+    // STRATEGY 5 - Function/Template with Variable Preservation
     // ─────────────────────────────────────────────────────────────
     static strategyFunctionReturn(lines, callerLine, oldSelector, newSelector, domContext, dnaAttrHint) {
         const callBlock = lines
@@ -939,7 +971,7 @@ class SourceUpdater {
         return { success: false, reason: "function strategy exhausted" };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY 6 — Global Scan
+    // STRATEGY 6 - Global Scan
     // ─────────────────────────────────────────────────────────────
     static strategyGlobalScan(lines, oldSelector, newSelector) {
         const lastOldPart = oldSelector.split(">>").pop().trim();
@@ -1008,7 +1040,7 @@ class SourceUpdater {
                 if (pattern.test(lines[i])) {
                     const safeNew = sanitizeForInjection(newArgument, q);
                     lines[i] = lines[i].replace(pattern, `$1${safeNew}$2`);
-                    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                    persistFile(filePath, lines.join("\n"));
                     return { success: true, reason: "argument updated", lineUpdated: i };
                 }
             }
@@ -1016,7 +1048,7 @@ class SourceUpdater {
                 if (pattern.test(lines[i])) {
                     const safeNew = sanitizeForInjection(newArgument, q);
                     lines[i] = lines[i].replace(pattern, `$1${safeNew}$2`);
-                    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
+                    persistFile(filePath, lines.join("\n"));
                     return { success: true, reason: "argument updated", lineUpdated: i };
                 }
             }

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

@@ -1 +1 @@
-{"version":3,"file":"TemplateDiffService.d.ts","sourceRoot":"","sources":["../../src/services/TemplateDiffService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,kBAAkB,EAAc,MAAM,UAAU,CAAC;AAMhE,MAAM,MAAM,eAAe,GACvB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA6BN,qBAAa,mBAAmB;IAW9B,MAAM,CAAC,YAAY,CACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IA6GlB,MAAM,CAAC,gBAAgB,CACrB,YAAY,EAAE,kBAAkB,EAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IAoFlB,MAAM,CAAC,qBAAqB,CAC1B,YAAY,EAAE,kBAAkB,EAChC,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,GAAG,IAAI;CASnB;AAgJD,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD"}
+{"version":3,"file":"TemplateDiffService.d.ts","sourceRoot":"","sources":["../../src/services/TemplateDiffService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,kBAAkB,EAAc,MAAM,UAAU,CAAC;AAMhE,MAAM,MAAM,eAAe,GACvB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA6BN,qBAAa,mBAAmB;IAW9B,MAAM,CAAC,YAAY,CACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IAiHlB,MAAM,CAAC,gBAAgB,CACrB,YAAY,EAAE,kBAAkB,EAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IAoFlB,MAAM,CAAC,qBAAqB,CAC1B,YAAY,EAAE,kBAAkB,EAChC,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,GAAG,IAAI;CASnB;AAgJD,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD"}

package/dist/services/TemplateDiffService.js

@@ -5,13 +5,13 @@ exports.escapeForTemplate = escapeForTemplate;
 // ═══════════════════════════════════════════════════════════════════
 // TemplateDiffService
 //
-// T-8: String-based API — diffAndPatch()
+// T-8: String-based API - diffAndPatch()
 //   Given a template source like `input[data-role="${role}_legacy"]`,
 //   its resolved old string, and an AI-proposed new string, compute
 //   the patched template that preserves ${...} spans while updating
 //   only the changed static segments.
 //
-// T-8.1: Node-based API — computeNodePatch()
+// T-8.1: Node-based API - computeNodePatch()
 //   Wraps diffAndPatch() using the TemplateExpression AST node as the
 //   source of truth (avoids text-parsing ambiguity). Returns the full
 //   patched template text for use with templateNode.replaceWithText().
@@ -34,7 +34,7 @@ class TemplateDiffService {
         const exprSegs = segments
             .filter((s) => s.type === "expr")
             .map((s) => s.text);
-        // No spans — the "template" is just a plain string.
+        // No spans - the "template" is just a plain string.
         if (exprSegs.length === 0) {
             if (resolvedOld !== resolvedNew) {
                 return {
@@ -43,18 +43,21 @@ class TemplateDiffService {
                     changedSegmentIndices: [0],
                 };
             }
-            return { ok: false, reason: "resolvedOld === resolvedNew — no change needed" };
+            return {
+                ok: false,
+                reason: "resolvedOld === resolvedNew - no change needed",
+            };
         }
         // Extract span values from resolvedOld using static segments as anchors.
         const spanValues = extractSpanValues(staticSegs, resolvedOld);
         if (!spanValues) {
             return {
                 ok: false,
-                reason: "template static segments don't align with resolvedOld — possible desync. " +
+                reason: "template static segments don't align with resolvedOld - possible desync. " +
                     `template="${templateText}", resolvedOld="${resolvedOld}"`,
             };
         }
-        // Verify reconstruction — extractSpanValues already guarantees this
+        // Verify reconstruction - extractSpanValues already guarantees this
         // implicitly, but an explicit check catches any edge-case bugs early.
         {
             let check = "";
@@ -76,13 +79,13 @@ class TemplateDiffService {
             return {
                 ok: false,
                 reason: `dynamic span value(s) [${spanValues.map((v) => `"${v}"`).join(", ")}] ` +
-                    `not found in resolvedNew="${resolvedNew}" — structural change, manual review required`,
+                    `not found in resolvedNew="${resolvedNew}" - structural change, manual review required`,
             };
         }
         if (newStaticSegs.length !== staticSegs.length) {
             return {
                 ok: false,
-                reason: "static segment count mismatch after alignment — structural change",
+                reason: "static segment count mismatch after alignment - structural change",
             };
         }
         // Diff: find which static segments changed.
@@ -94,14 +97,14 @@ class TemplateDiffService {
         if (changedIndices.length === 0) {
             return {
                 ok: false,
-                reason: "no static segment changed — the difference is in a dynamic span. " +
+                reason: "no static segment changed - the difference is in a dynamic span. " +
                     "Update the argument passed to the function instead.",
             };
         }
         if (changedIndices.length > 1) {
             return {
                 ok: false,
-                reason: `${changedIndices.length} static segments changed simultaneously — ` +
+                reason: `${changedIndices.length} static segments changed simultaneously - ` +
                     "ambiguous, manual review required",
             };
         }
@@ -119,7 +122,7 @@ class TemplateDiffService {
     //
     // Uses the TemplateExpression AST node as the authoritative source
     // of static/expr segments (avoids text-parsing edge cases).
-    // Returns `patchedText` — pass directly to templateNode.replaceWithText().
+    // Returns `patchedText` - pass directly to templateNode.replaceWithText().
     // ─────────────────────────────────────────────────────────────────
     static computeNodePatch(templateNode, resolvedOld, resolvedNew) {
         // Extract static segments and expr texts directly from the AST.
@@ -172,13 +175,13 @@ class TemplateDiffService {
         if (changedIndices.length === 0) {
             return {
                 ok: false,
-                reason: "difference is in dynamic span — update call-site argument",
+                reason: "difference is in dynamic span - update call-site argument",
             };
         }
         if (changedIndices.length > 1) {
             return {
                 ok: false,
-                reason: `${changedIndices.length} static segments changed — ambiguous`,
+                reason: `${changedIndices.length} static segments changed - ambiguous`,
             };
         }
         const patchedStatics = [...staticSegs];
@@ -238,7 +241,7 @@ function parseTemplateSource(text) {
  *
  * Algorithm: iterate over all static segments in order. After consuming
  * each static segment, find the next static as the delimiter for the
- * span value — then advance pos to the start of that next static so
+ * span value - then advance pos to the start of that next static so
  * the following iteration can consume it. This ensures pos is always
  * consistent at the start of each static segment.
  *
@@ -265,7 +268,7 @@ function extractSpanValues(staticSegments, resolved) {
             break;
         }
         if (nextStatic === "") {
-            // Empty non-trailing static: adjacent spans — boundary is ambiguous.
+            // Empty non-trailing static: adjacent spans - boundary is ambiguous.
             return null;
         }
         const delimIdx = resolved.indexOf(nextStatic, pos);

package/dist/services/WorkspaceSnapshotService.d.ts

@@ -0,0 +1,71 @@
+export interface FileSnapshot {
+    /** Absolute, normalised path of the tracked file. */
+    absolutePath: string;
+    /** Project-relative path (posix slashes) - for diff headers + PR commits. */
+    relativePath: string;
+    /**
+     * Disk content captured BEFORE Sela's first write to this file.
+     * May contain the developer's uncommitted edits - that's the point.
+     */
+    contentBefore: string;
+    /** Disk content captured AFTER Sela's latest write. `null` until first postWrite(). */
+    contentAfter: string | null;
+    /** Content of the file at `HEAD` (last committed) - `null` when untracked / no git. */
+    headContent: string | null;
+    /** True when `contentBefore !== headContent`, i.e. developer had dirty edits. */
+    hadUncommittedChanges: boolean;
+    /** True when the file did not exist on disk before Sela touched it. */
+    createdBySela: boolean;
+}
+export declare class WorkspaceSnapshotService {
+    private snapshots;
+    private cwd;
+    constructor(cwd?: string);
+    /** Override the cwd used for relative-path + HEAD lookups (tests). */
+    setCwd(cwd: string): void;
+    /**
+     * Record the pre-mutation state of `filePath` if not already tracked.
+     * Idempotent - only the FIRST call per file matters.
+     */
+    preWrite(filePath: string): void;
+    /**
+     * Refresh the post-mutation state. Safe to call multiple times - each
+     * call overwrites `contentAfter` with the latest disk state.
+     */
+    postWrite(filePath: string): void;
+    /** Lookup by absolute or relative path. Returns `null` when untracked. */
+    getSnapshot(filePath: string): FileSnapshot | null;
+    /** Every tracked snapshot. Insertion order. */
+    getAllSnapshots(): FileSnapshot[];
+    /**
+     * Did Sela actually mutate this file? True when contentAfter exists and
+     * differs from contentBefore.
+     */
+    isMutated(filePath: string): boolean;
+    /** All snapshots with a real mutation recorded. */
+    getMutatedSnapshots(): FileSnapshot[];
+    /**
+     * Rewind every tracked file on disk to `contentBefore` - restoring the
+     * developer's pre-Sela workspace state byte-for-byte.
+     */
+    restoreOriginal(): void;
+    /**
+     * Rewind a SINGLE tracked file on disk to `contentBefore`. Used by the
+     * Local DX interactive review flow when the developer rejects a fix.
+     * Returns true when the rewind happened, false when the file is untracked.
+     */
+    restoreOriginalByPath(filePath: string): boolean;
+    private rewindSnapshot;
+    /**
+     * Forward every tracked file on disk to `contentAfter` (no-op for files
+     * that were never written). Used by PRAutomationService to reapply
+     * Sela's mutations after a `git stash pop` round-trip.
+     */
+    restoreMutated(): void;
+    clear(): void;
+    private normalise;
+    private toRelative;
+    private readHeadContent;
+}
+export declare const sharedWorkspaceSnapshot: WorkspaceSnapshotService;
+//# sourceMappingURL=WorkspaceSnapshotService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceSnapshotService.d.ts","sourceRoot":"","sources":["../../src/services/WorkspaceSnapshotService.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uFAAuF;IACvF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iFAAiF;IACjF,qBAAqB,EAAE,OAAO,CAAC;IAC/B,uEAAuE;IACvE,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,wBAAwB;IACnC,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,GAAG,CAAS;gBAER,GAAG,GAAE,MAAsB;IAIvC,sEAAsE;IACtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAqBhC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOjC,0EAA0E;IAC1E,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIlD,+CAA+C;IAC/C,eAAe,IAAI,YAAY,EAAE;IAIjC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMpC,mDAAmD;IACnD,mBAAmB,IAAI,YAAY,EAAE;IAMrC;;;OAGG;IACH,eAAe,IAAI,IAAI;IAMvB;;;;OAIG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAOhD,OAAO,CAAC,cAAc;IAUtB;;;;OAIG;IACH,cAAc,IAAI,IAAI;IAOtB,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,eAAe;CAcxB;AAED,eAAO,MAAM,uBAAuB,0BAAiC,CAAC"}