@auto-engineer/model-diff 1.12.0

package/src/model-dependencies.specs.ts

@@ -0,0 +1,455 @@
+import { describe, expect, it } from 'vitest';
+import {
+  computeSharedTypesHash,
+  findCommandSource,
+  findEventSource,
+  getCommandSourceMap,
+  getEventSourceMap,
+  getReferencedIntegrations,
+  getReferencedMessageNames,
+  walkStepsByKeyword,
+} from './model-dependencies';
+
+const makeSpec = (steps: Array<{ keyword: 'Given' | 'When' | 'Then' | 'And'; text: string }>) => [
+  {
+    type: 'gherkin' as const,
+    feature: 'test',
+    rules: [{ name: 'r1', examples: [{ name: 'e1', steps }] }],
+  },
+];
+
+describe('walkStepsByKeyword', () => {
+  it('groups step texts by their keyword', () => {
+    const specs = makeSpec([
+      { keyword: 'Given', text: 'EventA' },
+      { keyword: 'When', text: 'CommandB' },
+      { keyword: 'Then', text: 'EventC' },
+    ]);
+    expect(walkStepsByKeyword(specs)).toEqual({
+      given: ['EventA'],
+      when: ['CommandB'],
+      then: ['EventC'],
+    });
+  });
+
+  it('resolves And to previous major keyword', () => {
+    const specs = makeSpec([
+      { keyword: 'Given', text: 'E1' },
+      { keyword: 'And', text: 'E2' },
+      { keyword: 'When', text: 'C1' },
+      { keyword: 'Then', text: 'Ev1' },
+      { keyword: 'And', text: 'Ev2' },
+    ]);
+    expect(walkStepsByKeyword(specs)).toEqual({
+      given: ['E1', 'E2'],
+      when: ['C1'],
+      then: ['Ev1', 'Ev2'],
+    });
+  });
+
+  it('skips error steps (no text property)', () => {
+    const specs = [
+      {
+        type: 'gherkin' as const,
+        feature: 'test',
+        rules: [
+          {
+            name: 'r1',
+            examples: [
+              {
+                name: 'e1',
+                steps: [
+                  { keyword: 'Given' as const, text: 'E1' },
+                  { keyword: 'When' as const, text: 'C1' },
+                  { keyword: 'Then' as const, error: { type: 'ValidationError' as const, message: 'bad' } },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    expect(walkStepsByKeyword(specs)).toEqual({
+      given: ['E1'],
+      when: ['C1'],
+      then: [],
+    });
+  });
+
+  it('deduplicates step texts across examples', () => {
+    const specs = [
+      {
+        type: 'gherkin' as const,
+        feature: 'test',
+        rules: [
+          {
+            name: 'r1',
+            examples: [
+              { name: 'e1', steps: [{ keyword: 'Given' as const, text: 'EventA' }] },
+              { name: 'e2', steps: [{ keyword: 'Given' as const, text: 'EventA' }] },
+            ],
+          },
+        ],
+      },
+    ];
+    expect(walkStepsByKeyword(specs)).toEqual({ given: ['EventA'], when: [], then: [] });
+  });
+
+  it('returns empty buckets for empty specs', () => {
+    expect(walkStepsByKeyword([])).toEqual({ given: [], when: [], then: [] });
+  });
+});
+
+describe('getReferencedMessageNames', () => {
+  it('extracts message names from server spec steps', () => {
+    const slice = {
+      name: 'AddTodo',
+      type: 'command' as const,
+      client: { specs: [] },
+      server: {
+        description: '',
+        specs: makeSpec([
+          { keyword: 'Given', text: 'TodoAdded' },
+          { keyword: 'When', text: 'AddTodo' },
+          { keyword: 'Then', text: 'TodoAdded' },
+        ]),
+      },
+    };
+    expect(getReferencedMessageNames(slice)).toEqual(['TodoAdded', 'AddTodo']);
+  });
+
+  it('includes data item target names', () => {
+    const slice = {
+      name: 'AddTodo',
+      type: 'command' as const,
+      client: { specs: [] },
+      server: {
+        description: '',
+        specs: makeSpec([
+          { keyword: 'When', text: 'AddTodo' },
+          { keyword: 'Then', text: 'TodoAdded' },
+        ]),
+        data: {
+          items: [
+            {
+              target: { type: 'Event' as const, name: 'TodoAdded' },
+              destination: { type: 'stream' as const, pattern: 'todo-${id}' },
+            },
+            {
+              target: { type: 'State' as const, name: 'TodoList' },
+              origin: { type: 'projection' as const, name: 'todo-list' },
+            },
+          ],
+        },
+      },
+    };
+    const names = getReferencedMessageNames(slice);
+    expect(names).toContain('AddTodo');
+    expect(names).toContain('TodoAdded');
+    expect(names).toContain('TodoList');
+  });
+
+  it('returns empty array for experience slices', () => {
+    const slice = {
+      name: 'ViewTodos',
+      type: 'experience' as const,
+      client: { specs: [] },
+    };
+    expect(getReferencedMessageNames(slice)).toEqual([]);
+  });
+
+  it('handles command slice with no data', () => {
+    const slice = {
+      name: 'DoThing',
+      type: 'command' as const,
+      client: { specs: [] },
+      server: {
+        description: '',
+        specs: makeSpec([
+          { keyword: 'When', text: 'DoThing' },
+          { keyword: 'Then', text: 'ThingDone' },
+        ]),
+      },
+    };
+    expect(getReferencedMessageNames(slice)).toEqual(['DoThing', 'ThingDone']);
+  });
+});
+
+describe('findEventSource', () => {
+  const flows = [
+    {
+      name: 'TodoFlow',
+      slices: [
+        {
+          name: 'AddTodo',
+          type: 'command' as const,
+          client: { specs: [] },
+          server: {
+            description: '',
+            specs: makeSpec([
+              { keyword: 'When', text: 'AddTodo' },
+              { keyword: 'Then', text: 'TodoAdded' },
+            ]),
+          },
+        },
+        {
+          name: 'NotifyUser',
+          type: 'react' as const,
+          server: {
+            description: '',
+            specs: makeSpec([
+              { keyword: 'Given', text: 'TodoAdded' },
+              { keyword: 'When', text: 'TodoAdded' },
+              { keyword: 'Then', text: 'SendNotification' },
+            ]),
+          },
+        },
+      ],
+    },
+  ];
+
+  it('finds event source from command slice Then steps', () => {
+    expect(findEventSource(flows, 'TodoAdded')).toEqual({
+      flowName: 'TodoFlow',
+      sliceName: 'AddTodo',
+    });
+  });
+
+  it('does not find events from react slice Then steps', () => {
+    expect(findEventSource(flows, 'SendNotification')).toBeNull();
+  });
+
+  it('returns null for unknown event', () => {
+    expect(findEventSource(flows, 'UnknownEvent')).toBeNull();
+  });
+});
+
+describe('findCommandSource', () => {
+  const flows = [
+    {
+      name: 'TodoFlow',
+      slices: [
+        {
+          name: 'AddTodo',
+          type: 'command' as const,
+          client: { specs: [] },
+          server: {
+            description: '',
+            specs: makeSpec([
+              { keyword: 'When', text: 'AddTodo' },
+              { keyword: 'Then', text: 'TodoAdded' },
+            ]),
+          },
+        },
+      ],
+    },
+  ];
+
+  it('finds command source from command slice When steps', () => {
+    expect(findCommandSource(flows, 'AddTodo')).toEqual({
+      flowName: 'TodoFlow',
+      sliceName: 'AddTodo',
+    });
+  });
+
+  it('returns null for unknown command', () => {
+    expect(findCommandSource(flows, 'UnknownCommand')).toBeNull();
+  });
+});
+
+describe('getEventSourceMap', () => {
+  const flows = [
+    {
+      name: 'TodoFlow',
+      slices: [
+        {
+          name: 'AddTodo',
+          type: 'command' as const,
+          client: { specs: [] },
+          server: {
+            description: '',
+            specs: makeSpec([
+              { keyword: 'When', text: 'AddTodo' },
+              { keyword: 'Then', text: 'TodoAdded' },
+            ]),
+          },
+        },
+        {
+          name: 'RemoveTodo',
+          type: 'command' as const,
+          client: { specs: [] },
+          server: {
+            description: '',
+            specs: makeSpec([
+              { keyword: 'Given', text: 'TodoAdded' },
+              { keyword: 'When', text: 'RemoveTodo' },
+              { keyword: 'Then', text: 'TodoRemoved' },
+            ]),
+          },
+        },
+      ],
+    },
+  ];
+
+  it('maps consumed Given events for command slices', () => {
+    const slice = flows[0].slices[1];
+    expect(getEventSourceMap(slice, flows)).toEqual({
+      TodoAdded: { flowName: 'TodoFlow', sliceName: 'AddTodo' },
+    });
+  });
+
+  it('maps consumed Given+When events for react slices', () => {
+    const reactSlice = {
+      name: 'Reactor',
+      type: 'react' as const,
+      server: {
+        description: '',
+        specs: makeSpec([
+          { keyword: 'Given', text: 'TodoAdded' },
+          { keyword: 'When', text: 'TodoRemoved' },
+          { keyword: 'Then', text: 'SendNotification' },
+        ]),
+      },
+    };
+    expect(getEventSourceMap(reactSlice, flows)).toEqual({
+      TodoAdded: { flowName: 'TodoFlow', sliceName: 'AddTodo' },
+      TodoRemoved: { flowName: 'TodoFlow', sliceName: 'RemoveTodo' },
+    });
+  });
+
+  it('returns empty map for experience slices', () => {
+    const expSlice = { name: 'View', type: 'experience' as const, client: { specs: [] } };
+    expect(getEventSourceMap(expSlice, flows)).toEqual({});
+  });
+});
+
+describe('getCommandSourceMap', () => {
+  const flows = [
+    {
+      name: 'TodoFlow',
+      slices: [
+        {
+          name: 'AddTodo',
+          type: 'command' as const,
+          client: { specs: [] },
+          server: {
+            description: '',
+            specs: makeSpec([
+              { keyword: 'When', text: 'AddTodo' },
+              { keyword: 'Then', text: 'TodoAdded' },
+            ]),
+          },
+        },
+      ],
+    },
+  ];
+
+  it('maps produced commands for react slices', () => {
+    const reactSlice = {
+      name: 'AutoAdd',
+      type: 'react' as const,
+      server: {
+        description: '',
+        specs: makeSpec([
+          { keyword: 'Given', text: 'TodoAdded' },
+          { keyword: 'When', text: 'TodoAdded' },
+          { keyword: 'Then', text: 'AddTodo' },
+        ]),
+      },
+    };
+    expect(getCommandSourceMap(reactSlice, flows)).toEqual({
+      AddTodo: { flowName: 'TodoFlow', sliceName: 'AddTodo' },
+    });
+  });
+
+  it('returns empty map for command slices', () => {
+    expect(getCommandSourceMap(flows[0].slices[0], flows)).toEqual({});
+  });
+
+  it('returns empty map for experience slices', () => {
+    const expSlice = { name: 'View', type: 'experience' as const, client: { specs: [] } };
+    expect(getCommandSourceMap(expSlice, flows)).toEqual({});
+  });
+
+  it('returns empty map for query slices', () => {
+    const querySlice = {
+      name: 'GetTodos',
+      type: 'query' as const,
+      client: { specs: [] },
+      server: {
+        description: '',
+        specs: makeSpec([
+          { keyword: 'Given', text: 'TodoAdded' },
+          { keyword: 'When', text: 'GetTodos' },
+          { keyword: 'Then', text: 'TodoList' },
+        ]),
+      },
+    };
+    expect(getCommandSourceMap(querySlice, flows)).toEqual({});
+  });
+});
+
+describe('getReferencedIntegrations', () => {
+  const integrations = [
+    { name: 'MailChimp', description: 'Email service', source: '@auto-engineer/mailchimp' },
+    { name: 'Twilio', description: 'SMS service', source: '@auto-engineer/twilio' },
+  ];
+
+  it('filters integrations by slice.via names', () => {
+    const slice = { name: 'Notify', type: 'react' as const, via: ['MailChimp'], server: { specs: [] } };
+    expect(getReferencedIntegrations(slice, integrations)).toEqual([
+      { name: 'MailChimp', description: 'Email service', source: '@auto-engineer/mailchimp' },
+    ]);
+  });
+
+  it('returns undefined when slice has no via', () => {
+    const slice = {
+      name: 'AddTodo',
+      type: 'command' as const,
+      client: { specs: [] },
+      server: { description: '', specs: [] },
+    };
+    expect(getReferencedIntegrations(slice, integrations)).toBeUndefined();
+  });
+
+  it('returns undefined when integrations is undefined', () => {
+    const slice = { name: 'Notify', type: 'react' as const, via: ['MailChimp'], server: { specs: [] } };
+    expect(getReferencedIntegrations(slice, undefined)).toBeUndefined();
+  });
+
+  it('returns undefined when no via names match', () => {
+    const slice = { name: 'Notify', type: 'react' as const, via: ['Stripe'], server: { specs: [] } };
+    expect(getReferencedIntegrations(slice, integrations)).toBeUndefined();
+  });
+});
+
+describe('computeSharedTypesHash', () => {
+  it('hashes string literal union fields from messages', () => {
+    const messages = [
+      {
+        name: 'TodoAdded',
+        type: 'event' as const,
+        fields: [
+          { name: 'status', type: "'active' | 'inactive'", required: true },
+          { name: 'id', type: 'string', required: true },
+        ],
+      },
+    ];
+    expect(computeSharedTypesHash(messages)).toBe("TodoAdded.status:'active' | 'inactive'");
+  });
+
+  it('returns empty string when no union fields exist', () => {
+    const messages = [
+      { name: 'TodoAdded', type: 'event' as const, fields: [{ name: 'id', type: 'string', required: true }] },
+    ];
+    expect(computeSharedTypesHash(messages)).toBe('');
+  });
+
+  it('preserves model order for deterministic output', () => {
+    const messages = [
+      { name: 'A', type: 'event' as const, fields: [{ name: 'x', type: "'a' | 'b'", required: true }] },
+      { name: 'B', type: 'event' as const, fields: [{ name: 'y', type: "'c' | 'd'", required: true }] },
+    ];
+    expect(computeSharedTypesHash(messages)).toBe("A.x:'a' | 'b'|B.y:'c' | 'd'");
+  });
+});

package/src/model-dependencies.ts

@@ -0,0 +1,136 @@
+import type { Model, Narrative, Slice, Spec } from '@auto-engineer/narrative';
+
+type StepBuckets = { given: string[]; when: string[]; then: string[] };
+
+export function walkStepsByKeyword(specs: Spec[]): StepBuckets {
+  const given = new Set<string>();
+  const when = new Set<string>();
+  const then = new Set<string>();
+
+  for (const spec of specs) {
+    for (const rule of spec.rules) {
+      for (const example of rule.examples) {
+        let lastMajor: 'given' | 'when' | 'then' = 'given';
+        for (const step of example.steps) {
+          if (!('text' in step)) continue;
+          const keyword = step.keyword;
+          if (keyword === 'Given') lastMajor = 'given';
+          else if (keyword === 'When') lastMajor = 'when';
+          else if (keyword === 'Then') lastMajor = 'then';
+          const bucket = keyword === 'And' ? lastMajor : (keyword.toLowerCase() as 'given' | 'when' | 'then');
+          if (bucket === 'given') given.add(step.text);
+          else if (bucket === 'when') when.add(step.text);
+          else then.add(step.text);
+        }
+      }
+    }
+  }
+
+  return { given: [...given], when: [...when], then: [...then] };
+}
+
+function getServerSpecs(slice: Slice): Spec[] {
+  if ('server' in slice && slice.server) return slice.server.specs;
+  return [];
+}
+
+export function getReferencedMessageNames(slice: Slice): string[] {
+  const names = new Set<string>();
+  const specs = getServerSpecs(slice);
+  const buckets = walkStepsByKeyword(specs);
+  for (const text of [...buckets.given, ...buckets.when, ...buckets.then]) {
+    names.add(text);
+  }
+  if ('server' in slice && slice.server?.data?.items) {
+    for (const item of slice.server.data.items) {
+      names.add(item.target.name);
+    }
+  }
+  return [...names];
+}
+
+export function findEventSource(flows: Narrative[], eventName: string): { flowName: string; sliceName: string } | null {
+  for (const flow of flows) {
+    for (const slice of flow.slices) {
+      if (slice.type !== 'command') continue;
+      const buckets = walkStepsByKeyword(slice.server.specs);
+      if (buckets.then.includes(eventName)) {
+        return { flowName: flow.name, sliceName: slice.name };
+      }
+    }
+  }
+  return null;
+}
+
+export function findCommandSource(
+  flows: Narrative[],
+  commandName: string,
+): { flowName: string; sliceName: string } | null {
+  for (const flow of flows) {
+    for (const slice of flow.slices) {
+      if (slice.type !== 'command') continue;
+      const buckets = walkStepsByKeyword(slice.server.specs);
+      if (buckets.when.includes(commandName)) {
+        return { flowName: flow.name, sliceName: slice.name };
+      }
+    }
+  }
+  return null;
+}
+
+type SourceLocation = { flowName: string; sliceName: string };
+
+export function getEventSourceMap(slice: Slice, flows: Narrative[]): Record<string, SourceLocation> {
+  const specs = getServerSpecs(slice);
+  if (specs.length === 0) return {};
+
+  const buckets = walkStepsByKeyword(specs);
+  const consumedEvents: string[] = [];
+
+  if (slice.type === 'command') {
+    consumedEvents.push(...buckets.given);
+  } else if (slice.type === 'react' || slice.type === 'query') {
+    consumedEvents.push(...buckets.given, ...buckets.when);
+  }
+
+  const result: Record<string, SourceLocation> = {};
+  for (const eventName of consumedEvents) {
+    const source = findEventSource(flows, eventName);
+    if (source) result[eventName] = source;
+  }
+  return result;
+}
+
+export function getCommandSourceMap(slice: Slice, flows: Narrative[]): Record<string, SourceLocation> {
+  if (slice.type !== 'react') return {};
+
+  const specs = getServerSpecs(slice);
+  if (specs.length === 0) return {};
+
+  const buckets = walkStepsByKeyword(specs);
+  const result: Record<string, SourceLocation> = {};
+  for (const cmdName of buckets.then) {
+    const source = findCommandSource(flows, cmdName);
+    if (source) result[cmdName] = source;
+  }
+  return result;
+}
+
+export function getReferencedIntegrations(slice: Slice, integrations?: Model['integrations']): Model['integrations'] {
+  if (!integrations || !slice.via || slice.via.length === 0) return undefined;
+  const viaSet = new Set(slice.via);
+  const filtered = integrations.filter((i) => viaSet.has(i.name));
+  return filtered.length > 0 ? filtered : undefined;
+}
+
+export function computeSharedTypesHash(messages: Model['messages']): string {
+  const unionFields: string[] = [];
+  for (const msg of messages) {
+    for (const field of msg.fields) {
+      if (field.type.includes("'") && field.type.includes('|')) {
+        unionFields.push(`${msg.name}.${field.name}:${field.type}`);
+      }
+    }
+  }
+  return unionFields.join('|');
+}

package/src/stable-stringify.specs.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { stableStringify } from './stable-stringify';
+
+describe('stableStringify', () => {
+  it('produces identical output regardless of key order', () => {
+    const a = stableStringify({ z: 1, a: 2 });
+    const b = stableStringify({ a: 2, z: 1 });
+    expect(a).toBe(b);
+  });
+
+  it('sorts nested object keys', () => {
+    const result = stableStringify({ b: { d: 1, c: 2 }, a: 3 });
+    expect(result).toBe('{"a":3,"b":{"c":2,"d":1}}');
+  });
+
+  it('handles arrays without reordering elements', () => {
+    const result = stableStringify([3, 1, 2]);
+    expect(result).toBe('[3,1,2]');
+  });
+
+  it('handles null and primitive values', () => {
+    expect(stableStringify(null)).toBe('null');
+    expect(stableStringify('hello')).toBe('"hello"');
+    expect(stableStringify(42)).toBe('42');
+    expect(stableStringify(true)).toBe('true');
+  });
+
+  it('handles nested arrays with objects', () => {
+    const result = stableStringify([
+      { z: 1, a: 2 },
+      { y: 3, b: 4 },
+    ]);
+    expect(result).toBe('[{"a":2,"z":1},{"b":4,"y":3}]');
+  });
+
+  it('handles empty objects and arrays', () => {
+    expect(stableStringify({})).toBe('{}');
+    expect(stableStringify([])).toBe('[]');
+  });
+
+  it('handles undefined values by omitting them', () => {
+    const result = stableStringify({ a: 1, b: undefined, c: 3 });
+    expect(result).toBe('{"a":1,"c":3}');
+  });
+});

package/src/stable-stringify.ts

@@ -0,0 +1,19 @@
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+
+  const obj = value as Record<string, unknown>;
+  const sortedKeys = Object.keys(obj).sort();
+  const parts: string[] = [];
+  for (const key of sortedKeys) {
+    const val = obj[key];
+    if (val === undefined) continue;
+    parts.push(`${JSON.stringify(key)}:${stableStringify(val)}`);
+  }
+  return `{${parts.join(',')}}`;
+}

package/src/utils.specs.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { toKebabCase } from './utils';
+
+describe('toKebabCase', () => {
+  it('converts PascalCase to kebab-case', () => {
+    expect(toKebabCase('PropertyListing')).toBe('property-listing');
+  });
+
+  it('converts camelCase to kebab-case', () => {
+    expect(toKebabCase('createUser')).toBe('create-user');
+  });
+
+  it('converts spaced strings to kebab-case', () => {
+    expect(toKebabCase('Property Listing')).toBe('property-listing');
+  });
+
+  it('handles single word', () => {
+    expect(toKebabCase('Todo')).toBe('todo');
+  });
+
+  it('handles already kebab-case', () => {
+    expect(toKebabCase('property-listing')).toBe('property-listing');
+  });
+});

package/src/utils.ts

@@ -0,0 +1,6 @@
+export function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/\s+/g, '-')
+    .toLowerCase();
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "types": ["vitest/globals", "node"],
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.specs.ts"]
+}