@stonecrop/schema 0.31.0 → 0.33.0

package/dist/src/converter/heuristics.js

@@ -1,304 +0,0 @@
-/**
- * Default heuristics for identifying entity types and fields in a GraphQL schema.
- *
- * These heuristics work across common GraphQL servers (PostGraphile, Hasura, Apollo, etc.)
- * by detecting widely-adopted conventions like the Relay connection pattern.
- *
- * All heuristics can be overridden via the `isEntityType`, `isEntityField`, and
- * `classifyField` options in `GraphQLConversionOptions`.
- *
- * @packageDocumentation
- */
-import { isScalarType, isEnumType, isObjectType, isListType, isNonNullType, isNamedType, } from 'graphql';
-import { buildScalarMap, INTERNAL_SCALARS } from './scalars';
-import { toSlug, camelToLabel, toPascalCase } from '../naming';
-/**
- * Suffixes that identify synthetic/framework types generated by GraphQL servers.
- * Types ending with these suffixes are typically not entities.
- */
-const SYNTHETIC_SUFFIXES = [
-    'Connection',
-    'Edge',
-    'Input',
-    'Patch',
-    'Payload',
-    'Condition',
-    'Filter',
-    'OrderBy',
-    'Aggregate',
-    'AggregateResult',
-    'AggregateFilter',
-    'DeleteResponse',
-    'InsertResponse',
-    'UpdateResponse',
-    'MutationResponse',
-];
-/**
- * Root operation type names that are never entities.
- */
-const ROOT_TYPE_NAMES = new Set(['Query', 'Mutation', 'Subscription']);
-/**
- * Default heuristic to determine if a GraphQL object type represents an entity.
- * An entity type becomes a Stonecrop doctype.
- *
- * This heuristic excludes:
- * - Introspection types (`__*`)
- * - Root operation types (`Query`, `Mutation`, `Subscription`)
- * - Types with synthetic suffixes (e.g., `*Connection`, `*Edge`, `*Input`)
- * - Types starting with `Node` interface marker (exact match only)
- *
- * @param typeName - The GraphQL type name
- * @param type - The GraphQL object type definition
- * @returns `true` if this type should become a Stonecrop doctype
- * @public
- */
-export function defaultIsEntityType(typeName, type) {
-    // Exclude introspection types
-    if (typeName.startsWith('__')) {
-        return false;
-    }
-    // Exclude root operation types
-    if (ROOT_TYPE_NAMES.has(typeName)) {
-        return false;
-    }
-    // Exclude the Node interface marker type
-    if (typeName === 'Node') {
-        return false;
-    }
-    // Exclude types matching synthetic suffixes
-    for (const suffix of SYNTHETIC_SUFFIXES) {
-        if (typeName.endsWith(suffix)) {
-            return false;
-        }
-    }
-    // Must have at least one field
-    const fields = type.getFields();
-    if (Object.keys(fields).length === 0) {
-        return false;
-    }
-    return true;
-}
-/**
- * Fields to skip by default on entity types.
- * These are internal to GraphQL servers and don't represent semantic data.
- *
- * Relay's global object identifier is deliberately absent: which field carries it is a
- * declaration, not a name. See {@link relayNodeIdField}.
- */
-const SKIP_FIELDS = new Set(['__typename', 'clientMutationId']);
-/**
- * The name Relay's Object Identification spec gives its marker interface.
- */
-const RELAY_NODE_INTERFACE = 'Node';
-/**
- * The field carrying Relay's global object identifier on this type, or `undefined` for a type that
- * declares none.
- *
- * Read off the interface rather than matched against a list of names, because the name is a server
- * setting: PostGraphile exposes it as `nodeIdFieldName`, which is `id` under the un-overridden
- * Amber preset, `nodeId` under Stonecrop's, and whatever a foreign host chose under theirs. A
- * hardcoded name is a snapshot of one of those, and gets it wrong in both directions at once — it
- * emits an opaque identifier as a column (whose every read then fails on a column that does not
- * exist), and drops a real column that happens to share the name.
- *
- * The interface must be Relay's marker and not a domain interface that shares its name, so it has
- * to declare exactly one field, a non-null `ID`, and nothing else — anything carrying domain fields
- * is a different interface, and skipping against it would drop real columns.
- *
- * @internal
- */
-function relayNodeIdField(type) {
-    for (const iface of type.getInterfaces()) {
-        if (iface.name !== RELAY_NODE_INTERFACE)
-            continue;
-        const declared = Object.values(iface.getFields());
-        if (declared.length !== 1)
-            continue;
-        const { namedType, required, isList } = unwrapType(declared[0].type);
-        if (required && !isList && namedType.name === 'ID')
-            return declared[0].name;
-    }
-    return undefined;
-}
-/**
- * Default heuristic to filter fields on entity types.
- * Skips internal fields that don't represent meaningful data.
- *
- * @param fieldName - The GraphQL field name
- * @param _field - The GraphQL field definition (unused in default implementation)
- * @param parentType - The parent entity type, whose interfaces declare its Relay identifier
- * @returns `true` if this field should be included
- * @public
- */
-export function defaultIsEntityField(fieldName, _field, parentType) {
-    if (SKIP_FIELDS.has(fieldName))
-        return false;
-    return fieldName !== relayNodeIdField(parentType);
-}
-/**
- * Unwrap NonNull and List wrappers from a GraphQL type, tracking nullability.
- *
- * @param type - The GraphQL output type
- * @returns The unwrapped named type, whether it's required, and whether it's a list
- * @internal
- */
-function unwrapType(type) {
-    let required = false;
-    let isList = false;
-    let current = type;
-    // Unwrap outer NonNull
-    if (isNonNullType(current)) {
-        required = true;
-        current = current.ofType;
-    }
-    // Unwrap List
-    if (isListType(current)) {
-        isList = true;
-        current = current.ofType;
-        // Unwrap inner NonNull (e.g., [Type!])
-        if (isNonNullType(current)) {
-            current = current.ofType;
-        }
-    }
-    // At this point, current should be a named type (scalar, enum, or object)
-    if (!isNamedType(current)) {
-        throw new Error(`Expected a named GraphQL type, got: ${String(current)}`);
-    }
-    return { namedType: current, required, isList };
-}
-/**
- * Check if a GraphQL object type looks like a Relay Connection type.
- * A connection type has an `edges` field returning a list of edge types,
- * where each edge has a `node` field.
- *
- * @param type - The GraphQL object type to check
- * @returns The node type name if this is a connection, or `undefined`
- * @internal
- */
-function getConnectionNodeType(type) {
-    const fields = type.getFields();
-    // Must have an 'edges' field
-    const edgesField = fields['edges'];
-    if (!edgesField)
-        return undefined;
-    // edges must be a list
-    const { namedType: edgesType, isList: edgesIsList } = unwrapType(edgesField.type);
-    if (!edgesIsList || !isObjectType(edgesType))
-        return undefined;
-    // Each edge must have a 'node' field
-    const edgeFields = edgesType.getFields();
-    const nodeField = edgeFields['node'];
-    if (!nodeField)
-        return undefined;
-    const { namedType: nodeType } = unwrapType(nodeField.type);
-    if (!isObjectType(nodeType))
-        return undefined;
-    return nodeType.name;
-}
-/**
- * Classify a single GraphQL field into a Stonecrop field definition.
- *
- * Classification rules (in order):
- * 1. Scalar types → look up in merged scalar map
- * 2. Enum types → `Select` with enum values as options
- * 3. Object types that are entities → `Link` with slug as options
- * 4. Object types that are Connections → `Doctype` with node type slug as options
- * 5. List of entity type → `Doctype` with item type slug as options
- * 6. Anything else → `Data` with `_unmapped: true`
- *
- * @param fieldName - The GraphQL field name
- * @param field - The GraphQL field definition
- * @param entityTypes - Set of type names classified as entities
- * @param options - Conversion options (for custom scalars, unmapped meta, etc.)
- * @returns The Stonecrop field definition
- * @public
- */
-export function classifyFieldType(fieldName, field, entityTypes, options = {}) {
-    const { namedType, required, isList } = unwrapType(field.type);
-    const scalarMap = buildScalarMap(options.customScalars);
-    const base = {
-        kind: 'field',
-        fieldname: fieldName,
-        label: camelToLabel(fieldName),
-        component: 'ATextInput',
-    };
-    if (required) {
-        base.required = true;
-    }
-    // 1. Scalar types
-    if (isScalarType(namedType)) {
-        // Skip internal scalars (e.g., Cursor)
-        if (INTERNAL_SCALARS.has(namedType.name)) {
-            base._unmapped = true;
-            if (options.includeUnmappedMeta) {
-                base._graphqlType = namedType.name;
-            }
-            return base;
-        }
-        // Special case: ID fields that reference an entity type → Link
-        if (namedType.name === 'ID') {
-            const candidateTypeName = toPascalCase(fieldName);
-            if (entityTypes.has(candidateTypeName)) {
-                base.component = 'AFormLink';
-                base.doctype = toSlug(candidateTypeName);
-                return base;
-            }
-        }
-        const template = scalarMap[namedType.name];
-        if (template) {
-            base.component = template.component;
-        }
-        else {
-            // Unknown scalar — default to Data with unmapped marker
-            base._unmapped = true;
-            if (options.includeUnmappedMeta) {
-                base._graphqlType = namedType.name;
-            }
-        }
-        return base;
-    }
-    // 2. Enum types → Select
-    if (isEnumType(namedType)) {
-        base.component = 'ADropdown';
-        base.options = namedType.getValues().map(v => v.name);
-        return base;
-    }
-    // 3–5. Object types
-    if (isObjectType(namedType)) {
-        // 3. Direct reference to an entity type → Link
-        if (!isList && entityTypes.has(namedType.name)) {
-            base.component = 'AFormLink';
-            base.doctype = toSlug(namedType.name);
-            return base;
-        }
-        // 4. Connection type → link (child table)
-        const connectionNodeTypeName = getConnectionNodeType(namedType);
-        if (connectionNodeTypeName && entityTypes.has(connectionNodeTypeName)) {
-            base.component = 'ATable';
-            base._isLink = true;
-            base.doctype = toSlug(connectionNodeTypeName);
-            base.cardinality = 'noneOrMany';
-            return base;
-        }
-        // 5. List of entity type → link
-        if (isList && entityTypes.has(namedType.name)) {
-            base.component = 'ATable';
-            base._isLink = true;
-            base.doctype = toSlug(namedType.name);
-            base.cardinality = 'noneOrMany';
-            return base;
-        }
-        // Unknown object type — mark as unmapped
-        base._unmapped = true;
-        if (options.includeUnmappedMeta) {
-            base._graphqlType = namedType.name;
-        }
-        return base;
-    }
-    // Fallback — shouldn't normally be reached
-    base._unmapped = true;
-    if (options.includeUnmappedMeta) {
-        base._graphqlType = namedType.name;
-    }
-    return base;
-}

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

