@pikku/cli 0.12.0 → 0.12.1

package/dist/src/utils/openapi/naming.js

@@ -0,0 +1,167 @@
+/**
+ * Derives function/method names from HTTP method + path.
+ * Uses operationId when available, otherwise generates from path segments.
+ */
+const IRREGULAR_PLURALS = {
+    addresses: 'address',
+    statuses: 'status',
+    indices: 'index',
+    analyses: 'analysis',
+    quizzes: 'quiz',
+    matrices: 'matrix',
+    vertices: 'vertex',
+    aliases: 'alias',
+    buses: 'bus',
+};
+export function singularize(word) {
+    const lower = word.toLowerCase();
+    if (IRREGULAR_PLURALS[lower]) {
+        const singular = IRREGULAR_PLURALS[lower];
+        return word[0] === word[0].toUpperCase()
+            ? singular.charAt(0).toUpperCase() + singular.slice(1)
+            : singular;
+    }
+    if (lower.endsWith('ies') && lower.length > 4) {
+        return word.slice(0, -3) + 'y';
+    }
+    // -shes, -ches, -xes, -zes, -sses → drop "es"
+    if (lower.endsWith('shes') || lower.endsWith('ches') || lower.endsWith('xes') || lower.endsWith('zes') || lower.endsWith('sses')) {
+        return word.slice(0, -2);
+    }
+    // General: drop trailing "s" (covers courses→course, products→product, etc.)
+    if (lower.endsWith('s') && !lower.endsWith('ss') && !lower.endsWith('us') && lower.length > 2) {
+        return word.slice(0, -1);
+    }
+    return word;
+}
+export function toCamelCase(str) {
+    return str
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_, c) => c.toUpperCase())
+        .replace(/^[A-Z]/, (c) => c.toLowerCase());
+}
+export function toPascalCase(str) {
+    const camel = toCamelCase(str);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+/**
+ * Strip common API prefix from paths (e.g. /api/v2/).
+ * Uses majority voting — a prefix shared by >75% of paths is stripped,
+ * so a few outlier paths (e.g. /oauth/...) don't break detection.
+ */
+export function detectCommonPrefix(paths) {
+    if (paths.length === 0)
+        return '';
+    const segments = paths.map((p) => p.replace(/^\//, '').split('/'));
+    const threshold = Math.ceil(paths.length * 0.75);
+    // Find the longest prefix shared by at least `threshold` paths
+    let prefixLen = 0;
+    for (let i = 0; i < 10; i++) {
+        // Count how many paths have the same segment at position i as the first path
+        const candidateSeg = segments[0][i];
+        if (!candidateSeg || candidateSeg.startsWith('{'))
+            break;
+        const count = segments.filter((s) => s.length > i + 1 && s[i] === candidateSeg).length;
+        if (count >= threshold) {
+            prefixLen = i + 1;
+        }
+        else {
+            break;
+        }
+    }
+    if (prefixLen === 0)
+        return '';
+    return '/' + segments[0].slice(0, prefixLen).join('/') + '/';
+}
+/** Convert operationId to camelCase function name */
+function fromOperationId(operationId) {
+    // operationId might be snake_case, camelCase, PascalCase, or kebab-case
+    return toCamelCase(operationId
+        .replace(/[^a-zA-Z0-9_-]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, ''));
+}
+const METHOD_PREFIXES = {
+    get: 'get',
+    post: 'create',
+    put: 'update',
+    patch: 'update',
+    delete: 'delete',
+};
+/**
+ * Generate function names for a list of operations.
+ * Handles collision detection and auto-deduplication.
+ */
+export function generateOperationNames(operations, commonPrefix) {
+    const results = [];
+    const usedNames = new Map();
+    for (const op of operations) {
+        let name;
+        if (op.operationId) {
+            name = fromOperationId(op.operationId);
+        }
+        else {
+            name = deriveNameFromPath(op.method, op.path, commonPrefix);
+        }
+        // Handle collisions
+        const existing = usedNames.get(name) ?? 0;
+        if (existing > 0) {
+            usedNames.set(name, existing + 1);
+            name = `${name}${existing + 1}`;
+        }
+        usedNames.set(name, (usedNames.get(name) ?? 0) || 1);
+        results.push({
+            method: op.method,
+            path: op.path,
+            functionName: name,
+            methodName: name,
+        });
+    }
+    return results;
+}
+function deriveNameFromPath(method, path, commonPrefix) {
+    // Strip common prefix
+    let cleanPath = path;
+    if (commonPrefix && cleanPath.startsWith(commonPrefix)) {
+        cleanPath = '/' + cleanPath.slice(commonPrefix.length);
+    }
+    const segments = cleanPath
+        .replace(/^\//, '')
+        .split('/')
+        .filter(Boolean);
+    const methodLower = method.toLowerCase();
+    const prefix = METHOD_PREFIXES[methodLower] || methodLower;
+    // Separate param and non-param segments
+    const nonParams = [];
+    let hasTrailingParam = false;
+    for (let i = 0; i < segments.length; i++) {
+        if (segments[i].startsWith('{')) {
+            if (i === segments.length - 1) {
+                hasTrailingParam = true;
+            }
+        }
+        else {
+            nonParams.push(segments[i]);
+        }
+    }
+    if (nonParams.length === 0) {
+        return prefix;
+    }
+    // For GET with trailing param: singularize the last non-param segment
+    // For GET without trailing param: keep plural (list)
+    // For POST without trailing param: use prefix (create)
+    const parts = nonParams.map((seg, i) => {
+        const isLast = i === nonParams.length - 1;
+        let word = seg;
+        if (isLast && hasTrailingParam) {
+            word = singularize(word);
+        }
+        // For GET on collection (no trailing param), use "list" prefix instead of "get"
+        return toPascalCase(word);
+    });
+    // For GET on collection, use "list" instead of "get"
+    let finalPrefix = prefix;
+    if (methodLower === 'get' && !hasTrailingParam) {
+        finalPrefix = 'list';
+    }
+    return finalPrefix + parts.join('');
+}

package/dist/src/utils/openapi/parse-openapi.d.ts

@@ -0,0 +1,36 @@
+import type { OpenAPISchema } from './zod-codegen.js';
+export interface ParsedSpec {
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    baseUrl: string;
+    authType: 'bearer' | 'oauth2' | 'apiKey' | 'none';
+    operations: ParsedOperation[];
+    componentSchemas: Record<string, OpenAPISchema>;
+}
+export interface ParsedOperation {
+    operationId?: string;
+    method: string;
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    pathParams: ParsedParam[];
+    queryParams: ParsedParam[];
+    requestBody?: OpenAPISchema;
+    responseSchema?: OpenAPISchema;
+    responseDescription?: string;
+}
+export interface ParsedParam {
+    name: string;
+    required: boolean;
+    schema: OpenAPISchema;
+    description?: string;
+}
+/**
+ * Read and parse an OpenAPI spec from a file path.
+ * Supports both YAML (.yaml, .yml) and JSON (.json) files.
+ */
+export declare function parseOpenAPISpec(filePath: string): Promise<ParsedSpec>;

package/dist/src/utils/openapi/parse-openapi.js

@@ -0,0 +1,196 @@
+/**
+ * Parses OpenAPI YAML/JSON specs, resolves $ref pointers, and produces a normalized IR.
+ */
+import { readFile } from 'fs/promises';
+import { parse as parseYAML } from 'yaml';
+/**
+ * Read and parse an OpenAPI spec from a file path.
+ * Supports both YAML (.yaml, .yml) and JSON (.json) files.
+ */
+export async function parseOpenAPISpec(filePath) {
+    const content = await readFile(filePath, 'utf-8');
+    let doc;
+    if (filePath.endsWith('.json')) {
+        doc = JSON.parse(content);
+    }
+    else {
+        doc = parseYAML(content);
+    }
+    // Resolve all $ref pointers in-place
+    resolveRefs(doc, doc);
+    const info = {
+        title: doc.info?.title ?? 'Unknown API',
+        version: doc.info?.version ?? '1.0.0',
+        description: doc.info?.description,
+    };
+    const baseUrl = extractBaseUrl(doc);
+    const authType = detectAuthType(doc);
+    // Extract component schemas
+    const componentSchemas = {};
+    if (doc.components?.schemas) {
+        for (const [name, schema] of Object.entries(doc.components.schemas)) {
+            componentSchemas[name] = schema;
+        }
+    }
+    // Extract operations
+    const operations = [];
+    if (doc.paths) {
+        for (const [path, pathItem] of Object.entries(doc.paths)) {
+            // Shared parameters at the path level
+            const sharedParams = pathItem.parameters ?? [];
+            for (const method of ['get', 'post', 'put', 'patch', 'delete']) {
+                const op = pathItem[method];
+                if (!op)
+                    continue;
+                const allParams = [...sharedParams, ...(op.parameters ?? [])];
+                operations.push({
+                    operationId: op.operationId,
+                    method,
+                    path,
+                    summary: op.summary,
+                    description: op.description,
+                    tags: op.tags ?? [],
+                    pathParams: extractParams(allParams, 'path'),
+                    queryParams: extractParams(allParams, 'query'),
+                    requestBody: extractRequestBody(op),
+                    responseSchema: extractResponseSchema(op),
+                    responseDescription: extractResponseDescription(op),
+                });
+            }
+        }
+    }
+    return { info, baseUrl, authType, operations, componentSchemas };
+}
+/** Recursively resolve $ref pointers in-place */
+function resolveRefs(node, root) {
+    if (node === null || typeof node !== 'object')
+        return node;
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) {
+            node[i] = resolveRefs(node[i], root);
+        }
+        return node;
+    }
+    if (typeof node.$ref === 'string') {
+        const resolved = resolveRefPath(node.$ref, root);
+        if (resolved && typeof resolved === 'object') {
+            // Merge any sibling properties (like description overrides)
+            const { $ref, ...siblings } = node;
+            const result = { ...resolved, ...siblings };
+            // Don't recurse infinitely — mark as resolved
+            return result;
+        }
+        return node;
+    }
+    for (const key of Object.keys(node)) {
+        node[key] = resolveRefs(node[key], root);
+    }
+    return node;
+}
+function resolveRefPath(ref, root) {
+    if (!ref.startsWith('#/'))
+        return undefined;
+    const parts = ref.slice(2).split('/');
+    let current = root;
+    for (const part of parts) {
+        const decoded = part.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[decoded];
+    }
+    return current;
+}
+function extractBaseUrl(doc) {
+    // OpenAPI 3.x
+    if (doc.servers && doc.servers.length > 0) {
+        return doc.servers[0].url ?? '';
+    }
+    // Swagger 2.x
+    if (doc.host) {
+        const scheme = doc.schemes?.[0] ?? 'https';
+        const basePath = doc.basePath ?? '';
+        return `${scheme}://${doc.host}${basePath}`;
+    }
+    return '';
+}
+function detectAuthType(doc) {
+    const securitySchemes = doc.components?.securitySchemes ?? doc.securityDefinitions ?? {};
+    for (const scheme of Object.values(securitySchemes)) {
+        if (scheme.type === 'oauth2')
+            return 'oauth2';
+        if (scheme.type === 'http' && scheme.scheme === 'bearer')
+            return 'bearer';
+        if (scheme.type === 'apiKey')
+            return 'apiKey';
+    }
+    return 'none';
+}
+function extractParams(params, location) {
+    return params
+        .filter((p) => p.in === location)
+        .map((p) => ({
+        name: p.name,
+        required: p.required ?? location === 'path',
+        schema: (p.schema ?? { type: 'string' }),
+        description: p.description,
+    }));
+}
+function extractRequestBody(op) {
+    const body = op.requestBody;
+    if (!body)
+        return undefined;
+    const content = body.content;
+    if (!content)
+        return undefined;
+    // Prefer JSON
+    const jsonContent = content['application/json'];
+    if (jsonContent?.schema)
+        return jsonContent.schema;
+    // Fallback to first content type
+    const firstKey = Object.keys(content)[0];
+    if (firstKey && content[firstKey]?.schema) {
+        return content[firstKey].schema;
+    }
+    return undefined;
+}
+function extractResponseDescription(op) {
+    const responses = op.responses;
+    if (!responses)
+        return undefined;
+    for (const code of ['200', '201', '202']) {
+        const resp = responses[code];
+        if (resp?.description)
+            return resp.description;
+    }
+    return undefined;
+}
+function extractResponseSchema(op) {
+    const responses = op.responses;
+    if (!responses)
+        return undefined;
+    // Look for 2xx responses in order of preference
+    for (const code of ['200', '201', '202', '204']) {
+        const resp = responses[code];
+        if (!resp)
+            continue;
+        const content = resp.content;
+        if (!content)
+            continue;
+        const jsonContent = content['application/json'];
+        if (jsonContent?.schema)
+            return jsonContent.schema;
+        const firstKey = Object.keys(content)[0];
+        if (firstKey && content[firstKey]?.schema) {
+            return content[firstKey].schema;
+        }
+    }
+    // Fallback: any 2xx
+    for (const [code, resp] of Object.entries(responses)) {
+        if (code.startsWith('2') && resp.content) {
+            const jsonContent = resp.content['application/json'];
+            if (jsonContent?.schema)
+                return jsonContent.schema;
+        }
+    }
+    return undefined;
+}

package/dist/src/utils/openapi/zod-codegen.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Converts OpenAPI schemas into Zod code strings.
+ *
+ * Chaining order: base → refinements → .nullable() → .optional() → .default() → .describe()
+ */
+export interface OpenAPISchema {
+    type?: string;
+    format?: string;
+    description?: string;
+    enum?: unknown[];
+    items?: OpenAPISchema;
+    properties?: Record<string, OpenAPISchema>;
+    required?: string[];
+    nullable?: boolean;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    oneOf?: OpenAPISchema[];
+    anyOf?: OpenAPISchema[];
+    allOf?: OpenAPISchema[];
+    additionalProperties?: boolean | OpenAPISchema;
+    $ref?: string;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+}
+export interface ZodCodegenContext {
+    /** Map from component schema name to its Zod variable name */
+    schemaRefs: Map<string, string>;
+    /** Track which refs are actually used */
+    usedRefs: Set<string>;
+    /** Indent level for readability */
+    indent: number;
+}
+export declare function createContext(schemaRefs?: Map<string, string>): ZodCodegenContext;
+/**
+ * Convert a single OpenAPI schema to a Zod expression string.
+ * Does NOT include .optional() — that's handled at the property level based on `required`.
+ */
+export declare function schemaToZod(schema: OpenAPISchema, ctx: ZodCodegenContext, opts?: {
+    optional?: boolean;
+}): string;
+/**
+ * Generate the Zod variable name for a component schema.
+ * e.g. "PaginatedResponse" → "PaginatedResponseSchema"
+ */
+export declare function schemaVarName(name: string): string;

package/dist/src/utils/openapi/zod-codegen.js

@@ -0,0 +1,251 @@
+/**
+ * Converts OpenAPI schemas into Zod code strings.
+ *
+ * Chaining order: base → refinements → .nullable() → .optional() → .default() → .describe()
+ */
+export function createContext(schemaRefs) {
+    return {
+        schemaRefs: schemaRefs ?? new Map(),
+        usedRefs: new Set(),
+        indent: 0,
+    };
+}
+/**
+ * Convert a single OpenAPI schema to a Zod expression string.
+ * Does NOT include .optional() — that's handled at the property level based on `required`.
+ */
+export function schemaToZod(schema, ctx, opts = {}) {
+    let code = schemaToZodBase(schema, ctx);
+    // Refinements
+    code = applyRefinements(code, schema);
+    // Nullable
+    if (schema.nullable) {
+        code += '.nullable()';
+    }
+    // Optional
+    if (opts.optional) {
+        code += '.optional()';
+    }
+    // Default
+    if (schema.default !== undefined) {
+        code += `.default(${JSON.stringify(schema.default)})`;
+    }
+    // Description
+    if (schema.description) {
+        code += `.describe(${JSON.stringify(schema.description)})`;
+    }
+    return code;
+}
+function schemaToZodBase(schema, ctx) {
+    // Handle $ref
+    if (schema.$ref) {
+        const refName = schema.$ref.split('/').pop();
+        const zodName = ctx.schemaRefs.get(refName);
+        if (zodName) {
+            ctx.usedRefs.add(refName);
+            return zodName;
+        }
+        // Unknown ref — fallback to z.unknown()
+        return 'z.unknown()';
+    }
+    // Handle allOf — merge into single object
+    if (schema.allOf && schema.allOf.length > 0) {
+        return handleAllOf(schema.allOf, ctx);
+    }
+    // Handle oneOf/anyOf — union
+    if (schema.oneOf && schema.oneOf.length > 0) {
+        return handleUnion(schema.oneOf, ctx);
+    }
+    if (schema.anyOf && schema.anyOf.length > 0) {
+        return handleUnion(schema.anyOf, ctx);
+    }
+    // Handle enum
+    if (schema.enum && schema.enum.length > 0) {
+        return handleEnum(schema.enum);
+    }
+    // Handle by type
+    switch (schema.type) {
+        case 'string':
+            return handleString(schema);
+        case 'integer':
+            return 'z.number().int()';
+        case 'number':
+            return 'z.number()';
+        case 'boolean':
+            return 'z.boolean()';
+        case 'array':
+            return handleArray(schema, ctx);
+        case 'object':
+            return handleObject(schema, ctx);
+        default:
+            // No type specified but has properties — treat as object
+            if (schema.properties) {
+                return handleObject(schema, ctx);
+            }
+            return 'z.unknown()';
+    }
+}
+function handleString(schema) {
+    switch (schema.format) {
+        case 'uuid':
+            return 'z.string().uuid()';
+        case 'date-time':
+            return 'z.string().datetime()';
+        case 'date':
+            return 'z.string().date()';
+        case 'email':
+            return 'z.string().email()';
+        case 'uri':
+        case 'url':
+            return 'z.string().url()';
+        default:
+            return 'z.string()';
+    }
+}
+function handleEnum(values) {
+    // If all values are strings, use z.enum
+    if (values.every((v) => typeof v === 'string')) {
+        const enumValues = values.map((v) => JSON.stringify(v)).join(', ');
+        return `z.enum([${enumValues}])`;
+    }
+    // Mixed types — use z.union of z.literal
+    const literals = values.map((v) => `z.literal(${JSON.stringify(v)})`).join(', ');
+    return `z.union([${literals}])`;
+}
+function handleArray(schema, ctx) {
+    const itemsZod = schema.items
+        ? schemaToZodBase(schema.items, ctx)
+        : 'z.unknown()';
+    return `z.array(${itemsZod})`;
+}
+function indent(ctx) {
+    return '  '.repeat(ctx.indent);
+}
+function handleObject(schema, ctx) {
+    if (!schema.properties || Object.keys(schema.properties).length === 0) {
+        // Object with no defined properties
+        if (schema.additionalProperties) {
+            const valueSchema = typeof schema.additionalProperties === 'object'
+                ? schemaToZod(schema.additionalProperties, ctx)
+                : 'z.unknown()';
+            return `z.record(z.string(), ${valueSchema})`;
+        }
+        return 'z.record(z.string(), z.unknown())';
+    }
+    const inner = { ...ctx, indent: ctx.indent + 1 };
+    const pad = indent(inner);
+    const closePad = indent(ctx);
+    const requiredSet = new Set(schema.required ?? []);
+    const entries = [];
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+        const isOptional = !requiredSet.has(key);
+        const propZod = schemaToZod(propSchema, inner, { optional: isOptional });
+        entries.push(`${pad}${safeKey(key)}: ${propZod},`);
+    }
+    return `z.object({\n${entries.join('\n')}\n${closePad}})`;
+}
+function handleAllOf(schemas, ctx) {
+    // Collect all properties from all schemas
+    const mergedProps = {};
+    const mergedRequired = [];
+    for (const sub of schemas) {
+        if (sub.$ref) {
+            const refName = sub.$ref.split('/').pop();
+            const zodName = ctx.schemaRefs.get(refName);
+            if (zodName) {
+                ctx.usedRefs.add(refName);
+                // If it's a pure ref in an allOf, we'd need to merge/extend
+                // For simplicity, if we have refs mixed with objects, use .merge()
+            }
+        }
+        if (sub.properties) {
+            Object.assign(mergedProps, sub.properties);
+        }
+        if (sub.required) {
+            mergedRequired.push(...sub.required);
+        }
+    }
+    // If we have only refs, use .merge()
+    const refSchemas = schemas.filter((s) => s.$ref);
+    const objSchemas = schemas.filter((s) => !s.$ref && (s.properties || s.type === 'object'));
+    if (refSchemas.length > 0 && objSchemas.length === 0) {
+        const parts = refSchemas.map((s) => {
+            const refName = s.$ref.split('/').pop();
+            ctx.usedRefs.add(refName);
+            return ctx.schemaRefs.get(refName) || 'z.object({})';
+        });
+        if (parts.length === 1)
+            return parts[0];
+        return parts.reduce((acc, part) => `${acc}.merge(${part})`);
+    }
+    // Otherwise, merge into a single object
+    if (Object.keys(mergedProps).length > 0) {
+        return handleObject({
+            type: 'object',
+            properties: mergedProps,
+            required: [...new Set(mergedRequired)],
+        }, ctx);
+    }
+    // Fallback
+    return 'z.unknown()';
+}
+function handleUnion(schemas, ctx) {
+    const members = schemas.map((s) => schemaToZodBase(s, ctx));
+    if (members.length === 1)
+        return members[0];
+    return `z.union([${members.join(', ')}])`;
+}
+function applyRefinements(code, schema) {
+    let result = code;
+    // String refinements
+    if (schema.type === 'string' || (!schema.type && !schema.format)) {
+        if (schema.minLength !== undefined) {
+            result += `.min(${schema.minLength})`;
+        }
+        if (schema.maxLength !== undefined) {
+            result += `.max(${schema.maxLength})`;
+        }
+        if (schema.pattern) {
+            result += `.regex(new RegExp(${JSON.stringify(schema.pattern)}))`;
+        }
+    }
+    // Number refinements
+    if (schema.type === 'number' || schema.type === 'integer') {
+        if (schema.minimum !== undefined) {
+            result += `.min(${schema.minimum})`;
+        }
+        if (schema.maximum !== undefined) {
+            result += `.max(${schema.maximum})`;
+        }
+        if (schema.exclusiveMinimum !== undefined) {
+            result += `.gt(${schema.exclusiveMinimum})`;
+        }
+        if (schema.exclusiveMaximum !== undefined) {
+            result += `.lt(${schema.exclusiveMaximum})`;
+        }
+    }
+    // Array refinements
+    if (schema.type === 'array') {
+        if (schema.minItems !== undefined) {
+            result += `.min(${schema.minItems})`;
+        }
+        if (schema.maxItems !== undefined) {
+            result += `.max(${schema.maxItems})`;
+        }
+    }
+    return result;
+}
+/** Ensure property keys are safe identifiers, or quote them */
+function safeKey(key) {
+    if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+        return key;
+    }
+    return JSON.stringify(key);
+}
+/**
+ * Generate the Zod variable name for a component schema.
+ * e.g. "PaginatedResponse" → "PaginatedResponseSchema"
+ */
+export function schemaVarName(name) {
+    return name.endsWith('Schema') ? name : `${name}Schema`;
+}