The Inevitable Architecture

.changeset/the-inevitable-architecture.md

@@ -0,0 +1,24 @@
+---
+'@effector/model': major
+'@effector-model/core-experimental': major
+'@effector/model-react': major
+---
+
+# The Inevitable Architecture: Trait-Based Composition & Predictable Systems
+
+This major update introduces a paradigm shift in how models are composed and consumed, moving from rigid structures to a flexible, trait-based system.
+
+## Key Changes
+
+- **Trait-Based Model Composition**: Introduced the `model()` API with support for Facets (traits) and Variants (conditional logic).
+- **Deep Reactivity with Lenses**: New `Lens` concept and `select` API for type-safe, deep reactive access to model state.
+- **Predictable System Architecture**:
+  - Hardened development loop with Vitest console interceptors.
+  - Strict ESLint rules to prevent common pitfalls (e.g., passing Lenses to `useUnit`).
+  - Enhanced runtime validation and API guardrails in `useLens` and `select`.
+- **New Experimental Package**: `@effector-model/core-experimental` houses the next-generation model system.
+- **Advanced Features**:
+  - Multi-restaurant support and item grouping in the cart.
+  - Union API for handling heterogeneous product types.
+  - `serialize` utility for model snapshots.
+- **Refactorings**: Updated `@effector/model` and `@effector/model-react` to support the new Lens-based architecture and improved type safety.

.eslintignore

@@ -4,6 +4,7 @@ node_modules
 # Build files
 build
 coverage
+coverage-ts
 typescript
 
 # IDE

.eslintrc.json

@@ -1,6 +1,6 @@
 {
   "root": true,
-  "ignorePatterns": ["**/*"],
+  "ignorePatterns": ["dist", "node_modules"],
   "plugins": ["@nrwl/nx"],
   "overrides": [
     {
@@ -34,6 +34,19 @@
       "files": ["*.js", "*.jsx"],
       "extends": ["plugin:@nrwl/nx/javascript"],
       "rules": {}
+    },
+    {
+      "files": ["apps/**/*.ts", "apps/**/*.tsx"],
+      "extends": ["plugin:react-hooks/recommended"],
+      "rules": {
+        "no-restricted-syntax": [
+          "error",
+          {
+            "selector": "CallExpression[callee.name='useUnit'] > MemberExpression[property.name='facets']",
+            "message": "Do not pass a Facet to useUnit. Use 'useLens' instead."
+          }
+        ]
+      }
     }
   ]
 }

.github/workflows/ci.yml

@@ -15,9 +15,8 @@ jobs:
           cache: 'pnpm'
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint:format
-      # - run: pnpm lint:workspace
       - run: pnpm test
       - run: pnpm test:types
-      # - run: pnpm lint
+      - run: pnpm lint
       - run: pnpm build
-      # - run: pnpm size
+      - run: pnpm size

.gitignore

@@ -4,3 +4,65 @@ node_modules
 *.log
 .nx
 .vscode
