Add CLI command for return reasons

[ricardotejedorsanz]

Add Return Reason Management to Product Taxonomy

This PR introduces support for managing return reasons in the product taxonomy, including commands to add return reasons and associate them with product categories.

New Commands

Add Return Reason

bundle exec ./bin/product_taxonomy add_return_reason NAME DESCRIPTION

Creates a new return reason with the specified name and description, generating appropriate identifiers.

1. Creates a new return reason with auto-generated identifiers:
   • id: Next available numeric ID
   • friendly_id: Parameterized from name (e.g., "size-too-small")
   • handle: Kebab-case version (e.g., "size-too-small")
2. Validates uniqueness across all existing return reasons (ID, name, handle, friendly_id)
3. Appends the new return reason to data/return_reasons.yml
4. Triggers automatic updates:
   • Regenerates English localizations
   • Updates distribution files (JSON, TXT)
   • Regenerates documentation

Add Return Reasons to Categories

bundle exec ./bin/product_taxonomy add_return_reasons_to_categories RETURN_REASON_FRIENDLY_IDS CATEGORY_IDS

Associates one or more return reasons with one or more product categories. Supports optional inclusion of descendant categories.

1. Maps specified return reasons to specified categories
2. Optionally cascades to descendant categories with --include-descendants flag
3. Validates that all referenced return reasons exist
4. Auto-sorts return reasons alphabetically with Unknown/Other last
5. Updates category YAML files with new mappings
6. Triggers automatic regeneration of:
   • Distribution files (JSON, TXT)
   • Documentation files

Dump Return Reasons

bundle exec ./bin/product_taxonomy dump_return_reasons

Exports all return reasons to a YAML file for persistence.

1. Loads all return reasons from memory
2. Serializes them to YAML format using the data serializer
3. Overwrites data/return_reasons.yml with the current state
4. Preserves the structure: id, name, handle, friendly_id, description

Features

• Return Reason Creation: Creates return reasons with auto-generated IDs, friendly IDs, and handles
• Category Association: Links return reasons to appropriate product categories
• Hierarchical Support: Option to apply return reasons to all descendant categories
• Intelligent Sorting: Maintains alphabetical order with special reasons ("unknown", "other") at the end
• Validation: Prevents duplicate return reasons and ensures data integrity
• Data Persistence: Automatically updates YAML files and localizations

Implementation Details

• Follows existing taxonomy command patterns for consistency
• Includes comprehensive test coverage for all new commands
• Maintains proper sorting of return reasons within categories
• Handles whitespace in comma-separated input lists
• Updates all affected data files automatically

The PR provides a complete solution for managing product return reasons through the CLI, enabling teams to maintain this taxonomy data programmatically.

[ricardotejedorsanz]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• Add CLI command for return reasons #791 : 2 dependent PRs (#794 , #802 ) 👈 (View in Graphite)
• Extend localization sync command to support return reasons #795
• Implement return reasons model and distribution pipeline #790 : 1 other dependent PR (#792 )
• Add return reasons data and category mappings #789
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Hetul-Patel-2]

Do we want to separate the create return reasons and dump commands?

Current workflow is that running the create and attach commands will create the return reasons object and will modify the yaml directly. Do we want to separate it so that one command will create it, one command will dump it?

If this follows the existing workflow with categories where creating a category will automatically add it to the yaml then we can discard this feedback.

[Hetul-Patel-2]

Since this attaches the objects and also writes to the yaml, do we want some sort of rollback or atomic transaction where if it fails to write the yaml then it also detaches it from the object?

Attaches the two objects -> writes to yaml
Attaches the two objects -> error writing to yaml -> rollback attaching the objects and signal that command failed

It could also be the case that these operations are something we can confidently say will work and not need to implement this rollback logic.