@type-crafter/mcp 1.2.0 → 1.2.1

package/dist/docs/RULES_TYPES.md

@@ -1,66 +1,89 @@
 # Types Rules
 
+**Only the keywords documented here are valid. Anything not listed will be rejected.**
+
+---
+
+## Valid Type Values (Complete List)
+
+These are the **only** values the `type` field accepts:
+
+| `type` value | Notes |
+| --- | --- |
+| `string` | Accepts optional `format: date` and/or `enum` |
+| `number` | Accepts optional `enum` |
+| `integer` | Same as number. Accepts optional `enum` |
+| `boolean` | |
+| `unknown` | Dynamic/untyped value |
+| `object` | Requires `properties` and/or `additionalProperties` |
+| `array` | Requires `items`. Cannot be a top-level type |
+
+**No other type values exist.** `date`, `datetime`, `float`, `int`, `any`, `null`, `void`, `map`, `list` are all invalid.
+
+---
+
+## Valid Format Values (Complete List)
+
+There is exactly **one** valid format:
+
+| `format` value | Applies to |
+| --- | --- |
+| `date` | `type: string` only |
+
+**No other format values exist.** `date-time`, `datetime`, `time`, `email`, `uri`, `uuid`, `iso8601`, `url` are all invalid.
+
+---
+
 ## 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    |
+Valid keywords on a primitive: `type`, `enum`, `format`, `description`, `example`. Nothing else.
 
 ```yaml
 properties:
-  name: { type: string }
-  age: { type: number }
-  isActive: { type: boolean }
-  birthDate: { type: string, format: date }
-  metadata: { type: unknown }
+  name:
+    type: string
+  age:
+    type: number
+  isActive:
+    type: boolean
+  birthDate:
+    type: string
+    format: date
+  metadata:
+    type: unknown
 ```
 
 ---
 
 ## Object Types
 
+Valid keywords on an object: `type`, `properties`, `required`, `additionalProperties`, `description`, `example`. Nothing else.
+
 ```yaml
 User:
   type: object
-  description: 'User account' # Optional - becomes JSDoc
-  example: "{ id: '123' }" # Optional - becomes JSDoc
+  description: 'User account'
   required:
     - id
     - email
   properties:
     id:
       type: string
-      description: 'Unique ID' # Optional
-      example: 'user-123' # Optional
+      description: 'Unique ID'
     email:
       type: string
     name:
-      type: string # Not in required = nullable
+      type: string
 ```
 
-**TypeScript:**
-
-```typescript
-/**
- * @description User account
- */
-export type User = {
-  /** @description Unique ID */
-  id: string;
-  email: string;
-  name: string | null;
-};
-```
+In this example, `name` is not in `required`, so it is nullable.
 
 ---
 
 ## Enum Types
 
+Enums use the `enum` keyword with either `type: string` or `type: number`. No other enum mechanism exists (`allowed_values`, `values`, `options`, `choices` are all invalid).
+
 ### String Enum (Top-Level)
 
 ```yaml
@@ -72,8 +95,6 @@ Status:
     - pending
 ```
 
-**TypeScript:** `export type Status = 'active' | 'inactive' | 'pending';`
-
 ### Number Enum (Top-Level)
 
 ```yaml
@@ -85,8 +106,6 @@ Priority:
     - 3
 ```
 
-**TypeScript:** `export type Priority = 1 | 2 | 3;`
-
 ### Inline Enum (Property)
 
 ```yaml
@@ -101,28 +120,22 @@ User:
         - guest
 ```
 
-**TypeScript:**
-
-```typescript
-export type User = {
-  role: ('admin' | 'user' | 'guest') | null;
-};
-```
-
 ---
 
 ## Array Types
 
-### CRITICAL: Arrays Cannot Be Top-Level Types
+Valid keywords on an array: `type`, `items`, `description`. Nothing else.
+
+### Arrays Cannot Be Top-Level Types
 
 ```yaml
-# WRONG - This will NOT work
+# WRONG - will not work
 Tags:
   type: array
   items:
     type: string
 
-# CORRECT - Arrays must be properties
+# CORRECT - arrays must be properties
 Post:
   type: object
   properties:
@@ -142,8 +155,6 @@ properties:
       type: string
 ```
 
