@stonecrop/schema 0.16.4 → 0.16.5

package/dist/src/cli.js

@@ -16,7 +16,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { getIntrospectionQuery } from 'graphql';
-import { convertGraphQLSchema } from './converter/index';
+import { convertGraphQLSchema, formatDoctypeDrift, mergeIntrospectedDoctype } from './converter/index';
 import { validateDoctype } from './validation';
 /**
  * Fetch an introspection result from a live GraphQL endpoint.
@@ -58,9 +58,10 @@ async function main() {
             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: false },
+            check: { type: 'boolean', default: false },
             help: { type: 'boolean', short: 'h' },
         },
     });
@@ -95,11 +96,11 @@ async function main() {
     if (values.exclude) {
         options.exclude = values.exclude.split(',').map(s => s.trim());
     }
-    if (values.overrides) {
-        const overridesPath = resolve(values.overrides);
-        const overridesContent = readFileSync(overridesPath, 'utf-8');
-        options.typeOverrides = JSON.parse(overridesContent);
+    if (values.names) {
+        const namesPath = resolve(values.names);
+        options.doctypeNames = JSON.parse(readFileSync(namesPath, 'utf-8'));
     }
+    options.onWarning = message => console.warn(`  WARN: ${message}`);
     if (values['custom-scalars']) {
         const scalarsPath = resolve(values['custom-scalars']);
         const scalarsContent = readFileSync(scalarsPath, 'utf-8');
@@ -134,13 +135,35 @@ async function main() {
     }
     let warnings = 0;
     let errors = 0;
-    for (const doctype of doctypes) {
-        const fileName = `${doctype.slug}.json`;
+    let changed = 0;
+    const driftLines = [];
+    for (const generated of doctypes) {
+        const fileName = `${generated.slug}.json`;
         const filePath = join(outputDir, fileName);
-        const json = JSON.stringify(doctype, null, '\t');
-        writeFileSync(filePath, json + '\n', 'utf-8');
+        // When a doctype already exists it is the source of truth: generation confirms it and adds
+        // provenance markers, and reports anything it disagrees with rather than applying it. A
+        // doctype legitimately declares identity the schema cannot express — most often a natural
+        // key that is a UNIQUE constraint, not the table's PRIMARY KEY — and overwriting that would
+        // silently re-key the doctype on every run. A first generation has nothing to merge into,
+        // so converter output is written verbatim.
+        let output = generated;
+        if (existsSync(filePath)) {
+            const { doctype: merged, drift } = mergeIntrospectedDoctype(JSON.parse(readFileSync(filePath, 'utf-8')), generated);
+            output = merged;
+            driftLines.push(...formatDoctypeDrift(drift));
+        }
+        // Serialize the merged object directly. Never round-trip it through the Zod parser first:
+        // that runs in strip mode and would silently drop every key this package does not model,
+        // `handler` on an action being the one consumers actually rely on.
+        const json = JSON.stringify(output, null, '\t') + '\n';
+        const unchanged = existsSync(filePath) && readFileSync(filePath, 'utf-8') === json;
+        if (!unchanged)
+            changed++;
+        if (!values.check && !unchanged) {
+            writeFileSync(filePath, json, 'utf-8');
+        }
         // Validate the output
-        const validation = validateDoctype(doctype);
+        const validation = validateDoctype(output);
         if (!validation.success) {
             errors++;
             console.error(`  ERROR: ${fileName} failed validation:`);
@@ -150,7 +173,7 @@ async function main() {
         }
         else {
             // Check for unmapped fields
-            const unmappedFields = doctype.fields.filter((f) => f._unmapped);
+            const unmappedFields = generated.fields.filter((f) => f._unmapped);
             if (unmappedFields.length > 0) {
                 warnings++;
                 console.warn(`  WARN: ${fileName} has ${unmappedFields.length} unmapped field(s): ${unmappedFields
@@ -159,10 +182,16 @@ async function main() {
             }
         }
     }
-    console.log(`\nGenerated ${doctypes.length} doctype(s) in ${outputDir}` +
+    if (driftLines.length > 0) {
+        console.log('\nDrift between the authored doctypes and the schema (reported, not applied):');
+        for (const line of driftLines)
+            console.log(line);
+    }
+    console.log(`\n${values.check ? 'Checked' : 'Generated'} ${doctypes.length} doctype(s) in ${outputDir}` +
+        (changed ? ` (${changed} ${values.check ? 'would change' : 'written'})` : ' (all up to date)') +
         (warnings ? ` (${warnings} with warnings)` : '') +
         (errors ? ` (${errors} with errors)` : ''));
-    if (errors > 0) {
+    if (errors > 0 || (values.check && changed > 0)) {
         process.exit(1);
     }
 }
@@ -184,11 +213,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

package/dist/src/converter/index.d.ts

@@ -43,5 +43,7 @@ export { convertGraphQLSchema as default };
 export type { IntrospectionSource, GraphQLConversionOptions, GraphQLConversionFieldMeta, ConvertedGraphQLDoctype, } from './types';
 export { GQL_SCALAR_MAP, WELL_KNOWN_SCALARS, INTERNAL_SCALARS, buildScalarMap } from './scalars';
 export { defaultIsEntityType, defaultIsEntityField, classifyFieldType } from './heuristics';
+export { mergeIntrospectedDoctype, formatDoctypeDrift } from './merge';
+export type { AuthoredDoctype, DoctypeDrift, MergeResult } from './merge';
 export { toSlug, toPascalCase, pascalToSnake, snakeToCamel, camelToSnake, snakeToLabel, camelToLabel } from '../naming';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/converter/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAIrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,wBAA6B,GACpC,uBAAuB,EAAE,CA+H3B;AAwBD,OAAO,EAAE,oBAAoB,IAAI,OAAO,EAAE,CAAA;AAG1C,YAAY,EACX,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhG,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAG3F,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/converter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAIrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,GAAE,wBAA6B,GACpC,uBAAuB,EAAE,CAkJ3B;AAwBD,OAAO,EAAE,oBAAoB,IAAI,OAAO,EAAE,CAAA;AAG1C,YAAY,EACX,mBAAmB,EACnB,wBAAwB,EACxB,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAGhG,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAG3F,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AACtE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAGzE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/src/converter/index.js

@@ -86,8 +86,18 @@ export function convertGraphQLSchema(source, options = {}) {
         if (!isObjectType(type))
             continue;
         const fields = type.getFields();
-        const typeOverrides = options.typeOverrides?.[typeName];
-        const entityFields = Object.entries(fields).filter(([fieldName, field]) => isEntityField(fieldName, field, type));
+        // A type carrying BOTH `id` and `rowId` is PostGraphile Amber with its default inflection:
+        // the Relay global identifier has taken `id`, displacing the real column to `rowId`. Neither
+        // name can be emitted as-is — `id` is an opaque node id, and `rowId` does not name a column.
+        // Refuse to guess: drop the Relay field and tell the caller to fix it at the inflector, where
+        // it belongs. Normalizing here would bake a database fact into the doctype.
+        const isUnnormalizedPostGraphile = 'id' in fields && 'rowId' in fields;
+        if (isUnnormalizedPostGraphile) {
+            options.onWarning?.(`${typeName}: schema exposes both 'id' (Relay identifier) and 'rowId' (the real column). ` +
+                `Skipping 'id' and emitting 'rowId' verbatim — no primary key can be derived. ` +
+                `Override the '_attributeName' and 'nodeIdFieldName' inflectors so the column keeps its own name.`);
+        }
+        const entityFields = Object.entries(fields).filter(([fieldName, field]) => isEntityField(fieldName, field, type) && !(isUnnormalizedPostGraphile && fieldName === 'id'));
         // oxlint-disable-next-line oxc/no-map-spread -- ...custom spread required; Object.assign cannot preserve the metadata-carrying inferred union type from classifyField
         const allClassifiedFields = entityFields.map(([fieldName, field]) => {
             // Check for full custom classification first
@@ -104,13 +114,14 @@ export function convertGraphQLSchema(source, options = {}) {
                 }
             }
             // Default classification
-            const classified = classifyFieldType(fieldName, field, entityTypes, options);
-            // Apply per-field overrides
-            if (typeOverrides?.[fieldName]) {
-                return Object.assign(classified, typeOverrides[fieldName]);
-            }
-            return classified;
+            return classifyFieldType(fieldName, field, entityTypes, options);
         });
+        // Derive the primary key, but only for the one case SDL actually settles: a non-null `id`
+        // that is a plain scalar. A natural key is typically a UNIQUE constraint indistinguishable
+        // from any other column here, and a table may carry several — so anything else is left for
+        // the author to declare. Emitting a guess would be worse than emitting nothing, because the
+        // middleware builds its identity predicate from this and the client keys records by it.
+        const primaryKeyFieldname = allClassifiedFields.find(field => field.fieldname === 'id' && field.required && !field.doctype && !field._isLink)?.fieldname;
         // Separate scalar fields from link fields
         const links = {};
         const convertedFields = allClassifiedFields
@@ -124,21 +135,22 @@ export function convertGraphQLSchema(source, options = {}) {
             }
             return true;
         })
-            // Clean up internal metadata unless requested, and stamp provenance.
-            // Stamped last so every classification path (default, classifyField,
-            // typeOverrides) carries the marker — the docbuilder's identity lock
-            // keys off it, and an override must not be able to unset it.
+            // Clean up internal metadata unless requested, and stamp identity + provenance.
+            // Stamped last so every classification path (default, classifyField) carries the marker —
+            // the docbuilder's identity lock keys off it, and no classifier may unset it.
             .map(field => {
+            const identity = field.fieldname === primaryKeyFieldname ? { primaryKey: true } : {};
             if (!options.includeUnmappedMeta) {
                 const { _graphqlType, _unmapped, _isLink, ...clean } = field;
-                return Object.assign(clean, { source: 'introspected' });
+                return Object.assign(clean, identity, { source: 'introspected' });
             }
             const { _isLink, ...rest } = field;
-            return Object.assign(rest, { source: 'introspected' });
+            return Object.assign(rest, identity, { source: 'introspected' });
         });
+        const doctypeName = options.doctypeNames?.[typeName] ?? typeName;
         const doctype = {
-            name: typeName,
-            slug: toSlug(typeName),
+            name: doctypeName,
+            slug: toSlug(doctypeName),
             fields: convertedFields,
         };
         if (Object.keys(links).length > 0) {
@@ -175,5 +187,7 @@ export { convertGraphQLSchema as default };
 export { GQL_SCALAR_MAP, WELL_KNOWN_SCALARS, INTERNAL_SCALARS, buildScalarMap } from './scalars';
 // Heuristics
 export { defaultIsEntityType, defaultIsEntityField, classifyFieldType } from './heuristics';
+// Merge — verifies an authored doctype against the schema and stamps provenance
+export { mergeIntrospectedDoctype, formatDoctypeDrift } from './merge';
 // Naming utilities
 export { toSlug, toPascalCase, pascalToSnake, snakeToCamel, camelToSnake, snakeToLabel, camelToLabel } from '../naming';

package/dist/src/converter/merge.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Merge introspected schema facts into an already-authored doctype.
+ *
+ * The authored doctype is the source of truth. Generation **verifies** it and stamps provenance;
+ * it does not overwrite. That polarity is deliberate and load-bearing — a doctype legitimately
+ * declares a `primaryKey` the schema cannot express. A natural business key is very often a
+ * `UNIQUE` constraint rather than the table's `PRIMARY KEY`, and where a table carries several
+ * uniques no rule can pick between them. Overwriting identity from the schema would silently
+ * re-key such a doctype on every regeneration and break the handlers that key on the old value.
+ *
+ * So divergence is **reported, never applied** — a human decides. The only mutation this performs
+ * is adding `source: 'introspected'` to fields confirmed to exist in the GraphQL schema.
+ *
+ * @packageDocumentation
+ */
+import type { ConvertedGraphQLDoctype } from './types';
+/**
+ * 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 type AuthoredDoctype = Record<string, unknown>;
+/**
+ * What generation found that the authored doctype does not agree with. Every bucket is advisory —
+ * nothing here is applied automatically.
+ *
+ * @public
+ */
+export 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[];
+}
+/** Outcome of a merge: the doctype to write, plus what generation disagreed with. @public */
+export interface MergeResult {
+    /** The authored doctype with `source` markers added and nothing else changed. */
+    doctype: AuthoredDoctype;
+    /** Advisory report. Never applied. */
+    drift: DoctypeDrift;
+}
+/**
+ * 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;
+/**
+ * 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[];
+//# sourceMappingURL=merge.d.ts.map

package/dist/src/converter/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/converter/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;IACzB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,mGAAmG;IACnG,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,qGAAqG;IACrG,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,mGAAmG;IACnG,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,oEAAoE;IACpE,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,mFAAmF;IACnF,aAAa,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC3B,iFAAiF;IACjF,OAAO,EAAE,eAAe,CAAA;IACxB,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAA;CACnB;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,uBAAuB,GAAG,WAAW,CA4EnH;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAYhE"}

package/dist/src/converter/merge.js

@@ -0,0 +1,145 @@
+/**
+ * Merge introspected schema facts into an already-authored doctype.
+ *
+ * The authored doctype is the source of truth. Generation **verifies** it and stamps provenance;
+ * it does not overwrite. That polarity is deliberate and load-bearing — a doctype legitimately
+ * declares a `primaryKey` the schema cannot express. A natural business key is very often a
+ * `UNIQUE` constraint rather than the table's `PRIMARY KEY`, and where a table carries several
+ * uniques no rule can pick between them. Overwriting identity from the schema would silently
+ * re-key such a doctype on every regeneration and break the handlers that key on the old value.
+ *
+ * So divergence is **reported, never applied** — a human decides. The only mutation this performs
+ * is adding `source: 'introspected'` to fields confirmed to exist in the GraphQL schema.
+ *
+ * @packageDocumentation
+ */
+import { INTROSPECTED_IDENTITY_PROPS } from '../field';
+/** Recursively flatten authored fields, descending into fieldsets. */
+function flattenAuthored(fields) {
+    const out = [];
+    for (const f of fields) {
+        if (Array.isArray(f.schema)) {
+            out.push(...flattenAuthored(f.schema.filter(isRecord)));
+        }
+        else {
+            out.push(f);
+        }
+    }
+    return out;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describe(value) {
+    return value === undefined ? '—' : JSON.stringify(value);
+}
+/**
+ * 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 function mergeIntrospectedDoctype(authored, generated) {
+    const authoredFields = Array.isArray(authored.fields) ? authored.fields.filter(isRecord) : [];
+    const generatedByName = new Map(generated.fields.map(f => [f.fieldname, f]));
+    // Expanding links live in `links`, not `fields`, so a field naming one is modelled, not orphaned.
+    const generatedLinkNames = new Set(Object.keys(generated.links ?? {}));
+    const drift = {
+        doctype: typeof authored.name === 'string' ? authored.name : '(unnamed)',
+        mode: 'clean',
+        tagged: [],
+        orphan: [],
+        omitted: [],
+        componentDrift: [],
+        requiredDrift: [],
+        identityDrift: [],
+    };
+    const tag = (field) => {
+        // Containers have no column of their own; recurse and leave the container itself alone.
+        if (Array.isArray(field.schema)) {
+            return { ...field, schema: field.schema.filter(isRecord).map(tag) };
+        }
+        const name = typeof field.fieldname === 'string' ? field.fieldname : '';
+        const match = generatedByName.get(name);
+        if (!match) {
+            // A computed field declares up front that it has no backing column, so it is not a
+            // discrepancy. Everything else is worth surfacing — it may be an app component, or a
+            // column that has since been dropped.
+            if (field.computed !== true && !generatedLinkNames.has(name))
+                drift.orphan.push(name);
+            return field;
+        }
+        drift.tagged.push(name);
+        if (match.component !== field.component) {
+            drift.componentDrift.push(`${name}: authored=${describe(field.component)} schema=${describe(match.component)}`);
+        }
+        if (Boolean(match.required) !== Boolean(field.required)) {
+            drift.requiredDrift.push(`${name}: authored=${Boolean(field.required)} schema=${Boolean(match.required)}`);
+        }
+        for (const prop of INTROSPECTED_IDENTITY_PROPS) {
+            if (prop === 'fieldname' || prop === 'required')
+                continue;
+            const authoredValue = field[prop];
+            const schemaValue = match[prop];
+            // Absent on both sides is agreement, not drift — most fields set none of these.
+            if (authoredValue === undefined && schemaValue === undefined)
+                continue;
+            if (JSON.stringify(authoredValue) !== JSON.stringify(schemaValue)) {
+                drift.identityDrift.push(`${name}.${prop}: authored=${describe(authoredValue)} schema=${describe(schemaValue)}`);
+            }
+        }
+        return { ...field, source: 'introspected' };
+    };
+    const merged = { ...authored, fields: authoredFields.map(tag) };
+    const authoredNames = new Set(flattenAuthored(authoredFields).map(f => f.fieldname));
+    drift.omitted = generated.fields.map(f => f.fieldname).filter(n => !authoredNames.has(n));
+    // Classify identity last, once every field has been compared.
+    const authoredPk = flattenAuthored(authoredFields).find(f => f.primaryKey === true);
+    const generatedPk = generated.fields.find(f => f.primaryKey === true);
+    if (authoredPk && generatedPk && authoredPk.fieldname !== generatedPk.fieldname) {
+        drift.mode = 'partial';
+        drift.reason = `authored primary key '${String(authoredPk.fieldname)}' is not the derivable '${generatedPk.fieldname}' — left as authored`;
+    }
+    else if (authoredPk && !generatedPk) {
+        drift.mode = 'partial';
+        drift.reason = `authored primary key '${String(authoredPk.fieldname)}' is not derivable from the schema — left as authored`;
+    }
+    else if (!authoredPk && generatedPk) {
+        drift.mode = 'partial';
+        drift.reason = `schema suggests '${generatedPk.fieldname}' as primary key but the doctype declares none — not applied`;
+    }
+    return { doctype: merged, drift };
+}
+/**
+ * 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 function formatDoctypeDrift(drift) {
+    const lines = [];
+    if (drift.reason)
+        lines.push(`  ${drift.doctype}: ${drift.reason}`);
+    const bucket = (label, entries) => {
+        if (entries.length)
+            lines.push(`  ${drift.doctype}: ${label} ${entries.join('; ')}`);
+    };
+    bucket('identity drift', drift.identityDrift);
+    bucket('component drift', drift.componentDrift);
+    bucket('required drift', drift.requiredDrift);
+    bucket('authored fields with no schema field:', drift.orphan);
+    bucket('schema fields not modelled:', drift.omitted);
+    return lines;
+}

package/dist/src/converter/types.d.ts

@@ -50,19 +50,28 @@ export 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).

package/dist/src/converter/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/converter/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG,MAAM,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAEjF;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;IAEtD;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAA;IAErE;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,iBAAiB,KAAK,OAAO,CAAA;IAEpH;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,UAAU,EAAE,iBAAiB,KACzB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAE7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,UAAU;IAC7D,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;IAC3E,iGAAiG;IACjG,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACzB;AAGD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/converter/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG,MAAM,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAErC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAErC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;IAEtD;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAA;IAErE;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,iBAAiB,KAAK,OAAO,CAAA;IAEpH;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,UAAU,EAAE,iBAAiB,KACzB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAE7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,UAAU;IAC7D,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;IAC3E,iGAAiG;IACjG,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACzB;AAGD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/field.d.ts

@@ -171,6 +171,53 @@ export type DoctypeField = ValueField | FieldsetField | TableField;
  * @public
  */
 export declare function normalizeFieldKind(field: unknown): unknown;
+/**
+ * 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"];
+/**
+ * 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;
 /**
  * Zod runtime validation schema for ValueField.
  * @public

package/dist/src/field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/field.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/field.ts"],"names":[],"mappings":"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"}

package/dist/src/field.js

@@ -96,6 +96,73 @@ export function normalizeFieldKind(field) {
     }
     return injected;
 }
+/**
+ * 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 const INTROSPECTED_IDENTITY_PROPS = [
+    'fieldname',
+    'primaryKey',
+    'required',
+    'options',
+    'cardinality',
+    'doctype',
+];
+/**
+ * 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 function getPrimaryKeyField(fields) {
+    return fields.find((f) => f.kind === 'field' && Boolean(f.primaryKey));
+}
+/**
+ * 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 function getRecordIdentity(fields, record) {
+    const pkField = getPrimaryKeyField(fields);
+    const candidates = pkField ? [record[pkField.fieldname], record.id] : [record.id];
+    for (const value of candidates) {
+        // Numbers are valid keys (a serial PK); 0 is a legitimate id, so test the type, not truthiness.
+        if (typeof value === 'number')
+            return String(value);
+        if (typeof value === 'string' && value !== '')
+            return value;
+    }
+    return undefined;
+}
 function createDoctypeFieldSchemas() {
     const ValueFieldSchema = z
         .object({