feat: new jqPaths ignore differences field for dynamic field selection (#24599)

[puretension]

Summary

This PR fixes issue #24599 where jqPathExpressions in ignoreApplicationDifferences failed when expressions returned multiple values.

Problem

The user's jq expression .metadata.annotations? // {} | keys[] | select ( . | startswith("customprefix.")) returns multiple annotation keys, but ArgoCD wraps it with del() which cannot handle multiple values, causing a runtime error that gets silently ignored.

Solution

• Add detection for multi-value jq expressions (specifically annotation key selections)
• Implement jqMultiPathNormalizerPatch for special handling of expressions that return multiple paths
• For annotation-based expressions, directly evaluate and remove matching keys from the annotations map
• Maintain backward compatibility with existing single-path expressions

---

Checklist:

• Either (a) I've created an enhancement proposal and discussed it with the community, (b) this is a bug fix, or (c) this does not need to be in the release notes.
• The title of the PR states what changed and the related issues number (used for the release note).
• The title of the PR conforms to the Title of the PR
• I've included "Closes [ISSUE #]" or "Fixes [ISSUE #]" in the description to automatically close the associated issue.
• I've updated both the CLI and UI to expose my feature, or I plan to submit a second PR with them.
• Does this PR require documentation updates?
• I've updated documentation as required by this PR.
• I have signed off all my commits as required by DCO
• I have written unit and/or e2e tests for my change. PRs without these are unlikely to be merged.
• My build is green (troubleshooting builds).
• My new feature complies with the feature status guidelines.
• I have added a brief description of why this PR is necessary and/or what this PR solves.
• Optional. My organization is added to USERS.md.
• Optional. For bug fixes, I've indicated what older releases this fix should be cherry-picked into (this may or may not happen depending on risk/complexity).

[bunnyshell]

🔴 Preview Environment stopped on Bunnyshell

See: Environment Details | Pipeline Logs

Available commands (reply to this comment):

• 🔵 /bns:start to start the environment
• 🚀 /bns:deploy to redeploy the environment
• ❌ /bns:delete to remove the environment

[codecov]

Codecov Report

❌ Patch coverage is 59.80392% with 41 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.48%. Comparing base (f4c4c66) to head (7798860).
⚠️ Report is 41 commits behind head on master.

Files with missing lines	Patch %	Lines
util/argo/normalizers/diff_normalizer.go	59.80%	34 Missing and 7 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #24658      +/-   ##
==========================================
+ Coverage   60.46%   60.48%   +0.01%     
==========================================
  Files         350      350              
  Lines       60105    60272     +167     
==========================================
+ Hits        36345    36454     +109     
- Misses      20828    20871      +43     
- Partials     2932     2947      +15     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[crenshaw-dev]

Thanks for the PR! Added a comment suggesting a different direction.

[crenshaw-dev]

I think trying to infer the user's intent from the output of their expression is going to be too error-prone.

Consider this input:

{"a": 1, "b": "a", "c": [["a"]]}

Suppose we decide that, if the user's query evaluates to a string, we're going to treat it as a path.

If the user passes this query:

.b

then we'll receive the value "a", assume it's a path, and delete the "a" key from the input. But that's unintuitive. The user obviously wanted to delete the "b" key.

We could be more strict and say that the user must produce a valid delpaths() input, i.e. a [][]string.

But if the input object actually contains a [][]string, we have no way of knowing whether the user is trying to pass us paths or has directly targeted something they want to delete:

.c

Output:

[["a"]]

Did the user mean to delete the .c from the object, or .a?

tl;dr, I don't think we should reuse the jqPathExpressions field. I think we should create a new jqPaths field. It should be an array of queries that produce jq paths:

each path is an array of strings and numbers

So the solution to the user's problem would be something like:

jqPaths:
- '.metadata?.annotations // {} | [keys | map(select(startswith("a")))]'

Then we should use delpaths() instead of del() to complete the mutation.

[puretension]

@crenshaw-dev Thanks for the sharp analysis!
the examples with .b and .c really highlight how ambiguous and error-prone the current approach would be.
I completely agree with your reasoning. I’ll follow your suggestion and introduce a new jqPaths field (array of jq path queries), and update the implementation to use delpaths() instead of del().

I’ll update the schema, implementation, tests, and docs accordingly. 🙏

[crenshaw-dev]

I also added an item to the next Contributors' meeting to discuss w/ other maintainers. I'm always hesitant to add new features, so I want to make sure everyone feels its worth it.

[puretension]

Thanks for bringing this to the Contributors' meeting!
I've implemented the jqPaths approach you suggested.
Happy to push it for reference during the discussion! we can always adjust based on the team's feedback.

Looking forward to hearing everyone's thoughts! 🙏