@pikku/openapi-parser 0.12.9 → 0.12.10

package/dist/codegen.js

@@ -1,4 +1,4 @@
-import { schemaToZod, schemaVarName, sanitizeTypeName, createContext, } from './zod-codegen.js';
+import { schemaToZod, schemaVarName, sanitizeTypeName, createContext, snakeToCamel, } from './zod-codegen.js';
 import { generateOperationNames, detectCommonPrefix, } from './naming.js';
 function safeKey(key) {
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
@@ -44,6 +44,130 @@ function getErrorClassesForResponses(errorResponses) {
     }
     return classes;
 }
+/**
+ * Collect all component schema names directly referenced by an operation's
+ * params, request body, and response schema.
+ */
+function collectOperationSchemaRefs(parsed, componentNames, schemaIdentityMap) {
+    const refs = new Set();
+    const allSchemas = [];
+    // Gather all schema objects from this operation
+    for (const p of [
+        ...parsed.pathParams,
+        ...parsed.queryParams,
+        ...parsed.headerParams,
+    ]) {
+        if (p.schema)
+            allSchemas.push(p.schema);
+    }
+    if (parsed.requestBody)
+        allSchemas.push(parsed.requestBody);
+    if (parsed.responseSchema)
+        allSchemas.push(parsed.responseSchema);
+    for (const schema of allSchemas) {
+        // Check if the schema itself IS a component schema (by object identity).
+        // collectSchemaRefs skips the root identity check, so we must do it here.
+        if (schema && typeof schema === 'object') {
+            const identityName = schemaIdentityMap.get(schema);
+            if (identityName && componentNames.has(identityName)) {
+                refs.add(identityName);
+            }
+        }
+        for (const ref of collectSchemaRefs(schema, componentNames, schemaIdentityMap)) {
+            refs.add(ref);
+        }
+    }
+    return refs;
+}
+/**
+ * Compute the transitive closure of schema dependencies.
+ * Given a set of schema names, expand it to include all schemas they depend on.
+ */
+function transitiveClosure(schemaNames, allSchemas, componentNames, schemaIdentityMap) {
+    const result = new Set();
+    const queue = [...schemaNames];
+    while (queue.length > 0) {
+        const name = queue.pop();
+        if (result.has(name))
+            continue;
+        if (!allSchemas[name])
+            continue;
+        result.add(name);
+        const deps = collectSchemaRefs(allSchemas[name], componentNames, schemaIdentityMap);
+        for (const dep of deps) {
+            if (!result.has(dep))
+                queue.push(dep);
+        }
+    }
+    return result;
+}
+/**
+ * Partition component schemas into shared, single-use, and unused buckets.
+ *
+ * Algorithm:
+ * 1. For each operation, collect its directly referenced component schemas
+ * 2. Expand each operation's refs to include transitive deps
+ * 3. Count how many operations reference each schema (via transitive closure)
+ * 4. Schemas with 2+ operations → shared, 1 operation → single, 0 → unused
+ * 5. Single-use schemas whose transitive deps include shared schemas still go
+ *    into single-use (the function file will import those shared deps)
+ */
+function partitionSchemas(spec, schemaIdentityMap) {
+    const componentNames = new Set(Object.keys(spec.componentSchemas));
+    // Step 1: Direct refs per operation
+    const opDirectRefs = spec.operations.map((op) => collectOperationSchemaRefs(op, componentNames, schemaIdentityMap));
+    // Step 2: Transitive refs per operation
+    const opTransitiveRefs = opDirectRefs.map((directRefs) => transitiveClosure(directRefs, spec.componentSchemas, componentNames, schemaIdentityMap));
+    // Step 3: Count how many operations reference each schema
+    const refCount = new Map();
+    for (let i = 0; i < opTransitiveRefs.length; i++) {
+        for (const name of opTransitiveRefs[i]) {
+            if (!refCount.has(name))
+                refCount.set(name, new Set());
+            refCount.get(name).add(i);
+        }
+    }
+    // Step 4: Partition
+    const shared = new Set();
+    const single = new Map();
+    const unused = new Set();
+    for (const name of componentNames) {
+        const ops = refCount.get(name);
+        if (!ops || ops.size === 0) {
+            unused.add(name);
+        }
+        else if (ops.size === 1) {
+            single.set(name, [...ops][0]);
+        }
+        else {
+            shared.add(name);
+        }
+    }
+    // Step 5: If a single-use schema transitively depends on another single-use
+    // schema from a DIFFERENT operation, promote both to shared.
+    // This handles chains like: OpA → SchemaX → SchemaY ← OpB
+    // Also: single-use schemas that depend on other single-use schemas from the
+    // same operation stay single-use (they'll be inlined together).
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [name, opIdx] of [...single]) {
+            const deps = collectSchemaRefs(spec.componentSchemas[name], componentNames, schemaIdentityMap);
+            for (const dep of deps) {
+                if (single.has(dep) && single.get(dep) !== opIdx) {
+                    // Dep is single-use but for a different operation — promote both
+                    shared.add(dep);
+                    single.delete(dep);
+                    shared.add(name);
+                    single.delete(name);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    return { shared, single, unused };
+}
 export function generateAddonFromOpenAPI(spec, vars, flags) {
     const files = {};
     const { name } = vars;
@@ -52,7 +176,41 @@ export function generateAddonFromOpenAPI(spec, vars, flags) {
     for (const schemaName of Object.keys(spec.componentSchemas)) {
         schemaRefs.set(schemaName, schemaVarName(schemaName));
     }
-    const ctx = createContext(schemaRefs);
+    // Build an identity map from resolved schema objects to their component names.
+    // After $ref resolution, many references become the same JS object as the
+    // component schema (or a spread-copy). This map lets the codegen detect those
+    // resolved references by object identity instead of relying on $ref strings.
+    const schemaIdentityMap = new Map();
+    for (const [schemaName, schema] of Object.entries(spec.componentSchemas)) {
+        if (schema && typeof schema === 'object') {
+            schemaIdentityMap.set(schema, schemaName);
+        }
+    }
+    // Partition schemas: shared (2+ ops), single-use (1 op), unused (0 ops)
+    const partition = partitionSchemas(spec, schemaIdentityMap);
+    // Build the set of schemas that go in the shared types file:
+    // shared schemas + their transitive dependencies
+    const componentNames = new Set(Object.keys(spec.componentSchemas));
+    const sharedWithDeps = transitiveClosure(partition.shared, spec.componentSchemas, componentNames, schemaIdentityMap);
+    // Any transitive dep of a shared schema that was single-use gets promoted to shared
+    for (const name of sharedWithDeps) {
+        partition.single.delete(name);
+    }
+    // Build a reduced componentSchemas for the types file (only shared schemas)
+    const sharedComponentSchemas = {};
+    for (const schemaName of sharedWithDeps) {
+        if (spec.componentSchemas[schemaName]) {
+            sharedComponentSchemas[schemaName] = spec.componentSchemas[schemaName];
+        }
+    }
+    // schemaRefs for shared types file context — only shared schemas
+    const sharedSchemaRefs = new Map();
+    for (const schemaName of sharedWithDeps) {
+        sharedSchemaRefs.set(schemaName, schemaVarName(schemaName));
+    }
+    const ctx = createContext(sharedSchemaRefs, schemaIdentityMap, {
+        camelCase: flags.camelCase,
+    });
     // Generate operation names
     const paths = spec.operations.map((op) => op.path);
     const commonPrefix = detectCommonPrefix(paths);
@@ -64,14 +222,35 @@ export function generateAddonFromOpenAPI(spec, vars, flags) {
     // Pair named operations with their parsed data
     const opPairs = namedOps.map((named, i) => ({ named, parsed: spec.operations[i] }));
     // Generate types file with shared schemas (only if there are any)
-    if (Object.keys(spec.componentSchemas).length > 0) {
-        files[`src/${name}.types.ts`] = generateTypesFile(spec, ctx);
+    if (Object.keys(sharedComponentSchemas).length > 0) {
+        files[`src/${name}.types.ts`] = generateTypesFile({ ...spec, componentSchemas: sharedComponentSchemas }, ctx, schemaIdentityMap);
+    }
+    // Collect single-use schemas per operation index
+    const singleSchemasPerOp = new Map();
+    for (const [schemaName, opIdx] of partition.single) {
+        if (!singleSchemasPerOp.has(opIdx))
+            singleSchemasPerOp.set(opIdx, new Set());
+        singleSchemasPerOp.get(opIdx).add(schemaName);
+    }
+    // Expand single-use schemas to include their transitive deps that are also single-use
+    for (const [_opIdx, schemas] of singleSchemasPerOp) {
+        const expanded = transitiveClosure(schemas, spec.componentSchemas, componentNames, schemaIdentityMap);
+        // Only keep schemas that are NOT in the shared set
+        for (const s of expanded) {
+            if (!sharedWithDeps.has(s) && !partition.unused.has(s)) {
+                schemas.add(s);
+            }
+        }
     }
     // Generate function files
     const functionExports = [];
-    for (const { named, parsed } of opPairs) {
-        const funcCtx = createContext(schemaRefs);
-        const funcCode = generateFunctionFile(named, parsed, vars, funcCtx, spec, flags);
+    for (let i = 0; i < opPairs.length; i++) {
+        const { named, parsed } = opPairs[i];
+        const funcCtx = createContext(schemaRefs, schemaIdentityMap, {
+            camelCase: flags.camelCase,
+        });
+        const inlineSchemas = singleSchemasPerOp.get(i) ?? new Set();
+        const funcCode = generateFunctionFile(named, parsed, vars, funcCtx, spec, flags, inlineSchemas, sharedWithDeps, schemaIdentityMap);
         files[`src/functions/${named.functionName}.function.ts`] = funcCode;
         functionExports.push(named.functionName);
     }
@@ -83,43 +262,216 @@ export function generateAddonFromOpenAPI(spec, vars, flags) {
     files[`src/${name}.variable.ts`] = generateVariableFile(spec, vars);
     return files;
 }
-function generateTypesFile(spec, ctx) {
+/**
+ * Collect all component schema names referenced (directly or via properties/items/allOf/oneOf/anyOf)
+ * by a given OpenAPI schema object.
+ *
+ * After $ref resolution, most $ref strings are gone and replaced by the resolved
+ * object (often the same JS identity as the component schema). We detect
+ * dependencies both by surviving $ref strings AND by object identity via
+ * schemaIdentityMap.
+ */
+function collectSchemaRefs(schema, componentNames, schemaIdentityMap) {
+    const refs = new Set();
+    const visited = new Set();
+    function walk(node, isRoot) {
+        if (!node || typeof node !== 'object' || visited.has(node))
+            return;
+        visited.add(node);
+        // Check surviving $ref strings
+        if (node.$ref) {
+            const refName = node.$ref.split('/').pop();
+            if (componentNames.has(refName))
+                refs.add(refName);
+        }
+        // Check if this node IS a known component schema (resolved $ref by identity).
+        // Skip this check for the root node (the schema we're analyzing),
+        // otherwise we'd match the schema against itself and return early,
+        // missing its internal dependencies.
+        if (!isRoot) {
+            const identityName = schemaIdentityMap.get(node);
+            if (identityName && componentNames.has(identityName)) {
+                refs.add(identityName);
+                // Don't walk into the component schema's internals — those are
+                // handled when that schema is processed as a top-level entry.
+                return;
+            }
+        }
+        if (node.properties) {
+            for (const prop of Object.values(node.properties))
+                walk(prop, false);
+        }
+        if (node.items)
+            walk(node.items, false);
+        if (node.allOf)
+            for (const s of node.allOf)
+                walk(s, false);
+        if (node.oneOf)
+            for (const s of node.oneOf)
+                walk(s, false);
+        if (node.anyOf)
+            for (const s of node.anyOf)
+                walk(s, false);
+        if (node.additionalProperties &&
+            typeof node.additionalProperties === 'object') {
+            walk(node.additionalProperties, false);
+        }
+    }
+    walk(schema, true);
+    return refs;
+}
+/**
+ * Topologically sort component schemas so that dependencies come before dependents.
+ * Schemas involved in cycles are placed in arbitrary order (cycles are handled via z.lazy).
+ */
+function topoSortSchemas(schemas, schemaIdentityMap) {
+    const names = new Set(Object.keys(schemas));
+    const deps = new Map();
+    const selfRefs = new Set();
+    for (const [name, schema] of Object.entries(schemas)) {
+        const refNames = collectSchemaRefs(schema, names, schemaIdentityMap);
+        if (refNames.has(name)) {
+            selfRefs.add(name); // track self-referential schemas
+        }
+        refNames.delete(name); // remove self-refs from dependency graph
+        deps.set(name, refNames);
+    }
+    const sorted = [];
+    const visited = new Set();
+    const inStack = new Set();
+    const cyclicEdges = new Set(); // "child" schemas that are referenced before declaration
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        if (inStack.has(name)) {
+            // This is a cycle — mark this name as needing z.lazy()
+            cyclicEdges.add(name);
+            return;
+        }
+        inStack.add(name);
+        const children = deps.get(name) ?? new Set();
+        for (const child of children) {
+            if (names.has(child))
+                visit(child);
+        }
+        inStack.delete(name);
+        visited.add(name);
+        sorted.push(name);
+    }
+    for (const name of names) {
+        visit(name);
+    }
+    // Self-referential schemas also need z.lazy() forward declarations
+    for (const name of selfRefs) {
+        cyclicEdges.add(name);
+    }
+    return { sorted, cyclicEdges };
+}
+function generateTypesFile(spec, ctx, schemaIdentityMap) {
     const lines = [];
     lines.push("import { z } from 'zod'");
     lines.push('');
     lines.push(`// Shared schemas from ${spec.info.title} v${spec.info.version}`);
     lines.push('');
-    for (const [name, schema] of Object.entries(spec.componentSchemas)) {
-        const varName = schemaVarName(name);
+    const { sorted, cyclicEdges } = topoSortSchemas(spec.componentSchemas, schemaIdentityMap);
+    // Track emitted variable names and type names to deduplicate collisions
+    // (e.g. two OpenAPI components that sanitize to the same JS identifier)
+    const emittedVarNames = new Set();
+    const emittedTypeNames = new Set();
+    function deduplicateName(baseName, usedSet) {
+        if (!usedSet.has(baseName)) {
+            usedSet.add(baseName);
+            return baseName;
+        }
+        let counter = 2;
+        while (usedSet.has(`${baseName}_${counter}`)) {
+            counter++;
+        }
+        const deduped = `${baseName}_${counter}`;
+        usedSet.add(deduped);
+        return deduped;
+    }
+    // For schemas that participate in cycles, emit a z.lazy() forward declaration
+    // before any schemas are defined, so forward references work.
+    if (cyclicEdges.size > 0) {
+        lines.push('// Forward declarations for circular references');
+        for (const name of cyclicEdges) {
+            const varName = deduplicateName(schemaVarName(name), emittedVarNames);
+            const typeName = deduplicateName(sanitizeTypeName(name), emittedTypeNames);
+            lines.push(`export const ${varName}: z.ZodType<any> = z.lazy(() => _${varName})`);
+            lines.push(`export type ${typeName} = z.infer<typeof ${varName}>`);
+            lines.push('');
+        }
+    }
+    // Emit schemas in topological order
+    for (const name of sorted) {
+        const schema = spec.componentSchemas[name];
+        const varName = deduplicateName(schemaVarName(name), emittedVarNames);
+        const typeName = deduplicateName(sanitizeTypeName(name), emittedTypeNames);
+        // Temporarily remove the current schema from the identity map so that
+        // schemaToZod doesn't short-circuit to referencing the variable we're
+        // currently defining (which would produce `const XSchema = XSchema`).
+        ctx.schemaIdentityMap.delete(schema);
         const zodCode = schemaToZod(schema, ctx);
-        lines.push(`export const ${varName} = ${zodCode}`);
-        lines.push(`export type ${sanitizeTypeName(name)} = z.infer<typeof ${varName}>`);
+        // Restore it for subsequent schemas that may reference this one.
+        ctx.schemaIdentityMap.set(schema, name);
+        if (cyclicEdges.has(name)) {
+            // The public variable was already declared above via z.lazy();
+            // emit the real implementation with an underscore prefix.
+            lines.push(`const _${varName} = ${zodCode}`);
+        }
+        else {
+            lines.push(`export const ${varName} = ${zodCode}`);
+            lines.push(`export type ${typeName} = z.infer<typeof ${varName}>`);
+        }
         lines.push('');
     }
     return lines.join('\n');
 }
-function generateFunctionFile(named, parsed, vars, ctx, spec, flags) {
+function generateFunctionFile(named, parsed, vars, ctx, spec, flags, inlineSchemas = new Set(), sharedSchemas = new Set(), schemaIdentityMap = new Map()) {
     const lines = [];
-    const { camelName } = vars;
+    const { camelName, name } = vars;
+    const hasInput = parsed.pathParams.length > 0 ||
+        parsed.queryParams.length > 0 ||
+        parsed.headerParams.length > 0 ||
+        parsed.requestBody;
+    const pascalName = named.functionName.charAt(0).toUpperCase() + named.functionName.slice(1);
+    const inputName = `${pascalName}Input`;
+    const outputName = `${pascalName}Output`;
+    // Pre-generate Zod code to discover which schema refs are used
+    let inputCode;
+    let outputCode;
+    if (hasInput) {
+        inputCode = buildInputSchema(parsed, ctx);
+    }
+    if (parsed.responseSchema) {
+        outputCode = buildOutputSchema(parsed.responseSchema, ctx);
+    }
+    // Bug 2: If generated Zod code is too large (> 500 lines), TypeScript
+    // can't infer the type (TS7056). Replace with z.any() to stay compilable.
+    const LINE_LIMIT = 500;
+    if (inputCode && inputCode.split('\n').length > LINE_LIMIT) {
+        inputCode = 'z.any()';
+    }
+    if (outputCode && outputCode.split('\n').length > LINE_LIMIT) {
+        outputCode = 'z.any()';
+    }
     // Tag description as file header
     if (parsed.tags.length > 0) {
         const tag = parsed.tags[0];
         const tagDesc = spec.tagDescriptions[tag];
         if (tagDesc) {
-            lines.push(`// ${tag} — ${tagDesc}`);
+            const cleanDesc = tagDesc
+                .replace(/\r?\n/g, ' ')
+                .replace(/\s+/g, ' ')
+                .trim();
+            lines.push(`// ${tag} — ${cleanDesc}`);
             lines.push('');
         }
     }
-    const hasInput = parsed.pathParams.length > 0 ||
-        parsed.queryParams.length > 0 ||
-        parsed.headerParams.length > 0 ||
-        parsed.requestBody;
-    const pascalName = named.functionName.charAt(0).toUpperCase() + named.functionName.slice(1);
-    const inputName = `${pascalName}Input`;
-    const outputName = `${pascalName}Output`;
     // Determine error imports needed
     const errorClasses = getErrorClassesForResponses(parsed.errorResponses);
-    const needsZod = hasInput || !!parsed.responseSchema;
+    const needsZod = hasInput || !!parsed.responseSchema || inlineSchemas.size > 0;
     if (needsZod) {
         lines.push("import { z } from 'zod'");
     }
@@ -127,16 +479,122 @@ function generateFunctionFile(named, parsed, vars, ctx, spec, flags) {
     if (errorClasses.length > 0) {
         lines.push(`import { ${errorClasses.join(', ')} } from '@pikku/core/errors'`);
     }
+    // Import referenced component schemas from the types file.
+    // Only import schemas that are in the shared set (not inlined ones).
+    // In addition to the refs tracked through usedRefs, scan the generated Zod
+    // code for schema variable names that may have been missed (e.g. when
+    // a $ref survived resolution in a nested path not covered by usedRefs).
+    if (Object.keys(spec.componentSchemas).length > 0) {
+        const allGeneratedCode = [inputCode, outputCode].filter(Boolean).join('\n');
+        for (const [refName, varName] of ctx.schemaRefs) {
+            if (!ctx.usedRefs.has(refName) && allGeneratedCode.includes(varName)) {
+                ctx.usedRefs.add(refName);
+            }
+        }
+        const schemaImports = [
+            ...new Set([...ctx.usedRefs]
+                .filter((refName) => sharedSchemas.has(refName)) // only import shared schemas
+                .map((refName) => ctx.schemaRefs.get(refName))
+                .filter(Boolean)),
+        ].sort();
+        if (schemaImports.length > 0) {
+            lines.push(`import { ${schemaImports.join(', ')} } from '../${name}.types.js'`);
+        }
+    }
     lines.push('');
+    // Emit inline (single-use) schema definitions before input/output
+    if (inlineSchemas.size > 0) {
+        // Build a mini component schemas map for just the inline schemas
+        const inlineComponentSchemas = {};
+        for (const schemaName of inlineSchemas) {
+            if (spec.componentSchemas[schemaName]) {
+                inlineComponentSchemas[schemaName] = spec.componentSchemas[schemaName];
+            }
+        }
+        if (Object.keys(inlineComponentSchemas).length > 0) {
+            // Create a context that knows about both shared (for imports) and inline schemas
+            const inlineCtx = createContext(ctx.schemaRefs, schemaIdentityMap, {
+                camelCase: flags.camelCase,
+            });
+            const { sorted, cyclicEdges } = topoSortSchemas(inlineComponentSchemas, schemaIdentityMap);
+            // Bug 4: Pre-generate all Zod code and detect forward references.
+            // The topological sort may miss dependencies when $ref resolution
+            // replaces references with copies (breaking object identity).
+            // Scan generated code for variable names that appear before their
+            // declaration and promote those to z.lazy() forward declarations.
+            const inlineSorted = sorted.filter((s) => inlineSchemas.has(s));
+            const generatedCode = new Map();
+            for (const sName of inlineSorted) {
+                const schema = spec.componentSchemas[sName];
+                inlineCtx.schemaIdentityMap.delete(schema);
+                const zodCode = schemaToZod(schema, inlineCtx);
+                inlineCtx.schemaIdentityMap.set(schema, sName);
+                generatedCode.set(sName, zodCode);
+            }
+            // Build a map of variable names to schema names for inline schemas
+            const inlineVarToName = new Map();
+            for (const sName of inlineSorted) {
+                inlineVarToName.set(schemaVarName(sName), sName);
+            }
+            // Detect forward references and self-references: for each schema in order,
+            // check if its generated code references a variable that appears later in
+            // the sorted list OR references its own variable (self-referential schema).
+            const forwardRefs = new Set(cyclicEdges);
+            const emittedSoFar = new Set();
+            for (const sName of inlineSorted) {
+                const code = generatedCode.get(sName);
+                const ownVarN = schemaVarName(sName);
+                // Self-reference: schema uses its own variable name in its definition
+                if (code.includes(ownVarN)) {
+                    forwardRefs.add(sName);
+                }
+                for (const [varN, refName] of inlineVarToName) {
+                    if (refName !== sName &&
+                        !emittedSoFar.has(refName) &&
+                        code.includes(varN)) {
+                        // This schema references another inline schema not yet emitted
+                        forwardRefs.add(refName);
+                    }
+                }
+                emittedSoFar.add(sName);
+            }
+            const emittedVarNames = new Set();
+            const emittedTypeNames = new Set();
+            // Forward declarations for cycles and forward references within inline schemas
+            if (forwardRefs.size > 0) {
+                lines.push('// Forward declarations for circular references');
+                for (const sName of forwardRefs) {
+                    if (!inlineSchemas.has(sName))
+                        continue;
+                    const varN = schemaVarName(sName);
+                    const typeN = sanitizeTypeName(sName);
+                    emittedVarNames.add(varN);
+                    emittedTypeNames.add(typeN);
+                    lines.push(`const ${varN}: z.ZodType<any> = z.lazy(() => _${varN})`);
+                    lines.push('');
+                }
+            }
+            for (const sName of inlineSorted) {
+                const varN = schemaVarName(sName);
+                emittedVarNames.add(varN);
+                const zodCode = generatedCode.get(sName);
+                if (forwardRefs.has(sName)) {
+                    lines.push(`const _${varN} = ${zodCode}`);
+                }
+                else {
+                    lines.push(`const ${varN} = ${zodCode}`);
+                }
+                lines.push('');
+            }
+        }
+    }
     // Build Input schema (exported for pikku schema discovery)
-    if (hasInput) {
-        const inputCode = buildInputSchema(parsed, ctx);
+    if (hasInput && inputCode) {
         lines.push(`export const ${inputName} = ${inputCode}`);
         lines.push('');
     }
     // Build Output schema (exported for pikku schema discovery)
-    if (parsed.responseSchema) {
-        const outputCode = buildOutputSchema(parsed.responseSchema, ctx);
+    if (parsed.responseSchema && outputCode) {
         lines.push(`export const ${outputName} = ${outputCode}`);
         lines.push('');
     }
@@ -157,9 +615,13 @@ function generateFunctionFile(named, parsed, vars, ctx, spec, flags) {
     if (flags.mcp) {
         funcConfig.push('  mcp: true,');
     }
-    const funcParams = hasInput ? `{ ${camelName} }, data` : `{ ${camelName} }`;
+    // Bug 3: Avoid duplicate identifier when camelName is 'data' (TS2300)
+    const inputParamName = camelName === 'data' ? 'inputData' : 'data';
+    const funcParams = hasInput
+        ? `{ ${camelName} }, ${inputParamName}`
+        : `{ ${camelName} }`;
     const returnCast = parsed.responseSchema ? ' as any' : '';
-    funcConfig.push(`  func: async (${funcParams}) => {`, `    return ${camelName}.call(${JSON.stringify(method)}, ${JSON.stringify(parsed.path)}${hasInput ? ', data' : ''})${returnCast}`, '  },');
+    funcConfig.push(`  func: async (${funcParams}) => {`, `    return ${camelName}.call(${JSON.stringify(method)}, ${JSON.stringify(parsed.path)}${hasInput ? `, ${inputParamName}` : ''})${returnCast}`, '  },');
     lines.push(`export const ${named.functionName} = pikkuSessionlessFunc({`);
     lines.push(funcConfig.join('\n'));
     lines.push('})');
@@ -168,35 +630,55 @@ function generateFunctionFile(named, parsed, vars, ctx, spec, flags) {
 }
 function buildInputSchema(parsed, ctx) {
     const props = [];
-    for (const param of parsed.pathParams) {
-        props.push(formatParamProp(param, ctx));
+    // Track which parameter names have been emitted to prevent duplicates.
+    // When shared path-level params and operation-level params overlap
+    // (e.g. both define "Version"), the later (operation-level) one wins.
+    const emittedNames = new Set();
+    // Deduplicate params: operation-level params override shared path-level
+    // params with the same name. Build deduplicated lists per category.
+    function deduplicateParams(params) {
+        const seen = new Map();
+        for (const param of params) {
+            seen.set(param.name, param); // last wins (operation-level comes after shared)
+        }
+        return [...seen.values()];
     }
-    for (const param of parsed.queryParams) {
-        props.push(formatParamProp(param, ctx));
+    const useCamel = !!ctx.camelCase;
+    for (const param of deduplicateParams(parsed.pathParams)) {
+        if (!emittedNames.has(param.name)) {
+            emittedNames.add(param.name);
+            props.push(formatParamProp(param, ctx, useCamel));
+        }
     }
-    for (const param of parsed.headerParams) {
-        props.push(formatParamProp(param, ctx));
+    for (const param of deduplicateParams(parsed.queryParams)) {
+        if (!emittedNames.has(param.name)) {
+            emittedNames.add(param.name);
+            props.push(formatParamProp(param, ctx, useCamel));
+        }
+    }
+    for (const param of deduplicateParams(parsed.headerParams)) {
+        if (!emittedNames.has(param.name)) {
+            emittedNames.add(param.name);
+            props.push(formatParamProp(param, ctx, useCamel));
+        }
     }
     if (parsed.requestBody) {
         if (parsed.requestBody.properties) {
-            const paramNames = new Set([
-                ...parsed.pathParams.map((p) => p.name),
-                ...parsed.queryParams.map((p) => p.name),
-                ...parsed.headerParams.map((p) => p.name),
-            ]);
             const requiredSet = new Set(parsed.requestBody.required ?? []);
             for (const [key, propSchema] of Object.entries(parsed.requestBody.properties)) {
                 // Skip readOnly properties from input
                 if (propSchema.readOnly)
                     continue;
-                // Skip body properties that collide with path/query/header params
-                if (paramNames.has(key)) {
+                // Skip body properties that collide with already-emitted params
+                if (emittedNames.has(key)) {
                     console.warn(`[openapi] Skipping body property '${key}' — collides with path/query/header param`);
                     continue;
                 }
+                emittedNames.add(key);
                 const isOptional = !requiredSet.has(key);
                 const zodCode = schemaToZod(propSchema, ctx, { optional: isOptional });
-                props.push(`  ${safeKey(key)}: ${zodCode},`);
+                const outputKey = useCamel ? snakeToCamel(key) : key;
+                props.push(`  ${safeKey(outputKey)}: ${zodCode},`);
             }
         }
         else {
@@ -206,29 +688,35 @@ function buildInputSchema(parsed, ctx) {
     }
     return `z.object({\n${props.join('\n')}\n})`;
 }
-function formatParamProp(param, ctx) {
+function formatParamProp(param, ctx, camelCase = false) {
     const zodCode = schemaToZod(param.schema, ctx, { optional: !param.required });
     let descParts = [];
     if (param.description)
-        descParts.push(param.description);
+        descParts.push(param.description.replace(/\*\//g, '* /'));
     if (param.example !== undefined)
         descParts.push(`Example: ${JSON.stringify(param.example)}`);
     const desc = descParts.length > 0
         ? `${zodCode}.describe(${JSON.stringify(descParts.join('. '))})`
         : zodCode;
-    return `  ${safeKey(param.name)}: ${desc},`;
+    const outputKey = camelCase ? snakeToCamel(param.name) : param.name;
+    return `  ${safeKey(outputKey)}: ${desc},`;
 }
 function buildOutputSchema(schema, ctx) {
-    // For output schemas, filter out writeOnly properties
+    // For output schemas, filter out writeOnly properties.
+    // Only create a filtered copy if there are actually writeOnly properties,
+    // to preserve object identity for schema identity map matching.
     if (schema.properties) {
-        const filteredProps = {};
-        for (const [key, propSchema] of Object.entries(schema.properties)) {
-            if (!propSchema.writeOnly) {
-                filteredProps[key] = propSchema;
+        const hasWriteOnly = Object.values(schema.properties).some((p) => p.writeOnly);
+        if (hasWriteOnly) {
+            const filteredProps = {};
+            for (const [key, propSchema] of Object.entries(schema.properties)) {
+                if (!propSchema.writeOnly) {
+                    filteredProps[key] = propSchema;
+                }
             }
+            const filteredSchema = { ...schema, properties: filteredProps };
+            return schemaToZod(filteredSchema, ctx);
         }
-        const filteredSchema = { ...schema, properties: filteredProps };
-        return schemaToZod(filteredSchema, ctx);
     }
     return schemaToZod(schema, ctx);
 }
@@ -241,7 +729,8 @@ function generateIndexFile(functionExports) {
     return lines.join('\n');
 }
 function generateServiceFile(spec, opPairs, vars, flags) {
-    const { name, pascalName, screamingName, displayName } = vars;
+    const { name, pascalName, screamingName } = vars;
+    const displayName = vars.displayName.replace(/'/g, '');
     const lines = [];
     // Always import all error classes used in the switch statement
     const allErrorClasses = new Set(Object.values(STATUS_TO_ERROR));
@@ -296,6 +785,20 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     }
     lines.push(`const ROUTES: Record<string, { path: string[], query: string[], headers: string[], errors?: Record<number, string> }> = ${JSON.stringify(routes, null, 2)}`);
     lines.push('');
+    if (flags.camelCase) {
+        lines.push('function _toSnakeCase(data: Record<string, unknown>): Record<string, unknown> {');
+        lines.push('  return Object.fromEntries(');
+        lines.push('    Object.entries(data).map(([k, v]) => [k.replace(/[A-Z]/g, c => `_${c.toLowerCase()}`), v])');
+        lines.push('  )');
+        lines.push('}');
+        lines.push('');
+        lines.push('function _toCamelCase(data: Record<string, unknown>): Record<string, unknown> {');
+        lines.push('  return Object.fromEntries(');
+        lines.push('    Object.entries(data).map(([k, v]) => [k.replace(/[-_]+(.)/g, (_, c) => c.toUpperCase()), v])');
+        lines.push('  )');
+        lines.push('}');
+        lines.push('');
+    }
     // Class declaration
     lines.push(`export class ${pascalName}Service {`);
     lines.push('  private baseUrl: string');
@@ -337,6 +840,9 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     lines.push('    path: string,');
     lines.push('    data?: Record<string, unknown>');
     lines.push('  ): Promise<T> {');
+    if (flags.camelCase) {
+        lines.push('    const rawData = data ? _toSnakeCase(data) : data');
+    }
     lines.push('    const route = ROUTES[`${method} ${path}`]');
     lines.push('    let endpoint = path');
     lines.push('    let body: Record<string, unknown> | undefined');
@@ -345,29 +851,31 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     lines.push("      'Content-Type': 'application/json',");
     lines.push('    }');
     lines.push('');
-    lines.push('    if (data && route) {');
+    // When camelCase flag is on, use rawData (snake_case converted) for route matching
+    const dataVar = flags.camelCase ? 'rawData' : 'data';
+    lines.push(`    if (${dataVar} && route) {`);
     lines.push('      // Interpolate path params');
     lines.push('      for (const param of route.path) {');
-    lines.push('        if (data[param] !== undefined) {');
-    lines.push('          endpoint = endpoint.replace(`{${param}}`, String(data[param]))');
+    lines.push(`        if (${dataVar}[param] !== undefined) {`);
+    lines.push(`          endpoint = endpoint.replace(\`{\${param}}\`, String(${dataVar}[param]))`);
     lines.push('        }');
     lines.push('      }');
     lines.push('      // Extract query params');
     lines.push('      for (const param of route.query) {');
-    lines.push('        if (data[param] !== undefined) {');
-    lines.push('          query[param] = String(data[param])');
+    lines.push(`        if (${dataVar}[param] !== undefined) {`);
+    lines.push(`          query[param] = String(${dataVar}[param])`);
     lines.push('        }');
     lines.push('      }');
     lines.push('      // Extract header params');
     lines.push('      for (const param of route.headers) {');
-    lines.push('        if (data[param] !== undefined) {');
-    lines.push('          headers[param] = String(data[param])');
+    lines.push(`        if (${dataVar}[param] !== undefined) {`);
+    lines.push(`          headers[param] = String(${dataVar}[param])`);
     lines.push('        }');
     lines.push('      }');
     lines.push('      // Everything else goes into body');
     lines.push('      const pathQueryHeaders = new Set([...route.path, ...route.query, ...route.headers])');
     lines.push('      const remaining = Object.fromEntries(');
-    lines.push('        Object.entries(data).filter(([k]) => !pathQueryHeaders.has(k))');
+    lines.push(`        Object.entries(${dataVar}).filter(([k]) => !pathQueryHeaders.has(k))`);
     lines.push('      )');
     lines.push('      if (Object.keys(remaining).length > 0) {');
     lines.push('        body = remaining');
@@ -451,14 +959,21 @@ function generateServiceFile(spec, opPairs, vars, flags) {
     lines.push('');
     lines.push('    const text = await response.text()');
     lines.push('    if (!text) return {} as T');
-    lines.push('    return JSON.parse(text) as T');
+    if (flags.camelCase) {
+        lines.push('    const result = JSON.parse(text)');
+        lines.push('    return (typeof result === "object" && result !== null && !Array.isArray(result) ? _toCamelCase(result) : result) as T');
+    }
+    else {
+        lines.push('    return JSON.parse(text) as T');
+    }
     lines.push('  }');
     lines.push('}');
     lines.push('');
     return lines.join('\n');
 }
 function generateVariableFile(spec, vars) {
-    const { camelName, screamingName, displayName } = vars;
+    const { camelName, screamingName } = vars;
+    const displayName = vars.displayName.replace(/'/g, '');
     const serverUrls = spec.serverUrls.length > 0 ? spec.serverUrls : [];
     const defaultUrl = serverUrls[0];
     const lines = [];
@@ -466,8 +981,13 @@ function generateVariableFile(spec, vars) {
     lines.push("import { wireVariable } from '@pikku/core/variable'");
     lines.push('');
     const schemaVarName = `${camelName}BaseUrlSchema`;
-    const urlsLiteral = serverUrls.map((u) => JSON.stringify(u)).join(', ');
-    lines.push(`export const ${schemaVarName} = z.enum([${urlsLiteral}]).default(${JSON.stringify(defaultUrl)})`);
+    if (serverUrls.length > 0) {
+        const urlsLiteral = serverUrls.map((u) => JSON.stringify(u)).join(', ');
+        lines.push(`export const ${schemaVarName} = z.enum([${urlsLiteral}]).default(${JSON.stringify(defaultUrl)})`);
+    }
+    else {
+        lines.push(`export const ${schemaVarName} = z.string().describe('Base URL for the ${displayName} API')`);
+    }
     lines.push('');
     lines.push(`wireVariable({`);
     lines.push(`  name: '${screamingName}_BASE_URL',`);