@khanacademy/graphql-flow 0.3.0 → 1.0.0

package/.github/workflows/pr-checks.yml

@@ -22,16 +22,14 @@ jobs:
         node-version: ${{ matrix.node-version }}
 
     - name: Get All Changed Files
-      uses: jaredly/get-changed-files@absolute
+      uses: Khan/actions@get-changed-files-v1
       id: changed
-      with:
-        format: 'json'
 
     - id: js-files
       name: Find .js changed files
       uses: Khan/actions@filter-files-v0
       with:
-        changed-files: ${{ steps.changed.outputs.added_modified }}
+        changed-files: ${{ steps.changed.outputs.files }}
         extensions: '.js'
 
     - name: Run Flow
@@ -42,7 +40,7 @@ jobs:
       uses: Khan/actions@filter-files-v0
       name: Files that would trigger a full eslint run
       with:
-        changed-files: ${{ steps.changed.outputs.added_modified }}
+        changed-files: ${{ steps.changed.outputs.files }}
         files: '.eslintrc.js,package.json,.eslintignore'
 
     - name: Eslint
@@ -57,7 +55,7 @@ jobs:
       uses: Khan/actions@filter-files-v0
       name: Files that would trigger a full jest run
       with:
-        changed-files: ${{ steps.changed.outputs.added_modified }}
+        changed-files: ${{ steps.changed.outputs.files }}
         files: 'package.json,package-lock.json'
 
     - name: Jest

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @khanacademy/graphql-flow
 
+## 1.0.0
+
+### Major Changes
+
+-   1e1de13: BREAKING: Change config file format, split into 'crawl' and 'generate' sections
+    See schema.json for new organization.
+-   284be55: [breaking] remove support for running graphql-flow via jest
+
+    Now the cli tool is the only way to invoke graphql-flow.
+
+-   9f7f2d1: Breaking: removed support for multiple config files (to be replaced with override support in the central config file)
+
+### Minor Changes
+
+-   a99fc38: Support multiple 'generate' configs, allowing projects to have different settings for different directories or files
+
+    `config.generate` can now be an object or an array of objects, with `match` and `exclude` arrays (either a RegExp or a string that will be passed to `new RegExp()`) to fine-tune which files they apply to.
+
+### Patch Changes
+
+-   bcc06d0: Use jsonschema for validating the config file
+
 ## 0.3.0
 
 ### Minor Changes

package/Readme.md

@@ -4,44 +4,7 @@ This is a tool for generating flow types from graphql queries in javascript fron
 
 ## Using as a CLI tool
 
-Write a config file, with the following options:
-
-```json
-{
-    // Response to the "introspection query" (see below), or a .graphql schema file.
-    // The file extension indicates the format, .json or .graphql (default .json).
-    // This path is resolved relative to the config file location.
-    "schemaFilePath": "../some/schema-file.json",
-    // List of regexes
-    "excludes": ["\\bsome-thing", "_test.jsx?$"],
-    // Options for type generation (see below)
-    "options": {
-        "scalars": {
-            "JSONString": "string"
-        }
-    }
-}
-```
-
-Optionally add subconfig files to subdirectories for granular control of behavior, with the following options:
-
-```json
-{
-    // Note that this file must be named, or end with, "graphql-flow.config.json"
-    // I.e., "my-service.graphql.config.json" would also work.
-    // These files will affect the directory in which they are located and all subdirectories, unless overridden by a deeper subconfig.
-
-    // Optionally add the path of another config file. Can be the root config (provided when running the script) or any other subconfig to merge options.
-    // If a chain of extends are provided, will resolve in order. Be sure not to extend in a circle-- currently, this will just cause a stack overflow error. 
-    // Cannot currently override `schemaFilePath`.
-    "extends": "./another/config/from/root.config.json",
-    // Can extend or override `excludes` and `options`.
-    "excludes": ["\\bsome-thing", "_test.jsx?$"],
-    "options": {
-        ...
-    }
-}
-```
+Write a config file, following the schema defined in [src/cli/schema.json](src/cli/schema.json), either as a `.json` file, or a `.js` file that `module.exports` an object adhering to the schema.
 
 Then run from the CLI, like so:
 
