feat: refactor stack detection and metadata handling for improved wizard integration

Author: spivx

app/api/scan-repo/route.ts

@@ -6,9 +6,10 @@ import type {
     RepoScanSummary,
     RepoStructureSummary,
 } from "@/types/repo-scan"
-import { collectConventionValues, normalizeConventionValue } from "@/lib/convention-values"
+import { loadStackQuestionMetadata, normalizeConventionValue } from "@/lib/question-metadata"
 import { loadStackConventions } from "@/lib/conventions"
 import { inferStackFromScan } from "@/lib/scan-to-wizard"
+import { stackQuestion } from "@/lib/wizard-config"
 
 const GITHUB_API_BASE_URL = "https://api.github.com"
 const GITHUB_HOSTNAMES = new Set(["github.com", "www.github.com"])
@@ -302,10 +303,10 @@ const getTestingConventionValues = async (stackId: string): Promise<TestingConve
         return testingConventionCache.get(normalized)!
     }
 
-    const { conventions } = await loadStackConventions(normalized)
+    const metadata = await loadStackQuestionMetadata(normalized)
     const values: TestingConventionValues = {
-        unit: collectConventionValues(conventions, "testingUT"),
-        e2e: collectConventionValues(conventions, "testingE2E"),
+        unit: metadata.answersByResponseKey.testingUT ?? [],
+        e2e: metadata.answersByResponseKey.testingE2E ?? [],
     }
     testingConventionCache.set(normalized, values)
     return values
@@ -873,8 +874,16 @@ export async function GET(request: NextRequest): Promise<NextResponse<RepoScanRe
 
         const detectedStack = inferStackFromScan(summary)
         const { conventions, hasStackFile } = await loadStackConventions(detectedStack)
+        const stackAnswers = stackQuestion?.answers ?? []
+        const matchedStackAnswer = stackAnswers.find((answer) => answer.value === detectedStack) ?? null
+        const stackSupported = matchedStackAnswer
+            ? matchedStackAnswer.disabled !== true && matchedStackAnswer.enabled !== false
+            : false
+        const stackLabel = matchedStackAnswer?.label ?? null
         summary.conventions = {
             stack: detectedStack,
+            stackLabel,
+            isSupported: stackSupported,
             hasCustomConventions: hasStackFile,
             structureRelevant: conventions.structureRelevant,
         }

app/existing/[repoUrl]/repo-scan-client.tsx

@@ -6,18 +6,17 @@ This document outlines how repository scans are transformed into AI instruction
 
 1. **Scan the repository** (`app/api/scan-repo/route.ts`)
    - Detect languages, frameworks, tooling, structure hints, and enriched metadata.
-   - Use stack conventions (`collectConventionValues`) to cross-check detection lists (e.g., testing tools) so any signal we add in `conventions/<stack>.json` becomes discoverable with minimal code changes.
-   - Reuse convention values to expand stack-specific heuristics (e.g., Python’s Behave directories, Next.js routing shapes), so each conventions file remains the source of truth for new detections.
+   - Load stack question metadata (`loadStackQuestionMetadata`) so detection lists (e.g., testing tools) map onto the same canonical values the wizard exposes.
+   - Reuse those canonical values to expand stack-specific heuristics (e.g., Python’s Behave directories, Next.js routing shapes) without hard-coding strings inside the scanner.
    - Infer the primary stack using `inferStackFromScan`.
    - Load stack conventions (`loadStackConventions`) to determine which structure hints matter and whether stack-specific rules exist.
    - Attach `summary.conventions` so the UI knows which directories to highlight and whether a conventions file was found.
 
 2. **Build wizard defaults** (`lib/scan-to-wizard.ts`)
    - Start with an empty `WizardResponses` object.
-   - Apply convention defaults from `conventions/<stack>.json` + `default.json`.
-   - Layer in detections from the scan (tooling, testing, naming signals, etc.), matching scan values against convention-provided options so stack JSON remains the single source of truth.
+   - Layer in detections from the scan (tooling, testing, naming signals, etc.), matching scan values against the question catalog so defaults stay in sync with the wizard.
    - Run convention rules to tweak values based on detected tooling/testing.
