@auto-engineer/narrative 0.11.11

package/src/testing.ts

@@ -0,0 +1,40 @@
+// Legacy testing functions - deprecated, use new specs/rule/example API instead
+// This module is kept for backward compatibility but the functions are no-ops
+
+export const createNarrativeSpec = () => {
+  console.warn('createNarrativeSpec is deprecated. Use specs/rule/example API instead.');
+  return {
+    given: (_events: unknown[]) => ({
+      when: (_command: unknown) => ({
+        then: (_expectedEvents: unknown[]) => {},
+        thenThrows: (_errorMatcher: (error: Error) => boolean) => {},
+      }),
+      then: (_expectedData: unknown | unknown[]) => {},
+    }),
+    when: (_commandOrEvents: unknown | unknown[]) => ({
+      then: (_expected: unknown[]) => {},
+      thenThrows: (_errorMatcher: (error: Error) => boolean) => {},
+    }),
+  };
+};
+
+export const given = (_events: unknown[]) => {
+  console.warn('given is deprecated. Use specs/rule/example API instead.');
+  return createNarrativeSpec().given(_events);
+};
+
+export const when = (_commandOrEvents: unknown | unknown[]) => {
+  console.warn('when is deprecated. Use specs/rule/example API instead.');
+  return createNarrativeSpec().when(_commandOrEvents);
+};
+
+// GraphQL query testing helper
+export const gqlQuery = (query: string) => ({
+  query,
+  then: (_expectedResponse: unknown) => {},
+});
+
+// Alternative when function for GraphQL queries
+export const whenQuery = (_query: unknown) => ({
+  then: (_expectedResponse: unknown) => {},
+});

package/src/transformers/model-to-narrative/analysis/extract-flow.ts

@@ -0,0 +1,26 @@
+import { collectTypeDeclarations } from './type-decls';
+
+export function extractFlowCode(code: string): string {
+  const lines = code.split('\n');
+  const typeRanges = new Set<number>();
+
+  // Collect all type declarations
+  const allTypes = collectTypeDeclarations(lines);
+
+  // Mark all lines in type declarations as excluded
+  for (const type of allTypes) {
+    for (let i = type.startIdx; i <= type.endIdx; i++) {
+      typeRanges.add(i);
+    }
+  }
+
+  // Extract flow lines (everything that's not a type declaration)
+  const flowLines: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!typeRanges.has(i)) {
+      flowLines.push(lines[i]);
+    }
+  }
+
+  return flowLines.join('\n');
+}

package/src/transformers/model-to-narrative/analysis/lint-helpers.ts

@@ -0,0 +1,98 @@
+import ts from 'typescript';
+
+export function isTypeReferenceMethod(methodName: string): boolean {
+  return ['event', 'state', 'command'].includes(methodName);
+}
+
+export function processTypeMatching(text: string, typeNames: string[], usedTypes: Set<string>): void {
+  for (const typeName of typeNames) {
+    if (text === typeName) {
+      usedTypes.add(typeName);
+      break;
+    }
+  }
+}
+
+export function checkCallExpressionContext(call: ts.CallExpression): string | null {
+  if (call.expression === null || call.expression === undefined || !ts.isPropertyAccessExpression(call.expression)) {
+    return null;
+  }
+
+  const methodName = call.expression.name.text;
+  return isTypeReferenceMethod(methodName) ? methodName : null;
+}
+
+export function extractIntegrationNames(code: string): string[] {
+  const integrationMatch = code.match(/import\s+{[^}]*}\s+from\s+['"][^'"]*integrations['"]/);
+
+  if (integrationMatch) {
+    const importMatch = integrationMatch[0].match(/{([^}]*)}/);
+    if (importMatch) {
+      return importMatch[1]
+        .split(',')
+        .map((name) => name.replace(/^type\s+/, '').trim())
+        .filter((name) => name.length > 0);
+    }
+  }
+  return [];
+}
+
+export function findCodeBoundaries(lines: string[]): { lastImportIdx: number } {
+  let lastImportIdx = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].match(/^\s*import\s/)) {
+      lastImportIdx = i;
+    } else if (lines[i].includes('flow(')) {
+      break;
+    }
+  }
+
+  return { lastImportIdx };
+}
+
+export function reconstructCode(
+  lines: string[],
+  filteredTypes: Array<{ name: string; startIdx: number; endIdx: number }>,
+  allTypes: Array<{ name: string; startIdx: number; endIdx: number }>,
+  lastImportIdx: number,
+): string {
+  const result: string[] = [];
+
+  // Add imports section
+  for (let i = 0; i <= lastImportIdx; i++) {
+    result.push(lines[i]);
+  }
+
+  // Add blank line before types
+  result.push('');
+
+  // Add sorted types
+  filteredTypes.forEach((type, index) => {
+    for (let i = type.startIdx; i <= type.endIdx; i++) {
+      result.push(lines[i]);
+    }
+    if (index < filteredTypes.length - 1) {
+      result.push(''); // Blank line between types
+    }
+  });
+
+  // Add blank line after types
+  result.push('');
+
+  // Add everything after imports that isn't a type declaration
+  const typeRanges = new Set<number>();
+  for (const type of allTypes) {
+    for (let i = type.startIdx; i <= type.endIdx; i++) {
+      typeRanges.add(i);
+    }
+  }
+
+  for (let i = lastImportIdx + 1; i < lines.length; i++) {
+    if (!typeRanges.has(i)) {
+      result.push(lines[i]);
+    }
+  }
+
+  return result.join('\n');
+}

