@type-crafter/mcp 0.6.0 → 1.1.0

package/dist/docs/RULES_COMPOSITION.md

@@ -0,0 +1,343 @@
+# Composition Rules
+
+## oneOf - Union Types
+
+Creates TypeScript union: `TypeA | TypeB | TypeC`
+
+Use when a value can be ONE of several types.
+
+### Basic Union
+
+```yaml
+Response:
+  oneOf:
+    - $ref: '#/types/SuccessResponse'
+    - $ref: '#/types/ErrorResponse'
+```
+
+**TypeScript:** `export type Response = SuccessResponse | ErrorResponse;`
+
+### Union with Primitives
+
+```yaml
+Value:
+  oneOf:
+    - type: string
+    - type: number
+    - type: boolean
+```
+
+**TypeScript:** `export type Value = string | number | boolean;`
+
+### Union with Inline Objects
+
+```yaml
+Result:
+  oneOf:
+    - type: object
+      required: [data]
+      properties:
+        data: { type: string }
+    - type: object
+      required: [error]
+      properties:
+        error: { type: string }
+```
+
+**TypeScript:**
+
+```typescript
+export type Result = { data: string } | { error: string };
+```
+
+### Union with Arrays
+
+```yaml
+Items:
+  oneOf:
+    - type: string
+    - type: array
+      items:
+        type: string
+```
+
+**TypeScript:** `export type Items = string | string[];`
+
+### Union with Enums
+
+```yaml
+Status:
+  oneOf:
+    - type: string
+      enum: [pending, loading]
+    - type: string
+      enum: [success, error]
+```
+
+**TypeScript:** `export type Status = 'pending' | 'loading' | 'success' | 'error';`
+
+### Complex Union Example
+
+```yaml
+ApiResponse:
+  oneOf:
+    - $ref: '#/types/User'
+    - $ref: '#/types/Error'
+    - type: string
+    - type: number
+    - type: string
+      enum: [pending, loading]
+    - type: object
+      properties:
+        status: { type: string }
+    - type: array
+      items:
+        type: string
+    - type: array
+      items:
+        $ref: '#/types/User'
+```
+
+**TypeScript:**
+
+```typescript
+export type ApiResponse =
+  | User
+  | Error
+  | string
+  | number
+  | ('pending' | 'loading')
+  | { status: string | null }
+  | string[]
+  | User[];
+```
+
+---
+
+## allOf - Intersection/Merge Types
+
+Creates TypeScript intersection: `TypeA & TypeB & TypeC`
+
+Use to combine multiple types into one (all properties merged).
+
+### Basic Intersection
+
+```yaml
+AdminUser:
+  allOf:
+    - $ref: '#/types/BaseUser'
+    - $ref: '#/types/AdminPermissions'
+```
+
+**TypeScript:** `export type AdminUser = BaseUser & AdminPermissions;`
+
+### Intersection with Inline Extension
+
+```yaml
+types:
+  BaseUser:
+    type: object
+    required: [id]
+    properties:
+      id: { type: string }
+
+  ExtendedUser:
+    allOf:
+      - $ref: '#/types/BaseUser'
+      - type: object
+        required: [email]
+        properties:
+          email: { type: string }
+          name: { type: string }
+```
+
+**TypeScript:**
+
+```typescript
+export type BaseUser = {
+  id: string;
+};
+
+export type ExtendedUser = BaseUser & {
+  email: string;
+  name: string | null;
+};
+```
+
+### Multiple Inheritance Pattern
+
+```yaml
+types:
+  Timestamped:
+    type: object
+    required: [createdAt, updatedAt]
+    properties:
+      createdAt: { type: string, format: date }
+      updatedAt: { type: string, format: date }
+
+  Identifiable:
+    type: object
+    required: [id]
+    properties:
+      id: { type: string }
+
+  User:
+    allOf:
+      - $ref: '#/types/Timestamped'
+      - $ref: '#/types/Identifiable'
+      - type: object
+        required: [email]
+        properties:
+          email: { type: string }
+          name: { type: string }
+```
+
+**TypeScript:**
+
+```typescript
+export type User = Timestamped &
+  Identifiable & {
+    email: string;
+    name: string | null;
+  };
+
+// Effectively:
+// {
+//   createdAt: Date;
+//   updatedAt: Date;
+//   id: string;
+//   email: string;
+//   name: string | null;
+// }
+```
+
+---
+
+## Combining oneOf and allOf
+
+You can nest composition operators:
+
+### Union of Intersections
+
+```yaml
+Response:
+  oneOf:
+    - allOf:
+        - $ref: '#/types/BaseResponse'
+        - type: object
+          properties:
+            data: { $ref: '#/types/User' }
+    - allOf:
+        - $ref: '#/types/BaseResponse'
+        - type: object
+          properties:
+            error: { type: string }
+```
+
+### Intersection with Union Property
+
+```yaml
+Entity:
+  allOf:
+    - $ref: '#/types/BaseEntity'
+    - type: object
+      properties:
+        status:
+          oneOf:
+            - type: string
+              enum: [active, inactive]
+            - type: number
+```
+
+---
+
+## Common Patterns
+
+### Discriminated Union (Tagged Union)
+
+```yaml
+types:
+  SuccessResult:
+    type: object
+    required: [type, data]
+    properties:
+      type:
+        type: string
+        enum: [success]
+      data: { type: unknown }
+
+  ErrorResult:
+    type: object
+    required: [type, message]
+    properties:
+      type:
+        type: string
+        enum: [error]
+      message: { type: string }
+
+  Result:
+    oneOf:
+      - $ref: '#/types/SuccessResult'
+      - $ref: '#/types/ErrorResult'
+```
+
+**TypeScript:**
+
+```typescript
+export type Result = { type: 'success'; data: unknown } | { type: 'error'; message: string };
+```
+
+### Mixin Pattern
+
+```yaml
+types:
+  WithTimestamps:
+    type: object
+    required: [createdAt]
+    properties:
+      createdAt: { type: string, format: date }
+      updatedAt: { type: string, format: date }
+
+  WithSoftDelete:
+    type: object
+    properties:
+      deletedAt: { type: string, format: date }
+
+  User:
+    allOf:
+      - $ref: '#/types/WithTimestamps'
+      - $ref: '#/types/WithSoftDelete'
+      - type: object
+        required: [id, email]
+        properties:
+          id: { type: string }
+          email: { type: string }
+```
+
+### Nullable Union
+
+```yaml
+MaybeUser:
+  oneOf:
+    - $ref: '#/types/User'
+    - type: object
+      properties: {} # Empty object as "null" representation
+```
+
+---
+
+## Rules Summary
+
+| Operator | TypeScript    | Use Case                      |
+| -------- | ------------- | ----------------------------- |
+| `oneOf`  | `A \| B \| C` | Value is one of several types |
+| `allOf`  | `A & B & C`   | Combine/merge multiple types  |
+
+### What Can Be in oneOf/allOf
+
+- `$ref` to other types
+- `type: object` with properties
+- `type: string/number/boolean` primitives
+- `type: string` with `enum`
+- `type: array` with items
+- Nested `oneOf` or `allOf`

