Cycle between identical products so each is picked once

[guplem]

Summary

Closes #27

When several products of one ingredient are truly identical, the optimizer used to keep recommending the same one. Now it spreads equivalent products one-of-each, and that spread is shown to the user in both the card and the copied list.

• "Equivalent" means every field that drives how a product is bought and consumed matches: items per pack, quantity per item, unit, shelf life (open and closed), and can-be-frozen. The store link is excluded on purpose (two pizza flavors of the same pack size are interchangeable). Price is not a field on Product, so it cannot be part of the key yet; a code comment records this.
• rankProducts distributes the packs one-of-each across equivalent products (e.g. 3 identical products needing 4 packs -> 2,1,1). Total cost and waste are unchanged.
• The card now shows an equivalent group as a combined "buy one of each" (each with its share, joined by "and"), instead of each showing the full solo count as an "or" alternative. Non-equivalent products keep the "or" alternative view with their solo count.
• The copied list shows the same one-of-each split, so three identical pizzas read "1 pack / 1 pack / 1 pack" instead of "3 / 3 / 3".
• Equivalence is defined in one shared place (productEquivalenceKey), used by the optimizer, the card, and the copy.

Note for the reviewer

This "buy some of A and some of B" presentation overlaps with #42 (the mixed-pack combination display). The two are complementary in intent (this one spreads identical products for variety; #42 mixes different pack sizes to cut waste), but they touch the same card and copy code. When both land they should be reconciled into one presentation. Landing order does not matter for correctness; expect a merge conflict in shopping_ingredient.dart / shopping_page.dart / waste_optimizer.dart.

Test plan

• flutter analyze passes
• flutter test test/ passes (640 tests)
• Several identical products: card shows "buy one of each" and the copy lists one-of-each (not the full count each)
• Non-equivalent products keep the "or" alternatives with solo counts
• Owned stock still lowers the grouped counts; owned-field auto-fill uses the true total

🤖 Generated with Claude Code

[guplem]

Reviewed by an automated pass. The change is correct and matches the issue's acceptance criteria; one thing the human reviewer should know before merge.

What is done well

• The equivalence key is well chosen and clearly documented: it groups on every field that changes how a product is bought and consumed (pack shape, both shelf lives, can-be-frozen) and excludes the store link on purpose, so two flavors of the same pack size are cycled. Price is not a Product field, and the comment says to add it to the key if it ever is.
• The distribution is deterministic (stable sort, then round-robin with the remainder to earlier products) and leaves total cost and waste unchanged. Strong test coverage: one-of-each, remainder split (2,1,1), single-unit no-op, link-only variants cycled, and non-equivalent products (different size / different shelf life) kept on waste ranking.

Key point for the reviewer (Suggestion, not blocking)

• The cycle is applied to the recommendation object, which is exactly what the issue's acceptance criteria ask for. But the on-screen "Buy N" count and the copied list do not read ProductRecommendation.packsNeeded; they recompute packs per product via product.packsNeeded(...) (shopping_ingredient.dart:194-197, shopping_product_row.dart:181). So the cycled distribution is not yet visible to the user. Making it visible means reworking the "or"-alternatives display and the multi-trip copy path (ADR 0014 area), a larger change kept out of this issue's scope. Good candidate for a follow-up issue.
• Minor side effect: the owned-field pack auto-fill uses the top recommendation's packsNeeded (shopping_ingredient.dart:230), which is now the cycled (smaller) share. Low impact, worth a glance.

Verdict: approved pending human review. CI analyze-and-test gate must be green before merge.

[guplem]

Re-review after surfacing the cycle in the UI and copy (the earlier "key point for the reviewer"). The cycle is now visible to the user, and a regression found during this pass was fixed on the branch. Ready for a human check.

What changed since the first review

• The one-of-each cycle now shows in both places: the card presents equivalent products as a combined "buy one of each" (joined by "and") using each product's cycled share, and the copied list lists one-of-each instead of the full solo count for every equivalent product. Non-equivalent products keep the "or" alternatives with their solo counts.
• Equivalence is now defined once (productEquivalenceKey) and reused by the optimizer, the card, and the copy. The round-robin split is a shared distributeEquivalentPacks helper (verified: sums to the total, remainder to earliest, no negatives).

Found and fixed on this branch

• (was Required) The owned-field auto-fill over-counted when an equivalent group needed only 1 pack total: the cycle skipped the 1-pack case, leaving each member at 1, so auto-fill summed to the group size (2) instead of 1. Fixed by always distributing (1 pack across 2 equivalents -> [1, 0]), so the shares sum to the true total. Also stopped the card rendering a stray "... and Covered" row for a zero-share variant (now matches the copy, which drops it). New tests cover both, driven through rankProducts. Full suite green (640 tests).

Verified correct: grouping is order-independent, owned stock still lowers grouped counts, non-equivalent products unchanged, distribution math sound.

Known minor (not fixed, immaterial): in multi-trip mode the card distributes the whole-menu total while the copy distributes per trip, so the extra pack can land on a different equivalent variant. Same total; since equivalent products are interchangeable by definition, which one gets the extra does not matter.

Verdict: approved pending human review. CI analyze-and-test gate must be green before merge. Note: overlaps with #42 (mixed-pack display) - reconcile when both land.

[guplem]

Rebased onto the updated main (which now has #34, #29, #28) and reconciled. CI is green and the PR is mergeable.

Reconciliation (verified)

• rankProducts now composes both features in sequence: #29's per-product under-buy reduction runs first (keeping full-buy waste for fair ranking), then #27's _cycleEquivalentProducts spreads each equivalence group's (already-reduced) total one-of-each. Equivalent products get identical reductions, so cycling the reduced total is correct. distributeEquivalentPacks/productEquivalenceKey stay the single source of truth.
• Copy: #34's per-trip split (distributeRemainingAcrossTrips + computeRemainingQuantities) runs first, then buildIngredientCopyLines distributes each trip's equivalent products one-of-each. They nest cleanly.
• Card keeps the equivalent-group presentation (#27), the freeze note (#28), and the under-buy chip (#29) together.
• No test expectations changed. Full suite passes together: 665 tests.

Known minor (documented, not fixed): copyWithPacksNeeded (used by cycling) does not carry the underBuy/shortfall fields, so an equivalent group that also qualifies for under-buy loses the under-buy chip on its cycled shares. This is a rare intersection, all tests pass, and forcing the flag onto each cycled share could show a confusing per-share shortfall. Flagging for awareness; can be a follow-up if you want the warning on cycled groups.

Verdict: approved pending human review. CI green and mergeable. Reminder: overlaps with #42 (multi-product card/copy presentation) - reconcile the two displays if you merge both.