WA-DOC-027: Add any_of Mongoid 8 migration pattern doc

[kitcommerce]

Fixes #1129

Adds docs/rails7-migration-patterns/mongoid8-any-of-semantics.md documenting the Mongoid 7→8 any_of API change and fix patterns, based on the implementation in PR #1091.

Client impact

None (documentation only).

Verification Plan

Read the doc for clarity. Verify README index updated.

[kitcommerce]

Rails Conventions Review

Verdict: APPROVED ✅

Documentation-only PR — no Ruby code changes to evaluate for Rails conventions compliance.

Doc Quality Assessment

Content accuracy: Both breaking patterns are correctly identified and documented:

• Pattern 1 (array-as-single-arg): fix via splat is correct and backwards-compatible with Mongoid 7
• Pattern 2 (loop-based chaining): collect-then-splat refactor correctly explains the $and[$or,$or] narrowing behavior in Mongoid 8

Code examples: Ruby syntax is idiomatic. Before/after examples are clear. Real file paths from PR #1091 are cited, which is helpful for traceability.

Structure: Follows the established format of other docs in docs/rails7-migration-patterns/. README index entry is consistent with neighboring entries.

Minor note (non-blocking): The relative link ../mongoid-8-embedded-document-migration.md in the Related Docs section should be verified to exist in the repo. If that file does not yet exist, consider noting it as a planned doc or removing the link to avoid broken references.

No Rails convention violations. Approving.

[kitcommerce]

Architecture Review

Verdict: APPROVED

This is a documentation-only PR with no code changes, so architecture concerns are minimal. The doc itself is well-structured and architecturally sound:

Strengths:

• Correctly identifies both breaking patterns (array-as-arg and loop-chaining) with clear before/after examples
• The section structure (Background → Patterns → Detection → Quick Reference → Audit Checklist) follows a logical progression for migration docs
• Detection commands are practical and actionable for downstream implementors
• The 'No Intentional Behavior Differences' section explicitly calls out that fixes should be semantically equivalent — good guardrail against accidental logic changes during migration
• Related Docs section ties back to PR WA-VERIFY-091: Audit and fix Mongoid 8 any_of scoping semantics #1091 implementation, maintaining traceability

No architectural concerns identified. Documentation accurately reflects the Mongoid 8 API change and provides safe, equivalent migration patterns.

[kitcommerce]

Simplicity Review

Verdict: APPROVE ✅

Summary

Clean, focused docs-only PR. No simplicity concerns.

What I checked

• Structure: Logical flow — Background → two numbered patterns → Detection → Quick Ref table → Checklist → Caveats → Related Docs. Easy to navigate.
• Pattern 1 (Array as single arg): Before/after Ruby examples are concise and correct. Risk level (low–medium) is appropriately communicated.
• Pattern 2 (Loop-based chaining): Before/after examples clearly illustrate the narrowing problem. High-risk label is warranted. The flat_map fix is idiomatic.
• Detection commands: Both rg and grep variants provided. Post-match instructions (check for array var, check for loop) are actionable.
• Quick Reference table: Two-column symptom→fix format is useful for a developer triaging issues.
• Audit Checklist: OK / Low / High classification is practical and non-redundant with the Quick Ref.
• 'No Intentional Behavior Differences' section: Important clarification — makes clear these are semantics-preserving fixes, not query logic changes.
• Related Docs link: ../mongoid-8-embedded-document-migration.md resolves correctly to docs/mongoid-8-embedded-document-migration.md, which exists on the branch. ✅
• README index entry: One bullet, descriptive parenthetical, consistent style with existing entries.

Findings

None.

---

Reviewed by simplicity agent · wave 1

[kitcommerce]

Security Review

Verdict: APPROVED

This is a documentation-only PR adding a Mongoid 8 any_of migration guide. No Ruby code, no configuration, no executable content.

Security assessment:

• No code changes to review
• Markdown content is factually accurate and describes known Mongoid 7→8 breaking changes
• Code examples in the doc are correct and safe (standard Ruby/Mongoid query patterns)
• No sensitive data, credentials, or security-relevant implementation details exposed
• Detection commands (rg, grep) are standard read-only shell utilities

Finding count: 0

No security concerns. Safe to merge.

[kitcommerce]

Rails Security Review

Verdict: PASS

Findings

No security findings. This PR adds a documentation file (mongoid8-any-of-semantics.md) and a README index entry — no Ruby source, no controller/model/view changes, no parameter handling, no query logic.

Notes

• The documented patterns (array-as-single-arg, loop-based chaining) are themselves relevant to data integrity — silent empty result sets from incorrect any_of usage could mask authorization-scoped queries in downstream apps. The documentation correctly flags these risks and provides safe fix patterns.
• No secrets, credentials, or sensitive data in the new file.

No action required.

[kitcommerce]

Database Review

Verdict: PASS

Findings

No schema changes, migrations, or query code modifications in this PR — it is purely documentation.

From a database perspective, the documented patterns are technically accurate:

1. Pattern 1 (array-arg): Correct — Mongoid 8 changed any_of argument handling; splatting the array is the right fix and produces identical $or queries.
2. Pattern 2 (loop-chaining): Correct — Mongoid 8 preserves each .any_of call as a distinct $and[$or, $or, …] instead of merging into a single $or. The collect-then-splat approach correctly restores the intended widening semantics.
3. Detection commands are appropriate for finding affected call sites.
4. Quick reference table correctly maps symptoms to root causes.

No concerns about data integrity, index coverage, or query performance implications of the documented fixes — the splat-based patterns produce the same MongoDB $or operators that Mongoid 7 generated.

Recommendations

None — clean documentation that will help downstream teams audit their any_of usage safely.

[kitcommerce]

Test Quality Review

Verdict: PASS

Findings

This PR is documentation-only — two new markdown files with no Ruby code changes, no migrations, and no logic modifications.

• No executable code was added or changed, so test coverage requirements do not apply.
• The documented patterns reference real production fixes from PR WA-VERIFY-091: Audit and fix Mongoid 8 any_of scoping semantics #1091, which presumably carried its own test changes at the time.
• Detection commands provided (ripgrep/grep) are shell utilities, not application logic — not testable in the test suite.
• The fix examples are illustrative snippets, not production code paths being introduced here.

Recommendations

• No test changes are required or expected for this PR.
• If future work converts these patterns into a Rubocop custom cop or lint task, that work should carry unit tests at that time.
• Consider adding a brief note in the doc pointing to the test changes from PR WA-VERIFY-091: Audit and fix Mongoid 8 any_of scoping semantics #1091 (if any) so readers can see a tested example of the fix in context.

---

Reviewed by: test-quality (automated)

[kitcommerce]

Wave 3 Quality Review

Verdict: PASS

Reviewed the pending quality lanes for this PR:

• Performance: docs-only change; no executable code, query path, or build/runtime behavior added. The guidance itself correctly distinguishes the high-risk loop-chaining case from the lower-risk array-arg case.
• Frontend: no storefront/admin UI, CSS, JS, or rendered template changes. README index entry and new migration doc are consistent with the existing docs structure.
• Accessibility: no interactive UI changes or semantic markup changes affecting app accessibility. The markdown content is clear, structured, and link targets referenced in the doc are valid for this branch/PR context.

No material issues found in these lanes. Marking wave-3 quality review as passed.