@xyd-js/openapi2opencli 0.0.0-canary-4287eee-20260630010340

package/__fixtures__/3.nested/output.json

@@ -0,0 +1,196 @@
+{
+  "opencli": "1.0.0",
+  "info": {
+    "title": "stores-api",
+    "version": "1.0.0"
+  },
+  "x-openapi": {
+    "servers": [
+      "https://api.stores.test/v2"
+    ]
+  },
+  "commands": [
+    {
+      "name": "stores",
+      "commands": [
+        {
+          "name": "items",
+          "commands": [
+            {
+              "name": "list",
+              "description": "List items in a store.",
+              "arguments": [
+                {
+                  "name": "store-id",
+                  "required": true
+                }
+              ],
+              "options": [
+                {
+                  "name": "limit",
+                  "group": "query",
+                  "arguments": [
+                    {
+                      "name": "integer"
+                    }
+                  ]
+                }
+              ],
+              "x-openapi": {
+                "method": "get",
+                "path": "/stores/{store_id}/items",
+                "operationId": "listStoreItems",
+                "params": [
+                  {
+                    "in": "path",
+                    "name": "store_id",
+                    "from": "argument:store-id",
+                    "required": true
+                  },
+                  {
+                    "in": "query",
+                    "name": "limit",
+                    "from": "option:limit"
+                  }
+                ]
+              }
+            },
+            {
+              "name": "create",
+              "description": "Create an item in a store.",
+              "arguments": [
+                {
+                  "name": "store-id",
+                  "required": true
+                }
+              ],
+              "options": [
+                {
+                  "name": "sku",
+                  "group": "body",
+                  "required": true,
+                  "arguments": [
+                    {
+                      "name": "string"
+                    }
+                  ]
+                },
+                {
+                  "name": "quantity",
+                  "group": "body",
+                  "arguments": [
+                    {
+                      "name": "integer"
+                    }
+                  ]
+                }
+              ],
+              "x-openapi": {
+                "method": "post",
+                "path": "/stores/{store_id}/items",
+                "operationId": "createStoreItem",
+                "contentType": "application/json",
+                "params": [
+                  {
+                    "in": "path",
+                    "name": "store_id",
+                    "from": "argument:store-id",
+                    "required": true
+                  }
+                ],
+                "body": {
+                  "style": "flatten",
+                  "contentType": "application/json",
+                  "properties": [
+                    {
+                      "name": "sku",
+                      "from": "option:sku",
+                      "jsonPath": "sku",
+                      "encoding": "string",
+                      "required": true
+                    },
+                    {
+                      "name": "quantity",
+                      "from": "option:quantity",
+                      "jsonPath": "quantity",
+                      "encoding": "integer"
+                    }
+                  ]
+                }
+              }
+            },
+            {
+              "name": "retrieve",
+              "aliases": [
+                "get"
+              ],
+              "description": "Retrieve a store item.",
+              "arguments": [
+                {
+                  "name": "store-id",
+                  "required": true
+                },
+                {
+                  "name": "item-id",
+                  "required": true
+                }
+              ],
+              "x-openapi": {
+                "method": "get",
+                "path": "/stores/{store_id}/items/{item_id}",
+                "operationId": "retrieveStoreItem",
+                "params": [
+                  {
+                    "in": "path",
+                    "name": "store_id",
+                    "from": "argument:store-id",
+                    "required": true
+                  },
+                  {
+                    "in": "path",
+                    "name": "item_id",
+                    "from": "argument:item-id",
+                    "required": true
+                  }
+                ]
+              }
+            },
+            {
+              "name": "archive",
+              "description": "Archive a store item.",
+              "arguments": [
+                {
+                  "name": "store-id",
+                  "required": true
+                },
+                {
+                  "name": "item-id",
+                  "required": true
+                }
+              ],
+              "x-openapi": {
+                "method": "post",
+                "path": "/stores/{store_id}/items/{item_id}/archive",
+                "operationId": "archiveStoreItem",
+                "params": [
+                  {
+                    "in": "path",
+                    "name": "store_id",
+                    "from": "argument:store-id",
+                    "required": true
+                  },
+                  {
+                    "in": "path",
+                    "name": "item_id",
+                    "from": "argument:item-id",
+                    "required": true
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/__fixtures__/4.body-flatten/input.yaml

@@ -0,0 +1,61 @@
+openapi: 3.0.3
+info:
+  title: Chat API
+  version: 1.0.0
+servers:
+  - url: https://api.chat.test/v1
+security:
+  - bearerAuth: []
+paths:
+  /chat/completions:
+    post:
+      operationId: createChatCompletion
+      summary: Creates a model response for the given chat conversation.
+      tags:
+        - Chat
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [model, messages]
+              properties:
+                model:
+                  type: string
+                  description: ID of the model to use.
+                  enum: [gpt-4o, gpt-4o-mini, o3]
+                messages:
+                  type: array
+                  description: A list of messages comprising the conversation.
+                  items:
+                    type: object
+                    properties:
+                      role:
+                        type: string
+                      content:
+                        type: string
+                temperature:
+                  type: number
+                  default: 1
+                  description: Sampling temperature.
+                stop:
+                  type: array
+                  items:
+                    type: string
+                stream:
+                  type: boolean
+                  default: false
+                response_format:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+      responses:
+        "200":
+          description: OK
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer

package/__fixtures__/4.body-flatten/output.json

@@ -0,0 +1,153 @@
+{
+  "opencli": "1.0.0",
+  "info": {
+    "title": "chat-api",
+    "version": "1.0.0"
+  },
+  "x-openapi": {
+    "servers": [
+      "https://api.chat.test/v1"
+    ],
+    "security": [
+      {
+        "type": "http",
+        "kind": "bearer",
+        "envVar": "CHAT_API_API_KEY",
+        "scheme": "bearer"
+      }
+    ]
+  },
+  "commands": [
+    {
+      "name": "chat",
+      "commands": [
+        {
+          "name": "completions",
+          "commands": [
+            {
+              "name": "create",
+              "description": "Creates a model response for the given chat conversation.",
+              "options": [
+                {
+                  "name": "model",
+                  "group": "body",
+                  "required": true,
+                  "description": "ID of the model to use.",
+                  "arguments": [
+                    {
+                      "name": "string",
+                      "acceptedValues": [
+                        "gpt-4o",
+                        "gpt-4o-mini",
+                        "o3"
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "name": "messages",
+                  "group": "body",
+                  "required": true,
+                  "description": "A list of messages comprising the conversation.",
+                  "arguments": [
+                    {
+                      "name": "json",
+                      "arity": {
+                        "minimum": 0
+                      }
+                    }
+                  ]
+                },
+                {
+                  "name": "temperature",
+                  "group": "body",
+                  "description": "Sampling temperature.",
+                  "arguments": [
+                    {
+                      "name": "number"
+                    }
+                  ]
+                },
+                {
+                  "name": "stop",
+                  "group": "body",
+                  "arguments": [
+                    {
+                      "name": "string",
+                      "arity": {
+                        "minimum": 0
+                      }
+                    }
+                  ]
+                },
+                {
+                  "name": "stream",
+                  "group": "body"
+                },
+                {
+                  "name": "response-format",
+                  "group": "body",
+                  "arguments": [
+                    {
+                      "name": "json"
+                    }
+                  ]
+                }
+              ],
+              "x-openapi": {
+                "method": "post",
+                "path": "/chat/completions",
+                "operationId": "createChatCompletion",
+                "contentType": "application/json",
+                "body": {
+                  "style": "flatten",
+                  "contentType": "application/json",
+                  "properties": [
+                    {
+                      "name": "model",
+                      "from": "option:model",
+                      "jsonPath": "model",
+                      "encoding": "string",
+                      "required": true
+                    },
+                    {
+                      "name": "messages",
+                      "from": "option:messages",
+                      "jsonPath": "messages",
+                      "encoding": "array",
+                      "required": true
+                    },
+                    {
+                      "name": "temperature",
+                      "from": "option:temperature",
+                      "jsonPath": "temperature",
+                      "encoding": "number"
+                    },
+                    {
+                      "name": "stop",
+                      "from": "option:stop",
+                      "jsonPath": "stop",
+                      "encoding": "array"
+                    },
+                    {
+                      "name": "stream",
+                      "from": "option:stream",
+                      "jsonPath": "stream",
+                      "encoding": "boolean"
+                    },
+                    {
+                      "name": "response_format",
+                      "from": "option:response-format",
+                      "jsonPath": "response_format",
+                      "encoding": "json"
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/__tests__/conformance.test.ts

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { deferencedOpenAPI } from '@xyd-js/openapi';
+
+import { openapi2opencli } from '../index';
+import { type Allowlist, diffSurfaces, opencliToSurface } from '../src/surface';
+import { parseOpenaiCli } from '../oracle/parseOpenaiCli';
+
+const ORACLE_DIR = path.join(__dirname, '../oracle');
+const SURFACE = path.join(ORACLE_DIR, 'surface.json');
+const FLOOR = path.join(ORACLE_DIR, 'coverage.floor.json');
+const REPORT = path.join(ORACLE_DIR, 'coverage.report.json');
+// The OpenAI OpenAPI spec is already vendored in @xyd-js/openapi's fixtures.
+const OPENAPI = path.join(__dirname, '../../xyd-openapi/__fixtures__/-2.complex.openai/input.yaml');
+
+const REFRESH = process.env.ORACLE_REFRESH === '1';
+
+// Known, intentional divergences (the burn-down backlog). Each needs a reason.
+const allowlist: Allowlist = {
+  // Stainless injects a pagination flag on list endpoints that isn't in the spec.
+  oracleOnlyFlags: ['max-items'],
+};
+
+// ---- Oracle refresh (network; opt-in) ------------------------------------
+describe.skipIf(!REFRESH)('oracle refresh (network)', () => {
+  it('fetch + parse openai-cli pkg/cmd → oracle/surface.json', async () => {
+    const head = await fetch('https://api.github.com/repos/openai/openai-cli/commits/main').then((r) => r.json());
+    const sha: string = head.sha;
+    const listing = await fetch(
+      `https://api.github.com/repos/openai/openai-cli/contents/pkg/cmd?ref=${sha}`,
+    ).then((r) => r.json());
+
+    const files: Record<string, string> = {};
+    for (const entry of listing as Array<{ name: string; download_url: string }>) {
+      if (!entry.name.endsWith('.go') || entry.name.endsWith('_test.go')) continue;
+      files[entry.name] = await fetch(entry.download_url).then((r) => r.text());
+    }
+
+    const surface = parseOpenaiCli(files);
+    fs.mkdirSync(ORACLE_DIR, { recursive: true });
+    fs.writeFileSync(SURFACE, `${JSON.stringify(surface, null, 2)}\n`);
+    fs.writeFileSync(
+      path.join(ORACLE_DIR, 'pins.json'),
+      `${JSON.stringify(
+        { repo: 'openai/openai-cli', commit: sha, files: Object.keys(files).length, commands: surface.commands.length },
+        null,
+        2,
+      )}\n`,
+    );
+    expect(surface.commands.length).toBeGreaterThan(50);
+  }, 180000);
+});
+
+// ---- Conformance (offline; reads committed surface.json) ------------------
+const hasOracle = fs.existsSync(SURFACE);
+
+describe.skipIf(!hasOracle)('conformance: openapi → opencli surface vs openai-cli', () => {
+  it('matches the oracle command surface above the coverage floor', async () => {
+    const oracle = JSON.parse(fs.readFileSync(SURFACE, 'utf8'));
+    const doc = await deferencedOpenAPI(OPENAPI);
+    if (!doc) throw new Error(`vendored openai-openapi not found at ${OPENAPI}`);
+
+    const spec = openapi2opencli(doc, { cliName: 'openai' });
+    const ours = opencliToSurface(spec);
+    const diff = diffSurfaces(ours, oracle, allowlist);
+
+    fs.writeFileSync(
+      REPORT,
+      `${JSON.stringify(
+        {
+          l0Coverage: Number(diff.l0Coverage.toFixed(4)),
+          l1Coverage: Number(diff.l1Coverage.toFixed(4)),
+          oracleCommands: diff.oracleCommandCount,
+          ourCommands: diff.oursCommandCount,
+          matched: diff.commandsMatched.length,
+          onlyOracle: diff.commandsOnlyOracle.length,
+          onlyOurs: diff.commandsOnlyOurs.length,
+          sampleOnlyOracle: diff.commandsOnlyOracle.slice(0, 15),
+          sampleOnlyOurs: diff.commandsOnlyOurs.slice(0, 15),
+          sampleFlagDiffs: diff.perCommand.slice(0, 15),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[conformance] L0 ${(diff.l0Coverage * 100).toFixed(1)}%  L1 ${(diff.l1Coverage * 100).toFixed(1)}%  ` +
+        `matched ${diff.commandsMatched.length}/${diff.oracleCommandCount} (ours ${diff.oursCommandCount})`,
+    );
+
+    const floor = fs.existsSync(FLOOR) ? JSON.parse(fs.readFileSync(FLOOR, 'utf8')).l0 : 0;
+    expect(diff.l0Coverage).toBeGreaterThanOrEqual(floor);
+  }, 180000);
+});