@stonecrop/schema 0.16.4 → 0.16.5

package/README.md

@@ -333,11 +333,26 @@ then `--exclude` removes any remaining unwanted names.
 | `--output <dir>`          | `-o`  | Directory to write doctype JSON files (required)         |
 | `--include <types>`       |       | Comma-separated allowlist of type names to generate      |
 | `--exclude <types>`       |       | Comma-separated list of type names to skip               |
-| `--overrides <file>`      |       | JSON file with per-type, per-field overrides             |
+| `--names <file>`          |       | JSON file mapping GraphQL type name to doctype name      |
 | `--custom-scalars <file>` |       | JSON file mapping custom scalar names to field templates |
 | `--include-unmapped`      |       | Retain `_graphqlType` metadata on fields with no mapping |
+| `--check`                 |       | Report drift and exit non-zero if anything would change  |
 | `--help`                  | `-h`  | Show help                                                |
 
+### Regeneration is non-destructive
+
+An existing doctype file is the source of truth. Regeneration verifies each field against the
+schema, stamps `"source": "introspected"` on the ones it confirms, and **reports** anything it
+disagrees with rather than overwriting it — so labels, component choices and a hand-declared
+primary key all survive.
+
+That polarity is deliberate. A doctype legitimately declares identity the schema cannot express:
+a natural business key is usually a `UNIQUE` constraint rather than the table's `PRIMARY KEY`, and
+where a table carries several no rule can pick between them. Overwriting identity from the schema
+would silently re-key such a doctype on every run.
+
+Use `--check` in CI to fail the build when a doctype and the schema have diverged.
+
 ### Custom scalars
 
 For servers that use non-standard scalars (e.g. PostGraphile's `BigFloat`, `Datetime`), provide
@@ -355,21 +370,20 @@ stonecrop-schema generate -e http://localhost:3000/graphql -o ./app/doctypes \
   --custom-scalars custom-scalars.json
 ```
 
-### Per-field overrides
+### Doctype name remap
 
-Override the generated field definition for specific types and fields:
+Emit a doctype under a name other than its GraphQL type — for a second view over an existing type,
+say, distinguished only by presentation. The `slug` follows the doctype name, so it addresses both
+the output file and the route. Keep this consistent with the middleware's `tables` option, which
+maps the resulting doctype name to its SQL target.
 
 ```json
-{
-  "SalesOrder": {
-    "totalAmount": { "component": "ANumericInput" }
-  }
-}
+{ "Plan": "Planner" }
 ```
 
 ```bash
 stonecrop-schema generate -e http://localhost:3000/graphql -o ./app/doctypes \
-  --overrides overrides.json
+  --names names.json
 ```
 
 ## Naming Utilities

package/dist/cli.js

@@ -1,31 +1,31 @@
 #!/usr/bin/env node
-import { readFileSync as u, existsSync as S, mkdirSync as w, writeFileSync as x } from "node:fs";
-import { resolve as c, join as O } from "node:path";
-import { parseArgs as $ } from "node:util";
-import { getIntrospectionQuery as N } from "graphql";
-import { c as P, v as j } from "./validation-Dyxjvaio.js";
-async function C(e, m) {
-  const t = await fetch(e, {
+import { readFileSync as c, existsSync as v, mkdirSync as O, writeFileSync as k } from "node:fs";
+import { resolve as d, join as C } from "node:path";
+import { parseArgs as P } from "node:util";
+import { getIntrospectionQuery as j } from "graphql";
+import { c as E, m as J, f as L, v as R } from "./validation-CToUOy0a.js";
+async function q(e, f) {
+  const o = await fetch(e, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
-      ...m
+      ...f
     },
     body: JSON.stringify({
-      query: N()
+      query: j()
     })
   });
-  if (!t.ok)
-    throw new Error(`Failed to fetch introspection: ${t.status} ${t.statusText}`);
-  const i = await t.json();
-  if (i.errors?.length)
-    throw new Error(`GraphQL errors: ${i.errors.map((r) => r.message).join(", ")}`);
-  if (!i.data)
+  if (!o.ok)
+    throw new Error(`Failed to fetch introspection: ${o.status} ${o.statusText}`);
+  const p = await o.json();
+  if (p.errors?.length)
+    throw new Error(`GraphQL errors: ${p.errors.map((i) => i.message).join(", ")}`);
+  if (!p.data)
     throw new Error("No data in introspection response");
-  return i.data;
+  return p.data;
 }
-async function E() {
-  const { values: e, positionals: m } = $({
+async function D() {
+  const { values: e, positionals: f } = P({
     allowPositionals: !0,
     options: {
       endpoint: { type: "string", short: "e" },
@@ -34,59 +34,75 @@ async function E() {
       output: { type: "string", short: "o" },
       include: { type: "string" },
       exclude: { type: "string" },
-      overrides: { type: "string" },
+      names: { type: "string" },
       "custom-scalars": { type: "string" },
       "include-unmapped": { type: "boolean", default: !1 },
+      check: { type: "boolean", default: !1 },
       help: { type: "boolean", short: "h" }
     }
-  }), t = m[0];
-  (e.help || !t) && (q(), process.exit(t ? 0 : 1)), t !== "generate" && (console.error(`Unknown command: ${t}`), console.error("Available commands: generate"), process.exit(1)), [e.endpoint, e.introspection, e.sdl].filter(Boolean).length !== 1 && (console.error("Exactly one of --endpoint, --introspection, or --sdl must be provided"), process.exit(1)), e.output || (console.error("--output <dir> is required"), process.exit(1));
-  const r = c(e.output), a = {
+  }), o = f[0];
+  (e.help || !o) && (F(), process.exit(o ? 0 : 1)), o !== "generate" && (console.error(`Unknown command: ${o}`), console.error("Available commands: generate"), process.exit(1)), [e.endpoint, e.introspection, e.sdl].filter(Boolean).length !== 1 && (console.error("Exactly one of --endpoint, --introspection, or --sdl must be provided"), process.exit(1)), e.output || (console.error("--output <dir> is required"), process.exit(1));
+  const i = d(e.output), a = {
     includeUnmappedMeta: e["include-unmapped"]
   };
-  if (e.include && (a.include = e.include.split(",").map((o) => o.trim())), e.exclude && (a.exclude = e.exclude.split(",").map((o) => o.trim())), e.overrides) {
-    const o = c(e.overrides), s = u(o, "utf-8");
-    a.typeOverrides = JSON.parse(s);
+  if (e.include && (a.include = e.include.split(",").map((t) => t.trim())), e.exclude && (a.exclude = e.exclude.split(",").map((t) => t.trim())), e.names) {
+    const t = d(e.names);
+    a.doctypeNames = JSON.parse(c(t, "utf-8"));
   }
-  if (e["custom-scalars"]) {
-    const o = c(e["custom-scalars"]), s = u(o, "utf-8");
-    a.customScalars = JSON.parse(s);
+  if (a.onWarning = (t) => console.warn(`  WARN: ${t}`), e["custom-scalars"]) {
+    const t = d(e["custom-scalars"]), r = c(t, "utf-8");
+    a.customScalars = JSON.parse(r);
   }
-  let l;
+  let h;
   if (e.endpoint)
-    console.log(`Fetching introspection from ${e.endpoint}...`), l = await C(e.endpoint);
+    console.log(`Fetching introspection from ${e.endpoint}...`), h = await q(e.endpoint);
   else if (e.introspection) {
-    const o = c(e.introspection), s = u(o, "utf-8"), d = JSON.parse(s);
-    l = d.data ?? d;
+    const t = d(e.introspection), r = c(t, "utf-8"), s = JSON.parse(r);
+    h = s.data ?? s;
   } else {
-    const o = c(e.sdl);
-    l = u(o, "utf-8");
+    const t = d(e.sdl);
+    h = c(t, "utf-8");
   }
-  const f = P(l, a);
-  f.length === 0 && (console.warn("No entity types found in the schema. Check your include/exclude filters."), process.exit(0)), S(r) || w(r, { recursive: !0 });
-  let h = 0, p = 0;
-  for (const o of f) {
-    const s = `${o.slug}.json`, d = O(r, s), v = JSON.stringify(o, null, "	");
-    x(d, v + `
-`, "utf-8");
-    const g = j(o);
-    if (g.success) {
-      const n = o.fields.filter((y) => y._unmapped);
-      n.length > 0 && (h++, console.warn(
-        `  WARN: ${s} has ${n.length} unmapped field(s): ${n.map((y) => y.fieldname).join(", ")}`
+  const g = E(h, a);
+  g.length === 0 && (console.warn("No entity types found in the schema. Check your include/exclude filters."), process.exit(0)), v(i) || O(i, { recursive: !0 });
+  let y = 0, m = 0, u = 0;
+  const w = [];
+  for (const t of g) {
+    const r = `${t.slug}.json`, s = C(i, r);
+    let S = t;
+    if (v(s)) {
+      const { doctype: n, drift: l } = J(
+        JSON.parse(c(s, "utf-8")),
+        t
+      );
+      S = n, w.push(...L(l));
+    }
+    const x = JSON.stringify(S, null, "	") + `
+`, $ = v(s) && c(s, "utf-8") === x;
+    $ || u++, !e.check && !$ && k(s, x, "utf-8");
+    const N = R(S);
+    if (N.success) {
+      const n = t.fields.filter((l) => l._unmapped);
+      n.length > 0 && (y++, console.warn(
+        `  WARN: ${r} has ${n.length} unmapped field(s): ${n.map((l) => l.fieldname).join(", ")}`
       ));
     } else {
-      p++, console.error(`  ERROR: ${s} failed validation:`);
-      for (const n of g.errors)
+      m++, console.error(`  ERROR: ${r} failed validation:`);
+      for (const n of N.errors)
         console.error(`    ${n.path.join(".")}: ${n.message}`);
     }
   }
+  if (w.length > 0) {
+    console.log(`
+Drift between the authored doctypes and the schema (reported, not applied):`);
+    for (const t of w) console.log(t);
+  }
   console.log(
     `
-Generated ${f.length} doctype(s) in ${r}` + (h ? ` (${h} with warnings)` : "") + (p ? ` (${p} with errors)` : "")
-  ), p > 0 && process.exit(1);
+${e.check ? "Checked" : "Generated"} ${g.length} doctype(s) in ${i}` + (u ? ` (${u} ${e.check ? "would change" : "written"})` : " (all up to date)") + (y ? ` (${y} with warnings)` : "") + (m ? ` (${m} with errors)` : "")
+  ), (m > 0 || e.check && u > 0) && process.exit(1);
 }
