feat(cli): comprehensive indexing UX improvements

prosdev · prosdev · commit 9da8107e4abc · 2025-12-13T20:23:30.000-08:00
- Add update plan display to 'dev update' (shows what will change before starting)
- Add detailed progress with rates to all indexing phases (files/sec, docs/sec, commits/sec)
- Extract progress formatting to reusable updateSectionWithRate() method
- Fix NaN display when totalFiles is 0 (now shows 'Discovering...')
- Improve 'dev map' hot paths display with tree branches and file icons
- Add getUpdatePlan() public method to RepositoryIndexer

All indexing commands now show consistent detailed progress:
  1,234/4,567 files (27%, 45 files/sec)

Instead of just:
  27% complete
diff --git a/packages/cli/src/commands/git.ts b/packages/cli/src/commands/git.ts
@@ -98,9 +98,11 @@ export const gitCommand = new Command('git')
                 }
 
                 // Update embedding progress
-                const pct = Math.round((progress.commitsProcessed / progress.totalCommits) * 100);
-                progressRenderer.updateSection(
-                  `${progress.commitsProcessed}/${progress.totalCommits} commits (${pct}%)`
+                progressRenderer.updateSectionWithRate(
+                  progress.commitsProcessed,
+                  progress.totalCommits,
+                  'commits',
+                  embeddingStartTime
                 );
               }
             },
diff --git a/packages/cli/src/commands/github.ts b/packages/cli/src/commands/github.ts
@@ -133,11 +133,11 @@ Related:
                 }
 
                 // Update embedding progress
-                const pct = Math.round(
-                  (progress.documentsProcessed / progress.totalDocuments) * 100
-                );
-                progressRenderer.updateSection(
-                  `${progress.documentsProcessed}/${progress.totalDocuments} documents (${pct}%)`
+                progressRenderer.updateSectionWithRate(
+                  progress.documentsProcessed,
+                  progress.totalDocuments,
+                  'documents',
+                  embeddingStartTime
                 );
               }
             },
diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts
@@ -199,17 +199,20 @@ export const indexCommand = new Command('index')
             }
 
             // Update embedding progress
-            const pct = Math.round((progress.documentsIndexed / progress.totalDocuments) * 100);
-            const embeddingElapsed = (Date.now() - embeddingStartTime) / 1000;
-            const docsPerSec =
-              embeddingElapsed > 0 ? progress.documentsIndexed / embeddingElapsed : 0;
-            progressRenderer.updateSection(
-              `${progress.documentsIndexed.toLocaleString()}/${progress.totalDocuments.toLocaleString()} documents (${pct}%, ${docsPerSec.toFixed(0)} docs/sec)`
+            progressRenderer.updateSectionWithRate(
+              progress.documentsIndexed,
+              progress.totalDocuments,
+              'documents',
+              embeddingStartTime
             );
           } else {
             // Scanning phase
-            const percent = progress.percentComplete || 0;
-            progressRenderer.updateSection(`${percent.toFixed(0)}% complete`);
+            progressRenderer.updateSectionWithRate(
+              progress.filesProcessed,
+              progress.totalFiles,
+              'files',
+              scanStartTime
+            );
           }
         },
       });
