@auto-engineer/component-implementor-react 1.98.0 → 1.100.0

package/src/prompt.ts

@@ -64,14 +64,21 @@ Name props to match the spec language directly. If the spec says "shows loading
 ### Phase 3 — Implement the component body
 Build the JSX tree to satisfy structure specs. Add conditional rendering for rendering specs. Wire event handlers for interaction specs. Apply Tailwind classes for styling specs.
 
-### Phase 4 — Verify completeness
+### Phase 4 — Align with the test file
+If a test file is provided, it is the **source of truth**. Your component must pass every test. Read each test case and ensure:
+- Your export name matches the test's import
+- Your prop names match exactly what the tests pass
+- Your rendered elements match what the tests query (getByRole, getByText)
+- Your event handlers fire the callbacks the tests assert
+
+### Phase 5 — Verify completeness
 Walk through each spec delta and confirm the implementation covers it. Every spec string must trace to a specific line of code.`;
 
 const COMPONENT_RULES = `─────────────────────────────────────────────
 RULES
 ─────────────────────────────────────────────
 
-1. **Functional components only.** Use \`function ComponentName\` with TypeScript. No class components.
+1. **Functional components only.** Use \`function ComponentName\` with TypeScript. No class components. When the spec requires \`forwardRef\`, use \`export const ComponentName = React.forwardRef<HTMLElement, ComponentNameProps>(function ComponentName(props, ref) { ... })\` — never write \`export function ComponentName = forwardRef(...)\` (that is invalid syntax).
 2. **Named exports.** Export the component as a named export. Export the Props type. No default exports.
 3. **Tailwind CSS.** Use Tailwind utility classes for all styling. No inline styles, no CSS modules, no styled-components.
 4. **ARIA roles.** Use semantic HTML elements and ARIA attributes for accessibility. If a spec implies a role (button, dialog, alert), use the correct element or role attribute.
@@ -80,7 +87,10 @@ RULES
 7. **No side effects.** No fetch calls, no localStorage, no timers unless a spec explicitly requires them.
 8. **No unnecessary state.** Derive from props where possible. Only use \`useState\` when the component genuinely manages internal state per spec.
 9. **Composition-ready.** If structure specs mention slots or regions, accept them as children or named props (e.g. \`header\`, \`footer\`).
-10. **Code only.** Return ONLY the component file code. No markdown fences, no commentary, no file names.`;
+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.`;
 
 const COMPONENT_CHECKLIST = `─────────────────────────────────────────────
 QUALITY CHECKLIST
@@ -95,7 +105,10 @@ Before returning, verify:
 - [ ] Component is exported as a named export
 - [ ] ARIA roles and semantic elements are used where specs imply them
 - [ ] No dead code or unused imports
