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.