-**TypeScript:** `tags: string[] | null`
-
 ### Array of Objects
 
 ```yaml
@@ -152,14 +163,15 @@ properties:
     type: array
     items:
       type: object
-      required: [text]
+      required:
+        - text
       properties:
-        text: { type: string }
-        author: { type: string }
+        text:
+          type: string
+        author:
+          type: string
 ```
 
-**TypeScript:** `comments: { text: string; author: string | null }[] | null`
-
 ### Array of References
 
 ```yaml
@@ -170,12 +182,12 @@ properties:
       $ref: '#/types/Post'
 ```
 
-**TypeScript:** `posts: Post[] | null`
-
 ---
 
 ## Nested Objects
 
+Each nested object follows the same keyword rules as top-level objects.
+
 ```yaml
 Company:
   type: object
@@ -198,23 +210,12 @@ Company:
           type: string
 ```
 
-**TypeScript:**
-
-```typescript
-export type Company = {
-  id: string;
-  address: {
-    street: string;
-    city: string | null;
-    zip: string | null;
-  };
-};
-```
-
 ---
 
 ## Additional Properties (Hashmaps/Dictionaries)
 
+`additionalProperties` accepts either `true` or an object with `keyType` and `valueType`. No other forms.
+
 ### Simple Hashmap (any values)
 
 ```yaml
@@ -223,8 +224,6 @@ Metadata:
   additionalProperties: true
 ```
 
-**TypeScript:** `{ [keys: string]: unknown }`
-
 ### Typed Hashmap
 
 ```yaml
@@ -236,8 +235,6 @@ StringMap:
       type: string
 ```
 
-**TypeScript:** `{ [keys: string]: string }`
-
 ### Number Keys
 
 ```yaml
@@ -249,8 +246,6 @@ IdMap:
       $ref: '#/types/User'
 ```
 
-**TypeScript:** `{ [keys: number]: User }`
-
 ### Mixed: Properties + Additional
 
 ```yaml
@@ -267,25 +262,27 @@ UserWithMeta:
       type: string
 ```
 
-**TypeScript:**
+---
 
-```typescript
-export type UserWithMeta = {
-  id: string;
-  [keys: string]: string;
-};
-```
+## Valid Keywords Summary
 
----
+| Type Kind | Valid Keywords (and ONLY these) |
+| --- | --- |
+| Primitive | `type`, `enum`, `format`, `description`, `example` |
+| Object | `type`, `properties`, `required`, `additionalProperties`, `description`, `example` |
+| Array | `type`, `items`, `description` |
+| Reference | `$ref` |
+| Union | `oneOf` |
+| Intersection | `allOf` |
 
 ## 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        |
+| Type | Structure | Top-Level? |
+| --- | --- | --- |
+| Object | `type: object` + `properties` | Yes |
+| Enum | `type: string` or `type: number` + `enum` | Yes |
+| Primitive | `type: string` / `number` / `boolean` / `unknown` | Yes |
+| Array | `type: array` + `items` | **NO** |
+| Union | `oneOf` with array | Yes |
+| Intersection | `allOf` with array | Yes |
+| Reference | `$ref` with path | Yes |

package/dist/docs/WRITING_GUIDE.md

@@ -1,147 +1,165 @@
 # Type Crafter YAML Specification Guide
 
-Type Crafter generates TypeScript types from YAML specifications. This guide teaches you how to write valid specs.
+Type Crafter generates typed code from YAML specifications. This guide is the definitive reference for what is valid. **If something is not listed here, it is not supported and will be rejected.**
 
 ---
 
-## Minimal Valid Spec
+## Complete Valid Keyword Reference
 
