@type-crafter/mcp 0.1.0

package/src/SPEC_RULES.md

@@ -0,0 +1,970 @@
+# Type Crafter YAML Specification Rules
+
+Complete guide for writing Type Crafter YAML specifications and understanding TypeScript generation.
+
+---
+
+## Table of Contents
+
+- [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)
+
+---
+
+## 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`)**
+
+```yaml
+User:
+  type: object
+  required:
+    - id # Will be: id: string
+    - email # Will be: email: string
+  properties:
+    id:
+      type: string
+    email:
+      type: string
+    name:
+      type: string # NOT in required → becomes: string | null
+    age:
+      type: number # NOT in required → becomes: number | null
+```
+
+**TypeScript Output:**
+
+```typescript
+export type User = {
+  id: string; // Required - no null
+  email: string; // Required - no null
+  name: string | null; // Optional - nullable
+  age: number | null; // Optional - nullable
+};
+```
+
+### Rules
+
+1. ✅ **In `required` array** → `Type`
+2. ✅ **NOT in `required` array** → `Type | null`
+3. ✅ **No `required` array** → All properties are `Type | null`
+4. ❌ **Empty `required: []`** → All properties are `Type | null`
+
+---
+
+## 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
+
+### Local References (Same File)
+
+```yaml
+# Reference to top-level type
+Post:
+  type: object
+  properties:
+    author:
+      $ref: '#/types/User'
+
+# Reference to grouped type
+Comment:
+  type: object
+  properties:
+    author:
+      $ref: '#/groupedTypes/Auth/UserProfile'
+```
+
+**Reference Format:**
+
+- Top-level: `#/types/TypeName`
+- Grouped: `#/groupedTypes/GroupName/TypeName`
+
+### External File References
+
+**⚠️ IMPORTANT: Paths are from project root, not relative to current file**
+
+```yaml
+# Reference to type in another file (path from project root)
+Post:
+  type: object
+  properties:
+    author:
+      $ref: './src/types/users.yaml#/User'
+
+# Reference to grouped type in another file
+Comment:
+  type: object
+  properties:
+    metadata:
+      $ref: './docs/specs/common.yaml#/SharedTypes/Metadata'
+
+# Real-world example: Shopify cart referencing cart item
+SCart:
+  type: object
+  properties:
+    items:
+      type: array
+      items:
+        $ref: './docs/specs/Cart.yaml#/Cart/SCartItem'
+```
+
+**Reference Format:**
+
+- **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`
+
+**Path Rules:**
+
+- 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`
+
+### 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!