AlignDiff

AlignDiff turns local Git changes into complete, structure-aware relationships between code blocks, while they never leave your local browser. 100% code and network privacy

Comment

Inspiration

Traditional line diffs become difficult to trust during refactors. A function may be renamed, moved to another part of the file, or changed internally, and the reviewer must mentally reconstruct what happened from disconnected additions and deletions.

I built AlignDiff to answer a simpler question:

Can a reviewer see the complete old and new files while the tool also explains which structures moved, changed, appeared, or disappeared?

Source-code privacy was equally important. Developers should not have to upload proprietary code merely to understand a refactor.

What it does

AlignDiff is a browser-local, structure-aware comparison tool for Python, JavaScript, and TypeScript.

Users can paste or load an old and new file, then compare them entirely inside the browser. AlignDiff:

  • parses supported languages locally;
  • identifies functions, classes, methods, imports, constants, and other structures;
  • pairs structures that were moved, renamed, or modified;
  • distinguishes unchanged, moved, modified, added, deleted, and uncertain matches;
  • aligns detailed code rows within changed structures;
  • falls back safely to a bounded text comparison when structural parsing is unreliable;
  • keeps source code in the browser instead of sending it to a hosted comparison service.

Its primary Aligned File view preserves complete-file context so reviewers can verify that no part of either file has disappeared. Supporting Source Order and Pair Details views help investigate movement, matching rationale, and detailed changes.

AlignDiff deliberately exposes uncertainty rather than presenting every possible match as fact. Reviewers can inspect possible pairings and make their own judgment.

How I built it

The application combines:

  • a React and TypeScript interface;
  • Vite for development and production builds;
  • Tree-sitter language parsers running in a browser worker;
  • a Rust comparison engine compiled to WebAssembly;
  • deterministic structural matching and classification;
  • browser-local detailed diff refinement;
  • Vitest, Node test suites, Rust tests, and Playwright browser validation;
  • CircleCI delivery to Cloudflare Pages.

The production application is deployed at aligndiff.com.

How I used GPT-5.6

GPT-5.6, used through Codex, was an implementation and review partner throughout Build Week.

Rather than using one long, unconstrained coding session, I divided the work into bounded sessions with explicit goals, repository restrictions, validation commands, and recorded session evidence. GPT-5.6 helped with:

  • designing complete-file trust requirements;
  • implementing and reviewing browser-local comparison workflows;
  • identifying gaps between claimed and executable behavior;
  • creating regression tests for previously observed failures;
  • repairing frontend usability and deployment integration;
  • reviewing changes against the product contract;
  • diagnosing validation and CI failures.

Every material implementation slice was independently validated before being accepted. The repository keeps a session ledger separating the task, model evidence, result, validation, and commit.

What I built during Build Week

AlignDiff had earlier comparator foundations, but Build Week transformed those foundations into a deployable Local Changeset Review experience.

The Build Week work included:

  • the complete Aligned File trust experience;
  • browser-local direct file entry;
  • structure-aware comparison across Python, JavaScript, and TypeScript;
  • clearer movement, modification, insertion, deletion, and uncertainty presentation;
  • source-order and pair-detail review views;
  • responsive application and landing-page redesign;
  • privacy-focused local processing checks;
  • deterministic quality and regression catalogs;
  • production asset verification;
  • CircleCI and Cloudflare deployment from the new canonical repository.

The released candidate passed the canonical repository validation, 150 functional browser tests, and 10 production deployment smoke tests before being deployed.

Challenges

Preserving complete-file trust

A structurally paired view can accidentally focus only on matched functions and hide unmatched or unchanged context. The product therefore needed explicit complete-file accounting and tests proving that every source line remained represented.

Avoiding false confidence

Two blocks may look similar without representing the same logical entity. AlignDiff distinguishes automatic matches from possible candidates and suppresses several classes of weak, low-information matches.

Keeping everything browser-local

The parser runtime, language grammars, WebAssembly engine, worker scripts, and source files all had to operate without sending user code to an external comparison API.

Making production behave like local development

Worker files, WebAssembly assets, nested public paths, redirects, and release metadata all needed separate production validation. The final deployment pipeline builds, verifies, smoke-tests, and then publishes the same portable artifact.

What I learned

The most important lesson was that trustworthy review is not only about producing a clever match. It is also about showing:

  • what the tool knows;
  • what it is uncertain about;
  • whether the full input is still present;
  • why two structures were paired;
  • and where processing occurs.

Privacy is strongest when it is an architectural boundary, not merely a promise in the interface.

What's next

The current public experience focuses on direct old/new file comparison.

The next major step is a simple user-facing local Git changeset generator that can create review inputs without requiring users to understand an internal file format. That will make multi-file repository review practical while preserving the same browser-local privacy boundary.

Further work will include richer file queues, rename-aware changeset navigation, improved manual pairing workflows, and expanded language support.

Built With

Share this project:

Updates