@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 121 lines 4.33 KB
Raw
1 /**
2 * Generates typed GraphQL modules and diagnostics without writing to disk.
3 * The CLI uses {@link generate} to write, check or watch the output.
4 *
5 * @since 4.0.0
6 */
7 import type * as Effect from "effect/Effect"
8 import type * as FileSystem from "effect/FileSystem"
9 import type * as Path from "effect/Path"
10 import type { PlatformError } from "effect/PlatformError"
11 import type { Config } from "./Config.ts"
12 import * as Generate from "./internal/Generate.ts"
13
14 /**
15 * A generated file: an absolute path and the full contents to write there.
16 *
17 * @stability experimental
18 * @category models
19 * @since 4.0.0
20 */
21 export interface GeneratedFile {
22 readonly path: string
23 readonly contents: string
24 }
25
26 /**
27 * A problem found while generating.
28 *
29 * - `path` is relative to the `cwd` passed to {@link generate}, with `/`
30 * separators.
31 * - `line` and `column` are 1-based. They, and `codeFrame`, are `undefined`
32 * for diagnostics about the run as a whole, such as the unmapped-scalars
33 * warning, which is reported against the schema file.
34 * - Any `"error"` means the output must not be written. Warnings don't stop
35 * generation.
36 *
37 * @stability experimental
38 * @category models
39 * @since 4.0.0
40 */
41 export interface Diagnostic {
42 readonly severity: "error" | "warning"
43 readonly path: string
44 readonly line: number | undefined
45 readonly column: number | undefined
46 readonly message: string
47 readonly codeFrame: string | undefined
48 }
49
50 /**
51 * The result of {@link generate}. `files` and `deletes` are empty when
52 * `diagnostics` holds an error.
53 *
54 * `deletes` lists stale `*.graphql.ts` and `*.gql.ts` files by absolute path.
55 * A file qualifies only under a `documents` glob root, with a generator
56 * header naming a missing sibling source, and when absent from `files`.
57 * Shared modules and files without a matching document header are excluded.
58 *
59 * @stability experimental
60 * @category models
61 * @since 4.0.0
62 */
63 export interface GenerateResult {
64 readonly files: ReadonlyArray<GeneratedFile>
65 readonly deletes: ReadonlyArray<string>
66 readonly diagnostics: ReadonlyArray<Diagnostic>
67 }
68
69 /**
70 * The config cannot be used with this schema, e.g. a `scalars` key that
71 * isn't a custom scalar or a built-in `Int`, `Float` or `ID`, or an absolute
72 * `documents` pattern.
73 *
74 * @stability experimental
75 * @category errors
76 * @since 4.0.0
77 */
78 export { ConfigError } from "./internal/Generate.ts"
79
80 /**
81 * Generates the `.graphql.ts` module for every document file and the shared
82 * module, in memory.
83 *
84 * **Details**
85 *
86 * - Relative paths in the config, and the `documents` globs, resolve against
87 * `options.cwd`, which is normally the config file's directory.
88 * - `foo.graphql` generates `foo.graphql.ts` next to it, and `foo.gql`
89 * generates `foo.gql.ts`.
90 * - The shared module goes to `config.shared`, or next to the schema as
91 * `<schema name>.graphql.ts`, and holds only the scalars, enums, input
92 * objects and possible `__typename` unions the operations reach. A `shared`
93 * path equal to the schema, a document or a document's output is an error
94 * diagnostic.
95 * - Entries under a glob root that can't be read, such as dangling symlinks,
96 * are skipped.
97 * - Custom scalars named `DateTime` and `URI` default to
98 * `Schema.DateTimeUtcFromString` and `Schema.String`. Configured `scalars`
99 * override these defaults. Other unmapped custom scalars decode as
100 * `Schema.Json`, and one warning lists every one the operations reach.
101 * - A selection on an interface or union decodes as a `Schema.Union`
102 * discriminated by `__typename`, which is added to the document. Types the
103 * selection doesn't name, including ones the server adds later, fall into
104 * a last member built with `GraphQL.otherTypename`.
105 * - `@skip` / `@include` with a variable condition make the fields they cover
106 * optional keys; literal conditions are folded.
107 * - Input objects on a cycle, such as filters with `and` / `or`, are
108 * `Schema.Codec` consts annotated with written-out Type and Encoded
109 * interfaces, and reference the cycle through `Schema.suspend`.
110 *
111 * @stability experimental
112 * @category generation
113 * @since 4.0.0
114 */
115 export const generate: (
116 config: Config,
117 options: { readonly cwd: string }
118 ) => Effect.Effect<GenerateResult, Generate.ConfigError | PlatformError, FileSystem.FileSystem | Path.Path> = (
119 config,
120 options
121 ) => Generate.generate(config, { cwd: options.cwd })