@type-crafter/mcp 1.2.0 → 1.2.1

package/dist/docs/RULES_REFERENCES.md

@@ -1,46 +1,37 @@
 # References Rules
 
-## Reference Syntax
+**Only the `$ref` keyword is used for references. No other referencing mechanism exists (`$include`, `$import`, `extends`, `inherits`, etc. are all invalid).**
 
-References use `$ref` to point to other types:
+---
 
-```yaml
-$ref: '#/types/TypeName'           # Same file, top-level type
-$ref: '#/groupedTypes/Group/Type'  # Same file, grouped type
-$ref: './path/file.yaml#/TypeName' # External file
-```
+## Valid Reference Formats (Complete List)
 
----
+There are exactly **three** valid `$ref` formats:
 
-## Top File vs Non-Top File (CRITICAL)
+| Format | When to use | Example |
+| --- | --- | --- |
+| `#/types/TypeName` | Top file, same-file, types section | `$ref: '#/types/User'` |
+| `#/groupedTypes/Group/TypeName` | Top file, same-file, grouped section | `$ref: '#/groupedTypes/Auth/Token'` |
+| `'./path/file.yaml#/TypePath'` | External file, OR any ref in non-top files | `$ref: './shared/types.yaml#/User'` |
 
-### Identifying File Type
+**No other reference formats exist.**
+
+---
 
-**Top File** = Has `info` section at root:
+## Top File vs Non-Top File
 
-```yaml
-info:
-  version: '1.0.0'
-  title: 'My Types'
-types:
-  User: { ... }
-```
+### Identifying File Type
 
-**Non-Top File** = No `info` section:
+**Top File** = Has `info` section with valid `version` and `title`.
 
-```yaml
-# No info section here
-UserTypes:
-  User: { ... }
-  Profile: { ... }
-```
+**Non-Top File** = No `info` section.
 
 ### Reference Rules by File Type
 
-| File Type    | Same-File Reference                | External Reference         |
-| ------------ | ---------------------------------- | -------------------------- |
-| Top File     | `#/types/Name`                     | `'./path/file.yaml#/Name'` |
-| Non-Top File | `'./path/to/this-file.yaml#/Name'` | `'./path/file.yaml#/Name'` |
+| File Type | Same-File Reference | External Reference |
+| --- | --- | --- |
+| Top File | `#/types/Name` or `#/groupedTypes/Group/Name` | `'./path/file.yaml#/Name'` |
+| Non-Top File | `'./path/to/this-file.yaml#/Name'` (full path required) | `'./path/file.yaml#/Name'` |
 
 ---
 
@@ -49,7 +40,6 @@ UserTypes:
 In a file WITH `info` section:
 
 ```yaml
-# types.yaml (TOP FILE)
 info:
   version: '1.0.0'
   title: 'API Types'
@@ -59,12 +49,13 @@ types:
     type: object
     properties:
       profile:
-        $ref: '#/types/Profile' # Same-file reference
+        $ref: '#/types/Profile'
 
   Profile:
     type: object
     properties:
-      bio: { type: string }
+      bio:
+        type: string
 
 groupedTypes:
   Auth:
@@ -72,14 +63,15 @@ groupedTypes:
       type: object
       properties:
         user:
-          $ref: '#/types/User' # Reference to types section
+          $ref: '#/types/User'
         session:
-          $ref: '#/groupedTypes/Auth/Session' # Same group
+          $ref: '#/groupedTypes/Auth/Session'
 
     Session:
       type: object
       properties:
-        token: { type: string }
+        token:
+          type: string
 ```
 
 ---
@@ -89,7 +81,6 @@ groupedTypes:
 In a file WITHOUT `info` section, you MUST use full paths for EVERYTHING:
 
 ```yaml
-# shared/cart.yaml (NON-TOP FILE - no info section)
 Cart:
   CartItem:
     type: object
@@ -97,7 +88,6 @@ Cart:
       - product
     properties:
       product:
-        # MUST use full path even for same-file reference
         $ref: './shared/cart.yaml#/Cart/Product'
       quantity:
         type: number
@@ -105,27 +95,14 @@ Cart:
   Product:
     type: object
     properties:
-      name: { type: string }
-      price: { type: number }
+      name:
+        type: string
+      price:
+        type: number
 ```
 
 **Why?** Non-top files have no root context. The parser needs the full path to resolve references.
 
-### Common Mistake in Non-Top Files
-
-```yaml
-# shared/cart.yaml (NON-TOP FILE)
-Cart:
-  CartItem:
-    type: object
-    properties:
-      product:
-        $ref: '#/Cart/Product'  # WRONG! Missing file path
-
-      product:
-        $ref: './shared/cart.yaml#/Cart/Product'  # CORRECT
-```
-
 ---
 
 ## External File References