-   - Pull default answers directly from the stack’s question set (`buildStepsForStack`) and fill any remaining empty responses. We track which questions were auto-defaulted (`defaultedQuestionIds`) so the summary can explain why.
+   - Pull default answers directly from the stack’s question set (`loadStackQuestionMetadata`) and fill any remaining empty responses. We track which questions were auto-defaulted (`defaultedQuestionIds`) so the summary can explain why.
 
 3. **Persist and surface responses**
    - `lib/scan-prefill.ts` merges the generated responses into local wizard state and stores both `autoFilledMap` and `defaultedMap` in localStorage.
@@ -34,8 +33,9 @@ This document outlines how repository scans are transformed into AI instruction
 
 | Location | Purpose |
 | --- | --- |
-| `conventions/default.json` & `/conventions/<stack>.json` | Declarative defaults + rules for each stack (tooling choices, structure hints, apply-to glob, etc.). |
-| `lib/convention-values.ts` | Helpers that normalize and aggregate convention values (e.g., testingUT/testingE2E) for both the scanner and the wizard. |
+| `conventions/default.json` & `/conventions/<stack>.json` | Declarative rules, `applyToGlob`, and structure hints for each stack. |
+| `lib/question-metadata.ts` | Caches question answers/defaults per stack so both the scanner and wizard share a single source of truth. |
+| `lib/wizard-responses.ts` | Produces empty `WizardResponses` objects and guards response keys. |
 | `data/stacks.json` | List of stacks exposed to the wizard; each should have a matching conventions file. |
 | `data/questions/<stack>.json` | Stack-specific questions with default answers and metadata. These defaults are now honored automatically when scan data is missing. |
 

docs/scan-flow.md

@@ -0,0 +1,73 @@
+import { buildStepsForStack } from "@/lib/wizard-summary-data"
+import { isWizardResponseKey } from "@/lib/wizard-responses"
+import type { WizardResponses, WizardStep } from "@/types/wizard"
+
+export const normalizeConventionValue = (value: string): string => value.trim().toLowerCase()
+
+export type StackQuestionDefault = {
+  questionId: string
+  responseKey: keyof WizardResponses
+  value: string
+  label: string
+}
+
+export type StackQuestionMetadata = {
+  defaults: StackQuestionDefault[]
+  answersByResponseKey: Partial<Record<keyof WizardResponses, string[]>>
+}
+
+const metadataCache = new Map<string, StackQuestionMetadata>()
+
+const extractQuestionMetadata = (steps: WizardStep[], stack: string): StackQuestionMetadata => {
+  const defaults: StackQuestionDefault[] = []
+  const answersByResponseKey: Partial<Record<keyof WizardResponses, string[]>> = {}
+
+  steps.forEach((step) => {
+    step.questions.forEach((question) => {
+      const rawKey = question.responseKey ?? question.id
+      if (!rawKey || rawKey === "stackSelection" || !isWizardResponseKey(rawKey)) {
+        return
+      }
+
+      const key = rawKey as keyof WizardResponses
+      const enabledAnswers = question.answers.filter((answer) => !answer.disabled)
+
+      if (enabledAnswers.length > 0) {
+        const seen = new Set<string>()
+        answersByResponseKey[key] = enabledAnswers.reduce<string[]>((list, answer) => {
+          const value = typeof answer.value === "string" ? answer.value : ""
+          if (!value || seen.has(value.toLowerCase())) {
+            return list
+          }
+          seen.add(value.toLowerCase())
+          list.push(value)
+          return list
+        }, [])
+      }
+
+      const defaultAnswer = enabledAnswers.find((answer) => answer.isDefault)
+      if (defaultAnswer && typeof defaultAnswer.value === "string" && defaultAnswer.value.trim().length > 0) {
+        defaults.push({
+          questionId: question.id,
+          responseKey: key,
+          value: defaultAnswer.value,
+          label: defaultAnswer.label ?? defaultAnswer.value,
+        })
+      }
+    })
+  })
+
+  return { defaults, answersByResponseKey }
+}
+
+export const loadStackQuestionMetadata = async (stack: string): Promise<StackQuestionMetadata> => {
+  const normalized = stack.trim().toLowerCase()
+  if (metadataCache.has(normalized)) {
+    return metadataCache.get(normalized)!
+  }
+
+  const { steps } = await buildStepsForStack(stack)
+  const metadata = extractQuestionMetadata(steps, stack)
+  metadataCache.set(normalized, metadata)
+  return metadata
+}

lib/convention-values.ts

@@ -1,9 +1,9 @@
-import { collectConventionValues, normalizeConventionValue } from "@/lib/convention-values"
 import { applyConventionRules, loadStackConventions } from "@/lib/conventions"