@@ -49,143 +12,54 @@ Then run from the CLI, like so:
 $ graphql-flow path/to/config.json
 ```
 
-Files will be discovered relative to the current working directory.
-
-To specify what file should be checked, pass them in as subsequent cli arguments.
-
-## Options (for the cli 'options' config item, or when running from jest):
-
-```ts
-type Options = {
-    // These are from the `documentToFlowTypes` options object above
-    strictNullability: boolean = true,
-    readOnlyArray: boolean = true,
-    scalars: {[key: string]: 'string' | 'boolean' | 'number'}
-
-    // Specify the name of the generated types directory.  If this
-    // is a relative path, then this is used to suffix the output
-    // directory; if it's an absolute path it's used to prefix the
-    // output directory.  For instance, if a gql directive is
-    // found in /foo/bar/baz/query.js and you run the cli (or
-    // jest) from directory /foo, then:
-    // * if `generatedDirectory` is "__generated__", the output will
-    //   be in /foo/bar/baz/__generated__/index.js and sibling files
-    // * if `generatedDirectory` is "/tmp/__generated__", the output
-    //   will be in /tmp/__generated__/bar/baz/index.js and sibling
-    //   files.
-    generatedDirectory: string = '__generated__',
-
-    // The default generated type contains both the types of the response
-    // and the variables, combined as [operatioName]Type. Setting
-    // `splitTypes = true` adds the additional exports [operationName]
-    // (for the response) and [operationName]Variables (for the variables).
-    splitTypes?: boolean,
-
-    // Specify an opt-in pragma that must be present in a graphql string source
-    // in order for it to be picked up and processed
-    // e.g. set this to `"# @autogen\n"` to only generate types for queries that
-    // have the comment `# @autogen` in them.
-    pragma?: string,
-    // Specify a pragma that will turn off `strictNullability` for that
-    // source file. e.g. `"# @autogen-loose\n"`.
-    loosePragma?: string,
-    // If neither pragma nor loosePragma are specified, all graphql documents
-    // that contain a query or mutation will be processed.
-
-    // Any graphql operations containing ignorePragma will be skipped
-    ignorePragma?: string,
-
-    // Set to true to mirror gqlgen's behavior of exporting all
-    // nested object types within the response type.
-    // Names are generated by concatenating the attribute names
-    // of the path to the object type, separated by underscores.
-    exportAllObjectTypes?: boolean,
-
-    // A template for the name of generated files
-    // default: [operationName].js
-    typeFileName?: string,
-
-    // Generate flow enums to replace literal unions in generated types. Exports
-    // each set of enums from each file regardless of other options. Designated
-    // "experimental" because of bug in eslint that requires config comments.
-    experimentalEnums?: boolean,
-}
-```
-
-## Using from jest
-
-You can also use jest to do the heavy lifting, running all of your code and collecting queries
-by mocking out the `graphql-tag` function itself. This requires that all graphql operations are
-defined at the top level (no queries defined in functions or components, for example), but does
-support complicated things like returning a fragment from a function (which is probably
-not a great idea code-style-wise anyway).
-
-### jest-setup.js
-
-Add the following snippet to your jest-setup.js
+Files will be discovered relative to the `crawl.root`.
 
-```js
-if (process.env.GRAPHQL_FLOW) {
-    jest.mock('graphql-tag', () => {
-        const introspectionData = jest.requireActual(
-            './server-introspection-response.json',
-        );
-
-        return jest.requireActual('../tools/graphql-flow/jest-mock-graphql-tag.js')(
-            introspectionData,
-            // See "Options" type above
-            {
-                pragma: '# @autogen\n',
-                loosePragma: '# @autogen-loose\n',
-            }
-        );
-    });
-}
-```
+### Multiple generate configs
 
-That will mock out the `graphql-tag` function, so that everywhere you call 'gql`some-query`', we'll pick it up and
-generate a type for it! As written, the mocking only happens if the `GRAPHQL_FLOW` env variable is set, so that it won't run every time.
+To customize type generation for certain directories or files, you can provide multiple
+`generate` configs as an array, using `match` and `exclude` to customize behavior.
 
-By default, all queries are processed. To have them 'opt-in', use the `pragma` and `loosePragma` options. Queries with `loosePragma` in the source will have types generated that ignore nullability.
+For a given file containing operations, the first `generate` config that matches that path
+(and doesn't exclude it) will be used to generate types for those operations. If a `generate`
+config doesn't have a `match` attribute, it will match all files (but might exclude some via the
+`exclude` attribute).
 
-### Ensure all files with queries get processed by jest
+For example:
 
-Then you'll want to make a pseudo-'test' that makes sure to 'require' all of the files that define queries, so that
-jest will process them and our mock will see them. 
 ```js
