@type-crafter/mcp 0.6.0 → 1.0.0

package/dist/docs/RULES_REFERENCES.md

@@ -0,0 +1,302 @@
+# References Rules
+
+## Reference Syntax
+
+References use `$ref` to point to other types:
+
+```yaml
+$ref: '#/types/TypeName'           # Same file, top-level type
+$ref: '#/groupedTypes/Group/Type'  # Same file, grouped type
+$ref: './path/file.yaml#/TypeName' # External file
+```
+
+---
+
+## Top File vs Non-Top File (CRITICAL)
+
+### Identifying File Type
+
+**Top File** = Has `info` section at root:
+
+```yaml
+info:
+  version: '1.0.0'
+  title: 'My Types'
+types:
+  User: { ... }
+```
+
+**Non-Top File** = No `info` section:
+
+```yaml
+# No info section here
+UserTypes:
+  User: { ... }
+  Profile: { ... }
+```
+
+### Reference Rules by File Type
+
+| File Type    | Same-File Reference                | External Reference         |
+| ------------ | ---------------------------------- | -------------------------- |
+| Top File     | `#/types/Name`                     | `'./path/file.yaml#/Name'` |
+| Non-Top File | `'./path/to/this-file.yaml#/Name'` | `'./path/file.yaml#/Name'` |
+
+---
+
+## Top File References
+
+In a file WITH `info` section:
+
+```yaml
+# types.yaml (TOP FILE)
+info:
+  version: '1.0.0'
+  title: 'API Types'
+
+types:
+  User:
+    type: object
+    properties:
+      profile:
+        $ref: '#/types/Profile' # Same-file reference
+
+  Profile:
+    type: object
+    properties:
+      bio: { type: string }
+
+groupedTypes:
+  Auth:
+    LoginResponse:
+      type: object
+      properties:
+        user:
+          $ref: '#/types/User' # Reference to types section
+        session:
+          $ref: '#/groupedTypes/Auth/Session' # Same group
+
+    Session:
+      type: object
+      properties:
+        token: { type: string }
+```
+
+---
+
+## Non-Top File References
+
+In a file WITHOUT `info` section, you MUST use full paths for EVERYTHING:
+
+```yaml
+# shared/cart.yaml (NON-TOP FILE - no info section)
+Cart:
+  CartItem:
+    type: object
+    required:
+      - product
+    properties:
+      product:
+        # MUST use full path even for same-file reference
+        $ref: './shared/cart.yaml#/Cart/Product'
+      quantity:
+        type: number
+
+  Product:
+    type: object
+    properties:
+      name: { type: string }
+      price: { type: number }
+```
+
+**Why?** Non-top files have no root context. The parser needs the full path to resolve references.
+
+### Common Mistake in Non-Top Files
+
+```yaml
+# shared/cart.yaml (NON-TOP FILE)
+Cart:
+  CartItem:
+    type: object
+    properties:
+      product:
+        $ref: '#/Cart/Product'  # WRONG! Missing file path
+
+      product:
+        $ref: './shared/cart.yaml#/Cart/Product'  # CORRECT
+```
+
+---
+
+## External File References
+
+### Path Rules
+
+1. **Paths are from project root** (where you run `type-crafter` CLI)
+2. **Always start with `./`**
+3. **Never use `../`** for relative navigation
+
+### Project Structure Example
+
+```
+my-project/           # <- Run CLI from here
+  specs/
+    api.yaml          # Top file
+    auth/
+      types.yaml      # Non-top file
+    shop/
+      cart.yaml       # Non-top file
+      product.yaml    # Non-top file
+```
+
+### References in api.yaml (top file)
+
+```yaml
+# specs/api.yaml
+info:
+  version: '1.0.0'
+  title: 'API'
+
+groupedTypes:
+  Auth:
+    $ref: './specs/auth/types.yaml#/AuthTypes'
+
+  Shop:
+    Cart:
+      $ref: './specs/shop/cart.yaml#/Cart'
+    Product:
+      $ref: './specs/shop/product.yaml#/Product'
+```
+
+### References in cart.yaml (non-top file)
+
+```yaml
+# specs/shop/cart.yaml (NON-TOP FILE)
+Cart:
+  CartItem:
+    type: object
+    properties:
+      product:
+        # Reference to another non-top file
+        $ref: './specs/shop/product.yaml#/Product/ProductInfo'
+
+      # Same-file reference - still needs full path!
+      discount:
+        $ref: './specs/shop/cart.yaml#/Cart/Discount'
+
+  Discount:
+    type: object
+    properties:
+      amount: { type: number }
+```
+
+### WRONG: Using Relative Paths
+
+```yaml
+# specs/shop/cart.yaml
+Cart:
+  CartItem:
+    type: object
+    properties:
+      product:
+        # WRONG - Don't use ../
+        $ref: '../product.yaml#/Product'
+
+        # CORRECT - From project root
+        $ref: './specs/shop/product.yaml#/Product'
+```
+
+---
+
+## Referencing Entire Groups
+
+You can reference an entire group, not just individual types:
+
+```yaml
+# api.yaml (top file)
+info:
+  version: '1.0.0'
+  title: 'API'
+
+groupedTypes:
+  # Import entire Auth group from external file
+  Auth:
+    $ref: './specs/auth/types.yaml#/AuthTypes'
+```
+
+```yaml
+# specs/auth/types.yaml (can be top or non-top)
+AuthTypes:
+  LoginRequest:
+    type: object
+    properties:
+      email: { type: string }
+
+  LoginResponse:
+    type: object
+    properties:
+      token: { type: string }
+```
+
+---
+
+## Cyclic/Self References
+
+Types can reference themselves (useful for trees, linked lists):
+
+```yaml
+TreeNode:
+  type: object
+  required:
+    - value
+  properties:
+    value:
+      type: string
+    children:
+      type: array
+      items:
+        $ref: '#/types/TreeNode' # Self-reference
+
+LinkedList:
+  type: object
+  properties:
+    value:
+      type: number
+    next:
+      $ref: '#/types/LinkedList' # Self-reference
+```
+
+**TypeScript:**
+
+```typescript
+export type TreeNode = {
+  value: string;
+  children: TreeNode[] | null;
+};
+
+export type LinkedList = {
+  value: number | null;
+  next: LinkedList | null;
+};
+```
+
+---
+
+## Reference Path Formats
+
+| Context                      | Format                      | Example                                |
+| ---------------------------- | --------------------------- | -------------------------------------- |
+| Top file, same file, types   | `#/types/Name`              | `$ref: '#/types/User'`                 |
+| Top file, same file, grouped | `#/groupedTypes/Group/Name` | `$ref: '#/groupedTypes/Auth/Token'`    |
+| Top file, external           | `'./path/file.yaml#/...'`   | `$ref: './shared/types.yaml#/User'`    |
+| Non-top file, ANY reference  | `'./path/file.yaml#/...'`   | `$ref: './this/file.yaml#/Group/Type'` |
+
+---
+
+## Checklist
+
+- [ ] Is this a top file or non-top file?
+- [ ] If non-top: Am I using full paths for ALL references?
+- [ ] Are paths from project root (not relative to current file)?
+- [ ] Do paths start with `./`?
+- [ ] No `../` in any path?