@@ -260,9 +263,11 @@ export const indexCommand = new Command('index')
           logger: indexLogger,
           onProgress: (progress) => {
             if (progress.phase === 'storing' && progress.totalCommits > 0) {
-              const pct = Math.round((progress.commitsProcessed / progress.totalCommits) * 100);
-              progressRenderer.updateSection(
-                `${progress.commitsProcessed}/${progress.totalCommits} commits (${pct}%)`
+              progressRenderer.updateSectionWithRate(
+                progress.commitsProcessed,
+                progress.totalCommits,
+                'commits',
+                gitStartTime
               );
             }
           },
@@ -280,6 +285,7 @@ export const indexCommand = new Command('index')
       let ghStats = { totalDocuments: 0, indexDuration: 0 };
       if (canIndexGitHub) {
         const ghStartTime = Date.now();
+        let ghEmbeddingStartTime = 0;
         const ghVectorPath = `${filePaths.vectors}-github`;
         const ghIndexer = new GitHubIndexer({
           vectorStorePath: ghVectorPath,
@@ -295,9 +301,14 @@ export const indexCommand = new Command('index')
             if (progress.phase === 'fetching') {
               progressRenderer.updateSection('Fetching issues/PRs...');
             } else if (progress.phase === 'embedding') {
-              const pct = Math.round((progress.documentsProcessed / progress.totalDocuments) * 100);
-              progressRenderer.updateSection(
-                `${progress.documentsProcessed}/${progress.totalDocuments} documents (${pct}%)`
+              if (ghEmbeddingStartTime === 0) {
+                ghEmbeddingStartTime = Date.now();
+              }
+              progressRenderer.updateSectionWithRate(
+                progress.documentsProcessed,
+                progress.totalDocuments,
+                'documents',
+                ghEmbeddingStartTime
               );
             }
           },
diff --git a/packages/cli/src/commands/update.ts b/packages/cli/src/commands/update.ts
@@ -83,12 +83,67 @@ export const updateCommand = new Command('update')
 
       await indexer.initialize();
 
-      // Create logger for updating (verbose mode shows debug logs)
-      const indexLogger = createIndexLogger(options.verbose);
+      // Get update plan to show user what will be updated
+      const updatePlan = await indexer.getUpdatePlan();
 
-      // Stop spinner and switch to section-based progress
+      // Stop spinner
       spinner.stop();
 
+      if (!updatePlan || updatePlan.total === 0) {
+        output.success('No changes detected');
+        await indexer.close();
+        metricsStore.close();
+        return;
+      }
+
+      // Show update plan
+      console.log('');
+      console.log(chalk.bold('Update plan:'));
+      console.log('');
+
+      if (updatePlan.added.length > 0) {
+        console.log(chalk.green(`  ✓ ${updatePlan.added.length} new file(s)`));
+        if (options.verbose) {
+          for (const file of updatePlan.added.slice(0, 5)) {
+            console.log(chalk.dim(`    + ${file}`));
+          }
+          if (updatePlan.added.length > 5) {
+            console.log(chalk.dim(`    ... and ${updatePlan.added.length - 5} more`));
+          }
+        }
+      }
+
+      if (updatePlan.changed.length > 0) {
+        console.log(chalk.yellow(`  ↻ ${updatePlan.changed.length} modified file(s)`));
+        if (options.verbose) {
+          for (const file of updatePlan.changed.slice(0, 5)) {
+            console.log(chalk.dim(`    ~ ${file}`));
+          }
+          if (updatePlan.changed.length > 5) {
+            console.log(chalk.dim(`    ... and ${updatePlan.changed.length - 5} more`));
+          }
+        }
+      }
+
+      if (updatePlan.deleted.length > 0) {
+        console.log(chalk.red(`  ✗ ${updatePlan.deleted.length} deleted file(s)`));
+        if (options.verbose) {
+          for (const file of updatePlan.deleted.slice(0, 5)) {
+            console.log(chalk.dim(`    - ${file}`));
+          }
+          if (updatePlan.deleted.length > 5) {
+            console.log(chalk.dim(`    ... and ${updatePlan.deleted.length - 5} more`));
+          }
+        }
+      }
+
+      console.log('');
+      console.log(chalk.dim(`Total: ${updatePlan.total} file(s) to process`));
+      console.log('');
+
+      // Create logger for updating (verbose mode shows debug logs)
+      const indexLogger = createIndexLogger(options.verbose);
+
       // Initialize progress renderer
       const progressRenderer = new ProgressRenderer({ verbose: options.verbose });
       progressRenderer.setSections(['Scanning Changed Files', 'Embedding Vectors']);
@@ -114,17 +169,20 @@ export const updateCommand = new Command('update')
             }
 
             // Update embedding progress
-            const pct = Math.round((progress.documentsIndexed / progress.totalDocuments) * 100);
-            const embeddingElapsed = (Date.now() - embeddingStartTime) / 1000;
-            const docsPerSec =
-              embeddingElapsed > 0 ? progress.documentsIndexed / embeddingElapsed : 0;
-            progressRenderer.updateSection(
-              `${progress.documentsIndexed.toLocaleString()}/${progress.totalDocuments.toLocaleString()} documents (${pct}%, ${docsPerSec.toFixed(0)} docs/sec)`
+            progressRenderer.updateSectionWithRate(
+              progress.documentsIndexed,
+              progress.totalDocuments,
+              'documents',
+              embeddingStartTime
             );
           } else {
             // Scanning phase
-            const percent = progress.percentComplete || 0;
-            progressRenderer.updateSection(`${percent.toFixed(0)}% complete`);
+            progressRenderer.updateSectionWithRate(
+              progress.filesProcessed,
+              progress.totalFiles,
+              'files',
+              scanStartTime
+            );
           }
         },
       });
@@ -155,13 +213,9 @@ export const updateCommand = new Command('update')
 
       // Show completion message
       output.log('');
-      if (stats.filesScanned === 0) {
-        output.success('No changes detected');
-      } else {
-        output.success(
-          `Updated ${stats.filesScanned.toLocaleString()} files in ${duration.toFixed(1)}s`
-        );
-      }
+      output.success(
+        `Updated ${stats.filesScanned.toLocaleString()} files in ${duration.toFixed(1)}s`
+      );
       output.log('');
 
       // Show errors if any
