@auto-engineer/server-implementer 1.81.0 → 1.83.0

package/ketchup-plan.md

@@ -0,0 +1,9 @@
+# Ketchup Plan: Prevent implementer AI from redefining imported types
+
+## TODO
+
+## DONE
+
+- [x] Burst 1: Detection utility — detectImportedTypeShadowing with TypeScript AST [depends: none] (afff6f0f)
+- [x] Burst 2: Integrate shadow detection into runSlice.ts and implement-slice.ts [depends: 1] (b47ae539)
+- [x] Burst 3: Clarify Internal State Pattern in projection template + update snapshots [depends: none] (pending)

package/package.json

@@ -18,8 +18,8 @@
     "debug": "^4.3.4",
     "fast-glob": "^3.3.3",
     "vite": "^5.4.1",
-    "@auto-engineer/model-factory": "1.81.0",
-    "@auto-engineer/message-bus": "1.81.0"
+    "@auto-engineer/message-bus": "1.83.0",
+    "@auto-engineer/model-factory": "1.83.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
@@ -29,9 +29,9 @@
     "glob": "^11.0.3",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
-    "@auto-engineer/cli": "1.81.0"
+    "@auto-engineer/cli": "1.83.0"
   },
-  "version": "1.81.0",
+  "version": "1.83.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts",
     "test": "vitest run --reporter=dot",

package/src/agent/detectShadowsInSlice.specs.ts

@@ -0,0 +1,62 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { detectShadowsInSlice } from './runSlice';
+
+describe('detectShadowsInSlice', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(path.join(tmpdir(), 'shadow-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true });
+  });
+
+  it('returns empty results for clean files', async () => {
+    await writeFile(path.join(tempDir, 'projection.ts'), `import type { MyState } from './state';\nconst x = 1;\n`);
+
+    const result = await detectShadowsInSlice(tempDir);
+
+    expect(result).toEqual({ errors: '', failedFiles: [] });
+  });
+
+  it('detects shadow in a file and returns error with file path', async () => {
+    await writeFile(
+      path.join(tempDir, 'projection.ts'),
+      `import type { MyState } from './state';\ntype MyState = { name: string };\n`,
+    );
+
+    const result = await detectShadowsInSlice(tempDir);
+
+    expect(result).toEqual({
+      errors:
+        'CONTRACT VIOLATION in projection.ts: Types [MyState] are imported but redefined locally. Remove local definitions and use the imports.',
+      failedFiles: [path.join(tempDir, 'projection.ts')],
+    });
+  });
+
+  it('ignores spec files', async () => {
+    await writeFile(
+      path.join(tempDir, 'projection.specs.ts'),
+      `import type { MyState } from './state';\ntype MyState = { name: string };\n`,
+    );
+
+    const result = await detectShadowsInSlice(tempDir);
+
+    expect(result).toEqual({ errors: '', failedFiles: [] });
+  });
+
+  it('reports multiple files with shadows', async () => {
+    await writeFile(path.join(tempDir, 'a.ts'), `import type { Alpha } from './types';\ntype Alpha = { x: number };\n`);
+    await writeFile(path.join(tempDir, 'b.ts'), `import type { Beta } from './types';\ninterface Beta { y: string }\n`);
+
+    const result = await detectShadowsInSlice(tempDir);
+
+    expect(result.failedFiles).toEqual([path.join(tempDir, 'a.ts'), path.join(tempDir, 'b.ts')]);
+    expect(result.errors).toContain('CONTRACT VIOLATION in a.ts');
+    expect(result.errors).toContain('CONTRACT VIOLATION in b.ts');
+  });
+});

package/src/agent/runSlice.ts

@@ -5,6 +5,7 @@ import { generateText } from 'ai';
 import { execa } from 'execa';
 import fg from 'fast-glob';
 import { SYSTEM_PROMPT } from '../prompts/systemPrompt';
+import { buildShadowWarning } from '../utils/detectImportedTypeShadowing';
 import { extractCodeBlock } from '../utils/extractCodeBlock';
 import { runTests } from './runTests';
 