+packages/core-experimental/coverage/*
+apps/models-research/src/tree/__tests__/__screenshots__/*
+packages/react/src/__tests__/examples/__screenshots__/*
+coverage/base.css
+coverage/block-navigation.js
+coverage/coverage-final.json
+coverage/favicon.png
+coverage/index.html
+coverage/prettify.css
+coverage/prettify.js
+coverage/sort-arrow-sprite.png
+coverage/sorter.js
+coverage/src/index.css.html
+coverage/src/index.html
+coverage/src/main.tsx.html
+coverage/src/types.ts.html
+coverage/src/vite-env.d.ts.html
+coverage/src/data/index.html
+coverage/src/data/restaurants.ts.html
+coverage/src/data/dodo/cocktails.json.html
+coverage/src/data/dodo/coffee.json.html
+coverage/src/data/dodo/drinks.json.html
+coverage/src/data/dodo/index.html
+coverage/src/data/dodo/pizzas.json.html
+coverage/src/data/dodo/sauces.json.html
+coverage/src/data/dodo/snacks.json.html
+coverage/src/data/kfc/buckets.json.html
+coverage/src/data/kfc/burgers.json.html
+coverage/src/data/kfc/drinks.json.html
+coverage/src/data/kfc/index.html
+coverage/src/data/kfc/sauces.json.html
+coverage/src/data/kfc/snacks.json.html
+coverage/src/data/kfc/twisters.json.html
+coverage/src/models/app.ts.html
+coverage/src/models/cart.ts.html
+coverage/src/models/index.html
+coverage/src/models/traits.ts.html
+coverage/src/models/products/bucket.ts.html
+coverage/src/models/products/burger.ts.html
+coverage/src/models/products/cocktail.ts.html
+coverage/src/models/products/coffee.ts.html
+coverage/src/models/products/drink.ts.html
+coverage/src/models/products/index.html
+coverage/src/models/products/pizza.ts.html
+coverage/src/models/products/sauce.ts.html
+coverage/src/models/products/snack.ts.html
+coverage/src/models/products/twister.ts.html
+coverage/src/view/AppContext.tsx.html
+coverage/src/view/AppView.tsx.html
+coverage/src/view/CartScreen.tsx.html
+coverage/src/view/CheckoutScreen.tsx.html
+coverage/src/view/GlobalCartScreen.tsx.html
+coverage/src/view/hooks.ts.html
+coverage/src/view/index.html
+coverage/src/view/ProductScreen.tsx.html
+coverage/src/view/Restaurant.tsx.html
+coverage/src/view/RestaurantScreen.tsx.html
+coverage/src/view/components/CartItem.tsx.html
+coverage/src/view/components/Common.tsx.html
+coverage/src/view/components/index.html
+coverage/src/view/components/ProductView.tsx.html
+.roomodes

.nvmrc

@@ -1 +1 @@
-20.16
+20

.roomodes

@@ -0,0 +1,122 @@
+customModes:
+  - slug: user-story-creator
+    name: 📝 User Story Creator
+    roleDefinition: |
+      You are an agile requirements specialist focused on creating clear, valuable user stories. Your expertise includes:
+      - Crafting well-structured user stories following the standard format
+      - Breaking down complex requirements into manageable stories
+      - Identifying acceptance criteria and edge cases
+      - Ensuring stories deliver business value
+      - Maintaining consistent story quality and granularity
+    whenToUse: |
+      Use this mode when you need to create user stories, break down requirements into manageable pieces, or define acceptance criteria for features. Perfect for product planning, sprint preparation, requirement gathering, or converting high-level features into actionable development tasks.
+    description: Create structured agile user stories
+    groups:
+      - read
+      - edit
+      - command
+    source: project
+    customInstructions: |
+      Expected User Story Format:
+
+      Title: [Brief descriptive title]
+
+      As a [specific user role/persona],
+      I want to [clear action/goal],
+      So that [tangible benefit/value].
+
+      Acceptance Criteria:
+      1. [Criterion 1]
+      2. [Criterion 2]
+      3. [Criterion 3]
+
+      Story Types to Consider:
+      - Functional Stories (user interactions and features)
+      - Non-functional Stories (performance, security, usability)
+      - Epic Breakdown Stories (smaller, manageable pieces)
+      - Technical Stories (architecture, infrastructure)
+
+      Edge Cases and Considerations:
+      - Error scenarios
+      - Permission levels
+      - Data validation
+      - Performance requirements
+      - Security implications
+  - slug: project-research
+    name: 🔍 Project Research
+    roleDefinition: |
+      You are a detailed-oriented research assistant specializing in examining and understanding codebases. Your primary responsibility is to analyze the file structure, content, and dependencies of a given project to provide comprehensive context relevant to specific user queries.
+    whenToUse: |
+      Use this mode when you need to thoroughly investigate and understand a codebase structure, analyze project architecture, or gather comprehensive context about existing implementations. Ideal for onboarding to new projects, understanding complex codebases, or researching how specific features are implemented across the project.
+    description: Investigate and analyze codebase structure
+    groups:
+      - read
+    source: project
+    customInstructions: |
+      Your role is to deeply investigate and summarize the structure and implementation details of the project codebase. To achieve this effectively, you must:
+
+      1. Start by carefully examining the file structure of the entire project, with a particular emphasis on files located within the "docs" folder. These files typically contain crucial context, architectural explanations, and usage guidelines.
+
+      2. When given a specific query, systematically identify and gather all relevant context from:
+         - Documentation files in the "docs" folder that provide background information, specifications, or architectural insights.
+         - Relevant type definitions and interfaces, explicitly citing their exact location (file path and line number) within the source code.
+         - Implementations directly related to the query, clearly noting their file locations and providing concise yet comprehensive summaries of how they function.
+         - Important dependencies, libraries, or modules involved in the implementation, including their usage context and significance to the query.
+
+      3. Deliver a structured, detailed report that clearly outlines:
+         - An overview of relevant documentation insights.
+         - Specific type definitions and their exact locations.
+         - Relevant implementations, including file paths, functions or methods involved, and a brief explanation of their roles.
+         - Critical dependencies and their roles in relation to the query.
+
+      4. Always cite precise file paths, function names, and line numbers to enhance clarity and ease of navigation.
+
+      5. Organize your findings in logical sections, making it straightforward for the user to understand the project's structure and implementation status relevant to their request.
+
+      6. Ensure your response directly addresses the user's query and helps them fully grasp the relevant aspects of the project's current state.
+
+      These specific instructions supersede any conflicting general instructions you might otherwise follow. Your detailed report should enable effective decision-making and next steps within the overall workflow.
+  - slug: jest-test-engineer
+    name: 🧪 Test Engineer
+    roleDefinition: |-
+      You are a testing specialist with deep expertise in:
+      - Writing and maintaining test suites
+      - Test-driven development (TDD) practices
+      - Mocking and stubbing with testing library
+      - Integration testing strategies
+      - TypeScript testing patterns
+      - Code coverage analysis
+      - Test performance optimization
+
+      Your focus is on maintaining high test quality and coverage across the codebase, working primarily with:
+      - Test files in __tests__ directories
+      - Mock implementations in __mocks__
+      - Test utilities and helpers
+      - Jest configuration and setup
+
+      You ensure tests are:
+      - Well-structured and maintainable
+      - Following @testing-library best practices
+      - Properly typed with TypeScript
+      - Providing meaningful coverage
+      - Using appropriate mocking strategies
+    whenToUse: |
+      Use this mode when you need to write, maintain, or improve Jest tests. Ideal for implementing test-driven development, creating comprehensive test suites, setting up mocks and stubs, analyzing test coverage, or ensuring proper testing practices across the codebase.
+    description: Write and maintain Jest test suites
+    customInstructions: |
+      When writing tests:
+      - Always use describe/it blocks for clear test organization
+      - Include meaningful test descriptions
+      - Use beforeEach/afterEach for proper test isolation
+      - Implement proper error cases
+      - Add JSDoc comments for complex test scenarios
+      - Ensure mocks are properly typed
+      - Verify both positive and negative test cases
+    groups:
+      - read
+      - browser
+      - command
+      - - edit
+        - fileRegex: (__tests__/.*|__mocks__/.*|\.test\.(ts|tsx|js|jsx)$|/test/.*|jest\.config\.(js|ts)$)
+          description: Test files, mocks, and Jest configuration
+    source: project

PLAN_PROJECT_HEALTH_CHECK.md

@@ -0,0 +1,28 @@
+# Project-Wide Health Check & CI Fix Plan
+
+**Objective:** Ensure the entire project passes all GitHub Actions workflows (`.github/workflows`).
+
+## Phase 1: Baseline & Quick Wins
+
+1.  **Formatting:** Run `pnpm lint:format` and `pnpm format` to ensure all files are pretty.
+2.  **Build:** Run `pnpm build` to confirm no compilation errors exist.
+3.  **State Assessment:** Run `pnpm test` and `pnpm test:types` to capture the exact current failure/hang state.
+
+## Phase 2: Resolving Process Hangs (Critical)
+
+1.  **Core Test Hang:** Investigate why `packages/core` tests hang after completion.
+    - _Hypothesis:_ Open handles (timers, intervals, database connections).
+    - _Action:_ Use `--pool=threads` or `--no-threads` to see if isolation helps, or inspect teardown logic.
+2.  **Type Check Hang:** Investigate why `pnpm test:types` hangs on `react` and `core`.
+    - _Hypothesis:_ Circular type references, excessive recursion, or memory limits.
+    - _Action:_ Isolate the problematic file/type by running `tsc` on specific files or bisecting the includes.
+
+## Phase 3: Linting Cleanup
+
+1.  **Bulk Fixes:** Run `pnpm lint --fix` to handle auto-fixable rules.
+2.  **Manual Fixes:** Address remaining errors (e.g., `no-explicit-any`, unused vars).
+    - _Strategy:_ Prioritize fixing errors that break the build. For non-critical style issues that are overwhelming, consider suppressing them temporarily with comments if a proper fix is too large for this scope.
+
+## Phase 4: Final Validation
+
+1.  **Simulation:** Run the full suite of commands (`lint`, `test`, `build`, `typecheck`) locally to verify green status.