@type-crafter/mcp 0.6.0 → 1.0.0

package/src/SPEC_RULES.md

@@ -1,1755 +0,0 @@
-# Type Crafter YAML Specification Rules
-
-Complete guide for writing Type Crafter YAML specifications and understanding TypeScript generation.
-
----
-
-## Table of Contents
-
-- [🚨 Common Mistakes (Read This First)](#-common-mistakes-read-this-first)
-- [Multi-File Specifications](#multi-file-specifications)
-- [Root Structure](#root-structure)
-- [Data Types & Type Mapping](#data-types--type-mapping)
-- [Constraints & Limitations](#constraints--limitations)
-- [Nullable Types (Critical)](#nullable-types-critical)
-- [Type Definitions](#type-definitions)
-- [References](#references)
-- [Composition](#composition)
-- [TypeScript Generation Examples](#typescript-generation-examples)
-- [Best Practices](#best-practices)
-- [Common Patterns](#common-patterns)
-- [Rules Checklist](#rules-checklist)
-
----
-
-## 🚨 Common Mistakes (Read This First)
-
-### ❌ NEVER Do These
-
-```yaml
-# ❌ WRONG: Adding 'nullable: true' property
-User:
-  type: object
-  properties:
-    name:
-      type: string
-      nullable: true  # ❌ INVALID! This property does NOT exist
-
-# ❌ WRONG: Using 'optional: true' property
-User:
-  type: object
-  properties:
-    name:
-      type: string
-      optional: true  # ❌ INVALID! This property does NOT exist
-
-# ❌ WRONG: Using '?' suffix for optional
-User:
-  type: object
-  properties:
-    name?:  # ❌ INVALID! Don't use ? suffix
-      type: string
-
-# ❌ WRONG: Creating top-level array types
-Tags:
-  type: array  # ❌ INVALID! Arrays cannot be top-level types
-  items:
-    type: string
-
-# ❌ WRONG: Using relative paths from current file
-# File: src/api/users.yaml
-User:
-  type: object
-  properties:
-    profile:
-      $ref: './profile.yaml#/Profile'  # ❌ WRONG! Not relative to current file
-
-# ❌ WRONG: Using # reference in non-top file (file without info section)
-# File: docs/cart.yaml (NON-TOP FILE - no info section)
-Cart:
-  SCart:
-    type: object
-    properties:
-      items:
-        type: array
-        items:
-          $ref: '#/Cart/SCartItem'  # ❌ WRONG! Must use full path in non-top files
-
-# ❌ WRONG: Using full path in top file for same-file reference
-# File: types.yaml (TOP FILE - has info section)
-info:
-  version: '1.0.0'
-  title: 'Types'
-types:
-  User:
-    type: object
-    properties:
-      profile:
-        $ref: './types.yaml#/types/Profile'  # ❌ WRONG! Use # in top files for same-file refs
-```
-
-### ✅ CORRECT Ways
-
-```yaml
-# ✅ CORRECT: Use 'required' array to control nullable
-User:
-  type: object
-  required:
-    - id      # id is required (NOT nullable)
-    # name is NOT in required, so it's nullable
-  properties:
-    id:
-      type: string      # Generates: string
-    name:
-      type: string      # Generates: string | null (because not in required)
-
-# ✅ CORRECT: Arrays must be properties within objects
-Post:
-  type: object
-  properties:
-    tags:
-      type: array
-      items:
-        type: string
-
-# ✅ CORRECT: Use paths from project root
-# File: src/api/users.yaml (running type-crafter from project root)
-User:
-  type: object
-  properties:
-    profile:
-      $ref: './src/api/profile.yaml#/Profile'  # ✅ From project root
-
-# ✅ CORRECT: Top file using # for same-file references
-# File: types.yaml (TOP FILE - has info section)
-info:
-  version: '1.0.0'
-  title: 'API Types'
-types:
-  User:
-    type: object
-    properties:
-      profile:
-        $ref: '#/types/Profile'  # ✅ Use # in top files for same-file refs
-  Profile:
-    type: object
-    properties:
-      bio: { type: string }
-
-# ✅ CORRECT: Non-top file using full path for all references
-# File: docs/cart.yaml (NON-TOP FILE - no info section)
-Cart:
-  SCart:
-    type: object
-    properties:
-      items:
-        type: array
-        items:
-          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ Full path in non-top files
-  SCartItem:
-    type: object
-    properties:
-      id: { type: number }
-```
-
-### 🔑 Key Rules to Remember
-
-1. **Nullable is controlled by `required` array ONLY**
-   - In `required` → generates `Type`
-   - NOT in `required` → generates `Type | null`
-   - No properties like `nullable`, `optional`, `?` exist
-
-2. **Arrays cannot be top-level types**
-   - Arrays MUST be properties within objects
-   - Use `type: array` with `items` specification
-
-3. **File paths are from project root**
-   - NOT relative to current YAML file
-   - Always use `./path/from/root/file.yaml#/Type`
-
-4. **Referencing depends on file type**
-   - **Top file** (has `info:` at root): Use `#/types/TypeName` for same-file refs
-   - **Non-top file** (no `info:` at root): MUST use `'./path/from/root/file.yaml#/TypeName'` for ALL refs
-   - Identify top files by presence of `info` section at root level
-
-5. **Top file is required for generation**
-   - Only files with `info:` section can be used with `type-crafter generate`
-   - Non-top files must be referenced from a top file
-
----
-
-## Multi-File Specifications
-
-### File Organization Patterns
-
-#### Pattern 1: Single Top-Level File
-
-**Best for:** Small to medium projects
-
-```
-project/
-├── types.yaml          # Single file with all types
-└── src/
-    └── index.ts
-```
-
-**types.yaml:**
-```yaml
-info:
-  version: '1.0.0'
-  title: 'Project Types'
-
-types:
-  User:
-    type: object
-    properties:
-      id: { type: string }
-
-  Post:
-    type: object
-    properties:
-      author: { $ref: '#/types/User' }
-```
-
-#### Pattern 2: Multiple Files with Main Entry Point
-
-**Best for:** Large projects with logical domain separation
-
-```
-project/
-├── types/
-│   ├── index.yaml      # Main entry point (top-level file)
-│   ├── user.yaml       # User-related types (sub-file)
-│   ├── post.yaml       # Post-related types (sub-file)
-│   └── comment.yaml    # Comment-related types (sub-file)
-└── src/
-    └── index.ts
-```
-
-**types/index.yaml (Top-level file):**
-```yaml
-info:
-  version: '1.0.0'
-  title: 'Main API Types'
-
-# Import types from other files
-types:
-  # Reference to external file (from project root)
-  User:
-    $ref: './types/user.yaml#/User'
-
-  Post:
-    $ref: './types/post.yaml#/Post'
-
-  Comment:
-    $ref: './types/comment.yaml#/Comment'
-```
-
-**types/user.yaml (Sub-file):**
-```yaml
-info:
-  version: '1.0.0'
-  title: 'User Types'
-
-types:
-  User:
-    type: object
-    required:
-      - id
-      - email
-    properties:
-      id:
-        type: string
-      email:
-        type: string
-      name:
-        type: string  # nullable (not in required)
-```
-
-**types/post.yaml (Sub-file):**
-```yaml
-info:
-  version: '1.0.0'
-  title: 'Post Types'
-
-types:
-  Post:
-    type: object
-    required:
-      - id
-      - title
-      - author
-    properties:
-      id:
-        type: string
-      title:
-        type: string
-      author:
-        # Reference to user.yaml from project root
-        $ref: './types/user.yaml#/User'
-```
-
-#### Pattern 3: Grouped Types with External References
-
-**Best for:** Complex domains with many related types
-
-```
-project/
-├── specs/
-│   ├── api.yaml        # Main entry point
-│   ├── auth/
-│   │   └── types.yaml  # Auth domain types
-│   └── shop/
-│       ├── cart.yaml   # Shopping cart types
-│       └── product.yaml # Product types
-└── src/
-```
-
-**specs/api.yaml (Top-level file):**
-```yaml
-info:
-  version: '1.0.0'
-  title: 'API Specification'
-
-groupedTypes:
-  # Import entire groups from external files
-  Auth:
-    $ref: './specs/auth/types.yaml#/AuthTypes'
-
-  Shop:
-    Cart:
-      $ref: './specs/shop/cart.yaml#/ShopTypes/Cart'
-    Product:
-      $ref: './specs/shop/product.yaml#/ShopTypes/Product'
-```
-
-**specs/auth/types.yaml:**
-```yaml
-info:
-  version: '1.0.0'
-  title: 'Authentication Types'
-
-groupedTypes:
-  AuthTypes:
-    LoginRequest:
-      type: object
-      required:
-        - email
-        - password
-      properties:
-        email: { type: string }
-        password: { type: string }
-
-    LoginResponse:
-      type: object
-      required:
-        - token
-        - user
-      properties:
-        token: { type: string }
-        user:
-          $ref: './specs/user.yaml#/User'  # Cross-file reference
-```
-
-### Multi-File Reference Rules
-
-#### 1. Every File Needs `info` Section
-
-```yaml
-# ✅ CORRECT: All files need info section
-info:
-  version: '1.0.0'
-  title: 'File Title'
-
-types:
-  # ... your types
-```
-
-#### 2. Reference Format
-
-```yaml
-# Local reference (same file)
-$ref: '#/types/TypeName'
-$ref: '#/groupedTypes/GroupName/TypeName'
-
-# External reference (from project root)
-$ref: './path/from/root/file.yaml#/TypeName'
-$ref: './path/from/root/file.yaml#/GroupName/TypeName'
-```
-
-#### 3. Path Resolution
-
-**CRITICAL:** All paths are from **project root** (where you run `type-crafter` command)
-
-```bash
-# If you run this command from /project
-cd /project
-type-crafter generate typescript ./specs/api.yaml ./output
-
-# Then all $ref paths in ANY file are relative to /project
-```
-
-**Example:**
-```
-/project/
-├── specs/
-│   ├── api.yaml        # File A
-│   └── user/
-│       └── types.yaml  # File B
-```
-
-**In specs/api.yaml:**
-```yaml
-# ✅ CORRECT: Path from project root
-User:
-  $ref: './specs/user/types.yaml#/User'
-
-# ❌ WRONG: Don't use relative path from current file
-User:
-  $ref: './user/types.yaml#/User'
-```
-
-**In specs/user/types.yaml:**
-```yaml
-# ✅ CORRECT: Path from project root
-Profile:
-  $ref: './specs/api.yaml#/ApiTypes/Profile'
-
-# ❌ WRONG: Don't use relative path
-Profile:
-  $ref: '../api.yaml#/ApiTypes/Profile'
-```
-
-### Generating Types from Multi-File Specs
-
-```bash
-# Generate from top-level file (references will be resolved automatically)
-type-crafter generate typescript ./types/index.yaml ./output
-
-# Or from any entry point
-type-crafter generate typescript ./specs/api.yaml ./src/types
-```
-
-All referenced files will be automatically processed and types generated.
-
----
-
-## Root Structure
-
-### Required Fields
-
-```yaml
-info:
-  version: '0.0.0' # Semver format (required)
-  title: 'My API Types' # Specification title (required)
-```
-
-### Type Organization
-
-**At least ONE is required:**
-
-```yaml
-types: {} # Flat/top-level types
-groupedTypes: {} # Grouped/organized types
-```
-
-**Can have both:**
-
-```yaml
-types:
-  User: {}
-  Post: {}
-
-groupedTypes:
-  Auth:
-    LoginRequest: {}
-    LoginResponse: {}
-```
-
----
-
-## Data Types & Type Mapping
-
-### Primitive Types → TypeScript Mapping
-
-| YAML Type               | TypeScript Output | Notes                          |
-| ----------------------- | ----------------- | ------------------------------ |
-| `string`                | `string`          | Default string                 |
-| `string` (format: date) | `Date`            | With format specified          |
-| `number`                | `number`          | Floating point                 |
-| `integer`               | `number`          | TypeScript has no integer type |
-| `boolean`               | `boolean`         |                                |
-| `array`                 | `Type[]`          | Requires `items` specification |
-| `object`                | `{ ... }`         | Custom object type             |
-| `unknown`               | `unknown`         | For dynamic/any type           |
-
-### Format Modifiers
-
-```yaml
-# String with format
-dateField:
-  type: string
-  format: date # Generates: Date (not string)
-```
-
----
-
-## Constraints & Limitations
-
-### ❌ Arrays Cannot Be Top-Level Types
-
-Arrays can **ONLY** be used as properties within object types, never as standalone top-level types.
-
-```yaml
-# ❌ INVALID - This will NOT work
-Tags:
-  type: array
-  items:
-    type: string
-
-# ✅ VALID - Arrays must be properties
-Post:
-  type: object
-  properties:
-    tags:
-      type: array
-      items:
-        type: string
-```
-
-**Why:** Type Crafter generates named types. An array alone has no semantic meaning - it must be a property that describes what the array contains.
-
-### ✅ Valid Type Categories
-
-Only these can be top-level types:
-
-- **Objects** (`type: object` with properties)
-- **Enums** (`type: string/number` with enum array)
-- **Primitives** (string, number, boolean, unknown)
-- **Unions** (oneOf)
-- **Intersections** (allOf)
-- **References** ($ref)
-
----
-
-## Nullable Types (Critical)
-
-### ⚠️ IMPORTANT: Required vs Optional Properties
-
-**Properties NOT in `required` array become nullable (`Type | null`)**
-
-This is controlled EXCLUSIVELY by the `required` array. There are NO other properties or syntax for controlling nullability.
-
-### ❌ WRONG: What NOT to Do
-
-```yaml
-# ❌ WRONG: Do NOT use 'nullable' property
-User:
-  type: object
-  properties:
-    name:
-      type: string
-      nullable: true  # ❌ INVALID! This property does NOT exist in Type Crafter
-
-# ❌ WRONG: Do NOT use 'optional' property
-User:
-  type: object
-  properties:
-    name:
-      type: string
-      optional: true  # ❌ INVALID! This property does NOT exist
-
-# ❌ WRONG: Do NOT use '?' suffix
-User:
-  type: object
-  properties:
-    name?:  # ❌ INVALID! Don't use ? in property names
-      type: string
-
-# ❌ WRONG: Do NOT use null in type
-User:
-  type: object
-  properties:
-    name:
-      type: [string, null]  # ❌ INVALID! Don't use array of types here
-```
-
-### ✅ CORRECT: Use `required` Array Only
-
-```yaml
-# ✅ CORRECT: Control nullability with 'required' array
-User:
-  type: object
-  required:
-    - id      # id is required → generates: string
-    - email   # email is required → generates: string
-    # name is NOT in required → generates: string | null
-    # age is NOT in required → generates: number | null
-  properties:
-    id:
-      type: string
-    email:
-      type: string
-    name:
-      type: string
-    age:
-      type: number
-```
-
-**TypeScript Output:**
-
-```typescript
-export type User = {
-  id: string; // Required (in required array)
-  email: string; // Required (in required array)
-  name: string | null; // Nullable (NOT in required array)
-  age: number | null; // Nullable (NOT in required array)
-};
-```
-
-### Detailed Rules
-
-1. ✅ **Property in `required` array** → Generates `Type` (NOT nullable)
-
-   ```yaml
-   User:
-     type: object
-     required:
-       - name
-     properties:
-       name: { type: string }
-   # Generates: name: string
-   ```
-
-2. ✅ **Property NOT in `required` array** → Generates `Type | null` (nullable)
-
-   ```yaml
-   User:
-     type: object
-     required:
-       - id
-     properties:
-       id: { type: string }
-       name: { type: string } # NOT in required
-   # Generates: name: string | null
-   ```
-
-3. ✅ **No `required` array at all** → All properties are `Type | null`
-
-   ```yaml
-   User:
-     type: object
-     # No required array
-     properties:
-       id: { type: string }
-       name: { type: string }
-   # Generates: id: string | null, name: string | null
-   ```
-
-4. ✅ **Empty `required: []`** → All properties are `Type | null`
-   ```yaml
-   User:
-     type: object
-     required: [] # Empty array
-     properties:
-       id: { type: string }
-   # Generates: id: string | null
-   ```
-
-### Complete Examples
-
-#### Example 1: All Properties Required
-
-```yaml
-User:
-  type: object
-  required:
-    - id
-    - email
-    - name
-    - age
-  properties:
-    id: { type: string }
-    email: { type: string }
-    name: { type: string }
-    age: { type: number }
-```
-
-```typescript
-// Generated TypeScript
-export type User = {
-  id: string;
-  email: string;
-  name: string;
-  age: number;
-};
-```
-
-#### Example 2: Some Properties Required
-
-```yaml
-User:
-  type: object
-  required:
-    - id
-    - email
-  properties:
-    id: { type: string }
-    email: { type: string }
-    name: { type: string }
-    age: { type: number }
-```
-
-```typescript
-// Generated TypeScript
-export type User = {
-  id: string;
-  email: string;
-  name: string | null;
-  age: number | null;
-};
-```
-
-#### Example 3: No Properties Required
-
-```yaml
-User:
-  type: object
-  properties:
-    id: { type: string }
-    email: { type: string }
-    name: { type: string }
-    age: { type: number }
-```
-
-```typescript
-// Generated TypeScript - All nullable
-export type User = {
-  id: string | null;
-  email: string | null;
-  name: string | null;
-  age: number | null;
-};
-```
-
-### Nested Objects and Arrays
-
-```yaml
-User:
-  type: object
-  required:
-    - profile
-    - posts
-  properties:
-    profile:
-      type: object
-      required:
-        - name
-      properties:
-        name: { type: string }
-        bio: { type: string } # NOT in profile.required
-    posts:
-      type: array
-      items:
-        type: object
-        required:
-          - title
-        properties:
-          title: { type: string }
-          content: { type: string } # NOT in items.required
-```
-
-```typescript
-// Generated TypeScript
-export type User = {
-  profile: {
-    // profile is required (in User.required)
-    name: string; // required in profile
-    bio: string | null; // NOT required in profile
-  };
-  posts: Array<{
-    // posts array is required
-    title: string; // required in post item
-    content: string | null; // NOT required in post item
-  }>;
-};
-```
-
----
-
-## Type Definitions
-
-### Object Type
-
-```yaml
-User:
-  type: object
-  description: 'User account type' # Optional metadata
-  example: "{ id: '123', name: 'John' }" # Optional example
-  required:
-    - id
-    - email
-  properties:
-    id:
-      type: string
-      description: 'Unique identifier'
-      example: 'user-123'
-    email:
-      type: string
-    name:
-      type: string
-    age:
-      type: number
-```
-
-**TypeScript:**
-
-```typescript
-/**
- * @type { User }
- * @description User account type
- * @example { id: '123', name: 'John' }
- */
-export type User = {
-  /**
-   * @description Unique identifier
-   * @type { string }
-   * @memberof User
-   * @example user-123
-   */
-  id: string;
-  email: string;
-  name: string | null;
-  age: number | null;
-};
-```
-
-### Enum Type (Top-Level)
-
-```yaml
-Status:
-  type: string
-  description: 'User status enum'
-  example: 'active'
-  enum:
-    - active
-    - inactive
-    - pending
-
-Priority:
-  type: number
-  enum:
-    - 1
-    - 2
-    - 3
-```
-
-**TypeScript:**
-
-```typescript
-// String enum
-export type Status = 'active' | 'inactive' | 'pending';
-
-// Number enum
-export type Priority = 1 | 2 | 3;
-```
-
-### Inline Enum (Property)
-
-```yaml
-User:
-  type: object
-  properties:
-    role:
-      type: string
-      enum:
-        - admin
-        - user
-        - guest
-```
-
-**TypeScript:**
-
-```typescript
-export type User = {
-  role: ('admin' | 'user' | 'guest') | null;
-};
-```
-
-### Array Types (Property-Level Only)
-
-**⚠️ IMPORTANT: Arrays cannot be top-level types. They must be properties within an object type.**
-
-```yaml
-# ❌ INVALID - Cannot create standalone array types
-Tags:
-  type: array
-  items:
-    type: string
-
-# ✅ VALID - Arrays as properties within objects
-Post:
-  type: object
-  required:
-    - id
-    - tags
-  properties:
-    id:
-      type: string
-    tags:
-      type: array
-      items:
-        type: string
-    comments:
-      type: array
-      items:
-        type: object
-        properties:
-          text:
-            type: string
-    relatedPosts:
-      type: array
-      items:
-        $ref: '#/types/Post'
-```
-
-**TypeScript:**
-
-```typescript
-// Arrays only appear as properties, never as top-level types
-export type Post = {
-  id: string;
-  tags: string[];
-  comments: { text: string | null }[] | null;
-  relatedPosts: Post[] | null;
-};
-```
-
-### Nested Objects
-
-```yaml
-Company:
-  type: object
-  required:
-    - id
-    - address
-  properties:
-    id:
-      type: string
-    address:
-      type: object
-      required:
-        - street
-      properties:
-        street:
-          type: string
-        city:
-          type: string
-        zipCode:
-          type: string
-```
-
-**TypeScript:**
-
-```typescript
-export type Company = {
-  id: string;
-  address: {
-    street: string;
-    city: string | null;
-    zipCode: string | null;
-  };
-};
-```
-
-### Additional Properties (Hashmap/Dictionary)
-
-```yaml
-# Simple hashmap (any keys → any values)
-SimpleMap:
-  type: object
-  additionalProperties: true
-
-# Typed hashmap (string keys → string values)
-StringMap:
-  type: object
-  additionalProperties:
-    keyType: string
-    valueType:
-      type: string
-
-# Number keys → Object values
-IdMap:
-  type: object
-  additionalProperties:
-    keyType: number
-    valueType:
-      $ref: '#/types/User'
-
-# Properties + additional (mixed)
-UserWithMeta:
-  type: object
-  required:
-    - id
-  properties:
-    id:
-      type: string
-  additionalProperties:
-    keyType: string
-    valueType:
-      type: string
-```
-
-**TypeScript:**
-
-```typescript
-export type SimpleMap = {
-  [keys: string]: unknown;
-};
-
-export type StringMap = {
-  [keys: string]: string;
-};
-
-export type IdMap = {
-  [keys: number]: User;
-};
-
-export type UserWithMeta = {
-  id: string;
-  [keys: string]: string; // Additional dynamic properties
-};
-```
-
----
-
-## References
-
-### Understanding Top Files vs Non-Top Files
-
-**CRITICAL:** Referencing rules differ based on whether you're in a top file or non-top file.
-
-#### What is a Top File?
-
-A **top file** is the root specification file that contains the `info` section at the root level.
-
-**Identifying a top file:**
-```yaml
-# ✅ This is a TOP FILE
-info:
-  version: '1.0.0'  # Has info section at root
-  title: 'My API Types'
-
-types:
-  User: { ... }
-```
-
-**Characteristics:**
-- Contains `info:` section with `version` and `title` at the root level
-- Is the root of all schemas
-- Can be directly used with `type-crafter generate` command
-- Typically referenced by other files
-
-#### What is a Non-Top File?
-
-A **non-top file** is any YAML file that does NOT have `info:` at the root level. These files are used to organize types into domain-specific files.
-
-**Identifying a non-top file:**
-```yaml
-# ✅ This is a NON-TOP FILE (no info section at root)
-Cart:
-  SCart:
-    type: object
-    properties:
-      items: { ... }
-
-  SCartItem:
-    type: object
-    properties:
-      id: { ... }
-```
-
-**Characteristics:**
-- Does NOT have `info:` section at the root level
-- Must be referenced from a top file or another file
-- Used for better organization of types in domain-specific files
-- Cannot be used directly with `type-crafter generate` command
-
-### Referencing Rules
-
-#### Rule 1: References in TOP Files
-
-**In top files, you can reference types using `#` without specifying the file path.**
-
-**Example:**
-
-```yaml
-# File: types.yaml (TOP FILE - has info section)
-info:
-  version: '0.0.0'
-  title: 'Sample Typing Spec'
-
-types:
-  TypeObjectTwo:
-    type: object
-    properties:
-      propOne:
-        $ref: '#/types/TypeObjectOne'  # ✅ Direct reference (no file path needed)
-
-  TypeObjectOne:
-    type: object
-    properties:
-      name:
-        type: string
-```
-
-**Valid reference formats in top files:**
-- Same file, top-level type: `#/types/TypeName`
-- Same file, grouped type: `#/groupedTypes/GroupName/TypeName`
-- External file: `'./path/from/root/file.yaml#/TypeName'` (when referencing another file)
-
-#### Rule 2: References in NON-TOP Files
-
-**In non-top files, you MUST specify the complete file path (from project root) when referencing ANY type, even types in the same file.**
-
-**Example:**
-
-```yaml
-# File: docs/cart.yaml (NON-TOP FILE - no info section)
-Cart:
-  SCart:
-    description: 'Shopify cart object'
-    type: object
-    properties:
-      items:
-        type: array
-        items:
-          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ MUST include full file path
-
-  SCartItem:
-    description: 'Individual cart item'
-    type: object
-    properties:
-      id:
-        type: number
-```
-
-**Why the full path?** Non-top files don't have an `info` section, so they don't have a root context. You must always specify where the type is located.
-
-### Complete Examples
-
-#### Example 1: Top File with Local References
-
-```yaml
-# File: types.yaml (TOP FILE)
-info:
-  version: '1.0.0'
-  title: 'API Types'
-
-types:
-  Post:
-    type: object
-    properties:
-      author:
-        $ref: '#/types/User'  # ✅ Local reference in top file (no path)
-      comments:
-        type: array
-        items:
-          $ref: '#/types/Comment'  # ✅ Local reference in top file (no path)
-
-  User:
-    type: object
-    properties:
-      id: { type: string }
-      name: { type: string }
-
-  Comment:
-    type: object
-    properties:
-      text: { type: string }
-```
-
-#### Example 2: Top File Referencing Non-Top Files
-
-```yaml
-# File: types.yaml (TOP FILE)
-info:
-  version: '0.0.0'
-  title: 'Sample Typing Spec'
-
-groupedTypes:
-  Cart:
-    $ref: './docs/cart.yaml#/Cart'  # ✅ Importing entire Cart group from non-top file
-
-# Project structure:
-# .
-# ├── types.yaml (this file - top file)
-# └── docs/
-#     └── cart.yaml (non-top file)
-```
-
-```yaml
-# File: docs/cart.yaml (NON-TOP FILE)
-Cart:
-  SCart:
-    description: 'Shopify cart object'
-    type: object
-    required:
-      - items
-    properties:
-      items:
-        type: array
-        items:
-          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ Full path required in non-top file
-
-  SCartItem:
-    description: 'Individual item in the cart'
-    type: object
-    required:
-      - id
-    properties:
-      id:
-        type: number
-        description: 'Unique item identifier'
-      quantity:
-        type: number
-```
-
-#### Example 3: Non-Top File Referencing Another Non-Top File
-
-```yaml
-# File: docs/order.yaml (NON-TOP FILE)
-Order:
-  SOrder:
-    type: object
-    properties:
-      items:
-        type: array
-        items:
-          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ Full path to another non-top file
-      customer:
-        $ref: './docs/user.yaml#/User/SCustomer'  # ✅ Full path to another non-top file
-```
-
-### Reference Format Summary
-
-| File Type | Referencing Same File | Referencing Another File |
-|-----------|----------------------|--------------------------|
-| **Top File** | `#/types/TypeName`<br>`#/groupedTypes/Group/TypeName` | `'./path/from/root/file.yaml#/TypeName'` |
-| **Non-Top File** | `'./path/from/root/current-file.yaml#/TypeName'`<br>(full path required) | `'./path/from/root/other-file.yaml#/TypeName'` |
-
-### Path Rules (All Files)
-
-1. **Paths are from project root** (where you run `type-crafter` command), NOT relative to current file
-2. **Always start with `./`** for file paths
-3. **Never use `../`** for relative navigation
-4. **Case matters** - file paths are case-sensitive on some systems
-
-**Example project structure:**
-```
-project-root/
-├── types.yaml          (top file)
-└── docs/
-    ├── cart.yaml       (non-top file)
-    └── user.yaml       (non-top file)
-```
-
-If running `type-crafter generate typescript ./types.yaml ./output` from `project-root/`:
-- Path to cart.yaml: `'./docs/cart.yaml#/...'`
-- Path to user.yaml: `'./docs/user.yaml#/...'`
-
-### Group References (Entire Group)
-
-```yaml
-groupedTypes:
-  # Import entire group from external file
-  SharedModels:
-    $ref: './shared.yaml#/Models'
-```
-
-### Cyclic References (Self-Referencing)
-
-```yaml
-TreeNode:
-  type: object
-  properties:
-    value:
-      type: string
-    children:
-      type: array
-      items:
-        $ref: '#/types/TreeNode' # Self-reference allowed
-
-LinkedList:
-  type: object
-  properties:
-    value:
-      type: number
-    next:
-      $ref: '#/types/LinkedList' # Self-reference allowed
-```
-
-**TypeScript:**
-
-```typescript
-export type TreeNode = {
-  value: string | null;
-  children: TreeNode[] | null;
-};
-
-export type LinkedList = {
-  value: number | null;
-  next: LinkedList | null;
-};
-```
-
----
-
-## Composition
-
-### oneOf (Union Types)
-
-Creates TypeScript union: `TypeA | TypeB | TypeC`
-
-```yaml
-Response:
-  oneOf:
-    # Reference types
-    - $ref: '#/types/SuccessResponse'
-    - $ref: '#/types/ErrorResponse'
-    # Primitive types
-    - type: string
-    - type: number
-    # Inline enum
-    - type: string
-      enum:
-        - pending
-        - loading
-    # Inline object
-    - type: object
-      properties:
-        status:
-          type: string
-    # Array type
-    - type: array
-      items:
-        type: string
-```
-
-**TypeScript:**
-
-```typescript
-export type Response =
-  | SuccessResponse
-  | ErrorResponse
-  | string
-  | number
-  | ('pending' | 'loading')
-  | { status: string | null }
-  | string[];
-```
-
-### allOf (Intersection/Merge Types)
-
-Creates TypeScript intersection: `TypeA & TypeB & TypeC`
-
-```yaml
-AdminUser:
-  allOf:
-    - $ref: '#/types/BaseUser'
-    - $ref: '#/types/AdminPermissions'
-    - type: object
-      properties:
-        adminLevel:
-          type: number
-
-# Output merges all types together
-```
-
-**TypeScript:**
-
-```typescript
-export type AdminUser = BaseUser &
-  AdminPermissions & {
-    adminLevel: number | null;
-  };
-```
-
----
-
-## TypeScript Generation Examples
-
-### Complete Example
-
-**YAML:**
-
-```yaml
-info:
-  version: '1.0.0'
-  title: 'Blog API Types'
-
-types:
-  User:
-    type: object
-    description: 'Blog user account'
-    required:
-      - id
-      - email
-      - role
-    properties:
-      id:
-        type: string
-        description: 'Unique user ID'
-      email:
-        type: string
-      role:
-        $ref: '#/types/UserRole'
-      profile:
-        type: object
-        properties:
-          name:
-            type: string
-          avatar:
-            type: string
-
-  UserRole:
-    type: string
-    enum:
-      - admin
-      - editor
-      - viewer
-
-  Post:
-    type: object
-    required:
-      - id
-      - title
-      - author
-    properties:
-      id:
-        type: string
-      title:
-        type: string
-      content:
-        type: string
-      author:
-        $ref: '#/types/User'
-      tags:
-        type: array
-        items:
-          type: string
-      metadata:
-        type: object
-        additionalProperties:
-          keyType: string
-          valueType:
-            type: string
-```
-
-**TypeScript Output:**
-
-```typescript
-/**
- * @type { User }
- * @description Blog user account
- */
-export type User = {
-  /**
-   * @description Unique user ID
-   * @type { string }
-   * @memberof User
-   */
-  id: string;
-  email: string;
-  role: UserRole;
-  profile: {
-    name: string | null;
-    avatar: string | null;
-  } | null;
-};
-
-export type UserRole = 'admin' | 'editor' | 'viewer';
-
-export type Post = {
-  id: string;
-  title: string;
-  content: string | null;
-  author: User;
-  tags: string[] | null;
-  metadata: {
-    [keys: string]: string;
-  } | null;
-};
-```
-
----
-
-## Best Practices
-
-### 1. Always Use `required` Array
-
-```yaml
-# ❌ BAD - All properties become nullable
-User:
-  type: object
-  properties:
-    id: { type: string }
-    email: { type: string }
-
-# ✅ GOOD - Explicit required fields
-User:
-  type: object
-  required:
-    - id
-    - email
-  properties:
-    id: { type: string }
-    email: { type: string }
-```
-
-### 2. Use PascalCase for Type Names
-
-```yaml
-# ✅ GOOD
-types:
-  UserProfile: {}
-  BlogPost: {}
-  APIResponse: {}
-
-# ❌ AVOID
-types:
-  userProfile: {}
-  blog_post: {}
-  api-response: {}
-```
-
-### 3. Group Related Types
-
-```yaml
-# ✅ GOOD
-groupedTypes:
-  Auth:
-    LoginRequest: {}
-    LoginResponse: {}
-    RefreshToken: {}
-
-  Users:
-    UserProfile: {}
-    UserSettings: {}
-    UserPreferences: {}
-```
-
-### 4. Use Descriptions for Complex Types
-
-```yaml
-# ✅ GOOD
-User:
-  type: object
-  description: 'Represents a registered user account with authentication details'
-  properties:
-    passwordHash:
-      type: string
-      description: 'Bcrypt hashed password (never expose in responses)'
-```
-
-### 5. Reference External Types for Reusability
-
-```yaml
-# ✅ GOOD - Reuse common types (paths from project root)
-Post:
-  type: object
-  properties:
-    author:
-      $ref: './src/types/common.yaml#/User'
-    metadata:
-      $ref: './src/types/common.yaml#/Metadata'
-
-# Real example: Shopify cart referencing item types
-SCart:
-  type: object
-  properties:
-    items:
-      type: array
-      items:
-        $ref: './docs/specs/Cart.yaml#/Cart/SCartItem'
-```
-
-**Remember:** Paths are from project root, not relative to current file location.
-
----
-
-## Common Patterns
-
-### Pattern 1: Paginated Response
-
-```yaml
-PaginatedUsers:
-  type: object
-  required:
-    - data
-    - total
-    - page
-  properties:
-    data:
-      type: array
-      items:
-        $ref: '#/types/User'
-    total:
-      type: number
-    page:
-      type: number
-    perPage:
-      type: number
-```
-
-### Pattern 2: API Response Wrapper
-
-```yaml
-ApiResponse:
-  oneOf:
-    - type: object
-      required:
-        - success
-        - data
-      properties:
-        success:
-          type: boolean
-        data:
-          type: unknown
-    - type: object
-      required:
-        - success
-        - error
-      properties:
-        success:
-          type: boolean
-        error:
-          type: string
-```
-
-### Pattern 3: Timestamps Mixin
-
-```yaml
-Timestamped:
-  type: object
-  required:
-    - createdAt
-    - updatedAt
-  properties:
-    createdAt:
-      type: string
-      format: date
-    updatedAt:
-      type: string
-      format: date
-
-# Use with allOf
-User:
-  allOf:
-    - $ref: '#/types/Timestamped'
-    - type: object
-      required:
-        - id
-      properties:
-        id: { type: string }
-```
-
-### Pattern 4: Enum + Metadata
-
-```yaml
-StatusType:
-  type: string
-  enum:
-    - draft
-    - published
-    - archived
-
-Post:
-  type: object
-  required:
-    - status
-  properties:
-    status:
-      $ref: '#/types/StatusType'
-    statusChangedAt:
-      type: string
-      format: date
-```
-
----
-
-## Rules Checklist
-
-### Required ✅
-
-- [ ] Has `info.version` (string)
-- [ ] Has `info.title` (string)
-- [ ] Has `types` OR `groupedTypes` (or both)
-
-### Constraints ✅
-
-- [ ] **Arrays CANNOT be top-level types** - must be properties within objects
-- [ ] Only objects, enums, primitives, unions, intersections, and references can be top-level types
-- [ ] Arrays require `items` specification
-
-### Type Definitions ✅
-
-- [ ] Objects have `type: object`
-- [ ] Arrays are only used as properties (never top-level)
-- [ ] Enums have `type` (string/number) with `enum` array
-- [ ] Use `required` array for non-nullable properties
-- [ ] Properties not in `required` become `Type | null`
-
-### References ✅
-
-- [ ] Local references: `#/types/Name` or `#/groupedTypes/Group/Name`
-- [ ] External references: `./path/from/root/file.yaml#/Name`
-- [ ] **External paths are from project root, NOT relative to current file**
-- [ ] Cyclic references are allowed
-
-### Composition ✅
-
-- [ ] `oneOf` creates unions (`A | B | C`)
-- [ ] `allOf` creates intersections (`A & B & C`)
-- [ ] Can mix inline types and references
-
-### TypeScript Generation ✅
-
-- [ ] `string` → `string`
-- [ ] `string` (format: date) → `Date`
-- [ ] `number`/`integer` → `number`
-- [ ] `boolean` → `boolean`
-- [ ] `array` → `Type[]`
-- [ ] `object` → `{ ... }`
-- [ ] `unknown` → `unknown`
-- [ ] NOT in `required` → `Type | null`
-
-### Best Practices ✅
-
-- [ ] Use PascalCase for type names
-- [ ] Always specify `required` array for objects
-- [ ] Group related types in `groupedTypes`
-- [ ] Add descriptions for complex types
-- [ ] Use references for reusability
-- [ ] Prefer explicit over implicit nullability
-
----
-
-## Summary
-
-| Concept           | YAML                          | TypeScript           |
-| ----------------- | ----------------------------- | -------------------- |
-| Required property | In `required` array           | `prop: Type`         |
-| Optional property | NOT in `required` array       | `prop: Type \| null` |
-| String enum       | `type: string, enum: [...]`   | `'a' \| 'b' \| 'c'`  |
-| Number enum       | `type: number, enum: [...]`   | `1 \| 2 \| 3`        |
-| Union             | `oneOf: [...]`                | `A \| B \| C`        |
-| Intersection      | `allOf: [...]`                | `A & B & C`          |
-| Array             | `type: array, items: {...}`   | `Type[]`             |
-| Hashmap           | `additionalProperties: {...}` | `[key: Type]: Type`  |
-| Reference         | `$ref: '#/...'`               | Type name            |
-| Nested object     | Inline `type: object`         | `{ ... }`            |
-
----
-
-**Remember:** Properties NOT in the `required` array automatically become `Type | null` in TypeScript!