@auto-engineer/narrative 0.11.11

package/src/transformers/model-to-narrative/generators/gwt.ts

@@ -0,0 +1,335 @@
+import tsNS from 'typescript';
+import { jsonToExpr, type FieldTypeInfo } from '../ast/emit-helpers';
+
+/**
+ * Build a single specs() block for a GWT entry, adapting to slice type:
+ * - command: when(Command).then([Events|Error])
+ * - react:   when([Events]).then([Commands])
+ * - query:   given([Events]).then([State])
+ */
+
+function isWhenCommand(x: unknown): x is { commandRef: string; exampleData: Record<string, unknown> } {
+  return x !== null && x !== undefined && typeof x === 'object' && 'commandRef' in (x as Record<string, unknown>);
+}
+function isWhenEvents(x: unknown): x is Array<{ eventRef: string; exampleData: Record<string, unknown> }> {
+  return Array.isArray(x);
+}
+function hasGivenEvents(x: unknown): x is { given: Array<{ eventRef: string; exampleData: Record<string, unknown> }> } {
+  return x !== null && x !== undefined && typeof x === 'object' && Array.isArray((x as Record<string, unknown>).given);
+}
+
+export type GWTBlock = {
+  given?: Array<{ eventRef: string; exampleData: Record<string, unknown> }>;
+  when?:
+    | { commandRef: string; exampleData: Record<string, unknown> }
+    | { eventRef: string; exampleData: Record<string, unknown> }
+    | Array<
+        | { commandRef: string; exampleData: Record<string, unknown> }
+        | { eventRef: string; exampleData: Record<string, unknown> }
+      >;
+  then: Array<
+    | { eventRef: string; exampleData: Record<string, unknown> }
+    | { commandRef: string; exampleData: Record<string, unknown> }
+    | { stateRef: string; exampleData: Record<string, unknown> }
+    | { errorType: 'IllegalStateError' | 'ValidationError' | 'NotFoundError'; message?: string }
+  >;
+};
+
+function buildThenItems(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  g: GWTBlock,
+  messages?: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+): tsNS.Expression[] {
+  return g.then.map((t) => {
+    const item = t as Record<string, unknown>;
+
+    // Handle event references: just return the data (type handled by generic parameter)
+    if ('eventRef' in item) {
+      const e = t as { eventRef: string; exampleData: Record<string, unknown> };
+      const typeInfo = messages ? getFieldTypeInfo(messages, e.eventRef) : undefined;
+      return jsonToExpr(ts, f, e.exampleData, typeInfo);
+    }
+
+    // Handle command references: just return the data (type handled by generic parameter)
+    if ('commandRef' in item) {
+      const c = t as { commandRef: string; exampleData: Record<string, unknown> };
+      const typeInfo = messages ? getFieldTypeInfo(messages, c.commandRef) : undefined;
+      return jsonToExpr(ts, f, c.exampleData, typeInfo);
+    }
+
+    // Handle state references: just return the data (type handled by generic parameter)
+    if ('stateRef' in item) {
+      const s = t as { stateRef: string; exampleData: Record<string, unknown> };
+      const typeInfo = messages ? getFieldTypeInfo(messages, s.stateRef) : undefined;
+      return jsonToExpr(ts, f, s.exampleData, typeInfo);
+    }
+
+    // Handle error objects: { errorType: 'ValidationError', message: '...' }
+    if ('errorType' in item) {
+      const err = t as { errorType: 'IllegalStateError' | 'ValidationError' | 'NotFoundError'; message?: string };
+      return f.createObjectLiteralExpression(
+        [
+          f.createPropertyAssignment('errorType', f.createStringLiteral(err.errorType)),
+          ...(err.message !== null && err.message !== undefined
+            ? [f.createPropertyAssignment('message', f.createStringLiteral(err.message))]
+            : []),
+        ],
+        false,
+      );
+    }
+
+    return f.createNull();
+  });
+}
+
+function getDescriptions(
+  g: GWTBlock & { description?: string; ruleDescription?: string; exampleDescription?: string },
+) {
+  const ruleDesc =
+    g.ruleDescription !== null && g.ruleDescription !== undefined && g.ruleDescription !== ''
+      ? g.ruleDescription
+      : 'Generated rule description';
+
+  const exampleDesc =
+    g.exampleDescription !== null && g.exampleDescription !== undefined && g.exampleDescription !== ''
+      ? g.exampleDescription
+      : g.description !== null && g.description !== undefined && g.description !== ''
+        ? g.description
+        : 'Generated example description';
+
+  return { ruleDesc, exampleDesc };
+}
+
+function addGivenToChain(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  exampleChain: tsNS.Expression,
+  g: GWTBlock,
+  messages?: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+): tsNS.Expression {
+  if (hasGivenEvents(g) && g.given !== null && g.given !== undefined && g.given.length > 0) {
+    // Start with the first given
+    const firstGiven = g.given[0];
+    const firstTypeInfo = messages ? getFieldTypeInfo(messages, firstGiven.eventRef) : undefined;
+    let currentChain = f.createCallExpression(
+      f.createPropertyAccessExpression(exampleChain, 'given'),
+      [f.createTypeReferenceNode(firstGiven.eventRef, undefined)],
+      [jsonToExpr(ts, f, firstGiven.exampleData, firstTypeInfo)],
+    );
+
+    // Chain additional givens with .and()
+    for (let i = 1; i < g.given.length; i++) {
+      const givenEvent = g.given[i];
+      const typeInfo = messages ? getFieldTypeInfo(messages, givenEvent.eventRef) : undefined;
+      currentChain = f.createCallExpression(
+        f.createPropertyAccessExpression(currentChain, 'and'),
+        [f.createTypeReferenceNode(givenEvent.eventRef, undefined)],
+        [jsonToExpr(ts, f, givenEvent.exampleData, typeInfo)],
+      );
+    }
+
+    return currentChain;
+  }
+  return exampleChain;
+}
+
+function addCommandWhenToChain(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  exampleChain: tsNS.Expression,
+  when: { commandRef: string; exampleData: Record<string, unknown> },
+  messages?: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+): tsNS.Expression {
+  const typeInfo = messages ? getFieldTypeInfo(messages, when.commandRef) : undefined;
+  return f.createCallExpression(
+    f.createPropertyAccessExpression(exampleChain, 'when'),
+    when.commandRef ? [f.createTypeReferenceNode(when.commandRef, undefined)] : undefined,
+    [jsonToExpr(ts, f, when.exampleData, typeInfo)],
+  );
+}
+
+function addEventWhenToChain(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  exampleChain: tsNS.Expression,
+  firstEvent: { eventRef: string; exampleData: Record<string, unknown> },
+  messages?: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+): tsNS.Expression {
+  const typeInfo = messages ? getFieldTypeInfo(messages, firstEvent.eventRef) : undefined;
+  return f.createCallExpression(
+    f.createPropertyAccessExpression(exampleChain, 'when'),
+    firstEvent.eventRef ? [f.createTypeReferenceNode(firstEvent.eventRef, undefined)] : undefined,
+    [jsonToExpr(ts, f, firstEvent.exampleData, typeInfo)],
+  );
+}
+
+function addWhenToChain(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  exampleChain: tsNS.Expression,
+  g: GWTBlock,
+  sliceKind: 'command' | 'react' | 'query' | 'experience',
+  messages?: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+): tsNS.Expression {
+  if (sliceKind === 'command' && isWhenCommand(g.when)) {
+    return addCommandWhenToChain(ts, f, exampleChain, g.when, messages);
+  } else if ((sliceKind === 'react' || sliceKind === 'query') && isWhenEvents(g.when)) {
+    const firstWhenEvent = g.when[0];
+    return addEventWhenToChain(ts, f, exampleChain, firstWhenEvent, messages);
+  } else if (sliceKind === 'query' && g.when && !Array.isArray(g.when) && 'eventRef' in g.when) {
+    const whenEvent = g.when as { eventRef: string; exampleData: Record<string, unknown> };
+    return addEventWhenToChain(ts, f, exampleChain, whenEvent, messages);
+  }
+  return exampleChain;
+}
+
+function getThenTypeRef(firstThenItem: GWTBlock['then'][0]): string {
+  if ('eventRef' in firstThenItem) {
+    return (firstThenItem as { eventRef: string }).eventRef;
+  } else if ('commandRef' in firstThenItem) {
+    return (firstThenItem as { commandRef: string }).commandRef;
+  } else if ('stateRef' in firstThenItem) {
+    return (firstThenItem as { stateRef: string }).stateRef;
+  }
+  return '';
+}
+
+function addThenToChain(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  exampleChain: tsNS.Expression,
+  g: GWTBlock,
+  messages?: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+): tsNS.Expression {
+  const thenItems = buildThenItems(ts, f, g, messages);
+  const firstThenItem = g.then[0];
+  const thenTypeRef = getThenTypeRef(firstThenItem);
+
+  // Always use single object format for .then()
+  const thenArg = thenItems[0];
+  const thenTypeParams = thenTypeRef ? [f.createTypeReferenceNode(thenTypeRef, undefined)] : undefined;
+
+  return f.createCallExpression(f.createPropertyAccessExpression(exampleChain, 'then'), thenTypeParams, [thenArg]);
+}
+
+export function buildGwtSpecBlock(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  g: GWTBlock & { description?: string; ruleDescription?: string; exampleDescription?: string; ruleId?: string },
+  sliceKind: 'command' | 'react' | 'query' | 'experience',
+): tsNS.Statement {
+  const { ruleDesc, exampleDesc } = getDescriptions(g);
+
+  // Build the example chain: example('desc').given().when().then()
+  let exampleChain: tsNS.Expression = f.createCallExpression(f.createIdentifier('example'), undefined, [
+    f.createStringLiteral(exampleDesc),
+  ]);
+
+  // Add .given() if present
+  exampleChain = addGivenToChain(ts, f, exampleChain, g);
+
+  // Add .when()
+  exampleChain = addWhenToChain(ts, f, exampleChain, g, sliceKind);
+
+  // Add .then()
+  exampleChain = addThenToChain(ts, f, exampleChain, g);
+
+  // Create the rule() call containing the example
+  const ruleArgs: tsNS.Expression[] = [f.createStringLiteral(ruleDesc)];
+
+  // Add rule ID if provided
+  if (g.ruleId !== null && g.ruleId !== undefined) {
+    ruleArgs.push(f.createStringLiteral(g.ruleId));
+  }
+
+  ruleArgs.push(
+    f.createArrowFunction(
+      undefined,
+      undefined,
+      [],
+      undefined,
+      f.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+      f.createBlock([f.createExpressionStatement(exampleChain)], true),
+    ),
+  );
+
+  const ruleCall = f.createCallExpression(f.createIdentifier('rule'), undefined, ruleArgs);
+  return f.createExpressionStatement(ruleCall);
+}
+
+/**
+ * Build a rule() call that contains multiple examples
+ */
+/**
+ * Extract field type information from messages for a specific type
+ */
+function getFieldTypeInfo(
+  messages: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+  typeName: string,
+): FieldTypeInfo {
+  const message = messages.find((msg) => msg.name === typeName);
+  if (!message) return {};
+
+  const typeInfo: FieldTypeInfo = {};
+  for (const field of message.fields) {
+    typeInfo[field.name] = field.type;
+  }
+  return typeInfo;
+}
+
+export function buildConsolidatedGwtSpecBlock(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  rule: { id?: string; description: string },
+  gwtBlocks: Array<
+    GWTBlock & { description?: string; ruleDescription?: string; exampleDescription?: string; ruleId?: string }
+  >,
+  sliceKind: 'command' | 'react' | 'query' | 'experience',
+  messages?: Array<{ type: string; name: string; fields: Array<{ name: string; type: string; required: boolean }> }>,
+): tsNS.Statement {
+  // Build example chains for each GWT block
+  const exampleStatements: tsNS.Statement[] = [];
+
+  for (const g of gwtBlocks) {
+    const { exampleDesc } = getDescriptions(g);
+
+    // Build the example chain: example('desc').given().when().then()
+    let exampleChain: tsNS.Expression = f.createCallExpression(f.createIdentifier('example'), undefined, [
+      f.createStringLiteral(exampleDesc),
+    ]);
+
+    // Add .given() if present
+    exampleChain = addGivenToChain(ts, f, exampleChain, g, messages);
+
+    // Add .when()
+    exampleChain = addWhenToChain(ts, f, exampleChain, g, sliceKind, messages);
+
+    // Add .then()
+    exampleChain = addThenToChain(ts, f, exampleChain, g, messages);
+
+    exampleStatements.push(f.createExpressionStatement(exampleChain));
+  }
+
+  // Create the rule() call containing all examples
+  const ruleArgs: tsNS.Expression[] = [f.createStringLiteral(rule.description)];
+
+  // Add rule ID if provided
+  if (rule.id !== null && rule.id !== undefined) {
+    ruleArgs.push(f.createStringLiteral(rule.id));
+  }
+
+  ruleArgs.push(
+    f.createArrowFunction(
+      undefined,
+      undefined,
+      [],
+      undefined,
+      f.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+      f.createBlock(exampleStatements, true),
+    ),
+  );
+
+  const ruleCall = f.createCallExpression(f.createIdentifier('rule'), undefined, ruleArgs);
+  return f.createExpressionStatement(ruleCall);
+}

