peta-docs 0.3.0

package/dist/hono/index.mjs

@@ -0,0 +1,435 @@
+import { n as setDefaultScanner } from "../spec-Bobwv7gP.mjs";
+import { validator } from "hono/validator";
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Hono } from "hono";
+//#region src/hono/route.ts
+const OPENAPI_META = Symbol("openapi-meta");
+/** Parse a comma-separated string into a trimmed, non-empty array. */
+function parseCommaSeparated(value) {
+	return value ? value.split(",").map((s) => s.trim()).filter(Boolean) : [];
+}
+/**
+* Validate a value against a Standard Schema.
+* Returns the validated value, or calls `onError` and returns a Response.
+*/
+async function validateOrError(schema, value, c, onError) {
+	const result = await schema["~standard"].validate(value);
+	if (Array.isArray(result)) return onError(result, c);
+	const r = result;
+	if (r.issues) return onError([...r.issues], c);
+	if ("value" in r && r.value !== void 0) return r.value;
+	return value;
+}
+let onValidationError = (issues, c) => {
+	return c.json({
+		error: "Validation failed",
+		issues
+	}, 400);
+};
+/** @deprecated Use {@link RouteBuilder.onValidationError} on the route chain instead. Per-route handlers take precedence over the global handler. */
+function setOnValidationError(handler) {
+	const prev = onValidationError;
+	onValidationError = handler;
+	return () => {
+		onValidationError = prev;
+	};
+}
+const onResponseValidationError = (issues, c) => {
+	return c.json({
+		error: "Response validation failed",
+		issues
+	}, 500);
+};
+/** @internal */
+function createValidator(target, schema, onError) {
+	return validator(target, async (value, c) => {
+		const validated = await validateOrError(schema, value, c, onError);
+		if (validated instanceof Response) return validated;
+		return validated;
+	});
+}
+/**
+* Creates a middleware that checks for the presence of auth credentials.
+*
+* This is a mechanism-level guard — it verifies that the expected auth
+* header/cookie exists, but does NOT verify the credential itself
+* (e.g., JWT validity, session data). The app's own middleware or
+* handler is responsible for identity verification.
+*/
+function authGuard(schemes) {
+	return async (c, next) => {
+		for (const scheme of schemes) {
+			if (scheme === "bearerAuth") {
+				if (!c.req.header("Authorization")?.startsWith("Bearer ")) return c.json({ error: "unauthorized" }, 401);
+			}
+			if (scheme === "sessionAuth" || scheme === "cookieAuth") {
+				if (!c.req.header("Cookie")?.includes("session=")) return c.json({ error: "unauthorized" }, 401);
+			}
+		}
+		return await next();
+	};
+}
+var RouteBuilder = class RouteBuilder {
+	_config = { responses: {} };
+	static VALIDATOR_MAP = [
+		["requestBody", "json"],
+		["params", "param"],
+		["headers", "header"]
+	];
+	summary(s) {
+		this._config.summary = s;
+		return this;
+	}
+	description(s) {
+		this._config.description = s;
+		return this;
+	}
+	operationId(s) {
+		this._config.operationId = s;
+		return this;
+	}
+	tags(...t) {
+		this._config.tags = t;
+		return this;
+	}
+	deprecated(d = true) {
+		this._config.deprecated = d;
+		return this;
+	}
+	requestBody(schema) {
+		this._config.requestBody = schema;
+		return this;
+	}
+	query(schema) {
+		this._config.query = schema;
+		return this;
+	}
+	params(schema) {
+		this._config.params = schema;
+		return this;
+	}
+	headers(schema) {
+		this._config.headers = schema;
+		return this;
+	}
+	response(status, value) {
+		this._config.responses[String(status)] = value;
+		return this;
+	}
+	auth(scheme = "bearerAuth") {
+		const acc = this._config.security ?? [];
+		acc.push(scheme);
+		this._config.security = acc;
+		return this;
+	}
+	filter(name, schema, options) {
+		const acc = this._config.filters ?? [];
+		acc.push({
+			name,
+			schema,
+			operators: options?.operators ?? ["eq"]
+		});
+		this._config.filters = acc;
+		return this;
+	}
+	sort(fields) {
+		this._config.sort = fields;
+		return this;
+	}
+	include(relations) {
+		this._config.include = relations;
+		return this;
+	}
+	fieldsets(resources) {
+		this._config.fieldsets = resources;
+		return this;
+	}
+	onValidationError(handler) {
+		this._config.onValidationError = handler;
+		return this;
+	}
+	onResponseValidationError(handler) {
+		this._config.onResponseValidationError = handler;
+		return this;
+	}
+	paginated(options) {
+		this._config.pagination = {
+			maxLimit: options?.maxLimit ?? 100,
+			defaultLimit: options?.defaultLimit ?? 20
+		};
+		return this;
+	}
+	handle(handler) {
+		const onError = this._config.onValidationError ?? onValidationError;
+		const validators = this.buildValidators(onError);
+		if (this._config.security?.length) validators.unshift(authGuard(this._config.security));
+		const routeConfig = this.buildRouteConfig(handler);
+		const wrapped = this.composeHandler(validators, handler);
+		return this.attachRouteMeta(wrapped, routeConfig);
+	}
+	buildValidators(onError) {
+		const validators = [];
+		const querySchema = this._config.query;
+		const filters = this._config.filters;
+		const sortFields = this._config.sort;
+		const includeFields = this._config.include;
+		const fieldsetResources = this._config.fieldsets;
+		const pag = this._config.pagination;
+		if (querySchema || filters?.length || sortFields || includeFields || fieldsetResources || pag) validators.push(validator("query", async (value, c) => {
+			let merged = {};
+			const raw = value;
+			if (querySchema) {
+				const validated = await validateOrError(querySchema, value, c, onError);
+				if (validated instanceof Response) return validated;
+				merged = {
+					...merged,
+					...validated
+				};
+			}
+			if (filters) for (const filter of filters) for (const op of filter.operators) {
+				const paramName = op === "eq" ? filter.name : `${filter.name}__${op}`;
+				const val = raw[paramName];
+				if (val === void 0) continue;
+				if (op === "in") {
+					const items = parseCommaSeparated(val);
+					const validatedItems = [];
+					for (const item of items) {
+						const validated = await validateOrError(filter.schema, item, c, onError);
+						if (validated instanceof Response) return validated;
+						validatedItems.push(validated);
+					}
+					merged[paramName] = validatedItems;
+				} else {
+					const validated = await validateOrError(filter.schema, val, c, onError);
+					if (validated instanceof Response) return validated;
+					merged[paramName] = validated;
+				}
+			}
+			if (sortFields) {
+				const sortVal = raw.sort;
+				if (sortVal !== void 0) {
+					const parts = parseCommaSeparated(sortVal);
+					const allowed = new Set(sortFields.flatMap((f) => [f, `-${f}`]));
+					for (const part of parts) if (!allowed.has(part)) return onError([{ message: `Invalid sort field "${part}". Allowed: ${[...allowed].join(", ")}` }], c);
+					merged.sort = parts;
+				}
+			}
+			const includeFields = this._config.include;
+			if (includeFields) {
+				const rawInclude = raw.include;
+				if (rawInclude !== void 0) {
+					const parts = parseCommaSeparated(rawInclude);
+					const allowed = new Set(includeFields);
+					for (const part of parts) if (!allowed.has(part)) return onError([{ message: `Invalid include "${part}". Allowed: ${[...allowed].join(", ")}` }], c);
+					merged.include = parts;
+				}
+			}
+			const fieldsetResources = this._config.fieldsets;
+			if (fieldsetResources) for (const resource of fieldsetResources) {
+				const paramName = `fields[${resource}]`;
+				const val = raw[paramName];
+				if (val !== void 0 && typeof val !== "string") return onError([{ message: `"${paramName}" must be a string` }], c);
+				if (val !== void 0) merged[paramName] = val;
+			}
+			if (pag) {
+				const page = Math.floor(Number(raw.page ?? "1"));
+				const limit = Math.min(pag.maxLimit, Math.max(1, Math.floor(Number(raw.limit ?? String(pag.defaultLimit)))));
+				merged.page = Number.isFinite(page) && page >= 1 ? page : 1;
+				merged.limit = Number.isFinite(limit) ? limit : pag.defaultLimit;
+				merged.offset = (merged.page - 1) * merged.limit;
+			}
+			return merged;
+		}));
+		for (const [key, target] of RouteBuilder.VALIDATOR_MAP) {
+			const schema = this._config[key];
+			if (schema != null) validators.push(createValidator(target, schema, onError));
+		}
+		return validators;
+	}
+	buildRouteConfig(handler) {
+		return {
+			...this._config,
+			responses: this._config.responses,
+			pagination: this._config.pagination,
+			filters: this._config.filters,
+			sort: this._config.sort,
+			include: this._config.include,
+			fieldsets: this._config.fieldsets,
+			security: this._config.security,
+			handler
+		};
+	}
+	composeHandler(validators, handler) {
+		return async (c, _next) => {
+			const run = async (i) => {
+				if (i < validators.length) return await validators[i](c, run.bind(null, i + 1)) ?? void 0;
+				const response = await handler(c) ?? void 0;
+				if (response) {
+					const onError = this._config.onResponseValidationError ?? onResponseValidationError;
+					return await this.validateResponse(response, c, onError) ?? void 0;
+				}
+				return response;
+			};
+			return run(0);
+		};
+	}
+	async validateResponse(response, c, onError) {
+		if (!(response.headers.get("content-type") ?? "").includes("application/json")) return response;
+		if (response.status === 204) return response;
+		const schema = this._config.responses[String(response.status)];
+		if (!schema || typeof schema !== "object" && typeof schema !== "function" || !("~standard" in schema)) return response;
+		try {
+			const validated = await validateOrError(schema, await response.clone().json(), c, onError);
+			if (validated instanceof Response) return validated;
+			return response;
+		} catch {
+			return response;
+		}
+	}
+	attachRouteMeta(handler, config) {
+		Object.defineProperty(handler, OPENAPI_META, {
+			value: config,
+			writable: false
+		});
+		return handler;
+	}
+};
+function route() {
+	return new RouteBuilder();
+}
+function getRouteMeta(handler) {
+	if (typeof handler !== "function") return void 0;
+	return handler[OPENAPI_META];
+}
+//#endregion
+//#region src/hono/scanner.ts
+function routeProp(obj, key) {
+	if (obj == null) return void 0;
+	return obj[key];
+}
+/**
+* Scans a Hono app instance and extracts route metadata.
+*
+* Relies on Hono's internal `app.routes` array. If that structure
+* changes in a future Hono version, this scanner will warn and
+* return an empty array.
+*/
+const honoScanner = { scan(app) {
+	const entries = [];
+	const raw = routeProp(app, "routes");
+	if (!Array.isArray(raw)) {
+		console.warn(`[peta-docs] honoScanner: expected app.routes to be an array, got ${typeof raw}. Is this a Hono app? Provide a custom RouteScanner for other frameworks.`);
+		return entries;
+	}
+	for (const r of raw) {
+		const handler = routeProp(r, "handler");
+		const meta = typeof handler === "function" ? getRouteMeta(handler) : void 0;
+		if (meta) {
+			const path = typeof routeProp(r, "path") === "string" ? String(routeProp(r, "path")) : "";
+			const method = typeof routeProp(r, "method") === "string" ? String(routeProp(r, "method")) : "";
+			entries.push({
+				path,
+				method,
+				config: meta
+			});
+		}
+	}
+	return entries;
+} };
+//#endregion
+//#region src/hono/loader.ts
+/**
+* Convert a directory name to a URL path segment.
+*   `[id]` → `:id`
+*   `[postId]` → `:postId`
+*   `pets` → `pets`
+*/
+function toPathSegment(entry) {
+	const match = entry.match(/^\[(\w+)\]$/);
+	return match ? `:${match[1]}` : entry;
+}
+function hasIndex(dir) {
+	try {
+		return statSync(join(dir, "index.ts")).isFile();
+	} catch {
+		return false;
+	}
+}
+async function walkDir(parentRouter, dir, accumulatedPath) {
+	let entries;
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const fullPath = join(dir, entry);
+		if (!statSync(fullPath).isDirectory()) continue;
+		if (entry.startsWith(".") || entry === "node_modules") continue;
+		const segment = toPathSegment(entry);
+		if (hasIndex(fullPath)) try {
+			const mod = await import(join(fullPath, "index.ts"));
+			const router = mod.default ?? mod.routes ?? mod.router;
+			const honoRouter = router instanceof Hono ? router : typeof router === "function" ? router() : null;
+			if (honoRouter) {
+				await walkDir(honoRouter, fullPath, "");
+				const mountPath = accumulatedPath ? `${accumulatedPath}/${segment}` : `/${segment}`;
+				parentRouter.route(mountPath, honoRouter);
+			}
+		} catch (err) {
+			console.warn(`[peta-docs] could not load routes from "${entry}": ${err instanceof Error ? err.message : err}`);
+		}
+		else await walkDir(parentRouter, fullPath, accumulatedPath ? `${accumulatedPath}/${segment}` : `/${segment}`);
+	}
+}
+/**
+* Load routes from a directory tree. Each subdirectory with an `index.ts`
+* exporting a Hono instance (default export) is mounted as a sub-router.
+*
+* Directories named `[param]` are converted to `:param` path segments for
+* dynamic routing. Directories without `index.ts` accumulate their path
+* until a child directory with `index.ts` is found (gap pattern).
+*
+* Convention:
+*   routes/
+*     pets/
+*       index.ts          mounted at {basePath}/pets
+*       [id]/
+*         index.ts        mounted at {basePath}/pets/:id
+*         comments/
+*           index.ts      mounted at {basePath}/pets/:id/comments
+*     species/
+*       index.ts          mounted at {basePath}/species
+*
+* @param app    Hono application to mount routes on
+* @param dir    Path to the routes directory
+* @param options.basePath  URL prefix (default "/api")
+*/
+async function loadRoutes(app, dir, options) {
+	const basePath = (options?.basePath ?? "/api").replace(/\/+$/, "");
+	const resolvedDir = resolve(dir);
+	try {
+		readdirSync(resolvedDir);
+	} catch {
+		console.warn(`[peta-docs] could not read routes directory: ${dir}`);
+		return;
+	}
+	await walkDir(app, resolvedDir, basePath);
+}
+//#endregion
+//#region src/hono/index.ts
+/**
+* peta-docs/hono — Hono framework adapter.
+*
+* Provides the RouteBuilder fluent API, a Hono route scanner,
+* and a filesystem-based route loader.
+*
+* Importing this module also registers the Hono scanner as the
+* default scanner for `getOpenAPISpec()`.
+*
+* @module
+*/
+setDefaultScanner(honoScanner);
+//#endregion
+export { RouteBuilder, getRouteMeta, honoScanner, loadRoutes, route, setOnValidationError };

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+import { a as FilterFields, c as OpenAPIObject, d as ResponseValue, f as RouteConfig, g as TypedContext, h as StatusCode, i as FilterDef, l as Pagination, m as SchemaObject, n as ArkTypeSchema, o as FilterOperator, p as RouteEntry, r as FieldsetParams, s as InfoObject, t as RouteScanner, u as PathItemObject } from "./scanner-CU4MsJ2G.mjs";
+
+//#region src/scalar.d.ts
+interface ScalarUIOptions {
+  specUrl: string;
+  title?: string;
+  theme?: string;
+  showSidebar?: boolean;
+  cdnUrl?: string;
+}
+declare function serveScalarUI(options: ScalarUIOptions): (c: {
+  html(html: string): Response | Promise<Response>;
+}) => Response | Promise<Response>;
+//#endregion
+//#region src/spec/builder.d.ts
+declare function buildOpenAPISpec(routes: RouteEntry[], info: InfoObject, options?: {
+  basePath?: string;
+  components?: Record<string, unknown>;
+}): OpenAPIObject;
+//#endregion
+//#region src/spec/schema.d.ts
+declare function toOpenAPISchema(schema: unknown): SchemaObject;
+//#endregion
+//#region src/spec.d.ts
+declare function getOpenAPISpec(app: unknown, info: InfoObject, scanner?: RouteScanner, options?: {
+  basePath?: string;
+  components?: Record<string, unknown>;
+}): OpenAPIObject;
+//#endregion
+export { type ArkTypeSchema, type FieldsetParams, type FilterDef, type FilterFields, type FilterOperator, type InfoObject, type OpenAPIObject, type Pagination, type PathItemObject, type ResponseValue, type RouteConfig, type RouteEntry, type RouteScanner, type ScalarUIOptions, type SchemaObject, type StatusCode, type TypedContext, buildOpenAPISpec, getOpenAPISpec, serveScalarUI, toOpenAPISchema };