package/dist/docs/RULES_NULLABLE.md

@@ -0,0 +1,293 @@
+# Nullable Types Rules
+
+## The Core Rule
+
+**Properties NOT in the `required` array become `Type | null` in TypeScript.**
+
+This is the ONLY way to control nullability. No other mechanism exists.
+
+---
+
+## 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
+```
+
+---
+
+## What DOES Work
+
+```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
+  properties:
+    id:
+      type: string
+    email:
+      type: string
+    name:
+      type: string
+    age:
+      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)
+};
+```
+
+---
+
+## Scenarios
+
+### 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
+export type User = {
+  id: string;
+  email: string;
+  name: string;
+  age: number;
+};
+```
+
+### Some Properties Required
+
+```yaml
+User:
+  type: object
+  required:
+    - id
+    - email
+  properties:
+    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;
+};
+```
+
+### No Properties Required (All Nullable)
+
+```yaml
+User:
+  type: object
+  # No required array at all
+  properties:
+    id: { type: string }
+    email: { type: string }
+    name: { type: string }
+```
+
+```typescript
+export type User = {
+  id: string | null;
+  email: string | null;
+  name: string | null;
+};
+```
+
+### Empty Required Array (All Nullable)
+
+```yaml
+User:
+  type: object
+  required: [] # Explicit empty array
+  properties:
+    id: { type: string }
+```
+
+```typescript
+export type User = {
+  id: string | null;
+};
+```
+
+---
+
+## Nested Objects
+
+Each nested object has its OWN `required` array:
+
+```yaml
+User:
+  type: object
+  required:
+    - id
+    - profile # profile object is required
+  properties:
+    id:
+      type: string
+    profile:
+      type: object
+      required:
+        - name # name inside profile is required
+      properties:
+        name:
+          type: string
+        bio:
+          type: string # NOT required inside profile
+```
+
+```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
+  };
+};
+```
+
+---
+
+## Arrays
+
+The array itself follows `required` rules. Items have their own rules:
+
+```yaml
+Post:
+  type: object
+  required:
+    - id
+    - tags # tags array is required
+  properties:
+    id:
+      type: string
+    tags:
+      type: array
+      items:
+        type: string
+    comments: # NOT in required
+      type: array
+      items:
+        type: object
+        required:
+          - text
+        properties:
+          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;
+};
+```
+
+---
+
+## References
+
+Referenced types maintain their own nullability. The reference's position in `required` controls if the reference itself is nullable:
+
+```yaml
+types:
+  Profile:
+    type: object
+    required: [bio]
+    properties:
+      bio: { type: string }
+      avatar: { type: string } # nullable inside Profile
+
+  User:
+    type: object
+    required:
+      - id
+      - mainProfile # This reference is required
+    properties:
+      id:
+        type: string
+      mainProfile:
+        $ref: '#/types/Profile'
+      backupProfile: # NOT in required
+        $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
+};
+```
+
+---
+
+## 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 |