package/src/transformers/model-to-narrative/generators/imports.ts

@@ -0,0 +1,110 @@
+type BuildImportsOpts = { flowImport: string; integrationImport: string };
+
+export const ALL_FLOW_FUNCTION_NAMES = [
+  'command',
+  'query',
+  'react',
+  'experience',
+  'narrative',
+  'should',
+  'specs',
+  'rule',
+  'example',
+  'gql',
+  'source',
+  'data',
+  'sink',
+] as const;
+
+export function buildImports(
+  ts: typeof import('typescript'),
+  opts: BuildImportsOpts,
+  messages: Array<{ type: string; name: string }>,
+  typeIntegrationNames: string[],
+  valueIntegrationNames: string[] = [],
+  usedFlowFunctionNames: string[] = [],
+) {
+  const f = ts.factory;
+
+  const flowValueNames = usedFlowFunctionNames.length > 0 ? [...usedFlowFunctionNames].sort() : [];
+
+  // Determine which flow types are actually needed based on the messages
+  const usedMessageTypes = new Set(messages.map((msg) => msg.type));
+  const typeMapping: Record<string, string> = {
+    command: 'Command',
+    event: 'Event',
+    state: 'State',
+  };
+
+  const flowTypeNames = Array.from(usedMessageTypes)
+    .map((type) => typeMapping[type])
+    .filter(Boolean)
+    .sort();
+
+  const importFlowValues =
+    flowValueNames.length > 0
+      ? f.createImportDeclaration(
+          undefined,
+          f.createImportClause(
+            false,
+            undefined,
+            f.createNamedImports([
+              ...flowValueNames.map((n) => f.createImportSpecifier(false, undefined, f.createIdentifier(n))),
+            ]),
+          ),
+          f.createStringLiteral(opts.flowImport),
+        )
+      : null;
+
+  const importFlowTypes =
+    flowTypeNames.length > 0
+      ? f.createImportDeclaration(
+          undefined,
+          f.createImportClause(
+            true,
+            undefined,
+            f.createNamedImports([
+              ...flowTypeNames.map((n) => f.createImportSpecifier(false, undefined, f.createIdentifier(n))),
+            ]),
+          ),
+          f.createStringLiteral(opts.flowImport),
+        )
+      : null;
+
+  const importIntegrationValues =
+    valueIntegrationNames.length > 0
+      ? f.createImportDeclaration(
+          undefined,
+          f.createImportClause(
+            false,
+            undefined,
+            f.createNamedImports([
+              ...valueIntegrationNames.map((n) => f.createImportSpecifier(false, undefined, f.createIdentifier(n))),
+            ]),
+          ),
+          f.createStringLiteral(opts.integrationImport),
+        )
+      : null;
+
+  const importIntegrationTypes =
+    typeIntegrationNames.length > 0
+      ? f.createImportDeclaration(
+          undefined,
+          f.createImportClause(
+            true,
+            undefined,
+            f.createNamedImports([
+              ...typeIntegrationNames.map((n) => f.createImportSpecifier(false, undefined, f.createIdentifier(n))),
+            ]),
+          ),
+          f.createStringLiteral(opts.integrationImport),
+        )
+      : null;
+
+  return {
+    importFlowValues,
+    importFlowTypes,
+    importIntegrationValues,
+    importIntegrationTypes,
+  };
+}