-function q() {
+function F() {
   console.log(`
 stonecrop-schema - Convert GraphQL schemas to Stonecrop doctypes
 
@@ -104,11 +120,16 @@ OUTPUT:
 OPTIONS:
   --include <types>            Comma-separated list of type names to include
   --exclude <types>            Comma-separated list of type names to exclude
-  --overrides <file>           JSON file with per-type field overrides
+  --names <file>               JSON file mapping GraphQL type name to doctype name
   --custom-scalars <file>      JSON file mapping custom scalar names to field templates
   --include-unmapped           Include _graphqlType metadata on unmapped fields
+  --check                      Report drift and exit non-zero if anything would change; write nothing
   --help, -h                   Show this help message
 
+NOTE: an existing doctype file is the source of truth. Regeneration verifies it against the
+schema and adds 'source: introspected' markers; it reports disagreements rather than
+overwriting them, so hand-curation survives. Use --check in CI.
+
 EXAMPLES:
   # From a live PostGraphile server
   stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas
@@ -125,7 +146,7 @@ EXAMPLES:
     --include "User,Post,Comment"
 `);
 }
-E().catch((e) => {
+D().catch((e) => {
   console.error("Error:", e.message), process.exit(1);
 });
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/* oxlint-disable no-console */\n\n/**\n * Stonecrop Schema CLI\n *\n * Converts GraphQL introspection results to Stonecrop doctype JSON schemas.\n *\n * Usage:\n *   stonecrop-schema generate --endpoint <url> --output <dir>\n *   stonecrop-schema generate --introspection <file.json> --output <dir>\n *   stonecrop-schema generate --sdl <file.graphql> --output <dir>\n *\n * @packageDocumentation\n */\n\nimport { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'\nimport { resolve, join } from 'node:path'\nimport { parseArgs } from 'node:util'\nimport { getIntrospectionQuery, type IntrospectionQuery } from 'graphql'\n\nimport { convertGraphQLSchema } from './converter/index'\nimport { validateDoctype } from './validation'\nimport type { GraphQLConversionOptions } from './converter/types'\n\n/**\n * Fetch an introspection result from a live GraphQL endpoint.\n *\n * @param endpoint - The GraphQL endpoint URL\n * @param headers - Optional HTTP headers\n * @returns The introspection query result\n */\nasync function fetchIntrospection(endpoint: string, headers?: Record<string, string>): Promise<IntrospectionQuery> {\n\tconst response = await fetch(endpoint, {\n\t\tmethod: 'POST',\n\t\theaders: {\n\t\t\t'Content-Type': 'application/json',\n\t\t\t...headers,\n\t\t},\n\t\tbody: JSON.stringify({\n\t\t\tquery: getIntrospectionQuery(),\n\t\t}),\n\t})\n\n\tif (!response.ok) {\n\t\tthrow new Error(`Failed to fetch introspection: ${response.status} ${response.statusText}`)\n\t}\n\n\tconst json: { data?: IntrospectionQuery; errors?: Array<{ message: string }> } = await response.json()\n\n\tif (json.errors?.length) {\n\t\tthrow new Error(`GraphQL errors: ${json.errors.map(e => e.message).join(', ')}`)\n\t}\n\n\tif (!json.data) {\n\t\tthrow new Error('No data in introspection response')\n\t}\n\n\treturn json.data\n}\n\nasync function main(): Promise<void> {\n\tconst { values, positionals } = parseArgs({\n\t\tallowPositionals: true,\n\t\toptions: {\n\t\t\tendpoint: { type: 'string', short: 'e' },\n\t\t\tintrospection: { type: 'string', short: 'i' },\n\t\t\tsdl: { type: 'string', short: 's' },\n\t\t\toutput: { type: 'string', short: 'o' },\n\t\t\tinclude: { type: 'string' },\n\t\t\texclude: { type: 'string' },\n\t\t\toverrides: { type: 'string' },\n\t\t\t'custom-scalars': { type: 'string' },\n\t\t\t'include-unmapped': { type: 'boolean', default: false },\n\t\t\thelp: { type: 'boolean', short: 'h' },\n\t\t},\n\t})\n\n\tconst command = positionals[0]\n\n\tif (values.help || !command) {\n\t\tprintHelp()\n\t\tprocess.exit(command ? 0 : 1)\n\t}\n\n\tif (command !== 'generate') {\n\t\tconsole.error(`Unknown command: ${command}`)\n\t\tconsole.error('Available commands: generate')\n\t\tprocess.exit(1)\n\t}\n\n\t// Determine source\n\tconst sourceCount = [values.endpoint, values.introspection, values.sdl].filter(Boolean).length\n\tif (sourceCount !== 1) {\n\t\tconsole.error('Exactly one of --endpoint, --introspection, or --sdl must be provided')\n\t\tprocess.exit(1)\n\t}\n\n\tif (!values.output) {\n\t\tconsole.error('--output <dir> is required')\n\t\tprocess.exit(1)\n\t}\n\n\tconst outputDir = resolve(values.output)\n\n\t// Build conversion options\n\tconst options: GraphQLConversionOptions = {\n\t\tincludeUnmappedMeta: values['include-unmapped'],\n\t}\n\n\tif (values.include) {\n\t\toptions.include = values.include.split(',').map(s => s.trim())\n\t}\n\n\tif (values.exclude) {\n\t\toptions.exclude = values.exclude.split(',').map(s => s.trim())\n\t}\n\n\tif (values.overrides) {\n\t\tconst overridesPath = resolve(values.overrides)\n\t\tconst overridesContent = readFileSync(overridesPath, 'utf-8')\n\t\toptions.typeOverrides = JSON.parse(overridesContent)\n\t}\n\n\tif (values['custom-scalars']) {\n\t\tconst scalarsPath = resolve(values['custom-scalars'])\n\t\tconst scalarsContent = readFileSync(scalarsPath, 'utf-8')\n\t\toptions.customScalars = JSON.parse(scalarsContent)\n\t}\n\n\t// Resolve source\n\tlet source: IntrospectionQuery | string\n\n\tif (values.endpoint) {\n\t\tconsole.log(`Fetching introspection from ${values.endpoint}...`)\n\t\tsource = await fetchIntrospection(values.endpoint)\n\t} else if (values.introspection) {\n\t\tconst filePath = resolve(values.introspection)\n\t\tconst content = readFileSync(filePath, 'utf-8')\n\t\tconst parsed = JSON.parse(content)\n\t\t// Handle both { data: { __schema: ... } } and { __schema: ... } formats\n\t\tsource = parsed.data ?? parsed\n\t} else {\n\t\tconst filePath = resolve(values.sdl!)\n\t\tsource = readFileSync(filePath, 'utf-8')\n\t}\n\n\t// Convert\n\tconst doctypes = convertGraphQLSchema(source, options)\n\n\tif (doctypes.length === 0) {\n\t\tconsole.warn('No entity types found in the schema. Check your include/exclude filters.')\n\t\tprocess.exit(0)\n\t}\n\n\t// Write output\n\tif (!existsSync(outputDir)) {\n\t\tmkdirSync(outputDir, { recursive: true })\n\t}\n\n\tlet warnings = 0\n\tlet errors = 0\n\n\tfor (const doctype of doctypes) {\n\t\tconst fileName = `${doctype.slug}.json`\n\t\tconst filePath = join(outputDir, fileName)\n\t\tconst json = JSON.stringify(doctype, null, '\\t')\n\n\t\twriteFileSync(filePath, json + '\\n', 'utf-8')\n\n\t\t// Validate the output\n\t\tconst validation = validateDoctype(doctype)\n\t\tif (!validation.success) {\n\t\t\terrors++\n\t\t\tconsole.error(`  ERROR: ${fileName} failed validation:`)\n\t\t\tfor (const err of validation.errors) {\n\t\t\t\tconsole.error(`    ${err.path.join('.')}: ${err.message}`)\n\t\t\t}\n\t\t} else {\n\t\t\t// Check for unmapped fields\n\t\t\tconst unmappedFields = doctype.fields.filter((f: any) => f._unmapped)\n\t\t\tif (unmappedFields.length > 0) {\n\t\t\t\twarnings++\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`  WARN: ${fileName} has ${unmappedFields.length} unmapped field(s): ${unmappedFields\n\t\t\t\t\t\t.map((f: any) => f.fieldname)\n\t\t\t\t\t\t.join(', ')}`\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\t}\n\n\tconsole.log(\n\t\t`\\nGenerated ${doctypes.length} doctype(s) in ${outputDir}` +\n\t\t\t(warnings ? ` (${warnings} with warnings)` : '') +\n\t\t\t(errors ? ` (${errors} with errors)` : '')\n\t)\n\n\tif (errors > 0) {\n\t\tprocess.exit(1)\n\t}\n}\n\nfunction printHelp(): void {\n\tconsole.log(`\nstonecrop-schema - Convert GraphQL schemas to Stonecrop doctypes\n\nUSAGE:\n  stonecrop-schema generate [options]\n\nSOURCE (exactly one required):\n  --endpoint, -e <url>         Fetch introspection from a live GraphQL endpoint\n  --introspection, -i <file>   Read from a saved introspection JSON file\n  --sdl, -s <file>             Read from a GraphQL SDL (.graphql) file\n\nOUTPUT:\n  --output, -o <dir>           Directory to write doctype JSON files (required)\n\nOPTIONS:\n  --include <types>            Comma-separated list of type names to include\n  --exclude <types>            Comma-separated list of type names to exclude\n  --overrides <file>           JSON file with per-type field overrides\n  --custom-scalars <file>      JSON file mapping custom scalar names to field templates\n  --include-unmapped           Include _graphqlType metadata on unmapped fields\n  --help, -h                   Show this help message\n\nEXAMPLES:\n  # From a live PostGraphile server\n  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas\n\n  # From a saved introspection result\n  stonecrop-schema generate -i introspection.json -o ./schemas\n\n  # From an SDL file with custom scalars\n  stonecrop-schema generate -s schema.graphql -o ./schemas \\\\\n    --custom-scalars custom-scalars.json\n\n  # Only convert specific types\n  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas \\\\\n    --include \"User,Post,Comment\"\n`)\n}\n\nmain().catch(err => {\n\tconsole.error('Error:', err.message)\n\tprocess.exit(1)\n})\n"],"names":["fetchIntrospection","endpoint","headers","response","getIntrospectionQuery","json","e","main","values","positionals","parseArgs","command","printHelp","outputDir","resolve","options","s","overridesPath","overridesContent","readFileSync","scalarsPath","scalarsContent","source","filePath","content","parsed","doctypes","convertGraphQLSchema","existsSync","mkdirSync","warnings","errors","doctype","fileName","join","writeFileSync","validation","validateDoctype","unmappedFields","f","err"],"mappings":"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"}
+{"version":3,"file":"cli.js","sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/* oxlint-disable no-console */\n\n/**\n * Stonecrop Schema CLI\n *\n * Converts GraphQL introspection results to Stonecrop doctype JSON schemas.\n *\n * Usage:\n *   stonecrop-schema generate --endpoint <url> --output <dir>\n *   stonecrop-schema generate --introspection <file.json> --output <dir>\n *   stonecrop-schema generate --sdl <file.graphql> --output <dir>\n *\n * @packageDocumentation\n */\n\nimport { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'\nimport { resolve, join } from 'node:path'\nimport { parseArgs } from 'node:util'\nimport { getIntrospectionQuery, type IntrospectionQuery } from 'graphql'\n\nimport { convertGraphQLSchema, formatDoctypeDrift, mergeIntrospectedDoctype } from './converter/index'\nimport { validateDoctype } from './validation'\nimport type { GraphQLConversionOptions } from './converter/types'\n\n/**\n * Fetch an introspection result from a live GraphQL endpoint.\n *\n * @param endpoint - The GraphQL endpoint URL\n * @param headers - Optional HTTP headers\n * @returns The introspection query result\n */\nasync function fetchIntrospection(endpoint: string, headers?: Record<string, string>): Promise<IntrospectionQuery> {\n\tconst response = await fetch(endpoint, {\n\t\tmethod: 'POST',\n\t\theaders: {\n\t\t\t'Content-Type': 'application/json',\n\t\t\t...headers,\n\t\t},\n\t\tbody: JSON.stringify({\n\t\t\tquery: getIntrospectionQuery(),\n\t\t}),\n\t})\n\n\tif (!response.ok) {\n\t\tthrow new Error(`Failed to fetch introspection: ${response.status} ${response.statusText}`)\n\t}\n\n\tconst json: { data?: IntrospectionQuery; errors?: Array<{ message: string }> } = await response.json()\n\n\tif (json.errors?.length) {\n\t\tthrow new Error(`GraphQL errors: ${json.errors.map(e => e.message).join(', ')}`)\n\t}\n\n\tif (!json.data) {\n\t\tthrow new Error('No data in introspection response')\n\t}\n\n\treturn json.data\n}\n\nasync function main(): Promise<void> {\n\tconst { values, positionals } = parseArgs({\n\t\tallowPositionals: true,\n\t\toptions: {\n\t\t\tendpoint: { type: 'string', short: 'e' },\n\t\t\tintrospection: { type: 'string', short: 'i' },\n\t\t\tsdl: { type: 'string', short: 's' },\n\t\t\toutput: { type: 'string', short: 'o' },\n\t\t\tinclude: { type: 'string' },\n\t\t\texclude: { type: 'string' },\n\t\t\tnames: { type: 'string' },\n\t\t\t'custom-scalars': { type: 'string' },\n\t\t\t'include-unmapped': { type: 'boolean', default: false },\n\t\t\tcheck: { type: 'boolean', default: false },\n\t\t\thelp: { type: 'boolean', short: 'h' },\n\t\t},\n\t})\n\n\tconst command = positionals[0]\n\n\tif (values.help || !command) {\n\t\tprintHelp()\n\t\tprocess.exit(command ? 0 : 1)\n\t}\n\n\tif (command !== 'generate') {\n\t\tconsole.error(`Unknown command: ${command}`)\n\t\tconsole.error('Available commands: generate')\n\t\tprocess.exit(1)\n\t}\n\n\t// Determine source\n\tconst sourceCount = [values.endpoint, values.introspection, values.sdl].filter(Boolean).length\n\tif (sourceCount !== 1) {\n\t\tconsole.error('Exactly one of --endpoint, --introspection, or --sdl must be provided')\n\t\tprocess.exit(1)\n\t}\n\n\tif (!values.output) {\n\t\tconsole.error('--output <dir> is required')\n\t\tprocess.exit(1)\n\t}\n\n\tconst outputDir = resolve(values.output)\n\n\t// Build conversion options\n\tconst options: GraphQLConversionOptions = {\n\t\tincludeUnmappedMeta: values['include-unmapped'],\n\t}\n\n\tif (values.include) {\n\t\toptions.include = values.include.split(',').map(s => s.trim())\n\t}\n\n\tif (values.exclude) {\n\t\toptions.exclude = values.exclude.split(',').map(s => s.trim())\n\t}\n\n\tif (values.names) {\n\t\tconst namesPath = resolve(values.names)\n\t\toptions.doctypeNames = JSON.parse(readFileSync(namesPath, 'utf-8'))\n\t}\n\n\toptions.onWarning = message => console.warn(`  WARN: ${message}`)\n\n\tif (values['custom-scalars']) {\n\t\tconst scalarsPath = resolve(values['custom-scalars'])\n\t\tconst scalarsContent = readFileSync(scalarsPath, 'utf-8')\n\t\toptions.customScalars = JSON.parse(scalarsContent)\n\t}\n\n\t// Resolve source\n\tlet source: IntrospectionQuery | string\n\n\tif (values.endpoint) {\n\t\tconsole.log(`Fetching introspection from ${values.endpoint}...`)\n\t\tsource = await fetchIntrospection(values.endpoint)\n\t} else if (values.introspection) {\n\t\tconst filePath = resolve(values.introspection)\n\t\tconst content = readFileSync(filePath, 'utf-8')\n\t\tconst parsed = JSON.parse(content)\n\t\t// Handle both { data: { __schema: ... } } and { __schema: ... } formats\n\t\tsource = parsed.data ?? parsed\n\t} else {\n\t\tconst filePath = resolve(values.sdl!)\n\t\tsource = readFileSync(filePath, 'utf-8')\n\t}\n\n\t// Convert\n\tconst doctypes = convertGraphQLSchema(source, options)\n\n\tif (doctypes.length === 0) {\n\t\tconsole.warn('No entity types found in the schema. Check your include/exclude filters.')\n\t\tprocess.exit(0)\n\t}\n\n\t// Write output\n\tif (!existsSync(outputDir)) {\n\t\tmkdirSync(outputDir, { recursive: true })\n\t}\n\n\tlet warnings = 0\n\tlet errors = 0\n\tlet changed = 0\n\tconst driftLines: string[] = []\n\n\tfor (const generated of doctypes) {\n\t\tconst fileName = `${generated.slug}.json`\n\t\tconst filePath = join(outputDir, fileName)\n\n\t\t// When a doctype already exists it is the source of truth: generation confirms it and adds\n\t\t// provenance markers, and reports anything it disagrees with rather than applying it. A\n\t\t// doctype legitimately declares identity the schema cannot express — most often a natural\n\t\t// key that is a UNIQUE constraint, not the table's PRIMARY KEY — and overwriting that would\n\t\t// silently re-key the doctype on every run. A first generation has nothing to merge into,\n\t\t// so converter output is written verbatim.\n\t\tlet output: object = generated\n\t\tif (existsSync(filePath)) {\n\t\t\tconst { doctype: merged, drift } = mergeIntrospectedDoctype(\n\t\t\t\tJSON.parse(readFileSync(filePath, 'utf-8')),\n\t\t\t\tgenerated\n\t\t\t)\n\t\t\toutput = merged\n\t\t\tdriftLines.push(...formatDoctypeDrift(drift))\n\t\t}\n\n\t\t// Serialize the merged object directly. Never round-trip it through the Zod parser first:\n\t\t// that runs in strip mode and would silently drop every key this package does not model,\n\t\t// `handler` on an action being the one consumers actually rely on.\n\t\tconst json = JSON.stringify(output, null, '\\t') + '\\n'\n\t\tconst unchanged = existsSync(filePath) && readFileSync(filePath, 'utf-8') === json\n\t\tif (!unchanged) changed++\n\n\t\tif (!values.check && !unchanged) {\n\t\t\twriteFileSync(filePath, json, 'utf-8')\n\t\t}\n\n\t\t// Validate the output\n\t\tconst validation = validateDoctype(output)\n\t\tif (!validation.success) {\n\t\t\terrors++\n\t\t\tconsole.error(`  ERROR: ${fileName} failed validation:`)\n\t\t\tfor (const err of validation.errors) {\n\t\t\t\tconsole.error(`    ${err.path.join('.')}: ${err.message}`)\n\t\t\t}\n\t\t} else {\n\t\t\t// Check for unmapped fields\n\t\t\tconst unmappedFields = generated.fields.filter((f: any) => f._unmapped)\n\t\t\tif (unmappedFields.length > 0) {\n\t\t\t\twarnings++\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`  WARN: ${fileName} has ${unmappedFields.length} unmapped field(s): ${unmappedFields\n\t\t\t\t\t\t.map((f: any) => f.fieldname)\n\t\t\t\t\t\t.join(', ')}`\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\t}\n\n\tif (driftLines.length > 0) {\n\t\tconsole.log('\\nDrift between the authored doctypes and the schema (reported, not applied):')\n\t\tfor (const line of driftLines) console.log(line)\n\t}\n\n\tconsole.log(\n\t\t`\\n${values.check ? 'Checked' : 'Generated'} ${doctypes.length} doctype(s) in ${outputDir}` +\n\t\t\t(changed ? ` (${changed} ${values.check ? 'would change' : 'written'})` : ' (all up to date)') +\n\t\t\t(warnings ? ` (${warnings} with warnings)` : '') +\n\t\t\t(errors ? ` (${errors} with errors)` : '')\n\t)\n\n\tif (errors > 0 || (values.check && changed > 0)) {\n\t\tprocess.exit(1)\n\t}\n}\n\nfunction printHelp(): void {\n\tconsole.log(`\nstonecrop-schema - Convert GraphQL schemas to Stonecrop doctypes\n\nUSAGE:\n  stonecrop-schema generate [options]\n\nSOURCE (exactly one required):\n  --endpoint, -e <url>         Fetch introspection from a live GraphQL endpoint\n  --introspection, -i <file>   Read from a saved introspection JSON file\n  --sdl, -s <file>             Read from a GraphQL SDL (.graphql) file\n\nOUTPUT:\n  --output, -o <dir>           Directory to write doctype JSON files (required)\n\nOPTIONS:\n  --include <types>            Comma-separated list of type names to include\n  --exclude <types>            Comma-separated list of type names to exclude\n  --names <file>               JSON file mapping GraphQL type name to doctype name\n  --custom-scalars <file>      JSON file mapping custom scalar names to field templates\n  --include-unmapped           Include _graphqlType metadata on unmapped fields\n  --check                      Report drift and exit non-zero if anything would change; write nothing\n  --help, -h                   Show this help message\n\nNOTE: an existing doctype file is the source of truth. Regeneration verifies it against the\nschema and adds 'source: introspected' markers; it reports disagreements rather than\noverwriting them, so hand-curation survives. Use --check in CI.\n\nEXAMPLES:\n  # From a live PostGraphile server\n  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas\n\n  # From a saved introspection result\n  stonecrop-schema generate -i introspection.json -o ./schemas\n\n  # From an SDL file with custom scalars\n  stonecrop-schema generate -s schema.graphql -o ./schemas \\\\\n    --custom-scalars custom-scalars.json\n\n  # Only convert specific types\n  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas \\\\\n    --include \"User,Post,Comment\"\n`)\n}\n\nmain().catch(err => {\n\tconsole.error('Error:', err.message)\n\tprocess.exit(1)\n})\n"],"names":["fetchIntrospection","endpoint","headers","response","getIntrospectionQuery","json","e","main","values","positionals","parseArgs","command","printHelp","outputDir","resolve","options","s","namesPath","readFileSync","message","scalarsPath","scalarsContent","source","filePath","content","parsed","doctypes","convertGraphQLSchema","existsSync","mkdirSync","warnings","errors","changed","driftLines","generated","fileName","join","output","merged","drift","mergeIntrospectedDoctype","formatDoctypeDrift","unchanged","writeFileSync","validation","validateDoctype","unmappedFields","f","err","line"],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { A as d, D as A, F as u, G as p, I as S, T, a as m, b as y, V as L, W as C, d as N, e as F, f as b, g as f, h as k, i as O, c as D, j as I, k as x, l as E, n as h, p as _, m as M, o as g, s as v, q as P, t as R, r as w, v as W, u as G } from "./validation-Dyxjvaio.js";
+import { A as d, D as A, F as p, G as u, I as y, a as T, T as m, b as S, d as D, V as I, W as L, e as N, g as C, h as f, i as F, j as O, k as b, c as k, l as E, n as x, f as P, o as _, p as g, q as h, m as R, r as M, s as v, t as w, u as W, w as G, x as K, y as j, z as Q, v as V, B as q } from "./validation-CToUOy0a.js";
 const a = {
   ATextInput: "text",
   ATextboxInput: "text",
@@ -31,45 +31,50 @@ function i(e) {
 function s(e, n) {
   return i(e.component ?? n) === "inline" ? "inline" : e.cardinality === "noneOrMany" || e.cardinality === "atLeastOne" ? "table" : "record";
 }
-const l = [
+const r = [
   .../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(t)])
 ].toSorted();
 export {
   d as ActionDefinition,
-  l as CANONICAL_COMPONENTS,
+  r as CANONICAL_COMPONENTS,
   a as COMPONENT_CATEGORY,
   t as COMPONENT_LINK_EXPANSION,
   A as DoctypeFieldSchema,
-  u as FieldsetFieldSchema,
-  p as GQL_SCALAR_MAP,
-  S as INTERNAL_SCALARS,
-  T as TableFieldSchema,
-  m as TableViewConfig,
-  y as TriggerDefinition,
-  L as ValueFieldSchema,
-  C as WELL_KNOWN_SCALARS,
+  p as FieldsetFieldSchema,
+  u as GQL_SCALAR_MAP,
+  y as INTERNAL_SCALARS,
+  T as INTROSPECTED_IDENTITY_PROPS,
+  m as TableFieldSchema,
+  S as TableViewConfig,
+  D as TriggerDefinition,
+  I as ValueFieldSchema,
+  L as WELL_KNOWN_SCALARS,
   N as WorkflowLayout,
-  F as WorkflowMeta,
-  b as buildScalarMap,
-  f as camelToLabel,
-  k as camelToSnake,
-  O as classifyFieldType,
+  C as WorkflowMeta,
+  f as buildScalarMap,
+  F as camelToLabel,
+  O as camelToSnake,
+  b as classifyFieldType,
   o as componentCategory,
   i as componentLinkExpansion,
-  D as convertGraphQLSchema,
-  I as defaultIsEntityField,
+  k as convertGraphQLSchema,
+  E as defaultIsEntityField,
   x as defaultIsEntityType,
-  E as isActionAllowedInState,
-  h as normalizeFieldKind,
-  _ as parseDoctype,
-  M as parseField,
-  g as pascalToSnake,
+  P as formatDoctypeDrift,
+  _ as getPrimaryKeyField,
+  g as getRecordIdentity,
+  h as isActionAllowedInState,
+  R as mergeIntrospectedDoctype,
+  M as normalizeFieldKind,
+  v as parseDoctype,
+  w as parseField,
+  W as pascalToSnake,
   s as resolveLinkRenderMode,
-  v as snakeToCamel,
-  P as snakeToLabel,
-  R as toPascalCase,
-  w as toSlug,
-  W as validateDoctype,
-  G as validateField
+  G as snakeToCamel,
+  K as snakeToLabel,
+  j as toPascalCase,
+  Q as toSlug,
+  V as validateDoctype,
+  q as validateField
 };
 //# sourceMappingURL=index.js.map

package/dist/schema.d.ts

@@ -23,6 +23,15 @@ export declare const ActionDefinition: z.ZodObject<{
  */
 export declare type ActionDefinition = z.infer<typeof ActionDefinition>;
 
+/**
+ * A doctype as it exists on disk: a plain object that may carry keys this package does not model
+ * (`handler` on an action, `filterFunction` on a field, whatever an app has added). Typing it
+ * loosely is what lets the merge round-trip those keys untouched instead of dropping them.
+ *
+ * @public
+ */
+export declare type AuthoredDoctype = Record<string, unknown>;
+
 /**
  * Build a merged scalar map from the built-in maps and user-provided custom scalars.
  * Precedence (highest to lowest): customScalars → GQL_SCALAR_MAP → WELL_KNOWN_SCALARS
@@ -464,6 +473,36 @@ export declare interface DoctypeContext {
     [key: string]: unknown;
 }
 
+/**
+ * What generation found that the authored doctype does not agree with. Every bucket is advisory —
+ * nothing here is applied automatically.
+ *
+ * @public
+ */
+export declare interface DoctypeDrift {
+    /** The authored doctype's name. */
+    doctype: string;
+    /**
+     * `clean` — the authored primary key is the one generation would derive.
+     * `partial` — the doctype declares an identity generation cannot derive, so identity was left alone.
+     */
+    mode: 'clean' | 'partial';
+    /** Why the mode is `partial`, when it is. */
+    reason?: string;
+    /** Fieldnames confirmed against the schema and stamped. */
+    tagged: string[];
+    /** Authored fields with no matching schema field — app components, fieldsets, or stale entries. */
+    orphan: string[];
+    /** Schema fields absent from the doctype. Usually deliberate curation, occasionally an oversight. */
+    omitted: string[];
+    /** `fieldname: authored=… schema=…` where the chosen component differs from the scalar mapping. */
+    componentDrift: string[];
+    /** `fieldname: authored=… schema=…` where nullability disagrees. */
+    requiredDrift: string[];
+    /** Identity properties that differ. These are the ones a human must adjudicate. */
+    identityDrift: string[];
+}
+
 /**
  * Union of all authoring-time field variants.
  * Use `kind` to discriminate: `'field'` | `'fieldset'` | `'table'`.
@@ -676,6 +715,52 @@ export declare const FieldValidation: z.ZodObject<{
  */
 export declare type FieldValidation = z.infer<typeof FieldValidation>;
 
+/**
+ * Render a drift report as human-readable lines. Empty when generation agrees with the doctype.
+ *
+ * @param drift - a report from {@link mergeIntrospectedDoctype}
+ * @returns one line per finding, ready to print
+ *
+ * @public
+ */
+export declare function formatDoctypeDrift(drift: DoctypeDrift): string[];
+
+/**
+ * Find the field a doctype marks as its primary key, or `undefined` when none is marked.
+ *
+ * This is the single definition of "which field identifies a record". Both sides depend on it:
+ * the middleware builds the SQL identity predicate from it, and the client resolves a record's
+ * route/store key from it. Call this; never re-derive the rule at the call site, or the two will
+ * drift and the client will key records by a column the server never queried.
+ *
+ * Two deliberate limits, both matching the shape `primaryKey` actually has:
+ * - Only **top-level** fields are scanned. `primaryKey` is a `ValueField` flag and a fieldset's
+ *   children are not identity columns, so a nested match would be an authoring error, not a PK.
+ * - The **first** match wins. Nothing in the schema enforces exactly one `primaryKey: true`, and
+ *   there is no composite-key representation — a doctype with several is already malformed, and
+ *   picking the first is what the middleware has always done.
+ *
+ * @param fields - the doctype's top-level fields
+ * @returns the primary-key field, or `undefined` for a PK-less doctype
+ * @public
+ */
+export declare function getPrimaryKeyField(fields: readonly DoctypeField[]): ValueField | undefined;
+
+/**
+ * Resolve a record's identity value using the doctype's declared primary key.
+ *
+ * Falls back to `record.id` when the doctype declares no `primaryKey`. That fallback is
+ * load-bearing, not defensive: surrogate-key doctypes carry an `id` column and never mark a
+ * primary key, and PostGraphile renames a single-column `id` PK to `rowId` — so the declared
+ * field and `id` are both real sources, in that order.
+ *
+ * @param fields - the doctype's top-level fields
+ * @param record - the record to read the identity from
+ * @returns the identity as a string, or `undefined` when neither source yields a usable value
+ * @public
+ */
+export declare function getRecordIdentity(fields: readonly DoctypeField[], record: Record<string, unknown>): string | undefined;
+
 /**
  * Options for fetching a single record
  * @public
@@ -760,19 +845,28 @@ export declare interface GraphQLConversionOptions {
      */
     include?: string[];
     /**
-     * Per-type, per-field overrides for the converted field definitions.
-     * Outer key is the GraphQL type name, inner key is the field name.
+     * Emit a doctype under a different name than its GraphQL type. Key is the GraphQL type name,
+     * value is the doctype `name`; `slug` is derived from the value.
+     *
+     * This exists for the case where a doctype is not one-to-one with a table — a second view over
+     * an existing type, say, distinguished only by presentation. Without it the converter can only
+     * ever name a doctype after its type.
+     *
+     * Keep it consistent with the middleware's `tables` option, which maps the resulting doctype
+     * name to its SQL target.
      *
      * @example
      * ```typescript
-     * {
-     *   SalesOrder: {
-     *     totalAmount: { component: 'ANumericInput', align: 'right' }
-     *   }
-     * }
+     * { Plan: 'Planner' }   // emits a doctype named Planner, slug 'planner', from type Plan
      * ```
      */
-    typeOverrides?: Record<string, Record<string, Omit<Partial<ValueField>, 'kind'>>>;
+    doctypeNames?: Record<string, string>;
+    /**
+     * Called with any advisory message raised during conversion — currently only the
+     * un-normalized-PostGraphile warning. Left to the caller so the library never writes to the
+     * console itself.
+     */
+    onWarning?: (message: string) => void;
     /**
      * Map custom or non-standard GraphQL scalar types to the component that renders them.
      * Merged with the built-in scalar maps (GQL_SCALAR_MAP + WELL_KNOWN_SCALARS).
@@ -853,6 +947,20 @@ export declare type InteractionMode = 'edit' | 'read' | 'display';
  */
 export declare const INTERNAL_SCALARS: Set<string>;
 
+/**
+ * The field properties a `source: 'introspected'` marker freezes — the ones the database owns.
+ *
+ * This is the single definition of the identity set. The docbuilder greys these inputs on an
+ * introspected field, and the converter's merge refuses to rewrite them. Stating it twice is how
+ * the two drift, so both read this constant.
+ *
+ * Everything absent from this list is author-owned, `component` most importantly: it chooses the
+ * widget, which is an authoring decision the database has no opinion about.
+ *
+ * @public
+ */
+export declare const INTROSPECTED_IDENTITY_PROPS: readonly ["fieldname", "primaryKey", "required", "options", "cardinality", "doctype"];
+
 /**
  * Input source for the GraphQL schema converter.
  * Accepts either a standard GraphQL introspection result or an SDL string.
@@ -956,6 +1064,32 @@ export declare type LinkExpansion = 'inline' | 'expand';
  */
 export declare type LinkRenderMode = 'inline' | 'record' | 'table';
 
+/**
+ * Verify an authored doctype against freshly generated output and stamp provenance.
+ *
+ * @param authored - the doctype as it exists on disk; every key not named below is preserved verbatim
+ * @param generated - `convertGraphQLSchema` output for the corresponding GraphQL type
+ * @returns the doctype to write, plus a drift report
+ *
+ * @example
+ * ```ts
+ * const [generated] = convertGraphQLSchema(introspection, { include: ['Uom'] })
+ * const { doctype, drift } = mergeIntrospectedDoctype(JSON.parse(onDisk), generated)
+ * if (drift.identityDrift.length) console.warn(drift.identityDrift.join('\n'))
+ * ```
+ *
+ * @public
+ */
+export declare function mergeIntrospectedDoctype(authored: AuthoredDoctype, generated: ConvertedGraphQLDoctype): MergeResult;
+
+/** Outcome of a merge: the doctype to write, plus what generation disagreed with. @public */
+export declare interface MergeResult {
+    /** The authored doctype with `source` markers added and nothing else changed. */
+    doctype: AuthoredDoctype;
+    /** Advisory report. Never applied. */
+    drift: DoctypeDrift;
+}
+
 /**
  * Recursively injects the `kind` discriminant into a raw field object and, for fieldsets,
  * into each of its nested `schema` children — mirroring exactly what Zod's `preprocess`