@type-crafter/mcp 0.5.0 → 0.6.0

package/README.md

@@ -268,20 +268,6 @@ npm run build
 npm run dev
 ```
 
-## Development
-
-### Building from Source
-
-```bash
-npm run build
-```
-
-### Watch Mode
-
-```bash
-npm run dev
-```
-
 ### Linting
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@type-crafter/mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for Type Crafter - generate types from YAML specifications",
   "type": "module",
   "main": "./dist/index.js",

package/src/SPEC_RULES.md

@@ -63,6 +63,29 @@ User:
   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
@@ -96,6 +119,37 @@ User:
   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
@@ -113,9 +167,14 @@ User:
    - NOT relative to current YAML file
    - Always use `./path/from/root/file.yaml#/Type`
 
-4. **Every spec file needs `info` section**
-   - Even sub-files need `info: { version, title }`
-   - Top-level file and all referenced files must have `info`
+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
 
 ---
 
@@ -966,69 +1025,238 @@ export type UserWithMeta = {
 
 ## References
 
-### Local References (Same File)
+### 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
-# Reference to top-level type
-Post:
-  type: object
-  properties:
-    author:
-      $ref: '#/types/User'
+# ✅ This is a TOP FILE
+info:
+  version: '1.0.0'  # Has info section at root
+  title: 'My API Types'
 
-# Reference to grouped type
-Comment:
-  type: object
-  properties:
-    author:
-      $ref: '#/groupedTypes/Auth/UserProfile'
+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: { ... }
 ```
 
-**Reference Format:**
+**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
 
-- Top-level: `#/types/TypeName`
-- Grouped: `#/groupedTypes/GroupName/TypeName`
+### Referencing Rules
 
-### External File References
+#### Rule 1: References in TOP Files
 
-**⚠️ IMPORTANT: Paths are from project root, not relative to current file**
+**In top files, you can reference types using `#` without specifying the file path.**
+
+**Example:**
 
 ```yaml
-# Reference to type in another file (path from project root)
-Post:
-  type: object
-  properties:
-    author:
-      $ref: './src/types/users.yaml#/User'
+# File: types.yaml (TOP FILE - has info section)
+info:
+  version: '0.0.0'
+  title: 'Sample Typing Spec'
 
-# Reference to grouped type in another file
-Comment:
-  type: object
-  properties:
-    metadata:
-      $ref: './docs/specs/common.yaml#/SharedTypes/Metadata'
+types:
+  TypeObjectTwo:
+    type: object
+    properties:
+      propOne:
+        $ref: '#/types/TypeObjectOne'  # ✅ Direct reference (no file path needed)
 
-# Real-world example: Shopify cart referencing cart item
-SCart:
-  type: object
-  properties:
-    items:
-      type: array
+  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:
-        $ref: './docs/specs/Cart.yaml#/Cart/SCartItem'
+        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
 ```
 
-**Reference Format:**
+**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
 
-- **Path from project root:** `./path/from/root/file.yaml#/TypeName`
-- External type: `./path/from/root/file.yaml#/TypeName`
-- External grouped: `./path/from/root/file.yaml#/GroupName/TypeName`
+```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 }
 
-**Path Rules:**
+  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)
+```
 
-- Paths start with `./` and are relative to **project root** (where you run the command)
-- NOT relative to the current YAML file location
-- Example: If your spec is at `./src/api.yaml` and references `./src/types/user.yaml`, the path is `./src/types/user.yaml`, not `./types/user.yaml`
+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)