@ossl-dev/differens-tiers

The parsing pipeline. A content router picks a tier by file extension and magic bytes. The tier adapter parses the file into a Node tree for @ossl-dev/differens-core. If a tier fails to parse, or its diff falls back, the pipeline drops to the next lower tier. Raw line diff is the floor. Install:

npm install @ossl-dev/differens-tiers

Tiers

Tier	Value	Handles
`Tier.Binary`	`0`	Binary files: byte-size update, no parse
`Tier.Raw`	`1`	Line diff (`diffLines`)
`Tier.Prose`	`2`	Word diff for free prose (txt, log, readme, changelog)
`Tier.Markup`	`3`	HTML/XML/SVG: tree diff of tags
`Tier.Data`	`4`	JSON/YAML/TOML: tree diff of values
`Tier.Code`	`5`	tree-sitter backed code parsing

Exports

Export	Kind	Description
`classifyFile`	function	Map a path to its tier
`diffWithTier`	function	Diff two sources through the tier pipeline
`isParseable`	function	Will this file get a tree diff or only lines?
`initExtractors`	function	Await grammar loading (returns `Promise<void>`)
`getExtractors`	function	List available language extractors
`parseCode` / `parseData`	function	Parse a single side into a `Node` tree
`hasGrammar`	function	Is a grammar loaded for an extension?
`registerBinaryPlugin` / `unregisterBinaryPlugin`	function	Add / remove a T0 format plugin
`Tier`	enum	Tier identifiers above

classifyFile

classifyFile(filePath: string): FileInfo
// FileInfo: { path, extension, tier }

Extension-based routing, with a binary sniff (NUL bytes or failed UTF-8 decode) on top. Markdown goes to Tier.Raw, not prose: lines are structure in docs. CSV, TSV, GraphQL, and Dockerfiles are line-structured the same way, so they route to Tier.Raw too. Environment files (.env, .env.local) route to Tier.Data: KEY=VALUE lines parse as the TOML subset, so a changed value reports with its key path.

diffWithTier

diffWithTier(oldSource: string, newSource: string, oldPath: string, newPath: string): TierDiffResult

// TierDiffResult:
// { changes: EditAction[]; nodeCount: number; tier: Tier; fallback?: string }

Behavior worth knowing:

Entirely new or removed files become a single Insert/Delete of a kind: "file" node. That is one fact, not a tree diff.
Identical sources short-circuit with no changes.
A tier result is kept only if it parses and produces a usable tree diff; the core’s fallback verdict propagates instead of being reported as “no changes”.
On any failure the pipeline falls back to raw lines, with fallback: "lines".

LanguageExtractor

Each code language is a LanguageExtractor: a few dozen match arms that map tree-sitter CST node types to canonical concepts. It is not a parser.

interface LanguageExtractor {
  readonly language: string;            // e.g. "typescript"
  readonly extensions: string[];        // e.g. ["ts", "tsx"]
  extractConcept(nodeType: string): string;          // CST type -> canonical concept
  extractLabel(node: SyntaxNode, source: string): string | undefined;
  readonly labelFallbackTypes?: ReadonlySet<string>;
}

getExtractors() reports them as ExtractorInfo { language, level: "L6" | "L5", extensions }, where L6 extractors have semantic mappings and L5 are generic. Sixteen languages register extractors: TypeScript/JavaScript, Python, Rust, Go, C, C++, Java, Ruby, PHP, Swift, Kotlin, C#, Scala, Lua, and shell. A grammar registered without an extractor reports as L5. parseCode keeps a content-addressed cache (64-entry LRU, keyed by content hash and extension), so the same file content reappearing in one run parses once. The cache is per-run and per-process by design; worker children build their own.

BinaryDiffPlugin

T0 format plugins upgrade binary files from the byte-delta report to a real diff:

interface BinaryDiffPlugin {
  id: string;                                  // unique, for unregistering
  extensions: string[];                        // lowercase, no dot
  diff(oldBytes: Uint8Array, newBytes: Uint8Array): EditAction[] | undefined;
  // return actions to answer, undefined to decline and let the next plugin try
}

Plugins register in-process with registerBinaryPlugin. The first non-declining answer wins; a throwing plugin is skipped; the default byte-delta report always remains as the floor. Dynamic plugin loading from disk is deliberately not included: that belongs to an ecosystem layer, not the diff pipeline.

Usage

import { classifyFile, diffWithTier } from "@ossl-dev/differens-tiers";

const oldSource = "export function total(a, b) { return a + b; }";
const newSource = "export function sum(a, b) { return a + b; }";

const info = classifyFile("src/math.ts");   // { path, extension: "ts", tier: 5 }
const result = diffWithTier(oldSource, newSource, "src/math.ts", "src/math.ts");

console.log(result.tier);        // Tier.Code
console.log(result.changes);     // one Update action: Renamed, total -> sum

import { initExtractors, getExtractors } from "@ossl-dev/differens-tiers";

await initExtractors();
for (const { language, level, extensions } of getExtractors()) {
  console.log(language, level, extensions.join(", "));
}

​@ossl-dev/differens-tiers

​Tiers

​Exports

​classifyFile

​diffWithTier

​LanguageExtractor

​BinaryDiffPlugin

​Usage