-// generate-types.test.js
-import {findGraphqlTagReferences} from '../tools/graphql-flow/find-files-with-gql';
-import path from 'path';
-
-if (process.env.GRAPHQL_FLOW) {
-    findGraphqlTagReferences(path.join(__dirname, '..')).forEach(name => {
-        require(name);
-    });
-
-    it('should have found queries', () => {
-        const gql = require('graphql-tag')
-        expect(gql.collectedQueries.length).toBeGreaterThan(0)
-    })
-} else {
-    it(`not generating graphql types because the env flag isn't set`, () => {
-        // not doing anything because the env flag isn't set.
-    })
-}
-```
-
-### Run that test to generate the types!
-
-You can add a script to package.json, like so:
-```json
-    "scripts": {
-        "generate-types": "env GRAPHQL_FLOW=1 jest generate-types.test.js"
-    }
+// dev/graphql-flow/config.js
+
+const options = {
+    schemaFilePath: "../../gengraphql/composed-schema.graphql",
+    regenerateCommand: "make gqlflow",
+    generatedDirectory: "__graphql-types__",
+    exclude: [
+        /_test.js$/,
+        /.fixture.js$/,
+        /\b__flowtests__\b/,
+    ],
+};
+
+module.exports = {
+    crawl: {
+        root: "../../",
+    },
+    generate: [
+        {
+            ...options,
+            schemaFilePath: "../../gengraphql/course-editor-schema.graphql",
+            match: [/\bcourse-editor-package\b/, /\bcourse-editor\b/],
+        },
+        {
+            ...options,
+            match: [/\bdiscussion-package\b/]
+            experimentalEnums: true,
+        },
+        options,
+    ],
+};
 ```
 
-And then `yarn generate-types` or `npm run generate-types` gets your types generated!
-
-🚀
-
 ## Introspecting your backend's graphql schema
 Here's how to get your backend's schema in the way that this tool expects, using the builtin 'graphql introspection query':
 

package/dist/__test__/example-schema.graphql

@@ -0,0 +1,67 @@
+scalar PositiveNumber
+
+enum Episode { NEW_HOPE, EMPIRE, JEDI }
+
+"""
+A movie character
+"""
+interface Character {
+  id: String!
+  name: String
+  friends: [Character]
+  appearsIn: [Episode]
+}
+
+"""
+A human character
+"""
+type Human implements Character {
+  id: String!
+  """The person's name"""
+  name: String
+  friends: [Character]
+  appearsIn: [Episode]
+  homePlanet: String
+  alive: Boolean
+  hands: PositiveNumber
+}
+
+"""
+A robot character
+"""
+type Droid implements Character {
+  id: String!
+  name: String
+  friends: [Character]
+  appearsIn: [Episode]
+  """The robot's primary function"""
+  primaryFunction: String!
+}
+
+type Animal {
+  name: String
+}
+
+union Friendable = Human | Droid | Animal
+
+type Query {
+  hero(episode: Episode): Character
+  human(id: String!): Human
+  droid(id: String!): Droid
+  friend(id: String!): Friendable
+  candies(number: PositiveNumber!): String
+}
+
+"""A character to add"""
+input CharacterInput {
+  """The new character's name"""
+  name: String!
+  """The character's friends"""
+  friends: [ID!]
+  appearsIn: [Episode!]
+  candies: PositiveNumber!
+}
+
+type Mutation {
+  addCharacter(character: CharacterInput!): Character
+}

package/dist/__test__/generateTypeFileContents.test.js

@@ -0,0 +1,157 @@
+// @flow
+// Test the generate the type file contents
+
+import {getSchemas} from '../cli/config';
+import {generateTypeFileContents, indexPrelude} from '../generateTypeFiles';
+import gql from 'graphql-tag';
+
+const [_, exampleSchema] = getSchemas(__dirname + '/example-schema.graphql');
+
+describe('generateTypeFileContents', () => {
+    it('split types should export response & variables types', () => {
+        const {indexContents, files} = generateTypeFileContents(
+            'hello.js',
+            exampleSchema,
+            gql`
+                query Hello {
+                    human(id: "Han") {
+                        id
+                    }
+                }
+            `,
+            {splitTypes: true, schemaFilePath: ''},
+            '__generated__',
+            indexPrelude('yarn queries'),
+        );
+        expect(indexContents).toMatchInlineSnapshot(`
+            "// @flow
+            //
+            // AUTOGENERATED
+            // NOTE: New response types are added to this file automatically.
+            //       Outdated response types can be removed manually as they are deprecated.
+            //      To regenerate, run yarn queries
+            //
+
+            export type {HelloType} from './Hello.js';
+            "
+        `);
+        expect(
+            Object.keys(files)
+                .map((k) => `// ${k}\n${files[k]}`)
+                .join('\n\n'),
+        ).toMatchInlineSnapshot(`
+            "// __generated__/Hello.js
+            // @flow
+            // AUTOGENERATED -- DO NOT EDIT
+            // Generated for operation 'Hello' in file '../hello.js'
+            export type HelloType = {|
+                variables: {||},
+                response: {|
+              /** A human character*/
+              human: ?{|
+                id: string
+              |}
+            |}
+            |};
+            export type Hello = HelloType['response'];
+            export type HelloVariables = HelloType['variables'];
+            "
+        `);
+    });
+
+    it('should respect the typeFileName option', () => {
+        const {files} = generateTypeFileContents(
+            'hello.js',
+            exampleSchema,
+            gql`
+                query Hello {
+                    human(id: "Han") {
+                        id
+                    }
+                }
+            `,
+            {
+                splitTypes: true,
+                typeFileName: 'prefix-[operationName]-suffix.js',
+                schemaFilePath: '',
+            },
+            '__generated__',
+            indexPrelude('yarn queries'),
+        );
+        expect(
+            Object.keys(files)
+                .map((k) => `// ${k}\n${files[k]}`)
+                .join('\n\n'),
+        ).toMatchInlineSnapshot(`
+            "// __generated__/prefix-Hello-suffix.js
+            // @flow
+            // AUTOGENERATED -- DO NOT EDIT
+            // Generated for operation 'Hello' in file '../hello.js'
+            export type HelloType = {|
+                variables: {||},
+                response: {|
+              /** A human character*/
+              human: ?{|
+                id: string
+              |}
+            |}
+            |};
+            export type Hello = HelloType['response'];
+            export type HelloVariables = HelloType['variables'];
+            "
+        `);
+    });
+
+    describe('experimentalEnums', () => {
+        it('should generate the expected values', () => {
+            const {files} = generateTypeFileContents(
+                'hello.js',
+                exampleSchema,
+                gql`
+                    query Hello {
+                        human(id: "Han") {
+                            appearsIn
+                        }
+                    }
+                `,
+                {
+                    experimentalEnums: true,
+                    schemaFilePath: '',
+                },
+                '__generated__',
+                indexPrelude('yarn queries'),
+            );
+            expect(
+                Object.keys(files)
+                    .map((k) => `// ${k}\n${files[k]}`)
+                    .join('\n\n'),
+            ).toMatchInlineSnapshot(`
+                "// __generated__/Hello.js
+                // @flow
+                // AUTOGENERATED -- DO NOT EDIT
+                // Generated for operation 'Hello' in file '../hello.js'
+                export type HelloType = {|
+                    variables: {||},
+                    response: {|
+                  /** A human character*/
+                  human: ?{|
+                    appearsIn: ?$ReadOnlyArray<
+                    /** - NEW_HOPE
+                    - EMPIRE
+                    - JEDI*/
+                    ?Episode>
+                  |}
+                |}
+                |};
+                /* eslint-disable no-undef */
+                export enum Episode {
+                  NEW_HOPE,
+                  EMPIRE,
+                  JEDI,
+                };
+                /* eslint-enable no-undef */
+                "
+            `);
+        });
+    });
+});