@type-crafter/mcp 0.6.0 → 1.1.0

package/dist/docs/RULES_TYPES.md

@@ -0,0 +1,291 @@
+# Types Rules
+
+## Primitive Types
+
+| YAML Type                 | TypeScript | Notes               |
+| ------------------------- | ---------- | ------------------- |
+| `string`                  | `string`   | Basic string        |
+| `string` + `format: date` | `Date`     | Date object         |
+| `number`                  | `number`   | Floating point      |
+| `integer`                 | `number`   | Also becomes number |
+| `boolean`                 | `boolean`  | True/false          |
+| `unknown`                 | `unknown`  | Dynamic/any type    |
+
+```yaml
+properties:
+  name: { type: string }
+  age: { type: number }
+  isActive: { type: boolean }
+  birthDate: { type: string, format: date }
+  metadata: { type: unknown }
+```
+
+---
+
+## Object Types
+
+```yaml
+User:
+  type: object
+  description: 'User account' # Optional - becomes JSDoc
+  example: "{ id: '123' }" # Optional - becomes JSDoc
+  required:
+    - id
+    - email
+  properties:
+    id:
+      type: string
+      description: 'Unique ID' # Optional
+      example: 'user-123' # Optional
+    email:
+      type: string
+    name:
+      type: string # Not in required = nullable
+```
+
+**TypeScript:**
+
+```typescript
+/**
+ * @description User account
+ */
+export type User = {
+  /** @description Unique ID */
+  id: string;
+  email: string;
+  name: string | null;
+};
+```
+
+---
+
+## Enum Types
+
+### String Enum (Top-Level)
+
+```yaml
+Status:
+  type: string
+  enum:
+    - active
+    - inactive
+    - pending
+```
+
+**TypeScript:** `export type Status = 'active' | 'inactive' | 'pending';`
+
+### Number Enum (Top-Level)
+
+```yaml
+Priority:
+  type: number
+  enum:
+    - 1
+    - 2
+    - 3
+```
+
+**TypeScript:** `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
+
+### CRITICAL: Arrays Cannot Be Top-Level Types
+
+```yaml
+# WRONG - This will NOT work
+Tags:
+  type: array
+  items:
+    type: string
+
+# CORRECT - Arrays must be properties
+Post:
+  type: object
+  properties:
+    tags:
+      type: array
+      items:
+        type: string
+```
+
+### Array of Primitives
+
+```yaml
+properties:
+  tags:
+    type: array
+    items:
+      type: string
+```
+
+**TypeScript:** `tags: string[] | null`
+
+### Array of Objects
+
+```yaml
+properties:
+  comments:
+    type: array
+    items:
+      type: object
+      required: [text]
+      properties:
+        text: { type: string }
+        author: { type: string }
+```
+
+**TypeScript:** `comments: { text: string; author: string | null }[] | null`
+
+### Array of References
+
+```yaml
+properties:
+  posts:
+    type: array
+    items:
+      $ref: '#/types/Post'
+```
+
+**TypeScript:** `posts: 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
+        zip:
+          type: string
+```
+
+**TypeScript:**
+
+```typescript
+export type Company = {
+  id: string;
+  address: {
+    street: string;
+    city: string | null;
+    zip: string | null;
+  };
+};
+```
+
+---
+
+## Additional Properties (Hashmaps/Dictionaries)
+
+### Simple Hashmap (any values)
+
+```yaml
+Metadata:
+  type: object
+  additionalProperties: true
+```
+
+**TypeScript:** `{ [keys: string]: unknown }`
+
+### Typed Hashmap
+
+```yaml
+StringMap:
+  type: object
+  additionalProperties:
+    keyType: string
+    valueType:
+      type: string
+```
+
+**TypeScript:** `{ [keys: string]: string }`
+
+### Number Keys
+
+```yaml
+IdMap:
+  type: object
+  additionalProperties:
+    keyType: number
+    valueType:
+      $ref: '#/types/User'
+```
+
+**TypeScript:** `{ [keys: number]: User }`
+
+### Mixed: Properties + Additional
+
+```yaml
+UserWithMeta:
+  type: object
+  required:
+    - id
+  properties:
+    id:
+      type: string
+  additionalProperties:
+    keyType: string
+    valueType:
+      type: string
+```
+
+**TypeScript:**
+
+```typescript
+export type UserWithMeta = {
+  id: string;
+  [keys: string]: string;
+};
+```
+
+---
+
+## Type Definition Summary
+
+| Type         | Structure                      | Top-Level? |
+| ------------ | ------------------------------ | ---------- |
+| Object       | `type: object` + `properties`  | Yes        |
+| Enum         | `type: string/number` + `enum` | Yes        |
+| Primitive    | `type: string/number/boolean`  | Yes        |
+| Array        | `type: array` + `items`        | **NO**     |
+| Union        | `oneOf: [...]`                 | Yes        |
+| Intersection | `allOf: [...]`                 | Yes        |
+| Reference    | `$ref: '...'`                  | Yes        |

package/dist/docs/WRITING_GUIDE.md

@@ -0,0 +1,179 @@
+# Type Crafter YAML Specification Guide
+
+Type Crafter generates TypeScript types from YAML specifications. This guide teaches you how to write valid specs.
+
+---
+
+## Minimal Valid Spec
+
+```yaml
+info:
+  version: '1.0.0'
+  title: 'My API Types'
+
+types:
+  User:
+    type: object
+    required:
+      - id
+      - email
+    properties:
+      id:
+        type: string
+      email:
+        type: string
+      name:
+        type: string # Not in required = nullable (string | null)
+```
+
+**Generated TypeScript:**
+
+```typescript
+export type User = {
+  id: string;
+  email: string;
+  name: string | null;
+};
+```
+
+---
+
+## Common Mistakes - DO NOT DO THESE
+
+### 1. Using `nullable: true` - DOES NOT EXIST
+
+```yaml
+# WRONG
+name:
+  type: string
+  nullable: true # THIS PROPERTY DOES NOT EXIST
+
+# CORRECT - Omit from required array
+required:
+  - id # id is required
+  # name is NOT here, so it becomes nullable
+properties:
+  id: { type: string }
+  name: { type: string } # Generates: string | null
+```
+
+### 2. Using `optional: true` - DOES NOT EXIST
+
+```yaml
+# WRONG
+name:
+  type: string
+  optional: true # THIS PROPERTY DOES NOT EXIST
+
+# CORRECT - Use required array
+required: [id] # Only id is required
+properties:
+  id: { type: string }
+  name: { type: string } # Not in required = nullable
+```
+
+### 3. Using `?` suffix - NOT SUPPORTED
+
+```yaml
+# WRONG
+properties:
+  name?:  # INVALID SYNTAX
+    type: string
+
+# CORRECT
+required: [id]
+properties:
+  name: { type: string }
+```
+
+### 4. Top-level array types - NOT ALLOWED
+
+```yaml
+# WRONG - Arrays cannot be top-level types
+Tags:
+  type: array
+  items:
+    type: string
+
+# CORRECT - Arrays must be properties within objects
+Post:
+  type: object
+  properties:
+    tags:
+      type: array
+      items:
+        type: string
+```
+
+### 5. Using `../` in paths - WRONG
+
+```yaml
+# WRONG - Relative paths from current file
+$ref: '../common/types.yaml#/User'
+
+# CORRECT - Paths from project root (where CLI runs)
+$ref: './src/common/types.yaml#/User'
+```
+
+### 6. Using `#/` references in non-top files
+
+```yaml
+# In a file WITHOUT info section (non-top file)
+# WRONG
+$ref: '#/Cart/CartItem'
+
+# CORRECT - Must use full path
+$ref: './docs/cart.yaml#/Cart/CartItem'
+```
+
+---
+
+## Quick Reference
+
+| Concept           | YAML                         | TypeScript           |
+| ----------------- | ---------------------------- | -------------------- |
+| Required property | In `required` array          | `prop: Type`         |
+| Nullable property | NOT in `required`            | `prop: Type \| null` |
+| String            | `type: string`               | `string`             |
+| Number            | `type: number`               | `number`             |
+| Boolean           | `type: boolean`              | `boolean`            |
+| Date              | `type: string, format: date` | `Date`               |
+| Array             | `type: array, items: {...}`  | `Type[]`             |
+| Enum              | `type: string, enum: [...]`  | `'a' \| 'b'`         |
+| Union             | `oneOf: [...]`               | `A \| B`             |
+| Intersection      | `allOf: [...]`               | `A & B`              |
+
+---
+
+## Available Detail Sections
+
+Call `get-rules-section` with these topics for deep dives:
+
+| Section       | What You'll Learn                                   |
+| ------------- | --------------------------------------------------- |
+| `structure`   | Root structure, info section, types vs groupedTypes |
+| `types`       | Objects, enums, primitives, arrays, nested objects  |
+| `nullable`    | How `required` array controls nullability           |
+| `references`  | $ref syntax, top-file vs non-top-file rules         |
+| `composition` | oneOf (unions), allOf (intersections)               |
+| `patterns`    | Common patterns with full examples                  |
+
+---
+
+## Workflow
+
+1. Read this guide (you just did)
+2. Write your YAML spec
+3. Call `validate-spec` to check for errors
+4. Fix any issues
+5. Run `type-crafter generate` CLI in your project
+
+---
+
+## Key Rules Summary
+
+1. **Nullability = `required` array** - Nothing else controls this
+2. **Arrays = properties only** - Never top-level types
+3. **Paths = from project root** - Where you run the CLI
+4. **Top file = has `info` section** - Can use `#/` references
+5. **Non-top file = no `info`** - Must use full file paths for ALL references