@contractspec/bundle.library 0.0.0-canary-20260206014742

package/dist/components/docs/guides/GuideImportExistingCodebasesPage.js

@@ -0,0 +1,679 @@
+import { StudioPrompt } from "../shared/StudioPrompt.js";
+import { AlertCircle, ChevronRight, FileCode, Scan, Settings } from "lucide-react";
+import { CodeBlock } from "@contractspec/lib.design-system";
+import { jsx, jsxs } from "react/jsx-runtime";
+import Link from "@contractspec/lib.ui-link";
+
+//#region src/components/docs/guides/GuideImportExistingCodebasesPage.tsx
+const supportedFrameworks = [
+	{
+		name: "NestJS",
+		flag: "nestjs",
+		description: "Controllers, decorators, DTOs"
+	},
+	{
+		name: "Express",
+		flag: "express",
+		description: "Router methods, middleware"
+	},
+	{
+		name: "Fastify",
+		flag: "fastify",
+		description: "Route definitions, schemas"
+	},
+	{
+		name: "Hono",
+		flag: "hono",
+		description: "Route handlers, validators"
+	},
+	{
+		name: "Elysia",
+		flag: "elysia",
+		description: "Type-safe routes, schemas"
+	},
+	{
+		name: "tRPC",
+		flag: "trpc",
+		description: "Procedure definitions"
+	},
+	{
+		name: "Next.js",
+		flag: "next-api",
+		description: "API routes (app/api, pages/api)"
+	}
+];
+function GuideImportExistingCodebasesPage() {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "space-y-8",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-3",
+				children: [/* @__PURE__ */ jsx("h1", {
+					className: "text-4xl font-bold",
+					children: "Import Existing Codebases"
+				}), /* @__PURE__ */ jsx("p", {
+					className: "text-muted-foreground text-lg",
+					children: "Convert your existing API endpoints into ContractSpec contracts. Auto-detect frameworks, extract schemas, and generate spec-first definitions from your code."
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "card-subtle space-y-4 p-6",
+				children: [/* @__PURE__ */ jsx("h2", {
+					className: "text-2xl font-bold",
+					children: "What you'll learn"
+				}), /* @__PURE__ */ jsxs("ul", {
+					className: "text-muted-foreground space-y-2 text-sm",
+					children: [
+						/* @__PURE__ */ jsx("li", { children: "How to import existing API endpoints as ContractSpec contracts." }),
+						/* @__PURE__ */ jsx("li", { children: "Framework-specific patterns and auto-detection." }),
+						/* @__PURE__ */ jsx("li", { children: "Customizing imports with scopes, dry-run, and output options." }),
+						/* @__PURE__ */ jsx("li", { children: "Registering imported contracts and adding handlers." })
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "space-y-6",
+				children: [
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "Why import existing code?"
+							}),
+							/* @__PURE__ */ jsx("p", {
+								className: "text-muted-foreground text-sm",
+								children: "Instead of writing contracts from scratch, the import command extracts endpoint patterns from your existing codebase. This gives you:"
+							}),
+							/* @__PURE__ */ jsxs("ul", {
+								className: "text-muted-foreground list-disc space-y-1 pl-5 text-sm",
+								children: [
+									/* @__PURE__ */ jsx("li", { children: "Instant spec coverage for existing APIs" }),
+									/* @__PURE__ */ jsx("li", { children: "Type-safe schemas derived from your existing types" }),
+									/* @__PURE__ */ jsx("li", { children: "A foundation to iterate and refine contracts" }),
+									/* @__PURE__ */ jsx("li", { children: "Gradual adoption without rewriting code" })
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [/* @__PURE__ */ jsx("h2", {
+							className: "text-2xl font-bold",
+							children: "Supported frameworks"
+						}), /* @__PURE__ */ jsx("div", {
+							className: "grid gap-3 md:grid-cols-2 lg:grid-cols-3",
+							children: supportedFrameworks.map((fw) => /* @__PURE__ */ jsxs("div", {
+								className: "flex items-start gap-3 rounded-lg border border-white/10 p-4",
+								children: [/* @__PURE__ */ jsx(FileCode, {
+									className: "text-violet-400",
+									size: 18
+								}), /* @__PURE__ */ jsxs("div", {
+									className: "space-y-1",
+									children: [
+										/* @__PURE__ */ jsx("h3", {
+											className: "font-semibold",
+											children: fw.name
+										}),
+										/* @__PURE__ */ jsx("p", {
+											className: "text-muted-foreground text-xs",
+											children: fw.description
+										}),
+										/* @__PURE__ */ jsxs("code", {
+											className: "text-xs text-violet-400",
+											children: ["--framework ", fw.flag]
+										})
+									]
+								})]
+							}, fw.flag))
+						})]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "1) Quick start"
+							}),
+							/* @__PURE__ */ jsx("p", {
+								className: "text-muted-foreground text-sm",
+								children: "Run the import command to auto-detect your framework and extract endpoints:"
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "bash",
+								filename: "import-quickstart",
+								code: `# Auto-detect framework and import all endpoints
+contractspec import ./src
+
+# Preview what would be imported (dry-run)
+contractspec import ./src --dry-run
+
+# Force a specific framework
+contractspec import ./src --framework nestjs`
+							}),
+							/* @__PURE__ */ jsx("p", {
+								className: "text-muted-foreground text-sm",
+								children: "Expected output: A summary of endpoints found, schemas extracted, and files generated."
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [/* @__PURE__ */ jsx("h2", {
+							className: "text-2xl font-bold",
+							children: "2) Framework-specific patterns"
+						}), /* @__PURE__ */ jsx("p", {
+							className: "text-muted-foreground text-sm",
+							children: "The import command recognizes these patterns in each framework:"
+						})]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsxs("h3", {
+								className: "flex items-center gap-2 text-xl font-semibold",
+								children: [/* @__PURE__ */ jsx(Scan, {
+									size: 18,
+									className: "text-blue-400"
+								}), "NestJS"]
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "typescript",
+								filename: "src/users/users.controller.ts (before)",
+								code: `@Controller('users')
+export class UsersController {
+  @Get(':id')
+  async getUser(@Param('id') id: string): Promise<UserDto> {
+    return this.usersService.findOne(id);
+  }
+
+  @Post()
+  @UseGuards(AuthGuard)
+  async createUser(@Body() dto: CreateUserDto): Promise<UserDto> {
+    return this.usersService.create(dto);
+  }
+}`
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Detected: ",
+									/* @__PURE__ */ jsx("code", { children: "@Controller" }),
+									", ",
+									/* @__PURE__ */ jsx("code", { children: "@Get" }),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", { children: "@Post" }),
+									", ",
+									/* @__PURE__ */ jsx("code", { children: "@Body" }),
+									", ",
+									/* @__PURE__ */ jsx("code", { children: "@Param" }),
+									",",
+									" ",
+									/* @__PURE__ */ jsx("code", { children: "@UseGuards" }),
+									" decorators."
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsxs("h3", {
+								className: "flex items-center gap-2 text-xl font-semibold",
+								children: [/* @__PURE__ */ jsx(Scan, {
+									size: 18,
+									className: "text-green-400"
+								}), "Express"]
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "typescript",
+								filename: "src/routes/users.ts (before)",
+								code: `const router = express.Router();
+
+router.get('/users/:id', async (req, res) => {
+  const user = await getUserById(req.params.id);
+  res.json(user);
+});
+
+router.post('/users', validateBody(CreateUserSchema), async (req, res) => {
+  const user = await createUser(req.body);
+  res.status(201).json(user);
+});`
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Detected: ",
+									/* @__PURE__ */ jsx("code", { children: "router.get" }),
+									", ",
+									/* @__PURE__ */ jsx("code", { children: "router.post" }),
+									", validation middleware, Zod schemas."
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsxs("h3", {
+								className: "flex items-center gap-2 text-xl font-semibold",
+								children: [/* @__PURE__ */ jsx(Scan, {
+									size: 18,
+									className: "text-purple-400"
+								}), "Next.js API Routes"]
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "typescript",
+								filename: "app/api/users/[id]/route.ts (before)",
+								code: `export async function GET(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  const user = await getUserById(params.id);
+  return Response.json(user);
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const user = await createUser(body);
+  return Response.json(user, { status: 201 });
+}`
+							}),
+							/* @__PURE__ */ jsxs("p", {
+								className: "text-muted-foreground text-sm",
+								children: [
+									"Detected: ",
+									/* @__PURE__ */ jsx("code", { children: "GET" }),
+									", ",
+									/* @__PURE__ */ jsx("code", { children: "POST" }),
+									" exports in",
+									" ",
+									/* @__PURE__ */ jsx("code", { children: "app/api/**/route.ts" }),
+									" and ",
+									/* @__PURE__ */ jsx("code", { children: "pages/api/**/*.ts" }),
+									"."
+								]
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "3) Understanding generated contracts"
+							}),
+							/* @__PURE__ */ jsx("p", {
+								className: "text-muted-foreground text-sm",
+								children: "The import command generates ContractSpec operations with TODO placeholders for fields it cannot infer:"
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "typescript",
+								filename: ".contractspec/generated/users.operation.ts",
+								code: `import { defineQuery, defineCommand } from "@contractspec/lib.contracts";
+import { SchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
+
+export const GetUserQuery = defineQuery({
+  meta: {
+    key: "users.get",
+    version: "1.0.0",
+    description: "TODO: Add description",
+    stability: "draft",
+    owners: ["TODO"],
+    tags: ["users"],
+  },
+  io: {
+    input: new SchemaModel({
+      name: "GetUserInput",
+      fields: {
+        id: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+    output: new SchemaModel({
+      name: "GetUserOutput",
+      fields: {
+        // TODO: Add output fields based on your UserDto
+        id: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: "user" }, // Inferred from @UseGuards
+  transport: {
+    rest: { method: "GET", path: "/users/:id" },
+  },
+});
+
+export const CreateUserCommand = defineCommand({
+  meta: {
+    key: "users.create",
+    version: "1.0.0",
+    description: "TODO: Add description",
+    stability: "draft",
+    owners: ["TODO"],
+    tags: ["users"],
+  },
+  io: {
+    input: new SchemaModel({
+      name: "CreateUserInput",
+      fields: {
+        // TODO: Add fields from CreateUserDto
+      },
+    }),
+    output: new SchemaModel({
+      name: "CreateUserOutput",
+      fields: {
+        id: { type: ScalarTypeEnum.String(), isOptional: false },
+      },
+    }),
+  },
+  policy: { auth: "admin" },
+  transport: {
+    rest: { method: "POST", path: "/users" },
+  },
+});`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "4) Customizing imports"
+							}),
+							/* @__PURE__ */ jsxs("div", {
+								className: "flex items-center gap-2",
+								children: [/* @__PURE__ */ jsx(Settings, {
+									size: 18,
+									className: "text-violet-400"
+								}), /* @__PURE__ */ jsx("h3", {
+									className: "text-lg font-semibold",
+									children: "Available options"
+								})]
+							}),
+							/* @__PURE__ */ jsx("div", {
+								className: "overflow-x-auto",
+								children: /* @__PURE__ */ jsxs("table", {
+									className: "w-full text-sm",
+									children: [/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", {
+										className: "border-b border-white/10",
+										children: [
+											/* @__PURE__ */ jsx("th", {
+												className: "py-2 pr-4 text-left",
+												children: "Option"
+											}),
+											/* @__PURE__ */ jsx("th", {
+												className: "py-2 pr-4 text-left",
+												children: "Description"
+											}),
+											/* @__PURE__ */ jsx("th", {
+												className: "py-2 text-left",
+												children: "Example"
+											})
+										]
+									}) }), /* @__PURE__ */ jsxs("tbody", {
+										className: "text-muted-foreground",
+										children: [
+											/* @__PURE__ */ jsxs("tr", {
+												className: "border-b border-white/5",
+												children: [
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: /* @__PURE__ */ jsx("code", { children: "--scope" })
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: "Limit to specific directories"
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2",
+														children: /* @__PURE__ */ jsx("code", { children: "--scope src/users src/auth" })
+													})
+												]
+											}),
+											/* @__PURE__ */ jsxs("tr", {
+												className: "border-b border-white/5",
+												children: [
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: /* @__PURE__ */ jsx("code", { children: "--framework" })
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: "Force a specific framework"
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2",
+														children: /* @__PURE__ */ jsx("code", { children: "--framework express" })
+													})
+												]
+											}),
+											/* @__PURE__ */ jsxs("tr", {
+												className: "border-b border-white/5",
+												children: [
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: /* @__PURE__ */ jsx("code", { children: "--output" })
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: "Output directory"
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2",
+														children: /* @__PURE__ */ jsx("code", { children: "--output ./contracts" })
+													})
+												]
+											}),
+											/* @__PURE__ */ jsxs("tr", {
+												className: "border-b border-white/5",
+												children: [
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: /* @__PURE__ */ jsx("code", { children: "--dry-run" })
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: "Preview without writing files"
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2",
+														children: /* @__PURE__ */ jsx("code", { children: "--dry-run" })
+													})
+												]
+											}),
+											/* @__PURE__ */ jsxs("tr", {
+												className: "border-b border-white/5",
+												children: [
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: /* @__PURE__ */ jsx("code", { children: "--analyze" })
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2 pr-4",
+														children: "Analysis only, no code generation"
+													}),
+													/* @__PURE__ */ jsx("td", {
+														className: "py-2",
+														children: /* @__PURE__ */ jsx("code", { children: "--analyze" })
+													})
+												]
+											}),
+											/* @__PURE__ */ jsxs("tr", { children: [
+												/* @__PURE__ */ jsx("td", {
+													className: "py-2 pr-4",
+													children: /* @__PURE__ */ jsx("code", { children: "--json" })
+												}),
+												/* @__PURE__ */ jsx("td", {
+													className: "py-2 pr-4",
+													children: "Output as JSON for scripting"
+												}),
+												/* @__PURE__ */ jsx("td", {
+													className: "py-2",
+													children: /* @__PURE__ */ jsx("code", { children: "--json" })
+												})
+											] })
+										]
+									})]
+								})
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "bash",
+								filename: "import-options",
+								code: `# Import only specific modules
+contractspec import ./src --scope src/users src/orders
+
+# Preview with analysis
+contractspec import ./src --dry-run --analyze
+
+# Output to custom directory
+contractspec import ./src --output ./src/contracts/generated
+
+# Get JSON for CI/scripting
+contractspec import ./src --json > import-result.json`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [
+							/* @__PURE__ */ jsx("h2", {
+								className: "text-2xl font-bold",
+								children: "5) Registering imported contracts"
+							}),
+							/* @__PURE__ */ jsx("p", {
+								className: "text-muted-foreground text-sm",
+								children: "After import, register contracts and add handlers:"
+							}),
+							/* @__PURE__ */ jsx(CodeBlock, {
+								language: "typescript",
+								filename: "src/contracts/registry.ts",
+								code: `import {
+  OperationSpecRegistry,
+  installOp,
+} from "@contractspec/lib.contracts/operations";
+import {
+  GetUserQuery,
+  CreateUserCommand,
+} from "./.contractspec/generated/users.operation";
+
+export const registry = new OperationSpecRegistry();
+
+// Add handlers to imported operations
+installOp(registry, GetUserQuery, async (input) => {
+  const user = await db.user.findUnique({ where: { id: input.id } });
+  return user;
+});
+
+installOp(registry, CreateUserCommand, async (input) => {
+  const user = await db.user.create({ data: input });
+  return { id: user.id };
+});`
+							})
+						]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [/* @__PURE__ */ jsx("h2", {
+							className: "text-2xl font-bold",
+							children: "6) After importing"
+						}), /* @__PURE__ */ jsxs("ol", {
+							className: "text-muted-foreground list-decimal space-y-2 pl-5 text-sm",
+							children: [
+								/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Review generated contracts" }), " — Check the TODO placeholders and fill in descriptions, owners, and tags."] }),
+								/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Refine schemas" }), " — Add proper types, validation rules, and error definitions."] }),
+								/* @__PURE__ */ jsxs("li", { children: [
+									/* @__PURE__ */ jsx("strong", { children: "Run validation" }),
+									" —",
+									" ",
+									/* @__PURE__ */ jsx("code", { children: "contractspec validate" }),
+									" to ensure contracts are valid."
+								] }),
+								/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Register and wire handlers" }), " — Connect contracts to your existing business logic."] }),
+								/* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("strong", { children: "Iterate" }), " — The imported contracts are a starting point. Refine them as your spec matures."] })
+							]
+						})]
+					}),
+					/* @__PURE__ */ jsxs("div", {
+						className: "space-y-3",
+						children: [/* @__PURE__ */ jsxs("h2", {
+							className: "flex items-center gap-2 text-2xl font-bold",
+							children: [/* @__PURE__ */ jsx(AlertCircle, {
+								size: 20,
+								className: "text-yellow-400"
+							}), "Troubleshooting"]
+						}), /* @__PURE__ */ jsxs("div", {
+							className: "space-y-4",
+							children: [
+								/* @__PURE__ */ jsxs("div", {
+									className: "card-subtle space-y-2 p-4",
+									children: [/* @__PURE__ */ jsx("h3", {
+										className: "font-semibold",
+										children: "Framework not detected"
+									}), /* @__PURE__ */ jsxs("p", {
+										className: "text-muted-foreground text-sm",
+										children: [
+											"Use ",
+											/* @__PURE__ */ jsx("code", { children: "--framework <name>" }),
+											" to force a specific framework. Check that your entry files follow standard patterns."
+										]
+									})]
+								}),
+								/* @__PURE__ */ jsxs("div", {
+									className: "card-subtle space-y-2 p-4",
+									children: [/* @__PURE__ */ jsx("h3", {
+										className: "font-semibold",
+										children: "Missing schemas"
+									}), /* @__PURE__ */ jsxs("p", {
+										className: "text-muted-foreground text-sm",
+										children: [
+											"Schema inference works best with explicit types. If using",
+											" ",
+											/* @__PURE__ */ jsx("code", { children: "any" }),
+											" or dynamic types, you'll see TODO placeholders. Fill them in manually."
+										]
+									})]
+								}),
+								/* @__PURE__ */ jsxs("div", {
+									className: "card-subtle space-y-2 p-4",
+									children: [/* @__PURE__ */ jsx("h3", {
+										className: "font-semibold",
+										children: "Partial imports"
+									}), /* @__PURE__ */ jsxs("p", {
+										className: "text-muted-foreground text-sm",
+										children: [
+											"Some endpoints may not be detected if they use unconventional patterns. Use ",
+											/* @__PURE__ */ jsx("code", { children: "--analyze" }),
+											" to see what was found, then add missing contracts manually."
+										]
+									})]
+								})
+							]
+						})]
+					}),
+					/* @__PURE__ */ jsx(StudioPrompt, {
+						title: "Want automated contract evolution?",
+						body: "Studio monitors your codebase and suggests contract updates when your API changes, keeping specs and code in sync."
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center gap-4 pt-4",
+				children: [/* @__PURE__ */ jsxs(Link, {
+					href: "/docs/guides/spec-validation-and-typing",
+					className: "btn-primary",
+					children: ["Next: Spec validation + typing ", /* @__PURE__ */ jsx(ChevronRight, { size: 16 })]
+				}), /* @__PURE__ */ jsx(Link, {
+					href: "/docs/guides",
+					className: "btn-ghost",
+					children: "Back to guides"
+				})]
+			})
+		]
+	});
+}
+
+//#endregion
+export { GuideImportExistingCodebasesPage };
+//# sourceMappingURL=GuideImportExistingCodebasesPage.js.map