# Spectral ruleset for the TourScanner API contract (https://tourscanner.ai/openapi.json).
#
# Run it against the live spec:
#   npx @stoplight/spectral-cli lint https://tourscanner.ai/openapi.json --ruleset https://tourscanner.ai/spectral.yaml
#
# The base is Spectral's own OpenAPI ruleset. The rules below add what we hold our
# own spec to. Our spec passes every rule here with no results; tests/discovery.test.ts
# checks that this file stays in step with the contract.
extends: ["spectral:oas"]

rules:
  # ── error: the contract is broken or unusable without these ─────────────────
  tourscanner-operation-id-camel-case:
    description: operationId is camelCase, so generated SDK and tool names are predictable.
    severity: error
    given: "$.paths[*][*].operationId"
    then:
      function: casing
      functionOptions:
        type: camel

  tourscanner-error-response-documented:
    description: Every operation documents at least one error response (400, 401, 404 or 422).
    severity: error
    given: "$.paths[*][*].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ["400"]
            - required: ["401"]
            - required: ["404"]
            - required: ["422"]

  # ── warn: a consumer needs these to integrate without guessing ──────────────
  tourscanner-parameter-description:
    description: Every parameter says what it does.
    severity: warn
    given: "$.paths[*][*].parameters[*]"
    then:
      field: description
      function: truthy

  tourscanner-request-example:
    description: Every request body carries an example a client can send as it is.
    severity: warn
    given: "$.paths[*][*].requestBody.content[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ["example"]
            - required: ["examples"]

  tourscanner-schema-description:
    description: Every reusable schema is described.
    severity: warn
    given: "$.components.schemas[*]"
    then:
      field: description
      function: truthy

  tourscanner-security-scheme-description:
    description: The security scheme says how to obtain and send the key.
    severity: warn
    given: "$.components.securitySchemes[*]"
    then:
      field: description
      function: truthy

  # ── info: guidance, not a gate ──────────────────────────────────────────────
  tourscanner-summary-length:
    description: Operation summaries stay short enough for a list view.
    severity: info
    given: "$.paths[*][*].summary"
    then:
      function: length
      functionOptions:
        max: 80

  tourscanner-tag-description:
    description: Every tag is described.
    severity: info
    given: "$.tags[*]"
    then:
      field: description
      function: truthy

  tourscanner-terms-of-service:
    description: The spec links the terms of service.
    severity: info
    given: "$.info"
    then:
      field: termsOfService
      function: truthy
