@type-crafter/mcp 1.2.0 → 1.3.0

package/dist/docs/RULES_NULLABLE.md

@@ -1,48 +1,25 @@
 # Nullable Types Rules
 
-## The Core Rule
+## The Only Mechanism
 
-**Properties NOT in the `required` array become `Type | null` in TypeScript.**
+**The `required` array is the only way to control nullability.** No other mechanism exists in Type Crafter.
 
-This is the ONLY way to control nullability. No other mechanism exists.
+- Properties listed in `required` -> non-nullable
+- Properties NOT listed in `required` -> nullable
+- No `required` array at all -> all properties are nullable
 
----
-
-## What Does NOT Work
-
-```yaml
-# WRONG: nullable property does NOT exist
-name:
-  type: string
-  nullable: true      # INVALID - will be ignored or error
-
-# WRONG: optional property does NOT exist
-name:
-  type: string
-  optional: true      # INVALID - will be ignored or error
-
-# WRONG: ? suffix is NOT supported
-properties:
-  name?:              # INVALID SYNTAX
-    type: string
-
-# WRONG: Array type syntax
-name:
-  type: [string, null]  # INVALID - not supported
-```
+There are no keywords like `nullable`, `optional`, `nillable`, or any other annotation. There is no `?` suffix syntax. There is no `type: [string, null]` syntax. The `required` array is it.
 
 ---
 
-## What DOES Work
+## How It Works
 
 ```yaml
 User:
   type: object
-  required: # This array controls EVERYTHING
-    - id # id is required -> string
-    - email # email is required -> string
-    # name is NOT here -> string | null
-    # age is NOT here -> number | null
+  required:
+    - id
+    - email
   properties:
     id:
       type: string
@@ -54,16 +31,7 @@ User:
       type: number
 ```
 
-**TypeScript:**
-
-```typescript
-export type User = {
-  id: string; // Required
-  email: string; // Required
-  name: string | null; // Nullable (not in required)
-  age: number | null; // Nullable (not in required)
-};
-```
+In this example, `id` and `email` are in `required` so they are non-nullable. `name` and `age` are not in `required` so they are nullable.
 
 ---
 
@@ -80,20 +48,17 @@ User:
     - name
     - age
   properties:
-    id: { type: string }
-    email: { type: string }
-    name: { type: string }
-    age: { type: number }
+    id:
+      type: string
+    email:
+      type: string
+    name:
+      type: string
+    age:
+      type: number
 ```
 
-```typescript
-export type User = {
-  id: string;
-  email: string;
-  name: string;
-  age: number;
-};
-```
+All four properties are non-nullable.
 
 ### Some Properties Required
 
@@ -104,56 +69,46 @@ User:
     - id
     - email
   properties:
-    id: { type: string }
-    email: { type: string }
-    name: { type: string }
-    age: { type: number }
+    id:
+      type: string
+    email:
+      type: string
+    name:
+      type: string
+    age:
+      type: number
 ```
 
-```typescript
-export type User = {
-  id: string;
-  email: string;
-  name: string | null;
-  age: number | null;
-};
-```
+`id` and `email` are non-nullable. `name` and `age` are nullable.
 
 ### No Properties Required (All Nullable)
 
 ```yaml
 User:
   type: object
-  # No required array at all
   properties:
-    id: { type: string }
-    email: { type: string }
-    name: { type: string }
+    id:
+      type: string
+    email:
+      type: string
+    name:
+      type: string
 ```
 
-```typescript
-export type User = {
-  id: string | null;
-  email: string | null;
-  name: string | null;
-};
-```
+All three properties are nullable.
 
 ### Empty Required Array (All Nullable)
 
 ```yaml
 User:
   type: object
-  required: [] # Explicit empty array
+  required: []
   properties:
-    id: { type: string }
+    id:
+      type: string
 ```
 
-```typescript
-export type User = {
-  id: string | null;
-};
-```
+`id` is nullable.
 
 ---
 
@@ -166,31 +121,22 @@ User:
   type: object
   required:
     - id
-    - profile # profile object is required
+    - profile
   properties:
     id:
       type: string
     profile:
       type: object
       required:
-        - name # name inside profile is required
+        - name
       properties:
         name:
           type: string
         bio:
-          type: string # NOT required inside profile
+          type: string
 ```
 
-```typescript
-export type User = {
-  id: string;
-  profile: {
-    // profile is required (non-null)
-    name: string; // name is required inside profile
-    bio: string | null; // bio is nullable inside profile
-  };
-};
-```
+`profile` is non-nullable (it's in User's `required`). Inside profile, `name` is non-nullable (it's in profile's `required`), but `bio` is nullable (not in profile's `required`).
 
 ---
 
@@ -203,7 +149,7 @@ Post:
   type: object
   required:
     - id
-    - tags # tags array is required
+    - tags
   properties:
     id:
       type: string
@@ -211,30 +157,20 @@ Post:
       type: array
       items:
         type: string
-    comments: # NOT in required
+    comments:
       type: array
       items:
         type: object
         required:
           - text
         properties:
-          text: { type: string }
-          author: { type: string }
+          text:
+            type: string
+          author:
+            type: string
 ```
 
-```typescript
-export type Post = {
-  id: string;
-  tags: string[]; // Required array
-  comments:
-    | {
-        // Nullable array
-        text: string;
-        author: string | null;
-      }[]
-    | null;
-};
-```
+`tags` is non-nullable (in `required`). `comments` is nullable (not in `required`). Inside each comment item, `text` is non-nullable but `author` is nullable.
 
 ---
 
@@ -246,48 +182,40 @@ Referenced types maintain their own nullability. The reference's position in `re
 types:
   Profile:
     type: object
-    required: [bio]
+    required:
+      - bio
     properties:
-      bio: { type: string }
-      avatar: { type: string } # nullable inside Profile
+      bio:
+        type: string
+      avatar:
+        type: string
 
   User:
     type: object
     required:
       - id
-      - mainProfile # This reference is required
+      - mainProfile
     properties:
       id:
         type: string
       mainProfile:
         $ref: '#/types/Profile'
-      backupProfile: # NOT in required
+      backupProfile:
         $ref: '#/types/Profile'
 ```
 
-```typescript
-export type Profile = {
-  bio: string;
-  avatar: string | null;
-};
-
-export type User = {
-  id: string;
-  mainProfile: Profile; // Required reference
-  backupProfile: Profile | null; // Nullable reference
-};
-```
+`mainProfile` is non-nullable (in `required`). `backupProfile` is nullable (not in `required`). Inside Profile, `bio` is non-nullable and `avatar` is nullable regardless of where Profile is referenced.
 
 ---
 
 ## Quick Reference
 
-| Scenario                     | Result                                                |
-| ---------------------------- | ----------------------------------------------------- |
-| Property in `required` array | `Type`                                                |
-| Property NOT in `required`   | `Type \| null`                                        |
-| No `required` array          | All properties `Type \| null`                         |
-| `required: []` (empty)       | All properties `Type \| null`                         |
-| Nested object                | Uses its own `required` array                         |
-| Array items                  | Follow their own `required` rules                     |
-| References                   | Reference position in `required` controls nullability |
+| Scenario | Result |
+| --- | --- |
+| Property in `required` array | Non-nullable |
+| Property NOT in `required` | Nullable |
+| No `required` array | All properties nullable |
+| `required: []` (empty) | All properties nullable |
+| Nested object | Uses its own `required` array |
+| Array items | Follow their own `required` rules |
+| References | Reference position in `required` controls nullability |

package/dist/docs/RULES_PATTERNS.md

@@ -38,14 +38,6 @@ types:
       - $ref: '#/types/ErrorResponse'
 ```
 
-**TypeScript:**
-
-```typescript
-export type ApiResponse =
-  | { success: boolean; data: unknown }
-  | { success: boolean; error: string; code: number | null };
-```
-
 ---
 
 ## Pattern 2: Paginated Response
@@ -88,9 +80,12 @@ types:
       - id
       - email
     properties:
-      id: { type: string }
-      email: { type: string }
-      name: { type: string }
+      id:
+        type: string
+      email:
+        type: string
+      name:
+        type: string
 ```
 
 ---
@@ -120,9 +115,12 @@ types:
           - id
           - email
         properties:
-          id: { type: string }
-          email: { type: string }
-          name: { type: string }
+          id:
+            type: string
+          email:
+            type: string
+          name:
+            type: string
 
   Post:
     allOf:
@@ -132,19 +130,12 @@ types:
           - id
           - title
         properties:
-          id: { type: string }
-          title: { type: string }
-          content: { type: string }
-```
-
-**TypeScript:**
-
-```typescript
-export type User = Timestamps & {
-  id: string;
-  email: string;
-  name: string | null;
-};
+          id:
+            type: string
+          title:
+            type: string
+          content:
+            type: string
 ```
 
 ---
