Diff Parsing & Line Validation

Relevant source files

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

• packages/diff-parser/src/parser.ts
• packages/diff-parser/src/index.ts
• packages/review/src/orchestrator.ts
• packages/github/src/review-client.ts
• packages/review/src/schemas.ts
• README.md

The Diff Parsing & Line Validation system is a critical utility within the AI Code Reviewer pipeline. Its primary purpose is to convert raw unified diff patches received from the GitHub API into structured data that maps added and context lines to their actual 1-indexed line numbers in the new version of a file.

This system ensures technical accuracy by preventing "hallucinated" line numbers from the LLM. By validating every AI-generated comment against a set of commentableLines, the system avoids GitHub API errors (specifically 422 Unprocessable Entity) that occur when an inline comment is placed on a line that does not exist or is not part of the changed diff hunks.

Sources: packages/diff-parser/src/parser.ts:1-20, packages/diff-parser/src/index.ts:1-13, README.md:144-149

Diff Parsing Logic

The parser processes unified diff syntax, which includes hunk headers and line prefixes (+, -, ). Unlike traditional diff processing that relies on diff position offsets, this module calculates the real file line numbers for the "RIGHT" side (the new file).

Data Structures

The parser utilizes specific interfaces to represent the structured diff data:

Interface	Description
DiffLine	Represents a single line with its type (added, removed, context), line numbers, and content.
DiffHunk	A group of lines identified by a hunk header, containing start lines for old and new files.
ParsedPatch	The final output containing all hunks and a Set of commentable line numbers.

Sources: packages/diff-parser/src/parser.ts:31-54

Parsing Process

The parsePatch function iterates through the raw patch string to reconstruct the file's structure within the scope of the changes.

1. Hunk Header Identification: Uses the regex /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/ to find start positions for the old and new files.
2. Line Tracking:
   • Added lines (+): Increments the newLine counter and adds the number to the commentableLines set.
   • Removed lines (-): Increments the oldLine counter but does not add to commentableLines.
   • Context lines ( ): Increments both counters and adds the newLine to the commentableLines set.
3. Validation Guard: The isCommentableLine function provides a boolean check to verify if a specific line index is valid for commenting.

The flow shows how raw text is converted into a structured ParsedPatch object containing a set of valid line numbers.
Sources: packages/diff-parser/src/parser.ts:60-104, packages/diff-parser/src/parser.ts:114-116

Integration with the Review Pipeline

The Orchestrator utilizes the diff parser for every file in a Pull Request that contains a patch. This integration ensures that the LLM only receives relevant context and its output is strictly governed by the actual diff.

Validation Sequence

Before comments are persisted to the database or posted to GitHub, the orchestrator performs a validation loop.

This diagram illustrates how the ParsedPatch acts as a validator for LLM-generated output before any external API calls are made.
Sources: packages/review/src/orchestrator.ts:153-158, packages/review/src/orchestrator.ts:208-219

Line and Side Specifications

The system adheres to the modern GitHub Review API requirements, which favor actual line numbers over legacy diff positions.

• Line Numbers: Must be 1-indexed integers representing the position in the new file.
• Side: Defaults to RIGHT (the new file). While LEFT is supported for deleted content in the schema, the parser primarily focuses on the RIGHT side for commentable targets.
• Commentable Constraints: Comments are only valid on lines that appear in the diff, which include added lines and the surrounding context lines provided by GitHub.

Sources: packages/review/src/schemas.ts:21-25, packages/github/src/review-client.ts:89-94, packages/diff-parser/src/parser.ts:46-52

Summary Statistics

The diffStats function provides a high-level overview of the file changes, which can be used for logging or as lightweight context for the LLM.

Metric	Derivation
hunks	Count of @@ headers in the patch.
additions	Total count of lines starting with +.
deletions	Total count of lines starting with -.

Sources: packages/diff-parser/src/parser.ts:122-132

Error Handling & Edge Cases

The system is designed to be resilient against malformed diffs or files that cannot be reviewed:

1. Large Files: Files exceeding GitHub's ~20 KB limit do not have a patch field and are skipped by the parser.
2. Binary Files: These are explicitly filtered out as they contain no reviewable text content.
3. Empty Patches: parsePatch returns an empty set of commentableLines if the patch is empty or blank, causing the orchestrator to skip the file.
4. No Commentable Lines: If a file contains changes that don't result in commentable lines (e.g., only deletions that the LLM shouldn't comment on directly), the orchestrator logs a debug message and continues.

Sources: packages/diff-parser/src/parser.ts:22-24, packages/review/src/orchestrator.ts:154-157, packages/github/src/review-client.ts:46-48

Conclusion

Diff Parsing and Line Validation serve as the "ground truth" for the AI Code Reviewer. By bridging the gap between raw Git patches and structured line-level data, the system ensures that the AI's feedback is actionable and compatible with the GitHub platform. This module effectively eliminates a major class of API failures caused by LLM line hallucinations.

Sources: README.md:144-149, packages/diff-parser/src/index.ts:1-13