package/src/transformers/model-to-narrative/generators/types.ts

@@ -0,0 +1,48 @@
+import tsNS from 'typescript';
+import { typeFromString } from '../ast/emit-helpers';
+
+type Message = {
+  type: 'command' | 'event' | 'state';
+  name: string;
+  fields: { name: string; type: string; required: boolean }[];
+};
+
+export function buildTypeAliases(ts: typeof tsNS, messages: Message[]): tsNS.Statement[] {
+  const f = ts.factory;
+
+  const mkK = (s: string) => f.createLiteralTypeNode(f.createStringLiteral(s, true));
+
+  return messages.map((m) => {
+    const typeArgs: tsNS.TypeNode[] = [
+      mkK(m.name),
+      // payload object type
+      (() => {
+        const members = m.fields.map((fld) =>
+          f.createPropertySignature(
+            undefined,
+            /^[A-Za-z_]\w*$/.test(fld.name) ? f.createIdentifier(fld.name) : f.createStringLiteral(fld.name, true),
+            fld.required ? undefined : f.createToken(ts.SyntaxKind.QuestionToken),
+            typeFromString(ts, f, fld.type),
+          ),
+        );
+        const lit = f.createTypeLiteralNode(members);
+        // Allow multiline formatting
+        return lit;
+      })(),
+    ];
+
+    const name = f.createIdentifier(m.name);
+
+    const rhs = f.createTypeReferenceNode(
+      m.type === 'event' ? 'Event' : m.type === 'command' ? 'Command' : 'State',
+      typeArgs,
+    );
+
+    return f.createTypeAliasDeclaration(
+      undefined, // No export keyword
+      name,
+      [],
+      rhs,
+    );
+  });
+}