package/src/transformers/model-to-narrative/analysis/type-decls.ts

@@ -0,0 +1,94 @@
+function isStringStart(char: string): boolean {
+  return char === '"' || char === "'" || char === '`';
+}
+
+function updateBracketCounts(char: string, counts: { braceCount: number; angleCount: number }): void {
+  if (char === '{') counts.braceCount++;
+  else if (char === '}') counts.braceCount--;
+  else if (char === '<') counts.angleCount++;
+  else if (char === '>') counts.angleCount--;
+}
+
+function countBrackets(text: string): {
+  braceCount: number;
+  angleCount: number;
+  inString: boolean;
+  stringChar: string;
+} {
+  const counts = { braceCount: 0, angleCount: 0 };
+  let inString = false;
+  let stringChar = '';
+
+  for (const char of text) {
+    if (!inString && isStringStart(char)) {
+      inString = true;
+      stringChar = char;
+    } else if (inString && char === stringChar) {
+      inString = false;
+    } else if (!inString) {
+      updateBracketCounts(char, counts);
+    }
+  }
+
+  return { ...counts, inString, stringChar };
+}
+
+function findTypeDeclarationEnd(
+  lines: string[],
+  startIdx: number,
+  initialCounts: { braceCount: number; angleCount: number },
+): number {
+  let endIdx = startIdx;
+  let { braceCount, angleCount } = initialCounts;
+
+  if (braceCount > 0 || angleCount > 0) {
+    for (let j = startIdx + 1; j < lines.length; j++) {
+      endIdx = j;
+      const nextLine = lines[j];
+
+      const counts = countBrackets(nextLine);
+      braceCount += counts.braceCount;
+      angleCount += counts.angleCount;
+
+      if (braceCount === 0 && angleCount === 0 && nextLine.trim().endsWith(';')) {
+        break;
+      }
+
+      if (nextLine.match(/^type\s+\w+/)) {
+        endIdx = j - 1;
+        break;
+      }
+    }
+  }
+
+  return endIdx;
+}
+
+export function collectTypeDeclarations(lines: string[]): Array<{ name: string; startIdx: number; endIdx: number }> {
+  const allTypes: Array<{ name: string; startIdx: number; endIdx: number }> = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (line.match(/^type\s+\w+/)) {
+      const typeName = extractTypeName(line);
+      const startIdx = i;
+
+      // Count opening braces/angles on the first line
+      const initialCounts = countBrackets(line);
+
+      // Find the end of this type declaration
+      const endIdx = findTypeDeclarationEnd(lines, startIdx, initialCounts);
+
+      allTypes.push({ name: typeName, startIdx, endIdx });
+      i = endIdx; // Skip to end of this type
+    }
+  }
+
+  return allTypes;
+}
+
+export function extractTypeName(typeLine: string): string {
+  const match = typeLine.match(/^type\s+(\w+)/);
+  return match ? match[1] : '';
+}

