Structure-aware code comparison

How it differs from line comparison

Pair relationships before reading local edits

A source-order line comparison primarily compares text where it appears now. If a function moves far down a file, that move can look like a large deletion followed by a large insertion. A structure-aware comparison first identifies supported structures such as functions, methods, classes, named arrow functions, and relevant TypeScript declarations. It then proposes old and new counterparts and renders their detailed textual differences in the same review lane.

The word “semantic” here does not mean that AlignDiff understands all program behaviour. It refers to using syntax structure and similarity evidence to organise comparison output. Pairing remains an inspectable proposal. A reviewer can see the alignment, the visible status, and the detailed differences rather than treating the result as a hidden decision.

When it helps

Useful when source order hides the change

This view is most useful when a local refactor combines movement and editing. A reviewer can keep a moved function beside its counterpart while checking a changed return expression, a renamed helper, or a new-only block. It can also make competing structural candidates visible instead of implying that a name change alone settles identity. The worked checkout-refactor example shows these signals in one small fixture.

It is a way to reduce navigational noise in a focused comparison, not a model of the surrounding repository, deployment environment, or business rules. The detailed result stays tied to the two files the reviewer supplied.

Supported scope

Deliberately narrow browser support

The current browser product supports Python, JavaScript (.js, .mjs, and .cjs), and TypeScript (.ts). Initial structural entities include functions, methods, classes, named arrow functions, and TypeScript interfaces and type aliases. JSX and TSX are not supported. When structure-aware parsing is unavailable, the product retains a bounded source-order text comparison rather than inventing a structural result.

Limits

Structural similarity is not behavioural proof

A structural match does not prove behavioural equivalence, runtime correctness, dependency impact, test completeness, pull-request safety, or developer intent. It also does not prove that every automatic pairing is correct. Those questions require human judgement and the appropriate tests or review process. The evidence page separates the product’s observable signals from those unsupported conclusions.