Skip to main content

Interface: NodeTypeDescriptor

Defined in: packages/core/src/application/ports/artifact-parser.ts:251

Describes one addressable node type for a file format.

Each parser adapter returns an array of these from nodeTypes(). The applyDelta engine uses these descriptors for collection-aware logic, unwrapping, and semantic validation of delta operations.

Flag combinations reference​

Flags are NOT mutually exclusive — a node can be a container AND a leaf (e.g. a JSON property wrapping an object, which has both children and a scalar value). The only invalid combination is all false (a void node like markdown's thematic-break).

isCollectionisSequenceisSequenceItemisContainerisLeafExample
TTFTFlist, array, sequence
TFFTFobject, mapping
TFFFFparagraph (plaintext, wraps line children)
FFTTFlist-item (may wrap nested lists)
FFTTTarray-item, sequence-item (scalar or complex)
FFFTFsection, document
FFFTTproperty, pair (key wrapping scalar or complex)
FFFFTparagraph (md), code-block, line
FFFFFthematic-break (void)

How flags drive applyDelta​

  • isCollection: controls same-type unwrapping in added entries. When the parent scope is a collection and the parsed content's first child has the same type, the engine unwraps to the inner children (e.g. adding "a\nb" to a list unwraps the inner list-items).

  • isSequence: identifies ordered sequential collections (list, array, sequence) as opposed to keyed collections (object, mapping). Controls whether strategy (append/merge-by) is valid on the node and whether the node is treated as "array-like" for delta operations.

  • isSequenceItem: identifies items within a sequential collection. Used to detect "all children are sequence items" heuristics and to find inner array nodes wrapped inside property/pair containers.

  • isContainer: the node can have children. Hybrid nodes that are both container and leaf (e.g. property wrapping an object) set both isContainer: true AND isLeaf: true.

  • isLeaf: the node can have a scalar value. Hybrid nodes set both isContainer: true AND isLeaf: true.

  • identifiedBy (not a flag but related): if non-empty, the node has a label/identifier. Derived hasLabel = identifiedBy.length > 0 is used for rename validation (rename is only valid on identified nodes).

Properties​

description​

readonly description: string

Defined in: packages/core/src/application/ports/artifact-parser.ts:257

Human-readable description for LLM context generation.

identifiedBy​

readonly identifiedBy: readonly string[]

Defined in: packages/core/src/application/ports/artifact-parser.ts:255

Selector properties that identify a node, e.g. ["matches"]. Empty if the node has no label.

isCollection​

readonly isCollection: boolean

Defined in: packages/core/src/application/ports/artifact-parser.ts:263

True if this node's children are uniform items of a single type (e.g. list → list-item, object → property). Controls same-type unwrapping in added entries.

isContainer​

readonly isContainer: boolean

Defined in: packages/core/src/application/ports/artifact-parser.ts:283

True if this node can have children. Hybrid types (e.g. property wrapping an object) set both isContainer and isLeaf to true.

isLeaf​

readonly isLeaf: boolean

Defined in: packages/core/src/application/ports/artifact-parser.ts:288

True if this node can have a scalar value. Hybrid types set both isContainer and isLeaf to true.

isSequence​

readonly isSequence: boolean

Defined in: packages/core/src/application/ports/artifact-parser.ts:271

True if this node is an ordered sequential collection (list, array, sequence). object and mapping are collections but NOT sequences — their children are key-value pairs, not ordered items. Controls whether strategy (append/merge-by) is valid and whether the node is treated as "array-like".

isSequenceItem​

readonly isSequenceItem: boolean

Defined in: packages/core/src/application/ports/artifact-parser.ts:277

True if this node is an item within a sequential collection (list-item, array-item, sequence-item). Used for "all children are items" detection and inner-array lookup.

type​

readonly type: string

Defined in: packages/core/src/application/ports/artifact-parser.ts:253

Node type name, e.g. "section", "property", "pair".