fix(migration): align volumetrics AI flow with access-patterns and hide curated templates from file lists (#3052)

sevoku · web-flow · commit 49ee3f0211bd · 2026-05-20T15:58:04.000+02:00
* fix(migration): allow volumetrics AI analysis without source files

* fix(migration): hide curated template files from UI file lists
diff --git a/l10n/bundle.l10n.json b/l10n/bundle.l10n.json
@@ -612,8 +612,8 @@
   "No schema found for {0}. Use the \"Generate schema\" option to create one.": "No schema found for {0}. Use the \"Generate schema\" option to create one.",
   "No scope was provided for the role assignment.": "No scope was provided for the role assignment.",
   "No session found for executionId: {executionId}": "No session found for executionId: {executionId}",
-  "No source files found to analyze. Select files first, then try again.": "No source files found to analyze. Select files first, then try again.",
   "No subscriptions found": "No subscriptions found",
+  "No volumetric source files selected. AI will estimate from schema and workspace configuration.": "No volumetric source files selected. AI will estimate from schema and workspace configuration.",
   "NoSQL quick reference": "NoSQL quick reference",
   "Not sure where to start? Open the access-patterns template and fill it in by hand, or use the AI button (sparkle icon) to derive patterns from your workspace code — repositories, query builders, and raw SQL.": "Not sure where to start? Open the access-patterns template and fill it in by hand, or use the AI button (sparkle icon) to derive patterns from your workspace code — repositories, query builders, and raw SQL.",
   "Number of output documents": "Number of output documents",
diff --git a/src/panels/MigrationAssistantTab.ts b/src/panels/MigrationAssistantTab.ts
@@ -400,10 +400,18 @@ export class MigrationAssistantTab extends BaseTab {
             setMigrationTelemetryContext(context, this.project);
             context.telemetry.properties.isNewProject = String(isNewProject);
 
-            // Gather file lists
+            // Gather file lists. Hide the curated template files from the UI —
+            // they are managed via the dedicated "Open Template" buttons and AI flows,
+            // not the user-selectable source list.
+            const volTemplateAbs = this.projectService.getTemplateFilePath('volumetrics');
+            const apTemplateAbs = this.projectService.getTemplateFilePath('access-patterns');
             const schemaFiles = await this.projectService.listDiscoveryFiles(this.project, 'schema-ddl');
-            const volumetricFiles = await this.projectService.listDiscoveryFiles(this.project, 'volumetrics');
-            const accessPatternFiles = await this.projectService.listDiscoveryFiles(this.project, 'access-patterns');
+            const volumetricFiles = (await this.projectService.listDiscoveryFiles(this.project, 'volumetrics')).filter(
+                (f) => f !== volTemplateAbs,
+            );
+            const accessPatternFiles = (
+                await this.projectService.listDiscoveryFiles(this.project, 'access-patterns')
+            ).filter((f) => f !== apTemplateAbs);
             const excludedSchemaFiles = await this.projectService.listExcludedDiscoveryFiles(
                 this.project,
                 'schema-ddl',
@@ -671,9 +679,16 @@ export class MigrationAssistantTab extends BaseTab {
     private async refreshFileState(): Promise<void> {
         if (!this.project) return;
 
+        // Hide the curated template files from the UI (see loadProject for rationale).
+        const volTemplateAbs = this.projectService.getTemplateFilePath('volumetrics');
+        const apTemplateAbs = this.projectService.getTemplateFilePath('access-patterns');
         const schemaFiles = await this.projectService.listDiscoveryFiles(this.project, 'schema-ddl');
-        const volumetricFiles = await this.projectService.listDiscoveryFiles(this.project, 'volumetrics');
-        const accessPatternFiles = await this.projectService.listDiscoveryFiles(this.project, 'access-patterns');
+        const volumetricFiles = (await this.projectService.listDiscoveryFiles(this.project, 'volumetrics')).filter(
+            (f) => f !== volTemplateAbs,
+        );
+        const accessPatternFiles = (
+            await this.projectService.listDiscoveryFiles(this.project, 'access-patterns')
+        ).filter((f) => f !== apTemplateAbs);
         const excludedSchemaFiles = await this.projectService.listExcludedDiscoveryFiles(this.project, 'schema-ddl');
         const excludedVolumetricFiles = await this.projectService.listExcludedDiscoveryFiles(
             this.project,
diff --git a/src/panels/migration/prompts/Phase1Step1AnalysisPrompts.ts b/src/panels/migration/prompts/Phase1Step1AnalysisPrompts.ts
@@ -9,36 +9,39 @@ import * as path from 'path';
  * Builds a Copilot Chat prompt that instructs the AI to read the selected
  * volumetric data files and fill in the volumetrics.md template.
  *
- * @param sourceRefs - A folder path (string) or individual file paths (string[]), workspace-relative.
+ * @param sourceRefs - A folder path (string), individual file paths (string[]), or undefined if no source files.
+ *   When undefined, the AI is instructed to estimate values from the schema and workspace configuration.
  * @param templateRelativePath - Workspace-relative path to the template file.
  * @param schemaFileRefs - A folder path (string) or individual file paths (string[]), workspace-relative.
  * @param discoveryInstructions - Optional custom discovery instructions for the AI.
  */
 export function buildAnalyzeVolumetricsPrompt(
-    sourceRefs: string | string[],
+    sourceRefs: string | string[] | undefined,
     templateRelativePath: string,
     schemaFileRefs: string | string[],
     discoveryInstructions?: string,
 ): string {
-    const isFolder = typeof sourceRefs === 'string';
-    const sourceRefStr = isFolder ? `#file:${sourceRefs}` : sourceRefs.map((f) => `#file:${f}`).join('\n');
-
     const isSchemaFolder = typeof schemaFileRefs === 'string';
     const schemaRefStr = isSchemaFolder
         ? `#file:${schemaFileRefs}`
         : schemaFileRefs.map((f) => `#file:${f}`).join('\n');
 
     const lines: string[] = [
-        `Analyze the following volumetric data files and use the results to fill in the template at #file:${templateRelativePath}.`,
-        '',
-        'Source files to analyze:',
-        sourceRefStr,
+        sourceRefs !== undefined
+            ? `Analyze the following volumetric data files and use the results to fill in the template at #file:${templateRelativePath}.`
+            : `Estimate volumetric data from the schema and workspace configuration, and fill in the template at #file:${templateRelativePath}.`,
     ];
 
-    if (isFolder && path.dirname(templateRelativePath) === sourceRefs) {
-        lines.push(
-            `- The template file (${path.basename(templateRelativePath)}) is inside the source folder — do NOT treat it as source data.`,
-        );
+    if (sourceRefs !== undefined) {
+        const isFolder = typeof sourceRefs === 'string';
+        const sourceRefStr = isFolder ? `#file:${sourceRefs}` : sourceRefs.map((f) => `#file:${f}`).join('\n');
+        lines.push('', 'Source files to analyze:', sourceRefStr);
+
+        if (isFolder && path.dirname(templateRelativePath) === sourceRefs) {
+            lines.push(
+                `- The template file (${path.basename(templateRelativePath)}) is inside the source folder — do NOT treat it as source data.`,
+            );
+        }
     }
 
     lines.push(
@@ -51,7 +54,9 @@ export function buildAnalyzeVolumetricsPrompt(
     lines.push(
         '',
         'Instructions:',
-        '- Read each source file and extract volumetric data (table names, row counts, row sizes, read/write TPS, growth rates).',
+        sourceRefs !== undefined
+            ? '- Read each source file and extract volumetric data (table names, row counts, row sizes, read/write TPS, growth rates).'
+            : '- No volumetric source files were provided. Infer table names, row counts, row sizes, read/write TPS, and growth rates from the schema files, deployment scripts, configuration files, and application code. Mark every inferred value with "(estimated)".',
         '- Replace the example rows in the volumetrics.md template table with real data extracted from the source files.',
         '- Keep the existing table headers and markdown structure intact.',
         '- If a field cannot be determined from the source data, mark it with "N/A" or a reasonable estimate annotated with "(estimated)".',
diff --git a/src/panels/migration/steps/phase1Discovery.ts b/src/panels/migration/steps/phase1Discovery.ts
@@ -702,18 +702,19 @@ export async function runAnalyzeWithAI(
             ? projectService.getVolumetricsPath(project)
             : projectService.getAccessPatternsPath(project);
 
-    // Collect source files, excluding the template if it lives in the same directory.
-    // Honors per-source includedFiles/excludedFiles configuration in project.json.
+    // Collect source files, excluding the curated template (which lives in the
+    // source folder when the user hasn't picked a custom path). The template is
+    // treated as the output target, not as input data.
     const allFiles = await projectService.listDiscoveryFiles(project, subfolder);
-    const nonTemplateFiles =
-        sourceFolderPath === templateFolderPath ? allFiles.filter((f) => !f.endsWith(`/${fileName}`)) : allFiles;
-
-    // Volumetrics requires source data files; access patterns can scan the workspace without them
-    if (subfolder === 'volumetrics' && nonTemplateFiles.length === 0) {
-        void vscode.window.showInformationMessage(
-            l10n.t('No source files found to analyze. Select files first, then try again.'),
+    const sourceFiles = allFiles.filter((f) => f !== templateAbsPath);
+
+    // Both volumetrics and access patterns can proceed without explicit source files —
+    // the AI will fall back to schema + workspace inference. Surface a non-blocking warning
+    // for volumetrics so the user knows the analysis will be estimated.
+    if (subfolder === 'volumetrics' && sourceFiles.length === 0) {
+        void vscode.window.showWarningMessage(
+            l10n.t('No volumetric source files selected. AI will estimate from schema and workspace configuration.'),
         );
-        return;
     }
 
     const templateRelativePath = path.relative(workspacePath, templateAbsPath);
@@ -727,13 +728,13 @@ export async function runAnalyzeWithAI(
     const prompt =
         subfolder === 'volumetrics'
             ? buildAnalyzeVolumetricsPrompt(
-                  sourceFolderRelativePath,
+                  sourceFiles.length > 0 ? sourceFolderRelativePath : undefined,
                   templateRelativePath,
                   schemaFileRefs,
                   discoveryInstructions,
               )
             : buildAnalyzeAccessPatternsPrompt(
-                  nonTemplateFiles.length > 0 ? sourceFolderRelativePath : undefined,
+                  sourceFiles.length > 0 ? sourceFolderRelativePath : undefined,
                   templateRelativePath,
                   schemaFileRefs,
                   getVolumetricsTemplatePath(projectService, workspacePath),
diff --git a/src/services/MigrationProjectService.ts b/src/services/MigrationProjectService.ts
@@ -387,6 +387,12 @@ export class MigrationProjectService {
      * List discovery source files for a subfolder, applying the per-source
      * `includedFiles` allowlist and `excludedFiles` filter from project.json
      * (paths relative to the resolved base).
+     *
+     * NOTE: The curated template files (`volumetrics.md`, `access-patterns.md`)
+     * ARE included in the result when they live in the source folder, because
+     * downstream discovery/assessment steps extract them by name to read
+     * pre-filled values. UI callers that need to hide them should filter the
+     * template file out themselves (see {@link getTemplateFilePath}).
      */
     async listDiscoveryFiles(
         project: ProjectJson,
@@ -407,6 +413,25 @@ export class MigrationProjectService {
         return filtered;
     }
 
+    /**
+     * Return the absolute path of the curated template file for the given
+     * discovery subfolder (`volumetrics.md` / `access-patterns.md`), or
+     * `undefined` for subfolders that have no template. The template always
+     * lives in the default subfolder path; callers can use this to suppress
+     * the template from UI file lists without affecting AI flows that need to
+     * read it.
+     */
+    getTemplateFilePath(subfolder: 'schema-ddl' | 'volumetrics' | 'access-patterns'): string | undefined {
+        const templateFileName =
+            subfolder === 'volumetrics'
+                ? 'volumetrics.md'
+                : subfolder === 'access-patterns'
+                  ? 'access-patterns.md'
+                  : undefined;
+        if (templateFileName === undefined) return undefined;
+        return path.join(this.getDefaultSubfolderPath(subfolder), templateFileName);
+    }
+
     /**
      * List the absolute paths of the discovery files that are currently excluded
      * (paths preserved relative to the resolved base; only those still present on
