@pikku/openapi-parser 0.12.10 → 0.12.12

package/CHANGELOG.md

@@ -1,11 +1,24 @@
 # @pikku/openapi-parser
 
+## 0.12.12
+
+### Patch Changes
+
+- d97f2a1: Always emit a description for generated addon functions (and their MCP tools). When an OpenAPI operation omits both `description` and `summary` (common), the generator now synthesizes one — a humanized `operationId` (with the `Controller` segment stripped), else `METHOD /path` — instead of emitting none. This removes the "MCP tool is missing a description" warnings and makes `--mcp`-exposed tools usable.
+
+## 0.12.11
+
+### Patch Changes
+
+- 41ce2cb: Upgrade to TypeScript 6 and raise the minimum Node.js version to 22.
+
+  All packages now build against `typescript@^6.0.3` and declare `engines.node >= 22`. Internal tooling (`ts-json-schema-generator`, `zod-to-ts`) was bumped to TypeScript 6-compatible releases.
+
 ## 0.12.10
 
 ### Patch Changes
 
 - 02fca80: Fix OpenAPI-to-addon codegen robustness across 2521 real-world specs (77% → 97.8% pass rate).
-
   - Cycle detection and depth limits in schema generation to prevent stack overflows
   - Schema partitioning: shared types file for multi-referenced schemas, inline for single-use (fixes crash on large specs)
   - Topological sort with z.lazy() for circular schema references

package/dist/codegen.js