@@ -152,7 +129,6 @@ my-project/           # <- Run CLI from here
 ### References in api.yaml (top file)
 
 ```yaml
-# specs/api.yaml
 info:
   version: '1.0.0'
   title: 'API'
@@ -171,39 +147,20 @@ groupedTypes:
 ### References in cart.yaml (non-top file)
 
 ```yaml
-# specs/shop/cart.yaml (NON-TOP FILE)
 Cart:
   CartItem:
     type: object
     properties:
       product:
-        # Reference to another non-top file
         $ref: './specs/shop/product.yaml#/Product/ProductInfo'
-
-      # Same-file reference - still needs full path!
       discount:
         $ref: './specs/shop/cart.yaml#/Cart/Discount'
 
   Discount:
     type: object
     properties:
-      amount: { type: number }
-```
-
-### WRONG: Using Relative Paths
-
-```yaml
-# specs/shop/cart.yaml
-Cart:
-  CartItem:
-    type: object
-    properties:
-      product:
-        # WRONG - Don't use ../
-        $ref: '../product.yaml#/Product'
-
-        # CORRECT - From project root
-        $ref: './specs/shop/product.yaml#/Product'
+      amount:
+        type: number
 ```
 
 ---
@@ -213,29 +170,28 @@ Cart:
 You can reference an entire group, not just individual types:
 
 ```yaml
-# api.yaml (top file)
 info:
   version: '1.0.0'
   title: 'API'
 
 groupedTypes:
-  # Import entire Auth group from external file
   Auth:
     $ref: './specs/auth/types.yaml#/AuthTypes'
 ```
 
 ```yaml
-# specs/auth/types.yaml (can be top or non-top)
 AuthTypes:
   LoginRequest:
     type: object
     properties:
-      email: { type: string }
+      email:
+        type: string
 
   LoginResponse:
     type: object
     properties:
-      token: { type: string }
+      token:
+        type: string
 ```
 
 ---
@@ -255,7 +211,7 @@ TreeNode:
     children:
       type: array
       items:
-        $ref: '#/types/TreeNode' # Self-reference
+        $ref: '#/types/TreeNode'
 
 LinkedList:
   type: object
@@ -263,40 +219,16 @@ LinkedList:
     value:
       type: number
     next:
-      $ref: '#/types/LinkedList' # Self-reference
+      $ref: '#/types/LinkedList'
 ```
 
-**TypeScript:**
-
-```typescript
-export type TreeNode = {
-  value: string;
-  children: TreeNode[] | null;
-};
-
-export type LinkedList = {
-  value: number | null;
-  next: LinkedList | null;
-};
-```
-
----
-
-## Reference Path Formats
-
-| Context                      | Format                      | Example                                |
-| ---------------------------- | --------------------------- | -------------------------------------- |
-| Top file, same file, types   | `#/types/Name`              | `$ref: '#/types/User'`                 |
-| Top file, same file, grouped | `#/groupedTypes/Group/Name` | `$ref: '#/groupedTypes/Auth/Token'`    |
-| Top file, external           | `'./path/file.yaml#/...'`   | `$ref: './shared/types.yaml#/User'`    |
-| Non-top file, ANY reference  | `'./path/file.yaml#/...'`   | `$ref: './this/file.yaml#/Group/Type'` |
-
 ---
 
-## Checklist
+## Valid Reference Formats Summary
 
-- [ ] Is this a top file or non-top file?
-- [ ] If non-top: Am I using full paths for ALL references?
-- [ ] Are paths from project root (not relative to current file)?
-- [ ] Do paths start with `./`?
-- [ ] No `../` in any path?
+| Context | Format | Example |
+| --- | --- | --- |
+| Top file, same file, types | `#/types/Name` | `$ref: '#/types/User'` |
+| Top file, same file, grouped | `#/groupedTypes/Group/Name` | `$ref: '#/groupedTypes/Auth/Token'` |
+| Top file, external | `'./path/file.yaml#/...'` | `$ref: './shared/types.yaml#/User'` |
+| Non-top file, ANY reference | `'./path/file.yaml#/...'` | `$ref: './this/file.yaml#/Group/Type'` |

package/dist/docs/RULES_STRUCTURE.md

@@ -1,35 +1,43 @@
 # Structure Rules
 
-## Root Structure
+**Only the structure documented here is valid. Any keys or sections not listed will be rejected.**
 
-Every Type Crafter spec file has this structure:
+---
 
