@auto-engineer/model-diff 1.12.0

package/src/commands/detect-changes.ts

@@ -0,0 +1,112 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { type Command, defineCommandHandler, type Event } from '@auto-engineer/message-bus';
+import type { Model } from '@auto-engineer/narrative';
+import type { ChangeSet } from '../change-detector';
+import { computeChangeSet } from '../change-detector';
+import { computeAllFingerprints, computeAllSnapshots } from '../fingerprint';
+import type { GenerationState } from '../generation-state';
+import { loadGenerationState } from '../generation-state';
+import { computeSharedTypesHash } from '../model-dependencies';
+
+type DetectChangesCommand = Command<
+  'DetectChanges',
+  {
+    modelPath: string;
+    destination: string;
+    force?: boolean;
+  }
+>;
+
+type ChangesDetectedEvent = Event<
+  'ChangesDetected',
+  {
+    modelPath: string;
+    destination: string;
+    changeSet: ChangeSet;
+    isFirstRun: boolean;
+    newState: GenerationState;
+  }
+>;
+
+type ChangeDetectionFailedEvent = Event<
+  'ChangeDetectionFailed',
+  {
+    modelPath: string;
+    destination: string;
+    error: string;
+  }
+>;
+
+type DetectChangesEvents = ChangesDetectedEvent | ChangeDetectionFailedEvent;
+
+export const commandHandler = defineCommandHandler({
+  name: 'DetectChanges',
+  displayName: 'Detect Changes',
+  alias: 'detect:changes',
+  description: 'Detect model-level changes between pipeline runs',
+  category: 'generate',
+  icon: 'diff',
+  events: [
+    { name: 'ChangesDetected', displayName: 'Changes Detected' },
+    { name: 'ChangeDetectionFailed', displayName: 'Change Detection Failed' },
+  ],
+  fields: {
+    modelPath: { description: 'Path to the JSON model file', required: true },
+    destination: { description: 'Project root directory', required: true },
+    force: { description: 'Force full regeneration (treat as first run)' },
+  },
+  examples: ['$ auto detect:changes --model-path=.context/schema.json --destination=.'],
+  handle: async (command: Command): Promise<DetectChangesEvents> => {
+    const typed = command as DetectChangesCommand;
+    const { modelPath, destination, force } = typed.data;
+
+    try {
+      const absModel = resolve(modelPath);
+      const absDest = resolve(destination);
+
+      const content = await readFile(absModel, 'utf8');
+      const model = JSON.parse(content) as Model;
+
+      const previousState = force ? null : await loadGenerationState(absDest);
+      const isFirstRun = previousState === null;
+
+      const snapshots = computeAllSnapshots(model);
+      const fingerprints = computeAllFingerprints(snapshots);
+      const sharedTypesHash = computeSharedTypesHash(model.messages);
+      const changeSet = computeChangeSet(previousState, fingerprints, snapshots, sharedTypesHash);
+
+      const newState: GenerationState = {
+        version: 1,
+        timestamp: new Date().toISOString(),
+        sliceFingerprints: fingerprints,
+        sliceSnapshots: snapshots,
+        sharedTypesHash,
+      };
+
+      const contextDir = join(absDest, '.context');
+      await mkdir(contextDir, { recursive: true });
+      await writeFile(join(contextDir, '.change-set.json'), JSON.stringify(changeSet, null, 2), 'utf8');
+
+      return {
+        type: 'ChangesDetected',
+        data: { modelPath, destination, changeSet, isFirstRun, newState },
+        timestamp: new Date(),
+        requestId: typed.requestId,
+        correlationId: typed.correlationId,
+      };
+    } catch (error) {
+      return {
+        type: 'ChangeDetectionFailed',
+        data: {
+          modelPath,
+          destination,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        },
+        timestamp: new Date(),
+        requestId: typed.requestId,
+        correlationId: typed.correlationId,
+      };
+    }
+  },
+});

package/src/fingerprint.specs.ts

