Warn when schema.graphql api_version mismatches extension TOML

[davejcameron]

WHY are these changes introduced?

When a developer changes api_version in their shopify.extension.toml, the local schema.graphql becomes stale. The build then fails with cryptic type errors from typegen, with no indication that the schema simply needs to be re-fetched. This is a common failure case when working with Shopify Functions.

WHAT is this pull request doing?

Adds a lightweight check at the start of buildFunctionExtension that reads the first 512 bytes of schema.graphql looking for the server-stamped @apiVersion directive (e.g. schema @apiVersion(version: "2025-04") {). If present and it doesn't match the TOML's api_version, a warning is printed before the build runs:

schema.graphql was generated for API version 2025-01 but your extension targets 2025-04. Run shopify app function schema to update.

If the directive isn't present (legacy schema files, or server hasn't adopted stamping yet), the check is silently skipped — no false positives.

Depends on https://github.com/shop/world/pull/543227 for the server to stamp schemas with the @apiVersion directive.

How to test your changes?

1. Create a function extension with api_version: "2025-01"
2. Run shopify app function schema to fetch the schema (requires server-side directive stamping to be live, or manually add schema @apiVersion(version: "2025-01") { to the top of schema.graphql)
3. Change api_version to "2025-04" in shopify.extension.toml
4. Run shopify app function build
5. Observe the warning before the build proceeds

Measuring impact

How do we know this change was effective? Please choose one:

• n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix
• Existing analytics will cater for this addition
• PR includes analytics changes to measure impact

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	82.3%	14916/18125
🟡	Branches	74.83%	7364/9841
🟢	Functions	81.36%	3776/4641
🟢	Lines	82.68%	14098/17052

Test suite run success

3932 tests passing in 1513 suites.

Report generated by 🧪jest coverage report action from c185d02