package/src/transformers/model-to-narrative/index.ts

@@ -0,0 +1,27 @@
+import { generateTypeScriptCode } from './generators/compose';
+import { formatWithPrettier } from './formatting/prettier';
+import { Model } from '../../index';
+
+/**
+ * Converts a schema specification to TypeScript flow DSL code.
+ *
+ * This function takes a complete schema specification and generates the corresponding
+ * TypeScript code using the flow DSL, including imports, type definitions, builders,
+ * and flow specifications.
+ *
+ * @param model The complete schema specification conforming to SpecsSchema
+ * @returns Promise resolving to formatted TypeScript code string
+ */
+export async function modelToNarrative(model: Model): Promise<string> {
+  const flowImport = '@auto-engineer/narrative';
+  const integrationImport = extractIntegrationImportFromModel(model);
+  const rawCode = generateTypeScriptCode(model, { flowImport, integrationImport });
+  return await formatWithPrettier(rawCode);
+}
+
+function extractIntegrationImportFromModel(model: Model): string {
+  if (model.integrations && model.integrations.length > 0) {
+    return model.integrations[0].source;
+  }
+  return '';
+}

package/src/transformers/model-to-narrative/utils/integration-extractor.ts

@@ -0,0 +1,67 @@
+/**
+ * Extracts message name from integration destination configuration
+ */
+function extractMessageNameFromDestination(destination: Record<string, unknown>): string | null {
+  if (destination.type !== 'integration') return null;
+
+  const message = destination.message as Record<string, unknown> | undefined;
+  const messageName = message?.name;
+  return typeof messageName === 'string' && messageName.length > 0 ? messageName : null;
+}
+
+/**
+ * Extracts message name from withState integration configuration
+ */
+function extractMessageNameFromWithState(withState: Record<string, unknown>): string | null {
+  const origin = withState.origin as Record<string, unknown> | undefined;
+  if (origin?.type !== 'integration') return null;
+
+  const target = withState.target as Record<string, unknown> | undefined;
+  const targetName = target?.name;
+  return typeof targetName === 'string' && targetName.length > 0 ? targetName : null;
+}
+
+/**
+ * Processes a single data item and extracts integration names
+ */
+function processDataItem(dataItem: Record<string, unknown>, set: Set<string>): void {
+  const destination = dataItem.destination as Record<string, unknown> | undefined;
+  if (destination) {
+    const messageName = extractMessageNameFromDestination(destination);
+    if (messageName !== null) set.add(messageName);
+  }
+  const withState = dataItem._withState as Record<string, unknown> | undefined;
+  if (withState) {
+    const messageName = extractMessageNameFromWithState(withState);
+    if (messageName !== null) set.add(messageName);
+  }
+}
+
+/**
+ * Extracts all integration type names used in flows by analyzing
+ * toIntegration() and fromIntegration() patterns in the flow data.
+ *
+ * @param flows Array of flow specifications to analyze
+ * @returns Array of integration type names found in the flows
+ */
+export function extractTypeIntegrationNames(flows: Array<{ name: string; slices: unknown[] }>): string[] {
+  const set = new Set<string>();
+
+  for (const fl of flows) {
+    const slices = fl.slices ?? [];
+    for (const sl of slices) {
+      const sliceData = sl as Record<string, unknown>;
+      const server = sliceData.server as Record<string, unknown> | undefined;
+      const data = server?.data as unknown[] | undefined;
+
+      if (!Array.isArray(data)) continue;
+
+      for (const item of data) {
+        const dataItem = item as Record<string, unknown>;
+        processDataItem(dataItem, set);
+      }
+    }
+  }
+
+  return Array.from(set);
+}

