@stonecrop/schema 0.24.0 → 0.26.0

package/dist/schema.d.ts

@@ -23,6 +23,46 @@ export declare const ActionDefinition: z.ZodObject<{
  */
 export declare type ActionDefinition = z.infer<typeof ActionDefinition>;
 
+/**
+ * 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 declare function aggregateDoctypeName(doctypeName: string): string;
+
+/**
+ * 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
@@ -70,6 +110,38 @@ export declare interface BadgeSpecObject {
  */
 export declare type BadgeVariant = 'neutral' | 'success' | 'warning' | 'danger' | 'brand';
 
+/**
+ * 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 declare function buildAggregateDoctype(doctype: ConvertedGraphQLDoctype, declaredIdentity?: string): ConvertedGraphQLDoctype | undefined;
+
 /**
  * Build a merged scalar map from the built-in maps and user-provided custom scalars.
  * Precedence (highest to lowest): customScalars → GQL_SCALAR_MAP → WELL_KNOWN_SCALARS
@@ -479,11 +551,11 @@ export declare interface DataClient<T extends DoctypeRef = DoctypeRef, M = Docty
  *
  * @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;
 
 /**
  * Default heuristic to determine if a GraphQL object type represents an entity.
@@ -568,6 +640,7 @@ export declare const DoctypeMeta: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     displayField: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodString>;
     fields: z.ZodArray<z.ZodType<DoctypeField, unknown, z.core.$ZodTypeInternals<DoctypeField, unknown>>>;
     links: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         target: z.ZodString;
@@ -792,6 +865,45 @@ export declare function flattenFields(fields: readonly DoctypeField[]): (ValueFi
  */
 export declare function formatDoctypeDrift(drift: DoctypeDrift): string[];
 
+/**
+ * One file the generator will write, and what that file is verified against.
+ *
+ * `basis` exists because the two are not always the same document. An aggregate is written from
+ * its own one-field generation but verified against the **entity**, since its purpose is to carry
+ * fewer columns than the table — checking it against itself reports every curated column as one
+ * the table had dropped.
+ *
+ * @public
+ */
+export declare interface GenerationPlanEntry {
+    /** The doctype to write. */
+    generated: ConvertedGraphQLDoctype;
+    /** The doctype whose fields an existing file on disk is verified against. */
+    basis: ConvertedGraphQLDoctype;
+    /** Whether the file is a curated subset of `basis` — passed through to `MergeOptions.subset`. */
+    subset: boolean;
+}
+
+/** Options for {@link planGeneration}. @public */
+export declare interface GenerationPlanOptions {
+    /** Emit only the entity doctypes, skipping their aggregates. Defaults to `false`. */
+    noAggregates?: boolean;
+    /** Called with an advisory message for each entity that yields no aggregate. */
+    onWarning?: (message: string) => void;
+    /**
+     * Identity the authored doctype on disk declares, keyed by doctype `name`.
+     *
+     * SDL cannot say which `UNIQUE` column is a table's key, so for a natural-key table the converter
+     * derives nothing and the answer exists only in the file. Without this the aggregate is
+     * unreachable: generation says "declare a primaryKey and re-run", and re-running after declaring
+     * one changes nothing, because planning never reads the file.
+     *
+     * Passed in rather than read here so this stays a pure function of its inputs; the CLI owns the
+     * IO. The plan is then a function of the schema *and* what is already on disk.
+     */
+    identity?: Record<string, string>;
+}
+
 /**
  * Resolve the field a doctype nominates as its display text, or `undefined` when the nomination
  * does not name a readable column.
@@ -813,6 +925,44 @@ export declare function formatDoctypeDrift(drift: DoctypeDrift): string[];
  */
 export declare function getDisplayField(fields: readonly DoctypeField[], displayField: string | undefined): ValueField | undefined;
 
+/**
+ * The one string a doctype is addressed by.
+ *
+ * A doctype carries two names — `name` (`OrderItem`) and `slug` (`order-item`) — and every registry
+ * must agree on which one keys it. Three implementations had drifted apart: the adapter's registry is
+ * keyed by `name` and its `getMeta` also scans for a matching `slug`, so it accepts **either**; the
+ * client's registry is keyed by a slug it derives itself and accepts **only** that; and
+ * `Doctype.fromObject` dropped an authored `slug` on the floor and re-derived one regardless. The
+ * adapter's accepted set was therefore a strict superset of the client's, and a link target written
+ * as the Name booted the server, passed its reference check, served rows over GraphQL, and was
+ * silently dropped by the client — an expanding child table rendering as one empty text input, with
+ * nothing logged.
+ *
+ * Resolving through this in both runtimes is what makes the two answers the same answer. It is the
+ * derivation only; a *lookup* still belongs to whichever registry owns the corpus, because the two
+ * corpora legitimately differ (a client registers lazily, and a client-only host has no adapter at
+ * all).
+ *
+ * An authored `slug` wins over the derived one because the authored doctype is the source of truth:
+ * generation verifies a file and never overwrites it, so a doctype that states its own slug means it.
+ * Deriving unconditionally is what `fromObject` did, and it made an authored `slug` a silent no-op on
+ * one side of the wire while the other honoured it.
+ *
+ * @param doctype - anything carrying a doctype's `name` and optional authored `slug`
+ * @returns the canonical slug
+ * @public
+ *
+ * @example
+ * ```typescript
+ * getDoctypeSlug({ name: 'OrderItem' })                      // 'order-item'
+ * getDoctypeSlug({ name: 'Planner', slug: 'planner-board' }) // 'planner-board'
+ * ```
+ */
+export declare function getDoctypeSlug(doctype: {
+    name: string;
+    slug?: string;
+}): string;
+
 /**
  * Find the field a doctype marks as its primary key, or `undefined` when none is marked.
  *
@@ -821,15 +971,19 @@ export declare function getDisplayField(fields: readonly DoctypeField[], display
  * 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. Identity is single-valued by design — a doctype describes the API
- *   surface, and mapping a composite database key onto one identity there is the adapter's job —
- *   so a doctype declaring several is malformed rather than composite. `DoctypeMeta` rejects that
- *   at the load gate; this stays total for callers holding fields that never went through it.
- *
- * @param fields - the doctype's top-level fields
+ * Two deliberate rules, both matching the shape `primaryKey` actually has:
+ * - Fieldset children are **included**, via {@link flattenFields}. A fieldset is layout, not
+ *   scope: its children are fields of the doctype with columns of their own, which is why the
+ *   adapter's SELECT already descends and why `getDisplayField` does too. Scanning top level only
+ *   did not *refuse* a nested declaration — it ignored one, so an author marked identity and
+ *   nothing honoured it and nothing said so.
+ * - The **first** match in document order wins. Identity is single-valued by design — a doctype
+ *   describes the API surface, and mapping a composite database key onto one identity there is the
+ *   adapter's job — so a doctype declaring several is malformed rather than composite.
+ *   `DoctypeMeta` rejects that at the load gate; this stays total for callers holding fields that
+ *   never went through it.
+ *
+ * @param fields - the doctype's fields; fieldset children are descended into
  * @returns the primary-key field, or `undefined` for a PK-less doctype
  * @public
  */
@@ -1072,6 +1226,30 @@ export declare interface GraphQLConversionOptions {
  */
 export declare function hasBadgeOptions(options: FieldOptions | undefined): boolean;
 
+/**
+ * Which of the three field shapes an entry has, read from the entry's own structure.
+ *
+ * The single definition of that question. It had three copies before this — the parser's
+ * `injectKind`, {@link stripFieldKind}'s agreement check, and the docbuilder's own
+ * `isValueField` in another package — each free to drift, and drift here re-types a field rather
+ * than throwing: a value field read as a fieldset loses its column, a fieldset read as a value
+ * field loses every child.
+ *
+ * Deliberately **shape-only**: a declared `kind` is ignored. Two callers depend on that. The
+ * stripper compares this against the declaration to decide whether removing it is lossless, which
+ * it cannot do if this honours it. The docbuilder reads raw JSON off disk and classifies entries to
+ * decide which to render as editable rows — and `kind` is Stonecrop's own discriminant, not
+ * something a doctype author writes, so a tool reading a file has no business consulting it.
+ *
+ * `injectKind` is the one place a declaration still wins, and only to leave an already-parsed
+ * object untouched on its way back through.
+ *
+ * @param field - a field entry, authored or parsed
+ * @returns the kind its shape implies
+ * @public
+ */
+export declare function inferFieldKind(field: unknown): DoctypeField['kind'];
+
 /**
  * Controls the level of user interaction for a field, container, or table.
  *
@@ -1261,7 +1439,9 @@ export declare function lookupBadge(options: FieldOptions | undefined, key: stri
  * 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
@@ -1273,7 +1453,27 @@ export declare function lookupBadge(options: FieldOptions | undefined, key: stri
  *
  * @public
  */
-export declare function mergeIntrospectedDoctype(authored: AuthoredDoctype, generated: ConvertedGraphQLDoctype): MergeResult;
+export declare function mergeIntrospectedDoctype(authored: AuthoredDoctype, generated: ConvertedGraphQLDoctype, options?: MergeOptions): MergeResult;
+
+/**
+ * How to verify the authored doctype against the schema.
+ *
+ * @public
+ */
+export declare 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 declare interface MergeResult {
@@ -1331,6 +1531,24 @@ export declare function parseField(data: unknown): DoctypeField;
  */
 export declare function pascalToSnake(pascal: string): string;
 
+/**
+ * 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 declare function planGeneration(entities: readonly ConvertedGraphQLDoctype[], options?: GenerationPlanOptions): GenerationPlanEntry[];
+
 /**
  * Decide how a *declared* link (one with a `LinkDeclaration`) renders.
  *
@@ -1400,6 +1618,28 @@ export declare function snakeToCamel(snakeCase: string): string;
  */
 export declare function snakeToLabel(snakeCase: string): string;
 
+/**
+ * Remove the `kind` discriminant from a field, recursing into a fieldset's children.
+ *
+ * The outbound half of the boundary {@link normalizeFieldKind} owns inbound. `kind` is a
+ * discriminated-union tag the parser synthesizes, not something an author writes, so nothing that
+ * *writes* a doctype should put it on disk — the generator and the docbuilder's save both call
+ * this. Without it the two round-trip asymmetrically: every save adds a key the file never had.
+ *
+ * Strips only when `injectKind` would restore exactly what was removed. A fieldset carrying no
+ * `schema` re-infers as a plain field, so its `kind` is kept rather than silently re-typing the
+ * document; `DoctypeMeta` requires `schema` on a fieldset, so that shape is already invalid and
+ * belongs to the load gate, not here.
+ *
+ * Table `columns` are {@link ColumnSchema} entries rather than `DoctypeField`s and never carry an
+ * injected `kind`, so they are passed through untouched — the same asymmetry `injectKind` has.
+ *
+ * @param field - a field object, as held in memory after parsing
+ * @returns the field without `kind`, safe to serialize
+ * @public
+ */
+export declare function stripFieldKind(field: unknown): unknown;
+
 /**
  * Sync fetch strategy - data is fetched in the initial query.
  * @public

package/dist/src/cli.js

@@ -16,7 +16,9 @@ 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, formatDoctypeDrift, mergeIntrospectedDoctype } from './converter/index';
+import { authoredPrimaryKey } from './converter/authored';
+import { convertGraphQLSchema, formatDoctypeDrift, mergeIntrospectedDoctype, planGeneration } from './converter/index';
+import { stripFieldKind } from './field';
 import { validateDoctype } from './validation';
 /**
  * Fetch an introspection result from a live GraphQL endpoint.
@@ -61,6 +63,7 @@ async function main() {
             names: { type: 'string' },
             'custom-scalars': { type: 'string' },
             'include-unmapped': { type: 'boolean', default: false },
+            'no-aggregates': { type: 'boolean', default: false },
             check: { type: 'boolean', default: false },
             help: { type: 'boolean', short: 'h' },
         },
@@ -124,11 +127,33 @@ async function main() {
         source = readFileSync(filePath, 'utf-8');
     }
     // Convert
-    const doctypes = convertGraphQLSchema(source, options);
-    if (doctypes.length === 0) {
+    const entities = convertGraphQLSchema(source, options);
+    if (entities.length === 0) {
         console.warn('No entity types found in the schema. Check your include/exclude filters.');
         process.exit(0);
     }
+    // Read the identity each authored doctype declares, before planning rather than during the write
+    // loop below. SDL cannot express which UNIQUE column is a table's key, so for a natural-key
+    // doctype the declaration in the file is the only answer that exists — and planning is what
+    // decides whether the aggregate can be built at all. Reading it 20 lines later, as the loop
+    // does, made the "declare a primaryKey and re-run" warning a dead end: re-running after
+    // declaring one changed nothing.
+    const identity = {};
+    for (const entity of entities) {
+        const entityPath = join(outputDir, `${entity.slug}.json`);
+        if (!existsSync(entityPath))
+            continue;
+        const declared = authoredPrimaryKey(JSON.parse(readFileSync(entityPath, 'utf-8')));
+        if (declared !== undefined)
+            identity[entity.name] = declared;
+    }
+    // Each table yields two doctypes — the entity and its aggregate — written as peers, one file
+    // each, along with what each is verified against. See `planGeneration`.
+    const doctypes = planGeneration(entities, {
+        noAggregates: values['no-aggregates'],
+        identity,
+        onWarning: message => console.warn(`  WARN: ${message}`),
+    });
     // Write output
     if (!existsSync(outputDir)) {
         mkdirSync(outputDir, { recursive: true });
@@ -137,7 +162,7 @@ async function main() {
     let errors = 0;
     let changed = 0;
     const driftLines = [];
-    for (const generated of doctypes) {
+    for (const { generated, basis, subset } of doctypes) {
         const fileName = `${generated.slug}.json`;
         const filePath = join(outputDir, fileName);
         // When a doctype already exists it is the source of truth: generation confirms it and adds
@@ -148,14 +173,25 @@ async function main() {
         // so converter output is written verbatim.
         let output = generated;
         if (existsSync(filePath)) {
-            const { doctype: merged, drift } = mergeIntrospectedDoctype(JSON.parse(readFileSync(filePath, 'utf-8')), generated);
+            const { doctype: merged, drift } = mergeIntrospectedDoctype(JSON.parse(readFileSync(filePath, 'utf-8')), basis, {
+                subset,
+            });
             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';
+        //
+        // `kind` is dropped on the way out because it is the discriminated-union tag the parser
+        // synthesizes, not authored data — `injectKind` puts it back on every read. Writing it made
+        // the generator and the docbuilder disagree with hand-authored files about what a doctype
+        // looks like, and re-added the key on every regeneration.
+        const serializable = { ...output };
+        if (Array.isArray(serializable.fields)) {
+            serializable.fields = serializable.fields.map(stripFieldKind);
+        }
+        const json = JSON.stringify(serializable, null, '\t') + '\n';
         const unchanged = existsSync(filePath) && readFileSync(filePath, 'utf-8') === json;
         if (!unchanged)
             changed++;
@@ -216,9 +252,20 @@ OPTIONS:
   --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
+  --no-aggregates              Emit only the entity doctype, not its aggregate
   --check                      Report drift and exit non-zero if anything would change; write nothing
   --help, -h                   Show this help message
 
+Each table generates TWO doctypes: the entity (every column, backs the record form) and its
+aggregate (the collection view, identity column only by default), named as simple plurals —
+'task.json' and 'tasks.json'. Widen an aggregate by adding fields to it — curation survives
+regeneration. A doctype whose name is already plural gets no aggregate, because it would claim
+its own name and its own file; the run says so and still writes the entity.
+
+An aggregate needs an identity column. A table keyed on 'id' gives one up; for a natural key,
+declare 'primaryKey' on the field in the entity's own file and re-run — the aggregate is keyed
+on whatever that file declares.
+
 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.

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

@@ -0,0 +1,127 @@
+/**
+ * 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 type { ConvertedGraphQLDoctype } from './types';
+/**
+ * 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 declare function aggregateDoctypeName(doctypeName: string): string;
+/**
+ * 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 declare function buildAggregateDoctype(doctype: ConvertedGraphQLDoctype, declaredIdentity?: string): ConvertedGraphQLDoctype | undefined;
+/**
+ * One file the generator will write, and what that file is verified against.
+ *
+ * `basis` exists because the two are not always the same document. An aggregate is written from
+ * its own one-field generation but verified against the **entity**, since its purpose is to carry
+ * fewer columns than the table — checking it against itself reports every curated column as one
+ * the table had dropped.
+ *
+ * @public
+ */
+export interface GenerationPlanEntry {
+    /** The doctype to write. */
+    generated: ConvertedGraphQLDoctype;
+    /** The doctype whose fields an existing file on disk is verified against. */
+    basis: ConvertedGraphQLDoctype;
+    /** Whether the file is a curated subset of `basis` — passed through to `MergeOptions.subset`. */
+    subset: boolean;
+}
+/** Options for {@link planGeneration}. @public */
+export interface GenerationPlanOptions {
+    /** Emit only the entity doctypes, skipping their aggregates. Defaults to `false`. */
+    noAggregates?: boolean;
+    /** Called with an advisory message for each entity that yields no aggregate. */
+    onWarning?: (message: string) => void;
+    /**
+     * Identity the authored doctype on disk declares, keyed by doctype `name`.
+     *
+     * SDL cannot say which `UNIQUE` column is a table's key, so for a natural-key table the converter
+     * derives nothing and the answer exists only in the file. Without this the aggregate is
+     * unreachable: generation says "declare a primaryKey and re-run", and re-running after declaring
+     * one changes nothing, because planning never reads the file.
+     *
+     * Passed in rather than read here so this stays a pure function of its inputs; the CLI owns the
+     * IO. The plan is then a function of the schema *and* what is already on disk.
+     */
+    identity?: Record<string, string>;
+}
+/**
+ * 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 declare function planGeneration(entities: readonly ConvertedGraphQLDoctype[], options?: GenerationPlanOptions): GenerationPlanEntry[];
+//# sourceMappingURL=aggregate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../../src/converter/aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,uBAAuB,EAChC,gBAAgB,CAAC,EAAE,MAAM,GACvB,uBAAuB,GAAG,SAAS,CAyBrC;AAkED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IACnC,4BAA4B;IAC5B,SAAS,EAAE,uBAAuB,CAAA;IAClC,6EAA6E;IAC7E,KAAK,EAAE,uBAAuB,CAAA;IAC9B,iGAAiG;IACjG,MAAM,EAAE,OAAO,CAAA;CACf;AAED,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACrC,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,gFAAgF;IAChF,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,OAAO,GAAE,qBAA0B,GACjC,mBAAmB,EAAE,CAmEvB"}