sizuku 0.5.0 → 0.6.0

package/README.md

@@ -2,21 +2,19 @@
 
 # Sizuku
 
-**[Sizuku](https://www.npmjs.com/package/sizuku)** is a tool that generates validation schemas for Zod, Valibot, ArkType, and Effect Schema, as well as ER diagrams, from [Drizzle](https://orm.drizzle.team/) schemas.
+**[Sizuku](https://www.npmjs.com/package/sizuku)** is a CLI tool that generates validation schemas for Zod, Valibot, ArkType, and Effect Schema, as well as ER diagrams, from [Drizzle](https://orm.drizzle.team/) schemas.
 
 ## Features
 
-- 💎 Automatically generates [Zod](https://zod.dev/) schemas from your Drizzle schema
-- 🤖 Automatically generates [Valibot](https://valibot.dev/) schemas from your Drizzle schema
-- 🏹 Automatically generates [ArkType](https://arktype.io/) schemas from your Drizzle schema
-- ⚡ Automatically generates [Effect Schema](https://effect.website/docs/schema/introduction/) from your Drizzle schema
+- 💎 Generates [Zod](https://zod.dev/) schemas from your Drizzle schema
+- 🤖 Generates [Valibot](https://valibot.dev/) schemas from your Drizzle schema
+- 🏹 Generates [ArkType](https://arktype.io/) schemas from your Drizzle schema
+- ⚡ Generates [Effect Schema](https://effect.website/docs/schema/introduction/) from your Drizzle schema
 - 📊 Creates [Mermaid](https://mermaid.js.org/) ER diagrams
 - 📝 Generates [DBML](https://dbml.dbdiagram.io/) (Database Markup Language) files
-- 🖼️ Outputs ER diagrams as **PNG** images using [dbml-renderer](https://github.com/softwaretechnik-berlin/dbml-renderer)
+- 🖼️ Outputs ER diagrams as **PNG** images
 
-## Getting Started
-
-### Installation
+## Installation
 
 ```bash
 npm install -D sizuku
@@ -24,130 +22,111 @@ npm install -D sizuku
 
 ## Usage
 
-### Example
+```
+sizuku <input> -o <output> [options]
+```
+
+### Options
+
+```
+-o <path>                         Output file path
+--zod                             Generate Zod validation schema
+--valibot                         Generate Valibot validation schema
+--arktype                         Generate ArkType validation schema
+--effect                          Generate Effect Schema validation schema
+--zod-version <version>           Zod variant: 'v4' | 'mini' | '@hono/zod-openapi'
+--no-export-types                 Do not export inferred types
+--no-with-comment                 Do not add JSDoc comments
+--no-with-relation                Do not generate relation schemas
+-h, --help                        Display help message
+```
+
+### Quick Start
+
+```sh
+# Generate Zod schema
+npx sizuku db/schema.ts -o zod/index.ts --zod
+
+# Generate Valibot schema
+npx sizuku db/schema.ts -o valibot/index.ts --valibot
+
+# Generate DBML
+npx sizuku db/schema.ts -o docs/schema.dbml
+
+# Generate ER diagram PNG
+npx sizuku db/schema.ts -o docs/er.png
+
+# Generate Mermaid ER diagram
+npx sizuku db/schema.ts -o docs/ER.md
+```
 
-Prepare schema.ts:
+## Schema Annotations
+
+Add `///` comments to your Drizzle schema fields with library-specific annotations:
 
 ```ts
-import { relations } from 'drizzle-orm'
-import { mysqlTable, varchar } from 'drizzle-orm/mysql-core'
+import { relations } from "drizzle-orm";
+import { mysqlTable, varchar } from "drizzle-orm/mysql-core";
 
-export const user = mysqlTable('user', {
+export const user = mysqlTable("user", {
   /// Primary key
   /// @z.uuid()
   /// @v.pipe(v.string(), v.uuid())
   /// @a."string.uuid"
   /// @e.Schema.UUID
-  id: varchar('id', { length: 36 }).primaryKey(),
+  id: varchar("id", { length: 36 }).primaryKey(),
   /// Display name
   /// @z.string().min(1).max(50)
   /// @v.pipe(v.string(), v.minLength(1), v.maxLength(50))
   /// @a."1 <= string <= 50"
   /// @e.Schema.String.pipe(Schema.minLength(1), Schema.maxLength(50))
-  name: varchar('name', { length: 50 }).notNull(),
-})
+  name: varchar("name", { length: 50 }).notNull(),
+});
 
-/// @relation user.id post.userId one-to-many
-export const post = mysqlTable('post', {
-  /// Primary key
+export const post = mysqlTable("post", {
   /// @z.uuid()
   /// @v.pipe(v.string(), v.uuid())
   /// @a."string.uuid"
   /// @e.Schema.UUID
-  id: varchar('id', { length: 36 }).primaryKey(),
-  /// Article title
+  id: varchar("id", { length: 36 }).primaryKey(),
   /// @z.string().min(1).max(100)
   /// @v.pipe(v.string(), v.minLength(1), v.maxLength(100))
   /// @a."1 <= string <= 100"
   /// @e.Schema.String.pipe(Schema.minLength(1), Schema.maxLength(100))
-  title: varchar('title', { length: 100 }).notNull(),
-  /// Body content (no length limit)
-  /// @z.string().min(1).max(65535)
-  /// @v.pipe(v.string(), v.minLength(1), v.maxLength(65535))
-  /// @a."1 <= string <= 65535"
-  /// @e.Schema.String.pipe(Schema.minLength(1), Schema.maxLength(65535))
-  content: varchar('content', { length: 65535 }).notNull(),
-  /// Foreign key referencing User.id
+  title: varchar("title", { length: 100 }).notNull(),
   /// @z.uuid()
   /// @v.pipe(v.string(), v.uuid())
   /// @a."string.uuid"
   /// @e.Schema.UUID
-  userId: varchar('user_id', { length: 36 }).notNull(),
-})
+  userId: varchar("user_id", { length: 36 })
+    .notNull()
+    .references(() => user.id),
+});
 
 export const userRelations = relations(user, ({ many }) => ({
   posts: many(post),
-}))
+}));
 
 export const postRelations = relations(post, ({ one }) => ({
   user: one(user, {
     fields: [post.userId],
     references: [user.id],
   }),
-}))
+}));
 ```
 
-Prepare sizuku.config.ts:
+Annotations are optional. Generators work without them (DBML/Mermaid don't need annotations at all).
 
-```ts
-import { defineConfig } from 'sizuku/config'
-
-export default defineConfig({
-  input: 'db/schema.ts',
-  zod: {
-    output: 'zod/index.ts',
-    comment: true,
-    type: true,
-    zod: 'v4',
-    relation: true,
-  },
-  valibot: {
-    output: 'valibot/index.ts',
-    comment: true,
-    type: true,
-    relation: true,
-  },
-  arktype: {
-    output: 'arktype/index.ts',
-    comment: true,
-    type: true,
-    relation: true,
-  },
-  effect: {
-    output: 'effect/index.ts',
-    comment: true,
-    type: true,
-    relation: true,
-  },
-  mermaid: {
-    output: 'mermaid-er/ER.md',
-  },
-  dbml: {
-    output: 'docs/schema.dbml',
-  },
-})
-```
+## Output Examples
 
-Run Sizuku:
+### Zod
 
 ```sh
-npx sizuku
+npx sizuku db/schema.ts -o zod/index.ts --zod
 ```
 
-Output:
-```
-💧 Generated Zod schema at: zod/index.ts
-💧 Generated Valibot schema at: valibot/index.ts
-💧 Generated ArkType schema at: arktype/index.ts
-💧 Generated Effect schema at: effect/index.ts
-💧 Generated Mermaid ER at: mermaid-er/ER.md
-💧 Generated DBML at: docs/schema.dbml
-```
-
-### Zod
-
 ```ts
-import * as z from 'zod'
+import * as z from "zod";
 
 export const UserSchema = z.object({
   /**
@@ -158,44 +137,26 @@ export const UserSchema = z.object({
    * Display name
    */
   name: z.string().min(1).max(50),
-})
-
-export type User = z.infer<typeof UserSchema>
-
-export const PostSchema = z.object({
-  /**
-   * Primary key
-   */
-  id: z.uuid(),
-  /**
-   * Article title
-   */
-  title: z.string().min(1).max(100),
-  /**
-   * Body content (no length limit)
-   */
-  content: z.string().min(1).max(65535),
-  /**
-   * Foreign key referencing User.id
-   */
-  userId: z.uuid(),
-})
-
-export type Post = z.infer<typeof PostSchema>
-
-export const UserRelationsSchema = z.object({ ...UserSchema.shape, posts: z.array(PostSchema) })
+});
 
-export type UserRelations = z.infer<typeof UserRelationsSchema>
+export type User = z.infer<typeof UserSchema>;
 
-export const PostRelationsSchema = z.object({ ...PostSchema.shape, user: UserSchema })
+export const UserRelationsSchema = z.object({
+  ...UserSchema.shape,
+  posts: z.array(PostSchema),
+});
 
-export type PostRelations = z.infer<typeof PostRelationsSchema>
+export type UserRelations = z.infer<typeof UserRelationsSchema>;
 ```
 
 ### Valibot
 
+```sh
+npx sizuku db/schema.ts -o valibot/index.ts --valibot
+```
+
 ```ts
-import * as v from 'valibot'
+import * as v from "valibot";
 
 export const UserSchema = v.object({
   /**
@@ -206,195 +167,131 @@ export const UserSchema = v.object({
    * Display name
    */
   name: v.pipe(v.string(), v.minLength(1), v.maxLength(50)),
-})
-
-export type User = v.InferInput<typeof UserSchema>
-
-export const PostSchema = v.object({
-  /**
-   * Primary key
-   */
-  id: v.pipe(v.string(), v.uuid()),
-  /**
-   * Article title
-   */
-  title: v.pipe(v.string(), v.minLength(1), v.maxLength(100)),
-  /**
-   * Body content (no length limit)
-   */
-  content: v.pipe(v.string(), v.minLength(1), v.maxLength(65535)),
-  /**
-   * Foreign key referencing User.id
-   */
-  userId: v.pipe(v.string(), v.uuid()),
-})
-
-export type Post = v.InferInput<typeof PostSchema>
-
-export const UserRelationsSchema = v.object({ ...UserSchema.entries, posts: v.array(PostSchema) })
+});
 
-export type UserRelations = v.InferInput<typeof UserRelationsSchema>
+export type User = v.InferOutput<typeof UserSchema>;
 
-export const PostRelationsSchema = v.object({ ...PostSchema.entries, user: UserSchema })
+export const UserRelationsSchema = v.object({
+  ...UserSchema.entries,
+  posts: v.array(PostSchema),
+});
 
-export type PostRelations = v.InferInput<typeof PostRelationsSchema>
+export type UserRelations = v.InferOutput<typeof UserRelationsSchema>;
 ```
 
 ### ArkType
 
+```sh
+npx sizuku db/schema.ts -o arktype/index.ts --arktype
+```
+
 ```ts
-import { type } from 'arktype'
+import { type } from "arktype";
 
 export const UserSchema = type({
-  /** Primary key */
-  id: 'string.uuid',
-  /** Display name */
-  name: '1 <= string <= 50',
-})
-
-export type User = typeof UserSchema.infer
-
-export const PostSchema = type({
-  /** Primary key */
-  id: 'string.uuid',
-  /** Article title */
-  title: '1 <= string <= 100',
-  /** Body content (no length limit) */
-  content: '1 <= string <= 65535',
-  /** Foreign key referencing User.id */
-  userId: 'string.uuid',
-})
-
-export type Post = typeof PostSchema.infer
+  /**
+   * Primary key
+   */
+  id: "string.uuid",
+  /**
+   * Display name
+   */
+  name: "1 <= string <= 50",
+});
+
+export type User = typeof UserSchema.infer;
 ```
 
 ### Effect Schema
 
+```sh
+npx sizuku db/schema.ts -o effect/index.ts --effect
+```
+
 ```ts
-import { Schema } from 'effect'
+import { Schema } from "effect";
 
 export const UserSchema = Schema.Struct({
-  /** Primary key */
+  /**
+   * Primary key
+   */
   id: Schema.UUID,
-  /** Display name */
+  /**
+   * Display name
+   */
   name: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(50)),
-})
+});
 
-export type User = Schema.Schema.Type<typeof UserSchema>
+export type UserEncoded = typeof UserSchema.Encoded;
+```
 
-export const PostSchema = Schema.Struct({
-  /** Primary key */
-  id: Schema.UUID,
-  /** Article title */
-  title: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(100)),
-  /** Body content (no length limit) */
-  content: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(65535)),
-  /** Foreign key referencing User.id */
-  userId: Schema.UUID,
-})
-
-export type Post = Schema.Schema.Type<typeof PostSchema>
+### DBML
+
+```sh
+npx sizuku db/schema.ts -o docs/schema.dbml
+```
+
+```dbml
+Table user {
+  id varchar [pk, note: 'Primary key']
+  name varchar [note: 'Display name']
+}
+
+Table post {
+  id varchar [pk]
+  title varchar
+  userId varchar
+}
+
+Ref post_userId_user_id_fk: post.userId > user.id
 ```
 
 ### Mermaid ER
 
+```sh
+npx sizuku db/schema.ts -o docs/ER.md
+```
+
 ```mermaid
 erDiagram
     user ||--}| post : "(id) - (userId)"
     user {
-        varchar id "(PK) Primary key"
+        varchar id PK "Primary key"
         varchar name "Display name"
     }
     post {
-        varchar id "(PK) Primary key"
-        varchar title "Article title"
-        varchar content "Body content (no length limit)"
-        varchar userId "Foreign key referencing User.id"
+        varchar id PK
+        varchar title
+        varchar userId FK
     }
 ```
 
-### DBML
+## Relation Detection
 
-The `dbml` generator outputs a DBML schema file or ER diagram PNG depending on the file extension:
+Sizuku detects relations from three sources:
 
-- `.dbml` extension: outputs a DBML schema file
-- `.png` extension: outputs an ER diagram PNG image
+### 1. `.references()` chain
 
-```dbml
-Table user {
-  id varchar [pk, note: 'Primary key']
-  name varchar [note: 'Display name']
-}
-
-Table post {
-  id varchar [pk, note: 'Primary key']
-  title varchar [note: 'Article title']
-  content varchar [note: 'Body content (no length limit)']
-  userId varchar [note: 'Foreign key referencing User.id']
-}
-
-Ref post_userId_user_id_fk: post.userId > user.id
+```ts
+userId: varchar("user_id").references(() => user.id);
 ```
 
-## Configuration
-
-```typescript
-import { defineConfig } from 'sizuku/config'
-
-export default defineConfig({
-  // Input: Path to Drizzle schema file (must end with .ts)
-  input: 'db/schema.ts',
-
-  // Zod Schema Generator
-  zod: {
-    output: 'zod/index.ts',       // Output file path (must end with .ts)
-    comment: true,                 // Include schema documentation (default: false)
-    type: true,                    // Generate TypeScript types (default: false)
-    zod: 'v4',                     // Zod import: 'v4' | 'mini' | '@hono/zod-openapi' (default: 'v4')
-    relation: true,                // Generate relation schemas (default: false)
-  },
-
-  // Valibot Schema Generator
-  valibot: {
-    output: 'valibot/index.ts',
-    comment: true,
-    type: true,
-    relation: true,
-  },
-
-  // ArkType Schema Generator
-  arktype: {
-    output: 'arktype/index.ts',
-    comment: true,
-    type: true,
-    relation: true,                // Generate relation schemas (default: false)
-  },
-
-  // Effect Schema Generator
-  effect: {
-    output: 'effect/index.ts',
-    comment: true,
-    type: true,
-    relation: true,                // Generate relation schemas (default: false)
-  },
-
-  // Mermaid ER Diagram Generator
-  mermaid: {
-    output: 'mermaid-er/ER.md',    // Output file path
-  },
-
-  // DBML / ER Diagram PNG Generator
-  // Use .dbml extension for DBML text, .png extension for ER diagram image
-  dbml: {
-    output: 'docs/schema.dbml',    // Output file path (must end with .dbml or .png)
-  },
-})
+### 2. `foreignKey()` constraint
+
+```ts
+export const post = pgTable('post', { ... }, (t) => ({
+  fk: foreignKey({ columns: [t.userId], foreignColumns: [user.id] }),
+}))
 ```
 
-### ⚠️ WARNING: Potential Breaking Changes Without Notice
+### 3. `relations()` block
 
-This package is in active development and may introduce breaking changes without prior notice.
+```ts
+export const postRelations = relations(post, ({ one }) => ({
+  user: one(user, { fields: [post.userId], references: [user.id] }),
+}));
+```
 
 ## License
 
-Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/sizuku?tab=MIT-1-ov-file) for more information.
+Distributed under the MIT License. See [LICENSE](https://github.com/nakita628/sizuku?tab=MIT-1-ov-file) for more information.