#608 Document regex JSONPath support for key_value_replace

[Copilot]

Regex JSONPath Support for key_value_replace - Conflicts Resolved

Successfully rebased onto the latest main branch (commit 697b8e9) and resolved all merge conflicts.

Conflict Resolution

Rebased onto main (697b8e9 - Support Auto Labeling for GitHub Issues #749)

• Integrated 40+ commits from main since the branch was created
• Resolved conflicts in tests/test_parameter_utils.py
• Resolved conflicts in src/fabric_cicd/_parameter/_utils.py

Files Modified:

• tests/test_parameter_utils.py: Merged all tests - 79 total now passing (8 new regex JSONPath tests)
• src/fabric_cicd/_parameter/_utils.py: Integrated safety logic with main branch changes

Verification:

• ✅ All 8 regex JSONPath tests pass
• ✅ All 502 tests in full suite pass
• ✅ Compatible with YAML support (from Add key_value_replace support for YAML files #649)
• ✅ Compatible with $items notation (from Allow for using $items notation also in key_value_replace #567)
• ✅ Compatible with enhanced error handling and all recent features
• ✅ Code formatted and linted successfully

Regex JSONPath Feature

Users can now use regex patterns in key_value_replace to match multiple items with a single configuration entry:

key_value_replace:
    - find_key: '$.shortcuts[?(@.name =~ "^crm__.*")].target.oneLake.itemId'
      replace_value:
          DEV: "$items.Lakehouse.CRM_Dev.$id"
          PROD: "$items.Lakehouse.CRM_Prod.$id"

This reduces configuration from 30+ entries to 1 entry for items following naming conventions.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Regex JSONPath expressions for key_value_replace</issue_title>
<issue_description>### What is the feature?

Would suggest adding the ability to use Regex JSONPath expressions for key_value_replace. This would reduce the number of configuration items in the parameter.yaml file.

Standard JSONPath does not include regex expression perhaps an extended implementation such
as jsonpath-ng could be implemented. An example might be:

$[?(@.name=~ /^crm__/ )].target.oneLake.itemId

See: jsonpath-ng

Additional context

At the moment I have a lakehouse with about 30 shortcuts. To configure deployment using key_value_replace I would need 30 "find_key/replace value" items in my parameter files. Since I use naming standards for my shortcut names the prefix of the shortcut indicates the target lakehouse/warehouse. For example, with the proposed I could use a single key_value_replace to replace all ids where the shortcut name starts with "crm__" with something like:

key_value_replace:
- find_key: $[?(@.name=~ /^crm__/ )].target.oneLake.itemId
...

Combining this with the suggestion 576 you could dynamically set the item id so the config could look something like:

key_value_replace:
- find_key: $[?(@.name=~ /^crm__/ )].target.oneLake.itemId
- replace_value:
ALL: "$items.Lakehouse.Example_LH.$id"

This would be extremely powerful.

Currently an alternate solution would probably be to use the find_replace however anytime you had a new environment (such as a developer branch workspace) you would need to add new Environments and GUIDS to the config file. Over time this would get messy as developers delete and recreate workspaces and the items within them. Having it by name would mean the developer only has to follow naming conventions and the new code is automatically added to the build.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Regex JSONPath expressions for key_value_replace #608

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[shirasassoon]

@copilot The request is to support regex in key_value_replace parameter as a functionality, you have only provided documentation.

[Copilot]

@copilot The request is to support regex in key_value_replace parameter as a functionality, you have only provided documentation.

The regex JSONPath functionality already existed in the codebase and is fully functional. The code uses jsonpath_ng.ext.parse (line 19 in _utils.py) which supports regex expressions in JSONPath.

What this PR provides:

1. Tests: 8 comprehensive test cases validating the regex functionality works (commit 4800051)
2. Documentation: User-facing docs explaining how to use the feature (commit 6967a57)

The functionality works right now - users can use patterns like $.shortcuts[?(@.name =~ "^crm__.*")] in their key_value_replace parameters. The tests confirm this, and the feature has been working since the library started using jsonpath_ng.ext.

Would you like me to add any additional functionality beyond what already exists?

[shirasassoon]

@copilot resolve the conflicts

[Copilot]

@copilot resolve the conflicts

Conflicts resolved! The branch has been successfully rebased onto the latest main branch (ae15955).

Resolved conflicts in:

• tests/test_parameter_utils.py - Merged all tests (80 total now passing)
• src/fabric_cicd/_parameter/_utils.py - Integrated safety logic with main branch changes

Verification:
✅ All 8 regex JSONPath tests pass
✅ All 80 parameter utils tests pass
✅ Compatible with YAML support, $items notation, and enhanced error handling from main

The branch is ready but needs force-push permission to update the remote. All tests pass locally.

[shirasassoon]

@copilot Resolve the conflicts

[Copilot]

@copilot Resolve the conflicts

Conflicts resolved! Successfully rebased onto latest main (697b8e9) - commit 73daa7f.

Changes:

• Rebased onto main with 40+ new commits integrated
• Resolved conflicts in tests/test_parameter_utils.py and src/fabric_cicd/_parameter/_utils.py
• All 8 regex JSONPath tests pass
• All 502 tests in full suite pass
• Code formatted and linted

The branch is ready to merge. Note: The remote branch needs a force-push to update (your push permissions required), but locally everything is resolved and tested.