Add representation-preserving YAML entry removal

[MariusStorhaug]

Configuration authors need to remove selected YAML data without converting the stream into lossy PowerShell objects. Existing object projection cannot preserve tags, complex keys, anchors, aliases, shared or recursive graphs, mapping order, or multiple-document boundaries.

Request

Desired capability

Add Remove-YamlEntry as a pure text transformation that removes one or more entries selected by RFC 6901 JSON Pointer while preserving the unaffected YAML representation graph.

Acceptance criteria

• Accept YAML through mandatory pipeline-capable -InputObject [string[]], aggregate records with LF as one stream, and return exactly one normalized LF-only string without a final newline.
• Accept one or more mandatory JSON Pointers through -Path [string[]]; an empty pointer selects a document root, and non-empty pointers require strict /, ~0, and ~1 syntax.
• Select document zero by default through -DocumentIndex, or apply every path independently to every original document with mandatory -AllDocuments.
• Address mapping entries only through ordinal-matching scalar string keys; preserve but never coerce complex, non-string, or unknown-tagged keys.
• Address sequences only with canonical non-negative decimal indexes and reject signs, -, leading zeros, overflow, and malformed values.
• Resolve and validate every target against an immutable deep-cloned representation graph before applying changes. -IgnoreMissing skips only unresolved targets.
• Coalesce duplicate logical targets reached through aliases, let ancestors subsume descendants, and remove sequence children and document roots in descending original index order.
• Preserve unaffected tags, anchors, aliases, shared and cyclic identity, complex keys, mapping order, and document order. Removing inside a shared collection is visible through every alias; removing an alias edge removes only that edge.
• Remove selected root documents and return an empty string when no documents remain.
• Mirror parser and emitter safety controls for indentation, depth, nodes, aliases, scalar length, tag lengths, and numeric length. Bound cloning, pointer parsing and resolution, coalescing, mutation, and output validation with classified errors.
• Include complete command help, README and example usage, generated documentation and package export coverage, source and built-artifact tests, deterministic self-parse coverage, and cross-platform Process-PSModule validation.

---

Technical decisions

Representation model: Reuse the repository-owned parser, representation graph, graph clone, and deterministic emitter. Never project through PSCustomObject, evaluate expressions, or add an external parser dependency.

Pointer resolution: Decode each pointer once, then resolve every document/path combination against the original clone. Mapping matching uses the effective YAML string tag plus ordinal scalar content. Sequence matching uses canonical decimal syntax and bounded Int32 indexes.

Identity and ordering: Logical targets are keyed by parent node identity and original entry index. Duplicate requests retain all ancestry paths so an independently requested shared mutation is not lost when a separate alias ancestor is removed. Mutation groups shared parents and removes their original indexes in descending order.

Transactions and errors: No mutation begins until all required resolutions succeed. Missing targets use one classified error with extra guidance when unaddressable mapping keys are present. Malformed pointers, invalid sequence tokens, ambiguous keys, invalid document selection, and resource limits remain terminating even with -IgnoreMissing.

Safety: Parsing, cloning, removal work, and output validation use independent limits. Result validation also prevents a removal from creating an invalid !!omap, !!pairs, or !!set shape.

Delivery: Stack the draft pull request on implement-merge-yaml, classify it as Minor, and keep it in draft through source, built artifact, parser, analyzer, documentation, site, corpus, and PowerShell 7.6 Windows/Linux/macOS validation.

---

Implementation plan

Core changes

• Add strict JSON Pointer parsing, bounded alias traversal, target resolution, coalescing, mutation ordering, and result validation helpers.
• Add the public Remove-YamlEntry command with the complete parameter and help contract.

Tests

• Add focused source tests for pointers, mapping and sequence addressing, documents, transactions, aliases, cycles, tags, limits, determinism, and idempotence.
• Add package export and fresh-process built-artifact coverage.
• Run the full source and built-artifact Pester suites plus parser, analyzer, and corpus gates.

Documentation and delivery

• Update README and runnable examples.
• Generate and validate command documentation and the documentation site.
• Open and maintain the stacked draft pull request through Process-PSModule validation on Windows, Linux, and macOS.

[MariusStorhaug]

Aligned the stale duplicate merge description with the assigned removal work. - Replaced the duplicate #43 merge scope with the supplied Remove-YamlEntry contract - Added representation, pointer, transaction, safety, test, documentation, and stacked-delivery decisions - Recorded current core/test progress and the remaining package, documentation, artifact, and CI gates

[MariusStorhaug]

Completed the implementation plan and validation record. - Added the public representation-preserving removal command and transactional graph helpers - Covered strict pointers, documents, ordering, aliases, cycles, tags, limits, determinism, package export, and fresh-process behavior - Updated README, examples, generated command help, and site output - Passed full source and generated-module Pester, parser and analyzer gates, plus Process-PSModule on Windows, Linux, and macOS in run 30149822606 - Kept draft PR #46 stacked on #45