succinctly: Skill for Claude Code

YAML Semi-Indexing Skill

Implementation details for YAML semi-indexing using succinct data structures.

Comprehensive documentation: See docs/parsing/yaml.md for full parsing architecture.

Semi-Index Structure

YAML uses more components than JSON due to its richer structure:

• Interest Bits (IB): Marks structural positions (keys, values, items)
• Balanced Parentheses (BP): Encodes tree structure for navigation
• Type Bits (TY): Distinguishes mappings (0) from sequences (1)
• Sequence Item Bits (seq_items): Marks BP positions that are sequence item wrappers

Key Insight: Sequence Items vs Containers

Sequence items have BP open/close pairs but NO TY entry. This affects TY index calculations:

// WRONG: Direct rank gives incorrect TY index when seq_items exist
let ty_idx = bp.rank1(bp_pos);

// CORRECT: Subtract sequence items to get real container index
let bp_opens_before = bp.rank1(bp_pos);
let seq_items_before = count_seq_items_before(bp_pos);
let ty_idx = bp_opens_before.saturating_sub(seq_items_before);

Block Sequence Parsing

Multi-line Sequence Items

For YAML like:

-
  name: Mark
  hr: 65

The sequence item must remain open so content on subsequent lines becomes the item's value:

1. Parse - at indent 0 → open sequence, open item, push (indent+1, SequenceItem) to stacks
2. at_line_end() is true → return (item stays open)
3. Next line name: Mark at indent 2 → parse_mapping_entry(2)
4. Mapping opened inside the still-open item
5. Subsequent lines at same indent add to mapping
6. When indent returns to 0, close_deeper_indents closes mapping, item, etc.

Inline Compact Mappings

For - name: Mark\n hr: 65:

1. Parse - → open sequence, open item
2. looks_like_mapping_entry() is true → call parse_compact_mapping_entry(indent+2)
3. Mapping opened but NOT closed after first entry
4. Item also NOT closed
5. Next line hr: 65 at indent 2 adds to the same mapping