rules:
  # 基础结构错误
  - id: MISSING_OPENAPI_VERSION
    pattern: openapi
    severity: critical
    category: syntax
    title: Missing OpenAPI Version
    description: OpenAPI document must specify the OpenAPI version.
    suggestions:
      - description: Add openapi field with version 3.0.x or 3.1.x
        codeExample: '"openapi": "3.0.3"'
        documentationUrl: https://spec.openapis.org/oas/v3.0.3/#openapi-object

  - id: INVALID_OPENAPI_VERSION
    pattern: openapi
    severity: error
    category: compatibility
    title: Invalid OpenAPI Version
    description: OpenAPI version should be 3.0.x or 3.1.x for proper support.
    suggestions:
      - description: Use a supported OpenAPI version
        codeExample: '"openapi": "3.0.3"'

  # Info 对象错误
  - id: MISSING_INFO_TITLE
    pattern: info.title
    severity: error
    category: validation
    title: Missing API Title
    description: API title is required in the info object.
    suggestions:
      - description: Add a descriptive title for your API
        codeExample: '"title": "My API"'

  - id: MISSING_INFO_VERSION
    pattern: info.version
    severity: error
    category: validation
    title: Missing API Version
    description: API version is required in the info object.
    suggestions:
      - description: Add a version number using semantic versioning
        codeExample: '"version": "1.0.0"'
        documentationUrl: https://semver.org/

  # Paths 错误
  - id: EMPTY_PATHS
    pattern: paths
    severity: error
    category: validation
    title: Empty Paths Object
    description: OpenAPI document must contain at least one path.
    suggestions:
      - description: Add at least one API endpoint
        codeExample: '"/users": { "get": { "responses": { "200": { "description": "Success" } } } }'

  - id: INVALID_PATH_FORMAT
    pattern: paths.*
    severity: error
    category: syntax
    title: Invalid Path Format
    description: Path must start with a forward slash.
    suggestions:
      - description: Ensure path starts with /
        codeExample: '"/users" instead of "users"'

  - id: MISSING_OPERATION_RESPONSES
    pattern: paths.*.*.responses
    severity: error
    category: validation
    title: Missing Operation Responses
    description: Every operation must define at least one response.
    suggestions:
      - description: Add at least a default response
        codeExample: '"responses": { "200": { "description": "Success" } }'

  # 参数错误
  - id: PATH_PARAMETER_NOT_REQUIRED
    pattern: paths.*.*.parameters.*
    severity: error
    category: validation
    title: Path Parameter Not Required
    description: Path parameters must be marked as required.
    suggestions:
      - description: Set required: true for path parameters
        codeExample: '"required": true'

  - id: MISSING_PARAMETER_NAME
    pattern: paths.*.*.parameters.*.name
    severity: error
    category: validation
    title: Missing Parameter Name
    description: Parameter must have a name.
    suggestions:
      - description: Add a name for the parameter
        codeExample: '"name": "userId"'

  # Schema 错误
  - id: MISSING_SCHEMA_TYPE
    pattern: components.schemas.*.type
    severity: warning
    category: schema
    title: Missing Schema Type
    description: Schema should specify a type for better code generation.
    suggestions:
      - description: Add a type field to the schema
        codeExample: '"type": "object"'

  - id: CIRCULAR_REFERENCE
    pattern: components.schemas.*
    severity: warning
    category: schema
    title: Circular Reference Detected
    description: Circular references can cause issues in code generation.
    suggestions:
      - description: Consider using allOf or breaking the circular dependency
        codeExample: '"allOf": [{ "$ref": "#/components/schemas/BaseModel" }]'

  # 安全方案错误
  - id: MISSING_SECURITY_SCHEME_TYPE
    pattern: components.securitySchemes.*.type
    severity: error
    category: security
    title: Missing Security Scheme Type
    description: Security scheme must specify a type.
    suggestions:
      - description: Add a type field (apiKey, http, oauth2, openIdConnect)
        codeExample: '"type": "apiKey"'

  - id: MISSING_API_KEY_NAME
    pattern: components.securitySchemes.*.name
    severity: error
    category: security
    title: Missing API Key Name
    description: API Key security scheme must specify a parameter name.
    suggestions:
      - description: Add name field for API key parameter
        codeExample: '"name": "X-API-Key"'

  - id: MISSING_API_KEY_LOCATION
    pattern: components.securitySchemes.*.in
    severity: error
    category: security
    title: Missing API Key Location
    description: API Key security scheme must specify where the key is located.
    suggestions:
      - description: Add in field (query, header, cookie)
        codeExample: '"in": "header"'

  # 响应错误
  - id: MISSING_RESPONSE_DESCRIPTION
    pattern: paths.*.*.responses.*.description
    severity: warning
    category: bestPractice
    title: Missing Response Description
    description: Response should have a description.
    suggestions:
      - description: Add a description for the response
        codeExample: '"description": "Successful operation"'

  - id: NO_SUCCESS_RESPONSE
    pattern: paths.*.*.responses
    severity: warning
    category: bestPractice
    title: No Success Response
    description: Operation should define at least one success response (2xx).
    suggestions:
      - description: Add a success response
        codeExample: '"200": { "description": "Success" }'

  # 性能和最佳实践
  - id: MISSING_OPERATION_ID
    pattern: paths.*.*.operationId
    severity: warning
    category: bestPractice
    title: Missing Operation ID
    description: Operation should have an operationId for better code generation.
    suggestions:
      - description: Add a unique operationId
        codeExample: '"operationId": "getUsers"'

  - id: MISSING_OPERATION_SUMMARY
    pattern: paths.*.*.summary
    severity: info
    category: bestPractice
    title: Missing Operation Summary
    description: Operation should have a summary for better documentation.
    suggestions:
      - description: Add a brief summary
        codeExample: '"summary": "Get all users"'

  - id: LARGE_SCHEMA_OBJECT
    pattern: components.schemas.*
    severity: info
    category: performance
    title: Large Schema Object
    description: Schema has many properties, consider breaking it down.
    suggestions:
      - description: Consider using composition with allOf
        codeExample: '"allOf": [{ "$ref": "#/components/schemas/BaseModel" }, { "type": "object", "properties": {...} }]'

  # 媒体类型错误
  - id: MISSING_CONTENT_TYPE
    pattern: paths.*.*.requestBody.content
    severity: warning
    category: validation
    title: Missing Content Type
    description: Request body should specify at least one content type.
    suggestions:
      - description: Add a content type
        codeExample: '"application/json": { "schema": {...} }'

  - id: INCONSISTENT_CONTENT_TYPES
    pattern: paths.*
    severity: info
    category: bestPractice
    title: Inconsistent Content Types
    description: API uses different content types across operations.
    suggestions:
      - description: Consider standardizing on common content types
        codeExample: Use application/json consistently