package/dist/docs/RULES_STRUCTURE.md

@@ -0,0 +1,248 @@
+# Structure Rules
+
+## Root Structure
+
+Every Type Crafter spec file has this structure:
+
+```yaml
+info:
+  version: '1.0.0' # Required - semver format
+  title: 'My Types' # Required - descriptive title
+
+types: # Optional - flat/top-level types
+  TypeName: { ... }
+
+groupedTypes: # Optional - organized into namespaces
+  GroupName:
+    TypeName: { ... }
+```
+
+**Rule:** At least ONE of `types` or `groupedTypes` is required.
+
+---
+
+## The `info` Section
+
+```yaml
+info:
+  version: '1.0.0' # String, semver format
+  title: 'API Types' # String, describes the spec
+```
+
+Both fields are **required**. Without them, the file is a "non-top file" with different reference rules.
+
+---
+
+## Top File vs Non-Top File
+
+### Top File (has `info` section)
+
+```yaml
+# top-file.yaml
+info:
+  version: '1.0.0'
+  title: 'Main Types'
+
+types:
+  User:
+    type: object
+    properties:
+      profile:
+        $ref: '#/types/Profile' # Can use #/ for same-file refs
+  Profile:
+    type: object
+    properties:
+      bio: { type: string }
+```
+
+**Rules for top files:**
+
+- Can use `#/types/TypeName` for same-file references
+- Can use `#/groupedTypes/Group/TypeName` for grouped types
+- Can be used directly with `type-crafter generate` CLI
+
+### Non-Top File (no `info` section)
+
+```yaml
+# shared/cart.yaml - NO info section
+Cart:
+  CartItem:
+    type: object
+    properties:
+      product:
+        # MUST use full path, even for same-file refs
+        $ref: './shared/cart.yaml#/Cart/Product'
+  Product:
+    type: object
+    properties:
+      name: { type: string }
+```
+
+**Rules for non-top files:**
+
+- MUST use full file paths for ALL references
+- Cannot use `#/` alone - always include file path
+- Cannot be used directly with CLI - must be referenced from a top file
+
+---
+
+## `types` Section (Flat Types)
+
+For standalone, top-level types:
+
+```yaml
+types:
+  User:
+    type: object
+    required: [id]
+    properties:
+      id: { type: string }
+
+  Status:
+    type: string
+    enum: [active, inactive]
+
+  ApiResponse:
+    oneOf:
+      - $ref: '#/types/User'
+      - type: string
+```
+
+**Generated TypeScript:**
+
+```typescript
+export type User = { id: string };
+export type Status = 'active' | 'inactive';
+export type ApiResponse = User | string;
+```
+
+---
+
+## `groupedTypes` Section (Namespaced Types)
+
+For organizing related types:
+
+```yaml
+groupedTypes:
+  Auth:
+    LoginRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email: { type: string }
+        password: { type: string }
+
+    LoginResponse:
+      type: object
+      required: [token]
+      properties:
+        token: { type: string }
+        user:
+          $ref: '#/groupedTypes/Auth/User'
+
+    User:
+      type: object
+      properties:
+        id: { type: string }
+
+  Shop:
+    Product:
+      type: object
+      properties:
+        name: { type: string }
+```
+
+**Generated TypeScript (with FolderWithFiles mode):**
+
+```
+output/
+  Auth/
+    LoginRequest.ts
+    LoginResponse.ts
+    User.ts
+  Shop/
+    Product.ts
+```
+
+---
+
+## Combining `types` and `groupedTypes`
+
+You can have both:
+
+```yaml
+info:
+  version: '1.0.0'
+  title: 'Full API'
+
+types:
+  # Shared/common types
+  Timestamp:
+    type: object
+    required: [createdAt]
+    properties:
+      createdAt: { type: string, format: date }
+
+groupedTypes:
+  # Domain-specific types
+  Users:
+    User:
+      allOf:
+        - $ref: '#/types/Timestamp'
+        - type: object
+          properties:
+            name: { type: string }
+```
+
+---
+
+## File Organization Patterns
+
+### Pattern 1: Single File (Small Projects)
+
+```
+project/
+  types.yaml      # Everything in one file
+  src/
+```
+
+### Pattern 2: Main + Shared (Medium Projects)
+
+```
+project/
+  types/
+    index.yaml    # Top file with info
+    shared.yaml   # Non-top file, referenced from index
+  src/
+```
+
+### Pattern 3: Domain Separation (Large Projects)
+
+```
+project/
+  specs/
+    api.yaml      # Top file - main entry
+    auth/
+      types.yaml  # Non-top file
+    shop/
+      cart.yaml   # Non-top file
+      product.yaml
+  src/
+```
+
+**api.yaml (top file):**
+
+```yaml
+info:
+  version: '1.0.0'
+  title: 'E-Commerce API'
+
+groupedTypes:
+  Auth:
+    $ref: './specs/auth/types.yaml#/AuthTypes'
+  Shop:
+    Cart:
+      $ref: './specs/shop/cart.yaml#/Cart'
+    Product:
+      $ref: './specs/shop/product.yaml#/Product'
+```