RFC: Implement a CLI for programmatic TS LSP & Checking tasks

[kitten]

Summary

Currently we have a split in what the TS LSP plugin validates and what gql.tada validates in TS typings.

gql.tada	@0no-co/graphqlsp
Errors on field and sub-selection types, if they don't match usage Errors, potentially, on invalid fragments and fragment spreads	Errors on unused fields and fragments Errors on unknown fragments Errors on invalid types passed to field arguments (other schema-side validation)

This creates a split experience, where the in-editor experience is cohesive, prompt, and accurate, but the tsc (i.e. type checking) step when compilation at build-time occurs lacks everything in @0no-co/graphqlsp, i.e. the TS LSP plugin.

This can further be summarised by the following issues:

• Set up isn't automated
• Checking whether the setup is correct isn't possible
• Linting isn't possible at build-time
• Static analysis (e.g. for persisted queries) isn't possible

Proposed Solution

We'd like to collect tasks for a CLI and implement them, possibly gradually over time.
A CLI would be runnable either as $ gql.tada or $ gql-tada, with the following sub-commands:

• gql-tada init: For setting up a project
• gql-tada doctor: For checking pre-condition (TypeScript version, tsconfig.json, etc)
  • This may also make suggestions re. the setup to the user that aren't critical to gql.tada functioning properly (e.g. for performance reasons)
• gql-tada check: For checking/linting steps in the TS LSP (document validation, unused fields, etc) as lint rules
  • This may allow for auto-fixing rules, similar to what eslint --fix does
• gql-tada generate-output: For generating tadaOutputLocation i.e. generated file
• gql-tada generate-schema: For generating a schema that the TS LSP plugin can consume
  • This is a pain point for projects where no other tool outputs a schema.graphql file and can be supplemented by this CLI
• gql-tada generate-persisted: For generating a list of persisted documents (TBD for future RFC)

The exact names of these subcommands isn't determined yet.

Requirements

TBD

• gql-tada check and gql-tada generate-output must be runnable in CI

[wyattades]

I'm currently using https://github.com/Quramy/ts-graphql-plugin but I'm hoping to eliminate the slow file generation step completely. Maybe gql.tada could help!

Here is our current script running in CI:

# generate new graphql query types (to __gql_generated__)
rm -rf src/__gql_generated__ && npx ts-graphql-plugin typegen

# if any files changed, fail CI. This means someone forgot to run typegen locally.
git diff --exit-code

# type-checks
npx tsc --noEmit

It seems like gql.tada could work the same way, but replace line 1 with npx gql-tada generate-output?

Alternatively, I guess it would be possible to: not commit graphql-env.d.ts to source-control and generate it on the fly in CI.

Either way, is there a workaround for now to generate the introspection file programmatically?

[kitten]

@wyattades A rough version of the code that generates the introspection file in a CLI is already on main and published, so you can give it a try by installing the canary version and running it

[numfin]

is there a way rn to programmatically generate graphql-env.d.ts file? I don't mind creating little script in my project
p.s. answering my own question: npx gql.tada@canary generate

Thank you for your work again. Love this tool