popeye-cli 1.4.7 → 1.6.0

package/src/generators/website-content-scanner.ts

@@ -0,0 +1,208 @@
+/**
+ * Post-generation content scanner
+ * Scans generated website files for known placeholder fingerprints
+ * and reports quality issues as warnings
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * A single scan issue found in a generated file
+ */
+export interface ScanIssue {
+  /** Relative file path within the website directory */
+  file: string;
+  /** Human-readable description of the issue */
+  message: string;
+  /** Severity: error = likely broken, warning = looks generic */
+  severity: 'error' | 'warning';
+  /** Line number where the issue was found (approximate) */
+  line?: number;
+}
+
+/**
+ * Result of scanning generated website content
+ */
+export interface ScanResult {
+  /** All issues found across scanned files */
+  issues: ScanIssue[];
+  /** Number of files scanned */
+  filesScanned: number;
+  /** Content quality score 0-100 based on issues found */
+  score: number;
+}
+
+/**
+ * Known placeholder patterns to detect in generated files
+ */
+const PLACEHOLDER_PATTERNS: Array<{
+  pattern: RegExp;
+  message: string;
+  severity: 'error' | 'warning';
+}> = [
+  {
+    pattern: /\/\*\s*TODO[^*]*\*\//,
+    message: 'Contains TODO block comment',
+    severity: 'error',
+  },
+  {
+    pattern: /\{\/\*\s*TODO[^*]*\*\/\}/,
+    message: 'Contains JSX TODO comment',
+    severity: 'error',
+  },
+  {
+    pattern: /\/\/\s*TODO\b/,
+    message: 'Contains TODO line comment',
+    severity: 'error',
+  },
+  {
+    pattern: /Build something amazing/,
+    message: 'Default tagline "Build something amazing"',
+    severity: 'warning',
+  },
+  {
+    pattern: /Your modern web application/,
+    message: 'Generic description "Your modern web application"',
+    severity: 'warning',
+  },
+  {
+    pattern: /Lorem ipsum/i,
+    message: 'Contains lorem ipsum placeholder text',
+    severity: 'error',
+  },
+  {
+    pattern: /\$29(?:\/mo)?/,
+    message: 'Default pricing amount ($29/mo)',
+    severity: 'warning',
+  },
+];
+
+/**
+ * Multi-line patterns checked against the full file content
+ * These detect combinations that indicate default/template content
+ */
+const COMPOSITE_PATTERNS: Array<{
+  pattern: RegExp;
+  message: string;
+  severity: 'error' | 'warning';
+}> = [
+  {
+    pattern: /name:\s*['"]Starter['"][\s\S]{0,500}name:\s*['"]Pro['"][\s\S]{0,500}name:\s*['"]Enterprise['"]/,
+    message: 'Default pricing tiers (Starter/Pro/Enterprise)',
+    severity: 'warning',
+  },
+  {
+    pattern: /title:\s*['"]Sign Up['"][\s\S]{0,500}title:\s*['"]Configure['"][\s\S]{0,500}title:\s*['"]Deploy['"]/,
+    message: 'Default "How It Works" steps (Sign Up/Configure/Deploy)',
+    severity: 'warning',
+  },
+];
+
+/**
+ * File extensions to scan within the website directory
+ */
+const SCANNABLE_EXTENSIONS = new Set(['.tsx', '.ts', '.jsx', '.js', '.css']);
+
+/**
+ * Directories to skip during scanning
+ */
+const SKIP_DIRS = new Set(['node_modules', '.next', 'dist', 'build', 'coverage']);
+
+/**
+ * Recursively collect scannable files from a directory
+ *
+ * @param dir - Directory to scan
+ * @param baseDir - Base directory for relative path calculation
+ * @returns Array of absolute file paths
+ */
+async function collectFiles(dir: string, baseDir: string): Promise<string[]> {
+  const results: string[] = [];
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        const subFiles = await collectFiles(path.join(dir, entry.name), baseDir);
+        results.push(...subFiles);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name);
+        if (SCANNABLE_EXTENSIONS.has(ext)) {
+          results.push(path.join(dir, entry.name));
+        }
+      }
+    }
+  } catch {
+    // Directory not accessible, skip
+  }
+
+  return results;
+}
+
+/**
+ * Find the approximate line number for a regex match in content
+ *
+ * @param content - File content
+ * @param pattern - Pattern to search for
+ * @returns Line number (1-based) or undefined
+ */
+function findLineNumber(content: string, pattern: RegExp): number | undefined {
+  const match = content.match(pattern);
+  if (!match || match.index === undefined) return undefined;
+  const beforeMatch = content.slice(0, match.index);
+  return beforeMatch.split('\n').length;
+}
+
+/**
+ * Scan generated website files for placeholder fingerprints
+ *
+ * @param websiteDir - The website project directory to scan
+ * @returns Scan result with issues and quality score
+ */
+export async function scanGeneratedContent(websiteDir: string): Promise<ScanResult> {
+  const issues: ScanIssue[] = [];
+  const files = await collectFiles(path.join(websiteDir, 'src'), websiteDir);
+  let score = 100;
+
+  for (const filePath of files) {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      const relativePath = path.relative(websiteDir, filePath);
+
+      // Check per-line patterns
+      for (const { pattern, message, severity } of PLACEHOLDER_PATTERNS) {
+        if (pattern.test(content)) {
+          issues.push({
+            file: relativePath,
+            message,
+            severity,
+            line: findLineNumber(content, pattern),
+          });
+          score -= severity === 'error' ? 15 : 5;
+        }
+      }
+
+      // Check composite (multi-line) patterns
+      for (const { pattern, message, severity } of COMPOSITE_PATTERNS) {
+        if (pattern.test(content)) {
+          issues.push({
+            file: relativePath,
+            message,
+            severity,
+          });
+          score -= severity === 'error' ? 15 : 5;
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return {
+    issues,
+    filesScanned: files.length,
+    score: Math.max(0, Math.min(100, score)),
+  };
+}

package/src/generators/website-context.ts

@@ -0,0 +1,493 @@
+/**
+ * Website content context builder
+ * Discovers user documentation and brand assets to populate website templates
+ * with project-specific content instead of generic placeholders
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import {
+  stripCodeFences,
+  extractProductName,
+  extractTagline,
+  extractDescription,
+  extractFeatures,
+  extractPricing,
+  extractPrimaryColor,
+} from './doc-parser.js';
+import { getScanDirectories } from './workspace-root.js';
+import type { WebsiteStrategyDocument, BrandAssetsContract } from '../types/website-strategy.js';
+
+/** Per-file character cap to prevent a single large doc from consuming the budget */
+const PER_FILE_CAP = 8000;
+
+/**
+ * Structured content context for website generation
+ */
+export interface WebsiteContentContext {
+  productName: string;
+  tagline?: string;
+  description?: string;
+  features: Array<{ title: string; description: string }>;
+  pricing?: Array<{
+    name: string;
+    price: string;
+    period?: string;
+    description: string;
+    features: string[];
+    cta: string;
+    featured?: boolean;
+  }>;
+  brand?: {
+    primaryColor?: string;
+    colorScheme?: Record<string, string>;
+    logoPath?: string;
+  };
+  rawDocs: string;
+  /** Website marketing strategy (generated by AI from product context) */
+  strategy?: WebsiteStrategyDocument;
+  /** Resolved brand assets contract for deterministic logo/favicon placement */
+  brandAssets?: BrandAssetsContract;
+}
+
+/**
+ * Resolve brand assets into a deterministic contract
+ * Searches for logo/favicon in project directory and workspace root,
+ * sets canonical output paths
+ *
+ * @param cwd - Directory to scan for brand assets
+ * @param brandContext - Optional existing brand context from state
+ * @returns Resolved brand assets contract
+ */
+export async function resolveBrandAssets(
+  cwd: string,
+  brandContext?: { logoPath?: string; primaryColor?: string }
+): Promise<BrandAssetsContract> {
+  const assets = await findBrandAssets(cwd);
+  const logoPath = brandContext?.logoPath || assets.logoPath;
+  const ext = logoPath ? path.extname(logoPath) : '.svg';
+
+  return {
+    logoPath,
+    logoOutputPath: `public/brand/logo${ext}`,
+    primaryColor: brandContext?.primaryColor,
+  };
+}
+
+/** Patterns to match documentation files */
+const DOC_PATTERNS = [
+  /spec/i,
+  /pricing/i,
+  /color/i,
+  /brand/i,
+  /ui[\s_-]?spec/i,
+  /^readme\.md$/i,
+  /overview/i,
+  /features/i,
+  /product/i,
+];
+
+/** Directories to exclude from scanning */
+const EXCLUDED_DIRS = [
+  'node_modules',
+  '.popeye',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '__pycache__',
+  'venv',
+  '.venv',
+  'coverage',
+];
+
+/**
+ * Discover project documentation files in a directory
+ *
+ * @param cwd - Directory to scan for documentation
+ * @returns Array of absolute paths to discovered doc files
+ */
+export async function discoverProjectDocs(cwd: string): Promise<string[]> {
+  const scanDirs = await getScanDirectories(cwd);
+  const allDocs: string[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const dir of scanDirs) {
+    const found = await scanDirectoryForDocs(dir);
+    for (const docPath of found) {
+      const resolved = path.resolve(docPath);
+      if (!seenPaths.has(resolved)) {
+        seenPaths.add(resolved);
+        allDocs.push(resolved);
+      }
+    }
+  }
+
+  // Sort: brand/color docs first, then spec, then pricing, then others
+  // Reason: ensures critical brand context isn't truncated by the maxLength cap
+  allDocs.sort((a, b) => {
+    const nameA = path.basename(a).toLowerCase();
+    const nameB = path.basename(b).toLowerCase();
+    const priorityA = getDocPriority(nameA);
+    const priorityB = getDocPriority(nameB);
+    return priorityA - priorityB;
+  });
+
+  return allDocs;
+}
+
+/**
+ * Get sort priority for a doc file (lower = higher priority)
+ */
+function getDocPriority(fileName: string): number {
+  if (/color|brand/.test(fileName)) return 0;
+  if (/spec/.test(fileName)) return 1;
+  if (/pricing/.test(fileName)) return 2;
+  if (/feature/.test(fileName)) return 3;
+  return 4;
+}
+
+/**
+ * Scan a single directory for doc files (flat + docs/ subdirectory)
+ */
+async function scanDirectoryForDocs(dir: string): Promise<string[]> {
+  const docs: string[] = [];
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory() && EXCLUDED_DIRS.includes(entry.name)) {
+        continue;
+      }
+
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        const matches = DOC_PATTERNS.some((pattern) => pattern.test(entry.name));
+        if (matches) {
+          docs.push(path.join(dir, entry.name));
+        }
+      }
+
+      // Check one level of subdirectories (e.g., docs/)
+      if (entry.isDirectory() && entry.name === 'docs') {
+        try {
+          const subEntries = await fs.readdir(path.join(dir, entry.name), {
+            withFileTypes: true,
+          });
+          for (const subEntry of subEntries) {
+            if (subEntry.isFile() && subEntry.name.endsWith('.md')) {
+              docs.push(path.join(dir, entry.name, subEntry.name));
+            }
+          }
+        } catch {
+          // Skip unreadable directories
+        }
+      }
+    }
+  } catch {
+    // Directory not accessible
+  }
+
+  return docs;
+}
+
+/**
+ * Find brand assets (logo files) in a directory
+ * Also searches workspace root and parent directories
+ *
+ * @param cwd - Directory to scan for brand assets
+ * @returns Object with optional logoPath
+ */
+export async function findBrandAssets(
+  cwd: string
+): Promise<{ logoPath?: string }> {
+  const scanDirs = await getScanDirectories(cwd);
+
+  for (const dir of scanDirs) {
+    const result = await scanDirectoryForLogo(dir);
+    if (result.logoPath) return result;
+  }
+
+  return {};
+}
+
+/**
+ * Scan a single directory for logo files
+ */
+async function scanDirectoryForLogo(dir: string): Promise<{ logoPath?: string }> {
+  const logoExtensions = ['.png', '.svg', '.jpg', '.jpeg', '.webp'];
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+
+      const lowerName = entry.name.toLowerCase();
+      const hasLogoInName = lowerName.includes('logo');
+      const hasValidExt = logoExtensions.some((ext) => lowerName.endsWith(ext));
+
+      if (hasLogoInName && hasValidExt) {
+        return { logoPath: path.join(dir, entry.name) };
+      }
+    }
+  } catch {
+    // Directory not accessible
+  }
+
+  return {};
+}
+
+/**
+ * Read and concatenate project documentation files
+ *
+ * @param docPaths - Array of absolute paths to doc files
+ * @param maxLength - Maximum combined length (default 25000 chars)
+ * @returns Combined documentation content with file headers
+ */
+export async function readProjectDocs(
+  docPaths: string[],
+  maxLength: number = 25000
+): Promise<string> {
+  const sections: string[] = [];
+  let totalLength = 0;
+
+  for (const docPath of docPaths) {
+    if (totalLength >= maxLength) break;
+
+    try {
+      let content = await fs.readFile(docPath, 'utf-8');
+      const fileName = path.basename(docPath);
+      const header = `--- ${fileName} ---`;
+
+      // Per-file cap to prevent a single large doc from consuming the budget
+      if (content.length > PER_FILE_CAP) {
+        content = content.slice(0, PER_FILE_CAP) + '...';
+      }
+
+      const remaining = maxLength - totalLength;
+      const trimmedContent =
+        content.length > remaining ? content.slice(0, remaining) + '...' : content;
+
+      sections.push(`${header}\n${trimmedContent}`);
+      totalLength += header.length + 1 + trimmedContent.length;
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return sections.join('\n\n');
+}
+
+/**
+ * Build a structured website content context from discovered docs
+ *
+ * @param cwd - Working directory to scan for docs
+ * @param projectName - The project name (folder name fallback)
+ * @param specification - Optional expanded specification text
+ * @returns Structured content context for website templates
+ */
+export async function buildWebsiteContext(
+  cwd: string,
+  projectName: string,
+  specification?: string
+): Promise<WebsiteContentContext> {
+  const docPaths = await discoverProjectDocs(cwd);
+  const rawDocs = docPaths.length > 0 ? await readProjectDocs(docPaths) : '';
+  const brandAssets = await findBrandAssets(cwd);
+
+  // Strip markdown code fences that wrap entire doc files
+  const cleanDocs = stripCodeFences(rawDocs);
+
+  const context: WebsiteContentContext = {
+    productName: extractProductName(cleanDocs, specification) || projectName,
+    features: extractFeatures(cleanDocs, specification),
+    rawDocs,
+  };
+
+  context.tagline = extractTagline(cleanDocs, context.productName);
+  context.description = extractDescription(cleanDocs, specification);
+  context.pricing = extractPricing(cleanDocs);
+
+  // Extract brand info
+  if (brandAssets.logoPath) {
+    context.brand = { ...context.brand, logoPath: brandAssets.logoPath };
+  }
+
+  const primaryColor = extractPrimaryColor(cleanDocs);
+  if (primaryColor) {
+    context.brand = { ...context.brand, primaryColor };
+  }
+
+  return context;
+}
+
+/**
+ * Result of soft (non-throwing) website context validation
+ */
+export interface ValidationResult {
+  /** Whether the context is sufficient for generation (no blocking issues) */
+  passed: boolean;
+  /** Blocking problems that prevent quality generation */
+  issues: string[];
+  /** Non-blocking concerns about content quality */
+  warnings: string[];
+  /** Content quality score 0-100, deducted for each default/missing piece */
+  contentScore: number;
+}
+
+/** Default pricing tier names that indicate placeholder content */
+const DEFAULT_PRICING_NAMES = ['starter', 'free', 'pro', 'enterprise'];
+
+/** Default pricing amounts that indicate placeholder content */
+const DEFAULT_PRICING_AMOUNTS = ['$0', '$29', '$99', 'custom', 'free'];
+
+/**
+ * Validate website content context without throwing
+ * Returns structured result with issues, warnings, and a content quality score
+ *
+ * @param context - The built website content context
+ * @param projectName - The project name for validation
+ * @returns Validation result with issues, warnings, and score
+ */
+export function validateWebsiteContext(
+  context: WebsiteContentContext,
+  _projectName: string
+): ValidationResult {
+  const issues: string[] = [];
+  const warnings: string[] = [];
+  let contentScore = 100;
+
+  // Suspicious product name (looks like a directory name with hyphens/underscores)
+  const suspiciousNames = ['my-app', 'my-project', 'project', 'app', 'website', 'frontend'];
+  if (
+    /^[a-z]+-[a-z]+(-[a-z]+)*$/.test(context.productName) ||
+    suspiciousNames.includes(context.productName.toLowerCase())
+  ) {
+    issues.push(
+      `Product name "${context.productName}" looks like a directory name, not a product. ` +
+      `Provide .md docs with "# ProductName -- tagline" heading.`
+    );
+    contentScore -= 25;
+  }
+
+  // No docs found at all
+  if (!context.rawDocs || context.rawDocs.length < 100) {
+    issues.push(
+      'No project documentation found. Place .md files (spec, pricing, brand) ' +
+      'in the project directory or its parent.'
+    );
+    contentScore -= 30;
+  }
+
+  // No features extracted
+  if (context.features.length === 0) {
+    issues.push(
+      'No product features extracted from docs. Add a "## Features" section to your spec.'
+    );
+    contentScore -= 20;
+  }
+
+  // Strategy validation
+  if (!context.strategy) {
+    issues.push(
+      'Website strategy missing. Strategy generation may have failed or been skipped.'
+    );
+    contentScore -= 15;
+  }
+
+  // Brand color validation: brand/color docs exist but no color extracted
+  if (!context.brand?.primaryColor && context.rawDocs && /color|brand/i.test(context.rawDocs)) {
+    issues.push(
+      'Brand/color docs found but no primary color extracted. Check color doc format.'
+    );
+    contentScore -= 5;
+  }
+
+  // Logo found but output path not resolved
+  if (context.brand?.logoPath && !context.brandAssets?.logoOutputPath) {
+    issues.push(
+      'Logo found but output path not resolved. Call resolveBrandAssets().'
+    );
+    contentScore -= 5;
+  }
+
+  // --- Non-blocking warnings ---
+
+  // Default pricing tiers detection
+  if (context.pricing && context.pricing.length > 0) {
+    const tierNames = context.pricing.map((t) => t.name.toLowerCase());
+    const tierPrices = context.pricing.map((t) => t.price.toLowerCase().replace(/\/mo.*/, ''));
+    const nameMatches = tierNames.filter((n) => DEFAULT_PRICING_NAMES.includes(n));
+    const priceMatches = tierPrices.filter((p) => DEFAULT_PRICING_AMOUNTS.includes(p));
+
+    // Reason: if most tier names AND prices match defaults, it's likely placeholder content
+    if (nameMatches.length >= 2 && priceMatches.length >= 2) {
+      warnings.push(
+        'Pricing tiers appear to use default values (Starter/Pro/Enterprise at $0/$29/Custom). ' +
+        'Add a pricing section to your docs for accurate tiers.'
+      );
+      contentScore -= 10;
+    }
+  }
+
+  // Missing tagline
+  if (!context.tagline) {
+    warnings.push(
+      'No tagline extracted from docs. Footer and meta tags will use generic defaults. ' +
+      'Add "# ProductName -- Your tagline here" to your spec.'
+    );
+    contentScore -= 5;
+  }
+
+  // Missing description
+  if (!context.description) {
+    warnings.push(
+      'No product description extracted. Meta description will use generic text.'
+    );
+    contentScore -= 5;
+  }
+
+  // No brand color at all (not just missing from color docs)
+  if (!context.brand?.primaryColor && !(context.rawDocs && /color|brand/i.test(context.rawDocs))) {
+    warnings.push(
+      'No brand color found. Website will use default color scheme.'
+    );
+    contentScore -= 5;
+  }
+
+  // Clamp score to 0-100
+  contentScore = Math.max(0, Math.min(100, contentScore));
+
+  return {
+    passed: issues.length === 0,
+    issues,
+    warnings,
+    contentScore,
+  };
+}
+
+/**
+ * Validate website content context and throw if insufficient
+ * Prevents generation of generic websites with placeholder content
+ *
+ * @param context - The built website content context
+ * @param projectName - The project name for validation
+ * @throws Error with actionable message if context is insufficient
+ */
+export function validateWebsiteContextOrThrow(
+  context: WebsiteContentContext,
+  projectName: string
+): { passed: boolean; issues: string[] } {
+  const result = validateWebsiteContext(context, projectName);
+
+  if (!result.passed) {
+    throw new Error(
+      `Website generation blocked - insufficient project context:\n` +
+      result.issues.map((i) => `  - ${i}`).join('\n') +
+      `\n\nFix these issues and re-run. Use POPEYE_DEBUG_WEBSITE=1 to see discovery details.`
+    );
+  }
+
+  return { passed: true, issues: [] };
+}