package/src/transformers/model-to-narrative/utils/strings.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts integration name to PascalCase for value imports
+ * Handles kebab-case to PascalCase conversion
+ *
+ * @param name Integration name (e.g., "product-catalog")
+ * @returns PascalCase name (e.g., "ProductCatalog")
+ */
+export function integrationNameToPascalCase(name: string): string {
+  return name.charAt(0).toUpperCase() + name.slice(1).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}

package/src/transformers/narrative-to-model/assemble.ts

@@ -0,0 +1,10 @@
+import { Narrative, Model } from '../../index';
+
+export function assembleSpecs(narratives: Narrative[], messages: unknown[], integrations: unknown[]): Model {
+  return {
+    variant: 'specs' as const,
+    narratives,
+    messages: messages as Model['messages'],
+    integrations: integrations as Model['integrations'],
+  };
+}

package/src/transformers/narrative-to-model/debug.ts

@@ -0,0 +1,6 @@
+import createDebug from 'debug';
+
+export const debugIntegrations = createDebug('auto:flow:getFlows:integrations');
+if (typeof debugIntegrations === 'object' && debugIntegrations !== null && 'color' in debugIntegrations) {
+  (debugIntegrations as { color: string }).color = '6';
+}

package/src/transformers/narrative-to-model/example-shapes.ts

