@stonecrop/schema 0.25.0 → 0.27.0

package/dist/src/converter/aggregate.js

@@ -0,0 +1,235 @@
+/**
+ * Aggregate doctype derivation.
+ *
+ * A table gets two generated doctypes: the entity itself, whose `fields` carry every column and
+ * which backs the record form, and an **aggregate** — the collection view over the same table.
+ * The aggregate starts with identity alone, because the useful default for a collection is the
+ * one column that lets a row be opened, not all forty. Widening it is curation, and curation
+ * survives regeneration (see `mergeIntrospectedDoctype`).
+ *
+ * The two are peers: each is a complete doctype with its own `name` and `slug`, and nothing here
+ * encodes a relationship between them. Deriving the aggregate's name from the entity's is a
+ * generated encoding, not a readable one — no consumer recovers the pair by parsing a slug.
+ *
+ * @packageDocumentation
+ */
+import pluralize from 'pluralize';
+import { toSlug } from '../naming';
+import { getDoctypeSlug } from '../doctype';
+import { flattenFields, getPrimaryKeyField } from '../field';
+/**
+ * The name an entity's aggregate doctype is generated under: the entity's name, pluralised.
+ *
+ * One definition, because the CLI writes the file under `toSlug` of this and any later caller
+ * (a scaffolder, a docs generator) must land on the same name or it silently addresses a
+ * different file.
+ *
+ * `pluralize` rather than appending `s`, because the irregulars are not rare in practice —
+ * measured against a consumer's 41 hand-authored aggregate doctypes, this rule reproduces every
+ * one of their names, slugs and filenames exactly, while `+ 's'` gets five wrong
+ * (`Currencys`, `JournalEntrys`, …).
+ *
+ * The rule is not total: an already-plural name pluralises to itself. Callers must handle that —
+ * see {@link buildAggregateDoctype}.
+ *
+ * @param doctypeName - the entity doctype's `name`
+ * @returns the aggregate doctype's `name`
+ * @public
+ *
+ * @example
+ * ```typescript
+ * aggregateDoctypeName('SalesOrder') // 'SalesOrders' -> slug 'sales-orders'
+ * ```
+ */
+export function aggregateDoctypeName(doctypeName) {
+    return pluralize.plural(doctypeName);
+}
+/**
+ * Derive the aggregate doctype for a converted entity.
+ *
+ * Returns `undefined` when no identity column can be found — a natural-key table whose key the
+ * converter refuses to guess and whose author has not declared one, or a foreign PostGraphile
+ * endpoint that has left the Relay identifier occupying `id` (Stonecrop's own preset moves it to
+ * `nodeId`). That is deliberate: an aggregate with an empty `fields` array is a valid doctype that
+ * renders a table with no columns, which looks like a data problem rather than a generation one.
+ * Emitting nothing and saying so is the loud failure.
+ *
+ * Identity resolves the same way `getRecordIdField` resolves it — the declared `primaryKey`, then
+ * the conventional `id` — so an aggregate is always keyed on the column the client will later ask
+ * for. `declaredIdentity` overrides both: SDL cannot express which `UNIQUE` column is the key, so
+ * for a natural-key table the answer only exists in the authored file, and the caller that read it
+ * passes the fieldname back.
+ *
+ * @param doctype - a converted entity doctype, as returned by `convertGraphQLSchema`
+ * @param declaredIdentity - fieldname the authored doctype declares as its `primaryKey`, when the
+ *   caller has read one. Must name a field the converter emitted; the caller checks that, because
+ *   only it can say whether a missing one is a dropped column or a typo.
+ * @returns the aggregate doctype, or `undefined` when no identity column exists
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const [order] = convertGraphQLSchema(sdl, { include: ['Order'] })
+ * const aggregate = buildAggregateDoctype(order)
+ * // { name: 'Orders', slug: 'orders', fields: [ the id field ] }
+ * ```
+ */
+export function buildAggregateDoctype(doctype, declaredIdentity) {
+    const identity = findIdentityField(doctype.fields, declaredIdentity);
+    if (!identity)
+        return undefined;
+    const name = aggregateDoctypeName(doctype.name);
+    // An already-plural name pluralises to itself, which would give the aggregate the entity's own
+    // `name` *and* its filename. Both write paths are silent about it: the CLI writes the file twice
+    // in one run, and the middleware's registry is a Map keyed by name, so the later read wins in
+    // whatever order `readdirSync` returns. Refusing is the only loud option.
+    if (name === doctype.name)
+        return undefined;
+    // `primaryKey` is stamped rather than copied through: a declared identity is not marked on the
+    // converter's own field, and an aggregate whose one column carries no marker resolves identity
+    // through `getRecordIdField`'s `id` fallback — a column it does not have, so every listed row is
+    // silently dropped. Rebuilt with `source` last so the key order matches an entity's identity
+    // field and both files stay byte-stable.
+    //
+    // A copy, not a reference: the two doctypes are written to separate files and an edit to one
+    // must not reach the other.
+    const { source, ...rest } = identity;
+    return {
+        name,
+        slug: toSlug(name),
+        fields: [{ ...rest, primaryKey: true, ...(source === undefined ? {} : { source }) }],
+    };
+}
+/**
+ * The field an aggregate is keyed on: an identity the author declared, else the primary key the
+ * converter derived, else the conventional `id`.
+ *
+ * The author wins because the authored doctype is the source of truth — generation verifies it and
+ * never overwrites it (see `mergeIntrospectedDoctype`), and the divergence is already reported as
+ * identity drift.
+ *
+ * Calls `getPrimaryKeyField` for the derived half rather than restating it: a restatement drifted
+ * exactly as one does, staying top-level while the helper learned to descend into fieldsets.
+ *
+ * @internal
+ */
+function findIdentityField(fields, declared) {
+    if (declared !== undefined)
+        return fields.find(field => field.fieldname === declared);
+    return getPrimaryKeyField(fields) ?? fields.find(field => field.fieldname === 'id');
+}
+/**
+ * The doctypes in a run that get a URL of their own.
+ *
+ * A child table has no page: its rows exist inside a parent and are edited there, so a route for
+ * it is an address nothing can link to. The declaration that says so is the parent's `links` entry
+ * with a to-many cardinality — which the server derives from the foreign keys it treats as owning,
+ * so this reads what the schema states rather than guessing from a name.
+ *
+ * The rule is *listed by something, referenced by nothing*. A single reference wins over any number
+ * of listings, and the asymmetry is deliberate: a doctype that is both a parent's rows and another
+ * doctype's link target — a recipe task, say, embedded in its recipe and pointed at by four other
+ * records — needs somewhere for those links to navigate to. Denying it leaves the arrow on an
+ * `AFormLink` dead, which fails silently; granting it leaves a URL nobody visits, which does not.
+ *
+ * Scoped to one run, so a partial generation sees a partial graph and grants more routes than a
+ * whole one would. That is the safe direction, and the extra routes are deletable — an authored
+ * file's keys survive regeneration untouched.
+ *
+ * @internal
+ */
+function routableDoctypes(entities) {
+    const listed = new Set();
+    const referenced = new Set();
+    for (const entity of entities) {
+        for (const link of Object.values(entity.links ?? {})) {
+            if (link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne')
+                listed.add(link.target);
+            else
+                referenced.add(link.target);
+        }
+        // `flattenFields` rather than a top-level scan: a link inside a fieldset is still a reference,
+        // and the two ways to answer this question have already drifted apart once.
+        for (const field of flattenFields(entity.fields)) {
+            if ('doctype' in field && typeof field.doctype === 'string')
+                referenced.add(field.doctype);
+        }
+    }
+    return new Set(entities
+        .filter(entity => {
+        const slug = getDoctypeSlug(entity);
+        return referenced.has(slug) || !listed.has(slug);
+    })
+        .map(entity => entity.name));
+}
+/**
+ * Expand converted entities into the set of doctype files to write.
+ *
+ * Each table yields two: the entity, whose fields carry every column and which backs the record
+ * form, and its aggregate — the collection view. They are written as peers, one file each, with
+ * no key relating them.
+ *
+ * Separate from the CLI because the pairing of a file to its verification basis is the part that
+ * is easy to get wrong and impossible to notice: getting it wrong does not throw, it just reports
+ * drift that is not there, forever.
+ *
+ * @param entities - `convertGraphQLSchema` output
+ * @param options - see {@link GenerationPlanOptions}
+ * @returns one entry per file to write
+ * @public
+ */
+export function planGeneration(entities, options = {}) {
+    const entityNames = new Set(entities.map(entity => entity.name));
+    const claimed = new Set();
+    const routable = routableDoctypes(entities);
+    return entities.flatMap(entity => {
+        // Written out in full rather than as a segment the host assembles: the record parameter has
+        // to live somewhere, and a host given `/order` cannot know whether this doctype is the
+        // collection or the record without asking a second question. The pair shares the entity's
+        // slug, so no URL ever carries a plural.
+        const segment = `/${getDoctypeSlug(entity)}`;
+        const routed = routable.has(entity.name) ? { ...entity, route: `${segment}/:id` } : entity;
+        // `basis` is the same object as `generated` for an entity — it is verified against itself.
+        const self = { generated: routed, basis: routed, subset: false };
+        if (options.noAggregates)
+            return [self];
+        // Name collisions are checked here rather than in the builder because only this function
+        // holds the whole set. Reported before the identity check so each refusal names its own
+        // cause — the two are repaired differently.
+        const name = aggregateDoctypeName(entity.name);
+        if (name === entity.name) {
+            options.onWarning?.(`${entity.name} is already plural, so its aggregate would take the same name and the same ` +
+                `file. No aggregate was generated. Rename the doctype to its singular form, or author ` +
+                `${entity.slug}.json's collection view by hand.`);
+            return [self];
+        }
+        if (entityNames.has(name) || claimed.has(name)) {
+            options.onWarning?.(`${entity.name}'s aggregate would be named ${name}, which is already taken by another ` +
+                `doctype in this run. No aggregate was generated — one of the two needs an explicit ` +
+                `name via the doctypeNames option.`);
+            return [self];
+        }
+        // Checked here rather than in the builder because only the caller knows whether a name that
+        // matches nothing is a dropped column or a typo — and an aggregate built around a field the
+        // table has no column for renders a collection whose only column is absent from every row.
+        const declared = options.identity?.[entity.name];
+        if (declared !== undefined && !entity.fields.some(field => field.fieldname === declared)) {
+            options.onWarning?.(`${entity.name} declares its primaryKey on '${declared}', which the schema has no column for. ` +
+                `No aggregate was generated — correct the declaration in ${entity.slug}.json, or restore the ` +
+                `column to the table.`);
+            return [self];
+        }
+        const aggregate = buildAggregateDoctype(entity, declared);
+        if (!aggregate) {
+            options.onWarning?.(`${entity.name} has no derivable identity column, so no aggregate doctype was generated. ` +
+                `Declare a primaryKey on ${entity.slug}.json and re-run.`);
+            return [self];
+        }
+        claimed.add(name);
+        // The basis is the entity itself: an aggregate is verified against the table it curates from,
+        // not against its own one-field generation. Drift lines take their name from the authored file
+        // being checked, so they already name the file the reader has to edit.
+        const listed = routable.has(entity.name) ? { ...aggregate, route: segment } : aggregate;
+        return [self, { generated: listed, basis: entity, subset: true }];
+    });
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Reading an authored doctype — the JSON as it sits on disk, before any parsing.
+ *
+ * A separate reader from `@stonecrop/schema`'s `flattenFields`/`getPrimaryKeyField` because the two
+ * operate on different *shapes*, not different rules: those take parsed `DoctypeField`s and branch
+ * on the `kind` discriminant the Zod parser synthesizes, which authored JSON does not carry.
+ * `getPrimaryKeyField` on a raw file therefore returns `undefined` — indistinguishable from "no key
+ * declared", which is the exact condition its callers are testing.
+ *
+ * Every question about authored JSON is answered here once, so the rule cannot drift between the
+ * merge and the generation plan.
+ *
+ * @internal
+ */
+/**
+ * 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>;
+/** @internal */
+export declare function isAuthoredRecord(value: unknown): value is AuthoredDoctype;
+/**
+ * Flatten authored fields, descending into fieldsets.
+ *
+ * A fieldset is a layout grouping, not a scope: a field inside one is still a field of the doctype,
+ * with a column of its own and a key it may declare.
+ *
+ * @internal
+ */
+export declare function flattenAuthored(fields: readonly AuthoredDoctype[]): AuthoredDoctype[];
+/**
+ * The fieldname an authored doctype declares as its identity, or `undefined` when it declares none.
+ *
+ * Descends into fieldsets, because a nested `primaryKey` is a real declaration — ignoring one is
+ * what `getPrimaryKeyField` was fixed for.
+ *
+ * @internal
+ */
+export declare function authoredPrimaryKey(doctype: AuthoredDoctype): string | undefined;
+//# sourceMappingURL=authored.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authored.d.ts","sourceRoot":"","sources":["../../../src/converter/authored.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAErD,gBAAgB;AAChB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,eAAe,EAAE,CAUrF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAI/E"}

package/dist/src/converter/authored.js

@@ -0,0 +1,52 @@
+/**
+ * Reading an authored doctype — the JSON as it sits on disk, before any parsing.
+ *
+ * A separate reader from `@stonecrop/schema`'s `flattenFields`/`getPrimaryKeyField` because the two
+ * operate on different *shapes*, not different rules: those take parsed `DoctypeField`s and branch
+ * on the `kind` discriminant the Zod parser synthesizes, which authored JSON does not carry.
+ * `getPrimaryKeyField` on a raw file therefore returns `undefined` — indistinguishable from "no key
+ * declared", which is the exact condition its callers are testing.
+ *
+ * Every question about authored JSON is answered here once, so the rule cannot drift between the
+ * merge and the generation plan.
+ *
+ * @internal
+ */
+/** @internal */
+export function isAuthoredRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Flatten authored fields, descending into fieldsets.
+ *
+ * A fieldset is a layout grouping, not a scope: a field inside one is still a field of the doctype,
+ * with a column of its own and a key it may declare.
+ *
+ * @internal
+ */
+export function flattenAuthored(fields) {
+    const out = [];
+    for (const field of fields) {
+        if (Array.isArray(field.schema)) {
+            out.push(...flattenAuthored(field.schema.filter(isAuthoredRecord)));
+        }
+        else {
+            out.push(field);
+        }
+    }
+    return out;
+}
+/**
+ * The fieldname an authored doctype declares as its identity, or `undefined` when it declares none.
+ *
+ * Descends into fieldsets, because a nested `primaryKey` is a real declaration — ignoring one is
+ * what `getPrimaryKeyField` was fixed for.
+ *
+ * @internal
+ */
+export function authoredPrimaryKey(doctype) {
+    if (!Array.isArray(doctype.fields))
+        return undefined;
+    const declared = flattenAuthored(doctype.fields.filter(isAuthoredRecord)).find(f => f.primaryKey === true);
+    return typeof declared?.fieldname === 'string' ? declared.fieldname : undefined;
+}

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

@@ -33,11 +33,11 @@ export declare function defaultIsEntityType(typeName: string, type: GraphQLObjec
  *
  * @param fieldName - The GraphQL field name
  * @param _field - The GraphQL field definition (unused in default implementation)
- * @param _parentType - The parent entity type (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 declare function defaultIsEntityField(fieldName: string, _field: GraphQLField<unknown, unknown>, _parentType: GraphQLObjectType): boolean;
+export declare function defaultIsEntityField(fieldName: string, _field: GraphQLField<unknown, unknown>, parentType: GraphQLObjectType): boolean;
 /**
  * Classify a single GraphQL field into a Stonecrop field definition.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"heuristics.d.ts","sourceRoot":"","sources":["../../../src/converter/heuristics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAON,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGjB,MAAM,SAAS,CAAA;AAGhB,OAAO,KAAK,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AA+BnF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CA8BtF;AAQD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACtC,WAAW,EAAE,iBAAiB,GAC5B,OAAO,CAET;AAyED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,OAAO,GAAE,wBAA6B,GACpC,0BAA0B,CAkG5B"}
+{"version":3,"file":"heuristics.d.ts","sourceRoot":"","sources":["../../../src/converter/heuristics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAON,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGjB,MAAM,SAAS,CAAA;AAGhB,OAAO,KAAK,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AA+BnF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CA8BtF;AA+CD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACtC,UAAU,EAAE,iBAAiB,GAC3B,OAAO,CAGT;AAyED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,OAAO,GAAE,wBAA6B,GACpC,0BAA0B,CAkG5B"}

package/dist/src/converter/heuristics.js

@@ -81,20 +81,59 @@ export function defaultIsEntityType(typeName, type) {
 /**
  * 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
  */
-const SKIP_FIELDS = new Set(['nodeId', '__typename', 'clientMutationId']);
+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 (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) {
-    return !SKIP_FIELDS.has(fieldName);
+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.

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

@@ -43,7 +43,9 @@ 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, MergeResult } 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 +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,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"}
+{"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

@@ -187,6 +187,8 @@ export { convertGraphQLSchema as default };
 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

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

@@ -13,15 +13,9 @@
  *
  * @packageDocumentation
  */
+import type { AuthoredDoctype } from './authored';
 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>;
+export type { AuthoredDoctype };
 /**
  * What generation found that the authored doctype does not agree with. Every bucket is advisory —
  * nothing here is applied automatically.
@@ -51,6 +45,25 @@ export interface DoctypeDrift {
     /** 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. */
@@ -62,7 +75,9 @@ export interface MergeResult {
  * 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
+ * @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
@@ -74,7 +89,7 @@ export interface MergeResult {
  *
  * @public
  */
-export declare function mergeIntrospectedDoctype(authored: AuthoredDoctype, generated: ConvertedGraphQLDoctype): MergeResult;
+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.
  *

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

@@ -1 +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"}
+{"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"}

package/dist/src/converter/merge.js

@@ -14,22 +14,7 @@
  * @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);
-}
+import { authoredPrimaryKey, flattenAuthored, isAuthoredRecord } from './authored';
 function describe(value) {
     return value === undefined ? '—' : JSON.stringify(value);
 }
@@ -37,7 +22,9 @@ function describe(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
+ * @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
@@ -49,8 +36,8 @@ function describe(value) {
  *
  * @public
  */
-export function mergeIntrospectedDoctype(authored, generated) {
-    const authoredFields = Array.isArray(authored.fields) ? authored.fields.filter(isRecord) : [];
+export function mergeIntrospectedDoctype(authored, generated, options = {}) {
+    const authoredFields = Array.isArray(authored.fields) ? authored.fields.filter(isAuthoredRecord) : [];
     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 ?? {}));
@@ -67,7 +54,7 @@ export function mergeIntrospectedDoctype(authored, generated) {
     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) };
+            return { ...field, schema: field.schema.filter(isAuthoredRecord).map(tag) };
         }
         const name = typeof field.fieldname === 'string' ? field.fieldname : '';
         const match = generatedByName.get(name);
@@ -101,18 +88,22 @@ export function mergeIntrospectedDoctype(authored, generated) {
         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));
+    // A curated subset omits columns by definition, so the bucket that reports omissions has
+    // nothing true to say about one.
+    if (!options.subset) {
+        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 authoredPk = authoredPrimaryKey(authored);
     const generatedPk = generated.fields.find(f => f.primaryKey === true);
-    if (authoredPk && generatedPk && authoredPk.fieldname !== generatedPk.fieldname) {
+    if (authoredPk && generatedPk && authoredPk !== generatedPk.fieldname) {
         drift.mode = 'partial';
-        drift.reason = `authored primary key '${String(authoredPk.fieldname)}' is not the derivable '${generatedPk.fieldname}' — left as authored`;
+        drift.reason = `authored primary key '${authoredPk}' 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`;
+        drift.reason = `authored primary key '${authoredPk}' is not derivable from the schema — left as authored`;
     }
     else if (!authoredPk && generatedPk) {
         drift.mode = 'partial';