@auto-engineer/component-implementor-react 1.102.0 → 1.103.0

package/src/prompt.ts

@@ -90,7 +90,12 @@ RULES
 10. **Import paths.** Import composed UI components using the exact paths shown in the **Composed Components** section of the project context. Import utility functions from \`@/lib/utils\` (e.g. \`import { cn } from '@/lib/utils'\`). NEVER use made-up package names like \`'your-design-system'\`, \`'@company/ui'\`, or \`'@acme/components'\`. NEVER guess import paths — only use paths explicitly provided in the prompt.
 11. **Code only.** Return ONLY the component file code. No markdown fences, no commentary, no file names.
 12. **Numeric formatting.** Use the \`tabular-nums\` Tailwind class on all numeric displays (prices, counts, statistics). Use \`Intl.NumberFormat\` for currency formatting rather than string template literals with \`$\`.
-13. **Type imports for composed component props.** When you need to reference a composed component's prop type (e.g. to type an array of items), use \`import type { XProps } from '...'\` with the exact import path from the Composed Components section. Never reference a type without importing it.`;
+13. **Type imports for composed component props.** When you need to reference a composed component's prop type (e.g. to type an array of items), use \`import type { XProps } from '...'\` with the exact import path from the Composed Components section. Never reference a type without importing it.
+14. **Strict package boundary.** You may ONLY import from packages listed in the project's \`package.json\` dependencies/devDependencies and from local \`@/\` paths shown in the project context. Do NOT import from any other npm package — even well-known ones. If the spec implies behavior that would normally require an external package (routing, data fetching, animations, icons), implement it with plain React, callback props, and CSS/Tailwind instead.
+15. **UI components from barrel only.** Import UI components ONLY from \`@/components/ui\` using the exact export names shown in the barrel file (\`src/components/ui/index.ts\`). Do NOT import UI components that aren't listed in the barrel. Do NOT guess component names — if a UI component isn't in the barrel, build the equivalent with plain HTML + Tailwind.
+16. **Page components use callback props for navigation.** Never import a router library. Implement navigation via callback props (e.g. \`onNavigate?: (path: string) => void\`) and render \`<a>\` tags or \`<button>\` elements that call the callback. The project does not include a router.
+17. **Controlled input initialization.** When using \`useState\` for form input values, always initialize text/number inputs with an empty string (\`useState('')\`), never \`undefined\` or \`null\`. Inputs with \`value={undefined}\` become uncontrolled and return \`null\` from \`.value\`, which breaks \`toHaveValue('')\` assertions.
+18. **Array keys without indices.** Never use the \`.map()\` callback index parameter as a React key — not directly (\`key={i}\`) nor inside a template literal (\`key={\\\`item-\\\${i}\\\`}\`). Biome's \`noArrayIndexKey\` rule flags both forms. For data items, use a unique property (\`key={item.id}\`). For generated placeholders (skeletons, spacers), pre-compute an ID array outside the JSX: \`const ids = Array.from({ length: count }, (_, i) => \\\`placeholder-\\\${i}\\\`)\`, then \`ids.map(id => <div key={id}>…</div>)\`.`;
 
 const COMPONENT_CHECKLIST = `─────────────────────────────────────────────
 QUALITY CHECKLIST
@@ -108,7 +113,9 @@ Before returning, verify:
 - [ ] Existing component behavior is preserved when modifying
 - [ ] Numeric values use tabular-nums and Intl.NumberFormat for currency
 - [ ] forwardRef uses \`export const X = React.forwardRef(...)\` syntax, never \`export function X = forwardRef(...)\`
-- [ ] All referenced types from composed components are imported with \`import type { ... }\``;
+- [ ] All referenced types from composed components are imported with \`import type { ... }\`
+- [ ] Form input \`useState\` calls are initialized with \`''\`, not \`undefined\` or \`null\`
+- [ ] No \`.map()\` callback index parameter used as a React key (directly or in template literals)`;
 
 export const componentPromptSections = {
   PREAMBLE: COMPONENT_PREAMBLE,
@@ -205,7 +212,13 @@ RULES
 9. **Test descriptions mirror specs.** Use spec language directly in test descriptions so traceability is obvious.
 10. **Code only.** Return ONLY the test file code. No markdown fences, no commentary, no file names.
 11. **Tailwind classes, not inline styles.** The project uses Tailwind CSS. In JSDOM, Tailwind utility classes are just class names — they do NOT produce computed inline styles. Use \`toHaveClass('class-name')\` for class-based assertions. NEVER use \`toHaveStyle()\` for Tailwind utilities like \`tabular-nums\`, \`touch-manipulation\`, \`min-w-[44px]\`, etc. For hover states, transforms, transitions, and pseudo-elements — JSDOM cannot compute these. Skip those assertions entirely.
-12. **Verify semantic elements from component source.** Some UI library components use unexpected elements (e.g., CardTitle renders a \`<div>\`, not a heading). If composed component source code is provided, check the actual rendered element before choosing your query strategy. Prefer \`getByText\` when the semantic element is uncertain.`;
+12. **Verify semantic elements from component source.** Some UI library components use unexpected elements (e.g., CardTitle renders a \`<div>\`, not a heading). If composed component source code is provided, check the actual rendered element before choosing your query strategy. Prefer \`getByText\` when the semantic element is uncertain.
+13. **Strict package boundary.** Only import from \`vitest\`, \`@testing-library/react\`, \`@testing-library/user-event\`, and the component under test (via \`./ComponentName\`). Never import \`@testing-library/dom\` or any other \`@testing-library/*\` sub-package. Do NOT import any other npm package. Do NOT import other components (siblings, composed components, UI components) — only import the one component you are testing.
+14. **jsdom limitations.** Tests run in jsdom, which does NOT support: \`DataTransfer\`, \`ClipboardEvent\`, \`IntersectionObserver\`, \`ResizeObserver\`, \`window.matchMedia\`, \`getBoundingClientRect\` returning real dimensions, CSS computed styles, \`scrollIntoView\`, or HTML5 drag-and-drop events (\`dragstart\`, \`drop\`). Do NOT write tests that depend on these APIs. For drag-and-drop specs, test the callbacks directly (e.g. call \`onDrop\` with mock data) instead of simulating drag events. For scroll-to-bottom specs, test that the scroll container ref exists rather than asserting \`scrollIntoView\` was called. For specs requiring unavailable APIs, test the closest observable behavior that jsdom supports.
+15. **Test Tailwind classes individually.** When asserting CSS classes, use separate \`toHaveClass\` calls for each important class: \`expect(el).toHaveClass('rounded-md')\`, \`expect(el).toHaveClass('shadow-sm')\`. Do NOT assert the entire class string as one value — the component may include additional utility classes. Focus on the classes that the spec explicitly mentions.
+16. **Mock composed components.** If the component under test composes other project components (not built-in HTML elements), mock them with \`vi.mock\` so tests are isolated. Mock pattern: \`vi.mock('./ChildComponent', () => ({ ChildComponent: ({ children, ...rest }: Record<string, unknown>) => <div data-testid="child-component">{children as React.ReactNode}</div> }))\`. Do NOT spread props (\`{...props}\`) onto the mock div — callback functions are not valid DOM attributes. When testing a page or container that mocks its children, only test the page's own rendering (loading text, error messages, layout containers). Do NOT query for interactive elements (buttons, inputs) that only exist inside the real (unmocked) children. When asserting props passed to a mocked component, NEVER use \`toHaveBeenCalledWith\` — React passes \`(props, ref)\` where \`ref\` is \`undefined\` for non-forwardRef components, and \`expect.anything()\` does NOT match \`undefined\`. Instead, access mock calls directly: \`const [props] = MockChild.mock.calls[0]; expect(props).toMatchObject({...});\`. This is mandatory for ALL mock component prop assertions.
+17. **vi.mock factory hoisting.** \`vi.mock\` calls are hoisted to the top of the file by vitest. This means the factory function cannot reference any variables declared in the test file scope (imports, constants, etc.). Keep mock factories self-contained — define all needed values inline within the factory. If you need to spy on the mock, import it after the \`vi.mock\` call.
+18. **Semantic HTML role mapping.** When querying elements with \`getByRole\`, use the correct ARIA role, not the HTML tag name. Common mappings: \`<section>\` has role="region" (only when it has an accessible name via \`aria-label\` or \`aria-labelledby\` — otherwise it has NO implicit role and you must use a different query like \`getByTestId\`). \`<article>\` → \`"article"\`, \`<nav>\` → \`"navigation"\`, \`<aside>\` → \`"complementary"\`, \`<header>\` → \`"banner"\`, \`<footer>\` → \`"contentinfo"\`, \`<main>\` → \`"main"\`. There is NO role called \`"section"\` — never use \`getByRole('section')\`.`;
 
 const TEST_CHECKLIST = `─────────────────────────────────────────────
 QUALITY CHECKLIST
@@ -558,7 +571,7 @@ export function buildComponentPrompt(input: ComponentPromptInput): PromptResult
   }
 
   if (input.projectSection) {
-    parts.push('\n\n' + input.projectSection);
+    parts.push(`\n\n${input.projectSection}`);
   }
 
   return {
@@ -583,7 +596,7 @@ export function buildTestPrompt(input: TestPromptInput): PromptResult {
   }
 
   if (input.projectSection) {
-    parts.push('\n\n' + input.projectSection);
+    parts.push(`\n\n${input.projectSection}`);
   }
 
   return {
@@ -613,7 +626,7 @@ export function buildStoryPrompt(input: StoryPromptInput): PromptResult {
   }
 
   if (input.projectSection) {
-    parts.push('\n\n' + input.projectSection);
+    parts.push(`\n\n${input.projectSection}`);
   }
 
   return {
@@ -653,7 +666,7 @@ export function buildReconcilerPrompt(input: ReconcilerPromptInput): PromptResul
   parts.push('```');
 
   if (input.projectSection) {
-    parts.push('\n\n' + input.projectSection);
+    parts.push(`\n\n${input.projectSection}`);
   }
 
   return {
@@ -725,7 +738,13 @@ Rules:
 - Only modify the test if it has a genuine bug (e.g. wrong import path, typo in query). Never weaken assertions.
 - Make minimal changes to pass the failing tests without breaking passing ones.
 - Return complete files, not diffs.
-- No commentary, no explanations. Just the two code blocks.`;
+- No commentary, no explanations. Just the two code blocks.
+- **Unresolvable imports.** If the error is "Failed to resolve import" for a package (e.g. react-router-dom, lucide-react, @tanstack/react-query), that package is NOT installed. Fix both the component and test by removing the unavailable import entirely and rewriting the code to work without it. Replace router hooks with callback props, replace icon components with inline \`<span>\` or \`<svg>\` elements, replace data-fetching hooks with props.
+- **Missing UI component imports.** If the error is "Failed to resolve import" for a \`@/components/ui/*\` path, that UI component does not exist in the project. Remove the import and replace usage with plain HTML elements + Tailwind classes that provide equivalent functionality.
+- **vi.mock hoisting errors.** If the error mentions "vi.mock" and "hoisted to top of the file", the mock factory references variables from the file scope. Fix by inlining all values within the factory function — do not reference imports, constants, or variables declared outside the factory.
+- **Mock spy argument count mismatch.** If a \`toHaveBeenCalledWith\` assertion on a mocked component fails because of an extra \`undefined\` argument, React is passing \`(props, ref)\` where \`ref\` is \`undefined\`. \`expect.anything()\` does NOT match \`undefined\`, so do NOT use it. Fix the TEST: replace \`toHaveBeenCalledWith\` with direct mock call access: \`const [props] = MockedComponent.mock.calls[0]; expect(props).toMatchObject({...});\`.
+- **toHaveStyle() failures.** jsdom does NOT compute CSS from Tailwind classes. If a \`toHaveStyle()\` assertion fails because the received style is empty or missing, replace \`expect(el).toHaveStyle({prop: value})\` with \`expect(el).toHaveClass('tailwind-class')\` using the corresponding Tailwind utility class. Never use \`toHaveStyle()\` in jsdom tests.
+- **ReferenceError on mocked component.** If the error is \`ReferenceError: X is not defined\` and X is a component that was mocked with \`vi.mock\`, the test is accessing \`X.mock.calls\` without importing X. Add the import after the \`vi.mock\` call: \`import { X } from './X';\` — vitest resolves this to the mock.`;
 
 export interface TestFixInput {
   componentCode: string;
@@ -779,7 +798,8 @@ Rules:
 - Fix ONLY the lint errors listed. Do not refactor unrelated code.
 - Preserve all behavior and functionality.
 - Return complete files, not diffs.
-- No commentary, no explanations. Just the two code blocks.`;
+- No commentary, no explanations. Just the two code blocks.
+- **noArrayIndexKey.** If the error is \`lint/suspicious/noArrayIndexKey\`, the \`.map()\` callback index is used as a React key — either directly (\`key={i}\`) or inside a template literal (\`key={\\\`prefix-\\\${i}\\\`}\`). Both are flagged by Biome. Fix by using a unique property from the item data (\`key={item.id}\`). If no \`id\` field exists, use another unique item property (\`key={item.title}\`). For generated arrays (skeletons, placeholders) where items have no unique property, pre-compute IDs outside JSX: \`const ids = Array.from({ length: n }, (_, i) => \\\`skeleton-\\\${i}\\\`)\`, then \`ids.map(id => <div key={id}>…</div>)\` — this moves the index out of the \`.map()\` callback.`;
 
 export interface LintFixInput {
   componentCode: string;

package/src/tools/lint-runner.test.ts

@@ -14,7 +14,7 @@ describe('runLint', () => {
     const result = runLint(['src/Button.tsx'], '/project');
 
     expect(result).toEqual({ passed: true, errors: [] });
-    expect(execSync).toHaveBeenCalledWith('npx biome check src/Button.tsx', {
+    expect(execSync).toHaveBeenCalledWith('npx biome check --config-path=/project/biome.json src/Button.tsx', {
       cwd: '/project',
       stdio: 'pipe',
       encoding: 'utf-8',
@@ -43,11 +43,10 @@ describe('runLint', () => {
 
     runLint(['src/Button.tsx', 'src/Button.test.tsx'], '/project');
 
-    expect(execSync).toHaveBeenCalledWith('npx biome check src/Button.tsx src/Button.test.tsx', {
-      cwd: '/project',
-      stdio: 'pipe',
-      encoding: 'utf-8',
-    });
+    expect(execSync).toHaveBeenCalledWith(
+      'npx biome check --config-path=/project/biome.json src/Button.tsx src/Button.test.tsx',
+      { cwd: '/project', stdio: 'pipe', encoding: 'utf-8' },
+    );
   });
 });
 
@@ -58,7 +57,7 @@ describe('runLintFix', () => {
     const result = runLintFix(['src/Button.tsx'], '/project');
 
     expect(result).toEqual({ passed: true, errors: [] });
-    expect(execSync).toHaveBeenCalledWith('npx biome check --write src/Button.tsx', {
+    expect(execSync).toHaveBeenCalledWith('npx biome check --write --config-path=/project/biome.json src/Button.tsx', {
       cwd: '/project',
       stdio: 'pipe',
       encoding: 'utf-8',

package/src/tools/lint-runner.ts

@@ -1,13 +1,19 @@
 import { execSync } from 'node:child_process';
+import path from 'node:path';
 
 export type LintResult = {
   passed: boolean;
   errors: string[];
 };
 
+function biomeCmd(action: string, filePaths: string[], targetDir: string): string {
+  const configPath = path.resolve(targetDir, 'biome.json');
+  return `npx biome ${action} --config-path=${configPath} ${filePaths.join(' ')}`;
+}
+
 export function runLint(filePaths: string[], targetDir: string): LintResult {
   try {
-    execSync(`npx biome check ${filePaths.join(' ')}`, {
+    execSync(biomeCmd('check', filePaths, targetDir), {
       cwd: targetDir,
       stdio: 'pipe',
       encoding: 'utf-8',
@@ -20,7 +26,7 @@ export function runLint(filePaths: string[], targetDir: string): LintResult {
       if ('stdout' in err && typeof err.stdout === 'string') stdout = err.stdout;
       if ('stderr' in err && typeof err.stderr === 'string') stderr = err.stderr;
     }
-    const combined = stdout + '\n' + stderr;
+    const combined = `${stdout}\n${stderr}`;
 
     const errors = combined.split('\n').filter((line) => line.trim().length > 0);
 
@@ -30,7 +36,7 @@ export function runLint(filePaths: string[], targetDir: string): LintResult {
 
 export function runLintFix(filePaths: string[], targetDir: string): LintResult {
   try {
-    execSync(`npx biome check --write ${filePaths.join(' ')}`, {
+    execSync(biomeCmd('check --write', filePaths, targetDir), {
       cwd: targetDir,
       stdio: 'pipe',
       encoding: 'utf-8',
@@ -43,7 +49,7 @@ export function runLintFix(filePaths: string[], targetDir: string): LintResult {
       if ('stdout' in err && typeof err.stdout === 'string') stdout = err.stdout;
       if ('stderr' in err && typeof err.stderr === 'string') stderr = err.stderr;
     }
-    const combined = stdout + '\n' + stderr;
+    const combined = `${stdout}\n${stderr}`;
 
     const errors = combined.split('\n').filter((line) => line.trim().length > 0);
 

package/src/tools/test-runner.test.ts

@@ -102,13 +102,13 @@ describe('runTests', () => {
     });
   });
 
-  it('truncates output to 2000 chars', () => {
-    const longOutput = JSON.stringify({ testResults: [] }) + 'x'.repeat(3000);
+  it('truncates output to 4000 chars', () => {
+    const longOutput = JSON.stringify({ testResults: [] }) + 'x'.repeat(5000);
     vi.mocked(execSync).mockReturnValue(longOutput);
 
     const result = runTests('src/Button.test.tsx', '/project');
 
-    expect(result.output.length).toBeLessThanOrEqual(2000);
+    expect(result.output.length).toBeLessThanOrEqual(4000);
   });
 
   it('handles error object without stdout or stderr properties', () => {
@@ -197,6 +197,58 @@ describe('runTests', () => {
     });
   });
 
+  it('captures suite-level error when assertionResults is empty but suite failed', () => {
+    const json = JSON.stringify({
+      testResults: [
+        {
+          status: 'failed',
+          message: 'Failed to collect tests: Cannot find module @testing-library/jest-dom/vitest',
+          assertionResults: [],
+        },
+      ],
+    });
+    vi.mocked(execSync).mockReturnValue(json);
+
+    const result = runTests('src/Button.test.tsx', '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      numPassed: 0,
+      numFailed: 1,
+      failures: ['Suite error: Failed to collect tests: Cannot find module @testing-library/jest-dom/vitest'],
+      output: expect.any(String),
+    });
+  });
+
+  it('does not capture suite-level error when assertionResults already has failures', () => {
+    const json = JSON.stringify({
+      testResults: [
+        {
+          status: 'failed',
+          message: 'Some suite message',
+          assertionResults: [
+            {
+              status: 'failed',
+              fullName: 'test one',
+              failureMessages: ['assertion failed'],
+            },
+          ],
+        },
+      ],
+    });
+    vi.mocked(execSync).mockReturnValue(json);
+
+    const result = runTests('src/Button.test.tsx', '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      numPassed: 0,
+      numFailed: 1,
+      failures: ['test one: assertion failed'],
+      output: expect.any(String),
+    });
+  });
+
   it('handles malformed JSON after opening brace', () => {
     vi.mocked(execSync).mockReturnValue('prefix {invalid json');
 

package/src/tools/test-runner.ts

@@ -25,7 +25,7 @@ export function runTests(testFilePath: string, targetDir: string): TestRunResult
       if ('stdout' in err && typeof err.stdout === 'string') stdout = err.stdout;
       if ('stderr' in err && typeof err.stderr === 'string') stderr = err.stderr;
     }
-    const combined = stdout + '\n' + stderr;
+    const combined = `${stdout}\n${stderr}`;
 
     const parsed = parseVitestJson(combined);
     return parsed;
@@ -40,7 +40,7 @@ function parseVitestJson(output: string): TestRunResult {
       numPassed: 0,
       numFailed: 0,
       failures: [],
-      output: output.slice(0, 2000),
+      output: output.slice(0, 4000),
     };
   }
 
@@ -63,6 +63,10 @@ function parseVitestJson(output: string): TestRunResult {
           failures.push(`${name}: ${message}`);
         }
       }
+      if (suite.status === 'failed' && suite.message && failures.length === 0) {
+        failures.push(`Suite error: ${suite.message}`);
+        numFailed++;
+      }
     }
 
     return {
@@ -70,7 +74,7 @@ function parseVitestJson(output: string): TestRunResult {
       numPassed,
       numFailed,
       failures,
-      output: output.slice(0, 2000),
+      output: output.slice(0, 4000),
     };
   } catch {
     return {
@@ -78,7 +82,7 @@ function parseVitestJson(output: string): TestRunResult {
       numPassed: 0,
       numFailed: 0,
       failures: [],
-      output: output.slice(0, 2000),
+      output: output.slice(0, 4000),
     };
   }
 }