[LIB] Fix the behavior of null-preserving visitor, refactor, add comparison tests

[mozesl-nokia]

#4746 didn't cover enough of the use-cases for the null preservation behaviour. This PR refactors a big chunk of that code, splitting the visitor into it's own class and reverted the changes on the old custom Visitor (except for the associative list bugfix).

Added some comparison tests so we can track how each of our visitors handle merges compared to each other and kyaml's original.

AI disclosure:

• Cursor Grok 4.7 was used to complete NullPreservingVisitor, add the comparison tests and for review

Update

• Renamed PreserveExplicitNull to PreserveNulls
  • Had to uncomment the api replace, plan to fix it immediately after
  • Added an "Experimental" marker to it, surprisingly we have already used this kind of marking for the --for-deployment flag of kpt pkg get
• Fixed schema generation
  • It has not been run at least since we migrated the api into it's own module, thus some very big diff there.
  • It should now be running when you do make generate

AI disclosure:

• Later used Grok 4.7 to update the docs and relevant docstrings after renaming things.

[netlify]

✅ Deploy Preview for kptdocs ready!

Name	Link
🔨 Latest commit	6c84812
🔍 Latest deploy log	https://app.netlify.com/projects/kptdocs/deploys/6abe2141c678cf0008067dcf
😎 Deploy Preview	https://deploy-preview-4774--kptdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Copilot review overview

🟡 Changes recommended

Upstream-null associative lists are not reliably preserved, and the expanded behavior conflicts with existing public documentation.

Review effort: Balanced
Findings: 1

Open (1)

• Update null-preservation API and CLI documentation · New

What changed in this PR

Refactors merge3 null preservation into a dedicated visitor and expands behavioral comparisons.

Changes:

• Separates default and null-preserving merge visitors.
• Adds shared null-handling utilities and associative-list preprocessing.
• Replaces legacy tests with broader preservation and kyaml comparison coverage.

File	Description
visitor.go	Restores the default merge visitor behavior.
visitor_util.go	Adds shared null-handling helpers.
tuple.go	Selects the appropriate visitor and preprocesses null lists.
preserve_test.go	Removes superseded preservation tests.
null_preserving_visitor.go	Implements dedicated null-preserving merge behavior.
null_preserve_test.go	Tests scalar and associative-list null preservation.
comparison_test.go	Compares custom visitors with kyaml behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mozesl-nokia]

Also, the "PreserveExplicitNull" is now misleading, because this implementation preserves all null values, not just the explicit ones. How awkward would it be to break fresh api changes by renaming it? @kptdev/maintainers

[Copilot]

Copilot review overview

🟡 Changes recommended

The default associative-list merge has a null-deletion regression, and schema generation is not reliably pinned.

Review effort: Balanced
Findings: 1 · 2 · 2

Open (5)

• Handle absent-origin tagged null as destination list deletion · New
• Pass SWAGGER_VERSION explicitly to schema generation · New
• Match installed schema versions exactly · New
• Emit valid CEL expression in generated example · New
• Emit valid CEL expression in generated example · New

Resolved since last review (1)

• Update null-preservation API and CLI documentation

[Copilot]

Copilot review overview

🟡 Changes recommended

Legacy Kptfile compatibility and associative-list null-preservation issues remain unresolved.

Review effort: Lite
Findings: 1

Open (1)

• Preserve backward compatibility for renamed serialized field · New

Resolved since last review (5)

• Handle absent-origin tagged null as destination list deletion
• Match installed schema versions exactly
• Pass SWAGGER_VERSION explicitly to schema generation
• Emit valid CEL expression in generated example
• Emit valid CEL expression in generated example

[sonarqubecloud]

Quality Gate failed

Failed conditions
11.2% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud