@ossl-dev/differens-core

This package contains the tree matching engine. It takes two node trees and produces a typed edit script. The algorithm follows the GumTree lineage: top-down isomorphic matching finds anchors, bottom-up container matching pairs the rest, and leaf recovery fills the gaps. The result is a typed edit script with a minimal Move set. The package has zero dependencies. Tier adapters in @ossl-dev/differens-tiers parse source into Node trees and call diffTrees. Install:

npm install @ossl-dev/differens-core

Exports

Export	Kind	Description
`diffTrees`	function	Match two trees and produce an edit script
`treeFromValue`	function	Build a `Node` tree from a plain JS value
`createNode`	function	Build one `Node`, computing its hashes
`Node`	interface	The tree node shape
`EditAction`	union	`Insert` / `Delete` / `Update` / `Move`
`MatchOptions`	interface	Matching knobs
`DiffResult`	interface	Return shape of `diffTrees`

diffTrees

diffTrees(oldRoot: Node, newRoot: Node, options?: Partial<MatchOptions>): DiffResult

Returns { changes: EditAction[], nodeCount: number, fallback?: "lines" }. When either tree exceeds maxNodes, fallback is "lines" and the change list is empty. Line-diff instead in that case.

MatchOptions

Option	Default	Meaning
`minHeight`	`2`	Below this height an ambiguous subtree only matches when its parent already did
`bottomUpRatio`	`0.5`	Minimum Dice coefficient of matched descendants to pair two containers
`maxNodes`	`250_000`	Node-count valve: larger inputs fall back to a line diff

Node

Field	Type	Meaning
`kind`	`string`	Canonical concept, e.g. `"function"`
`label?`	`string`	Name, when the node has one
`value?`	`string`	Source text or primitive value
`children`	`Node[]`	Child nodes
`byteRange`	`[start, end]`	Source offsets
`line?`	`number`	1-based source line, when the adapter knows it
`height`	`number`	Distance from the leaves
`contentHash`	`number`	Merkle hash over kind + label + value + children
`structureHash`	`number`	Merkle hash over kind + children only (label/value ignored)

Both hashes are 53-bit-safe folds of two 32-bit FNV-1a streams, so subtree equality is an integer compare.

EditAction

Type	Fields
`Insert`	`node`, `parent`, `position`, `context`
`Delete`	`node`, `context`
`Update`	`node`, `detail: RenameDetail \| ValueChangeDetail`, `context`
`Move`	`node`, `fromParent`, `toParent`, `fromPosition`, `toPosition`, `context`

context: NodeContext[] is the containment chain, nearest ancestor first. Each entry is { kind, label? }. It lets narration say “removed parse from class Config”, and gives AI tooling the full chain without re-parsing. RenameDetail: { kind: "Renamed", from, to }. ValueChangeDetail: { kind: "ValueChanged", from?, to? }.

Usage

import { diffTrees, treeFromValue } from "@ossl-dev/differens-core";

const oldTree = treeFromValue({ host: "localhost", port: 8080 });
const newTree = treeFromValue({ host: "0.0.0.0", port: 8080 });

const { changes } = diffTrees(oldTree, newTree);

for (const action of changes) {
  console.log(action.type, action.node.kind, action.node.label);
  // "Update" "leaf" "host"   (detail: ValueChanged)
}

import { createNode } from "@ossl-dev/differens-core";

const tree = createNode({
  kind: "function",
  label: "parseConfig",
  children: [createNode({ kind: "identifier", value: "config", byteRange: [0, 6] })],
  byteRange: [0, 50],
});

​@ossl-dev/differens-core

​Exports

​diffTrees

​MatchOptions

​Node

​EditAction

​Usage