feat: enhance scan generation by adding defaulted response metadata and updating template rendering

Author: spivx

app/api/scan-generate/[fileId]/route.ts

@@ -18,13 +18,14 @@ export async function POST(request: NextRequest, context: RouteContext) {
       return NextResponse.json({ error: "Missing scan payload" }, { status: 400 })
     }
 
-    const { stack, responses } = await buildResponsesFromScan(payload.scan)
+    const { stack, responses, defaultedResponseMeta } = await buildResponsesFromScan(payload.scan)
     responses.outputFile = fileId
 
     const rendered = await renderTemplate({
       responses,
       frameworkFromPath: stack,
       fileNameFromPath: fileId,
+      defaultedResponses: defaultedResponseMeta,
     })
 
     return NextResponse.json({
@@ -37,4 +38,3 @@ export async function POST(request: NextRequest, context: RouteContext) {
     return NextResponse.json({ error: "Failed to generate instructions from scan" }, { status: 500 })
   }
 }
-

docs/scan-flow.md

@@ -28,6 +28,7 @@ This document outlines how repository scans are transformed into AI instruction
    - From the repo-scan UI, clicking “Generate” calls `lib/scan-generate.ts`, which posts to `/api/scan-generate/[fileId]`.
    - The API reuses `buildResponsesFromScan` server-side to ensure consistency, then renders the target template with `renderTemplate`.
    - Template rendering pulls `applyToGlob` from conventions so Copilot instructions target stack-appropriate file globs (e.g. `**/*.{py,pyi,md}` for Python).
+   - When a field falls back to a stack default because the scan lacked a signal, `renderTemplate` annotates the generated instruction with a note that it came from the default rather than the scan.
 
 ## Key Data Sources
 

lib/__tests__/template-render.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest"
+
+import { renderTemplate } from "@/lib/template-render"
+import type { WizardResponses } from "@/types/wizard"
+
+const buildResponses = (): WizardResponses => ({
+  stackSelection: "react",
+  tooling: "vite",
+  language: "TypeScript",
+  fileStructure: "feature-based",
+  styling: "tailwind",
+  testingUT: "jest",
+  testingE2E: "cypress",
+  projectPriority: "developer velocity",
+  codeStyle: "eslint-config-next",
+  variableNaming: "camelCase",
+  fileNaming: "kebab-case",
+  componentNaming: "PascalCase",
+  exports: "named",
+  comments: "jsdoc",
+  collaboration: "github",
+  stateManagement: "redux",
+  apiLayer: "trpc",
+  folders: "by-feature",
+  dataFetching: "swr",
+  reactPerf: "memoization",
+  auth: "oauth",
+  validation: "zod",
+  logging: "pino",
+  commitStyle: "conventional",
+  prRules: "reviewRequired",
+  outputFile: "instructions-md",
+})
+
+describe("renderTemplate", () => {
+  it("annotates defaulted responses passed from the scan pipeline", async () => {
+    const responses = buildResponses()
+
+    const result = await renderTemplate({
+      responses,
+      frameworkFromPath: "react",
+      fileNameFromPath: "instructions-md",
+      defaultedResponses: {
+        tooling: {
+          label: "Vite",
+          value: "vite",
+          questionId: "react-tooling",
+        },
+      },
+    })
+
+    expect(result.content).toContain("Vite (stack default - not detected via repo scan)")
+  })
+})

lib/scan-to-wizard.ts

@@ -154,6 +154,7 @@ type StackQuestionDefault = {
   questionId: string
   responseKey: keyof WizardResponses
   value: string
+  label: string
 }
 
 const defaultsCache = new Map<string, StackQuestionDefault[]>()
@@ -178,6 +179,7 @@ const extractDefaultsFromSteps = (steps: WizardStep[], template: WizardResponses
         questionId: question.id,
         responseKey: key,
         value: defaultAnswer.value,
+        label: defaultAnswer.label ?? defaultAnswer.value,
       })
     })
   })
