Git Rollback & Code Modifier

Relevant source files

The following files were used as context for generating this wiki page:

• src/engine/codeModifier.ts
• src/engine/codeAnalyzer.ts
• src/engine/optimizationLoop.ts
• plan.md
• src/test-demo-site.ts
• README.md

The Git Rollback & Code Modifier system is a critical component of the SynthCrowd optimization pipeline. Its primary purpose is to autonomously apply code changes suggested by the Code Analysis agent to fix identified friction points on a target website. It ensures safety and stability by utilizing Git for version control, allowing the system to commit states before changes and revert immediately if a modification breaks the site's functionality.

This system acts as the "Fix" phase (Phase 4) of the overall project lifecycle. It bridges the gap between identifying user experience issues through synthetic persona testing and implementing actual code-level solutions. By integrating automated verification, the system maintains a "never leave the site broken" policy during the iterative optimization loop.
Sources: plan.md:46-59, README.md:14-23

Architecture and Components

The system is structured as a series of sequential operations that prioritize safety and verification. It consists of three primary logic blocks: Git operations for versioning, file system manipulation for applying changes, and a verification engine to check site health.

Core Logic Flow

The following diagram illustrates how a single proposed change is processed by the modifier:

The logic ensures that any failure in the string matching or the post-change verification results in an immediate rollback of that specific change.
Sources: src/engine/codeModifier.ts:65-117, plan.md:121-125

Key Functions and Data Structures

The system relies on specific interfaces and functions to track the status of modifications and interact with the underlying OS.

Data Structures

Interface	Field	Type	Description
ProposedChange	file	string	The relative path to the file being modified.
	original	string	The exact substring to search for in the source.
	replacement	string	The new content to insert.
ChangeResult	applied	boolean	Indicates if the write was successful.
	reverted	boolean	Indicates if a Git rollback was triggered.
	error	string	Details of any failures during application.

Sources: src/engine/codeModifier.ts:7-12, src/engine/codeAnalyzer.ts:6-13

Core Functions

• gitCommit(sitePath, message): Executes git add -A and git commit to create a recovery point. It uses the --allow-empty flag to prevent errors if no changes exist.
  Sources: src/engine/codeModifier.ts:14-24
• gitRevert(sitePath): Executes git checkout -- . to discard any uncommitted changes to the working directory, effectively rolling back the last attempt.
  Sources: src/engine/codeModifier.ts:26-32
• verifySiteLoads(siteUrl): Performs an asynchronous fetch request to the target site. It validates the response status (must be 200) and checks for the presence of essential HTML tags like </html> or root to confirm the application hasn't crashed.
  Sources: src/engine/codeModifier.ts:34-51
• applyChanges(changes, sitePath, options): The main entry point that iterates through a list of ProposedChange objects, applying them sequentially while managing the Git state.
  Sources: src/engine/codeModifier.ts:53-64

Verification and Safety Mechanisms

Safety is enforced through exact string matching and connectivity checks. The system is designed to be conservative, preferring to skip a change rather than apply a potentially incorrect or broken one.

Implementation Detail: File Modification

const content = readFileSync(filePath, "utf-8");

if (!content.includes(change.original)) {
  console.warn(`[modifier] Original string not found in ${change.file} — skipping`);
  // Log failure and continue to next
  continue;
}

const newContent = content.replace(change.original, change.replacement);
writeFileSync(filePath, newContent, "utf-8");

The use of content.includes(change.original) serves as a final validation step to ensure the Code Analysis agent (Phase 4) didn't propose a change based on stale or incorrect file snapshots.
Sources: src/engine/codeModifier.ts:83-97, src/engine/codeAnalyzer.ts:114-126

Git Integration Sequence

The system follows a strict commit pattern during the optimization loop to maintain a clean history and enable recovery:

1. Pre-change Commit: Tagged with pre-change-iter[N]-[Index].
2. Modification: The file is written to disk.
3. Post-change Verification: If verifySiteLoads returns false, gitRevert is called.
4. Final Iteration Commit: Once all changes in a batch are processed, a final commit post-changes-iter[N] is made.
   Sources: src/engine/codeModifier.ts:77-113, src/engine/optimizationLoop.ts:251-255

Integration with Optimization Loop

The Code Modifier is orchestrated by the runOptimizationLoop function. It receives inputs after the analyzeFailures function has processed friction points from the ReportGenerator.

Summary

The Git Rollback & Code Modifier system provides a robust framework for autonomous website improvement. By wrapping file-system writes in Git transactions and verifying site availability immediately after each change, it allows SynthCrowd to iteratively "fix" conversion issues without manual developer intervention while guaranteeing that the target website remains functional throughout the process.
Sources: plan.md:52-59, src/engine/codeModifier.ts:119-124