🚀 [Feature]: YAML entries can now be removed without representation loss

[Marius Storhaug (MariusStorhaug)]

YAML streams can now have selected entries or whole documents removed without losing tags, complex keys, anchors, aliases, shared nodes, cycles, mapping order, or document order.

New: Representation-preserving YAML entry removal

Remove-YamlEntry accepts one or more RFC 6901 JSON Pointers and applies them as one transaction to document zero by default.

$cleanYaml = Get-Content -Path '.\config.yaml' |
    Remove-YamlEntry -Path @('/metadata/internalIdentifier', '/services/1/deprecated')

Use -DocumentIndex to select another zero-based document, or -AllDocuments to apply every pointer independently to every document. An empty pointer removes the selected document root, and -IgnoreMissing skips only unresolved document/path combinations.

Mapping tokens match only YAML string keys by ordinal scalar content. Sequence tokens must be canonical non-negative decimal indexes. JSON Pointer escapes are strict: ~0 addresses a tilde and ~1 addresses a slash.

Review hardening

• Post-mutation duplicate keys are rejected transactionally for ordinary mappings, !!set, and !!omap using bounded fingerprint candidate indexes plus cycle-safe structural equality. !!pairs retains its repeated-key semantics.
• Effective string tags and scalar mapping keys are compared with StringComparison.Ordinal, including composed/decomposed Unicode and near-standard unknown tags.
• Target subsumption uses strict resolved request paths and target-edge identity, so direct and longer cycles cannot suppress themselves or mutually suppress sibling targets.
• -AllDocuments:$false now follows default single-document behavior for nested and root removals; only an explicitly present true switch selects every document.

Technical Details

• The implementation works directly on a deep-cloned representation graph and never projects through PowerShell objects or evaluates expressions.
• Every target is resolved before mutation; one required missing target prevents all output changes.
• Parent-edge identity coalesces duplicate targets reached through aliases while retaining independent alias paths for correct ancestor subsumption.
• Shared collection mutations are grouped by parent identity and original indexes are removed in descending order, independent of the textual alias depth used to reach them.
• Parsing, clone creation, pointer and mutation work, structural key comparison, and result validation use independent resource ceilings with YAML-classified errors.
• Result validation preserves valid !!omap, !!pairs, and !!set shapes before deterministic representation emission.
• This pull request is stacked on 🚀 [Feature]: YAML streams can now be merged without representation loss #45. Every implementation-plan task in Add representation-preserving YAML entry removal #44 is complete.

Validation

• Full source Pester on PowerShell 7.6.4: 476 passed, 0 failed; 8 built-artifact-only tests skipped.
• Full generated-module Pester on PowerShell 7.6.4: 480 passed, 0 failed; 4 source-only tests skipped. The final artifact Remove-YamlEntry and packaging suites passed all 90 tests.
• PowerShell parser validation covered 124 files with no parse errors; repository source and built-module lint jobs passed on Windows, Linux, and macOS.
• Process-PSModule run 30152252297 passed all 56 jobs at 0941489, including source and built-module tests/lint on PowerShell 7.6 for Windows, Linux, and macOS, every per-command artifact suite, conformance/corpus tests, module build, generated command documentation, and site build.

Related issues

• Closes Add representation-preserving YAML entry removal #44

[Marius Storhaug (MariusStorhaug)]

Superseded by #47 (release/v1.0.0 consolidation PR). Closing this stacked layer as part of release cleanup.