@@ -205,6 +207,7 @@ type BuildResult = {
   conventions: LoadedConvention
   hasCustomConventions: boolean
   defaultedQuestionIds: Record<string, boolean>
+  defaultedResponseMeta: Partial<Record<keyof WizardResponses, { questionId: string; label: string; value: string }>>
 }
 
 export const buildResponsesFromScan = async (scan: RepoScanSummary): Promise<BuildResult> => {
@@ -227,12 +230,21 @@ export const buildResponsesFromScan = async (scan: RepoScanSummary): Promise<Bui
   afterRules.stackSelection = stack
 
   const defaultedQuestionIds: Record<string, boolean> = {}
+  const defaultedResponseMeta: Partial<Record<
+    keyof WizardResponses,
+    { questionId: string; label: string; value: string }
+  >> = {}
   const questionDefaults = await loadStackQuestionDefaults(stack, afterRules)
-  questionDefaults.forEach(({ responseKey, questionId, value }) => {
+  questionDefaults.forEach(({ responseKey, questionId, value, label }) => {
     const currentValue = afterRules[responseKey]
     if (currentValue === null || currentValue === undefined || currentValue === "") {
       afterRules[responseKey] = value
       defaultedQuestionIds[questionId] = true
+      defaultedResponseMeta[responseKey] = {
+        questionId,
+        label,
+        value,
+      }
     }
   })
 
@@ -261,6 +273,7 @@ export const buildResponsesFromScan = async (scan: RepoScanSummary): Promise<Bui
     conventions,
     hasCustomConventions: hasStackFile,
     defaultedQuestionIds,
+    defaultedResponseMeta,
   }
 }
 

lib/template-render.ts

@@ -30,10 +30,17 @@ function mapOutputFileToTemplateType(outputFile: string): string {
   return mapping[outputFile] ?? outputFile
 }
 
+type DefaultedResponseMeta = {
+  label: string
+  value: string
+  questionId: string
+}
+
 export type RenderTemplateParams = {
   responses: WizardResponses
   frameworkFromPath?: string | undefined
   fileNameFromPath?: string | undefined
+  defaultedResponses?: Partial<Record<keyof WizardResponses, DefaultedResponseMeta>>
 }
 
 export type RenderTemplateResult = {
@@ -46,6 +53,7 @@ export async function renderTemplate({
   responses,
   frameworkFromPath,
   fileNameFromPath,
+  defaultedResponses,
 }: RenderTemplateParams): Promise<RenderTemplateResult> {
   const framework = frameworkFromPath && !['general', 'none', 'undefined'].includes(frameworkFromPath)
     ? frameworkFromPath
@@ -97,13 +105,19 @@ export async function renderTemplate({
 
     const value = responses[key]
 
+    const defaultMeta = defaultedResponses?.[key]
+
     if (value === null || value === undefined || value === '') {
       const replacement = isJsonTemplate ? escapeForJson(fallback) : fallback
       generatedContent = generatedContent.replace(placeholder, replacement)
     } else {
-      const replacementValue = String(value)
-      const replacement = isJsonTemplate ? escapeForJson(replacementValue) : replacementValue
-      generatedContent = generatedContent.replace(placeholder, replacement)
+      const rawValue = String(value)
+      const baseValue = defaultMeta?.label ?? rawValue
+      const displayValue = defaultMeta
+        ? `${baseValue} (stack default - not detected via repo scan)`
+        : baseValue
+      const replacementValue = isJsonTemplate ? escapeForJson(displayValue) : displayValue
+      generatedContent = generatedContent.replace(placeholder, replacementValue)
     }
   }
 

playwright/tests/repo-scan.spec.ts

@@ -38,7 +38,7 @@ test('repo scan success path generates instructions preview', async ({ page }) =
   await expect(page.getByText('TypeScript').first()).toBeVisible()
   await expect(page.getByText('Playwright').first()).toBeVisible()
 
-  await page.route('**/api/generate/**', async (route) => {
+  await page.route('**/api/scan-generate/**', async (route) => {
     await route.fulfill({
       status: 200,
       contentType: 'application/json',

playwright/tests/wizard-free-text.spec.ts

@@ -28,16 +28,16 @@ test("wizard accepts custom free text answers and shows them in the summary", as
   const customInput = page.getByPlaceholder("Type your custom preference")
 
   await expect(customInput).toBeVisible()
-  await customInput.fill(customAnswer)
+  await customInput.click()
+  await customInput.fill("")
+  await customInput.type(customAnswer)
+  await expect(customInput).toHaveValue(customAnswer)
 
-  await expect(questionHeading).toHaveText("What build tooling do you use?")
+  const saveButton = page.getByRole("button", { name: "Save custom answer" })
+  await expect(saveButton).toBeEnabled()
+  await saveButton.click()
 
-  const confirmationMessage = page.getByTestId("custom-answer-confirmation")
-  await expect(confirmationMessage).toBeVisible()
-  await expect(confirmationMessage).toContainText(customAnswer)
-  await expect(confirmationMessage).toContainText(
-    "for this question when we generate your context file."
-  )
+  await expect(questionHeading).toHaveText("What language do you use?")
 
   await expect.poll(
     () =>

playwright/tests/wizard.spec.ts

@@ -19,8 +19,29 @@ test('wizard supports filtering, defaults, and reset', async ({ page }) => {
 
   const questionHeading = page.getByTestId('wizard-question-heading')
 
-  await page.getByRole('button', { name: 'Use default (Vite)' }).click()
-  await expect(page.getByTestId('answer-option-react-language-typescript')).toBeVisible()
+  const defaultButton = page.getByRole('button', { name: 'Use default (Vite)' })
+  await expect(defaultButton).toBeEnabled()
+  await defaultButton.click()
+  await expect(defaultButton).toBeDisabled()
+
+  await expect.poll(
+    () =>
+      page.evaluate(() => {
+        const raw = window.localStorage.getItem('devcontext:wizard:react')
+        if (!raw) {
+          return null
+        }
+
+        try {
+          const state = JSON.parse(raw)
+          return state.responses?.['react-tooling'] ?? null
+        } catch (error) {
+          console.warn('Unable to parse wizard state', error)
+          return 'PARSE_ERROR'
+        }
+      }),
+    { timeout: 15000 }
+  ).toBe('vite')
 
   await page.getByRole('button', { name: 'Start Over' }).click()
   await expect(page.getByTestId('wizard-confirmation-dialog')).toBeVisible()

test-results/.last-run.json

@@ -1,6 +1,4 @@
 {
-  "status": "failed",
-  "failedTests": [
-    "6b578dd8037bfa8e4836-6a36192f84de2a39d93f"
-  ]
+  "status": "passed",
+  "failedTests": []
 }