Skip to main content

​
Tier system

Every file that Differens processes goes through a tier adapter. The content router classifies files by extension and dispatches them to the right tier. Each tier can fall back to the tier below it. If the code parser fails, the line diff catches it. If the file is too large for the line diff, the hash fallback catches it.

​
Tier reference

​
Classification rules

The content router (classifyFile in @ossl-dev/differens-tiers) maps extensions:
  • Code extensions (.ts, .py, .rs, .go, etc.) → T5, with a tree-sitter grammar lookup. If no grammar is installed for the language, the file falls back to T1.
  • Data extensions (.json, .yaml, .toml) → T4. Unparseable data (malformed JSON) falls to T1.
  • Markup (.html, .htm, .xml, .svg) → T3. Element tree with attribute diffs.
  • Markdown and doc formats (.md, .mdx, .rst, .adoc) → T1 line diff.
  • Prose (.txt, .log, files named LICENSE, README, CHANGELOG, AUTHORS) → T2 word-level diff.
  • Everything else → T1 (line diff) or T0 (binary detection via null bytes).

​
Graceful degradation

The pipeline degrades instead of failing. At every level:
  1. Try the most specific parser for the file type.
  2. If it throws, try the next tier down.
  3. T0 is the terminal tier. It compares file hashes, and there is no tier below it.
Run differens on any file, in any format, at any size. The result ranges from a full semantic diff down to a hash comparison: “file changed, 1423 bytes different.”

​
Adding a tier adapter

New formats get new tiers. See Contributing for the step-by-step guide. Every adapter must produce a Node tree the diff core can consume. What the tree contains is up to the adapter. It can be a tree-sitter CST, a JSON path tree, an HTML element tree, or any other structured representation.