Port upstream Arazzo operation resolution fixes

[axewilledge]

Bring over wso2/vscode-extensions#2229 so the runner resolves sourceDescription-qualified operationPath and operationId values in this standalone repo.

Purpose

Describe the problems, issues, or needs driving this feature/fix and include links to related issues in the following format: Resolves issue1, issue2, etc.

Goals

Describe the solutions that this feature/fix will introduce to resolve the problems described above

Approach

Describe how you are implementing the solutions. Include an animated GIF or screenshot if the change affects the UI (email documentation@wso2.com to review all UI text). Include a link to a Markdown file or Google doc if the feature write-up is too long to paste here.

User stories

Summary of user stories addressed by this change>

Release note

Brief description of the new feature or bug fix as it will appear in the release notes

Documentation

Link(s) to product documentation that addresses the changes of this PR. If no doc impact, enter �N/A� plus brief explanation of why there�s no doc impact

Training

Link to the PR for changes to the training content in https://github.com/wso2/WSO2-Training, if applicable

Certification

Type �Sent� when you have provided new/updated certification questions, plus four answers for each question (correct answer highlighted in bold), based on this change. Certification questions/answers should be sent to certification@wso2.com and NOT pasted in this PR. If there is no impact on certification exams, type �N/A� and explain why.

Marketing

Link to drafts of marketing content that will describe and promote this feature, including product page changes, technical articles, blog posts, videos, etc., if applicable

Automation tests

• Unit tests

  Code coverage information

• Integration tests

  Details about the test cases and coverage

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? yes/no
• Ran FindSecurityBugs plugin and verified report? yes/no
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes/no

Samples

Provide high-level details about the samples related to this feature

Related PRs

List any other related PRs

Migrations (if applicable)

Describe migration steps and platforms on which migration has been tested

Test environment

List all JDK versions, operating systems, databases, and browser/versions on which this feature/fix was tested

Learning

Describe the research phase and any blog posts, patterns, libraries, or add-ons you used to solve the problem.

[coderabbitai]

📝 Walkthrough

Summary

Ports upstream changes to add support for sourceDescription-qualified operation resolution in the Arazzo runner. The primary changes enable the runner to resolve both operationPath and operationId values that reference specific sources using expressions like $sourceDescriptions.NAME.operationId.

Key Changes

Runner Core

• Enhanced OperationFinder to handle qualified operationId expressions in the format $sourceDescriptions.NAME.operationId, introducing a new exported method FindByIDInSource to search for operations within a specific named source
• Improved JSON-pointer-based operation lookup (FindByPath) to normalize sourceURL expressions, resolving them to bare source names for matching
• Extended parseOperationPointer with "path-only" resolution strategy to select the first available HTTP method when the pointer references a path item without a specific method
• Updated step_executor.go to parse and resolve qualified-format operation IDs, falling back to direct lookup for non-qualified values
• Simplified operationPath handling by delegating {} stripping and source resolution to FindByPath

Examples & Documentation

• Added 16-operation-path-advanced.arazzo.yaml demonstrating parameterized path item pointers with expression-based path resolution
• Added 17-qualified-operation-id.arazzo.yaml showcasing qualified operationId references across multiple workflow steps
• Expanded Explanation.md with detailed MCP Server Runner orchestration sequence, VS Code Tasks implementation, and process lifecycle documentation
• Added handover.md documenting project architecture, observability via OpenTelemetry, and REST endpoint implementation for workflow execution
• Added readme(project).md with development setup guidance, build workflow, and configuration instructions

Walkthrough

This PR enhances operation resolution in the Arazzo Go Runner by introducing qualified operationId expressions (scoped to specific source descriptions) and improving path-based operation discovery. The core changes in operation_finder.go add helpers to parse and resolve $sourceDescriptions.NAME.operationId patterns, normalize sourceURL expressions in path lookups, and implement path-only resolution for JSON pointers that reference paths without specific HTTP methods. The step_executor.go changes integrate these new patterns by delegating qualified operationId and operationPath lookups appropriately. Two new example workflows demonstrate these capabilities in practice. Supporting documentation expands coverage of MCP server orchestration, process lifecycle, and local development setup.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides a brief summary of the change but does not complete the required template sections. Only the opening sentence is filled in; all template sections (Purpose, Goals, Approach, User stories, Release note, Documentation, Training, Certification, Marketing, Automation tests, Security checks, Samples, Related PRs, Migrations, Test environment, Learning) remain as placeholders.	Complete the required template sections, particularly Purpose (with issue links), Goals, Approach, Release note, and Documentation. At minimum, address security checks, test coverage, and any related upstream PR references.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Port upstream Arazzo operation resolution fixes' accurately describes the main objective of the PR—porting changes from an upstream repository to resolve operation references in the Arazzo runner.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch import-arazzo-workspace-history

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.1)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

extensions/arazzo-visualizer/readme(project).md (1)

1-33: 💤 Low value

Consider polishing the documentation for clarity.

This file contains several typographical errors and informal phrasing that could be cleaned up:

• Line 4: "usefull" → "useful"
• Line 8: "go(0.26 something)" → specify exact version (e.g., "Go 1.21+")
• Line 16: "arazzo-desigenr-cli" → "arazzo-designer-cli"
• Line 16: "neeed" → "needed"
• Line 23: "myfork" → "my fork"
• Line 25: "vscode" → "VS Code"

The technical instructions are clear, but correcting these issues would improve the documentation's professionalism.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@extensions/arazzo-visualizer/readme`(project).md around lines 1 - 33, The
README has typos and informal phrasing under headings like "## Stuff to know"
and "## Starting"; update the text to be professional by fixing the listed typos
(change "usefull" → "useful", "arazzo-desigenr-cli" → "arazzo-designer-cli",
"neeed" → "needed", "myfork" → "my fork", "vscode" → "VS Code"), replace the
vague Go note "go(0.26 something)" with a precise requirement (e.g., "Go
1.21+"), and reword informal sentences for clarity and consistent capitalization
across the document (e.g., polish sentences in the "Starting" and "Future work"
sections and standardize CLI/extension names like "arazzo-designer-cli" and
"arazzo-designer-extension").

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@extensions/arazzo-visualizer/readme`(project).md:
- Around line 1-33: The README has typos and informal phrasing under headings
like "## Stuff to know" and "## Starting"; update the text to be professional by
fixing the listed typos (change "usefull" → "useful", "arazzo-desigenr-cli" →
"arazzo-designer-cli", "neeed" → "needed", "myfork" → "my fork", "vscode" → "VS
Code"), replace the vague Go note "go(0.26 something)" with a precise
requirement (e.g., "Go 1.21+"), and reword informal sentences for clarity and
consistent capitalization across the document (e.g., polish sentences in the
"Starting" and "Future work" sections and standardize CLI/extension names like
"arazzo-designer-cli" and "arazzo-designer-extension").

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4105192c-af0f-46ca-9997-2d8b64de3b5b

📥 Commits

Reviewing files that changed from the base of the PR and between 32b2739 and f0bcc85.

📒 Files selected for processing (7)

• arazzo-designer-cli/internal/runner/executor/operation_finder.go
• arazzo-designer-cli/internal/runner/executor/step_executor.go
• examples/go-runner-test/toolshop/16-operation-path-advanced.arazzo.yaml
• examples/go-runner-test/toolshop/17-qualified-operation-id.arazzo.yaml
• extensions/arazzo-visualizer/Explanation.md
• extensions/arazzo-visualizer/handover.md
• extensions/arazzo-visualizer/readme(project).md