-- [ ] Existing component behavior is preserved when modifying`;
+- [ ] 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 { ... }\``;
 
 export const componentPromptSections = {
   PREAMBLE: COMPONENT_PREAMBLE,
@@ -190,7 +203,9 @@ RULES
 7. **No implementation testing.** Test behavior, not implementation details. Do not assert on internal state, hook calls, or component instance methods.
 8. **Async awareness.** Use \`waitFor\` or \`findBy*\` queries when specs involve async behavior (loading states, delayed rendering).
 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.`;
+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.`;
 
 const TEST_CHECKLIST = `─────────────────────────────────────────────
 QUALITY CHECKLIST
@@ -253,13 +268,24 @@ const STORY_OUTPUT_FORMAT = `─────────────────
 YOUR OUTPUT — A SINGLE .stories.tsx FILE
 ─────────────────────────────────────────────
 
-Return a single Storybook story file using CSF3 format. The file must contain:
+Return a single Storybook story file using CSF3 format. Follow this exact file structure:
 
-1. Import \`Meta\` and \`StoryObj\` types from \`@storybook/react\`
-2. Import the component as a named import from \`./ComponentName\`
-3. A \`meta\` object (typed as \`Meta<typeof ComponentName>\`) as the default export
-4. Named story exports typed as \`StoryObj<typeof ComponentName>\`
-5. At minimum: a \`Default\` story plus one story per distinct visual/behavioral state`;
+\`\`\`
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ComponentName } from '<import path from Component Import Path section>';
+
+const meta: Meta<typeof ComponentName> = {
+  title: 'UI Components/ComponentName',
+  component: ComponentName,
+};
+export default meta;            // ← REQUIRED — Storybook crashes without this line
+
+type Story = StoryObj<typeof ComponentName>;
+
+export const Default: Story = { args: { ... } };
+\`\`\`
+
+CRITICAL: The \`export default meta;\` line is **mandatory**. Without it Storybook will crash. Never omit it.`;
 
 const STORY_METHODOLOGY = `─────────────────────────────────────────────
 METHODOLOGY
@@ -284,16 +310,20 @@ const STORY_RULES = `───────────────────
 RULES
 ─────────────────────────────────────────────
 
-1. **CSF3 format.** Use \`export default meta\` and named story exports. No CSF2 \`Template.bind({})\` pattern.
-2. **Named import.** Import the component as \`import { ComponentName } from './ComponentName'\`.
-3. **Type annotations.** Type meta as \`Meta<typeof ComponentName>\` and stories as \`StoryObj<typeof ComponentName>\`.
-4. **Prop names from spec language.** Use the exact prop names implied by the spec, matching the component and test agents.
-5. **Args over render.** Prefer \`args: { ... }\` over custom \`render\` functions. Use \`render\` only when you need to wrap the component or demonstrate interaction.
-6. **Action callbacks.** Use \`action('onEventName')\` from \`@storybook/addon-actions\` for callback props, or simply omit them if not critical to the story.
-7. **Descriptive story names.** PascalCase names that describe the state: \`Loading\`, \`Empty\`, \`WithLongContent\`, \`Disabled\`, \`ErrorState\`.
-8. **Default story first.** Always include a \`Default\` story that shows the component in its most common/ready state.
-9. **No mock data in meta.** Put shared default args in \`meta.args\` only if they apply to all stories.
-10. **Code only.** Return ONLY the story file code. No markdown fences, no commentary, no file names.`;
+1. **CSF3 format with default export.** You MUST include \`export default meta;\` — Storybook crashes without it. Use named story exports. No CSF2 \`Template.bind({})\` pattern.
+2. **Storybook imports.** Import types from \`@storybook/react-vite\`: \`import type { Meta, StoryObj } from '@storybook/react-vite'\`. NEVER import from \`@storybook/react\` — that package is not installed.
+3. **Component import path.** Import the component using the exact path specified in the **Component Import Path** section of the user prompt. NEVER use relative imports like \`./ComponentName\` and NEVER guess the import path.
+4. **Type annotations.** Type meta as \`Meta<typeof ComponentName>\`, then define \`type Story = StoryObj<typeof ComponentName>\` and use \`Story\` for all story exports.
+5. **Prop names from spec language.** Use the exact prop names implied by the spec, matching the component and test agents.
+6. **Args over render.** Prefer \`args: { ... }\` over custom \`render\` functions. Use \`render\` only when you need to wrap the component or demonstrate composition with other components.
+7. **No action() or addon imports.** Do NOT import \`action\` from \`@storybook/addon-actions\` or \`fn\` from \`@storybook/test\` — these packages are not installed. For callback props, simply omit them from args (Storybook auto-detects and logs them), or use inline arrow functions like \`() => {}\`.
+8. **Descriptive story names.** PascalCase names that describe the state: \`Loading\`, \`Empty\`, \`WithLongContent\`, \`Disabled\`, \`ErrorState\`.
+9. **Default story first.** Always include a \`Default\` story that shows the component in its most common/ready state.
+10. **1-3 stories maximum.** Keep it minimal: a \`Default\` story, plus at most 1-2 additional stories for the most important visual states (e.g. a key variant or a loading state). Do NOT create a story for every single prop combination — focus on what a designer needs to see at a glance.
+11. **Meta fields.** Set \`title: 'UI Components/ComponentName'\` and \`component: ComponentName\` in meta. Both are required.
+12. **No mock data in meta.** Put shared default args in \`meta.args\` only if they apply to all stories.
+13. **Composed component imports.** When a story needs other UI components (e.g. for a \`render\` function demonstrating composition), import them using the exact paths shown in the **Composed Components** section of the project context. NEVER guess import paths.
+14. **Code only.** Return ONLY the story file code. No markdown fences, no commentary, no file names.`;
 
 const STORY_CHECKLIST = `─────────────────────────────────────────────
 QUALITY CHECKLIST
@@ -305,9 +335,15 @@ Before returning, verify:
 - [ ] Every styling variant (size, color, emphasis) has a dedicated story
 - [ ] Story names are descriptive PascalCase
 - [ ] Args use prop names that match spec language
-- [ ] Meta has correct component reference and title
+- [ ] Meta has correct component reference and \`title: 'UI Components/ComponentName'\`
+- [ ] \`export default meta;\` is present (Storybook crashes without it)
+- [ ] Meta has \`component: ComponentName\` field
 - [ ] CSF3 format is used throughout
-- [ ] No unnecessary render functions — args suffice where possible`;
+- [ ] No unnecessary render functions — args suffice where possible
+- [ ] Imports use \`@storybook/react-vite\` (NOT \`@storybook/react\`)
+- [ ] Component imported using the exact path from the **Component Import Path** section (NOT relative path, NOT guessed)
+- [ ] No \`action()\` from \`@storybook/addon-actions\` — omit callbacks or use inline arrows
+- [ ] No imports from \`@storybook/test\` — \`fn()\`, \`userEvent\`, \`expect()\` are not available`;
 
 export const storyPromptSections = {
   PREAMBLE: STORY_PREAMBLE,
@@ -464,17 +500,23 @@ export interface ComponentPromptInput {
   componentName: string;
   specDeltas: SpecDeltas;
   existingComponent?: string;
+  projectSection: string;
+  testCode?: string;
 }
 
 export interface TestPromptInput {
   componentName: string;
   specDeltas: SpecDeltas;
   existingComponent?: string;
+  projectSection: string;
 }
 
 export interface StoryPromptInput {
   componentName: string;
   specDeltas: SpecDeltas;
+  projectSection: string;
+  componentCode?: string;
+  componentImportPath: string;
 }
 
 export interface ReconcilerPromptInput {
@@ -484,6 +526,7 @@ export interface ReconcilerPromptInput {
   testCode: string;
   storyCode: string;
   existingComponent?: string;
+  projectSection: string;
 }
 
 export function buildComponentPrompt(input: ComponentPromptInput): PromptResult {
@@ -501,6 +544,23 @@ export function buildComponentPrompt(input: ComponentPromptInput): PromptResult
     parts.push('```');
   }
 
+  if (input.testCode) {
+    parts.push('\n\n## Test File (source of truth — your component MUST pass every test)\n');
+    parts.push('The test file below was generated first and is immutable. Study it carefully:');
+    parts.push('- Match the exact export name the tests import');
+    parts.push('- Accept every prop the tests pass (with exact names)');
+    parts.push('- Render elements the tests query (getByRole, getByText)');
+    parts.push('- Wire event handlers the tests fire (fireEvent.click → onClick prop)');
+    parts.push('- Produce the conditional rendering the tests expect\n');
+    parts.push('```tsx');
+    parts.push(input.testCode);
+    parts.push('```');
+  }
+
+  if (input.projectSection) {
+    parts.push('\n\n' + input.projectSection);
+  }
+
   return {
     system: buildComponentSystemPrompt(),
     prompt: parts.join('\n'),
@@ -522,6 +582,10 @@ export function buildTestPrompt(input: TestPromptInput): PromptResult {
     parts.push('```');
   }
 
+  if (input.projectSection) {
+    parts.push('\n\n' + input.projectSection);
+  }
+
   return {
     system: buildTestSystemPrompt(),
     prompt: parts.join('\n'),
@@ -535,9 +599,23 @@ export function buildStoryPrompt(input: StoryPromptInput): PromptResult {
     `Write Storybook stories for the React component **${input.componentName}** from the following spec deltas.\n`,
   );
 
+  parts.push('## Component Import Path\n');
+  parts.push(`Import the component as: \`import { ${input.componentName} } from '${input.componentImportPath}'\`\n`);
+
   parts.push('## Spec Deltas\n');
   parts.push(buildSpecText(input.specDeltas));
 
+  if (input.componentCode) {
+    parts.push('\n\n## Component Code (use this as the source of truth for props, exports, and types)\n');
+    parts.push('```tsx');
+    parts.push(input.componentCode);
+    parts.push('```');
+  }
+
+  if (input.projectSection) {
+    parts.push('\n\n' + input.projectSection);
+  }
+
   return {
     system: buildStorySystemPrompt(),
     prompt: parts.join('\n'),
@@ -574,8 +652,208 @@ export function buildReconcilerPrompt(input: ReconcilerPromptInput): PromptResul
   parts.push(input.storyCode);
   parts.push('```');
 
+  if (input.projectSection) {
+    parts.push('\n\n' + input.projectSection);
+  }
+
   return {
     system: buildReconcilerSystemPrompt(),
     prompt: parts.join('\n'),
   };
 }
+
+// ═══════════════════════════════════════════════════════════════════
+// TYPE FIXER — fixes TypeScript compilation errors
+// ═══════════════════════════════════════════════════════════════════
+
+const TYPE_FIX_SYSTEM = `You are a TypeScript error fixer. You receive a React component file, its test file, and TypeScript compiler errors. Your job is to make minimal surgical changes to fix the type errors.
+
+Return EXACTLY two code blocks:
+1. First block: the fixed component file
+2. Second block: the fixed test file
+
+Rules:
+- Fix ONLY the errors listed. Do not refactor or improve unrelated code.
+- Preserve all existing behavior and functionality.
+- Prefer fixing the component over the test (test is source of truth).
+- If a type error is in the test, only fix it if the test has an import/type mismatch — never change test behavior.
+- Return complete files, not diffs.
+- No commentary, no explanations. Just the two code blocks.`;
+
+export interface TypeFixInput {
+  componentCode: string;
+  testCode: string;
+  errors: string[];
+}
+
+export function buildTypeFixPrompt(input: TypeFixInput): PromptResult {
+  const parts: string[] = [];
+
+  parts.push('## TypeScript Errors\n');
+  parts.push('```');
+  parts.push(input.errors.join('\n'));
+  parts.push('```');
+
+  parts.push('\n\n## Component Code\n');
+  parts.push('```tsx');
+  parts.push(input.componentCode);
+  parts.push('```');
+
+  parts.push('\n\n## Test Code\n');
+  parts.push('```tsx');
+  parts.push(input.testCode);
+  parts.push('```');
+
+  return {
+    system: TYPE_FIX_SYSTEM,
+    prompt: parts.join('\n'),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// TEST FIXER — fixes test failures by adjusting the component
+// ═══════════════════════════════════════════════════════════════════
+
+const TEST_FIX_SYSTEM = `You are a test failure fixer. You receive a React component, its test file, and vitest failure output. The test is the source of truth — fix the component to pass the tests.
+
+Return EXACTLY two code blocks:
+1. First block: the fixed component file
+2. Second block: the fixed test file (usually unchanged)
+
+Rules:
+- The test file is the source of truth. Prefer fixing the component.
+- 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.`;
+
+export interface TestFixInput {
+  componentCode: string;
+  testCode: string;
+  failures: string[];
+  testOutput: string;
+}
+
+export function buildTestFixPrompt(input: TestFixInput): PromptResult {
+  const parts: string[] = [];
+
+  parts.push('## Test Failures\n');
+  for (const failure of input.failures) {
+    parts.push('```');
+    parts.push(failure);
+    parts.push('```\n');
+  }
+
+  parts.push('\n## Test Output\n');
+  parts.push('```');
+  parts.push(input.testOutput);
+  parts.push('```');
+
+  parts.push('\n\n## Component Code\n');
+  parts.push('```tsx');
+  parts.push(input.componentCode);
+  parts.push('```');
+
+  parts.push('\n\n## Test Code\n');
+  parts.push('```tsx');
+  parts.push(input.testCode);
+  parts.push('```');
+
+  return {
+    system: TEST_FIX_SYSTEM,
+    prompt: parts.join('\n'),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// LINT FIXER — fixes lint errors that biome --write couldn't auto-fix
+// ═══════════════════════════════════════════════════════════════════
+
+const LINT_FIX_SYSTEM = `You are a lint error fixer. You receive source files and lint errors that could not be auto-fixed by biome. Fix the remaining lint issues with minimal changes.
+
+Return EXACTLY two code blocks:
+1. First block: the fixed component file
+2. Second block: the fixed test file
+
+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.`;
+
+export interface LintFixInput {
+  componentCode: string;
+  testCode: string;
+  errors: string[];
+}
+
+export function buildLintFixPrompt(input: LintFixInput): PromptResult {
+  const parts: string[] = [];
+
+  parts.push('## Lint Errors\n');
+  parts.push('```');
+  parts.push(input.errors.join('\n'));
+  parts.push('```');
+
+  parts.push('\n\n## Component Code\n');
+  parts.push('```tsx');
+  parts.push(input.componentCode);
+  parts.push('```');
+
+  parts.push('\n\n## Test Code\n');
+  parts.push('```tsx');
+  parts.push(input.testCode);
+  parts.push('```');
+
+  return {
+    system: LINT_FIX_SYSTEM,
+    prompt: parts.join('\n'),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// STORY FIXER — fixes story type errors
+// ═══════════════════════════════════════════════════════════════════
+
+const STORY_FIX_SYSTEM = `You are a Storybook story fixer. You receive a story file, the component it references, and TypeScript errors. Fix the story to compile correctly.
+
+Return EXACTLY one code block: the fixed story file.
+
+Rules:
+- Fix ONLY the errors listed. Do not add stories or change story behavior.
+- Ensure imports match the component's actual exports.
+- Ensure args match the component's actual props.
+- Use CSF3 format with \`export default meta;\`.
+- Import types from \`@storybook/react-vite\`.
+- Return the complete file, not a diff.
+- No commentary, no explanations. Just the one code block.`;
+
+export interface StoryFixInput {
+  storyCode: string;
+  componentCode: string;
+  errors: string[];
+}
+
+export function buildStoryFixPrompt(input: StoryFixInput): PromptResult {
+  const parts: string[] = [];
+
+  parts.push('## TypeScript Errors\n');
+  parts.push('```');
+  parts.push(input.errors.join('\n'));
+  parts.push('```');
+
+  parts.push('\n\n## Story Code\n');
+  parts.push('```tsx');
+  parts.push(input.storyCode);
+  parts.push('```');
+
+  parts.push('\n\n## Component Code (reference)\n');
+  parts.push('```tsx');
+  parts.push(input.componentCode);
+  parts.push('```');
+
+  return {
+    system: STORY_FIX_SYSTEM,
+    prompt: parts.join('\n'),
+  };
+}