package/src/transformers/model-to-narrative/analysis/usage.ts

@@ -0,0 +1,111 @@
+import ts from 'typescript';
+import { extractFlowCode } from './extract-flow';
+import { checkCallExpressionContext, processTypeMatching } from './lint-helpers';
+
+function checkTypeReference(node: ts.Node, typeNames: string[], usedTypes: Set<string>): void {
+  if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+    const typeName = node.typeName.text;
+    if (typeNames.includes(typeName)) {
+      usedTypes.add(typeName);
+    }
+  }
+}
+
+function checkIdentifierReference(node: ts.Node, valueIntegrationNames: string[], usedIntegrations: Set<string>): void {
+  if (ts.isIdentifier(node)) {
+    const name = node.text;
+    if (valueIntegrationNames.includes(name)) {
+      usedIntegrations.add(name);
+    }
+  }
+}
+
+function checkFlowFunctionReference(node: ts.Node, flowFunctionNames: string[], usedFlowFunctions: Set<string>): void {
+  if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+    const functionName = node.expression.text;
+    if (flowFunctionNames.includes(functionName)) {
+      usedFlowFunctions.add(functionName);
+    }
+  }
+}
+
+function checkCallExpressionTypes(node: ts.Node, typeNames: string[], usedTypes: Set<string>): void {
+  if (ts.isCallExpression(node) && node.typeArguments) {
+    for (const typeArg of node.typeArguments) {
+      if (ts.isTypeReferenceNode(typeArg) && ts.isIdentifier(typeArg.typeName)) {
+        const typeName = typeArg.typeName.text;
+        if (typeNames.includes(typeName)) {
+          usedTypes.add(typeName);
+        }
+      }
+    }
+  }
+}
+
+function checkAsExpression(node: ts.Node, typeNames: string[], usedTypes: Set<string>): void {
+  if (ts.isAsExpression(node) && ts.isTypeReferenceNode(node.type) && ts.isIdentifier(node.type.typeName)) {
+    const typeName = node.type.typeName.text;
+    if (typeNames.includes(typeName)) {
+      usedTypes.add(typeName);
+    }
+  }
+}
+
+function checkStringLiteralReferences(node: ts.Node, typeNames: string[], usedTypes: Set<string>): void {
+  if (!ts.isStringLiteral(node) || node.parent === null || node.parent === undefined) {
+    return;
+  }
+
+  const text = node.text;
+  const isTypeReference = checkIfStringLiteralIsTypeReference(node.parent);
+
+  if (isTypeReference) {
+    processTypeMatching(text, typeNames, usedTypes);
+  }
+}
+
+function checkIfStringLiteralIsTypeReference(parent: ts.Node): boolean {
+  if (!ts.isCallExpression(parent)) {
+    return false;
+  }
+
+  const contextResult = checkCallExpressionContext(parent);
+  return contextResult !== null;
+}
+
+/**
+ * Analyzes the flow code to find both used types and used integration names
+ */
+export function analyzeCodeUsage(
+  code: string,
+  typeNames: string[],
+  _typeIntegrationNames: string[],
+  valueIntegrationNames: string[],
+  flowFunctionNames: string[] = [],
+) {
+  const usedTypes = new Set<string>();
+  const usedIntegrations = new Set<string>();
+  const usedFlowFunctions = new Set<string>();
+
+  // Extract only the flow code (exclude type declarations) for analysis
+  const flowCode = extractFlowCode(code);
+
+  // Create a temporary source file for flow code analysis
+  const sourceFile = ts.createSourceFile('temp.ts', flowCode, ts.ScriptTarget.Latest, true);
+
+  // Visit all nodes to find type and integration references in the flow code
+  function visit(node: ts.Node): void {
+    // Check for various type references
+    checkTypeReference(node, typeNames, usedTypes);
+    checkIdentifierReference(node, valueIntegrationNames, usedIntegrations);
+    checkFlowFunctionReference(node, flowFunctionNames, usedFlowFunctions);
+    checkCallExpressionTypes(node, typeNames, usedTypes);
+    checkAsExpression(node, typeNames, usedTypes);
+    checkStringLiteralReferences(node, typeNames, usedTypes);
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return { usedTypes, usedIntegrations, usedFlowFunctions };
+}

package/src/transformers/model-to-narrative/ast/emit-helpers.ts

@@ -0,0 +1,199 @@
+import tsNS from 'typescript';
+
+/**
+ * Type information for converting JSON values with proper Date handling
+ */
+export interface FieldTypeInfo {
+  [fieldName: string]: string; // field name -> type (e.g., 'Date', 'string', etc.)
+}
+
+/**
+ * Check if a string is a valid ISO date string
+ */
+function isISODateString(str: string): boolean {
+  const isoDateRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})?$/;
+  return isoDateRegex.test(str);
+}
+
+/**
+ * Emit a TS expression from a plain JSON-like value with optional type information for Date handling.
+ */
+export function jsonToExpr(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  v: unknown,
+  typeInfo?: FieldTypeInfo,
+): tsNS.Expression {
+  if (v === null) return f.createNull();
+  switch (typeof v) {
+    case 'string':
+      return f.createStringLiteral(v);
+    case 'number':
+      return f.createNumericLiteral(String(v));
+    case 'boolean':
+      return v ? f.createTrue() : f.createFalse();
+    case 'object': {
+      if (v instanceof Date) {
+        // Generate new Date('...') for Date objects
+        return f.createNewExpression(f.createIdentifier('Date'), undefined, [f.createStringLiteral(v.toISOString())]);
+      }
+      if (Array.isArray(v)) {
+        return f.createArrayLiteralExpression(v.map((x) => jsonToExpr(ts, f, x, typeInfo)));
+      }
+      const entries = Object.entries(v as Record<string, unknown>);
+      return f.createObjectLiteralExpression(
+        entries.map(([k, x]) => {
+          // Check if this field should be a Date
+          const fieldType = typeInfo?.[k];
+          let valueExpr: tsNS.Expression;
+
+          if (fieldType === 'Date' && typeof x === 'string' && isISODateString(x)) {
+            // Generate new Date('...') for Date fields
+            valueExpr = f.createNewExpression(f.createIdentifier('Date'), undefined, [f.createStringLiteral(x)]);
+          } else if (fieldType === 'Date' && x instanceof Date) {
+            // Generate new Date('...') for Date objects
+            valueExpr = f.createNewExpression(f.createIdentifier('Date'), undefined, [
+              f.createStringLiteral(x.toISOString()),
+            ]);
+          } else {
+            valueExpr = jsonToExpr(ts, f, x, typeInfo);
+          }
+
+          return f.createPropertyAssignment(
+            // use identifier if safe, else quoted string
+            /^[A-Za-z_]\w*$/.test(k) ? f.createIdentifier(k) : f.createStringLiteral(k),
+            valueExpr,
+          );
+        }),
+        false,
+      );
+    }
+    default:
+      return f.createIdentifier('undefined');
+  }
+}
+
+/**
+ * Creates primitive type nodes
+ */
+function createPrimitiveTypeNode(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  trimmed: string,
+): tsNS.TypeNode | null {
+  switch (trimmed) {
+    case 'string':
+      return f.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
+    case 'number':
+      return f.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword);
+    case 'boolean':
+      return f.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword);
+    case 'unknown':
+      return f.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword);
+    case 'Date':
+      return f.createTypeReferenceNode('Date');
+    default:
+      return null;
+  }
+}
+
+/**
+ * Creates array type node if the type is Array<...>
+ */
+function createArrayTypeNode(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  trimmed: string,
+): tsNS.TypeNode | null {
+  const arrayMatch = /^Array<(.+)>$/.exec(trimmed);
+  if (arrayMatch) {
+    const inner = typeFromString(ts, f, arrayMatch[1]);
+    return f.createArrayTypeNode(inner);
+  }
+  return null;
+}
+
+/**
+ * Creates object literal type node for {prop: type, ...} syntax
+ */
+function createObjectLiteralTypeNode(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  trimmed: string,
+): tsNS.TypeNode | null {
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+    return null;
+  }
+
+  const inner = trimmed.slice(1, -1).trim();
+  const members: tsNS.TypeElement[] = [];
+
+  if (inner.length > 0) {
+    const parts = splitTopLevel(inner, ',');
+    for (const p of parts) {
+      const [rawName, ...rest] = p.split(':');
+      const name = rawName.trim();
+      const rhs = rest.join(':').trim();
+      if (name.length === 0 || rhs.length === 0) continue;
+
+      const typeNode = typeFromString(ts, f, rhs);
+      members.push(
+        f.createPropertySignature(
+          undefined,
+          /^[A-Za-z_]\w*$/.test(name) ? f.createIdentifier(name) : f.createStringLiteral(name),
+          undefined,
+          typeNode,
+        ),
+      );
+    }
+  }
+
+  return f.createTypeLiteralNode(members);
+}
+
+/**
+ * Create a TypeNode from a simple textual form (as produced by your schema).
+ * Supports: string, number, boolean, unknown, Date, Array<...>, inline object {a: string, ...}
+ * Falls back to a named type reference.
+ */
+export function typeFromString(ts: typeof import('typescript'), f: tsNS.NodeFactory, t: string): tsNS.TypeNode {
+  const trimmed = t.trim();
+
+  // Try primitive types
+  const primitive = createPrimitiveTypeNode(ts, f, trimmed);
+  if (primitive) return primitive;
+
+  // Try array types
+  const arrayType = createArrayTypeNode(ts, f, trimmed);
+  if (arrayType) return arrayType;
+
+  // Try object literal types
+  const objectType = createObjectLiteralTypeNode(ts, f, trimmed);
+  if (objectType) return objectType;
+
+  // Fallback: bare identifier type
+  return f.createTypeReferenceNode(trimmed);
+}
+
+/** Split a string by a delimiter at top-level only (not inside {}, <>). */
+function splitTopLevel(input: string, delim: ',' | '|'): string[] {
+  const out: string[] = [];
+  let depthBrace = 0;
+  let depthAngle = 0;
+  let cur = '';
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === '{') depthBrace++;
+    else if (ch === '}') depthBrace--;
+    else if (ch === '<') depthAngle++;
+    else if (ch === '>') depthAngle--;
+    if (ch === delim && depthBrace === 0 && depthAngle === 0) {
+      out.push(cur.trim());
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim()) out.push(cur.trim());
+  return out;
+}

