/** * GraphQL SDL reader (change: add-contract-graph-projection, GraphQL phase). * * Reads one schema file (`.graphql`, `.graphqls`, `.gql`) into a normalized element model: object, * interface, input, enum, union and scalar types with their fields, arguments, enum values, union * members and implemented interfaces, plus the `schema { query: … }` roots. `extend` definitions are * kept apart and merged across files by {@link mergeGraphqlSchema}, because a modular schema splits * one type over many files; {@link mergeGraphqlUniverses} does that once per PROJECT, since * GraphQL's namespace is global to a server and not to a repository. Deterministic and offline: a small hand-written tokenizer, no * `graphql-js`, no network. * * A file holding only operations and fragments is a CLIENT document, not a schema, and is reported * as such. Directives other than `@deprecated` are outside the model: each one is named in * `unassessed` and hashed into its element, so a change to one is seen and never read as "no * change". Every name is bounded, so a hostile file stays linear. */ /** Whether a path is a GraphQL file this reader may read. */ export declare const isGraphqlPath: (path: string) => boolean; export declare const isBuiltInScalar: (name: string) => boolean; export type GqlKind = 'object' | 'interface' | 'input' | 'enum' | 'union' | 'scalar'; export interface GqlArg { name: string; /** The type as written, whitespace removed: `[ID!]!`. */ type: string; /** The default value as written (whitespace collapsed), when there is one. */ defaultValue?: string; deprecated: boolean; /** A hash of the directives other than `@deprecated`. */ directivesHash: string; line: number; } export interface GqlField { name: string; type: string; /** Arguments (object and interface fields only), in declaration order. */ args: GqlArg[]; /** The default value (input fields only). */ defaultValue?: string; deprecated: boolean; directivesHash: string; line: number; /** Set by {@link mergeGraphqlSchema} on a field an `extend` in another file added. */ file?: string; } export interface GqlEnumValue { name: string; deprecated: boolean; directivesHash: string; line: number; } /** A type definition — or, with `extension`, the fields an `extend` adds to one. */ export interface GqlType { kind: GqlKind; name: string; line: number; extension: boolean; /** Object, interface and input fields. */ fields: GqlField[]; /** Enum values. */ values: GqlEnumValue[]; /** Union members. */ members: string[]; /** Interfaces an object or interface implements. */ interfaces: string[]; /** A hash of the type's own directives (`@deprecated` is not valid on a type, so all of them). */ directivesHash: string; /** * Why THIS type's shape cannot be read (change: scope-graphql-schema-universes). * * A duplicate field, enum value or argument makes the type genuinely ambiguous — which * definition wins is not knowable — but it says nothing about the rest of the document. The type * is kept with the reason and withheld from the merged namespace; every other type is still read. */ unassessable?: string; /** * The repeated declarations the parser did not keep (the first one is kept). Carried so a * withheld type's fingerprint still SEES a change to them: dropping them made `x: Int x: String` * → `x: Int x: Boolean` compare as unchanged. */ duplicates?: GqlDuplicate[]; } /** One repeated declaration: a field (or one of its arguments, keyed by the field) or an enum value. */ export interface GqlDuplicate { element: 'field' | 'value'; name: string; definition: unknown; } /** A directive definition: `directive @auth(role: Role!) repeatable on FIELD_DEFINITION | OBJECT`. */ export interface GqlDirectiveDef { name: string; args: GqlArg[]; repeatable: boolean; locations: string[]; line: number; } export interface GqlDocument { file: string; format: 'graphql-sdl'; /** Root operation types the file names in `schema { … }` (or `extend schema`). */ roots: Partial>; /** * Whether the file holds a `schema { … }` DEFINITION (not an `extend schema`). A schema with * one has exactly the roots it names: the default names apply only when no file defines one. */ hasSchemaDefinition: boolean; /** A hash of the directives on `schema` / `extend schema` (Federation's `@link`, …). */ schemaDirectivesHash: string; directiveDefs: GqlDirectiveDef[]; types: GqlType[]; /** Constructs outside the model: custom directives used, by name, and operations in a schema file. */ unassessed: string[]; } /** A GraphQL file that is a client document (operations and fragments only), not a schema. */ export interface GqlClientDocument { file: string; clientDocument: true; } /** * Parse one file. Returns an `error` when it cannot be read, or `{ clientDocument: true }` when it * holds operations and fragments only. */ export declare function readGraphql(file: string, text: string): GqlDocument | GqlClientDocument | { file: string; error: string; }; /** A merged type, with the files that define and extend it. */ export interface GqlMergedType extends GqlType { /** The file holding the definition (not an extension), or the first extension's file. */ file: string; /** Files that extend it, sorted. */ extendedIn: string[]; /** * No file read defines it; only `extend`s do. A Federation 1 subgraph writes * `extend type Query { … }` and `extend type User @key(…)` for types the gateway defines, so the * extensions ARE this repository's contract and are compared as such. */ extensionOnly?: true; /** * Elements an `extend` declared more than once (`field:` / `value:`). The extension's * readable part is folded in; these alone are compared by fingerprint and, when they differ, * reported `schema-unassessed` — never read as removed, and never hiding the rest of the type. */ unassessableElements?: Record; } export type GqlRootKind = 'query' | 'mutation' | 'subscription'; export interface GqlSchema { /** Types by name, definitions with their extensions folded in. A name defined twice is absent. */ types: Map; /** * Root operation type names. When a file defines `schema { … }`, exactly the roots it names; * otherwise the default names `Query`, `Mutation`, `Subscription` (as GraphQL itself says). */ roots: Partial>; /** Root kinds two files name differently: no root of that kind is assessed. */ rootConflicts: GqlRootKind[]; /** Names defined in more than one file, with a fingerprint of all their definitions. */ ambiguous: Array<{ name: string; files: string[]; fingerprint: string; }>; /** * Types withheld for THEIR OWN shape — a duplicate field, enum value or argument — each with * why and a fingerprint of its definitions (change: scope-graphql-schema-universes). Absent from * `types`, exactly like an ambiguous name: which definition wins is not knowable. Every other * type in the same document is read and compared normally. */ unassessableTypes: Array<{ name: string; files: string[]; reason: string; fingerprint: string; }>; /** `extend`s of a type no file read defines (projected as extension-only types). */ orphanExtensions: Array<{ name: string; file: string; }>; /** Directive definitions by name; one defined in two files is absent (see `ambiguousDirectives`). */ directives: Map; /** Directives defined in more than one file, with a fingerprint of all their definitions. */ ambiguousDirectives: Array<{ name: string; files: string[]; fingerprint: string; }>; /** A hash of every directive on `schema` / `extend schema`. */ schemaDirectivesHash: string; conflicts: string[]; } /** * One element's content for comparison across revisions: no line, and no `file` (a merged field * carries the extension file it came from, which moving the extension changes). */ export declare const elementFingerprint: (x: unknown) => string; /** * Merge the documents of ONE project into one schema, as a GraphQL server does: one global namespace * (see {@link mergeGraphqlUniverses} for the partition into projects), * definitions and their `extend`s folded together. A name defined in two files — two services' * schemas in one repository, or a copy beside its source — is ambiguous and dropped from the * merged map, never guessed between; its fingerprint is kept so a change to it is still seen. */ export declare function mergeGraphqlSchema(docs: readonly GqlDocument[]): GqlSchema; /** * A schema read from NO file: every map empty and NO root names. * * Deliberately not `mergeGraphqlSchema([])`, which supplies GraphQL's default root names. Used as * the absent side of a comparison, those defaults would make a real `type Mutation` in a schema * whose `schema { query: … }` names no mutation root read as a ROOT at the empty side — and a root * is skipped, so its removal would go ungraded. */ export declare const emptyGqlSchema: () => GqlSchema; /** One project's merged schema, with the universe it belongs to and the files it was merged from. */ export interface GqlUniverseSchema { /** The project-root directory the schemas share; `''` is the repository root. */ universe: string; files: string[]; schema: GqlSchema; } /** * Merge the documents into ONE schema PER UNIVERSE (change: scope-graphql-schema-universes). * * GraphQL's namespace is global to a server, not to a repository. Merging every file of a monorepo * into one namespace made each project's `type Query` "defined in more than one file", which * withheld every operation of every project — so a genuine breaking change inside one of them was * never graded. Two schemas in DIFFERENT universes never collide; two in the SAME universe still * do, and stay unassessed, because there the ambiguity is real. */ export declare function mergeGraphqlUniverses(docs: readonly GqlDocument[], universeOf: (file: string) => string): GqlUniverseSchema[]; /** Every config file name {@link clientSchemaReferences} reads: what a caller collects. */ export declare const CLIENT_SCHEMA_CONFIG_FILE: RegExp; /** The schema one config names, resolved inside the config's own directory. */ export interface ClientSchemaReference { /** The schema path, relative to the repository root. */ schema: string; /** The config file that named it. */ config: string; /** The human name of the toolchain, for a disclosure line. */ tool: string; } /** * The single literal schema path each client-toolchain config names, resolved from the config's * own directory: `"relay": { "schema": "./schema/schema.graphql" }` in a `package.json`, * `schema: '…'` in `relay.config.*`, `localSchemaFile` in `apollo.config.*`, `schema:` in * `graphql.config.*` / `.graphqlrc*` / `codegen.*`. */ export declare function clientSchemaReferences(configs: ReadonlyArray<{ path: string; content: string; }>): ClientSchemaReference[]; /** The subset of {@link clientSchemaReferences} a Relay compiler config names. */ export declare function relaySchemaPaths(configs: ReadonlyArray<{ path: string; content: string; }>): Set; /** The named type inside a type reference: `[Order!]!` → `Order`. */ export declare const namedType: (type: string) => string; //# sourceMappingURL=graphql.d.ts.map