api-tools/tests/core/parse-refs.test.ts

import { describe, expect, it } from "vitest";
import { collectAsyncOperations } from "../../src/core/asyncapi";
import {
  parseApiDocument,
  validateApiDescription,
  validateOpenApi,
} from "../../src/core/parse";
import {
  createWorkspace,
  generateSchemaSample,
  resolveLocalReference,
} from "../../src/core/refs";

describe("OpenAPI parsing and local references", () => {
  it("parses JSON and YAML and performs focused validation", () => {
    const json = parseApiDocument(
      '{"openapi":"3.0.3","info":{"title":"A","version":"1"},"paths":{}}',
      "api.json",
    );
    const yaml = parseApiDocument(
      "openapi: 3.1.0\ninfo: { title: A, version: '1' }\npaths: {}\n",
      "api.yaml",
    );
    expect(json.format).toBe("json");
    expect(yaml.format).toBe("yaml");
    expect(validateOpenApi(yaml).some((item) => item.level === "error")).toBe(
      false,
    );
  });

  it("recognizes OpenAPI 3.2 QUERY and bounded additional operations", () => {
    const document = parseApiDocument(
      `openapi: 3.2.0
info: { title: Extended, version: '1' }
paths:
  /search:
    query: { responses: { '200': { description: ok } } }
    additionalOperations:
      COPY: { responses: { '204': { description: copied } } }
`,
      "extended.yaml",
    );
    expect(
      validateOpenApi(document).some((item) => item.level === "error"),
    ).toBe(false);
  });

  it("rejects dangerous YAML keys and alias expansion", () => {
    expect(() =>
      parseApiDocument("__proto__: { polluted: true }", "bad.yaml"),
    ).toThrow(/prohibited key/iu);
    const aliases = `x: &x [1, 2]\ny: [${Array.from({ length: 60 }, () => "*x").join(",")}]`;
    expect(() => parseApiDocument(aliases, "aliases.yaml")).toThrow(/alias/iu);
  });

  it("resolves supplied relative files and refuses remote references", () => {
    const entry = parseApiDocument(
      "openapi: 3.1.0\ninfo: {title: A, version: '1'}\npaths: {}\ncomponents: { schemas: { Pet: { $ref: 'schemas.yaml#/Pet' } } }",
      "openapi.yaml",
    );
    const schemas = parseApiDocument(
      "Pet: { type: object, properties: { name: { type: string } } }",
      "schemas.yaml",
    );
    const workspace = createWorkspace(entry, [schemas]);
    expect(
      resolveLocalReference(workspace, "schemas.yaml#/Pet").value,
    ).toMatchObject({ type: "object" });
    expect(() =>
      resolveLocalReference(workspace, "https://example.test/schema.json"),
    ).toThrow(/disabled/iu);
    expect(
      validateOpenApi(
        parseApiDocument(
          "openapi: 3.1.0\ninfo: {title: A, version: '1'}\npaths: {}\nx: {$ref: 'https://bad.test/x'}",
        ),
      ),
    ).toContainEqual(expect.objectContaining({ level: "error" }));
  });

  it("generates bounded samples and reports reference cycles", () => {
    const entry = parseApiDocument(
      '{"openapi":"3.1.0","info":{"title":"A","version":"1"},"paths":{},"components":{"schemas":{"Node":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/Node"}}}}}}',
      "openapi.json",
    );
    const workspace = createWorkspace(entry);
    const schema = resolveLocalReference(
      workspace,
      "#/components/schemas/Node",
    ).value;
    const sample = generateSchemaSample(workspace, schema);
    expect(sample.value).toMatchObject({
      next: { next: { $cycle: "openapi.json#/components/schemas/Node" } },
    });
    expect(sample.notices[0]).toMatch(/cycle/iu);
  });

  it("inventories AsyncAPI 3.1 channels, operations, and local message samples", () => {
    const document = parseApiDocument(
      `asyncapi: 3.1.0
info: { title: Events, version: '1' }
defaultContentType: application/json
servers:
  broker: { host: broker.example.test, protocol: mqtt }
channels:
  signedUp:
    address: users.signed-up
    messages:
      user: { $ref: '#/components/messages/User' }
operations:
  sendUser:
    action: send
    channel: { $ref: '#/channels/signedUp' }
components:
  messages:
    User:
      name: UserSignedUp
      payload:
        type: object
        properties: { id: { type: string, example: user-1 } }
`,
      "asyncapi.yaml",
    );
    expect(
      validateApiDescription(document).some((item) => item.level === "error"),
    ).toBe(false);
    expect(collectAsyncOperations(createWorkspace(document))).toEqual([
      expect.objectContaining({
        operationId: "sendUser",
        action: "send",
        address: "users.signed-up",
        protocols: ["mqtt"],
        messages: [
          expect.objectContaining({
            name: "UserSignedUp",
            payload: { id: "user-1" },
          }),
        ],
      }),
    ]);
  });

  it("retains focused AsyncAPI 2.x publish/subscribe support", () => {
    const document = parseApiDocument(
      `asyncapi: 2.6.0
info: { title: Legacy events, version: '1' }
channels:
  users:
    publish:
      operationId: publishUser
      message: { payload: { type: string, example: hello } }
`,
    );
    expect(collectAsyncOperations(createWorkspace(document))[0]).toMatchObject({
      action: "publish",
      address: "users",
      operationId: "publishUser",
      messages: [{ payload: "hello" }],
    });
  });
});