package/src/transformers/model-to-narrative/formatting/prettier.ts

@@ -0,0 +1,30 @@
+function modDefault<T>(m: unknown): T {
+  const moduleObj = m as { default?: T };
+  return moduleObj?.default ?? (m as T);
+}
+
+export async function formatWithPrettier(rawCode: string): Promise<string> {
+  try {
+    const prettier = modDefault<{ format: (code: string, options: unknown) => Promise<string> }>(
+      await import('prettier/standalone'),
+    );
+    const tsPlugin = modDefault<unknown>(await import('prettier/plugins/typescript'));
+    const estreePlugin = modDefault<unknown>(await import('prettier/plugins/estree'));
+
+    const cfg = {
+      parser: 'typescript' as const,
+      singleQuote: true,
+      semi: true,
+      trailingComma: 'all' as const,
+      printWidth: 120,
+      plugins: [tsPlugin, estreePlugin],
+    };
+
+    const formatted = await prettier.format(rawCode, cfg);
+
+    return formatted;
+  } catch (err) {
+    console.warn('Prettier formatting failed, returning unformatted code:', err);
+    return rawCode;
+  }
+}

package/src/transformers/model-to-narrative/formatting/sort-types.ts

@@ -0,0 +1,19 @@
+import { collectTypeDeclarations } from '../analysis/type-decls';
+import { findCodeBoundaries, reconstructCode } from '../analysis/lint-helpers';
+
+/**
+ * Sorts TypeScript type declarations alphabetically, adds line breaks between them, and removes unused types.
+ * Ensures all types appear after imports but before flow statements.
+ */
+export function sortTypeDeclarations(code: string): string {
+  const lines = code.split('\n');
+  const allTypes = collectTypeDeclarations(lines);
+
+  if (allTypes.length === 0) return code;
+
+  const { lastImportIdx } = findCodeBoundaries(lines);
+  const filteredTypes = allTypes;
+  filteredTypes.sort((a, b) => a.name.localeCompare(b.name));
+
+  return reconstructCode(lines, filteredTypes, allTypes, lastImportIdx);
+}