@@ -185,15 +186,34 @@ export async function runTestsAndTypecheck(sliceDir: string): Promise<TestAndTyp
   const rootDir = await findProjectRoot(sliceDir);
   const testResult = await runTests(sliceDir, rootDir);
   const typecheckResult = await runTypecheck(sliceDir, rootDir);
+  const shadowResult = await detectShadowsInSlice(sliceDir);
+  const failedTypecheckFiles = [...typecheckResult.failedTypecheckFiles, ...shadowResult.failedFiles];
+  const typecheckErrors = [typecheckResult.typecheckErrors, shadowResult.errors].filter(Boolean).join('\n');
+  const hasErrors = !testResult.success || !typecheckResult.success || shadowResult.errors.length > 0;
   return {
-    success: testResult.success && typecheckResult.success,
+    success: !hasErrors,
     failedTestFiles: testResult.failedTestFiles,
-    failedTypecheckFiles: typecheckResult.failedTypecheckFiles,
+    failedTypecheckFiles,
     testErrors: testResult.testErrors,
-    typecheckErrors: typecheckResult.typecheckErrors,
+    typecheckErrors,
   };
 }
 
+export async function detectShadowsInSlice(sliceDir: string): Promise<{ errors: string; failedFiles: string[] }> {
+  const files = await fg(['*.ts'], { cwd: sliceDir, ignore: ['*.spec.ts', '*.specs.ts', '*.test.ts'] });
+  const errors: string[] = [];
+  const failedFiles: string[] = [];
+  for (const file of files) {
+    const content = await readFile(path.join(sliceDir, file), 'utf-8');
+    const warning = buildShadowWarning(content, file);
+    if (warning.length > 0) {
+      errors.push(warning);
+      failedFiles.push(path.join(sliceDir, file));
+    }
+  }
+  return { errors: errors.join('\n'), failedFiles };
+}
+
 async function retryFailedTests(sliceDir: string, flow: string, result: TestAndTypecheckResult) {
   let contextFiles = await loadContextFiles(sliceDir);
   for (let attempt = 1; attempt <= 5; attempt++) {

package/src/commands/implement-slice.ts

@@ -6,6 +6,7 @@ import { createModelFromEnv } from '@auto-engineer/model-factory';
 import { generateText } from 'ai';
 import createDebug from 'debug';
 import fg from 'fast-glob';
+import { buildShadowWarning } from '../utils/detectImportedTypeShadowing';
 
 const debug = createDebug('auto:server-implementer:slice');
 const debugHandler = createDebug('auto:server-implementer:slice:handler');
@@ -259,6 +260,7 @@ function buildRetryPrompt(targetFile: string, context: Record<string, string>, p
   const sliceFiles = Object.entries(context).filter(
     ([name]) => name !== targetFile && name !== 'domain-shared-types.ts',
   );
+  const shadowWarning = buildShadowWarning(context[targetFile], targetFile);
 
   return `
 ${SYSTEM_PROMPT}
@@ -267,6 +269,7 @@ ${SYSTEM_PROMPT}
 The previous implementation needs adjustment based on this feedback:
 
 ${previousOutputs}
+${shadowWarning.length > 0 ? `\n🚨 ${shadowWarning}\n` : ''}
 
 📄 File to update: ${targetFile}
 

package/src/utils/detectImportedTypeShadowing.specs.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest';
+import { buildShadowWarning, detectImportedTypeShadowing } from './detectImportedTypeShadowing';
+
+describe('detectImportedTypeShadowing', () => {
+  it('returns empty array when no shadows exist', () => {
+    const code = `
+import type { MyState } from './state';
+const x = 1;
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual([]);
+  });
+
+  it('detects import type shadowed by local type alias', () => {
+    const code = `
+import type { MyState } from './state';
+type MyState = { name: string };
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual(['MyState']);
+  });
+
+  it('detects import type shadowed by local interface', () => {
+    const code = `
+import type { MyState } from './state';
+interface MyState { name: string }
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual(['MyState']);
+  });
+
+  it('does not flag interface with different name extending imported type', () => {
+    const code = `
+import type { MyState } from './state';
+interface InternalMyState extends MyState { extra: number }
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual([]);
+  });
+
+  it('returns only shadowed names when multiple types imported', () => {
+    const code = `
+import type { Alpha, Beta, Gamma } from './types';
+type Beta = { value: number };
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual(['Beta']);
+  });
+
+  it('handles multi-line imports', () => {
+    const code = `
+import type {
+  Alpha,
+  Beta,
+} from './types';
+type Alpha = { x: number };
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual(['Alpha']);
+  });
+
+  it('uses local name when import has alias', () => {
+    const code = `
+import type { Original as Renamed } from './types';
+type Renamed = { x: number };
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual(['Renamed']);
+  });
+
+  it('collects only per-specifier type imports from mixed import', () => {
+    const code = `
+import { type TypeOnly, ValueImport } from './module';
+type TypeOnly = { x: number };
+type ValueImport = { y: number };
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual(['TypeOnly']);
+  });
+
+  it('ignores type names inside comments', () => {
+    const code = `
+import type { MyState } from './state';
+// type MyState = { fake: true };
+/* type MyState = { also: false }; */
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual([]);
+  });
+
+  it('ignores type names inside string literals', () => {
+    const code = `
+import type { MyState } from './state';
+const s = "type MyState = { name: string }";
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual([]);
+  });
+
+  it('returns empty array when there are no imports', () => {
+    const code = `
+type LocalOnly = { x: number };
+interface AnotherLocal { y: string }
+`;
+    expect(detectImportedTypeShadowing(code)).toEqual([]);
+  });
+});
+
+describe('buildShadowWarning', () => {
+  it('returns empty string for clean code', () => {
+    const code = `
+import type { MyState } from './state';
+const x = 1;
+`;
+    expect(buildShadowWarning(code)).toBe('');
+  });
+
+  it('returns contract-violation string for shadowed code', () => {
+    const code = `
+import type { MyState } from './state';
+type MyState = { name: string };
+`;
+    const result = buildShadowWarning(code, 'projection.ts');
+    expect(result).toBe(
+      'CONTRACT VIOLATION in projection.ts: Types [MyState] are imported but redefined locally. Remove local definitions and use the imports.',
+    );
+  });
+
+  it('returns contract-violation without file path when not provided', () => {
+    const code = `
+import type { MyState } from './state';
+type MyState = { name: string };
+`;
+    const result = buildShadowWarning(code);
+    expect(result).toBe(
+      'CONTRACT VIOLATION: Types [MyState] are imported but redefined locally. Remove local definitions and use the imports.',
+    );
+  });
+});

package/src/utils/detectImportedTypeShadowing.ts

@@ -0,0 +1,47 @@
+import ts from 'typescript';
+
+export function detectImportedTypeShadowing(code: string): string[] {
+  const sourceFile = ts.createSourceFile('check.ts', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+
+  const importedTypeNames = new Set<string>();
+  const localTypeNames = new Set<string>();
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isImportDeclaration(statement)) {
+      const clause = statement.importClause;
+      if (clause === undefined) continue;
+      const namedBindings = clause.namedBindings;
+      if (namedBindings === undefined || !ts.isNamedImports(namedBindings)) continue;
+      const isWholeImportTypeOnly = clause.isTypeOnly;
+      for (const element of namedBindings.elements) {
+        if (isWholeImportTypeOnly || element.isTypeOnly) {
+          const localName = element.name.text;
+          importedTypeNames.add(localName);
+        }
+      }
+    }
+
+    if (ts.isTypeAliasDeclaration(statement)) {
+      localTypeNames.add(statement.name.text);
+    }
+
+    if (ts.isInterfaceDeclaration(statement)) {
+      localTypeNames.add(statement.name.text);
+    }
+  }
+
+  const shadows: string[] = [];
+  for (const name of importedTypeNames) {
+    if (localTypeNames.has(name)) {
+      shadows.push(name);
+    }
+  }
+  return shadows;
+}
+
+export function buildShadowWarning(code: string, filePath?: string): string {
+  const shadows = detectImportedTypeShadowing(code);
+  if (shadows.length === 0) return '';
+  const location = filePath !== undefined ? ` in ${filePath}` : '';
+  return `CONTRACT VIOLATION${location}: Types [${shadows.join(', ')}] are imported but redefined locally. Remove local definitions and use the imports.`;
+}