[JOY (JOY)]

Closes #1149

Task 3 of the Item / variant / listing model (#1129, design doc Docs/Proposals/2026-10-27-item-variant-listing-model.md, sections 4 and 10). Pure library code; nothing consumes it yet.

What changes

packages/shared-data:

• rules/model-key.ts (zod-free, exported from the root entry and from @repo/shared-data/rules):
  • splitModelKey(modelKey) returns { itemKey, variantKey }, or null when the key is not in the brand:model:variant shape.
  • composeModelKey(itemKey, variantKey) builds item_key:variant_key and throws a RangeError on an invalid part or a key over 200 characters.
  • isItemKey, isVariantKey, isModelKey, isSizedVariantKey (^\d+(gb|tb)$, the multi-size rule of 4.2 / 7.2), UNKNOWN_VARIANT_KEY, and the *_PATTERN regexes.
  • The segment shapes are the design doc's inventory regex (7.3), with _ allowed. variant_key is the literal third segment (256gb, 1024gb, standard, unknown, and later 256gb-cellular). Apple screen and case sizes stay in the Item key (apple:ipad-pro-m5-11).
• schemas/item.schema.ts:
  • ItemSchema: a rate.items row per the 4.3 DDL. Like the table, item_key has no shape check, because legacy keys still get an Item.
  • VariantSchema: MasterProductSchema plus nullable item_id, variant_key and sort_order. It refines that variant_key equals the model_key's third segment when the key is well formed.
  • VariantSourceSchema: the products.variant_source values.
  • Strict ItemKeySchema, VariantKeySchema and ModelKeySchema.

Tests

pnpm --filter @repo/shared-data test adds a new 8/8 step:

• Every three-part key literal in apps/importer/src/shopee/__tests__ (155 today, read at test time) round-trips through split and compose. This covers Apple size-keyed lines, :unknown, earbuds, Garmin and Apple watches, and 1024gb.
• The fixture scan is wider than the key shape (upper case, _), so a fixture key the helpers would reject fails the test instead of being skipped.
• The suite also covers malformed keys and the schema defaults and refinements.

Also checked locally: @repo/crawlers build, test:dist, and @repo/web typecheck.

Review

• A fresh-context subagent review and a Codex adversarial pass found no P0.
• Fixed in round 1: the legacy variant_key note, the test comments, and the fixture scan's strictness.
• Decided by the PO (round 1): the doc's key regex rejected _, yet slugify in the normalizer keeps it, as in asus:vivobook-x1504_va:512gb (Codex rated this P1).
  • The key shape now allows _ in all three segments.
  • Empty segments (samsung::unknown, from a title with no model) stay rejected. The normalizer side is tracked on importer: item-first matcher (match_item), item_key/variant_key, nullable variant behind a flag #1151.
  • The design doc's 7.3 inventory regex is updated to match the helpers.

🤖 Generated with Claude Code

---

📌 TL;DR

Introduces a new Item/Variant data model with strict model_key parsing/composition utilities and Zod schemas to enforce the brand:model:variant structure, ensuring data integrity across the shared data package.

🎯 Type of Change

• 🚀 New feature
• 🐛 Bugfix
• 🧹 Refactor
• ⚡ Performance
• 📚 Documentation
• ⚙️ CI / Configuration

🔍 Changes Walkthrough

File	Summary of Changes
packages/shared-data/src/rules/model-key.ts	New file. Defines regex patterns and utility functions (splitModelKey, composeModelKey, isItemKey, etc.) to parse and validate the brand:model:variant key structure. Enforces length limits and segment shapes.
packages/shared-data/src/schemas/item.schema.ts	New file. Defines Zod schemas for Item, Variant, and key types. Includes a superRefine check on VariantSchema to ensure variant_key matches the third segment of model_key.
packages/shared-data/src/rules/index.ts	Re-exports the new model-key utilities to make them available via the @repo/shared-data/rules entry point.
packages/shared-data/src/schemas/index.ts	Re-exports the new item.schema to make Item/Variant schemas available via the main package entry.
packages/shared-data/src/index.ts	Re-exports model-key rules from the root entry point.
packages/shared-data/src/__tests__/shared-data.test.ts	Adds comprehensive tests for key parsing/composition round-trips, edge cases (invalid keys, legacy keys), and schema validation (Item/Variant defaults, constraints, and consistency checks).

📊 Architectural Flow

flowchart TD
    subgraph "Input"
        A[Raw model_key string]
    end

    subgraph "Rules: model-key.ts"
        B{isModelKey?}
        C[splitModelKey]
        D[composeModelKey]
        E[isItemKey / isVariantKey]
    end

    subgraph "Schemas: item.schema.ts"
        F[ItemSchema]
        G[VariantSchema]
        H[superRefine: Check variant_key consistency]
    end

    A --> B
    B -->|Valid| C
    B -->|Invalid| I[Return null]
    
    C --> J[ModelKeyParts: itemKey, variantKey]
    
    K[itemKey] --> E
    L[variantKey] --> E
    E -->|Valid| D
    D --> M[Composed model_key]
    
    N[Item Data] --> F
    O[Variant Data] --> G
    G --> H
    H -->|Uses splitModelKey| C
    H -->|Pass| P[Valid Variant]
    H -->|Fail| Q[Validation Error]

Loading

[claude]

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
rate	Ready	Preview	Oct 27, 2026 5:36pm UTC

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 20 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: e075780a-e459-4b9d-94e6-3e0c138a0380

Commits

Reviewing files that changed from the base of the PR and between 645c155 and 3eb34cc.

Files selected for processing: 7

• Docs/Proposals/2026-10-27-item-variant-listing-model.md
• packages/shared-data/src/__tests__/shared-data.test.ts
• packages/shared-data/src/index.ts
• packages/shared-data/src/rules/index.ts
• packages/shared-data/src/rules/model-key.ts
• packages/shared-data/src/schemas/index.ts
• packages/shared-data/src/schemas/item.schema.ts

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[dos]

⏱️ Code Review completed (7 eligible files · 22,220 chars · 1 model call(s) · 1 PR unit(s))

Whole diff with bounded context at base 645c155 / head 3eb34cc.

✅ CLEAN_PASS: Complete diff reviewed