gql-breaking-changes

name

gql-breaking-changes

description

Analyze GraphQL breaking changes between the public evitaDB demo server schema and the current local branch's schema. Builds the project, boots the local server, runs graphql-inspector via `tools/diff-graphql-schemas.sh`, and writes a prose summary of breaking changes and their client-facing implications. If the user provides a path to a downstream project that generates a GraphQL client from evitaDB's schema, the summary is tailored to that project specifically (TypeScript-heavy by default). Read-only: never modifies project code.

GQL Breaking Changes Analysis

Overview

This skill compares the GraphQL schema served by the public evitaDB demo (https://demo.evitadb.io/gql/evita) against the schema served by a local evitaDB server built from the current branch, and reports breaking changes together with their implications for API clients.

The intended use is to evaluate, before merging or releasing, how the current branch's API changes affect downstream consumers — in particular TypeScript applications that auto-generate a client from the published GraphQL schema.

Hard Rules

• Do NOT modify any project code. This skill is read-only on the evitaDB tree. It only builds, runs, and observes.
• Do NOT commit, push, or stage anything. No git writes.
• Do NOT touch files in a downstream client project if the user points at one — only read them to tailor the summary.
• If a required prerequisite (docker, curl, maven, network) is missing, stop and report to the user. Do not improvise a workaround that alters the tree.

When to Use

• The user asks for a GraphQL breaking-change analysis against the demo.
• The user asks "what would break for our clients if we released this?"
• The user mentions the diff-graphql-schemas.sh script and wants a human-readable report on top of it.

Inputs (ask up front if not given)

Before starting the workflow, use AskUserQuestion to collect anything the user did not supply explicitly:

1. Client project path (optional) — absolute path to a downstream project that generates a GraphQL client from the evitaDB schema. If provided, the summary in Step 5 is tailored to that project. If not, the summary discusses general TypeScript-client implications.
2. Original schema URL override (optional) — default https://demo.evitadb.io/gql/evita. Ask only if the user hinted they want to compare against something other than the public demo.
3. Skip build? (optional) — if the user says they already built the project in this shell session, you may skip Step 1. Otherwise always build, because the server jar must reflect the current branch.

Do not ask about the local URL — keep the script default (https://localhost:5555/gql/evita) unless the user explicitly overrides it. Do not ask about the output file — keep the script default (graphql-schema-diff.txt at the project root).

Workflow

Execute the steps in order. On any failure, stop, clean up any server you started (Step 6), and report to the user.

Step 1: Build the project

From the repository root:

mvn clean install -DskipTests

Skip JUnit tests — this skill compares schemas, it does not need the test suite green. -DskipTests still compiles test sources (which some modules rely on for packaging) but does not execute them.

This can still take several minutes. Run it in the foreground so its exit code is observable. If the build fails, stop and report the failing module — do not attempt fixes.

Skip this step only if the user explicitly confirmed the jar is already fresh.

Step 2: Start the local server in the background

The server script expects to be executed from the evita_server/ directory (paths inside the script are relative).

cd evita_server && bash ./run-server.sh

Run this with run_in_background: true via the Bash tool. Capture the background shell id — you will need it in Step 6 to stop the server.

Step 3: Wait until the server is ready

Poll the local GraphQL endpoint until it responds with a non-empty body. The schema download inside the diff script uses -k / --insecure, so the self-signed TLS certificate is expected and tolerated.

# Poll for up to ~120s. The server takes noticeable time to warm up,
# especially the first run after a clean build.
for i in $(seq 1 60); do
    if curl --silent --show-error --fail-with-body --insecure \
            --header 'Accept: application/graphql' \
            --output /dev/null \
            "https://localhost:5555/gql/evita"; then
        echo "server is up"
        break
    fi
    sleep 2
done

If the loop exits without a successful probe, stop the server (Step 6), dump the tail of its stdout/stderr for context, and report. Common causes: port 5555 occupied, missing data directory, previous server still running. Do not attempt to kill unrelated processes blindly — report what is bound to the port (lsof -i :5555) and let the user decide.

Step 4: Run the schema diff

From the repository root:

./tools/diff-graphql-schemas.sh

The script:

• downloads both schemas via curl --insecure,
• runs kamilkisiela/graphql-inspector via Docker,
• writes the full diff to graphql-schema-diff.txt at the project root,
• always exits 0 — a non-zero inspector exit code (printed on stdout) means breaking changes were found, which is the normal case here.

If the script itself fails (curl error, docker missing, schema download empty) stop, clean up, and report. Do not retry blindly.

Requirements the script checks for: curl, docker. If Docker is not running, the user will see a Docker daemon error — surface that verbatim.

Step 5: Analyze and summarize

Read graphql-schema-diff.txt in full. Its format is graphql-inspector's text output: each entry is tagged as breaking, dangerous, or non-breaking, followed by a description and a path.

Group findings into these categories and write a Markdown summary (printed to the user, not written to a file unless the user asks):

1. Breaking changes — ordered by severity:
   • Removed types / fields / enum values
   • Type narrowing (field type becomes more restrictive)
   • Required argument added to an existing field
   • Nullable field becoming non-nullable on inputs, or vice versa on outputs
   • Changed directive semantics that clients rely on
2. Dangerous changes — additions that can break permissive client codegen (e.g., new enum value in an output enum, new optional input field with no default).
3. Safe additions — new types, fields, args, enum values on inputs only, deprecations. Mention briefly; do not enumerate exhaustively.

For each breaking or dangerous entry, provide:

• The exact path from the inspector output (verbatim — do not paraphrase GraphQL identifiers).
• What the change is.
• Concrete client-side impact.
• Suggested remediation for the client (what the client author needs to change, and/or which evitaDB version introduces the change — if detectable from commit history, otherwise omit).

Tailoring the summary

• If the user supplied a client project path: read through that project (Glob + Grep — no writes) to find where GraphQL operations are defined and which types they consume. Typical signals:

  • *.graphql, *.gql, *.ts, *.tsx files with gql\...`orgraphql`...`` template literals
  • schema.graphql, generated *.generated.ts, __generated__/ directories
  • codegen.yml / codegen.ts / graphql.config.{ts,js,yml}
  • apollo.config.*, Relay compiler config, urql codegen For each breaking change, check whether the affected type, field, or enum value is actually referenced in the client. If it is not, say so explicitly ("no references found in <project>") — that is the most useful signal. If it is, point to the exact file(s) and describe the fix in terms of that project's codegen setup. In this mode, do not include generic TypeScript advice — only the project-specific impact.

• If no client project was supplied: give general implications for TypeScript clients, framed around the common codegen stacks (graphql-code-generator, Apollo, Relay, urql). Call out patterns that are likely to fail at build time vs. at runtime (e.g. removed enum value → TS exhaustiveness check breaks at compile time; nullable→non-nullable on output → runtime surprise if the client relied on null).

Report shape

Open with a one-line headline: "N breaking, M dangerous, K safe additions."

Then sections in this order, omitting any that are empty:

• ## Breaking changes
• ## Dangerous changes
• ## Safe additions (summary)
• ## Client impact — the tailored or general analysis described above
• ## Recommended next steps — short, actionable bullet list

Keep the full raw diff file on disk at graphql-schema-diff.txt and reference it at the end ("full machine-readable diff: ...").

Step 6: Stop the server

Always stop the background server before returning to the user, even if an earlier step failed.

# Preferred: kill the shell you started the server in (by background id)
# Fallback: kill the java process holding the debug agent on *:8005,
# which is unique to this script.
pkill -f 'evita-server.jar' || true

Confirm the port is free afterward (lsof -i :5555 returns nothing) and note it in the final output. If the server refuses to die, report the PID to the user — do not escalate to kill -9 without their say-so.

Output

The only artifact this skill writes to disk is the diff file produced by diff-graphql-schemas.sh itself (graphql-schema-diff.txt). The human summary goes into the chat. Do not create additional files unless the user asks.