@khanacademy/graphql-flow 0.0.1

package/src/jest-mock-graphql-tag.js

@@ -0,0 +1,191 @@
+// @flow
+// Import this in your jest setup, to mock out graphql-tag!
+import type {DocumentNode, IntrospectionQuery} from 'graphql';
+import type {Schema, Options, Scalars} from './types';
+import {validate} from 'graphql/validation';
+import {buildClientSchema} from 'graphql';
+import {print} from 'graphql/language/printer';
+import {addTypenameToDocument} from 'apollo-utilities'; // eslint-disable-line flowtype-errors/uncovered
+import {schemaFromIntrospectionData} from './schemaFromIntrospectionData';
+
+const indexPrelude = `// @flow
+//
+// AUTOGENERATED
+// NOTE: New response types are added to this file automatically.
+//       Outdated response types can be removed manually as they are deprecated.
+//
+
+`;
+
+const generateTypeFiles = (
+    schema: Schema,
+    document: DocumentNode,
+    options: Options,
+) => {
+    const {documentToFlowTypes} = require('.');
+    const path = require('path');
+    const fs = require('fs');
+    const format: ({text: string}) => string = require('prettier-eslint'); // eslint-disable-line flowtype-errors/uncovered
+
+    const indexFile = (generatedDir) => path.join(generatedDir, 'index.js');
+
+    const maybeCreateGeneratedDir = (generatedDir) => {
+        if (!fs.existsSync(generatedDir)) {
+            fs.mkdirSync(generatedDir, {recursive: true});
+
+            // Now write an index.js for each __generated__ dir.
+            fs.writeFileSync(indexFile(generatedDir), indexPrelude);
+        }
+    };
+
+    /// Write export for __generated__/index.js if it doesn't exist
+    const writeToIndex = (filePath, typeName) => {
+        const index = indexFile(path.dirname(filePath));
+        const indexContents = fs.readFileSync(index, 'utf8');
+        const newLine = `export type {${typeName}} from './${path.basename(
+            filePath,
+        )}';`;
+        if (indexContents.indexOf(path.basename(filePath)) === -1) {
+            fs.appendFileSync(index, newLine + '\n');
+        } else {
+            const lines = indexContents.split('\n').map((line) => {
+                if (line.includes(path.basename(filePath))) {
+                    return newLine;
+                }
+                return line;
+            });
+            fs.writeFileSync(index, lines.join('\n'));
+        }
+    };
+
+    // Get the name of the file that `gql` was called from
+    const errorLines = new Error().stack.split('\n');
+    const fileName = errorLines[3].split('(').slice(-1)[0].split(':')[0];
+
+    const generated = documentToFlowTypes(document, schema, options);
+    generated.forEach(({name, typeName, code}) => {
+        // We write all generated files to a `__generated__` subdir to keep
+        // things tidy.
+        const targetFileName = `${typeName}.js`;
+        const generatedDir = path.join(path.dirname(fileName), '__generated__');
+        const targetPath = path.join(generatedDir, targetFileName);
+
+        maybeCreateGeneratedDir(generatedDir);
+
+        // NOTE: Uncomment this to write the query definitions to disk if
+        // you need to add new features to the flow type generation
+        // fs.writeFileSync(
+        //     targetFileName + '.query',
+        //     JSON.stringify(definitions, null, 2),
+        // );
+        const fileContents = format({
+            text:
+                '// @' +
+                `flow\n// AUTOGENERATED -- DO NOT EDIT\n` +
+                `// Generated for operation '${name}' in file '../${path.basename(
+                    fileName,
+                )}'\n` +
+                `// To regenerate, run 'yarn test queries'.\n` +
+                code,
+        });
+        fs.writeFileSync(targetPath, fileContents);
+
+        writeToIndex(targetPath, typeName);
+    });
+};
+
+type GraphqlTagFn = (raw: string, ...args: Array<any>) => DocumentNode;
+
+type SpyOptions = {
+    pragma?: string,
+    loosePragma?: string,
+    scalars?: Scalars,
+    strictNullability?: boolean,
+    readOnlyArray?: boolean,
+};
+
+// This function is expected to be called like so:
+//
+// jest.mock('graphql-tag', () => {
+//     const introspectionData = jest.requireActual(
+//         './our-introspection-query.json',
+//     );
+//     const {spyOnGraphqlTagToCollectQueries} = jest.requireActual(
+//         'graphql-flow/jest-mock-graphql-tag.js');
+//
+//     return spyOnGraphqlTagToCollectQueries(
+//         jest.requireActual('graphql-tag'),
+//         introspectionData,
+//     );
+// });
+//
+// If both pragma and loosePragma are empty, then all graphql
+// documents will be processed. Otherwise, only documents
+// with one of the pragmas will be processed.
+const spyOnGraphqlTagToCollectQueries = (
+    realGraphqlTag: GraphqlTagFn,
+    introspectionData: IntrospectionQuery,
+    options: SpyOptions = {},
+): GraphqlTagFn => {
+    const collection: Array<{
+        raw: string,
+        errors: $ReadOnlyArray<Error>,
+    }> = [];
+
+    const clientSchema = buildClientSchema(introspectionData);
+    const schema = schemaFromIntrospectionData(introspectionData);
+
+    const wrapper = function gql() {
+        const document: DocumentNode = realGraphqlTag.apply(this, arguments); // eslint-disable-line flowtype-errors/uncovered
+        const hasNonFragments = document.definitions.some(
+            ({kind}) => kind !== 'FragmentDefinition',
+        );
+        if (hasNonFragments) {
+            // eslint-disable-next-line flowtype-errors/uncovered
+            const withTypeNames: DocumentNode = addTypenameToDocument(document);
+            collection.push({
+                raw: print(withTypeNames),
+                errors: validate(clientSchema, document),
+            });
+
+            const rawSource: string = arguments[0].raw[0]; // eslint-disable-line flowtype-errors/uncovered
+            const processedOptions = processPragmas(options, rawSource);
+            if (processedOptions) {
+                generateTypeFiles(schema, withTypeNames, processedOptions);
+            }
+        }
+        return document;
+    };
+    wrapper.collectedQueries = collection;
+    return wrapper;
+};
+
+const processPragmas = (
+    options: SpyOptions,
+    rawSource: string,
+): null | Options => {
+    const autogen = options.loosePragma
+        ? rawSource.includes(options.loosePragma)
+        : false;
+    const autogenStrict = options.pragma
+        ? rawSource.includes(options.pragma)
+        : false;
+    const noPragmas = !options.loosePragma && !options.pragma;
+
+    if (autogen || autogenStrict || noPragmas) {
+        return {
+            strictNullability: noPragmas
+                ? options.strictNullability
+                : autogenStrict || !autogen,
+            readOnlyArray: options.readOnlyArray,
+            scalars: options.scalars,
+        };
+    } else {
+        return null;
+    }
+};
+
+module.exports = {
+    processPragmas,
+    spyOnGraphqlTagToCollectQueries,
+};

