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

package/src/scaffold.ts

@@ -0,0 +1,281 @@
+// ═══════════════════════════════════════════════════════════════════
+// Scaffold generator — deterministic component skeleton with __BODY__
+// ═══════════════════════════════════════════════════════════════════
+
+export interface ScaffoldProp {
+  name: string;
+  type: string;
+  required: boolean;
+  default?: string;
+  description: string;
+  category: string;
+}
+
+export interface ScaffoldComposedComponent {
+  id: string;
+  path: string;
+  /** Actual exported value names from the file, resolved via TS AST. */
+  exports?: string[];
+}
+
+export interface ScaffoldInput {
+  componentName: string;
+  props?: ScaffoldProp[];
+  composes: ScaffoldComposedComponent[];
+  specDeltas: {
+    structure: string[];
+    rendering: string[];
+    interaction: string[];
+    styling: string[];
+  };
+}
+
+export interface ScaffoldResult {
+  /** The exported props type definition (e.g. `export type ButtonProps = { ... };`) */
+  propsInterface: string;
+  /** React + composed component import statements */
+  importStatements: string;
+  /** The function signature line with destructured props */
+  functionSignature: string;
+  /** Complete file with `__BODY__` placeholder where the LLM fills in the JSX */
+  scaffoldedFile: string;
+}
+
+/**
+ * Converts a file path like `src/components/ui/Button.tsx` or
+ * `src/components/MyFeature` to a `@/` import alias like
+ * `@/components/ui/Button` or `@/components/MyFeature`.
+ */
+export function filePathToImportAlias(filePath: string): string {
+  let rel = filePath;
+  if (rel.startsWith('./')) {
+    rel = rel.slice(2);
+  }
+  if (rel.startsWith('src/')) {
+    rel = rel.slice(4);
+  }
+  // Strip .tsx/.ts extension
+  rel = rel.replace(/\.tsx?$/, '');
+  return `@/${rel}`;
+}
+
+/**
+ * Generates the deterministic scaffold of a React component — imports,
+ * props type, function signature, and export — leaving a `__BODY__`
+ * placeholder for the LLM to fill in the JSX return statement and any
+ * internal hooks/logic.
+ */
+export function generateScaffold(input: ScaffoldInput): ScaffoldResult {
+  const { componentName, props = [], composes } = input;
+
+  const propsTypeName = `${componentName}Props`;
+
+  // ── Determine if we need React import ────────────────────────────
+  const hasSlotProps = props.some((p) => isReactNodeType(p.type));
+
+  // ── Build import statements ──────────────────────────────────────
+  const importLines: string[] = [];
+
+  if (hasSlotProps) {
+    importLines.push(`import React from 'react';`);
+  }
+
+  // cn utility — almost always needed for Tailwind class composition
+  importLines.push(`import { cn } from '@/lib/utils';`);
+
+  // Composed component imports — use AST-resolved exports when available
+  for (const composed of composes) {
+    const alias = filePathToImportAlias(composed.path);
+
+    if (composed.exports && composed.exports.length > 0) {
+      // Use actual exports from TS AST
+      const names = composed.exports.join(', ');
+      importLines.push(`import { ${names} } from '${alias}';`);
+    } else {
+      // Fallback: derive from filename
+      const pascalName = componentNameFromPath(composed.path);
+      importLines.push(`import { ${pascalName} } from '${alias}';`);
+    }
+  }
+
+  const importStatements = importLines.join('\n');
+
+  // ── Build props interface ────────────────────────────────────────
+  const propsInterface = buildPropsInterface(propsTypeName, props);
+
+  // ── Build function signature ─────────────────────────────────────
+  const functionSignature = buildFunctionSignature(componentName, propsTypeName, props);
+
+  // ── Assemble scaffolded file ─────────────────────────────────────
+  const fileParts: string[] = [];
+
+  fileParts.push(importStatements);
+  fileParts.push('');
+  fileParts.push(propsInterface);
+  fileParts.push('');
+  fileParts.push(`${functionSignature} {`);
+  fileParts.push(`  __BODY__`);
+  fileParts.push(`}`);
+  fileParts.push('');
+
+  const scaffoldedFile = fileParts.join('\n');
+
+  return {
+    propsInterface,
+    importStatements,
+    functionSignature,
+    scaffoldedFile,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// Internal helpers
+// ═══════════════════════════════════════════════════════════════════
+
+function kebabToPascal(name: string): string {
+  return name
+    .split('-')
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join('');
+}
+
+/**
+ * Extract the component name from a file path.
+ * e.g. "./src/components/ui/Button.tsx" → "Button"
+ *      "src/components/MyWidget.tsx" → "MyWidget"
+ */
+function componentNameFromPath(filePath: string): string {
+  const lastSlash = filePath.lastIndexOf('/');
+  const filename = lastSlash === -1 ? filePath : filePath.slice(lastSlash + 1);
+  const dotIndex = filename.lastIndexOf('.');
+  return dotIndex === -1 ? filename : filename.slice(0, dotIndex);
+}
+
+/**
+ * Returns true when the type string represents React.ReactNode or
+ * similar renderable slot types.
+ */
+function isReactNodeType(typeStr: string): boolean {
+  const t = typeStr.trim();
+  return (
+    t === 'React.ReactNode' ||
+    t === 'ReactNode' ||
+    t === 'React.ReactElement' ||
+    t === 'ReactElement' ||
+    t === 'JSX.Element' ||
+    t.includes('ReactNode') ||
+    t.includes('ReactElement')
+  );
+}
+
+/**
+ * Builds the exported TypeScript props type definition.
+ *
+ * Example output:
+ * ```
+ * export type ButtonProps = {
+ *   /** Label text for the button * /
+ *   label: string;
+ *   /** Whether the button is disabled * /
+ *   disabled?: boolean;
+ * };
+ * ```
+ */
+function buildPropsInterface(typeName: string, props: ScaffoldProp[]): string {
+  if (props.length === 0) {
+    return `export type ${typeName} = Record<string, never>;`;
+  }
+
+  const lines: string[] = [];
+  lines.push(`export type ${typeName} = {`);
+
+  for (const prop of props) {
+    // JSDoc comment for the prop
+    if (prop.description) {
+      lines.push(`  /** ${prop.description} */`);
+    }
+
+    const optional = prop.required ? '' : '?';
+    lines.push(`  ${prop.name}${optional}: ${prop.type};`);
+  }
+
+  lines.push(`};`);
+  return lines.join('\n');
+}
+
+/**
+ * Builds the function signature with destructured props and inline
+ * defaults where declared.
+ *
+ * Example output:
+ * ```
+ * export function Button({ variant = 'primary', onClick, children }: ButtonProps)
+ * ```
+ */
+function buildFunctionSignature(componentName: string, propsTypeName: string, props: ScaffoldProp[]): string {
+  if (props.length === 0) {
+    return `export function ${componentName}(props: ${propsTypeName})`;
+  }
+
+  const destructuredParts: string[] = [];
+
+  for (const prop of props) {
+    if (prop.default !== undefined && prop.default !== '') {
+      // Inline default in destructuring
+      const defaultLiteral = formatDefaultForDestructuring(prop.default);
+      destructuredParts.push(`${prop.name} = ${defaultLiteral}`);
+    } else {
+      destructuredParts.push(prop.name);
+    }
+  }
+
+  // Decide whether to format single-line or multi-line based on length
+  const singleLine = `{ ${destructuredParts.join(', ')} }`;
+  const signaturePrefix = `export function ${componentName}(`;
+  const signatureSuffix = `: ${propsTypeName})`;
+
+  if ((signaturePrefix + singleLine + signatureSuffix).length <= 100) {
+    return `${signaturePrefix}${singleLine}${signatureSuffix}`;
+  }
+
+  // Multi-line destructuring
+  const multiLines: string[] = [];
+  multiLines.push(`${signaturePrefix}{`);
+  for (let i = 0; i < destructuredParts.length; i++) {
+    const trailing = i < destructuredParts.length - 1 ? ',' : ',';
+    multiLines.push(`  ${destructuredParts[i]}${trailing}`);
+  }
+  multiLines.push(`}${signatureSuffix}`);
+  return multiLines.join('\n');
+}
+
+/**
+ * Formats a default value string for use in destructuring assignment.
+ *
+ * If the value is already a valid JS literal (quoted string, number,
+ * boolean, array, object), it is returned as-is. Otherwise it is
+ * returned unchanged (it may be a constant reference or expression
+ * that the LLM-generated body will define).
+ */
+function formatDefaultForDestructuring(raw: string): string {
+  const trimmed = raw.trim();
+
+  // Already looks like a valid literal — return as-is
+  if (
+    trimmed === 'true' ||
+    trimmed === 'false' ||
+    trimmed === 'null' ||
+    trimmed === 'undefined' ||
+    /^-?\d+(\.\d+)?$/.test(trimmed) || // numeric
+    /^['"]/.test(trimmed) || // string literal
+    trimmed.startsWith('[') || // array literal
+    trimmed.startsWith('{') || // object literal
+    trimmed.startsWith('`') // template literal
+  ) {
+    return trimmed;
+  }
+
+  // Wrap bare strings that look like identifiers or expressions — return as-is
+  // (e.g. a constant name like `DEFAULT_SIZE`)
+  return trimmed;
+}

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

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+import { execSync } from 'node:child_process';
+import { runLint, runLintFix } from './lint-runner';
+
+describe('runLint', () => {
+  it('returns passed when biome check succeeds', () => {
+    vi.mocked(execSync).mockReturnValue('');
+
+    const result = runLint(['src/Button.tsx'], '/project');
+
+    expect(result).toEqual({ passed: true, errors: [] });
+    expect(execSync).toHaveBeenCalledWith('npx biome check src/Button.tsx', {
+      cwd: '/project',
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+  });
+
+  it('returns errors when biome check fails', () => {
+    const error = {
+      stdout: 'src/Button.tsx:5:1 lint/error: some lint issue\n',
+      stderr: '',
+    };
+    vi.mocked(execSync).mockImplementation(() => {
+      throw error;
+    });
+
+    const result = runLint(['src/Button.tsx'], '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      errors: ['src/Button.tsx:5:1 lint/error: some lint issue'],
+    });
+  });
+
+  it('passes multiple file paths to biome', () => {
+    vi.mocked(execSync).mockReturnValue('');
+
+    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',
+    });
+  });
+});
+
+describe('runLintFix', () => {
+  it('returns passed when biome check --write succeeds', () => {
+    vi.mocked(execSync).mockReturnValue('');
+
+    const result = runLintFix(['src/Button.tsx'], '/project');
+
+    expect(result).toEqual({ passed: true, errors: [] });
+    expect(execSync).toHaveBeenCalledWith('npx biome check --write src/Button.tsx', {
+      cwd: '/project',
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+  });
+
+  it('returns errors when auto-fix still has remaining issues', () => {
+    const error = {
+      stdout: 'src/Button.tsx:3:1 lint/error: unfixable issue\n',
+      stderr: '',
+    };
+    vi.mocked(execSync).mockImplementation(() => {
+      throw error;
+    });
+
+    const result = runLintFix(['src/Button.tsx'], '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      errors: ['src/Button.tsx:3:1 lint/error: unfixable issue'],
+    });
+  });
+
+  it('handles error object without stdout or stderr properties', () => {
+    vi.mocked(execSync).mockImplementation(() => {
+      throw new Error('command failed');
+    });
+
+    const result = runLintFix(['src/Button.tsx'], '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      errors: [],
+    });
+  });
+});
+
+describe('runLint error without stdout/stderr', () => {
+  it('handles error object without stdout or stderr properties', () => {
+    vi.mocked(execSync).mockImplementation(() => {
+      throw new Error('command failed');
+    });
+
+    const result = runLint(['src/Button.tsx'], '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      errors: [],
+    });
+  });
+});

package/src/tools/lint-runner.ts

@@ -0,0 +1,52 @@
+import { execSync } from 'node:child_process';
+
+export type LintResult = {
+  passed: boolean;
+  errors: string[];
+};
+
+export function runLint(filePaths: string[], targetDir: string): LintResult {
+  try {
+    execSync(`npx biome check ${filePaths.join(' ')}`, {
+      cwd: targetDir,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+    return { passed: true, errors: [] };
+  } catch (err: unknown) {
+    let stdout = '';
+    let stderr = '';
+    if (typeof err === 'object' && err !== null) {
+      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 errors = combined.split('\n').filter((line) => line.trim().length > 0);
+
+    return { passed: false, errors };
+  }
+}
+
+export function runLintFix(filePaths: string[], targetDir: string): LintResult {
+  try {
+    execSync(`npx biome check --write ${filePaths.join(' ')}`, {
+      cwd: targetDir,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+    return { passed: true, errors: [] };
+  } catch (err: unknown) {
+    let stdout = '';
+    let stderr = '';
+    if (typeof err === 'object' && err !== null) {
+      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 errors = combined.split('\n').filter((line) => line.trim().length > 0);
+
+    return { passed: false, errors };
+  }
+}

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

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+import { execSync } from 'node:child_process';
+import { runStorybookTest } from './storybook-runner';
+
+describe('runStorybookTest', () => {
+  it('returns passed when storybook test succeeds', () => {
+    vi.mocked(execSync).mockReturnValue('');
+
+    const result = runStorybookTest('src/Button.stories.tsx', '/project');
+
+    expect(result).toEqual({ passed: true, errors: [] });
+    expect(execSync).toHaveBeenCalledWith('npx storybook test --stories src/Button.stories.tsx', {
+      cwd: '/project',
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+  });
+
+  it('returns errors when storybook test fails', () => {
+    const error = {
+      stdout: 'FAIL src/Button.stories.tsx\nStory "Default" failed\n',
+      stderr: '',
+    };
+    vi.mocked(execSync).mockImplementation(() => {
+      throw error;
+    });
+
+    const result = runStorybookTest('src/Button.stories.tsx', '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      errors: ['FAIL src/Button.stories.tsx', 'Story "Default" failed'],
+    });
+  });
+
+  it('handles error object without stdout or stderr properties', () => {
+    vi.mocked(execSync).mockImplementation(() => {
+      throw new Error('command failed');
+    });
+
+    const result = runStorybookTest('src/Button.stories.tsx', '/project');
+
+    expect(result).toEqual({
+      passed: false,
+      errors: [],
+    });
+  });
+});

package/src/tools/storybook-runner.ts

@@ -0,0 +1,29 @@
+import { execSync } from 'node:child_process';
+
+export type StorybookTestResult = {
+  passed: boolean;
+  errors: string[];
+};
+
+export function runStorybookTest(storyPath: string, targetDir: string): StorybookTestResult {
+  try {
+    execSync(`npx storybook test --stories ${storyPath}`, {
+      cwd: targetDir,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+    return { passed: true, errors: [] };
+  } catch (err: unknown) {
+    let stdout = '';
+    let stderr = '';
+    if (typeof err === 'object' && err !== null) {
+      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 errors = combined.split('\n').filter((line) => line.trim().length > 0);
+
+    return { passed: false, errors };
+  }
+}