popeye-cli 1.4.1 → 1.4.2

package/src/workflow/project-structure.ts

@@ -0,0 +1,233 @@
+/**
+ * Project structure scanner for build verification context enrichment
+ * Scans project directory and returns a concise summary for embedding in AI prompts
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { isWorkspace, languageToApps, type OutputLanguage } from '../types/project.js';
+
+/**
+ * Summary of a project's directory structure
+ */
+export interface ProjectStructureSummary {
+  tree: string;
+  fileCounts: Record<string, number>;
+  appFileCounts?: Record<string, Record<string, number>>;
+  workspaceApps: Array<{ name: string; path: string; exists: boolean }>;
+  totalSourceFiles: number;
+  tsconfigInfo?: string;
+  formatted: string;
+}
+
+/** Directories to skip during scanning */
+const SKIP_DIRS = new Set([
+  'node_modules', 'dist', 'build', '.git', '__pycache__', '.venv', 'venv',
+  '.next', '.turbo', '.cache', 'coverage', 'out', '.vercel',
+]);
+
+/** Source file extensions to count */
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.py']);
+
+/** Maximum tree entries before truncation */
+const MAX_TREE_ENTRIES = 30;
+
+/**
+ * Recursively scan a directory up to a given depth, building a tree and counting files
+ *
+ * @param dir - Directory to scan
+ * @param depth - Current recursion depth
+ * @param maxDepth - Maximum depth to recurse
+ * @returns Tree lines and file counts by extension
+ */
+async function scanDirectory(
+  dir: string,
+  depth: number,
+  maxDepth: number
+): Promise<{ lines: string[]; counts: Record<string, number> }> {
+  const lines: string[] = [];
+  const counts: Record<string, number> = {};
+
+  if (depth > maxDepth) return { lines, counts };
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const sorted = entries.sort((a, b) => {
+      // Directories first, then files
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+    for (const entry of sorted) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+
+      const indent = '  '.repeat(depth);
+      if (entry.isDirectory()) {
+        lines.push(`${indent}${entry.name}/`);
+        const sub = await scanDirectory(path.join(dir, entry.name), depth + 1, maxDepth);
+        lines.push(...sub.lines);
+        for (const [ext, count] of Object.entries(sub.counts)) {
+          counts[ext] = (counts[ext] || 0) + count;
+        }
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name);
+        if (SOURCE_EXTENSIONS.has(ext)) {
+          counts[ext] = (counts[ext] || 0) + 1;
+        }
+        lines.push(`${indent}${entry.name}`);
+      }
+    }
+  } catch {
+    // Directory access error - ignore
+  }
+
+  return { lines, counts };
+}
+
+/**
+ * Count source files within a specific directory (shallow recursion, max 5 levels)
+ *
+ * @param dir - Directory to count files in
+ * @returns File counts by extension
+ */
+async function countSourceFiles(dir: string): Promise<Record<string, number>> {
+  const result = await scanDirectory(dir, 0, 5);
+  return result.counts;
+}
+
+/**
+ * Read and summarize tsconfig.json if present
+ *
+ * @param projectDir - Project root directory
+ * @returns Brief tsconfig summary string or undefined
+ */
+async function summarizeTsconfig(projectDir: string): Promise<string | undefined> {
+  try {
+    const tsconfigPath = path.join(projectDir, 'tsconfig.json');
+    const content = await fs.readFile(tsconfigPath, 'utf-8');
+    const tsconfig = JSON.parse(content);
+
+    const parts: string[] = ['tsconfig: exists'];
+
+    if (tsconfig.references) {
+      parts.push(`references=${tsconfig.references.length}`);
+    }
+    if (tsconfig.include) {
+      const includeStr = JSON.stringify(tsconfig.include);
+      parts.push(`include=${includeStr.length > 60 ? includeStr.slice(0, 57) + '...' : includeStr}`);
+    }
+    if (tsconfig.exclude) {
+      parts.push(`exclude=${tsconfig.exclude.length} entries`);
+    }
+    if (tsconfig.compilerOptions?.baseUrl) {
+      parts.push(`baseUrl="${tsconfig.compilerOptions.baseUrl}"`);
+    }
+    if (tsconfig.compilerOptions?.paths) {
+      parts.push('paths=true');
+    }
+
+    return parts.join(', ');
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Scan a project directory and return a concise summary for embedding in AI prompts
+ *
+ * @param projectDir - Root directory of the project
+ * @param language - Project language type
+ * @returns Project structure summary with tree, counts, and formatted string
+ */
+export async function getProjectStructureSummary(
+  projectDir: string,
+  language: string
+): Promise<ProjectStructureSummary> {
+  // Scan directory tree (max 3 levels deep)
+  const { lines: treeLines, counts: fileCounts } = await scanDirectory(projectDir, 0, 3);
+
+  // Truncate tree if too large
+  let tree: string;
+  if (treeLines.length > MAX_TREE_ENTRIES) {
+    const extra = treeLines.length - MAX_TREE_ENTRIES;
+    tree = treeLines.slice(0, MAX_TREE_ENTRIES).join('\n') + `\n... (+${extra} more)`;
+  } else {
+    tree = treeLines.join('\n');
+  }
+
+  const totalSourceFiles = Object.values(fileCounts).reduce((sum, c) => sum + c, 0);
+
+  // Workspace app detection
+  const workspaceApps: ProjectStructureSummary['workspaceApps'] = [];
+  let appFileCounts: Record<string, Record<string, number>> | undefined;
+
+  if (isWorkspace(language as OutputLanguage)) {
+    const apps = languageToApps(language as OutputLanguage);
+    appFileCounts = {};
+
+    for (const appType of apps) {
+      const appPath = path.join('apps', appType);
+      const absolutePath = path.join(projectDir, appPath);
+      let exists = false;
+      try {
+        await fs.access(absolutePath);
+        exists = true;
+      } catch {
+        // App directory doesn't exist
+      }
+      workspaceApps.push({ name: appType, path: appPath, exists });
+
+      if (exists) {
+        appFileCounts[appType] = await countSourceFiles(absolutePath);
+      }
+    }
+  }
+
+  // tsconfig awareness
+  const tsconfigInfo = await summarizeTsconfig(projectDir);
+
+  // Assemble formatted summary
+  const formattedParts: string[] = [];
+  formattedParts.push(`Source files: ${totalSourceFiles} total`);
+
+  const countEntries = Object.entries(fileCounts).filter(([, c]) => c > 0);
+  if (countEntries.length > 0) {
+    formattedParts.push(`Extensions: ${countEntries.map(([ext, c]) => `${ext}=${c}`).join(', ')}`);
+  }
+
+  if (workspaceApps.length > 0) {
+    const appSummary = workspaceApps
+      .map(a => `${a.name}: ${a.exists ? 'exists' : 'MISSING'}`)
+      .join(', ');
+    formattedParts.push(`Workspace apps: ${appSummary}`);
+
+    if (appFileCounts) {
+      for (const [appName, counts] of Object.entries(appFileCounts)) {
+        const appCountStr = Object.entries(counts)
+          .filter(([, c]) => c > 0)
+          .map(([ext, c]) => `${ext}=${c}`)
+          .join(', ');
+        if (appCountStr) {
+          formattedParts.push(`  ${appName}: ${appCountStr}`);
+        }
+      }
+    }
+  }
+
+  if (tsconfigInfo) {
+    formattedParts.push(tsconfigInfo);
+  }
+
+  const formatted = formattedParts.join('\n');
+
+  return {
+    tree,
+    fileCounts,
+    appFileCounts,
+    workspaceApps,
+    totalSourceFiles,
+    tsconfigInfo,
+    formatted,
+  };
+}

package/src/workflow/project-verification.ts

@@ -36,6 +36,14 @@ export interface VerificationReport {
   criticalIssues: string[];
 }
 
+/**
+ * Resolved project paths for frontend and backend directories
+ */
+export interface ProjectPaths {
+  frontendDir: string | null;
+  backendDir: string | null;
+}
+
 /**
  * Check if a file exists
  */
@@ -125,15 +133,66 @@ function findTodoPlaceholders(content: string): string[] {
   return todos;
 }
 
+/**
+ * Resolve the correct frontend/backend paths based on language and what exists on disk.
+ *
+ * Workspace projects (fullstack, all) use apps/ or packages/ subdirectories.
+ * Single-language projects use the project root as their frontend or backend dir.
+ *
+ * @param projectDir - The project root directory
+ * @param language - The project language/type
+ * @returns Resolved frontend and backend directory paths (null if not applicable)
+ */
+export async function resolveProjectPaths(projectDir: string, language: string): Promise<ProjectPaths> {
+  // Workspace projects (fullstack, all): check apps/ first, then packages/
+  if (language === 'fullstack' || language === 'all') {
+    const appsF = path.join(projectDir, 'apps', 'frontend');
+    const pkgsF = path.join(projectDir, 'packages', 'frontend');
+    const appsB = path.join(projectDir, 'apps', 'backend');
+    const pkgsB = path.join(projectDir, 'packages', 'backend');
+
+    return {
+      frontendDir: await fileExists(appsF) ? appsF : await fileExists(pkgsF) ? pkgsF : null,
+      backendDir: await fileExists(appsB) ? appsB : await fileExists(pkgsB) ? pkgsB : null,
+    };
+  }
+
+  // Website: root IS the frontend
+  if (language === 'website') {
+    return { frontendDir: projectDir, backendDir: null };
+  }
+
+  // TypeScript/JavaScript: root IS the frontend
+  if (language === 'typescript' || language === 'javascript') {
+    return { frontendDir: projectDir, backendDir: null };
+  }
+
+  // Python: root IS the backend
+  if (language === 'python') {
+    return { frontendDir: null, backendDir: projectDir };
+  }
+
+  return { frontendDir: null, backendDir: null };
+}
+
 /**
  * Verify CSS/Styling setup
  */
-async function verifyStylingSetup(projectDir: string): Promise<VerificationResult[]> {
+async function verifyStylingSetup(paths: ProjectPaths): Promise<VerificationResult[]> {
   const results: VerificationResult[] = [];
-  const frontendDir = path.join(projectDir, 'packages', 'frontend');
+  const frontendDir = paths.frontendDir;
+
+  if (!frontendDir) {
+    return results;
+  }
 
   // Check if frontend uses Tailwind classes
-  const tsxFiles = await findFiles(path.join(frontendDir, 'src'), /\.tsx$/);
+  const srcDir = path.join(frontendDir, 'src');
+  if (!await fileExists(srcDir)) {
+    return results;
+  }
+
+  const tsxFiles = await findFiles(srcDir, /\.tsx$/);
   let usesTailwind = false;
 
   for (const file of tsxFiles.slice(0, 20)) { // Check first 20 files
@@ -216,9 +275,13 @@ async function verifyStylingSetup(projectDir: string): Promise<VerificationResul
 /**
  * Verify authentication setup
  */
-async function verifyAuthSetup(projectDir: string): Promise<VerificationResult[]> {
+async function verifyAuthSetup(paths: ProjectPaths): Promise<VerificationResult[]> {
   const results: VerificationResult[] = [];
-  const frontendDir = path.join(projectDir, 'packages', 'frontend');
+  const frontendDir = paths.frontendDir;
+
+  if (!frontendDir) {
+    return results;
+  }
 
   // Check if project uses Auth0
   const pkgJson = await readFile(path.join(frontendDir, 'package.json'));
@@ -265,9 +328,13 @@ async function verifyAuthSetup(projectDir: string): Promise<VerificationResult[]
 /**
  * Verify routes are complete (no TODO placeholders)
  */
-async function verifyRouteCompleteness(projectDir: string): Promise<VerificationResult[]> {
+async function verifyRouteCompleteness(paths: ProjectPaths): Promise<VerificationResult[]> {
   const results: VerificationResult[] = [];
-  const frontendDir = path.join(projectDir, 'packages', 'frontend');
+  const frontendDir = paths.frontendDir;
+
+  if (!frontendDir) {
+    return results;
+  }
 
   // Check routes file
   const routesFile = await readFile(path.join(frontendDir, 'src', 'routes', 'index.tsx'));
@@ -288,7 +355,12 @@ async function verifyRouteCompleteness(projectDir: string): Promise<Verification
   }
 
   // Check all page components
-  const pageFiles = await findFiles(path.join(frontendDir, 'src', 'pages'), /\.tsx$/);
+  const pagesDir = path.join(frontendDir, 'src', 'pages');
+  if (!await fileExists(pagesDir)) {
+    return results;
+  }
+
+  const pageFiles = await findFiles(pagesDir, /\.tsx$/);
   const incompletePages: string[] = [];
 
   for (const file of pageFiles) {
@@ -325,13 +397,15 @@ async function verifyRouteCompleteness(projectDir: string): Promise<Verification
 /**
  * Verify database setup
  */
-async function verifyDatabaseSetup(projectDir: string): Promise<VerificationResult[]> {
+async function verifyDatabaseSetup(projectDir: string, paths: ProjectPaths): Promise<VerificationResult[]> {
   const results: VerificationResult[] = [];
-  const backendDir = path.join(projectDir, 'packages', 'backend');
+  const backendDir = paths.backendDir;
 
-  // Check .env.example has database config
-  const envExample = await readFile(path.join(projectDir, '.env.example')) ||
-                     await readFile(path.join(backendDir, '.env.example'));
+  // Check .env.example has database config (check root and backend dir)
+  let envExample = await readFile(path.join(projectDir, '.env.example'));
+  if (!envExample && backendDir) {
+    envExample = await readFile(path.join(backendDir, '.env.example'));
+  }
 
   const hasDbConfig = envExample?.includes('DATABASE_URL') ||
                       envExample?.includes('DB_HOST');
@@ -368,11 +442,35 @@ async function verifyDatabaseSetup(projectDir: string): Promise<VerificationResu
 /**
  * Verify the app actually starts
  */
-async function verifyAppStarts(projectDir: string): Promise<VerificationResult[]> {
+async function verifyAppStarts(paths: ProjectPaths): Promise<VerificationResult[]> {
   const results: VerificationResult[] = [];
-  const frontendDir = path.join(projectDir, 'packages', 'frontend');
+  const frontendDir = paths.frontendDir;
+
+  if (!frontendDir) {
+    return results;
+  }
+
+  // Verify directory exists before attempting build
+  if (!await fileExists(frontendDir)) {
+    return results;
+  }
+
+  // Check package.json exists and has a build script
+  const pkgJsonContent = await readFile(path.join(frontendDir, 'package.json'));
+  if (!pkgJsonContent) {
+    return results;
+  }
 
-  // Try to start frontend briefly
+  try {
+    const pkgJson = JSON.parse(pkgJsonContent);
+    if (!pkgJson.scripts?.build) {
+      return results;
+    }
+  } catch {
+    return results;
+  }
+
+  // Try to build frontend
   try {
     await execAsync('npm run build', {
       cwd: frontendDir,
@@ -404,27 +502,36 @@ async function verifyAppStarts(projectDir: string): Promise<VerificationResult[]
 
 /**
  * Run comprehensive project verification
+ *
+ * @param projectDir - The project root directory
+ * @param language - The project language/type (e.g. 'fullstack', 'typescript', 'python')
+ * @param onProgress - Optional progress callback
+ * @returns Verification report
  */
 export async function runComprehensiveVerification(
   projectDir: string,
+  language: string,
   onProgress?: (message: string) => void
 ): Promise<VerificationReport> {
   const allResults: VerificationResult[] = [];
 
+  // Resolve correct paths based on language and disk layout
+  const paths = await resolveProjectPaths(projectDir, language);
+
   onProgress?.('Checking styling setup...');
-  allResults.push(...await verifyStylingSetup(projectDir));
+  allResults.push(...await verifyStylingSetup(paths));
 
   onProgress?.('Checking authentication setup...');
-  allResults.push(...await verifyAuthSetup(projectDir));
+  allResults.push(...await verifyAuthSetup(paths));
 
   onProgress?.('Checking route completeness...');
-  allResults.push(...await verifyRouteCompleteness(projectDir));
+  allResults.push(...await verifyRouteCompleteness(paths));
 
   onProgress?.('Checking database setup...');
-  allResults.push(...await verifyDatabaseSetup(projectDir));
+  allResults.push(...await verifyDatabaseSetup(projectDir, paths));
 
   onProgress?.('Verifying app builds...');
-  allResults.push(...await verifyAppStarts(projectDir));
+  allResults.push(...await verifyAppStarts(paths));
 
   // Calculate summary
   const passedChecks = allResults.filter(r => r.passed).length;