@@ -1,51 +0,0 @@
-/**
- * GraphQL Introspection to Stonecrop Schema Converter
- *
- * Converts a standard GraphQL introspection result (or SDL string) into
- * Stonecrop doctype schemas. Source-agnostic — works with any GraphQL server.
- *
- * @packageDocumentation
- */
-import type { IntrospectionSource, GraphQLConversionOptions, ConvertedGraphQLDoctype } from './types';
-/**
- * Convert a GraphQL schema to Stonecrop doctype schemas.
- *
- * Accepts either an `IntrospectionQuery` result object or an SDL string.
- * Entity types are identified using heuristics (or a custom `isEntityType` function)
- * and converted to `DoctypeMeta`-compatible JSON objects.
- *
- * @param source - GraphQL introspection result or SDL string
- * @param options - Conversion options for controlling output format and behavior
- * @returns Array of converted Stonecrop doctype definitions
- *
- * @example
- * ```typescript
- * // From introspection result (fetched from any GraphQL server)
- * const introspection = await fetchIntrospection('http://localhost:5000/graphql')
- * const doctypes = convertGraphQLSchema(introspection)
- *
- * // From SDL string
- * const sdl = fs.readFileSync('schema.graphql', 'utf-8')
- * const doctypes = convertGraphQLSchema(sdl)
- *
- * // With PostGraphile custom scalars
- * const doctypes = convertGraphQLSchema(introspection, {
- *   customScalars: {
- *     BigFloat: { component: 'ANumericInput' }
- *   }
- * })
- * ```
- *
- * @public
- */
-export declare function convertGraphQLSchema(source: IntrospectionSource, options?: GraphQLConversionOptions): ConvertedGraphQLDoctype[];
-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 { aggregateDoctypeName, buildAggregateDoctype, planGeneration } from './aggregate';
-export type { GenerationPlanEntry, GenerationPlanOptions } from './aggregate';
-export { mergeIntrospectedDoctype, formatDoctypeDrift } from './merge';
-export type { AuthoredDoctype, DoctypeDrift, MergeOptions, 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 +0,0 @@
-{"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,oBAAoB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzF,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAG7E,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AACtE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAGvF,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

@@ -1,195 +0,0 @@
-/**
- * GraphQL Introspection to Stonecrop Schema Converter
- *
- * Converts a standard GraphQL introspection result (or SDL string) into
- * Stonecrop doctype schemas. Source-agnostic — works with any GraphQL server.
- *
- * @packageDocumentation
- */
-import { buildClientSchema, buildSchema, isObjectType } from 'graphql';
-import { toSlug } from '../naming';
-import { defaultIsEntityType, defaultIsEntityField, classifyFieldType } from './heuristics';
-/**
- * Convert a GraphQL schema to Stonecrop doctype schemas.
- *
- * Accepts either an `IntrospectionQuery` result object or an SDL string.
- * Entity types are identified using heuristics (or a custom `isEntityType` function)
- * and converted to `DoctypeMeta`-compatible JSON objects.
- *
- * @param source - GraphQL introspection result or SDL string
- * @param options - Conversion options for controlling output format and behavior
- * @returns Array of converted Stonecrop doctype definitions
- *
- * @example
- * ```typescript
- * // From introspection result (fetched from any GraphQL server)
- * const introspection = await fetchIntrospection('http://localhost:5000/graphql')
- * const doctypes = convertGraphQLSchema(introspection)
- *
- * // From SDL string
- * const sdl = fs.readFileSync('schema.graphql', 'utf-8')
- * const doctypes = convertGraphQLSchema(sdl)
- *
- * // With PostGraphile custom scalars
- * const doctypes = convertGraphQLSchema(introspection, {
- *   customScalars: {
- *     BigFloat: { component: 'ANumericInput' }
- *   }
- * })
- * ```
- *
- * @public
- */
-export function convertGraphQLSchema(source, options = {}) {
-    const schema = buildGraphQLSchema(source);
-    const typeMap = schema.getTypeMap();
-    // Determine the root operation type names to exclude
-    const rootTypeNames = new Set();
-    const queryType = schema.getQueryType();
-    const mutationType = schema.getMutationType();
-    const subscriptionType = schema.getSubscriptionType();
-    if (queryType)
-        rootTypeNames.add(queryType.name);
-    if (mutationType)
-        rootTypeNames.add(mutationType.name);
-    if (subscriptionType)
-        rootTypeNames.add(subscriptionType.name);
-    // Use custom or default entity type detector
-    const isEntityType = options.isEntityType ?? defaultIsEntityType;
-    // Phase 1: Identify all entity types
-    const entityTypes = new Set();
-    for (const [typeName, type] of Object.entries(typeMap)) {
-        if (!isObjectType(type))
-            continue;
-        // Always skip root operation types (even if custom isEntityType doesn't)
-        if (rootTypeNames.has(typeName))
-            continue;
-        if (isEntityType(typeName, type)) {
-            entityTypes.add(typeName);
-        }
-    }
-    // Phase 2: Apply include/exclude filters
-    let filteredEntityTypes = entityTypes;
-    if (options.include) {
-        const includeSet = new Set(options.include);
-        filteredEntityTypes = new Set([...entityTypes].filter(t => includeSet.has(t)));
-    }
-    if (options.exclude) {
-        const excludeSet = new Set(options.exclude);
-        filteredEntityTypes = new Set([...filteredEntityTypes].filter(t => !excludeSet.has(t)));
-    }
-    // Phase 3: Convert each entity type to a doctype
-    const isEntityField = options.isEntityField ?? defaultIsEntityField;
-    const doctypes = [];
-    for (const typeName of filteredEntityTypes) {
-        const type = typeMap[typeName];
-        if (!isObjectType(type))
-            continue;
-        const fields = type.getFields();
-        // 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
-            if (options.classifyField) {
-                const custom = options.classifyField(fieldName, field, type);
-                if (custom !== null && custom !== undefined) {
-                    return {
-                        kind: 'field',
-                        fieldname: fieldName,
-                        label: custom.label ?? fieldName,
-                        component: custom.component ?? 'ATextInput',
-                        ...custom,
-                    };
-                }
-            }
-            // Default classification
-            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
-            .filter(field => {
-            if (field._isLink && field.doctype && field.cardinality) {
-                links[field.fieldname] = {
-                    target: field.doctype,
-                    cardinality: field.cardinality,
-                };
-                return false;
-            }
-            return true;
-        })
-            // 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, identity, { source: 'introspected' });
-            }
-            const { _isLink, ...rest } = field;
-            return Object.assign(rest, identity, { source: 'introspected' });
-        });
-        const doctypeName = options.doctypeNames?.[typeName] ?? typeName;
-        const doctype = {
-            name: doctypeName,
-            slug: toSlug(doctypeName),
-            fields: convertedFields,
-        };
-        if (Object.keys(links).length > 0) {
-            doctype.links = links;
-        }
-        if (options.includeUnmappedMeta) {
-            doctype._graphqlTypeName = typeName;
-        }
-        doctypes.push(doctype);
-    }
-    return doctypes;
-}
-/**
- * Build a GraphQLSchema from either an introspection result or SDL string.
- *
- * @param source - IntrospectionQuery object or SDL string
- * @returns A complete GraphQLSchema
- * @internal
- */
-function buildGraphQLSchema(source) {
-    if (typeof source === 'string') {
-        // SDL string
-        return buildSchema(source);
-    }
-    // IntrospectionQuery result
-    return buildClientSchema(source);
-}
-// ═══════════════════════════════════════════════════════════════
-// Re-exports
-// ═══════════════════════════════════════════════════════════════
-// Main converter (this file)
-export { convertGraphQLSchema as default };
-// Scalar maps
-export { GQL_SCALAR_MAP, WELL_KNOWN_SCALARS, INTERNAL_SCALARS, buildScalarMap } from './scalars';
-// Heuristics
-export { defaultIsEntityType, defaultIsEntityField, classifyFieldType } from './heuristics';
-// Aggregate — the collection-view doctype derived from an entity, emitted as its own file
-export { aggregateDoctypeName, buildAggregateDoctype, planGeneration } from './aggregate';
-// 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