@@ -224,17 +215,6 @@ types:
           $ref: '#/types/MenuItem'
 ```
 
-**TypeScript:**
-
-```typescript
-export type MenuItem = {
-  id: string;
-  label: string;
-  url: string | null;
-  children: MenuItem[] | null;
-};
-```
-
 ---
 
 ## Pattern 6: Form Request/Response
@@ -294,9 +274,12 @@ types:
       - id
       - email
     properties:
-      id: { type: string }
-      email: { type: string }
-      name: { type: string }
+      id:
+        type: string
+      email:
+        type: string
+      name:
+        type: string
 ```
 
 ---
@@ -312,10 +295,15 @@ types:
       - type
       - createdAt
     properties:
-      id: { type: string }
-      type: { type: string }
-      createdAt: { type: string, format: date }
-      read: { type: boolean }
+      id:
+        type: string
+      type:
+        type: string
+      createdAt:
+        type: string
+        format: date
+      read:
+        type: boolean
 
   EmailNotification:
     allOf:
@@ -327,9 +315,12 @@ types:
         properties:
           type:
             type: string
-            enum: [email]
-          subject: { type: string }
-          body: { type: string }
+            enum:
+              - email
+          subject:
+            type: string
+          body:
+            type: string
 
   SmsNotification:
     allOf:
@@ -341,9 +332,12 @@ types:
         properties:
           type:
             type: string
-            enum: [sms]
-          message: { type: string }
-          phoneNumber: { type: string }
+            enum:
+              - sms
+          message:
+            type: string
+          phoneNumber:
+            type: string
 
   PushNotification:
     allOf:
@@ -354,9 +348,12 @@ types:
         properties:
           type:
             type: string
-            enum: [push]
-          title: { type: string }
-          body: { type: string }
+            enum:
+              - push
+          title:
+            type: string
+          body:
+            type: string
 
   Notification:
     oneOf:
@@ -378,21 +375,30 @@ types:
       - port
       - database
     properties:
-      host: { type: string }
-      port: { type: number }
-      database: { type: string }
-      username: { type: string }
-      password: { type: string }
-      ssl: { type: boolean }
+      host:
+        type: string
+      port:
+        type: number
+      database:
+        type: string
+      username:
+        type: string
+      password:
+        type: string
+      ssl:
+        type: boolean
 
   CacheConfig:
     type: object
     required:
       - enabled
     properties:
-      enabled: { type: boolean }
-      ttl: { type: number }
-      maxSize: { type: number }
+      enabled:
+        type: boolean
+      ttl:
+        type: number
+      maxSize:
+        type: number
 
   AppConfig:
     type: object
@@ -402,7 +408,10 @@ types:
     properties:
       environment:
         type: string
-        enum: [development, staging, production]
+        enum:
+          - development
+          - staging
+          - production
       database:
         $ref: '#/types/DatabaseConfig'
       cache:
@@ -446,18 +455,24 @@ groupedTypes:
   UserTypes:
     User:
       type: object
-      required: [id, email]
+      required:
+        - id
+        - email
       properties:
-        id: { type: string }
-        email: { type: string }
+        id:
+          type: string
+        email:
+          type: string
         profile:
           $ref: '#/groupedTypes/UserTypes/UserProfile'
 
     UserProfile:
       type: object
       properties:
-        name: { type: string }
-        avatar: { type: string }
+        name:
+          type: string
+        avatar:
+          type: string
 ```
 
 ---
@@ -466,7 +481,6 @@ groupedTypes:
 
 ```yaml
 types:
-  # String to string map
   Headers:
     type: object
     additionalProperties:
@@ -474,12 +488,10 @@ types:
       valueType:
         type: string
 
-  # String to any map
   Metadata:
     type: object
     additionalProperties: true
 
-  # ID to entity map
   UserCache:
     type: object
     additionalProperties:
@@ -487,13 +499,13 @@ types:
       valueType:
         $ref: '#/types/User'
 
-  # Mixed: fixed properties + dynamic
   Response:
     type: object
     required:
       - status
     properties:
-      status: { type: number }
+      status:
+        type: number
     additionalProperties:
       keyType: string
       valueType:
@@ -501,16 +513,9 @@ types:
 
   User:
     type: object
-    required: [id]
+    required:
+      - id
     properties:
-      id: { type: string }
-```
-
-**TypeScript:**
-
-```typescript
-export type Headers = { [keys: string]: string };
-export type Metadata = { [keys: string]: unknown };
-export type UserCache = { [keys: string]: User };
-export type Response = { status: number; [keys: string]: unknown };
+      id:
+        type: string
 ```