-import { buildStepsForStack } from "@/lib/wizard-summary-data"
+import { loadStackQuestionMetadata, normalizeConventionValue } from "@/lib/question-metadata"
+import { createEmptyResponses } from "@/lib/wizard-responses"
 import type { RepoScanSummary } from "@/types/repo-scan"
 import type { LoadedConvention } from "@/types/conventions"
-import type { WizardResponses, WizardStep } from "@/types/wizard"
+import type { WizardResponses } from "@/types/wizard"
 
 const STACK_FALLBACK = "react"
 
@@ -12,14 +12,12 @@ const toLowerArray = (values: string[] | undefined | null) =>
 
 const detectFromScanList = (
   scanList: string[] | undefined | null,
-  conventions: LoadedConvention,
-  key: keyof WizardResponses,
+  candidates: string[] | undefined | null,
 ): string | null => {
   if (!Array.isArray(scanList) || scanList.length === 0) {
     return null
   }
-  const candidates = collectConventionValues(conventions, key)
-  if (candidates.length === 0) {
+  if (!Array.isArray(candidates) || candidates.length === 0) {
     return null
   }
 
@@ -66,35 +64,6 @@ const detectStack = (scan: RepoScanSummary): string => {
 
 export const inferStackFromScan = (scan: RepoScanSummary): string => detectStack(scan)
 
-const createEmptyResponses = (stack: string): WizardResponses => ({
-  stackSelection: stack,
-  tooling: null,
-  language: null,
-  fileStructure: null,
-  styling: null,
-  testingUT: null,
-  testingE2E: null,
-  projectPriority: null,
-  codeStyle: null,
-  variableNaming: null,
-  fileNaming: null,
-  componentNaming: null,
-  exports: null,
-  comments: null,
-  collaboration: null,
-  stateManagement: null,
-  apiLayer: null,
-  folders: null,
-  dataFetching: null,
-  reactPerf: null,
-  auth: null,
-  validation: null,
-  logging: null,
-  commitStyle: null,
-  prRules: null,
-  outputFile: null,
-})
-
 const detectLanguage = (scan: RepoScanSummary): string | null => {
   const languages = toLowerArray(scan.languages)
   if (languages.includes("typescript")) return "typescript"
@@ -103,22 +72,17 @@ const detectLanguage = (scan: RepoScanSummary): string | null => {
   return scan.language ? String(scan.language) : null
 }
 
-const detectTestingUnit = (scan: RepoScanSummary, conventions: LoadedConvention): string | null =>
-  detectFromScanList(scan.testing, conventions, "testingUT")
+const detectTestingUnit = (scan: RepoScanSummary, candidates: string[] | undefined | null): string | null =>
+  detectFromScanList(scan.testing, candidates)
 
-const detectTestingE2E = (scan: RepoScanSummary, conventions: LoadedConvention): string | null =>
-  detectFromScanList(scan.testing, conventions, "testingE2E")
+const detectTestingE2E = (scan: RepoScanSummary, candidates: string[] | undefined | null): string | null =>
+  detectFromScanList(scan.testing, candidates)
 
-const detectToolingSummary = (scan: RepoScanSummary, conventions: LoadedConvention): string | null => {
+const detectToolingSummary = (scan: RepoScanSummary): string | null => {
   if (scan.tooling && scan.tooling.length > 0) {
     return scan.tooling.join(" + ")
   }
 
-  const defaultTooling = conventions.defaults.tooling
-  if (typeof defaultTooling === "string" && defaultTooling.trim().length > 0) {
-    return defaultTooling
-  }
-
   return null
 }
 
@@ -150,57 +114,6 @@ const detectPRRules = (scan: RepoScanSummary): string | null => {
   return null
 }
 
-type StackQuestionDefault = {
-  questionId: string
-  responseKey: keyof WizardResponses
-  value: string
-  label: string
-}
-
-const defaultsCache = new Map<string, StackQuestionDefault[]>()
-
-const extractDefaultsFromSteps = (steps: WizardStep[], template: WizardResponses): StackQuestionDefault[] => {
-  const defaults: StackQuestionDefault[] = []
-  steps.forEach((step) => {
-    step.questions.forEach((question) => {
-      const rawKey = question.responseKey ?? question.id
-      if (!rawKey || rawKey === "stackSelection") {
-        return
-      }
-      const defaultAnswer = question.answers.find((answer) => answer.isDefault && !answer.disabled)
-      if (!defaultAnswer) {
-        return
-      }
-      if (!(rawKey in template)) {
-        return
-      }
-      const key = rawKey as keyof WizardResponses
-      defaults.push({
-        questionId: question.id,
-        responseKey: key,
-        value: defaultAnswer.value,
-        label: defaultAnswer.label ?? defaultAnswer.value,
-      })
-    })
-  })
-  return defaults
-}
-
-const loadStackQuestionDefaults = async (
-  stack: string,
-  template: WizardResponses,
-): Promise<StackQuestionDefault[]> => {
-  const normalized = stack.trim().toLowerCase()
-  if (defaultsCache.has(normalized)) {
-    return defaultsCache.get(normalized)!
-  }
-
-  const { steps } = await buildStepsForStack(stack)
-  const defaults = extractDefaultsFromSteps(steps, template)
-  defaultsCache.set(normalized, defaults)
-  return defaults
-}
-
 type BuildResult = {
   stack: string
   responses: WizardResponses
@@ -213,28 +126,28 @@ type BuildResult = {
 export const buildResponsesFromScan = async (scan: RepoScanSummary): Promise<BuildResult> => {
   const stack = detectStack(scan)
   const { conventions, hasStackFile } = await loadStackConventions(stack)
+  const { defaults: questionDefaults, answersByResponseKey } = await loadStackQuestionMetadata(stack)
 
   const base = createEmptyResponses(stack)
-  const withDefaults: WizardResponses = { ...base, ...conventions.defaults }
-
-  applyDetectedValue(withDefaults, "tooling", detectToolingSummary(scan, conventions))
-  applyDetectedValue(withDefaults, "language", detectLanguage(scan))
-  applyDetectedValue(withDefaults, "testingUT", detectTestingUnit(scan, conventions))
-  applyDetectedValue(withDefaults, "testingE2E", detectTestingE2E(scan, conventions))
-  applyDetectedValue(withDefaults, "fileNaming", detectFileNaming(scan))
-  applyDetectedValue(withDefaults, "componentNaming", detectComponentNaming(scan))
-  applyDetectedValue(withDefaults, "commitStyle", detectCommitStyle(scan))
-  applyDetectedValue(withDefaults, "prRules", detectPRRules(scan))
-
-  const afterRules = applyConventionRules(withDefaults, conventions.rules, scan)
+  const withDetected: WizardResponses = { ...base }
+
+  applyDetectedValue(withDetected, "tooling", detectToolingSummary(scan))
+  applyDetectedValue(withDetected, "language", detectLanguage(scan))
+  applyDetectedValue(withDetected, "testingUT", detectTestingUnit(scan, answersByResponseKey.testingUT))
+  applyDetectedValue(withDetected, "testingE2E", detectTestingE2E(scan, answersByResponseKey.testingE2E))
+  applyDetectedValue(withDetected, "fileNaming", detectFileNaming(scan))
+  applyDetectedValue(withDetected, "componentNaming", detectComponentNaming(scan))
+  applyDetectedValue(withDetected, "commitStyle", detectCommitStyle(scan))
+  applyDetectedValue(withDetected, "prRules", detectPRRules(scan))
+
+  const afterRules = applyConventionRules(withDetected, conventions.rules, scan)
   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, label }) => {
     const currentValue = afterRules[responseKey]
     if (currentValue === null || currentValue === undefined || currentValue === "") {
@@ -248,17 +161,14 @@ export const buildResponsesFromScan = async (scan: RepoScanSummary): Promise<Bui
     }
   })
 
-  if (!afterRules.tooling) {
-    applyDetectedValue(afterRules, "tooling", detectToolingSummary(scan, conventions))
-  }
   if (!afterRules.language) {
     applyDetectedValue(afterRules, "language", detectLanguage(scan))
   }
   if (!afterRules.testingUT) {
-    applyDetectedValue(afterRules, "testingUT", detectTestingUnit(scan, conventions))
+    applyDetectedValue(afterRules, "testingUT", detectTestingUnit(scan, answersByResponseKey.testingUT))
   }
   if (!afterRules.testingE2E) {
-    applyDetectedValue(afterRules, "testingE2E", detectTestingE2E(scan, conventions))
+    applyDetectedValue(afterRules, "testingE2E", detectTestingE2E(scan, answersByResponseKey.testingE2E))
   }
   if (!afterRules.fileNaming) {
     applyDetectedValue(afterRules, "fileNaming", detectFileNaming(scan))