Syntax Diff

Syntax Diff is a local CLI and browser app for comparing code structure at two committed Git revisions. It uses Tree-sitter for concrete syntax and React Flow for a linked, side-by-side declaration view.

Develop

Requires Node.js 22 or newer and system Git.

npm install
npm test
npm run build
npm run cli -- main feature/my-change

Use --file src/example.ts to focus an initially selected changed file, --port 41721 to override the fixed port, or --no-open to suppress browser launch.

MVP Behavior

• Discovers all files changed between two directly resolved endpoint commits, including Git-detected renames.
• Uses a resizable repository-graph sidebar containing only changed files and their ancestor folders. Folder nodes show recursive changed-file and added/deleted-line counts and provide right-click Expand all / Collapse all actions; file nodes select the linked syntax comparison.
• Switches the repository folder pane and declaration file panes independently between spatial React Flow graphs and compact, virtualized React Arborist trees. Both renderers use the same structural projections and retain classifications, line ranges, relocation markers, counts, expansion, selection, and source-diff actions.
• Switches the right workspace between the structural Flow/Tree comparison and a complete split source diff for the selected file.
• Parses TypeScript, TSX, and Python lazily. Unsupported text files open as standard split Git diffs; binary and oversized files remain visible with explicit fallback states.
• Matches exact syntax with full-tree SHA-256 Merkle fingerprints. Edited declarations remain removed/added; exact moves are marked as structural relocation.
• Projects changed high-level symbols into separate base and target panes: functions, classes, methods, type declarations, and callable arrow-function members. Ordinary assignments, imports, and unaffected declaration leaves stay out of the canvas.
• Opens changed declarations in a 95vw side-by-side Git hunk dialog with old/new line numbers and one shared horizontal scrollbar.
• Collapses unchanged declaration subtrees, automatically expands single-child folder and declaration chains, attaches Git source hunks to changed declarations, and synchronizes pane navigation through exact anchors.
• Gives focus to the repository graph or linked snapshot workspace when a click or drag starts, expanding either pane to 50vw only when it is smaller than half the viewport while preserving each graph's viewport center.
• Serves only on 127.0.0.1:41720 by default and fails clearly on port conflicts.
• Keeps repository navigation available when an individual file comparison fails.

Package

npm run build creates browser assets in dist/ and the prebuilt npm executable in dist-cli/. The intended published command is:

npx syntax-diff <base> <target>

See docs/library-review.md, docs/concepts.md, docs/directions.md, and docs/architecture.md.