diff --git a/packages/cli/src/utils/progress.ts b/packages/cli/src/utils/progress.ts
@@ -56,6 +56,23 @@ export class ProgressRenderer {
     }
   }
 
+  /**
+   * Update section with formatted progress including rate
+   */
+  updateSectionWithRate(processed: number, total: number, unit: string, startTime: number): void {
+    if (total === 0) {
+      this.updateSection('Discovering...');
+      return;
+    }
+
+    const pct = Math.round((processed / total) * 100);
+    const elapsed = (Date.now() - startTime) / 1000;
+    const rate = elapsed > 0 ? processed / elapsed : 0;
+    this.updateSection(
+      `${processed.toLocaleString()}/${total.toLocaleString()} ${unit} (${pct}%, ${rate.toFixed(0)} ${unit}/sec)`
+    );
+  }
+
   /**
    * Mark current section as complete and move to next
    */
diff --git a/packages/core/src/indexer/index.ts b/packages/core/src/indexer/index.ts
@@ -591,6 +591,29 @@ export class RepositoryIndexer {
     return validation.data;
   }
 
+  /**
+   * Get update plan showing which files will be processed
+   * Useful for displaying a plan before running update
+   */
+  async getUpdatePlan(options: { since?: Date } = {}): Promise<{
+    changed: string[];
+    added: string[];
+    deleted: string[];
+    total: number;
+  } | null> {
+    if (!this.state) {
+      return null;
+    }
+
+    const { changed, added, deleted } = await this.detectChangedFiles(options.since);
+    return {
+      changed,
+      added,
+      deleted,
+      total: changed.length + added.length + deleted.length,
+    };
+  }
+
   /**
    * Enrich language stats with change frequency data
    * Non-blocking: returns original stats if git analysis fails
diff --git a/packages/core/src/map/index.ts b/packages/core/src/map/index.ts
@@ -486,6 +486,26 @@ function computeHotPaths(docs: SearchResult[], maxPaths: number): HotPath[] {
   return sorted;
 }
 
+/**
+ * Get file icon based on extension
+ */
+function getFileIcon(ext: string): string {
+  const iconMap: Record<string, string> = {
+    ts: '📘',
+    tsx: '⚛️',
+    js: '📜',
+    jsx: '⚛️',
+    go: '🐹',
+    py: '🐍',
+    rs: '🦀',
+    md: '📝',
+    json: '📋',
+    yaml: '⚙️',
+    yml: '⚙️',
+  };
+  return iconMap[ext] || '📄';
+}
+
 /**
  * Format codebase map as readable text
  */
@@ -501,8 +521,20 @@ export function formatCodebaseMap(map: CodebaseMap, options: MapOptions = {}): s
     lines.push('## Hot Paths (most referenced)');
     for (let i = 0; i < map.hotPaths.length; i++) {
       const hp = map.hotPaths[i];
-      const component = hp.primaryComponent ? ` (${hp.primaryComponent})` : '';
-      lines.push(`${i + 1}. \`${hp.file}\`${component} - ${hp.incomingRefs} refs`);
+      const isLast = i === map.hotPaths.length - 1;
+      const prefix = isLast ? '└─' : '├─';
+
+      // Get file extension for icon
+      const ext = hp.file.split('.').pop() || '';
+      const icon = getFileIcon(ext);
+
+      // Extract just the filename for cleaner display
+      const fileName = hp.file.split('/').pop() || hp.file;
+      const dirPath = hp.file.substring(0, hp.file.lastIndexOf('/'));
+
+      const component = hp.primaryComponent ? ` • ${hp.primaryComponent}` : '';
+      lines.push(`  ${prefix} ${icon} **${fileName}**${component} • ${hp.incomingRefs} refs`);
+      lines.push(`     ${dirPath}`);
     }
     lines.push('');
   }

Original file line number	Diff line number	Diff line change
`@@ -98,9 +98,11 @@ export const gitCommand = new Command('git')`
`98`	`98`	`}`
`99`	`99`
`100`	`100`	`// Update embedding progress`
`101`		`- const pct = Math.round((progress.commitsProcessed / progress.totalCommits) * 100);`
`102`		`- progressRenderer.updateSection(`
`103`		- `${progress.commitsProcessed}/${progress.totalCommits} commits (${pct}%)`
	`101`	`+ progressRenderer.updateSectionWithRate(`
	`102`	`+ progress.commitsProcessed,`
	`103`	`+ progress.totalCommits,`
	`104`	`+ 'commits',`
	`105`	`+ embeddingStartTime`
`104`	`106`	`);`
`105`	`107`	`}`
`106`	`108`	`},`