Semantic Analysis
AST parsing, semantic diffing, and intelligent merge powered by structural code understanding.
Overview
Trellis doesn't just see text — it understands code structure. The semantic analysis engine parses TypeScript and JavaScript into structural entities, enabling diffs that know the difference between renaming a function and deleting one.
Parsing Code
trellis parse src/engine.ts
This produces a ParseResult containing:
- Declarations — Functions, classes, interfaces, enums, type aliases
- Imports — Module import relationships
- Exports — Exported symbols
import { typescriptParser } from "trellis";
const result = typescriptParser.parse(source, "file.ts");
result.declarations; // ASTEntity[]
result.imports; // ImportRelation[]
result.exports; // ExportRelation[]
Semantic Diff
Compare two versions of a file at the AST level:
trellis sdiff src/old.ts src/new.ts
Produces SemanticPatch[] with types:
| Patch Type | Description |
|---|---|
symbolAdd | New function, class, or type added |
symbolRemove | Symbol deleted |
symbolModify | Symbol body changed |
symbolRename | Symbol renamed (detected by signature) |
importAdd | New import added |
importRemove | Import removed |
importModify | Import specifiers changed |
Semantic Merge
When branches diverge, semantic merge resolves conflicts at the entity level:
import { semanticMerge } from "trellis";
const merged = semanticMerge(ourPatches, theirPatches, "file.ts");
merged.clean; // true if no conflicts
merged.patches; // Merged patch list
merged.conflicts; // SemanticMergeConflict[] with suggestions
Semantic merge can automatically resolve many conflicts that would be ambiguous in line-based merging — like two branches adding different functions to the same file.