parse-diff

parse-diff turns unified diff output — the kind produced by git diff, git show, or any patch/diff file — into a structured array of file objects, each broken down into chunks (hunks) and line-by-line changes tagged as additions, deletions, or normal context lines. It handles the full set of git diff headers: new/deleted file mode, old/new mode changes, index lines, quoted or timestamped filenames, and the \ No newline at end of file marker, so it works reliably against real-world git output rather than just idealized unified-diff examples.

Because it has zero runtime dependencies and ships both a CommonJS build and TypeScript type definitions, it’s commonly used as the parsing layer inside code-review tools, diff viewers, patch-application scripts, and CI bots that need to reason about what a diff actually changed — counting additions/deletions per file, walking chunks to render side-by-side views, or extracting the touched file paths.

What You Get

• Structured file objects - each parsed file exposes from/to paths, chunks, and running additions/deletions counts.
• Per-line change records - every changed line is tagged add, del, or normal with old/new line numbers preserved.
• Git header awareness - correctly parses new/deleted file mode, old/new mode, and index lines from real git diff output.
• Zero dependencies - a single small module with no runtime dependencies, safe to drop into any Node.js or browser bundle.
• TypeScript definitions included - ships index.d.ts with typed File, Chunk, and Change interfaces out of the box.

Common Use Cases

• Code review tooling - review-bot and diff-viewer authors use parse-diff to turn a pull request’s raw patch into renderable file/chunk/line structures.
• CI diff analysis - CI scripts parse git diff output to compute per-file addition/deletion counts or flag which files changed without shelling out to a second tool.
• Patch application scripts - tooling that needs to inspect or selectively apply hunks from a .patch file parses it first with parse-diff to get addressable chunks.
• Diff-based static analysis - linters/formatters that only want to check changed lines parse a diff to map line numbers back to the changed ranges.

Under The Hood

Architecture parse-diff implements a small hand-rolled state machine in a single module: two dispatch tables (one for diff-header lines, one for in-chunk content lines) match incoming lines against regexes and route them to handler closures that mutate a shared currentFile/currentChunk state held in the outer function’s scope. Which table is active is decided by whether the current chunk still has lines left to consume, tracked via a small counter object. This keeps the entire parser to one exported function with no external state, so the public contract is narrow — a single parseDiff(input): File[] call — and the internal state machine can be restructured freely as long as that shape holds.

Tech Stack The package is plain JavaScript with no runtime dependencies: Biome handles both linting and formatting under one config (replacing separate ESLint/Prettier setups), esbuild minifies the parse.js source into the published index.js, and Jest runs the test suite. A single GitHub Actions workflow installs dependencies and runs lint plus tests on every push and pull request against the master branch, pinned to a recent Node.js version. TypeScript consumers get a hand-authored index.d.ts alongside the CommonJS output rather than a compiled-from-source type layer.

Code Quality The test suite is extensive relative to the package’s size, covering null/empty/whitespace input, standard git-style diffs, mnemonic-prefix and quoted filenames, mode changes, new/deleted files, and missing-trailing-newline markers. There’s no explicit try/catch error handling, but the parser is designed as a pure function that degrades gracefully — returning an empty array for invalid input rather than throwing. Naming is consistent throughout, and Biome’s recommended lint rules run in CI alongside the test suite, though the implementation itself is untyped JavaScript rather than TypeScript.

API Design The public surface is a single function call — pass a diff string in, get back an array of typed file objects — with no configuration required to get started. The output shape (files containing chunks containing line-level changes) mirrors the structure of a real unified diff closely enough that consumers can map results back to the source text without much translation. TypeScript users get full autocomplete from the bundled type definitions. The parsing approach itself is conventional rather than novel, but the zero-configuration, dependency-free entry point is genuinely convenient to adopt.