From a4e6734dceda9ee6be033ded624892cacb5d90fb Mon Sep 17 00:00:00 2001 From: Trevor Scheer Date: Wed, 31 Jan 2024 15:53:34 -0800 Subject: [PATCH 1/5] improve composition hints for progressive override usage --- composition-js/src/__tests__/hints.test.ts | 58 ++++++++++++++++++ composition-js/src/hints.ts | 7 +++ composition-js/src/merging/merge.ts | 45 +++++++++----- docs/source/{errors.md => errors.mdx} | 0 docs/source/hints.mdx | 70 ++++++++++++++++++---- package.json | 4 +- 6 files changed, 158 insertions(+), 26 deletions(-) rename docs/source/{errors.md => errors.mdx} (100%) diff --git a/composition-js/src/__tests__/hints.test.ts b/composition-js/src/__tests__/hints.test.ts index b6b62aa23..2a5a549ca 100644 --- a/composition-js/src/__tests__/hints.test.ts +++ b/composition-js/src/__tests__/hints.test.ts @@ -899,6 +899,64 @@ describe('hint tests related to the @override directive', () => { 'T.id' ); }); + + it('hint when progressive @override migration is in progress', () => { + const subgraph1 = gql` + type Query { + a: Int + } + + type T @key(fields: "id"){ + id: Int + f: Int @override(from: "Subgraph2", label: "percent(1)") + } + `; + + const subgraph2 = gql` + type T @key(fields: "id"){ + id: Int + f: Int + } + `; + const result = mergeDocuments(subgraph1, subgraph2); + + // We don't want to see the related hint for non-progressive overrides that + // suggest removing the original field. + expect(result.hints).toHaveLength(1); + expect(result).toRaiseHint( + HINTS.OVERRIDE_MIGRATION_IN_PROGRESS, + `Field "T.f" is currently being migrated with progressive @override. Once the migration is complete, remove the field from subgraph "Subgraph2".`, + 'T.f', + ); + }); + + it('hint when progressive @override migration is in progress 2', () => { + const subgraph1 = gql` + type Query { + a: Int + } + + type T @key(fields: "id"){ + id: Int @override(from: "Subgraph2", label: "percent(1)") + } + `; + + const subgraph2 = gql` + type T @key(fields: "id"){ + id: Int + } + `; + const result = mergeDocuments(subgraph1, subgraph2); + + // We don't want to see the related hint for non-progressive overrides that + // suggest removing the original field. + expect(result.hints).toHaveLength(1); + expect(result).toRaiseHint( + HINTS.OVERRIDE_MIGRATION_IN_PROGRESS, + `Field "T.id" on subgraph "Subgraph2" is currently being migrated via progressive @override. It is still used in some federation directive(s) (@key, @requires, and/or @provides) and/or to satisfy interface constraint(s). Once the migration is complete, consider marking it @external explicitly or removing it along with its references.`, + 'T.id' + ); + }); }); describe('on non-repeatable directives used with incompatible arguments', () => { diff --git a/composition-js/src/hints.ts b/composition-js/src/hints.ts index de7a3d7ec..d7f3bc046 100644 --- a/composition-js/src/hints.ts +++ b/composition-js/src/hints.ts @@ -163,6 +163,12 @@ const OVERRIDE_DIRECTIVE_CAN_BE_REMOVED = makeCodeDefinition({ description: 'Field with @override directive no longer exists in source subgraph, the directive can be safely removed', }); +const OVERRIDE_MIGRATION_IN_PROGRESS = makeCodeDefinition({ + code: 'OVERRIDE_MIGRATION_IN_PROGRESS', + level: HintLevel.INFO, + description: 'Field is currently being migrated with progressive @override. Once the migration is complete, remove the field from the original subgraph.', +}); + const UNUSED_ENUM_TYPE = makeCodeDefinition({ code: 'UNUSED_ENUM_TYPE', level: HintLevel.DEBUG, @@ -221,6 +227,7 @@ export const HINTS = { FROM_SUBGRAPH_DOES_NOT_EXIST, OVERRIDDEN_FIELD_CAN_BE_REMOVED, OVERRIDE_DIRECTIVE_CAN_BE_REMOVED, + OVERRIDE_MIGRATION_IN_PROGRESS, UNUSED_ENUM_TYPE, INCONSISTENT_NON_REPEATABLE_DIRECTIVE_ARGUMENTS, MERGED_NON_REPEATABLE_DIRECTIVE_ARGUMENTS, diff --git a/composition-js/src/merging/merge.ts b/composition-js/src/merging/merge.ts index 2a6682360..53107f354 100644 --- a/composition-js/src/merging/merge.ts +++ b/composition-js/src/merging/merge.ts @@ -1265,6 +1265,8 @@ class Merger { // if the field being overridden is used, then we need to add an @external directive assert(fromField, 'fromField should not be undefined'); const overriddenSubgraphASTNode = fromField.sourceAST ? addSubgraphToASTNode(fromField.sourceAST, sourceSubgraphName) : undefined; + const overrideLabel = overrideDirective.arguments().label; + const overriddenFieldIsReferenced = !!this.metadata(fromIdx).isFieldUsed(fromField); if (this.isExternal(fromIdx, fromField)) { // The from field is explicitly marked external by the user (which means it is "used" and cannot be completely // removed) so the @override can be removed. @@ -1274,26 +1276,30 @@ class Merger { dest, overridingSubgraphASTNode, )); - } else if (this.metadata(fromIdx).isFieldUsed(fromField)) { + } else if (overriddenFieldIsReferenced) { result.setUsedOverridden(fromIdx); - this.hints.push(new CompositionHint( - HINTS.OVERRIDDEN_FIELD_CAN_BE_REMOVED, - `Field "${dest.coordinate}" on subgraph "${sourceSubgraphName}" is overridden. It is still used in some federation directive(s) (@key, @requires, and/or @provides) and/or to satisfy interface constraint(s), but consider marking it @external explicitly or removing it along with its references.`, - dest, - overriddenSubgraphASTNode, - )); + if (!overrideLabel) { + this.hints.push(new CompositionHint( + HINTS.OVERRIDDEN_FIELD_CAN_BE_REMOVED, + `Field "${dest.coordinate}" on subgraph "${sourceSubgraphName}" is overridden. It is still used in some federation directive(s) (@key, @requires, and/or @provides) and/or to satisfy interface constraint(s), but consider marking it @external explicitly or removing it along with its references.`, + dest, + overriddenSubgraphASTNode, + ) + ); + } } else { result.setUnusedOverridden(fromIdx); - this.hints.push(new CompositionHint( - HINTS.OVERRIDDEN_FIELD_CAN_BE_REMOVED, - `Field "${dest.coordinate}" on subgraph "${sourceSubgraphName}" is overridden. Consider removing it.`, - dest, - overriddenSubgraphASTNode, - )); + if (!overrideLabel) { + this.hints.push(new CompositionHint( + HINTS.OVERRIDDEN_FIELD_CAN_BE_REMOVED, + `Field "${dest.coordinate}" on subgraph "${sourceSubgraphName}" is overridden. Consider removing it.`, + dest, + overriddenSubgraphASTNode, + )); + } } // capture an override label if it exists - const overrideLabel = overrideDirective.arguments().label; if (overrideLabel) { const labelRegex = /^[a-zA-Z][a-zA-Z0-9_\-:./]*$/; // Enforce that the label matches the following pattern: percent(x) @@ -1319,6 +1325,17 @@ class Merger { { nodes: overridingSubgraphASTNode } )); } + + const message = overriddenFieldIsReferenced + ? `Field "${dest.coordinate}" on subgraph "${sourceSubgraphName}" is currently being migrated via progressive @override. It is still used in some federation directive(s) (@key, @requires, and/or @provides) and/or to satisfy interface constraint(s). Once the migration is complete, consider marking it @external explicitly or removing it along with its references.` + : `Field "${dest.coordinate}" is currently being migrated with progressive @override. Once the migration is complete, remove the field from subgraph "${sourceSubgraphName}".`; + + this.hints.push(new CompositionHint( + HINTS.OVERRIDE_MIGRATION_IN_PROGRESS, + message, + dest, + overriddenSubgraphASTNode, + )); } } } diff --git a/docs/source/errors.md b/docs/source/errors.mdx similarity index 100% rename from docs/source/errors.md rename to docs/source/errors.mdx diff --git a/docs/source/hints.mdx b/docs/source/hints.mdx index 053a94b69..6d922692d 100644 --- a/docs/source/hints.mdx +++ b/docs/source/hints.mdx @@ -2,22 +2,72 @@ title: Composition hints --- -When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or **hints**. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/). +When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. -> Composition hints only appear in GraphOS Studio and via the `rover subgraph check` command for graphs on [federation version `2.4`](/federation/federation-versions/#v24) or later. You can update a graph's version from its **Settings** page in [GraphOS Studio](https://studio.apollographql.com?referrer=docs-content). +Hints are categorized under the following levels: -The [`rover subgraph check`](/rover/commands/subgraphs#subgraph-check) command outputs rule violations with the [severity levels](/graphos/delivery/schema-linter/#setting-severity-levels) you've configured for your graph variant. The [`rover supergraph compose`](/rover/commands/supergraphs#supergraph-compose) command outputs rule violations for _all_ local subgraph schemas. +* `WARN`: Indicates a situation that might be expected but is usually temporary and should be double-checked. Typically, composition might have needed to ignore some elements from some subgraph when creating the supergraph. +* `INFO`: Suggests a potentially helpful improvement or highlights a noteworthy resolution made by composition. Can otherwise be ignored. +* `DEBUG`: Lower-level information that provides insight into the composition. These hints are of lesser importance/impact. -See below for a list of composition rules categorized by rule type. The heading for each rule is the code that GraphOS returns for the rule violation. Refer to the [rules reference page](/graphos/delivery/linter-rules) for a comprehensive list of linter rules. +Note that hints are first and foremost informative and don't necessarily correspond to a problem to be fixed. -### Inconsistent elements +This document lists the hints that can be generated for each level, with a description of why each is generated. - -### Overridden and unused elements +The following hints might be generated during composition: - +## `WARN` -### Directives +
- \ No newline at end of file +| Code | Description | Level | +|---|---|---| +| `INCONSISTENT_DEFAULT_VALUE_PRESENCE` | Indicates that an argument definition (of a field/input field/directive definition) has a default value in only some of the subgraphs that define the argument. | `WARN` | +| `INCONSISTENT_INPUT_OBJECT_FIELD` | Indicates that a field of an input object type definition is only defined in a subset of the subgraphs that declare the input object. | `WARN` | +| `INCONSISTENT_ENUM_VALUE_FOR_INPUT_ENUM` | Indicates that a value of an enum type definition (that is only used as an Input type) has not been merged into the supergraph because it is defined in only a subset of the subgraphs that declare the enum | `WARN` | +| `INCONSISTENT_EXECUTABLE_DIRECTIVE_PRESENCE` | Indicates that an executable directive definition is declared in only some of the subgraphs. | `WARN` | +| `NO_EXECUTABLE_DIRECTIVE_INTERSECTION` | Indicates that, for an executable directive definition, no location for it appears in all subgraphs. | `WARN` | +| `INCONSISTENT_EXECUTABLE_DIRECTIVE_REPEATABLE` | Indicates that an executable directive definition is marked repeatable in only a subset of the subgraphs (and will not be repeatable in the supergraph). | `WARN` | +| `INCONSISTENT_EXECUTABLE_DIRECTIVE_LOCATIONS` | Indicates that an executiable directive definition is declared with inconsistent locations across subgraphs (and will use the intersection of all locations in the supergraph). | `WARN` | +| `INCONSISTENT_DESCRIPTION` | Indicates that an element has a description in more than one subgraph, and the descriptions are not equal. | `WARN` | +| `INCONSISTENT_ARGUMENT_PRESENCE` | Indicates that an optional argument (of a field or directive definition) is not present in all subgraphs and will not be part of the supergraph. | `WARN` | +| `FROM_SUBGRAPH_DOES_NOT_EXIST` | Source subgraph specified by @override directive does not exist | `WARN` | +| `INCONSISTENT_NON_REPEATABLE_DIRECTIVE_ARGUMENTS` | A non-repeatable directive is applied to a schema element in different subgraphs but with arguments that are different. | `WARN` | +| `DIRECTIVE_COMPOSITION_WARN` | Indicates that an issue was detected when composing custom directives. | `WARN` | +| `INCONSISTENT_RUNTIME_TYPES_FOR_SHAREABLE_RETURN` | Indicates that a @shareable field returns different sets of runtime types in the different subgraphs in which it is defined. | `WARN` | + +
+ +## `INFO` + +
+ +| Code | Description | Level | +|---|---|---| +| `INCONSISTENT_BUT_COMPATIBLE_FIELD_TYPE` | Indicates that a field does not have the exact same types in all subgraphs, but that the types are "compatible" (2 types are compatible if one is a non-nullable version of the other, a list version, a subtype, or a combination of the former). | `INFO` | +| `INCONSISTENT_BUT_COMPATIBLE_ARGUMENT_TYPE` | Indicates that an argument type (of a field/input field/directive definition) does not have the exact same type in all subgraphs, but that the types are "compatible" (two types are compatible if one is a non-nullable version of the other, a list version, a subtype, or a combination of the former). | `INFO` | +| `INCONSISTENT_ENTITY` | Indicates that an object is declared as an entity (has a `@key`) in only some of the subgraphs in which the object is defined. | `INFO` | +| `OVERRIDDEN_FIELD_CAN_BE_REMOVED` | Field has been overridden by another subgraph. Consider removing. | `INFO` | +| `OVERRIDE_DIRECTIVE_CAN_BE_REMOVED` | Field with @override directive no longer exists in source subgraph, the directive can be safely removed | `INFO` | +| `OVERRIDE_MIGRATION_IN_PROGRESS` | Field is currently being migrated with progressive @override. Once the migration is complete, remove the field from the original subgraph. | `INFO` | +| `MERGED_NON_REPEATABLE_DIRECTIVE_ARGUMENTS` | A non-repeatable directive has been applied to a schema element in different subgraphs with different arguments and the arguments values were merged using the directive configured strategies. | `INFO` | +| `DIRECTIVE_COMPOSITION_INFO` | Indicates that an issue was detected when composing custom directives. | `INFO` | + +
+ +## `DEBUG` + +
+ +| Code | Description | Level | +|---|---|---| +| `INCONSISTENT_OBJECT_VALUE_TYPE_FIELD` | Indicates that a field of an object "value type" (has no `@key` in any subgraph) is not defined in all the subgraphs that declare the type. | `DEBUG` | +| `INCONSISTENT_INTERFACE_VALUE_TYPE_FIELD` | Indicates that a field of an interface "value type" (has no `@key` in any subgraph) is not defined in all the subgraphs that declare the type. | `DEBUG` | +| `INCONSISTENT_UNION_MEMBER` | Indicates that a member of a union type definition is only defined in a subset of the subgraphs that declare the union. | `DEBUG` | +| `INCONSISTENT_ENUM_VALUE_FOR_OUTPUT_ENUM` | Indicates that a value of an enum type definition (that is only used as an Output type, or is unused) has been merged in the supergraph but is defined in only a subset of the subgraphs that declare the enum | `DEBUG` | +| `INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_REPEATABLE` | Indicates that a type system directive definition is marked repeatable in only a subset of the subgraphs that declare the directive (and will be repeatable in the supergraph). | `DEBUG` | +| `INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_LOCATIONS` | Indicates that a type system directive definition is declared with inconsistent locations across subgraphs (and will use the union of all locations in the supergraph). | `DEBUG` | +| `UNUSED_ENUM_TYPE` | Indicates that an enum type is defined in some subgraphs but is unused (no field/argument references it). All the values from subgraphs defining that enum will be included in the supergraph. | `DEBUG` | + +
diff --git a/package.json b/package.json index 88444ebd8..bba4330ec 100644 --- a/package.json +++ b/package.json @@ -19,9 +19,9 @@ "codegen": "graphql-codegen --config codegen.yml", "codegen:check": "npm run codegen && git diff --exit-code", "lint": "eslint . --ext .ts", - "error-code-doc": "ts-node ./internals-js/src/genErrorCodeDoc.ts > ./docs/source/errors.md", + "error-code-doc": "ts-node ./internals-js/src/genErrorCodeDoc.ts > ./docs/source/errors.mdx", "error-code-doc:check": "npm run error-code-doc && git diff --exit-code", - "hints-doc": "ts-node ./composition-js/src/genHintDoc.ts > ./docs/source/hints.md", + "hints-doc": "ts-node ./composition-js/src/genHintDoc.ts > ./docs/source/hints.mdx", "hints-doc:check": "npm run hints-doc && git diff --exit-code", "gen-test-supergraph": "ts-node ./query-planner-js/src/__tests__/genTestSupergraph.ts", "changeset-version": "changeset version && npm i", From 45ca92d316a95f2ceb77d3d7994a266234f5cff9 Mon Sep 17 00:00:00 2001 From: Trevor Scheer Date: Wed, 31 Jan 2024 15:55:08 -0800 Subject: [PATCH 2/5] update test name --- composition-js/src/__tests__/hints.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composition-js/src/__tests__/hints.test.ts b/composition-js/src/__tests__/hints.test.ts index 2a5a549ca..9831d4851 100644 --- a/composition-js/src/__tests__/hints.test.ts +++ b/composition-js/src/__tests__/hints.test.ts @@ -930,7 +930,7 @@ describe('hint tests related to the @override directive', () => { ); }); - it('hint when progressive @override migration is in progress 2', () => { + it('hint when progressive @override migration is in progress (for a referenced field)', () => { const subgraph1 = gql` type Query { a: Int From 1868c29942d1a2e45ae836e00e6fc78cc9c14a10 Mon Sep 17 00:00:00 2001 From: Trevor Scheer Date: Wed, 31 Jan 2024 16:08:15 -0800 Subject: [PATCH 3/5] update hint doc generation + hint doc --- composition-js/src/genHintDoc.ts | 22 +++++++++++++++------- docs/source/hints.mdx | 22 +++++++++++++++------- 2 files changed, 30 insertions(+), 14 deletions(-) diff --git a/composition-js/src/genHintDoc.ts b/composition-js/src/genHintDoc.ts index 56bd70366..43b87f9e0 100644 --- a/composition-js/src/genHintDoc.ts +++ b/composition-js/src/genHintDoc.ts @@ -5,17 +5,25 @@ const header = `--- title: Composition hints --- -When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. +When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or **hints**. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/). -Hints are categorized under the following levels: +> Composition hints only appear in GraphOS Studio and via the \`rover subgraph check\` command for graphs on [federation version \`2.4\`](/federation/federation-versions/#v24) or later. You can update a graph's version from its **Settings** page in [GraphOS Studio](https://studio.apollographql.com?referrer=docs-content). -* \`WARN\`: Indicates a situation that might be expected but is usually temporary and should be double-checked. Typically, composition might have needed to ignore some elements from some subgraph when creating the supergraph. -* \`INFO\`: Suggests a potentially helpful improvement or highlights a noteworthy resolution made by composition. Can otherwise be ignored. -* \`DEBUG\`: Lower-level information that provides insight into the composition. These hints are of lesser importance/impact. +The [\`rover subgraph check\`](/rover/commands/subgraphs#subgraph-check) command outputs rule violations with the [severity levels](/graphos/delivery/schema-linter/#setting-severity-levels) you've configured for your graph variant. The [\`rover supergraph compose\`](/rover/commands/supergraphs#supergraph-compose) command outputs rule violations for _all_ local subgraph schemas. -Note that hints are first and foremost informative and don't necessarily correspond to a problem to be fixed. +See below for a list of composition rules categorized by rule type. The heading for each rule is the code that GraphOS returns for the rule violation. Refer to the [rules reference page](/graphos/delivery/linter-rules) for a comprehensive list of linter rules. -This document lists the hints that can be generated for each level, with a description of why each is generated. +### Inconsistent elements + + + +### Overridden and unused elements + + + +### Directives + + `; function makeMarkdownArray( diff --git a/docs/source/hints.mdx b/docs/source/hints.mdx index 6d922692d..e9d783792 100644 --- a/docs/source/hints.mdx +++ b/docs/source/hints.mdx @@ -2,17 +2,25 @@ title: Composition hints --- -When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. +When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or **hints**. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/). -Hints are categorized under the following levels: +> Composition hints only appear in GraphOS Studio and via the `rover subgraph check` command for graphs on [federation version `2.4`](/federation/federation-versions/#v24) or later. You can update a graph's version from its **Settings** page in [GraphOS Studio](https://studio.apollographql.com?referrer=docs-content). -* `WARN`: Indicates a situation that might be expected but is usually temporary and should be double-checked. Typically, composition might have needed to ignore some elements from some subgraph when creating the supergraph. -* `INFO`: Suggests a potentially helpful improvement or highlights a noteworthy resolution made by composition. Can otherwise be ignored. -* `DEBUG`: Lower-level information that provides insight into the composition. These hints are of lesser importance/impact. +The [`rover subgraph check`](/rover/commands/subgraphs#subgraph-check) command outputs rule violations with the [severity levels](/graphos/delivery/schema-linter/#setting-severity-levels) you've configured for your graph variant. The [`rover supergraph compose`](/rover/commands/supergraphs#supergraph-compose) command outputs rule violations for _all_ local subgraph schemas. -Note that hints are first and foremost informative and don't necessarily correspond to a problem to be fixed. +See below for a list of composition rules categorized by rule type. The heading for each rule is the code that GraphOS returns for the rule violation. Refer to the [rules reference page](/graphos/delivery/linter-rules) for a comprehensive list of linter rules. -This document lists the hints that can be generated for each level, with a description of why each is generated. +### Inconsistent elements + + + +### Overridden and unused elements + + + +### Directives + + The following hints might be generated during composition: From 332897f4b507912fea9687f0978f6718ef956b72 Mon Sep 17 00:00:00 2001 From: Trevor Scheer Date: Wed, 31 Jan 2024 16:34:57 -0800 Subject: [PATCH 4/5] Revert "update hint doc generation + hint doc" --- composition-js/src/genHintDoc.ts | 22 ++++------ docs/source/{errors.mdx => errors.md} | 0 docs/source/hints.mdx | 60 +-------------------------- package.json | 4 +- 4 files changed, 10 insertions(+), 76 deletions(-) rename docs/source/{errors.mdx => errors.md} (100%) diff --git a/composition-js/src/genHintDoc.ts b/composition-js/src/genHintDoc.ts index 43b87f9e0..56bd70366 100644 --- a/composition-js/src/genHintDoc.ts +++ b/composition-js/src/genHintDoc.ts @@ -5,25 +5,17 @@ const header = `--- title: Composition hints --- -When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or **hints**. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/). +When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. -> Composition hints only appear in GraphOS Studio and via the \`rover subgraph check\` command for graphs on [federation version \`2.4\`](/federation/federation-versions/#v24) or later. You can update a graph's version from its **Settings** page in [GraphOS Studio](https://studio.apollographql.com?referrer=docs-content). +Hints are categorized under the following levels: -The [\`rover subgraph check\`](/rover/commands/subgraphs#subgraph-check) command outputs rule violations with the [severity levels](/graphos/delivery/schema-linter/#setting-severity-levels) you've configured for your graph variant. The [\`rover supergraph compose\`](/rover/commands/supergraphs#supergraph-compose) command outputs rule violations for _all_ local subgraph schemas. +* \`WARN\`: Indicates a situation that might be expected but is usually temporary and should be double-checked. Typically, composition might have needed to ignore some elements from some subgraph when creating the supergraph. +* \`INFO\`: Suggests a potentially helpful improvement or highlights a noteworthy resolution made by composition. Can otherwise be ignored. +* \`DEBUG\`: Lower-level information that provides insight into the composition. These hints are of lesser importance/impact. -See below for a list of composition rules categorized by rule type. The heading for each rule is the code that GraphOS returns for the rule violation. Refer to the [rules reference page](/graphos/delivery/linter-rules) for a comprehensive list of linter rules. +Note that hints are first and foremost informative and don't necessarily correspond to a problem to be fixed. -### Inconsistent elements - - - -### Overridden and unused elements - - - -### Directives - - +This document lists the hints that can be generated for each level, with a description of why each is generated. `; function makeMarkdownArray( diff --git a/docs/source/errors.mdx b/docs/source/errors.md similarity index 100% rename from docs/source/errors.mdx rename to docs/source/errors.md diff --git a/docs/source/hints.mdx b/docs/source/hints.mdx index e9d783792..053a94b69 100644 --- a/docs/source/hints.mdx +++ b/docs/source/hints.mdx @@ -20,62 +20,4 @@ See below for a list of composition rules categorized by rule type. The heading ### Directives - - - -The following hints might be generated during composition: - -## `WARN` - -
- -| Code | Description | Level | -|---|---|---| -| `INCONSISTENT_DEFAULT_VALUE_PRESENCE` | Indicates that an argument definition (of a field/input field/directive definition) has a default value in only some of the subgraphs that define the argument. | `WARN` | -| `INCONSISTENT_INPUT_OBJECT_FIELD` | Indicates that a field of an input object type definition is only defined in a subset of the subgraphs that declare the input object. | `WARN` | -| `INCONSISTENT_ENUM_VALUE_FOR_INPUT_ENUM` | Indicates that a value of an enum type definition (that is only used as an Input type) has not been merged into the supergraph because it is defined in only a subset of the subgraphs that declare the enum | `WARN` | -| `INCONSISTENT_EXECUTABLE_DIRECTIVE_PRESENCE` | Indicates that an executable directive definition is declared in only some of the subgraphs. | `WARN` | -| `NO_EXECUTABLE_DIRECTIVE_INTERSECTION` | Indicates that, for an executable directive definition, no location for it appears in all subgraphs. | `WARN` | -| `INCONSISTENT_EXECUTABLE_DIRECTIVE_REPEATABLE` | Indicates that an executable directive definition is marked repeatable in only a subset of the subgraphs (and will not be repeatable in the supergraph). | `WARN` | -| `INCONSISTENT_EXECUTABLE_DIRECTIVE_LOCATIONS` | Indicates that an executiable directive definition is declared with inconsistent locations across subgraphs (and will use the intersection of all locations in the supergraph). | `WARN` | -| `INCONSISTENT_DESCRIPTION` | Indicates that an element has a description in more than one subgraph, and the descriptions are not equal. | `WARN` | -| `INCONSISTENT_ARGUMENT_PRESENCE` | Indicates that an optional argument (of a field or directive definition) is not present in all subgraphs and will not be part of the supergraph. | `WARN` | -| `FROM_SUBGRAPH_DOES_NOT_EXIST` | Source subgraph specified by @override directive does not exist | `WARN` | -| `INCONSISTENT_NON_REPEATABLE_DIRECTIVE_ARGUMENTS` | A non-repeatable directive is applied to a schema element in different subgraphs but with arguments that are different. | `WARN` | -| `DIRECTIVE_COMPOSITION_WARN` | Indicates that an issue was detected when composing custom directives. | `WARN` | -| `INCONSISTENT_RUNTIME_TYPES_FOR_SHAREABLE_RETURN` | Indicates that a @shareable field returns different sets of runtime types in the different subgraphs in which it is defined. | `WARN` | - -
- -## `INFO` - -
- -| Code | Description | Level | -|---|---|---| -| `INCONSISTENT_BUT_COMPATIBLE_FIELD_TYPE` | Indicates that a field does not have the exact same types in all subgraphs, but that the types are "compatible" (2 types are compatible if one is a non-nullable version of the other, a list version, a subtype, or a combination of the former). | `INFO` | -| `INCONSISTENT_BUT_COMPATIBLE_ARGUMENT_TYPE` | Indicates that an argument type (of a field/input field/directive definition) does not have the exact same type in all subgraphs, but that the types are "compatible" (two types are compatible if one is a non-nullable version of the other, a list version, a subtype, or a combination of the former). | `INFO` | -| `INCONSISTENT_ENTITY` | Indicates that an object is declared as an entity (has a `@key`) in only some of the subgraphs in which the object is defined. | `INFO` | -| `OVERRIDDEN_FIELD_CAN_BE_REMOVED` | Field has been overridden by another subgraph. Consider removing. | `INFO` | -| `OVERRIDE_DIRECTIVE_CAN_BE_REMOVED` | Field with @override directive no longer exists in source subgraph, the directive can be safely removed | `INFO` | -| `OVERRIDE_MIGRATION_IN_PROGRESS` | Field is currently being migrated with progressive @override. Once the migration is complete, remove the field from the original subgraph. | `INFO` | -| `MERGED_NON_REPEATABLE_DIRECTIVE_ARGUMENTS` | A non-repeatable directive has been applied to a schema element in different subgraphs with different arguments and the arguments values were merged using the directive configured strategies. | `INFO` | -| `DIRECTIVE_COMPOSITION_INFO` | Indicates that an issue was detected when composing custom directives. | `INFO` | - -
- -## `DEBUG` - -
- -| Code | Description | Level | -|---|---|---| -| `INCONSISTENT_OBJECT_VALUE_TYPE_FIELD` | Indicates that a field of an object "value type" (has no `@key` in any subgraph) is not defined in all the subgraphs that declare the type. | `DEBUG` | -| `INCONSISTENT_INTERFACE_VALUE_TYPE_FIELD` | Indicates that a field of an interface "value type" (has no `@key` in any subgraph) is not defined in all the subgraphs that declare the type. | `DEBUG` | -| `INCONSISTENT_UNION_MEMBER` | Indicates that a member of a union type definition is only defined in a subset of the subgraphs that declare the union. | `DEBUG` | -| `INCONSISTENT_ENUM_VALUE_FOR_OUTPUT_ENUM` | Indicates that a value of an enum type definition (that is only used as an Output type, or is unused) has been merged in the supergraph but is defined in only a subset of the subgraphs that declare the enum | `DEBUG` | -| `INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_REPEATABLE` | Indicates that a type system directive definition is marked repeatable in only a subset of the subgraphs that declare the directive (and will be repeatable in the supergraph). | `DEBUG` | -| `INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_LOCATIONS` | Indicates that a type system directive definition is declared with inconsistent locations across subgraphs (and will use the union of all locations in the supergraph). | `DEBUG` | -| `UNUSED_ENUM_TYPE` | Indicates that an enum type is defined in some subgraphs but is unused (no field/argument references it). All the values from subgraphs defining that enum will be included in the supergraph. | `DEBUG` | - -
+ \ No newline at end of file diff --git a/package.json b/package.json index bba4330ec..88444ebd8 100644 --- a/package.json +++ b/package.json @@ -19,9 +19,9 @@ "codegen": "graphql-codegen --config codegen.yml", "codegen:check": "npm run codegen && git diff --exit-code", "lint": "eslint . --ext .ts", - "error-code-doc": "ts-node ./internals-js/src/genErrorCodeDoc.ts > ./docs/source/errors.mdx", + "error-code-doc": "ts-node ./internals-js/src/genErrorCodeDoc.ts > ./docs/source/errors.md", "error-code-doc:check": "npm run error-code-doc && git diff --exit-code", - "hints-doc": "ts-node ./composition-js/src/genHintDoc.ts > ./docs/source/hints.mdx", + "hints-doc": "ts-node ./composition-js/src/genHintDoc.ts > ./docs/source/hints.md", "hints-doc:check": "npm run hints-doc && git diff --exit-code", "gen-test-supergraph": "ts-node ./query-planner-js/src/__tests__/genTestSupergraph.ts", "changeset-version": "changeset version && npm i", From bee4a8b3cb1c770a8699b5eff2db3444588c90a7 Mon Sep 17 00:00:00 2001 From: Trevor Scheer Date: Wed, 31 Jan 2024 16:44:03 -0800 Subject: [PATCH 5/5] changeset --- .changeset/yellow-horses-protect.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/yellow-horses-protect.md diff --git a/.changeset/yellow-horses-protect.md b/.changeset/yellow-horses-protect.md new file mode 100644 index 000000000..2a710bc41 --- /dev/null +++ b/.changeset/yellow-horses-protect.md @@ -0,0 +1,5 @@ +--- +"@apollo/composition": patch +--- + +Introduce a new composition hint pertaining specifically to progressive `@override` usage (when a `label` argument is present).