-```yaml
-info:
-  version: '1.0.0'
-  title: 'My API Types'
+### Root-Level Keys (ONLY these three exist)
 
-types:
-  User:
-    type: object
-    required:
-      - id
-      - email
-    properties:
-      id:
-        type: string
-      email:
-        type: string
-      name:
-        type: string # Not in required = nullable (string | null)
-```
+| Key | Required | Description |
+| --- | --- | --- |
+| `info` | Yes (for top files) | Version and title metadata |
+| `types` | At least one of `types` or `groupedTypes` | Flat/top-level type definitions |
+| `groupedTypes` | At least one of `types` or `groupedTypes` | Namespaced type definitions |
 
-**Generated TypeScript:**
+**No other root-level keys exist.** Do not add `schemas`, `definitions`, `components`, or anything else at the root.
 
-```typescript
-export type User = {
-  id: string;
-  email: string;
-  name: string | null;
-};
-```
+### The `info` Object (ONLY these two keys)
 
----
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `version` | string | Yes | Semver format, e.g. `'1.0.0'` |
+| `title` | string | Yes | Descriptive title |
 
-## Common Mistakes - DO NOT DO THESE
+**No other info keys exist.** Do not add `description`, `contact`, `license`, or anything else.
 
-### 1. Using `nullable: true` - DOES NOT EXIST
+### Valid Type Values (ONLY these)
 
-```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
-```
+| `type` value | Notes |
+| --- | --- |
+| `string` | Basic string |
+| `number` | Numeric value |
+| `integer` | Numeric value (same as number) |
+| `boolean` | True/false |
+| `unknown` | Dynamic/untyped value |
+| `object` | Must have `properties` and/or `additionalProperties` |
+| `array` | Must have `items`. **Cannot be a top-level type.** |
 
-### 2. Using `optional: true` - DOES NOT EXIST
+**No other type values exist.** Do not use `date`, `datetime`, `float`, `int`, `any`, `null`, `void`, `map`, `list`, `dict`, or anything else.
 
-```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
-```
+### Valid Format Values (ONLY one exists)
 
-### 3. Using `?` suffix - NOT SUPPORTED
+| `format` value | Applies to | Description |
+| --- | --- | --- |
+| `date` | `type: string` only | Represents a date value |
 
-```yaml
-# WRONG
-properties:
-  name?:  # INVALID SYNTAX
-    type: string
-
-# CORRECT
-required: [id]
-properties:
-  name: { type: string }
-```
+**No other format values exist.** Do not use `date-time`, `datetime`, `time`, `email`, `uri`, `url`, `uuid`, `iso8601`, or anything else.
+
+### Valid Keywords Per Type Kind
+
+#### On a primitive (`type: string | number | integer | boolean | unknown`)
+
+| Keyword | Required | Description |
+| --- | --- | --- |
+| `type` | Yes | One of: `string`, `number`, `integer`, `boolean`, `unknown` |
+| `enum` | No | Array of allowed values. Creates a union of literals. |
+| `format` | No | Only `date`, only on `type: string` |
+| `description` | No | Documentation comment |
+| `example` | No | Documentation example |
+
+#### On an object (`type: object`)
+
+| Keyword | Required | Description |
+| --- | --- | --- |
+| `type` | Yes | Must be `object` |
+| `properties` | Yes (unless `additionalProperties` only) | Map of property names to type definitions |
+| `required` | No | Array of property names that are non-nullable |
+| `additionalProperties` | No | `true` or object with `keyType` and `valueType` for hashmaps |
+| `description` | No | Documentation comment |
+| `example` | No | Documentation example |
+
+#### On an array (`type: array`)
 
