feat: add option to ignore external key checks

[alepane21]

Summary by CodeRabbit

• New Features

  • Added --ignore-external-keys CLI flag to the compose command to ignore external entity keys during composition.
  • Introduced composition-ignore-external-keys feature flag for controlling external key handling.

• Bug Fixes

  • Improved composition parameter handling with structured options objects.

• Chores

  • Updated composition API signatures to accept parameter objects instead of individual arguments.
  • Added ESLint configuration for TypeScript and import linting.
  • Enhanced type system with type-only imports throughout codebase.

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• Documentation has been updated on https://github.com/wundergraph/cosmo-docs.
• I have read the Contributors Guide.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a9f539f3-11ed-421f-9d9e-a9216d7ed28e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This PR introduces support for ignoring external keys during graph composition, adding a new --ignore-external-keys CLI flag and a composition-ignore-external-keys feature flag. The core composition APIs are refactored to accept a CompositionOptions object (containing ignoreExternalKeys and disableResolvabilityValidation) instead of separate boolean parameters, with all call sites updated accordingly. Extensive type-only import changes are applied throughout for improved tree-shaking clarity.

Changes

Cohort / File(s)	Summary
CLI and composition interface cli/src/commands/router/commands/compose.ts, cli/src/utils.ts	Added --ignore-external-keys flag to CLI compose command and updated composeSubgraphs API signature to accept a CompositionOptions object instead of a single boolean parameter.
Composition package parameter types composition/src/federation/params.ts, composition/src/normalization/params.ts, composition/src/types/params.ts, composition/src/v1/federation/params.ts, composition/src/v1/normalization/params.ts	New parameter type definitions added: FederateSubgraphsParams, FederateSubgraphsWithContractsParams, FederateSubgraphsContractParams, CompositionOptions, NormalizeSubgraph*Params, and BatchNormalizeParams to standardize API parameter shapes.
Composition API structure refactoring composition/src/federation/federation.ts, composition/src/federation/types.ts, composition/src/normalization/normalization.ts, composition/src/v1/federation/federation-factory.ts, composition/src/v1/normalization/normalization-factory.ts	Function signatures refactored from positional parameters to parameter objects; disableResolvabilityValidation boolean replaced with options?: CompositionOptions across federateSubgraphs* and normalizeSubgraph* functions.
Composition type-only imports composition/src/ast/utils.ts, composition/src/buildASTSchema/*, composition/src/errors/*, composition/src/federation/types.ts, composition/src/normalization/types.ts, composition/src/resolvability-graph/**, composition/src/router-configuration/*, composition/src/schema-building/*, composition/src/subgraph/types.ts, composition/src/utils/*, composition/src/v1/**	Widespread conversion of value imports to type-only imports (GraphQL AST types, data structures) throughout composition package for improved type clarity and tree-shaking.
Composition public exports composition/src/index.ts	Updated public exports: added ./federation/params, ./normalization/params, ./types/params, ./v1/federation/params; removed ./v1/federation/types.
Controlplane feature flag infrastructure controlplane/src/core/repositories/OrganizationRepository.ts, controlplane/src/types/index.ts	Added new composition-ignore-external-keys feature flag to organization features and FeatureIds enum; removed local CompositionOptions type (now imported from @wundergraph/composition).
Controlplane composition integration controlplane/src/core/composition/composer.ts, controlplane/src/core/composition/composition.ts, controlplane/src/core/repositories/FederatedGraphRepository.ts, controlplane/src/core/repositories/SubgraphRepository.ts	Updated composition function signatures to accept options?: CompositionOptions instead of compositionOptions; moved CompositionOptions import to @wundergraph/composition; updated buildSchema and composeWithProposedSchemas calls to pass options object.
Controlplane feature flag integration controlplane/src/core/bufservices/contract/*.ts, controlplane/src/core/bufservices/feature-flag/*.ts, controlplane/src/core/bufservices/federated-graph/*.ts, controlplane/src/core/bufservices/monograph/*.ts, controlplane/src/core/bufservices/subgraph/*.ts, controlplane/src/core/bufservices/graph/*.ts	Replaced newCompositionOptions helper with direct CompositionOptions object creation; added feature flag retrieval via OrganizationRepository.getFeature('composition-ignore-external-keys') across all graph/subgraph operation handlers and propagated ignoreExternalKeys through composition calls.
Controlplane utilities controlplane/src/core/util.ts	Removed newCompositionOptions helper function; updated import of CompositionOptions to source from @wundergraph/composition.
Controlplane schema checks controlplane/src/core/repositories/SchemaCheckRepository.ts, controlplane/src/core/bufservices/subgraph/checkSubgraphSchema.ts	Added ignoreExternalKeys parameter to buildSchema and performSchemaCheck calls; integrated feature flag retrieval into schema validation flow.
Composition test utilities composition/tests/utils/utils.ts, composition/tests/v1/contracts.test.ts, composition/tests/v1/directives/*.test.ts, composition/tests/v1/*.test.ts	Updated test helpers and fixtures to accept options?: CompositionOptions parameter; converted type imports to type-only; added normalizeSubgraphFailure, normalizeSubgraphSuccess, federateSubgraphs*Success, and createSubgraph test helpers; updated batchNormalize and normalizeSubgraph* calls to use object-based parameters.
Minor configuration changes cli/vite.config.ts, composition/.eslintrc.json, composition/package.json, composition/tsconfig.json, controlplane/emails/package.json	Updated quote style in vite config; added ESLint configuration with type-import rules; updated lint:fix scripts to include ESLint with auto-fix; reordered tsconfig properties.
Dependency updates controlplane/package.json	Updated @wundergraph/composition dependency from 0.51.1 to workspace:*.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Both PRs modify composition's federation/normalization APIs to refactor function signatures from positional parameters to CompositionOptions object-based parameters, affecting the same federateSubgraphs and normalizeSubgraph call sites and function declarations.
• Both PRs update controlplane/src/core/bufservices/subgraph/checkSubgraphSchema.ts to propagate organization-scoped feature flags (ignoreExternalKeys) through schema validation flows and composition call sites.
• Both PRs update controlplane/package.json to manage the @wundergraph/composition dependency version, coordinating composition package changes with controlplane breaking changes.

[codecov]

Codecov Report

❌ Patch coverage is 82.81250% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.85%. Comparing base (a1778da) to head (cb51f7b).
⚠️ Report is 12 commits behind head on david/eng-9098-add-composition-options.

Files with missing lines	Patch %	Lines
...e/bufservices/federated-graph/migrateFromApollo.ts	0.00%	5 Missing ⚠️
...rvices/graph/setGraphRouterCompatibilityVersion.ts	16.66%	5 Missing ⚠️
...src/core/bufservices/subgraph/fixSubgraphSchema.ts	0.00%	5 Missing ⚠️
...ane/src/core/repositories/SchemaCheckRepository.ts	71.42%	4 Missing ⚠️
cli/src/commands/router/commands/compose.ts	33.33%	2 Missing ⚠️
...ne/src/core/repositories/OrganizationRepository.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@                             Coverage Diff                             @@
##           david/eng-9098-add-composition-options    #2598       +/-   ##
===========================================================================
+ Coverage                                   43.74%   56.85%   +13.11%     
===========================================================================
  Files                                        1042      428      -614     
  Lines                                      146615    54038    -92577     
  Branches                                     9416     4803     -4613     
===========================================================================
- Hits                                        64132    30723    -33409     
+ Misses                                      80756    23292    -57464     
+ Partials                                     1727       23     -1704     

Files with missing lines	Coverage Δ
...ne/src/core/bufservices/contract/createContract.ts	76.16% <100.00%> (+0.63%)	⬆️
...ne/src/core/bufservices/contract/updateContract.ts	77.93% <100.00%> (+0.97%)	⬆️
...core/bufservices/feature-flag/createFeatureFlag.ts	82.17% <100.00%> (+0.39%)	⬆️
...core/bufservices/feature-flag/deleteFeatureFlag.ts	82.82% <100.00%> (+0.65%)	⬆️
...core/bufservices/feature-flag/enableFeatureFlag.ts	76.19% <100.00%> (+0.88%)	⬆️
...core/bufservices/feature-flag/updateFeatureFlag.ts	81.28% <100.00%> (+0.57%)	⬆️
...bufservices/federated-graph/checkFederatedGraph.ts	85.00% <100.00%> (+0.67%)	⬆️
...ufservices/federated-graph/createFederatedGraph.ts	72.31% <100.00%> (+3.95%)	⬆️
...ufservices/federated-graph/updateFederatedGraph.ts	84.53% <100.00%> (+0.53%)	⬆️
...src/core/bufservices/monograph/publishMonograph.ts	62.30% <ø> (-0.20%)	⬇️
... and 13 more

... and 615 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Router image scan passed

✅ No security vulnerabilities found in image:

ghcr.io/wundergraph/cosmo/router:sha-66e8f3c7445410eaced1d014b42f998c2d3e86b9

[Aenimus]

Some small changes and we're good to go

[Aenimus]

@alepane21 can you also write a test? You can use the exact same subgraphs as in my PR

[Aenimus]

Shouldn't disableResolvabilityValidation also be set here?

[alepane21]

Fixed. A bit worried because it was missed also before ...

[Aenimus]

buildSchema calls normalization, which doesn't use that flag. That's probably why it was not included before.

[Aenimus]

I think you can remove it and put a comment like
// disableResolvabilityValidation not included because buildSchema only calls normalization

[thisisnithin]

can we please create a constant somewhere for these feature ids please? we have others too in the codebase as loose strings repeated.

[Aenimus]

I think put the ?.enabled ?? false here to save doing it everywhere else

[Aenimus]

LGTM!