@capacms/sdk 1.0.0-next.0 → 1.0.0-next.10

package/dist/graphql-codegen.js

@@ -0,0 +1,705 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGraphQL = loadGraphQL;
+exports.cookTemplate = cookTemplate;
+exports.extractDocuments = extractDocuments;
+exports.generateGraphQLModule = generateGraphQLModule;
+const sha256_1 = require("./next/graphql/sha256");
+const summary_1 = require("./next/graphql/summary");
+const tree_layout_1 = require("./next/graphql/tree-layout");
+let loaded = null;
+/** graphql-js, or an error that says how to get it. */
+function loadGraphQL() {
+    if (loaded)
+        return loaded;
+    try {
+        loaded = require("graphql");
+    }
+    catch {
+        throw new Error("capa-codegen --graphql and capa persist need the graphql package: pnpm add -D graphql");
+    }
+    return loaded;
+}
+const INTERPOLATED = "a template with ${} in it cannot be checked ahead of time, since its text is only known at run time";
+/** Why a literal's `${NAME}` is not read: NAME is no literal of the project, as a fragment literal is. */
+const unknownInterpolation = (name) => `a template with \${} in it is read only when each \${} names a #graphql literal of this project, and ${name} is not one, so its text is only known at run time`;
+const NEEDS_AS_CONST = "Add `as const` after this template: TypeScript keeps the text of a template with ${} only then, and client.graphql types the call by that text.";
+/** `${NAME}`, a bare identifier: the one interpolation codegen resolves, from another literal of the project. */
+const NAMED_INTERPOLATION = /\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
+/** The variable a template is assigned to, from the text just before it: `export const CARD = `, `const Q = /* capa *\/ `, `const Q = gql(`. */
+const ASSIGNED_TO = /(?:^|[\s;{(,])(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]+)?=\s*(?:\/\*\s*capa\s*\*\/\s*|gql\s*\(\s*)?$/;
+const UNMARKED = "it looks like a GraphQL document but is not marked as one: start it with #graphql, put /* capa */ before it, or write gql(`...`)";
+const FETCH_TAG = "graphql`...` is /nextjs's request helper, not a tag: write gql`...`, or start the template with #graphql";
+/** Any template literal, and one whose text opens like a GraphQL operation or fragment. */
+const ANY_TEMPLATE = /`((?:[^`\\]|\\[\s\S])*)`/g;
+const LOOKS_LIKE_GRAPHQL = /^\s*(?:(?:query|fragment|mutation|subscription)\s+[_A-Za-z]\w*\s*[({@]|query\s*\{|\{\s*[_A-Za-z]\w*\s*[({])/;
+/**
+ * The template forms codegen reads, in order of precedence for a template two
+ * of them match. A template's body is anything but a backtick, or an escaped
+ * character. `gql` as a function keeps the literal's type; as a tag it returns
+ * a plain string. `graphql` is not one of them: it is `/nextjs`'s request
+ * helper, and graphql`...` would run a request, not declare a document.
+ */
+const TEMPLATES = [
+    { pattern: /\bgql\s*\(\s*`((?:[^`\\]|\\[\s\S])*)`/g, literal: true },
+    { pattern: /\/\*\s*capa\s*\*\/\s*`((?:[^`\\]|\\[\s\S])*)`/g, literal: true },
+    { pattern: /\bgql\s*`((?:[^`\\]|\\[\s\S])*)`/g, literal: false },
+    { pattern: /`(\s*#graphql\b(?:[^`\\]|\\[\s\S])*)`/g, literal: true },
+];
+/** A template's text at run time, from its source text: line ends as LF, escapes applied. */
+function cookTemplate(raw) {
+    const simple = { n: "\n", t: "\t", r: "\r", b: "\b", f: "\f", v: "\v", "0": "\0" };
+    return raw
+        .replace(/\r\n?/g, "\n")
+        .replace(/\\(u\{[0-9a-fA-F]+\}|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|\n|[\s\S])/g, (_, escape) => {
+        if (escape === "\n")
+            return "";
+        if (escape.length > 1)
+            return String.fromCodePoint(parseInt(escape.replace(/^[ux]\{?|\}$/g, ""), 16));
+        return simple[escape] ?? escape;
+    });
+}
+/** Whether the match at `at` sits on a comment line (// or a JSDoc *): an example, not code. */
+function onCommentLine(text, at) {
+    return /^\s*(\/\/|\/?\*)/.test(text.slice(text.lastIndexOf("\n", at - 1) + 1, at));
+}
+/**
+ * The GraphQL documents in one file: the whole file for `.graphql` and `.gql`,
+ * and elsewhere every template that is marked as one: a `#graphql` first
+ * line, a `/* capa *\/` comment before it, or `gql` as a tag or a function.
+ * One on a comment line is an example, not a document.
+ *
+ * `skipped` names every template codegen will not read that looks meant for
+ * it, with the reason: one with `${}` inside (its text is only known at run
+ * time, so it cannot be validated or hashed ahead of it), a named operation
+ * left unmarked, and `/nextjs`'s `graphql` used as a tag.
+ */
+function extractDocuments(file, text) {
+    if (/\.(graphql|gql)$/i.test(file)) {
+        return { documents: text.trim() ? [{ file, line: 1, text }] : [], skipped: [] };
+    }
+    const lineAt = (offset) => text.slice(0, offset).split("\n").length;
+    const found = new Map();
+    for (const { pattern, literal } of TEMPLATES) {
+        for (const match of text.matchAll(pattern)) {
+            const at = match.index ?? 0;
+            if (onCommentLine(text, at))
+                continue;
+            const start = at + match[0].indexOf("`") + 1;
+            if (!found.has(start))
+                found.set(start, { raw: match[1], literal, end: at + match[0].length, at });
+        }
+    }
+    const documents = [];
+    const skipped = [];
+    for (const [start, { raw, literal, end, at }] of [...found].sort(([a], [b]) => a - b)) {
+        const source = { file, line: lineAt(start), text: cookTemplate(raw) };
+        if (literal) {
+            source.literal = true;
+            const name = ASSIGNED_TO.exec(text.slice(Math.max(0, at - 200), at))?.[1];
+            if (name)
+                source.name = name;
+        }
+        if (!/(^|[^\\])\$\{/.test(raw)) {
+            documents.push(source);
+            continue;
+        }
+        // A literal whose every ${} names a variable may be another literal of the
+        // project, a fragment most often: generateGraphQLModule resolves it.
+        const parts = raw.split(NAMED_INTERPOLATION);
+        const segments = parts.filter((_, i) => i % 2 === 0);
+        if (!literal || segments.some((segment) => /(^|[^\\])\$\{/.test(segment))) {
+            skipped.push({ ...source, reason: INTERPOLATED });
+            continue;
+        }
+        source.template = {
+            segments: segments.map(cookTemplate),
+            names: parts.filter((_, i) => i % 2 === 1),
+            asConst: /^\s*as\s+const\b/.test(text.slice(end)),
+        };
+        documents.push(source);
+    }
+    for (const match of text.matchAll(ANY_TEMPLATE)) {
+        const at = match.index ?? 0;
+        if (found.has(at + 1) || onCommentLine(text, at) || !LOOKS_LIKE_GRAPHQL.test(match[1]))
+            continue;
+        const tag = /\bgraphql\s*$/.test(text.slice(Math.max(0, at - 20), at));
+        skipped.push({ file, line: lineAt(at + 1), text: cookTemplate(match[1]), reason: tag ? FETCH_TAG : UNMARKED });
+    }
+    skipped.sort((a, b) => a.line - b.line);
+    return { documents, skipped };
+}
+// ------------------------------------------------------------- schema types ---
+const SCALARS = {
+    ID: "string",
+    String: "string",
+    Int: "number",
+    Float: "number",
+    Boolean: "boolean",
+    DateTime: "string",
+    JSON: "unknown",
+};
+function tsNamed(g, type) {
+    if (g.isScalarType(type))
+        return SCALARS[type.name] ?? "unknown";
+    return type.name;
+}
+/** An output or input type as TS, `null` included where GraphQL allows it. */
+function tsType(g, type, inner) {
+    const print = (t, nullable) => {
+        if (g.isNonNullType(t))
+            return print(t.ofType, false);
+        const body = g.isListType(t) ? `Array<${print(t.ofType, true)}>` : (inner ?? ((n) => tsNamed(g, n)))(t);
+        return nullable ? `${body} | null` : body;
+    };
+    return print(type, true);
+}
+/**
+ * A JSDoc block: the description, then `@deprecated <reason>` for a field a
+ * later Capa-Version phases out, which editors strike through at every use.
+ */
+function docComment(description, indent = "", deprecationReason) {
+    const lines = [...(description ? description.split("\n") : []), ...(deprecationReason != null ? [`@deprecated ${deprecationReason}`] : [])];
+    if (lines.length === 0)
+        return [];
+    const safe = (line) => line.replace(/\*\//g, "* /");
+    if (lines.length === 1)
+        return [`${indent}/** ${safe(lines[0])} */`];
+    return [`${indent}/**`, ...lines.map((l) => `${indent} * ${safe(l)}`), `${indent} */`];
+}
+/** An enum's description, with a line per deprecated value: a union member carries no JSDoc of its own. */
+function enumDescription(type) {
+    const deprecated = type.getValues().filter((v) => v.deprecationReason != null);
+    const lines = [type.description ?? "", ...deprecated.map((v) => `${v.name} is deprecated: ${v.deprecationReason}`)].filter(Boolean);
+    return lines.length ? lines.join("\n") : null;
+}
+/** `/** @deprecated <reason> *\/ ` before a deprecated argument written inline, else nothing. */
+function inlineDeprecation(reason) {
+    return reason != null ? `/** @deprecated ${reason.replace(/\*\//g, "* /")} */ ` : "";
+}
+function argsType(g, args) {
+    const parts = args.map((arg) => {
+        const optional = !g.isNonNullType(arg.type) || arg.defaultValue !== undefined;
+        return `${inlineDeprecation(arg.deprecationReason)}${arg.name}${optional ? "?" : ""}: ${tsType(g, arg.type)}`;
+    });
+    return `{ ${parts.join("; ")} }`;
+}
+/**
+ * A model type's `TreeLayout`, from the N9 descriptions the API writes: each
+ * customer field's namespace, and the relations typed as ids. Null for any
+ * other object type.
+ */
+function treeLayoutMember(g, type) {
+    if (!(0, summary_1.modelNamespaceOf)(type.description))
+        return null;
+    const namespaces = [];
+    const ids = [];
+    for (const field of Object.values(type.getFields())) {
+        const parsed = (0, summary_1.parseFieldDescription)(field.description);
+        if (!parsed)
+            continue;
+        namespaces.push(`      ${field.name}: ${JSON.stringify(parsed.namespace)};`);
+        if (g.getNamedType(field.type).name === "ID")
+            ids.push(JSON.stringify(field.name));
+    }
+    return [
+        "  /** How toTree lays these entries out in REST's shape: each field's namespace, and the relations typed as ids. Not a field. */",
+        "  readonly [treeLayout]?: {",
+        ...(namespaces.length ? ["    fields: {", ...namespaces, "    };"] : ["    fields: {};"]),
+        `    ids: ${ids.length ? ids.join(" | ") : "never"};`,
+        "  };",
+    ];
+}
+/** `capaTreeLayout` as TypeScript: one line per model's root fields, one per field it lays out. */
+function treeLayoutConstant(layout) {
+    const text = (value) => (value === null ? "null" : JSON.stringify(value));
+    const out = [
+        "/** What toTree reads of this schema: toTree(data, selection, capaTreeLayout) reads no schema from the API. */",
+        "export const capaTreeLayout: CapaTreeLayout<CapaQuery> = {",
+        "  models: [",
+    ];
+    for (const model of layout.models) {
+        out.push(`    {`, `      namespace: ${text(model.namespace)},`, `      listField: ${text(model.listField)},`, `      singleField: ${text(model.singleField)},`);
+        if (model.fields.length === 0)
+            out.push("      fields: [],");
+        else {
+            out.push("      fields: [");
+            for (const field of model.fields) {
+                out.push(`        { name: ${text(field.name)}, namespace: ${text(field.namespace)}, kind: ${text(field.kind)}, target: ${text(field.target)} },`);
+            }
+            out.push("      ],");
+        }
+        out.push("    },");
+    }
+    out.push("  ],", "};", "");
+    return out;
+}
+function schemaTypes(g, schema) {
+    const out = [];
+    const names = Object.keys(schema.getTypeMap())
+        .filter((name) => !name.startsWith("__") && !(name in SCALARS))
+        .sort();
+    for (const name of names) {
+        const type = schema.getType(name);
+        if (g.isEnumType(type)) {
+            out.push(...docComment(enumDescription(type)));
+            out.push(`export type ${name} = ${type.getValues().map((v) => JSON.stringify(v.name)).join(" | ")};`, "");
+        }
+        else if (g.isObjectType(type) || g.isInterfaceType(type)) {
+            out.push(...docComment(type.description), `export interface ${name} {`);
+            for (const field of Object.values(type.getFields())) {
+                out.push(...docComment(field.description, "  ", field.deprecationReason));
+                const returns = tsType(g, field.type);
+                out.push(field.args.length
+                    ? `  ${field.name}: CapaField<${returns}, ${argsType(g, field.args)}>;`
+                    : `  ${field.name}: ${returns};`);
+            }
+            if (g.isObjectType(type))
+                out.push(...(treeLayoutMember(g, type) ?? []));
+            out.push("}", "");
+        }
+        else if (g.isInputObjectType(type)) {
+            out.push(...docComment(type.description), `export interface ${name} {`);
+            for (const field of Object.values(type.getFields())) {
+                const optional = !g.isNonNullType(field.type) || field.defaultValue !== undefined;
+                out.push(...docComment(null, "  ", field.deprecationReason));
+                out.push(`  ${field.name}${optional ? "?" : ""}: ${tsType(g, field.type)};`);
+            }
+            out.push("}", "");
+        }
+        else if (g.isUnionType(type)) {
+            out.push(`export type ${name} = ${type.getTypes().map((t) => t.name).join(" | ")};`, "");
+        }
+    }
+    return out;
+}
+/** Fields selected on `parent`, fragments folded in; fields under another type condition are optional. */
+function collect(g, schema, parent, selections, fragments, optional, into) {
+    for (const selection of selections) {
+        if (selection.kind === g.Kind.FIELD) {
+            const key = selection.alias?.value ?? selection.name.value;
+            const fields = g.isUnionType(parent) ? {} : parent.getFields();
+            const existing = into.get(key);
+            if (existing) {
+                existing.nodes.push(selection);
+                existing.optional = existing.optional && optional;
+            }
+            else {
+                into.set(key, { key, field: fields[selection.name.value] ?? null, nodes: [selection], optional });
+            }
+            continue;
+        }
+        const fragment = selection.kind === g.Kind.FRAGMENT_SPREAD ? fragments.get(selection.name.value) : selection;
+        if (!fragment)
+            continue;
+        const condition = fragment.typeCondition?.name.value;
+        const narrowed = condition ? schema.getType(condition) : parent;
+        const scope = narrowed && (g.isObjectType(narrowed) || g.isInterfaceType(narrowed) || g.isUnionType(narrowed)) ? narrowed : parent;
+        collect(g, schema, scope, fragment.selectionSet.selections, fragments, optional || scope.name !== parent.name, into);
+    }
+}
+function resultType(g, schema, parent, selections, fragments, indent) {
+    const collected = new Map();
+    collect(g, schema, parent, selections, fragments, false, collected);
+    const lines = ["{"];
+    for (const entry of collected.values()) {
+        const name = entry.nodes[0].name.value;
+        let type;
+        if (name === "__typename") {
+            type = g.isObjectType(parent) ? JSON.stringify(parent.name) : "string";
+        }
+        else if (!entry.field) {
+            type = "unknown";
+        }
+        else {
+            const children = entry.nodes.flatMap((node) => node.selectionSet?.selections ?? []);
+            type = tsType(g, entry.field.type, (named) => g.isObjectType(named) || g.isInterfaceType(named) || g.isUnionType(named)
+                ? resultType(g, schema, named, children, fragments, `${indent}  `)
+                : tsNamed(g, named));
+        }
+        lines.push(...docComment(null, `${indent}  `, entry.field?.deprecationReason));
+        lines.push(`${indent}  ${entry.key}${entry.optional ? "?" : ""}: ${type};`);
+    }
+    lines.push(`${indent}}`);
+    return lines.join("\n");
+}
+function variablesType(g, schema, operation) {
+    const parts = (operation.variableDefinitions ?? []).map((definition) => {
+        const type = g.typeFromAST(schema, definition.type);
+        const optional = definition.type.kind !== g.Kind.NON_NULL_TYPE || definition.defaultValue !== undefined;
+        return `  ${definition.variable.name.value}${optional ? "?" : ""}: ${type ? tsType(g, type) : "unknown"};`;
+    });
+    return parts.length ? `{\n${parts.join("\n")}\n}` : "Record<string, never>";
+}
+/** Every fragment an operation reaches, transitively, in first-use order. */
+function usedFragments(g, node, fragments, seen = new Set()) {
+    const out = [];
+    g.visit(node, {
+        FragmentSpread(spread) {
+            const name = spread.name.value;
+            const fragment = fragments.get(name);
+            if (!fragment || seen.has(name))
+                return;
+            seen.add(name);
+            out.push(fragment, ...usedFragments(g, fragment, fragments, seen));
+        },
+    });
+    return out;
+}
+/**
+ * The namespaces of the models an operation reads, in the order it first
+ * reaches them: each model whose entries it selects (every model for
+ * `entry(id:)`, which reads an entry of any), and each model a filter or sort
+ * reaches through a relation (`author: { name: ... }`, `author__name_ASC`),
+ * since a publish there changes which entries match or their order. A filter
+ * or sort passed as a variable is known only at run time, so every model its
+ * type can reach counts. These are the models whose publish must revalidate
+ * a cached read of it: `tagsFor({ namespace: <Name>Models })`.
+ */
+function modelsRead(g, schema, summary, document) {
+    const byType = new Map(summary.models.map((model) => [model.typeName, model]));
+    const bySort = new Map(summary.models.map((model) => [model.sortType, model]));
+    /** Whether a relation's filter input takes hop fields (`name: StringFilter`) beside its operators. */
+    const hasHops = (input) => g.isInputObjectType(input) && Object.values(input.getFields()).some((field) => g.isInputObjectType(g.getNamedType(field.type)));
+    /** A relation's filter input (`AuthorsRelationFilter`), to the model its hop fields read. */
+    const hopTargets = new Map();
+    /** A model's filter input (`ArticlesFilter`), to every model its hops can read. */
+    const filterReach = new Map();
+    for (const model of summary.models) {
+        const filter = schema.getType(model.filterType);
+        if (!g.isInputObjectType(filter))
+            continue;
+        const reach = [];
+        for (const field of model.fields) {
+            const input = field.target ? filter.getFields()[field.name] : undefined;
+            const relationFilter = input ? g.getNamedType(input.type) : undefined;
+            if (!field.target || !relationFilter || !hasHops(relationFilter))
+                continue;
+            hopTargets.set(relationFilter.name, field.target);
+            reach.push(field.target);
+        }
+        filterReach.set(model.filterType, reach);
+    }
+    /** The model a sort value reads through a relation (`author__name_ASC`), or null for the model's own field. */
+    const sortTarget = (model, value) => {
+        const hop = /^(.+?)__.+_(?:ASC|DESC)$/.exec(value);
+        return hop ? (model.fields.find((field) => field.name === hop[1])?.target ?? null) : null;
+    };
+    const read = [];
+    const add = (namespace) => {
+        if (namespace && !read.includes(namespace))
+            read.push(namespace);
+    };
+    const addEntries = (type) => {
+        const types = g.isAbstractType(type) ? schema.getPossibleTypes(type) : [type];
+        for (const each of types)
+            add(byType.get(each.name)?.namespace);
+        // A connection read for its count or page alone still reads its model.
+        if (g.isObjectType(type) && type.getFields().nodes)
+            addEntries(g.getNamedType(type.getFields().nodes.type));
+    };
+    const typeInfo = new g.TypeInfo(schema);
+    g.visit(document, g.visitWithTypeInfo(typeInfo, {
+        // Every variable is used in an argument, where its type is read below,
+        // after the field it filters, so the root model comes first.
+        VariableDefinition: () => false,
+        Field() {
+            const type = typeInfo.getType();
+            if (type)
+                addEntries(g.getNamedType(type));
+        },
+        ObjectField() {
+            const parent = typeInfo.getParentInputType();
+            const input = typeInfo.getInputType();
+            if (!parent || !input)
+                return;
+            const target = hopTargets.get(g.getNamedType(parent).name);
+            if (target && g.isInputObjectType(g.getNamedType(input)))
+                add(target);
+        },
+        EnumValue(node) {
+            const input = typeInfo.getInputType();
+            const model = input ? bySort.get(g.getNamedType(input).name) : undefined;
+            if (model)
+                add(sortTarget(model, node.value));
+        },
+        Variable() {
+            const input = typeInfo.getInputType();
+            if (!input)
+                return;
+            const name = g.getNamedType(input).name;
+            for (const target of filterReach.get(name) ?? [])
+                add(target);
+            add(hopTargets.get(name));
+            const sorted = bySort.get(name);
+            if (sorted)
+                for (const value of sorted.sortValues)
+                    add(sortTarget(sorted, value));
+        },
+    }));
+    return read;
+}
+function pascal(name) {
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+/**
+ * Each literal's `${NAME}`s filled in with the text of the literal assigned to
+ * NAME, as the program fills them in when it runs: the one in the same file
+ * when there is one, else the one literal of that name in the project. A name
+ * no literal takes leaves the template to run time (skipped, with the name); a
+ * name two files take, a cycle, and a template without `as const` (whose
+ * text TypeScript then forgets) are problems, each with its fix.
+ */
+function resolveTemplates(sources) {
+    const byName = new Map();
+    for (const source of sources) {
+        if (source.literal && source.name)
+            byName.set(source.name, [...(byName.get(source.name) ?? []), source]);
+    }
+    const done = new Map();
+    const resolve = (source, path) => {
+        const known = done.get(source);
+        if (known)
+            return known;
+        if (!source.template)
+            return { text: source.text };
+        if (path.includes(source))
+            return { problem: `${source.name ?? "This template"} spreads itself through \${}, so its text never ends.` };
+        const { segments, names, asConst } = source.template;
+        let text = segments[0];
+        let outcome = null;
+        for (const [i, name] of names.entries()) {
+            const all = byName.get(name) ?? [];
+            const here = all.filter((candidate) => candidate.file === source.file);
+            const candidates = here.length ? here : all;
+            if (candidates.length === 0) {
+                outcome = { skip: unknownInterpolation(name) };
+                break;
+            }
+            if (candidates.length > 1) {
+                const where = candidates.map((c) => `${c.file}:${c.line}`).join(", ");
+                outcome = { problem: `\${${name}} names ${candidates.length} literals (${where}): rename one, so this template spreads the one it means.` };
+                break;
+            }
+            const inner = resolve(candidates[0], [...path, source]);
+            if (!("text" in inner)) {
+                outcome = inner;
+                break;
+            }
+            text += inner.text + segments[i + 1];
+        }
+        const result = outcome ?? (asConst ? { text } : { problem: NEEDS_AS_CONST });
+        done.set(source, result);
+        return result;
+    };
+    for (const source of sources)
+        done.set(source, resolve(source, []));
+    return done;
+}
+/** Whether `node` sits inside one of `definitions`, by its place in the same text. */
+function insideAny(node, definitions) {
+    return definitions.some((d) => d.loc && node.loc && d.loc.source === node.loc.source && node.loc.start >= d.loc.start && node.loc.end <= d.loc.end);
+}
+/**
+ * The generated module for a schema and a project's documents. Problems (a
+ * syntax error, a field the key cannot read, an unnamed operation, a name used
+ * twice) are returned with their file and line, and no module is produced
+ * while any remain.
+ */
+function generateGraphQLModule(introspection, sources) {
+    const g = loadGraphQL();
+    const schema = g.buildClientSchema(introspection);
+    const summary = (0, summary_1.summarizeIntrospection)(introspection);
+    const problems = [];
+    const at = (source, message, location) => ({
+        file: source.file,
+        line: source.line + (location ? location.line - 1 : 0),
+        column: location?.column ?? 1,
+        message,
+    });
+    const problem = (source, message, location) => problems.push(at(source, message, location));
+    const warnings = new Map();
+    /** Every use of a deprecated field, argument, input field or enum value in `document`, once each. */
+    const warnDeprecated = (source, document) => {
+        for (const use of g.validate(schema, document, [g.NoDeprecatedCustomRule])) {
+            const location = use.locations?.[0];
+            const warning = at(source, use.message, location && use.source?.body === source.text ? location : undefined);
+            warnings.set(`${warning.file}:${warning.line}:${warning.column}:${warning.message}`, warning);
+        }
+    };
+    const skipped = [];
+    const readable = [];
+    const resolved = resolveTemplates(sources);
+    for (const source of sources) {
+        const outcome = resolved.get(source);
+        if ("skip" in outcome)
+            skipped.push({ file: source.file, line: source.line, text: source.text, literal: true, reason: outcome.skip });
+        else if ("problem" in outcome)
+            problem(source, outcome.problem);
+        else
+            readable.push(outcome.text === source.text ? source : { ...source, text: outcome.text, template: undefined });
+    }
+    const parsed = [];
+    const fragments = new Map();
+    const fragmentSources = new Map();
+    const lineOf = (source, node) => node.loc ? source.line + g.getLocation(node.loc.source, node.loc.start).line - 1 : source.line;
+    for (const source of readable) {
+        let document;
+        try {
+            document = g.parse(source.text);
+        }
+        catch (error) {
+            const located = error;
+            problem(source, located.message, located.locations?.[0]);
+            continue;
+        }
+        parsed.push({ source, document });
+        for (const definition of document.definitions) {
+            if (definition.kind !== g.Kind.FRAGMENT_DEFINITION)
+                continue;
+            const name = definition.name.value;
+            const first = fragments.get(name);
+            if (!first) {
+                fragments.set(name, definition);
+                fragmentSources.set(name, source);
+            }
+            else if (g.print(first) !== g.print(definition)) {
+                // The same fragment spread into several literals with ${} is one fragment; two texts under one name are not.
+                const also = fragmentSources.get(name);
+                problem(source, `Fragment ${name} is defined twice, differently (also ${also.file}:${lineOf(also, first)}). Fragment names must be unique across the project.`, definition.loc ? g.getLocation(definition.loc.source, definition.loc.start) : undefined);
+            }
+        }
+    }
+    // Every fragment is checked on its own and typed, so a component can take
+    // its data as props (`ArticleCardFragment`) wherever the fragment is spread.
+    const standaloneRules = g.specifiedRules.filter((rule) => rule !== g.NoUnusedFragmentsRule);
+    const invalidFragments = [];
+    const fragmentBlocks = [];
+    for (const [name, definition] of fragments) {
+        const source = fragmentSources.get(name);
+        const alone = { kind: g.Kind.DOCUMENT, definitions: [definition, ...usedFragments(g, definition, fragments)] };
+        const errors = g.validate(schema, alone, standaloneRules);
+        if (errors.length) {
+            invalidFragments.push(definition);
+            for (const error of errors) {
+                const location = error.locations?.[0];
+                problem(source, error.message, location && error.source?.body === source.text ? location : undefined);
+            }
+            continue;
+        }
+        const condition = schema.getType(definition.typeCondition.name.value);
+        if (!condition || !(g.isObjectType(condition) || g.isInterfaceType(condition) || g.isUnionType(condition)))
+            continue;
+        fragmentBlocks.push(`export type ${pascal(name)}Fragment = ${resultType(g, schema, condition, definition.selectionSet.selections, fragments, "")};`, "");
+    }
+    /** An error in a fragment already reported on its own is not reported again for each operation that spreads it. */
+    const reportedInFragment = (error) => invalidFragments.length > 0 && (error.nodes?.length ?? 0) > 0 && error.nodes.every((node) => insideAny(node, invalidFragments));
+    const operations = [];
+    const blocks = [];
+    const recorded = [];
+    const names = new Set();
+    const hash = (text) => (0, sha256_1.sha256Pure)(new TextEncoder().encode(text));
+    for (const { source, document } of parsed) {
+        // A literal is sent exactly as written and typed by its whole text, so it
+        // holds one operation and everything that operation needs, and is checked
+        // whole, as the API will check it.
+        if (source.literal) {
+            const count = document.definitions.filter((d) => d.kind === g.Kind.OPERATION_DEFINITION).length;
+            // A literal of fragments only is a fragment source for other literals' ${}: checked and typed above.
+            if (count === 0 && document.definitions.length > 0)
+                continue;
+            if (count !== 1) {
+                problem(source, `A #graphql, /* capa */ or gql() literal holds exactly one operation, since its text is what types it; this one holds ${count}.`);
+                continue;
+            }
+            const errors = g.validate(schema, document).filter((error) => !reportedInFragment(error));
+            if (errors.length) {
+                for (const error of errors) {
+                    const unknownFragment = /^Unknown fragment "/.test(error.message);
+                    problem(source, unknownFragment
+                        ? `${error.message} A literal is sent as written, so define the fragment inside it or spread a fragment literal into it with \${NAME}, or use the <Name>Document codegen writes.`
+                        : error.message, error.locations?.[0]);
+                }
+                continue;
+            }
+        }
+        for (const definition of document.definitions) {
+            if (definition.kind !== g.Kind.OPERATION_DEFINITION)
+                continue;
+            const name = definition.name?.value;
+            if (!name) {
+                problem(source, "Name every operation (query ArticlesPage { ... }): the name is what codegen exports.", definition.loc ? g.getLocation(definition.loc.source, definition.loc.start) : undefined);
+                continue;
+            }
+            if (names.has(name)) {
+                problem(source, `Operation name ${name} is used twice. Operation names must be unique across the project.`);
+                continue;
+            }
+            names.add(name);
+            const standalone = {
+                kind: g.Kind.DOCUMENT,
+                definitions: [definition, ...usedFragments(g, definition, fragments)],
+            };
+            const errors = g.validate(schema, standalone).filter((error) => !reportedInFragment(error));
+            if (errors.length) {
+                for (const error of errors) {
+                    const at = error.locations?.[0];
+                    problem(source, error.message, at && error.source?.body === source.text ? at : undefined);
+                }
+                continue;
+            }
+            if (invalidFragments.some((fragment) => standalone.definitions.includes(fragment)))
+                continue;
+            warnDeprecated(source, standalone);
+            const text = standalone.definitions.map((d) => g.print(d)).join("\n\n");
+            const root = definition.operation === "query" ? schema.getQueryType() : null;
+            if (!root) {
+                problem(source, `${name} is a ${definition.operation}; Capa's GraphQL API serves queries only.`);
+                continue;
+            }
+            const typeName = `${pascal(name)}Query`;
+            const models = modelsRead(g, schema, summary, standalone);
+            blocks.push(`export type ${typeName} = ${resultType(g, schema, root, definition.selectionSet.selections, fragments, "")};`, "", `export type ${typeName}Variables = ${variablesType(g, schema, definition)};`, "", `export const ${pascal(name)}Document = ${JSON.stringify(text)} as TypedDocument<${typeName}, ${typeName}Variables>;`, "", `/** The models ${name} reads, for its cache tags: tagsFor({ namespace: ${pascal(name)}Models }). */`, `export const ${pascal(name)}Models = ${JSON.stringify(models).replace(/","/g, '", "')} as const;`, "");
+            const operation = { name, document: text, sha256: hash(text), models };
+            if (source.literal) {
+                operation.literal = { document: source.text, sha256: hash(source.text) };
+                recorded.push(`    ${JSON.stringify(source.text)}: { result: ${typeName}; variables: ${typeName}Variables };`);
+            }
+            operations.push(operation);
+        }
+    }
+    const deprecatedUses = [...warnings.values()];
+    const unique = [...new Map(problems.map((p) => [`${p.file}:${p.line}:${p.column}:${p.message}`, p])).values()];
+    if (unique.length)
+        return { source: null, operations, problems: unique, warnings: deprecatedUses, skipped };
+    const sdl = g.printSchema(schema);
+    const header = [
+        "// Generated by capa-codegen --graphql. Do not edit by hand.",
+        `// Schema: version ${introspection.version ?? "unknown"}, sha256 ${(0, sha256_1.sha256Pure)(new TextEncoder().encode(sdl)).slice(0, 16)}.`,
+        "// Re-run it after a model changes in Capa or a document changes here.",
+        'import type { CapaField, CapaTreeLayout, treeLayout, TypedDocument } from "@capacms/sdk/next";',
+        "",
+    ];
+    const query = schema.getQueryType()?.name ?? "Query";
+    const body = [
+        ...schemaTypes(g, schema),
+        "/** Pass to createClient<CapaQuery>() to type client.graphql.query(). */",
+        `export type CapaQuery = ${query};`,
+        "",
+        ...treeLayoutConstant((0, tree_layout_1.treeLayoutOf)(summary)),
+        ...fragmentBlocks,
+        ...blocks,
+        ...(recorded.length
+            ? [
+                'declare module "@capacms/sdk/next" {',
+                "  /** The documents written as literals in this project, by their exact text: client.graphql(text) is typed from here. */",
+                "  interface CapaDocuments {",
+                ...recorded,
+                "  }",
+                "}",
+                "",
+            ]
+            : []),
+    ];
+    return { source: [...header, ...body].join("\n").trimEnd() + "\n", operations, problems: unique, warnings: deprecatedUses, skipped };
+}