feat: handle flow sequences gracefully in sync, insert, append, extend_list

[nathanjmcdougall]

Closes #31

Summary

Previously, sync(), insert(), append(), and extend_list() raised PatchError when operating on flow sequences (e.g. repos: [] or items: [a, b, c]). This forced callers to wrap calls in try/except and fall back to upsert().

Now these methods detect the flow sequence error and automatically fall back to a full replace operation, which converts the flow sequence to a block sequence. This is always correct because:

• Empty flow sequences ([]) have no formatting to preserve
• Non-empty flow sequences cannot contain comments
• The alternative was crashing

Changes

Flow sequence fallback (Category A)

• sync() — catches PatchError("expected BlockSequence") and falls back to Op.replace(value)
• insert() — catches the error, does list.insert() in Python, replaces the whole list
• append() — catches PatchError("flow sequence"), appends in Python, replaces
• extend_list() — same pattern as append

NodeTypeError (Category B)

• New NodeTypeError(PatchError, TypeError) for when operations are called on the wrong node type
• remove_from_list() now raises NodeTypeError instead of raw PatchError when the target isn't a list
• Backward compatible: existing except PatchError handlers still catch it

Test coverage

• 6 new tests for sync() on flow sequences
• 4 new tests for insert() on flow sequences
• 4 new tests for append()/extend_list() on flow sequences
• 2 new tests for NodeTypeError hierarchy

[Copilot]

Pull request overview

This PR improves yamltrip.Document list-mutation ergonomics by making sync(), insert(), append(), and extend_list() handle YAML flow sequences (e.g. items: [a, b], items: []) without raising PatchError, generally by falling back to a whole-value replace() that converts the node to a block-style representation. It also introduces a NodeTypeError exception to better distinguish “wrong node type for operation” from other patch failures.

Changes:

• Add flow-sequence fallbacks for sync(), insert(), append(), and extend_list() (replace whole list when patching can’t mutate a flow sequence).
• Introduce NodeTypeError(PatchError, TypeError) and use it for clearer type-mismatch failures (e.g. remove_from_list() on non-lists).
• Add/expand test coverage for flow sequence behaviors and NodeTypeError inheritance/usage.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/yamltrip/document.py	Adds flow-sequence pre-conversion for sync() and fallback behaviors for list mutations; raises NodeTypeError for type mismatches.
src/yamltrip/errors.py	Defines the new NodeTypeError exception type.
src/yamltrip/__init__.py	Exports NodeTypeError as part of the public API.
tests/test_sync.py	Adds flow-sequence-focused sync() tests, including nested mapping cases and sibling-comment preservation.
tests/test_document.py	Adds flow-sequence tests for append()/extend_list()/insert() and adds NodeTypeError behavioral tests.
tests/test_errors.py	Verifies NodeTypeError inherits from both PatchError and TypeError.
doc/specs/2026-05-20-flow-sequence-fallback-design.md	New design spec documenting the flow-sequence fallback approach.
doc/specs/2026-05-20-node-type-error-design.md	New design spec documenting the NodeTypeError rationale and hierarchy.
uv.lock	Updates the editable yamltrip package version reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.