GraphQL schema breaking change preflight gate

id: graphql-schema-breaking-change-preflight-gate
namespace: company.governance

inputs:
  - id: staging_graphql_url
    type: STRING
    displayName: Staging GraphQL Endpoint URL
    defaults: "https://spacex-production.up.railway.app/"
    description: Staging or release-candidate GraphQL endpoint about to be deployed
      to production.

  - id: production_graphql_url
    type: STRING
    displayName: Production GraphQL Endpoint URL
    defaults: "https://spacex-production.up.railway.app/"
    description: Current production GraphQL endpoint serving active client applications.

  - id: fail_on_breaking_changes
    type: BOOL
    displayName: Fail on Breaking Changes
    defaults: true
    description: Whether to fail execution when breaking schema modifications are
      detected to halt CI/CD deployment pipelines.

triggers:
  - id: pre_deployment_audit_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: Daily pre-release schema regression sweep comparing staging against
      production. Shipped disabled by default.
    cron: "0 6 * * 1-5"
    disabled: true

tasks:
  - id: fetch_production_schema
    type: io.kestra.plugin.graphql.Request
    description: Fetch production GraphQL schema type signatures via introspection.
    uri: "{{ inputs.production_graphql_url }}"
    headers:
      Authorization: "Bearer {{ secret('GRAPHQL_PROD_TOKEN') }}"
      Content-Type: "application/json"
      User-Agent: "Kestra-Schema-Preflight/1.0"
    failOnGraphQLErrors: false
    query: |
      query IntrospectTypes {
        __schema {
          types {
            name
            kind
            fields {
              name
              args {
                name
              }
            }
          }
        }
      }
    options:
      allowFailed: true

  - id: fetch_staging_schema
    type: io.kestra.plugin.graphql.Request
    description: Fetch staging GraphQL schema type signatures via introspection for
      release preflight comparison.
    uri: "{{ inputs.staging_graphql_url }}"
    headers:
      Authorization: "Bearer {{ secret('GRAPHQL_STAGING_TOKEN') }}"
      Content-Type: "application/json"
      User-Agent: "Kestra-Schema-Preflight/1.0"
    failOnGraphQLErrors: false
    query: |
      query IntrospectTypes {
        __schema {
          types {
            name
            kind
            fields {
              name
              args {
                name
              }
            }
          }
        }
      }
    options:
      allowFailed: true

  - id: detect_schema_breaking_changes
    type: io.kestra.plugin.scripts.python.Script
    description: Compare production and staging introspection payloads to detect
      deleted types and removed fields.
    taskRunner:
      type: io.kestra.plugin.core.runner.Process
    env:
      PROD_SCHEMA_JSON: "{{ outputs.fetch_production_schema.body | toJson }}"
      STAGING_SCHEMA_JSON: "{{ outputs.fetch_staging_schema.body | toJson }}"
    script: |
      import os
      import json

      prod_raw = json.loads(os.environ.get("PROD_SCHEMA_JSON", "{}"))
      staging_raw = json.loads(os.environ.get("STAGING_SCHEMA_JSON", "{}"))

      prod_types = (prod_raw.get("__schema") or {}).get("types") or []
      staging_types = (staging_raw.get("__schema") or {}).get("types") or []

      # Filter out internal introspection types (__Directive, __Schema, etc.)
      prod_map = {
          t["name"]: {f["name"] for f in (t.get("fields") or [])}
          for t in prod_types
          if t.get("name") and not t["name"].startswith("__") and t.get("kind") in ["OBJECT", "INTERFACE"]
      }

      staging_map = {
          t["name"]: {f["name"] for f in (t.get("fields") or [])}
          for t in staging_types
          if t.get("name") and not t["name"].startswith("__") and t.get("kind") in ["OBJECT", "INTERFACE"]
      }

      breaking_changes = []

      # 1. Check for removed types
      for type_name, prod_fields in prod_map.items():
          if type_name not in staging_map:
              breaking_changes.append(f"Removed type '{type_name}' entirely")
          else:
              removed_fields = prod_fields - staging_map[type_name]
              for rf in sorted(removed_fields):
                  breaking_changes.append(f"Removed field '{type_name}.{rf}'")

      breaking_count = len(breaking_changes)
      formatted_summary = "\\n".join([f"• {change}" for change in breaking_changes]) if breaking_changes else "No breaking changes detected."

      output_payload = {
          "breaking_changes_count": breaking_count,
          "breaking_changes": breaking_changes,
          "breaking_summary": formatted_summary,
          "is_backward_compatible": breaking_count == 0
      }

      print(f'::{"outputs": {json.dumps(output_payload)}}::')

  - id: evaluate_breaking_contract
    type: io.kestra.plugin.core.flow.If
    description: Evaluate whether detected breaking schema changes exceed zero tolerance.
    condition: "{{
      outputs.detect_schema_breaking_changes.vars.breaking_changes_count > 0 }}"
    then:
      - id: alert_breaking_changes
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Dispatch high-priority Slack incident alert itemizing breaking
          schema diffs to API Governance and Frontend teams.
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {
            "text": "🚨 *GRAPHQL SCHEMA BREAKING CHANGE GATE TRIGGERED* 🚨\n\n*Staging Endpoint:* `{{ inputs.staging_graphql_url }}`\n*Production Endpoint:* `{{ inputs.production_graphql_url }}`\n*Breaking Changes Count:* {{ outputs.detect_schema_breaking_changes.vars.breaking_changes_count }}\n\n*Violations Detected:*\n{{ outputs.detect_schema_breaking_changes.vars.breaking_summary }}\n\n*Execution ID:* {{ execution.id }}\n*Action Required:* Deprecate fields gracefully using @deprecated rather than removing them immediately to prevent client application crashes."
          }

      - id: check_fail_policy
        type: io.kestra.plugin.core.flow.If
        description: Halt pipeline when fail_on_breaking_changes is enabled to block
          deployment.
        condition: "{{ inputs.fail_on_breaking_changes }}"
        then:
          - id: halt_deployment_gate
            type: io.kestra.plugin.core.execution.Fail
            description: Fail execution to gate downstream Kubernetes, ECS, or serverless
              deployment pipelines.
    else:
      - id: log_contract_compatible
        type: io.kestra.plugin.core.log.Log
        description: Log backward-compatible schema status when zero removed types or
          fields are found.
        message: "SUCCESS: Staging GraphQL schema is 100% backward-compatible with
          production. No removed types or fields detected."

  - id: log_preflight_summary
    type: io.kestra.plugin.core.log.Log
    description: Record final audit metrics for API architecture governance.
    message: "GraphQL schema preflight gate completed. Breaking changes count: {{
      outputs.detect_schema_breaking_changes.vars.breaking_changes_count }}."

errors:
  - id: alert_on_preflight_error
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert API Governance channel if staging or production introspection
      endpoint fails to respond.
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "⚠️ *GraphQL Schema Gate Error*: Execution `{{ execution.id }}` failed to introspect staging or production GraphQL endpoints. Check token permissions and network connectivity."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.detect_schema_breaking_changes.vars.breaking_changes_count >
      0 ? 'BREAKING_CHANGES_DETECTED' : 'COMPATIBLE' }}"
  - id: breaking_count
    type: INT
    value: "{{ outputs.detect_schema_breaking_changes.vars.breaking_changes_count }}"