@@ -27,12 +27,41 @@ const STATUS_TO_ERROR = {
 function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
+/**
+ * Turn an operationId like `contactsControllerGetContacts` (or snake/kebab
+ * variants) into a readable phrase — split camel/snake/kebab into words, drop
+ * noise segments ("controller"), and capitalize. Returns undefined if nothing
+ * usable remains.
+ */
+function humanizeOperationId(operationId) {
+    if (!operationId)
+        return undefined;
+    const words = operationId
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .split(/\s+/)
+        .map((w) => w.trim())
+        .filter((w) => w && w.toLowerCase() !== 'controller');
+    if (words.length === 0)
+        return undefined;
+    return capitalize(words.join(' ').toLowerCase());
+}
+/**
+ * A description for the generated function (and its MCP tool). Prefers the
+ * spec's `description`, then `summary`; when a spec omits both (common), a
+ * synthesized description is still emitted so no function — and no MCP tool —
+ * ships description-less: a humanized operationId, else "METHOD /path".
+ */
 function humanDescription(parsed) {
     const description = parsed.description?.trim();
     if (description && !GENERIC_SUMMARIES.has(description.toLowerCase())) {
         return capitalize(description);
     }
-    return undefined;
+    const summary = parsed.summary?.trim();
+    if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+        return capitalize(summary);
+    }
+    return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`;
 }
 function getErrorClassesForResponses(errorResponses) {
     const classes = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/openapi-parser",
-  "version": "0.12.10",
+  "version": "0.12.12",
   "description": "OpenAPI spec parser and code generator for Pikku",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -21,6 +21,6 @@
     "yaml": "^2.7.1"
   },
   "devDependencies": {
-    "typescript": "^5.9"
+    "typescript": "^6.0.3"
   }
 }

package/src/codegen.test.ts

@@ -780,3 +780,68 @@ describe('camelCase flag', () => {
     )
   })
 })
+
+// ---------------------------------------------------------------------------
+// Function/MCP-tool description synthesis (specs that omit descriptions)
+// ---------------------------------------------------------------------------
+describe('function description synthesis', () => {
+  test('synthesizes a description from operationId when the spec omits one', () => {
+    const spec = makeSpec({
+      operations: [
+        makeOp({
+          operationId: 'contactsControllerGetContacts',
+          method: 'get',
+          path: '/contacts',
+        }),
+      ],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+      mcp: true,
+    })
+    const funcFile = files['src/functions/contactsControllerGetContacts.function.ts']
+    assert.ok(funcFile, 'function file should exist')
+    assert.ok(
+      funcFile.includes('description: "Contacts get contacts"'),
+      'humanized operationId (Controller stripped) should be emitted as the description'
+    )
+    assert.ok(funcFile.includes('mcp: true'), 'mcp tool flag should be present')
+  })
+
+  test('falls back to "METHOD /path" when operationId is absent', () => {
+    const spec = makeSpec({
+      operations: [makeOp({ operationId: undefined, method: 'get', path: '/health' })],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+    })
+    const key = Object.keys(files).find((k) => k.startsWith('src/functions/'))
+    assert.ok(key, 'a function file should be generated')
+    assert.ok(
+      files[key].includes('description: "GET /health"'),
+      'should fall back to METHOD path when nothing else is available'
+    )
+  })
+
+  test('prefers the spec description over synthesis', () => {
+    const spec = makeSpec({
+      operations: [
+        makeOp({ operationId: 'getPet', description: 'Fetch a single pet by id' }),
+      ],
+    })
+
+    const files = generateAddonFromOpenAPI(spec, makeVars(), {
+      oauth: false,
+      secret: false,
+    })
+    const funcFile = files['src/functions/getPet.function.ts']
+    assert.ok(
+      funcFile.includes('description: "Fetch a single pet by id"'),
+      'the real spec description should win over the synthesized one'
+    )
+  })
+})

package/src/codegen.ts

@@ -69,12 +69,40 @@ function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
 
-function humanDescription(parsed: ParsedOperation): string | undefined {
+/**
+ * Turn an operationId like `contactsControllerGetContacts` (or snake/kebab
+ * variants) into a readable phrase — split camel/snake/kebab into words, drop
+ * noise segments ("controller"), and capitalize. Returns undefined if nothing
+ * usable remains.
+ */
+function humanizeOperationId(operationId?: string): string | undefined {
+  if (!operationId) return undefined
+  const words = operationId
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .split(/\s+/)
+    .map((w) => w.trim())
+    .filter((w) => w && w.toLowerCase() !== 'controller')
+  if (words.length === 0) return undefined
+  return capitalize(words.join(' ').toLowerCase())
+}
+
+/**
+ * A description for the generated function (and its MCP tool). Prefers the
+ * spec's `description`, then `summary`; when a spec omits both (common), a
+ * synthesized description is still emitted so no function — and no MCP tool —
+ * ships description-less: a humanized operationId, else "METHOD /path".
+ */
+function humanDescription(parsed: ParsedOperation): string {
   const description = parsed.description?.trim()
   if (description && !GENERIC_SUMMARIES.has(description.toLowerCase())) {
     return capitalize(description)
   }
-  return undefined
+  const summary = parsed.summary?.trim()
+  if (summary && !GENERIC_SUMMARIES.has(summary.toLowerCase())) {
+    return capitalize(summary)
+  }
+  return humanizeOperationId(parsed.operationId) ?? `${parsed.method.toUpperCase()} ${parsed.path}`
 }
 
 function getErrorClassesForResponses(

package/src/parse-openapi.test.ts

@@ -166,7 +166,11 @@ describe('parseOpenAPISpec — Swagger 2.0', () => {
         properties: {
           id: { type: 'integer', format: 'int64' },
           name: { type: 'string' },
-          status: { type: 'string', enum: ['available', 'sold'], description: 'pet status' },
+          status: {
+            type: 'string',
+            enum: ['available', 'sold'],
+            description: 'pet status',
+          },
         },
       },
     },
@@ -179,7 +183,12 @@ describe('parseOpenAPISpec — Swagger 2.0', () => {
           operationId: 'listPets',
           summary: 'List all pets',
           parameters: [
-            { in: 'query', name: 'status', type: 'string', description: 'Filter by status' },
+            {
+              in: 'query',
+              name: 'status',
+              type: 'string',
+              description: 'Filter by status',
+            },
           ],
           responses: {
             '200': {
@@ -254,7 +263,9 @@ describe('parseOpenAPISpec — Swagger 2.0', () => {
 
   test('extracts requestBody from body parameter', async () => {
     const spec = await parseOpenAPISpec(specPath)
-    const createPet = spec.operations.find(op => op.operationId === 'createPet')
+    const createPet = spec.operations.find(
+      (op) => op.operationId === 'createPet'
+    )
     assert.ok(createPet?.requestBody)
     assert.equal(createPet.requestBody.type, 'object')
     assert.ok(createPet.requestBody.properties?.name)
@@ -264,25 +275,27 @@ describe('parseOpenAPISpec — Swagger 2.0', () => {
 
   test('extracts responseSchema from Swagger 2.0 response', async () => {
     const spec = await parseOpenAPISpec(specPath)
-    const createPet = spec.operations.find(op => op.operationId === 'createPet')
+    const createPet = spec.operations.find(
+      (op) => op.operationId === 'createPet'
+    )
     assert.ok(createPet?.responseSchema)
     assert.equal(createPet.responseSchema.type, 'object')
 
-    const listPets = spec.operations.find(op => op.operationId === 'listPets')
+    const listPets = spec.operations.find((op) => op.operationId === 'listPets')
     assert.ok(listPets?.responseSchema)
     assert.equal(listPets.responseSchema.type, 'array')
   })
 
   test('extracts query params', async () => {
     const spec = await parseOpenAPISpec(specPath)
-    const listPets = spec.operations.find(op => op.operationId === 'listPets')
+    const listPets = spec.operations.find((op) => op.operationId === 'listPets')
     assert.equal(listPets?.queryParams.length, 1)
     assert.equal(listPets?.queryParams[0].name, 'status')
   })
 
   test('extracts path params', async () => {
     const spec = await parseOpenAPISpec(specPath)
-    const getPet = spec.operations.find(op => op.operationId === 'getPet')
+    const getPet = spec.operations.find((op) => op.operationId === 'getPet')
     assert.equal(getPet?.pathParams.length, 1)
     assert.equal(getPet?.pathParams[0].name, 'petId')
     assert.equal(getPet?.pathParams[0].required, true)
@@ -290,7 +303,9 @@ describe('parseOpenAPISpec — Swagger 2.0', () => {
 
   test('extracts error responses', async () => {
     const spec = await parseOpenAPISpec(specPath)
-    const createPet = spec.operations.find(op => op.operationId === 'createPet')
+    const createPet = spec.operations.find(
+      (op) => op.operationId === 'createPet'
+    )
     assert.equal(createPet?.errorResponses.length, 1)
     assert.equal(createPet?.errorResponses[0].statusCode, 400)
   })

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/codegen.ts","./src/index.ts","./src/naming.ts","./src/openapi-to-zod-schema.ts","./src/parse-openapi.ts","./src/zod-codegen.ts"],"version":"5.9.3"}
+{"root":["./src/codegen.ts","./src/index.ts","./src/naming.ts","./src/openapi-to-zod-schema.ts","./src/parse-openapi.ts","./src/zod-codegen.ts"],"version":"6.0.3"}