Add Merge-Json to combine JSON structures #47

Context and request

The data-module verb vocabulary includes Merge-<Noun> for combining two structures, and PSModule/Hashtable ships Merge-Hashtable as the reference implementation. Json has no equivalent, so a user combining a base configuration with an environment overlay — the most common reason to merge JSON at all — has to convert to hashtables, merge, and convert back.

Acceptance criteria.

• Merge-Json combines two or more JSON inputs into one, with later inputs taking precedence.
• It accepts both JSON strings and objects, consistent with the parameter set pattern the other commands in the module use.
• Nested objects merge recursively; the caller can choose whether arrays concatenate or replace.
• Merge depth is bounded by an explicit -Depth parameter rather than an internal constant.
• It declares [OutputType()] with matching .OUTPUTS, and carries complete comment-based help with a .LINK to https://psmodule.io/Json/Functions/Merge-Json/.
• Behaviour matches Merge-Hashtable wherever the operation is analogous.
• Tests cover recursive merge, array handling in both modes, precedence, null and missing keys, and type conflicts. Coverage stays at or above the 95% target.

Technical decisions

Study Merge-Hashtable before designing the surface. Users move between these modules and the two should not disagree about what merging means. Where JSON genuinely differs — typed arrays, null as a distinct value from absent — document the difference rather than inventing a new convention.

Array semantics are the real design decision and must be settled before implementation. Concatenate and replace are both defensible; replace is the more common expectation for configuration overlays and is the safer default, with concatenation available through a switch. Confirm what Merge-Hashtable does and align unless there is a JSON-specific reason not to.

null is a value in JSON, not an absence. An explicit null in a later input should override an earlier value rather than being skipped as though the key were missing. This distinction does not exist in the hashtable case and needs deciding explicitly.

Depth is a parameter from the outset. This is the defect being corrected in Export-Json, and it should not be reintroduced in a new command.

Depends on the function-standard work landing first so this is written against the corrected patterns — declared output contract, prose parameter set names, terminating errors.

Implementation plan

• Review Merge-Hashtable's parameters, precedence rules, and array handling
• Decide and record the array strategy, the null override semantics, and the type-conflict behaviour
• Write failing tests for recursive merge, precedence, both array modes, null override, missing keys, and type conflicts
• Implement src/functions/public/Merge-Json.ps1 with [OutputType()], full comment-based help, and a -Depth parameter
• Confirm the command appears in Get-Command -Module Json and its reference page generates
• Add a README capability example if merging is one of the module's headline capabilities
• Confirm coverage still meets the 95% target