package/src/schemaFromIntrospectionData.js

@@ -0,0 +1,68 @@
+// @flow
+/**
+ * Takes the introspectionQuery response and parses it into the "Schema"
+ * type that we use to look up types, interfaces, etc.
+ */
+import type {IntrospectionQuery} from 'graphql';
+import type {Schema} from './types';
+
+export const schemaFromIntrospectionData = (
+    schema: IntrospectionQuery,
+): Schema => {
+    const result: Schema = {
+        interfacesByName: {},
+        typesByName: {},
+        inputObjectsByName: {},
+        unionsByName: {},
+        enumsByName: {},
+    };
+
+    schema.__schema.types.forEach((type) => {
+        if (type.kind === 'ENUM') {
+            result.enumsByName[type.name] = type;
+            return;
+        }
+        if (type.kind === 'UNION') {
+            result.unionsByName[type.name] = type;
+            return;
+        }
+        if (type.kind === 'INTERFACE') {
+            result.interfacesByName[type.name] = {
+                ...type,
+                possibleTypesByName: {},
+                fieldsByName: {},
+            };
+            type.possibleTypes.forEach(
+                (p) =>
+                    (result.interfacesByName[type.name].possibleTypesByName[
+                        p.name
+                    ] = true),
+            );
+            type.fields.forEach((field) => {
+                result.interfacesByName[type.name].fieldsByName[field.name] =
+                    field;
+            });
+            return;
+        }
+        if (type.kind === 'INPUT_OBJECT') {
+            result.inputObjectsByName[type.name] = type;
+            return;
+        }
+        if (type.kind === 'SCALAR') {
+            return;
+        }
+        result.typesByName[type.name] = {
+            ...type,
+            fieldsByName: {},
+        };
+        if (!type.fields) {
+            return;
+        }
+
+        type.fields.forEach((field) => {
+            result.typesByName[type.name].fieldsByName[field.name] = field;
+        });
+    });
+
+    return result;
+};

