[BRD-883] feature/magento-v2-migration

[tomas862]

task: BRD-883

magento v2 data migration pipeline.

[tomas862]

@claude review

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes the foundation for a Magento V2 data migration pipeline. It introduces a new adapter responsible for converting complex Magento GraphQL product responses into a simplified, standardized V2 data structure. This transformation is crucial for enabling efficient indexing, searching, and filtering of product data by handling various product fields, attributes, pricing, and hierarchical categories, ultimately improving data consistency and usability for downstream systems.

Highlights

• New Magento V2 Adapter: Introduced MagentoAdapterV2 for transforming Magento GraphQL product data into a standardized V2 format, enabling efficient indexing and searching.
• Enhanced Attribute Processing: Implemented detailed attribute processing within the adapter, creating flat feature_{code} fields for searchable attributes and a nested features array for filterable attributes, with special handling for 'manufacturer' as 'brand'.
• GraphQL Query for Features: Extended MagentoProductQuery with a new GraphQL query (getFeaturesQuery) to fetch catalog-level product attribute definitions.
• Comprehensive Test Coverage: Included a comprehensive test suite for the new MagentoAdapterV2 to ensure correct data transformation and robust error handling.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[claude]

Claude finished @tomas862's task in 1m 38s —— View job

---

Code Review: MagentoAdapterV2 + MagentoProductQuery

• Gather context and read changed files
• Review MagentoAdapterV2.php
• Review MagentoAdapterV2Test.php
• Review MagentoProductQuery.php changes
• Post final review

---

Overall this is clean, well-structured code that follows the established V2 adapter pattern (matching PrestaShopAdapterV2). The test coverage is thorough. A few items worth addressing:

---

Issues

1. Empty constructor is unnecessary

src/Adapters/MagentoAdapterV2.php lines 30-32 — PHP provides a default public constructor, so the explicit empty one just adds noise. Same pattern exists in PrestaShopAdapterV2, so if you want consistency keep it, but technically it can be removed.

2. Not using AdapterUtils::buildError()

src/Adapters/MagentoAdapterV2.php lines 74-80 — The error array is constructed inline, but AdapterUtils::buildError() already exists for this exact purpose. The other adapters use it too. This creates a subtle inconsistency: AdapterUtils::buildError() accepts ?string for exception, while the inline version always passes a non-null string. Minor, but worth unifying. Fix this →

3. Non-deterministic tie-breaking in extractDefaultCategory()

src/Adapters/MagentoAdapterV2.php lines 404-416 — When two categories share the same maximum level, the last one wins (no stable ordering). This could produce different categoryDefault values depending on the order Magento returns categories. Worth documenting or adding a deterministic tie-breaker (e.g., sort by path length or id). Fix this →

4. manufacturer attribute is silently excluded from filterable features

src/Adapters/MagentoAdapterV2.php lines 221-224 — When code === 'manufacturer', the method does continue after extracting the brand. This means even if manufacturer is is_filterable=true, it won't appear in features. This is tested and intentional (good), but it's worth noting in the inline comment that manufacturer is excluded from both flat fields AND features regardless of its flags. The current comment only says "Brand extraction from manufacturer."

---

Test Coverage Gaps

5. No test for items value being non-array

src/Adapters/MagentoAdapterV2.php lines 60-62 validates that items must be an array and throws ValidationException. This branch is not covered in MagentoAdapterV2Test.php.

6. No test for stock priority (is_in_stock vs stock_status)

When both is_in_stock and stock_status are present, is_in_stock wins (lines 317-319). A test with both fields present (e.g., is_in_stock=false, stock_status='IN_STOCK') would confirm the priority logic. Fix this →

7. No test for image fallback to small_image

extractImageUrl() has three fallback levels: image_optimized → image.url → small_image.url. The third level (small_image) is not tested.

8. No test for ValidationException on missing image

src/Adapters/MagentoAdapterV2.php line 300 throws when no image URL can be extracted. There is no test verifying this behavior.

---

MagentoProductQuery.php changes

The getFeaturesQuery() addition is clean and follows the existing pattern. No issues.

---

Summary

The implementation is solid and the test suite covers the main happy/sad paths well. The items above are mostly minor polish — the non-deterministic extractDefaultCategory() (point 3) and the missing AdapterUtils::buildError() usage (point 2) are the most worth fixing before merge. The test gaps (points 5-8) would improve confidence but are not blockers.

[gemini-code-assist]

Code Review

This pull request introduces a new MagentoAdapterV2 class to transform Magento GraphQL product data into a V2 ValueObject format, handling various product fields, attributes (for search and filtering), pricing, images, and categories. It also adds a new GraphQL query to fetch product attribute definitions. A review comment suggests improving the error handling in the transform method by catching \Throwable instead of the generic \Exception for more comprehensive error logging.

[gemini-code-assist]

Catching the generic \Exception is generally discouraged as it can mask unexpected errors. It's better to catch more specific exceptions, or \Throwable if the intent is to catch all errors (including Error types in PHP 7+). Given that transformProduct can throw ValidationException, and other unexpected issues might arise, catching \Throwable would ensure all potential transformation issues are logged consistently.

            } catch (\Throwable $e) {