package/dist/index.mjs

@@ -0,0 +1,38 @@
+import { i as toOpenAPISchema, r as buildOpenAPISpec, t as getOpenAPISpec } from "./spec-Bobwv7gP.mjs";
+//#region src/scalar.ts
+function escapeHtml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function generateScalarHTML(options) {
+	const specUrl = escapeHtml(options.specUrl);
+	const title = options.title ?? "API Reference";
+	const theme = options.theme ?? "purple";
+	const showSidebar = options.showSidebar ?? true;
+	const cdnUrl = options.cdnUrl ?? "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
+	const config = escapeHtml(JSON.stringify({
+		theme,
+		showSidebar
+	}));
+	return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escapeHtml(title)}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { height: 100%; }
+  </style>
+</head>
+<body>
+  <div id="api-reference" data-url="${specUrl}" data-configuration="${config}"></div>
+  <script src="${escapeHtml(cdnUrl)}" crossorigin><\/script>
+</body>
+</html>`;
+}
+function serveScalarUI(options) {
+	const html = generateScalarHTML(options);
+	return (c) => c.html(html);
+}
+//#endregion
+export { buildOpenAPISpec, getOpenAPISpec, serveScalarUI, toOpenAPISchema };

package/dist/scanner-CU4MsJ2G.d.mts

@@ -0,0 +1,155 @@
+//#region src/types.d.ts
+type ArkTypeResult = {
+  issues?: Iterable<unknown>;
+  value?: unknown;
+} | Iterable<unknown>;
+interface ArkTypeSchema {
+  toJsonSchema(): unknown;
+  infer: unknown;
+  "~standard": {
+    validate: (v: unknown) => ArkTypeResult | Promise<ArkTypeResult>;
+  };
+}
+type Pagination = {
+  page: number;
+  limit: number;
+  offset: number;
+};
+type FilterOperator = "eq" | "ne" | "gte" | "gt" | "lte" | "lt" | "contains" | "startsWith" | "endsWith" | "in";
+interface FilterDef {
+  name: string;
+  schema: ArkTypeSchema;
+  operators: FilterOperator[];
+}
+type FilterFields<N extends string, S extends ArkTypeSchema, O extends FilterOperator[]> = ("eq" extends O[number] ? { [K in N]?: S["infer"] } : Record<string, unknown>) & { [K in `${N}__${Extract<O[number], Exclude<FilterOperator, "eq">>}`]?: S["infer"] };
+type FieldsetParams<R extends string[]> = { [K in R[number] as `fields[${K}]`]?: string };
+type HonoContext = import("hono").Context;
+type TypedContext<B, Q, P, Hd, Pg extends Pagination | undefined = undefined, F = Record<string, unknown>, Sr = Record<string, unknown>, Ir = Record<string, unknown>, Fs = Record<string, unknown>> = Omit<HonoContext, "req"> & {
+  req: Omit<HonoContext["req"], "valid"> & {
+    valid: {
+      (type: "json"): [B] extends [ArkTypeSchema] ? B["infer"] : never;
+      (type: "query"): [Q] extends [ArkTypeSchema] ? Pg extends Pagination ? Q["infer"] & Pg & F & Sr & Ir & Fs : Q["infer"] & F & Sr & Ir & Fs : Pg extends Pagination ? Pg & F & Sr & Ir & Fs : F & Sr & Ir & Fs;
+      (type: "param"): [P] extends [ArkTypeSchema] ? P["infer"] : never;
+      (type: "header"): [Hd] extends [ArkTypeSchema] ? Hd["infer"] : never;
+    };
+  };
+};
+type SchemaObject = Record<string, unknown>;
+interface InfoObject {
+  title: string;
+  version: string;
+  description?: string;
+  summary?: string;
+}
+interface ServerObject {
+  url: string;
+  description?: string;
+}
+interface ParameterObject {
+  name: string;
+  in: "query" | "path" | "header" | "cookie";
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  schema: SchemaObject;
+}
+interface MediaTypeObject {
+  schema: SchemaObject;
+}
+interface RequestBodyObject {
+  description?: string;
+  required?: boolean;
+  content: Record<string, MediaTypeObject>;
+}
+interface ResponseObject {
+  description: string;
+  content?: Record<string, MediaTypeObject>;
+}
+type ResponsesObject = Record<string, ResponseObject>;
+interface OperationObject {
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  tags?: string[];
+  parameters?: ParameterObject[];
+  requestBody?: RequestBodyObject;
+  responses?: ResponsesObject;
+  deprecated?: boolean;
+  security?: Record<string, string[]>[];
+}
+interface PathItemObject {
+  summary?: string;
+  description?: string;
+  get?: OperationObject;
+  post?: OperationObject;
+  put?: OperationObject;
+  delete?: OperationObject;
+  patch?: OperationObject;
+  parameters?: ParameterObject[];
+}
+type PathsObject = Record<string, PathItemObject>;
+interface OpenAPIObject {
+  openapi: string;
+  info: InfoObject;
+  jsonSchemaDialect?: string;
+  servers?: ServerObject[];
+  paths?: PathsObject;
+  components?: Record<string, unknown>;
+  security?: Record<string, string[]>[];
+  tags?: {
+    name: string;
+    description?: string;
+  }[];
+}
+type StatusCode = "200" | "201" | "202" | "204" | "301" | "304" | "400" | "401" | "403" | "404" | "405" | "409" | "422" | "429" | "500" | "502" | "503" | (string & {});
+type ResponseValue = string | {
+  description?: string;
+  content?: Record<string, {
+    schema: unknown;
+  }>;
+};
+interface RouteConfig {
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  tags?: string[];
+  query?: unknown;
+  params?: unknown;
+  headers?: unknown;
+  requestBody?: unknown | {
+    description?: string;
+    required?: boolean;
+    content: Record<string, {
+      schema: unknown;
+    }>;
+  };
+  pagination?: {
+    maxLimit: number;
+    defaultLimit: number;
+  };
+  filters?: FilterDef[];
+  sort?: string[];
+  include?: string[];
+  fieldsets?: string[];
+  security?: string[];
+  responses: Partial<Record<StatusCode, ResponseValue>>;
+  handler: (...args: unknown[]) => unknown;
+}
+interface RouteEntry {
+  path: string;
+  method: string;
+  config: RouteConfig;
+}
+//#endregion
+//#region src/scanner.d.ts
+/**
+ * Scans a framework app instance and extracts registered routes.
+ *
+ * Each framework adapter implements this interface to bridge the
+ * framework-specific route registry to the generic OpenAPI pipeline.
+ */
+interface RouteScanner {
+  scan(app: unknown): RouteEntry[];
+}
+//#endregion
+export { FilterFields as a, OpenAPIObject as c, ResponseValue as d, RouteConfig as f, TypedContext as g, StatusCode as h, FilterDef as i, Pagination as l, SchemaObject as m, ArkTypeSchema as n, FilterOperator as o, RouteEntry as p, FieldsetParams as r, InfoObject as s, RouteScanner as t, PathItemObject as u };