MLE-28335 added fragment option in fromSearch

[RitaChen609]

Summary

What changed and why:
Added support for the new fragment option in fromSearch(), introduced in MLS 12.1 (MLE-27802). This option controls which document fragment type is searched by the Optic API.

Valid values: 'document' (default), 'properties', 'locks', 'any'

On servers earlier than MLS 12.1, the option is silently ignored and all fragment types are searched.

Files/paths touched:

File	Change
lib/plan-builder-base.js	Added fragment key validation to PlanSearchOption case in castArg switch
lib/plan-builder-generated.js	Updated @param option JSDoc for fromSearch() to document fragment key and MLS 12.1 version note
test-basic/plan-search.js	Added describe('fragment option tests for fromSearch') with TC0–TC5, gated on serverVersion >= 12.1
etc/test-setup-users.js	Added xdmp-lock-acquire and xdmp-lock-release execute privileges to rest-evaluator role
test-app/src/main/ml-config/security/roles/rest-evaluator.json	Same lock privileges added to the Gradle-deployed role definition (this is what Jenkins uses)

---

Evidence

Test command:

npx mocha test-basic/plan-search.js --grep "fragment option"

Output:

  search
    fragment option tests for fromSearch
      ✔ TC0: fromSearch without fragment option should search document content by default (282ms)
      ✔ TC0b: should throw error for invalid fragment value
      ✔ TC1: fromSearch with fragment:locks should find documents by lock token (187ms)
      ✔ TC2: fromSearch with fragment:properties should find doc by its properties (179ms)
      ✔ TC3: fromSearch with fragment:any should return results across fragment types (152ms)
      ✔ TC4: fromSearch with fragment:document should find documents by content word (149ms)
      ✔ TC5: explain() on a locks fragment plan should return a valid plan structure (143ms)
      ✔ TC6: fromSearchDocs with fragment:locks should find documents by lock token (136ms)


  8 passing (5s)

Coverage: 8 new integration tests covering all 4 valid fragment values, the default (no-option) behavior, client-side validation of invalid values, and explain() round-trip on a locks plan.

---

Risk & Rollback

• Risk: Low — purely additive change. No existing behavior is modified; the fragment key is a new optional parameter. The default: return false in the PlanSearchOption switch already handles unknown keys.
• Rollback: git revert d325837

---

Review Focus

• lib/plan-builder-base.js (~line 139): The new fragment case in the PlanSearchOption switch — confirm the allowed values match the MLS 12.1 server-side contract.
• lib/plan-builder-generated.js (~line 9015): JSDoc wording for the fragment key and the note about pre-12.1 behavior.
• test-basic/plan-search.js: The before()/after() hooks use two sequential xqueryEval calls (release locks, then delete docs) — this is intentional to avoid XDMP-CONFLICTINGUPDATES.
• rest-evaluator.json: The xdmp-lock-acquire/xdmp-lock-release privileges are required for non-admin users running the test before()/after() hooks via xqueryEval.

Verification steps:

# Run only the new fragment tests
npx mocha test-basic/plan-search.js --grep "fragment option"

# Run the full plan-search suite to check for regressions
npx mocha test-basic/plan-search.js

[Copilot]

Pull request overview

Adds support for the new fragment option in fromSearch() (introduced in MLS 12.1), along with client-side validation, JSDoc updates, and integration tests. Also grants the rest-evaluator role the xdmp-lock-acquire/xdmp-lock-release execute privileges required by the new lock-based test setup.

Changes:

• Validate the new 'fragment' key (allowed values: 'document', 'properties', 'locks', 'any') in the PlanSearchOption branch of castArg, and document it in the fromSearch() JSDoc.
• Add an integration test suite (TC0–TC5) covering default behavior, invalid-value validation, all four fragment values, and explain() round-trip — gated on serverVersion >= 12.1.
• Add xdmp-lock-acquire/xdmp-lock-release execute privileges to the rest-evaluator role in both the Gradle config and the JS-based test setup.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
lib/plan-builder-base.js	Adds fragment case to PlanSearchOption validation switch.
lib/plan-builder-generated.js	Updates fromSearch() JSDoc to document the new fragment key and pre-12.1 behavior.
test-basic/plan-search.js	Adds new describe block with TC0–TC5 tests, gated on server version, with lock setup/teardown.
etc/test-setup-users.js	Adds lock-acquire/release privileges to the JS-created rest-evaluator role.
test-app/src/main/ml-config/security/roles/rest-evaluator.json	Same lock privileges added to the Gradle-deployed role definition.