-### 4. Top-level array types - NOT ALLOWED
+| Keyword | Required | Description |
+| --- | --- | --- |
+| `type` | Yes | Must be `array` |
+| `items` | Yes | Type definition for array elements |
+| `description` | No | Documentation comment |
+
+#### On a reference
+
+| Keyword | Required | Description |
+| --- | --- | --- |
+| `$ref` | Yes | Path to referenced type |
+
+#### On a composition
+
+| Keyword | Required | Description |
+| --- | --- | --- |
+| `oneOf` | Yes (for unions) | Array of type definitions. Union of types. |
+| `allOf` | Yes (for intersections) | Array of type definitions. Intersection of types. |
+
+**No other keywords exist anywhere.** Do not use `nullable`, `optional`, `extensible`, `default`, `minimum`, `maximum`, `minLength`, `maxLength`, `pattern`, `title` (on properties), `readOnly`, `writeOnly`, `deprecated`, `discriminator`, `allowed_values`, `values`, `options`, `choices`, or anything from OpenAPI/JSON Schema that is not listed above.
+
+---
+
+## Nullability: The Only Mechanism
+
+Properties **not** listed in the `required` array become nullable. This is the **only** way to make a property nullable. There is no other mechanism.
 
 ```yaml
-# WRONG - Arrays cannot be top-level types
-Tags:
-  type: array
-  items:
-    type: string
-
-# CORRECT - Arrays must be properties within objects
-Post:
+User:
   type: object
+  required:
+    - id
+    - email
   properties:
-    tags:
-      type: array
-      items:
-        type: string
+    id:
+      type: string
+    email:
+      type: string
+    name:
+      type: string
 ```
 
-### 5. Using `../` in paths - WRONG
-
-```yaml
-# WRONG - Relative paths from current file
-$ref: '../common/types.yaml#/User'
+In this example, `id` and `email` are non-nullable. `name` is not in `required`, so it is nullable.
 
-# CORRECT - Paths from project root (where CLI runs)
-$ref: './src/common/types.yaml#/User'
-```
+---
 
-### 6. Using `#/` references in non-top files
+## Minimal Valid Spec
 
 ```yaml
-# In a file WITHOUT info section (non-top file)
-# WRONG
-$ref: '#/Cart/CartItem'
+info:
+  version: '1.0.0'
+  title: 'My API Types'
 
-# CORRECT - Must use full path
-$ref: './docs/cart.yaml#/Cart/CartItem'
+types:
+  User:
+    type: object
+    required:
+      - id
+      - email
+    properties:
+      id:
+        type: string
+      email:
+        type: string
+      name:
+        type: string
 ```
 
 ---
 
 ## 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`              |
+| Concept | YAML |
+| --- | --- |
+| Required property | Listed in `required` array |
+| Nullable property | NOT listed in `required` array |
+| String | `type: string` |
+| Number | `type: number` |
+| Boolean | `type: boolean` |
+| Date | `type: string` with `format: date` |
+| Unknown | `type: unknown` |
+| String enum | `type: string` with `enum` list |
+| Number enum | `type: number` with `enum` list |
+| Array | `type: array` with `items` |
+| Union | `oneOf` with array of types |
+| Intersection | `allOf` with array of types |
+| Reference | `$ref` with path |
+| Hashmap | `additionalProperties: true` or with `keyType`/`valueType` |
 
 ---
 
@@ -149,21 +167,21 @@ $ref: './docs/cart.yaml#/Cart/CartItem'
 
 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                  |
+| 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
+2. Write your YAML spec using ONLY the keywords listed above
 3. Call `validate-spec` to check for errors
 4. Fix any issues
 5. Run `type-crafter generate` CLI in your project
@@ -172,8 +190,11 @@ Call `get-rules-section` with these topics for deep dives:
 
 ## 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
+1. **Only use keywords listed in this guide** - Anything else is invalid and will be rejected
+2. **Nullability = `required` array** - The only mechanism that controls this
+3. **Only valid format is `date`** - No other format values exist
+4. **Only valid types are `string`, `number`, `integer`, `boolean`, `unknown`, `object`, `array`**
+5. **Arrays = properties only** - Never top-level types
+6. **Paths = from project root** - Where you run the CLI
+7. **Top file = has `info` section** - Can use `#/` references
+8. **Non-top file = no `info`** - Must use full file paths for ALL references

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@type-crafter/mcp",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "MCP server for Type Crafter - generate types from YAML specifications",
   "type": "module",
   "main": "./dist/index.js",