Module yaml_edit 

Comment-preserving YAML edit substrate.

Wraps yaml_edit (rowan-backed lossless syntax tree) so callers that mutate .team/*.yaml keep the user’s comments, blank-line clusters, and key ordering intact across save. The previous serde_yaml::Value round-trip stripped all of that on every write — see the dogfood .team/projects/teamctl.yaml regressions on the PR #54 + PR #55 cascades for the class this closes.

Surface

• load / save — IO with anyhow context.
• Re-exports of yaml_edit::Document, yaml_edit::Mapping, yaml_edit::Sequence, and YamlPath so callers can drive the editor directly for round-trip + leaf updates.
• set_nested_mapping — bounded line-anchored helper for the one pattern yaml-edit 0.2.x can’t do natively: insert or replace a properly-indented sub-block at a known parent path.

Why the bounded helper

yaml_edit::Document::set_path creates intermediate mappings via MappingBuilder::new().build_document().as_mapping() and inserts them with mapping.set(key, &empty_mapping). The empty mapping has zero base-indent, and the resulting nested entries serialize at column 0 instead of indenting under the parent (see path::set_path_on_mapping, registry source line 401-435 of yaml-edit 0.2.1). Filed upstream for a fix; until then set_nested_mapping handles the create-nested pattern via line-anchored splice into the source string before the Document re-parse. Substrate consumers never see the splice.

Per-pm scope lock (msg 1969): the helper handles ONE pattern only (“insert a properly-indented sub-block at a known parent path”). If a future T-077-E verb needs a different yaml-edit-gap workaround, escalate; do NOT generalize this helper.

Structs

Document

A single YAML document

Mapping

A YAML mapping (key-value pairs)

Sequence

A YAML sequence (list)

Traits

YamlPath

Trait for YAML types that support path-based access.

Functions

load

Read path and parse it as an editable YAML document.

save

Serialize doc and write it to path, replacing any previous contents.

set_nested_mapping

Insert or replace a nested mapping at the given parent path.

set_top_level_scalar

Replace a top-level scalar value (T-265 PR-a).