@@ -0,0 +1,66 @@
+import { Message } from '../../index';
+
+export type ExampleShapeHints = Map<
+  string, // message name, e.g. "Products"
+  Map<string, string> // field -> structural type string, e.g. "products" -> "Array<{ ... }>"
+>;
+
+function primitiveOf(v: unknown): string {
+  if (v === null) return 'null';
+  if (v instanceof Date) return 'Date';
+  const t = typeof v;
+  if (t === 'string' || t === 'number' || t === 'boolean') return t;
+  return 'unknown';
+}
+
+function typeFromExample(v: unknown): string {
+  if (Array.isArray(v)) {
+    const inner = v.length ? typeFromExample(v[0]) : 'unknown';
+    return `Array<${inner}>`;
+  }
+  if (v !== null && v !== undefined && typeof v === 'object' && !(v instanceof Date)) {
+    const entries = Object.entries(v as Record<string, unknown>)
+      .map(([k, val]) => `${k}: ${typeFromExample(val)}`)
+      .join('; ');
+    return `{ ${entries} }`;
+  }
+  return primitiveOf(v);
+}
+
+function isStructural(s: string): boolean {
+  const t = s.trim();
+  return t.startsWith('{') || t.startsWith('Array<{');
+}
+
+function shouldApplyExampleShape(currentType: string, exampleType: string): boolean {
+  // Don't override union types (like "string | null") with single types (like "null")
+  if (currentType.includes(' | ') && !exampleType.includes(' | ')) {
+    return false;
+  }
+  // Prefer structural example over alias-like/non-structural current type
+  return !isStructural(currentType) && isStructural(exampleType);
+}
+
+export function collectExampleHintsForData(msgName: string, exampleData: unknown, hints: ExampleShapeHints) {
+  if (exampleData === null || exampleData === undefined || typeof exampleData !== 'object') return;
+  const byField = hints.get(msgName) ?? new Map<string, string>();
+  for (const [k, v] of Object.entries(exampleData as Record<string, unknown>)) {
+    const inferred = typeFromExample(v);
+    const existing = byField.get(k);
+    if (existing === undefined || shouldApplyExampleShape(existing, inferred)) {
+      byField.set(k, inferred);
+    }
+  }
+  hints.set(msgName, byField);
+}
+
+export function applyExampleShapeHints(msgs: Map<string, Message>, hints: ExampleShapeHints) {
+  for (const [msgName, fieldsByName] of hints) {
+    const msg = msgs.get(msgName);
+    if (!msg || !Array.isArray(msg.fields)) continue;
+    msg.fields = msg.fields.map((f) => {
+      const hint = fieldsByName.get(f.name);
+      return hint !== undefined && shouldApplyExampleShape(f.type, hint) ? { ...f, type: hint } : f;
+    });
+  }
+}