package/src/types.js

@@ -0,0 +1,54 @@
+// @flow
+
+import type {
+    FragmentDefinitionNode,
+    IntrospectionEnumType,
+    IntrospectionField,
+    IntrospectionInputObjectType,
+    IntrospectionInterfaceType,
+    IntrospectionObjectType,
+    IntrospectionUnionType,
+    SelectionNode,
+} from 'graphql';
+
+export type Selections = $ReadOnlyArray<SelectionNode>;
+
+export type Options = {|
+    strictNullability?: boolean, // default true
+    readOnlyArray?: boolean, // default true
+    scalars?: Scalars,
+|};
+
+export type Schema = {
+    interfacesByName: {
+        [key: string]: IntrospectionInterfaceType & {
+            fieldsByName: {[key: string]: IntrospectionField},
+            possibleTypesByName: {[key: string]: boolean},
+        },
+    },
+    inputObjectsByName: {
+        [key: string]: IntrospectionInputObjectType,
+    },
+    typesByName: {
+        [key: string]: IntrospectionObjectType & {
+            fieldsByName: {[key: string]: IntrospectionField},
+        },
+    },
+    unionsByName: {
+        [key: string]: IntrospectionUnionType,
+    },
+    enumsByName: {
+        [key: string]: IntrospectionEnumType,
+    },
+};
+
+export type Config = {
+    strictNullability: boolean,
+    readOnlyArray: boolean,
+    fragments: {[key: string]: FragmentDefinitionNode},
+
+    schema: Schema,
+    scalars: Scalars,
+    errors: Array<string>,
+};
+export type Scalars = {[key: string]: 'string' | 'number' | 'boolean'};

package/src/utils.js

@@ -0,0 +1,50 @@
+// @flow
+
+import * as babelTypes from '@babel/types';
+import {BabelNodeObjectTypeProperty} from '@babel/types';
+
+export const liftLeadingPropertyComments = (
+    property: BabelNodeObjectTypeProperty,
+): BabelNodeObjectTypeProperty => {
+    return transferLeadingComments(property.value, property);
+};
+
+export const maybeAddDescriptionComment = <T: babelTypes.BabelNode>(
+    description: ?string,
+    node: T,
+): T => {
+    if (description) {
+        addCommentAsLineComments(description, node);
+    }
+    return node;
+};
+
+export function addCommentAsLineComments(
+    description: string,
+    res: babelTypes.BabelNode,
+) {
+    if (res.leadingComments?.length) {
+        res.leadingComments[0].value += '\n\n---\n\n' + description;
+    } else {
+        babelTypes.addComment(
+            res,
+            'leading',
+            '* ' + description,
+            false, // this specifies that it's a block comment, not a line comment
+        );
+    }
+}
+
+export const transferLeadingComments = <T: babelTypes.BabelNode>(
+    source: babelTypes.BabelNode,
+    dest: T,
+): T => {
+    if (source.leadingComments?.length) {
+        dest.leadingComments = [
+            ...(dest.leadingComments || []),
+            ...source.leadingComments,
+        ];
+        source.leadingComments = [];
+    }
+    return dest;
+};

package/tools/find-files-with-gql.js

@@ -0,0 +1,40 @@
+// @flow
+const path = require('path');
+const {execSync} = require('child_process');
+
+export const findRepoRoot = (): string => {
+    try {
+        const res = execSync('git rev-parse --show-toplevel', {
+            encoding: 'utf8',
+        });
+        return res.trim();
+        // eslint-disable-next-line flowtype-errors/uncovered
+    } catch (err) {
+        throw new Error(
+            // eslint-disable-next-line flowtype-errors/uncovered
+            `Unable to use git rev-parse to find the repository root. ${err.message}`,
+        );
+    }
+};
+
+export const findGraphqlTagReferences = (root: string): Array<string> => {
+    try {
+        const response = execSync(
+            "git grep -I --word-regexp --name-only --fixed-strings 'gql`' -- '*.js'",
+            {
+                encoding: 'utf8',
+                cwd: root,
+            },
+        );
+        return response
+            .trim()
+            .split('\n')
+            .map((relative) => path.join(root, relative));
+        // eslint-disable-next-line flowtype-errors/uncovered
+    } catch (err) {
+        throw new Error(
+            // eslint-disable-next-line flowtype-errors/uncovered
+            `Unable to use git grep to find files with gql tags. ${err.message}`,
+        );
+    }
+};