-```yaml
-info:
-  version: '1.0.0' # Required - semver format
-  title: 'My Types' # Required - descriptive title
+## Valid Root-Level Keys (Complete List)
 
-types: # Optional - flat/top-level types
-  TypeName: { ... }
+A spec file has exactly **three** possible root-level keys:
 
-groupedTypes: # Optional - organized into namespaces
-  GroupName:
-    TypeName: { ... }
-```
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `info` | object | Yes (for top files) | Metadata with version and title |
+| `types` | object | At least one required | Flat/top-level type definitions |
+| `groupedTypes` | object | At least one required | Namespaced type definitions |
+
+**No other root-level keys exist.** Do not add `schemas`, `definitions`, `components`, `models`, `imports`, `config`, or anything else.
 
 **Rule:** At least ONE of `types` or `groupedTypes` is required.
 
 ---
 
-## The `info` Section
+## The `info` Object (Complete List)
+
+The `info` object accepts exactly **two** keys:
+
+| Key | Type | Required |
+| --- | --- | --- |
+| `version` | string (semver) | Yes |
+| `title` | string | Yes |
+
+**No other info keys exist.** Do not add `description`, `contact`, `license`, `baseUrl`, `servers`, or anything else.
 
 ```yaml
 info:
-  version: '1.0.0' # String, semver format
-  title: 'API Types' # String, describes the spec
+  version: '1.0.0'
+  title: 'API Types'
 ```
 
-Both fields are **required**. Without them, the file is a "non-top file" with different reference rules.
+Without a valid `info` section, the file is a "non-top file" with different reference rules.
 
 ---
 
@@ -38,7 +46,6 @@ Both fields are **required**. Without them, the file is a "non-top file" with di
 ### Top File (has `info` section)
 
 ```yaml
-# top-file.yaml
 info:
   version: '1.0.0'
   title: 'Main Types'
@@ -48,11 +55,12 @@ types:
     type: object
     properties:
       profile:
-        $ref: '#/types/Profile' # Can use #/ for same-file refs
+        $ref: '#/types/Profile'
   Profile:
     type: object
     properties:
-      bio: { type: string }
+      bio:
+        type: string
 ```
 
 **Rules for top files:**
@@ -64,18 +72,17 @@ types:
 ### Non-Top File (no `info` section)
 
 ```yaml
-# shared/cart.yaml - NO info section
 Cart:
   CartItem:
     type: object
     properties:
       product:
-        # MUST use full path, even for same-file refs
         $ref: './shared/cart.yaml#/Cart/Product'
   Product:
     type: object
     properties:
-      name: { type: string }
+      name:
+        type: string
 ```
 
 **Rules for non-top files:**
@@ -94,13 +101,17 @@ For standalone, top-level types:
 types:
   User:
     type: object
-    required: [id]
+    required:
+      - id
     properties:
-      id: { type: string }
+      id:
+        type: string
 
   Status:
     type: string
-    enum: [active, inactive]
+    enum:
+      - active
+      - inactive
 
   ApiResponse:
     oneOf:
@@ -108,14 +119,6 @@ types:
       - type: string
 ```
 
-**Generated TypeScript:**
-
-```typescript
-export type User = { id: string };
-export type Status = 'active' | 'inactive';
-export type ApiResponse = User | string;
-```
-
 ---
 
 ## `groupedTypes` Section (Namespaced Types)
@@ -127,41 +130,37 @@ groupedTypes:
   Auth:
     LoginRequest:
       type: object
-      required: [email, password]
+      required:
+        - email
+        - password
       properties:
-        email: { type: string }
-        password: { type: string }
+        email:
+          type: string
+        password:
+          type: string
 
     LoginResponse:
       type: object
-      required: [token]
+      required:
+        - token
       properties:
-        token: { type: string }
+        token:
+          type: string
         user:
           $ref: '#/groupedTypes/Auth/User'
 
     User:
       type: object
       properties:
-        id: { type: string }
+        id:
+          type: string
 
   Shop:
     Product:
       type: object
       properties:
-        name: { type: string }
-```
-
-**Generated TypeScript (with FolderWithFiles mode):**
-
-```
-output/
-  Auth/
-    LoginRequest.ts
-    LoginResponse.ts
-    User.ts
-  Shop/
-    Product.ts
+        name:
+          type: string
 ```
 
 ---
@@ -176,22 +175,24 @@ info:
   title: 'Full API'
 
 types:
-  # Shared/common types
   Timestamp:
     type: object
-    required: [createdAt]
+    required:
+      - createdAt
     properties:
-      createdAt: { type: string, format: date }
+      createdAt:
+        type: string
+        format: date
 
 groupedTypes:
-  # Domain-specific types
   Users:
     User:
       allOf:
         - $ref: '#/types/Timestamp'
         - type: object
           properties:
-            name: { type: string }
+            name:
+              type: string
 ```
 
 ---