@@ -0,0 +1,213 @@
+import type { Model } from '@auto-engineer/narrative';
+import { describe, expect, it } from 'vitest';
+import {
+  buildSliceSnapshot,
+  computeAllFingerprints,
+  computeAllSnapshots,
+  computeFingerprintFromSnapshot,
+} from './fingerprint';
+
+const makeSpec = (steps: Array<{ keyword: 'Given' | 'When' | 'Then' | 'And'; text: string }>) => [
+  {
+    type: 'gherkin' as const,
+    feature: 'test',
+    rules: [{ name: 'r1', examples: [{ name: 'e1', steps }] }],
+  },
+];
+
+const baseModel: Model = {
+  variant: 'specs',
+  narratives: [
+    {
+      name: 'TodoManagement',
+      slices: [
+        {
+          name: 'AddTodo',
+          type: 'command' as const,
+          client: { specs: [] },
+          server: {
+            description: 'Add a todo item',
+            specs: makeSpec([
+              { keyword: 'When', text: 'AddTodo' },
+              { keyword: 'Then', text: 'TodoAdded' },
+            ]),
+          },
+        },
+        {
+          name: 'GetTodos',
+          type: 'query' as const,
+          client: { specs: [] },
+          server: {
+            description: 'Get all todos',
+            specs: makeSpec([
+              { keyword: 'Given', text: 'TodoAdded' },
+              { keyword: 'When', text: 'GetTodos' },
+              { keyword: 'Then', text: 'TodoList' },
+            ]),
+          },
+        },
+      ],
+    },
+  ],
+  messages: [
+    { name: 'AddTodo', type: 'command' as const, fields: [{ name: 'title', type: 'string', required: true }] },
+    {
+      name: 'TodoAdded',
+      type: 'event' as const,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'title', type: 'string', required: true },
+      ],
+    },
+    { name: 'GetTodos', type: 'query' as const, fields: [] },
+    { name: 'TodoList', type: 'state' as const, fields: [{ name: 'items', type: 'array', required: true }] },
+  ],
+  modules: [],
+};
+
+describe('buildSliceSnapshot', () => {
+  it('assembles snapshot with referenced messages sorted by name', () => {
+    const slice = baseModel.narratives[0].slices[0];
+    const snapshot = buildSliceSnapshot(slice, 'TodoManagement', baseModel);
+
+    expect(snapshot).toEqual({
+      slice,
+      flowName: 'TodoManagement',
+      referencedMessages: [
+        { name: 'AddTodo', type: 'command', fields: [{ name: 'title', type: 'string', required: true }] },
+        {
+          name: 'TodoAdded',
+          type: 'event',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'title', type: 'string', required: true },
+          ],
+        },
+      ],
+      eventSources: {},
+      commandSources: {},
+      referencedIntegrations: undefined,
+    });
+  });
+
+  it('includes event sources for query slices', () => {
+    const slice = baseModel.narratives[0].slices[1];
+    const snapshot = buildSliceSnapshot(slice, 'TodoManagement', baseModel);
+
+    expect(snapshot.eventSources).toEqual({
+      TodoAdded: { flowName: 'TodoManagement', sliceName: 'AddTodo' },
+    });
+  });
+
+  it('handles experience slices with empty dependencies', () => {
+    const model: Model = {
+      ...baseModel,
+      narratives: [
+        {
+          name: 'UI',
+          slices: [{ name: 'ViewTodos', type: 'experience' as const, client: { specs: [] } }],
+        },
+      ],
+    };
+    const snapshot = buildSliceSnapshot(model.narratives[0].slices[0], 'UI', model);
+
+    expect(snapshot).toEqual({
+      slice: model.narratives[0].slices[0],
+      flowName: 'UI',
+      referencedMessages: [],
+      eventSources: {},
+      commandSources: {},
+      referencedIntegrations: undefined,
+    });
+  });
+
+  it('includes referenced integrations when slice uses via', () => {
+    const model: Model = {
+      ...baseModel,
+      integrations: [
+        { name: 'MailChimp', source: '@auto-engineer/mailchimp' },
+        { name: 'Twilio', source: '@auto-engineer/twilio' },
+      ],
+      narratives: [
+        {
+          name: 'Notifications',
+          slices: [
+            {
+              name: 'NotifyUser',
+              type: 'react' as const,
+              via: ['MailChimp'],
+              server: {
+                specs: makeSpec([
+                  { keyword: 'Given', text: 'TodoAdded' },
+                  { keyword: 'When', text: 'TodoAdded' },
+                  { keyword: 'Then', text: 'SendEmail' },
+                ]),
+              },
+            },
+          ],
+        },
+        ...baseModel.narratives,
+      ],
+    };
+    const snapshot = buildSliceSnapshot(model.narratives[0].slices[0], 'Notifications', model);
+    expect(snapshot.referencedIntegrations).toEqual([{ name: 'MailChimp', source: '@auto-engineer/mailchimp' }]);
+  });
+});
+
+describe('computeFingerprintFromSnapshot', () => {
+  it('returns a SHA-256 hex string', () => {
+    const snapshot = buildSliceSnapshot(baseModel.narratives[0].slices[0], 'TodoManagement', baseModel);
+    const fingerprint = computeFingerprintFromSnapshot(snapshot);
+    expect(fingerprint).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  it('produces different fingerprints for different snapshots', () => {
+    const snap1 = buildSliceSnapshot(baseModel.narratives[0].slices[0], 'TodoManagement', baseModel);
+    const snap2 = buildSliceSnapshot(baseModel.narratives[0].slices[1], 'TodoManagement', baseModel);
+    expect(computeFingerprintFromSnapshot(snap1)).not.toBe(computeFingerprintFromSnapshot(snap2));
+  });
+
+  it('produces same fingerprint for identical snapshots', () => {
+    const snap1 = buildSliceSnapshot(baseModel.narratives[0].slices[0], 'TodoManagement', baseModel);
+    const snap2 = buildSliceSnapshot(baseModel.narratives[0].slices[0], 'TodoManagement', baseModel);
+    expect(computeFingerprintFromSnapshot(snap1)).toBe(computeFingerprintFromSnapshot(snap2));
+  });
+});
+
+describe('computeAllSnapshots', () => {
+  it('creates snapshots keyed by kebab-case sliceId', () => {
+    const snapshots = computeAllSnapshots(baseModel);
+    expect(Object.keys(snapshots)).toEqual(['todo-management/add-todo', 'todo-management/get-todos']);
+  });
+
+  it('includes experience slices', () => {
+    const model: Model = {
+      ...baseModel,
+      narratives: [
+        ...baseModel.narratives,
+        { name: 'UI', slices: [{ name: 'ViewTodos', type: 'experience' as const, client: { specs: [] } }] },
+      ],
+    };
+    const snapshots = computeAllSnapshots(model);
+    const expSlice = model.narratives[1].slices[0];
+    expect(snapshots['ui/view-todos']).toEqual({
+      slice: expSlice,
+      flowName: 'UI',
+      referencedMessages: [],
+      eventSources: {},
+      commandSources: {},
+      referencedIntegrations: undefined,
+    });
+  });
+});
+
+describe('computeAllFingerprints', () => {
+  it('returns fingerprints for all snapshots', () => {
+    const snapshots = computeAllSnapshots(baseModel);
+    const fingerprints = computeAllFingerprints(snapshots);
+    expect(Object.keys(fingerprints)).toEqual(['todo-management/add-todo', 'todo-management/get-todos']);
+    for (const fp of Object.values(fingerprints)) {
+      expect(fp).toMatch(/^[a-f0-9]{64}$/);
+    }
+  });
+});

package/src/fingerprint.ts

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import type { Message, Model, Slice } from '@auto-engineer/narrative';
+import {
+  getCommandSourceMap,
+  getEventSourceMap,
+  getReferencedIntegrations,
+  getReferencedMessageNames,
+} from './model-dependencies';
+import { stableStringify } from './stable-stringify';
+import { toKebabCase } from './utils';
+
+type SourceLocation = { flowName: string; sliceName: string };
+
+export type SliceSnapshot = {
+  slice: Slice;
+  flowName: string;
+  referencedMessages: Message[];
+  eventSources: Record<string, SourceLocation>;
+  commandSources: Record<string, SourceLocation>;
+  referencedIntegrations?: Model['integrations'];
+};
+
+export function buildSliceSnapshot(slice: Slice, flowName: string, model: Model): SliceSnapshot {
+  const messageNames = getReferencedMessageNames(slice);
+  const referencedMessages = messageNames
+    .map((name) => model.messages.find((m) => m.name === name))
+    .filter((m): m is Message => m !== undefined)
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const eventSources = getEventSourceMap(slice, model.narratives);
+  const commandSources = getCommandSourceMap(slice, model.narratives);
+  const referencedIntegrations = getReferencedIntegrations(slice, model.integrations);
+
+  return { slice, flowName, referencedMessages, eventSources, commandSources, referencedIntegrations };
+}
+
+export function computeFingerprintFromSnapshot(snapshot: SliceSnapshot): string {
+  const hash = createHash('sha256');
+  hash.update(stableStringify(snapshot));
+  return hash.digest('hex');
+}
+
+export function computeAllSnapshots(model: Model): Record<string, SliceSnapshot> {
+  const snapshots: Record<string, SliceSnapshot> = {};
+  for (const narrative of model.narratives) {
+    for (const slice of narrative.slices) {
+      const sliceId = `${toKebabCase(narrative.name)}/${toKebabCase(slice.name)}`;
+      snapshots[sliceId] = buildSliceSnapshot(slice, narrative.name, model);
+    }
+  }
+  return snapshots;
+}
+
+export function computeAllFingerprints(snapshots: Record<string, SliceSnapshot>): Record<string, string> {
+  const fingerprints: Record<string, string> = {};
+  for (const [sliceId, snapshot] of Object.entries(snapshots)) {
+    fingerprints[sliceId] = computeFingerprintFromSnapshot(snapshot);
+  }
+  return fingerprints;
+}

package/src/generation-state.specs.ts

@@ -0,0 +1,89 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { SliceSnapshot } from './fingerprint';
+import type { GenerationState } from './generation-state';
+import { loadGenerationState, saveGenerationState } from './generation-state';
+
+const stubSnapshot: SliceSnapshot = {
+  slice: {
+    name: 'AddTodo',
+    type: 'command',
+    client: { specs: [] },
+    server: { description: '', specs: [] },
+  },
+  flowName: 'Todo',
+  referencedMessages: [],
+  eventSources: {},
+  commandSources: {},
+  referencedIntegrations: undefined,
+};
+
+describe('generation state persistence', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `model-diff-test-${Date.now()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  const validState: GenerationState = {
+    version: 1,
+    timestamp: '2024-01-01T00:00:00.000Z',
+    sliceFingerprints: { 'todo/add-todo': 'abc123' },
+    sliceSnapshots: { 'todo/add-todo': stubSnapshot },
+    sharedTypesHash: 'hash123',
+  };
+
+  describe('saveGenerationState', () => {
+    it('writes state to .context/.generation-state.json', async () => {
+      await saveGenerationState(testDir, validState);
+
+      const content = await readFile(join(testDir, '.context', '.generation-state.json'), 'utf8');
+      const parsed = JSON.parse(content);
+      expect(parsed).toEqual(validState);
+    });
+
+    it('creates .context directory if it does not exist', async () => {
+      await saveGenerationState(testDir, validState);
+
+      const content = await readFile(join(testDir, '.context', '.generation-state.json'), 'utf8');
+      expect(JSON.parse(content)).toEqual(validState);
+    });
+  });
+
+  describe('loadGenerationState', () => {
+    it('loads previously saved state', async () => {
+      await saveGenerationState(testDir, validState);
+      const loaded = await loadGenerationState(testDir);
+      expect(loaded).toEqual(validState);
+    });
+
+    it('returns null when file does not exist', async () => {
+      const loaded = await loadGenerationState(testDir);
+      expect(loaded).toBeNull();
+    });
+
+    it('returns null when file has wrong version', async () => {
+      const badState = { ...validState, version: 999 };
+      await mkdir(join(testDir, '.context'), { recursive: true });
+      await writeFile(join(testDir, '.context', '.generation-state.json'), JSON.stringify(badState), 'utf8');
+
+      const loaded = await loadGenerationState(testDir);
+      expect(loaded).toBeNull();
+    });
+
+    it('returns null when file contains invalid JSON', async () => {
+      await mkdir(join(testDir, '.context'), { recursive: true });
+      await writeFile(join(testDir, '.context', '.generation-state.json'), 'not json', 'utf8');
+
+      const loaded = await loadGenerationState(testDir);
+      expect(loaded).toBeNull();
+    });
+  });
+});

package/src/generation-state.ts

@@ -0,0 +1,46 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import type { SliceSnapshot } from './fingerprint';
+
+export type GenerationState = {
+  version: 1;
+  timestamp: string;
+  sliceFingerprints: Record<string, string>;
+  sliceSnapshots: Record<string, SliceSnapshot>;
+  sharedTypesHash: string;
+};
+
+const STATE_VERSION = 1;
+
+function statePath(destination: string): string {
+  return join(destination, '.context', '.generation-state.json');
+}
+
+function isGenerationState(value: Record<string, unknown>): value is GenerationState {
+  return (
+    value.version === STATE_VERSION &&
+    typeof value.timestamp === 'string' &&
+    typeof value.sliceFingerprints === 'object' &&
+    value.sliceFingerprints !== null &&
+    typeof value.sliceSnapshots === 'object' &&
+    value.sliceSnapshots !== null &&
+    typeof value.sharedTypesHash === 'string'
+  );
+}
+
+export async function loadGenerationState(destination: string): Promise<GenerationState | null> {
+  try {
+    const content = await readFile(statePath(destination), 'utf8');
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+    if (!isGenerationState(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveGenerationState(destination: string, state: GenerationState): Promise<void> {
+  const filePath = statePath(destination);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(state, null, 2), 'utf8');
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+import { commandHandler as detectChangesHandler } from './commands/detect-changes';
+
+export const COMMANDS = [detectChangesHandler];
+export type { ChangeSet, SliceDelta } from './change-detector';
+export type { SliceSnapshot } from './fingerprint';
+export type { GenerationState } from './generation-state';
+export { saveGenerationState } from './generation-state';