@@ -1,102 +0,0 @@
-/**
- * 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 { AuthoredDoctype } from './authored';
-import type { ConvertedGraphQLDoctype } from './types';
-export type { AuthoredDoctype };
-/**
- * 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[];
-}
-/**
- * How to verify the authored doctype against the schema.
- *
- * @public
- */
-export interface MergeOptions {
-    /**
-     * The authored doctype is a curated **subset** of the schema's columns rather than a model of
-     * all of them — an aggregate being the case this exists for.
-     *
-     * This changes what counts as drift in both directions, so `generated` must be passed the
-     * *entity's* full field set, not the subset's. A column the author added to an aggregate is
-     * then confirmed against the real table (so a genuinely dropped column still reports as an
-     * orphan), while the columns deliberately left out stop reporting as omissions. Without it an
-     * aggregate reports phantom drift on every run, which both spams `--check` and buries the one
-     * finding that matters.
-     */
-    subset?: boolean;
-}
-/** 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. For a
- *   `subset` merge this is the **entity**, whose fields are the set the subset is curated from
- * @param options - see {@link MergeOptions}
- * @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, options?: MergeOptions): 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

@@ -1 +0,0 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/converter/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAEtD,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;;;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;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC3B,iFAAiF;IACjF,OAAO,EAAE,eAAe,CAAA;IACxB,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAA;CACnB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,uBAAuB,EAClC,OAAO,GAAE,YAAiB,GACxB,WAAW,CAgFb;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAYhE"}