ghostrail 0.17.0 → 0.18.0

package/scripts/linear-schema-snapshot.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * Refresh `test/fixtures/linear-schema.graphql`, the schema slice that
+ * `test/source/linear-schema.test.ts` validates our documents against.
+ *
+ * Run it when you add or change a Linear document:
+ *
+ *   LINEAR_API_KEY=lin_api_... node scripts/linear-schema-snapshot.mjs
+ *
+ * It introspects the live API, checks every document in `LINEAR_DOCUMENTS`
+ * against the real schema, and only then writes the snapshot. So an invalid
+ * document fails here, against Linear, rather than being frozen into the
+ * fixture and passing forever after.
+ *
+ * The snapshot is pruned to the fields our documents actually select, because
+ * Linear's full schema is 1.3MB of introspection and 1154 types. Pruning means
+ * a newly selected field fails the offline test until you re-run this, which is
+ * the point: the new field gets checked against Linear once, here.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  TypeInfo,
+  buildClientSchema,
+  getIntrospectionQuery,
+  getNamedType,
+  isEnumType,
+  isInputObjectType,
+  isInterfaceType,
+  isObjectType,
+  isScalarType,
+  isUnionType,
+  parse,
+  validate,
+  visit,
+  visitWithTypeInfo,
+} from "graphql";
+
+import { LINEAR_DOCUMENTS } from "../dist/source/linear.js";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const OUT = join(ROOT, "test", "fixtures", "linear-schema.graphql");
+const ENDPOINT = process.env.LINEAR_ENDPOINT ?? "https://api.linear.app/graphql";
+
+const BUILT_IN_SCALARS = new Set(["String", "Int", "Float", "Boolean", "ID"]);
+
+function die(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+async function introspect(apiKey) {
+  const response = await fetch(ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: apiKey },
+    body: JSON.stringify({ query: getIntrospectionQuery({ inputValueDeprecation: false }) }),
+  });
+  if (!response.ok) {
+    die(`introspection failed: HTTP ${response.status}: ${(await response.text()).slice(0, 500)}`);
+  }
+  const body = await response.json();
+  if (body.errors) die(`introspection failed: ${JSON.stringify(body.errors)}`);
+  return buildClientSchema(body.data);
+}
+
+/**
+ * Walk every document and collect what the snapshot has to define: the output
+ * fields actually selected (keyed `Type.field`), and every named type touched
+ * along the way, including the input types behind variables and arguments.
+ */
+function collectUsage(schema, documents) {
+  const usedFields = new Set();
+  const usedTypes = new Set();
+
+  const addType = (type) => {
+    const named = getNamedType(type);
+    if (!named || usedTypes.has(named.name)) return;
+    usedTypes.add(named.name);
+    // Input types are printed whole (an argument can reference any of their
+    // fields), so their own field types have to come along.
+    if (isInputObjectType(named)) {
+      for (const field of Object.values(named.getFields())) addType(field.type);
+    }
+  };
+
+  for (const [name, source] of Object.entries(documents)) {
+    const doc = parse(source);
+    const typeInfo = new TypeInfo(schema);
+    visit(
+      doc,
+      visitWithTypeInfo(typeInfo, {
+        Field() {
+          const parent = typeInfo.getParentType();
+          const field = typeInfo.getFieldDef();
+          if (!parent || !field) die(`${name}: could not resolve a field against the schema`);
+          usedFields.add(`${parent.name}.${field.name}`);
+          addType(parent);
+          addType(field.type);
+          // Every argument the field declares, not only the ones we pass: the
+          // snapshot has to be able to reject an argument we wrongly add later.
+          for (const arg of field.args) addType(arg.type);
+        },
+        VariableDefinition() {
+          addType(typeInfo.getInputType());
+        },
+      }),
+    );
+  }
+  return { usedFields, usedTypes };
+}
+
+/** Print one type, keeping only the selected fields for object-ish types. */
+function printPrunedType(type, usedFields) {
+  const describe = (field) => {
+    const args = field.args ?? [];
+    const argText =
+      args.length === 0 ? "" : `(${args.map((a) => `${a.name}: ${a.type}`).join(", ")})`;
+    return `  ${field.name}${argText}: ${field.type}`;
+  };
+
+  if (isScalarType(type)) {
+    return BUILT_IN_SCALARS.has(type.name) ? "" : `scalar ${type.name}`;
+  }
+  if (isEnumType(type)) {
+    const values = type.getValues().map((v) => `  ${v.name}`);
+    return `enum ${type.name} {\n${values.join("\n")}\n}`;
+  }
+  if (isUnionType(type)) {
+    return `union ${type.name} = ${type
+      .getTypes()
+      .map((t) => t.name)
+      .join(" | ")}`;
+  }
+  if (isInputObjectType(type)) {
+    const fields = Object.values(type.getFields()).map((f) => `  ${f.name}: ${f.type}`);
+    return `input ${type.name} {\n${fields.join("\n")}\n}`;
+  }
+  if (isObjectType(type) || isInterfaceType(type)) {
+    const kept = Object.values(type.getFields()).filter((f) =>
+      usedFields.has(`${type.name}.${f.name}`),
+    );
+    if (kept.length === 0) return "";
+    const keyword = isObjectType(type) ? "type" : "interface";
+    return `${keyword} ${type.name} {\n${kept.map(describe).join("\n")}\n}`;
+  }
+  return "";
+}
+
+async function main() {
+  const apiKey = process.env.LINEAR_API_KEY;
+  if (!apiKey) die("LINEAR_API_KEY is not set; this script talks to the real Linear API");
+
+  const schema = await introspect(apiKey);
+
+  // Check first, write second. A document that Linear rejects must not be able
+  // to bake itself into the fixture and look correct from then on.
+  let invalid = false;
+  for (const [name, source] of Object.entries(LINEAR_DOCUMENTS)) {
+    const errors = validate(schema, parse(source));
+    if (errors.length > 0) {
+      invalid = true;
+      console.error(`${name} is not valid against Linear's schema:`);
+      for (const error of errors) console.error(`  ${error.message}`);
+    }
+  }
+  if (invalid) die("\nrefusing to write a snapshot for documents Linear would reject");
+
+  const { usedFields, usedTypes } = collectUsage(schema, LINEAR_DOCUMENTS);
+  const blocks = [...usedTypes]
+    .sort()
+    .map((name) => printPrunedType(schema.getType(name), usedFields))
+    .filter((block) => block.length > 0);
+
+  const roots = [
+    "schema {",
+    `  query: ${schema.getQueryType().name}`,
+    ...(schema.getMutationType() ? [`  mutation: ${schema.getMutationType().name}`] : []),
+    "}",
+  ].join("\n");
+
+  const header = [
+    "# Generated by scripts/linear-schema-snapshot.mjs. Do not hand-edit.",
+    "#",
+    "# A slice of Linear's schema: the fields our documents select, plus the",
+    "# input types they pass. Regenerate with:",
+    "#",
+    "#   pnpm build && LINEAR_API_KEY=... node scripts/linear-schema-snapshot.mjs",
+    "",
+  ].join("\n");
+
+  mkdirSync(dirname(OUT), { recursive: true });
+  writeFileSync(OUT, `${header}${roots}\n\n${blocks.join("\n\n")}\n`);
+  console.log(
+    `wrote ${OUT}: ${blocks.length} types, ${usedFields.size} fields, ` +
+      `${Object.keys(LINEAR_DOCUMENTS).length} documents validated`,
+  );
+}
+
+await main();