@xenonbyte/da-vinci-workflow 0.2.4 → 0.2.5

package/lib/scaffold.js

@@ -1,22 +1,37 @@
 const fs = require("fs");
 const path = require("path");
 const { STATUS } = require("./workflow-contract");
-const { writeFileAtomic } = require("./utils");
+const { writeFileAtomic, normalizeRelativePath, pathWithinRoot } = require("./utils");
 const {
   unique,
   resolveChangeDir,
   parseBindingsArtifact,
   readChangeArtifacts,
-  readArtifactTexts
+  readArtifactTexts,
+  resolveImplementationLanding
 } = require("./planning-parsers");
 
-function sanitizeRouteToFileName(route) {
+const FRAMEWORKS = ["next", "react", "vue", "svelte"];
+const FRAMEWORK_EXTENSIONS = {
+  next: ".tsx",
+  react: ".tsx",
+  vue: ".vue",
+  svelte: ".svelte",
+  html: ".html"
+};
+const TARGET_SCAN_MAX_DEPTH = 6;
+const TARGET_SCAN_MAX_FILES = 3000;
+
+function sanitizeRoute(route) {
   const normalized = String(route || "")
     .trim()
     .split(/[?#]/, 1)[0]
     .replace(/\\/g, "/");
   if (!normalized || normalized === "/") {
-    return "index.html";
+    return {
+      safeSegments: [],
+      hasTraversal: false
+    };
   }
 
   const rawSegments = normalized.replace(/^\/+/, "").split("/").filter(Boolean);
@@ -34,34 +49,327 @@ function sanitizeRouteToFileName(route) {
     safeSegments.push(safeSegment || "index");
   }
 
-  if (safeSegments.length === 0) {
-    if (hasTraversal) {
-      return null;
-    }
+  return {
+    safeSegments,
+    hasTraversal
+  };
+}
+
+function stripKnownFileExtension(segment) {
+  return String(segment || "").replace(/\.(html?|jsx?|tsx?|vue|svelte)$/i, "");
+}
+
+function sanitizeRouteToHtmlFile(route) {
+  const parsed = sanitizeRoute(route);
+  if (parsed.hasTraversal) {
+    return null;
+  }
+  if (parsed.safeSegments.length === 0) {
     return "index.html";
   }
 
-  let relativePath = safeSegments.join("/");
+  let relativePath = parsed.safeSegments.join("/");
   if (!path.extname(relativePath)) {
     relativePath = `${relativePath}.html`;
   }
-  if (hasTraversal) {
+  return relativePath;
+}
+
+function deriveFrameworkTargetPath(route, templateMode) {
+  if (!FRAMEWORKS.includes(templateMode)) {
+    return sanitizeRouteToHtmlFile(route);
+  }
+
+  const parsed = sanitizeRoute(route);
+  if (parsed.hasTraversal) {
     return null;
   }
-  return relativePath;
+
+  const cleanedSegments = parsed.safeSegments
+    .map((segment) => stripKnownFileExtension(segment))
+    .filter(Boolean);
+  const extension = FRAMEWORK_EXTENSIONS[templateMode];
+  if (templateMode === "next") {
+    if (cleanedSegments.length === 0) {
+      return `app/page${extension}`;
+    }
+    return path.join("app", ...cleanedSegments, `page${extension}`);
+  }
+  if (templateMode === "react") {
+    if (cleanedSegments.length === 0) {
+      return `src/pages/index${extension}`;
+    }
+    return path.join("src", "pages", ...cleanedSegments, `index${extension}`);
+  }
+  if (templateMode === "vue") {
+    if (cleanedSegments.length === 0) {
+      return `src/pages/index${extension}`;
+    }
+    return path.join("src", "pages", `${cleanedSegments.join("/")}${extension}`);
+  }
+  if (templateMode === "svelte") {
+    if (cleanedSegments.length === 0) {
+      return "src/routes/+page.svelte";
+    }
+    return path.join("src", "routes", ...cleanedSegments, "+page.svelte");
+  }
+  return sanitizeRouteToHtmlFile(route);
+}
+
+function collectPackageFrameworkSignals(projectRoot) {
+  const reasons = {
+    next: [],
+    react: [],
+    vue: [],
+    svelte: []
+  };
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return reasons;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch (_error) {
+    return reasons;
+  }
+  const allDeps = {
+    ...(parsed.dependencies || {}),
+    ...(parsed.devDependencies || {}),
+    ...(parsed.peerDependencies || {})
+  };
+
+  if (allDeps.next) {
+    reasons.next.push("package:next");
+  }
+  if (allDeps.react || allDeps["react-dom"]) {
+    reasons.react.push("package:react");
+  }
+  if (allDeps.vue || allDeps.nuxt || allDeps["@vue/runtime-dom"]) {
+    reasons.vue.push("package:vue");
+  }
+  if (allDeps.svelte || allDeps["@sveltejs/kit"]) {
+    reasons.svelte.push("package:svelte");
+  }
+  return reasons;
+}
+
+function projectHasAnyFiles(projectRoot, options = {}) {
+  const {
+    roots = ["."],
+    extensions = [],
+    names = [],
+    maxDepth = TARGET_SCAN_MAX_DEPTH
+  } = options;
+  const extensionSet = new Set(extensions.map((value) => String(value || "").toLowerCase()));
+  const nameSet = new Set(names.map((value) => String(value || "").toLowerCase()));
+  const queue = [];
+  for (const root of roots) {
+    const absoluteRoot = path.resolve(projectRoot, root);
+    if (!pathWithinRoot(projectRoot, absoluteRoot) || !fs.existsSync(absoluteRoot)) {
+      continue;
+    }
+    queue.push({
+      dir: absoluteRoot,
+      depth: 0
+    });
+  }
+  const visited = new Set();
+  let scannedFiles = 0;
+  let scanLimitHit = false;
+  while (queue.length > 0) {
+    const current = queue.pop();
+    if (current.depth > maxDepth) {
+      continue;
+    }
+
+    let resolvedCurrent;
+    try {
+      resolvedCurrent = fs.realpathSync(current.dir);
+    } catch (_error) {
+      continue;
+    }
+    if (visited.has(resolvedCurrent)) {
+      continue;
+    }
+    visited.add(resolvedCurrent);
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current.dir, { withFileTypes: true });
+    } catch (_error) {
+      continue;
+    }
+    for (const entry of entries) {
+      const absolutePath = path.join(current.dir, entry.name);
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        queue.push({
+          dir: absolutePath,
+          depth: current.depth + 1
+        });
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      scannedFiles += 1;
+      if (scannedFiles > TARGET_SCAN_MAX_FILES) {
+        scanLimitHit = true;
+        return {
+          found: false,
+          scanLimitHit
+        };
+      }
+      const normalizedName = entry.name.toLowerCase();
+      if (nameSet.has(normalizedName)) {
+        return {
+          found: true,
+          scanLimitHit
+        };
+      }
+      const ext = path.extname(normalizedName);
+      if (extensionSet.has(ext)) {
+        return {
+          found: true,
+          scanLimitHit
+        };
+      }
+    }
+  }
+  return {
+    found: false,
+    scanLimitHit
+  };
+}
+
+function detectFramework(projectRoot) {
+  const reasons = collectPackageFrameworkSignals(projectRoot);
+
+  const nextConfigFiles = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
+  if (nextConfigFiles.some((file) => fs.existsSync(path.join(projectRoot, file)))) {
+    reasons.next.push("file:next.config");
+  }
+  const scanLimitSignals = [];
+  const nextAppSignal = projectHasAnyFiles(projectRoot, {
+    roots: ["app", "src/app"],
+    names: ["page.tsx", "page.jsx", "page.js", "page.ts"]
+  });
+  if (nextAppSignal.found) {
+    reasons.next.push("convention:app/page");
+  } else if (nextAppSignal.scanLimitHit) {
+    scanLimitSignals.push("next:convention:app/page");
+  }
+  const reactPagesSignal = projectHasAnyFiles(projectRoot, {
+    roots: ["src", "pages", "src/pages"],
+    extensions: [".tsx", ".jsx"]
+  });
+  if (reactPagesSignal.found) {
+    reasons.react.push("convention:tsx-jsx-pages");
+  } else if (reactPagesSignal.scanLimitHit) {
+    scanLimitSignals.push("react:convention:tsx-jsx-pages");
+  }
+  const vueSignal = projectHasAnyFiles(projectRoot, {
+    roots: ["src", "."],
+    extensions: [".vue"]
+  });
+  if (vueSignal.found) {
+    reasons.vue.push("convention:vue-files");
+  } else if (vueSignal.scanLimitHit) {
+    scanLimitSignals.push("vue:convention:vue-files");
+  }
+  const svelteSignal = projectHasAnyFiles(projectRoot, {
+    roots: ["src", "."],
+    extensions: [".svelte"]
+  });
+  if (svelteSignal.found) {
+    reasons.svelte.push("convention:svelte-files");
+  } else if (svelteSignal.scanLimitHit) {
+    scanLimitSignals.push("svelte:convention:svelte-files");
+  }
+
+  const candidates = FRAMEWORKS.filter((framework) => reasons[framework].length > 0);
+  const candidateSet = new Set(candidates);
+  if (candidateSet.has("next") && candidateSet.has("react")) {
+    // Next.js naturally implies React; treat this pair as Next.js rather than ambiguity.
+    candidateSet.delete("react");
+  }
+  const reducedCandidates = FRAMEWORKS.filter((framework) => candidateSet.has(framework));
+
+  if (reducedCandidates.length === 0) {
+    if (scanLimitSignals.length > 0) {
+      return {
+        mode: "ambiguous",
+        candidates: FRAMEWORKS,
+        reasons,
+        scanLimitSignals
+      };
+    }
+    return {
+      mode: "unknown",
+      candidates: [],
+      reasons,
+      scanLimitSignals
+    };
+  }
+
+  if (reducedCandidates.length === 1) {
+    return {
+      mode: reducedCandidates[0],
+      candidates: reducedCandidates,
+      reasons,
+      scanLimitSignals
+    };
+  }
+
+  return {
+    mode: "ambiguous",
+    candidates: reducedCandidates,
+    reasons,
+    scanLimitSignals
+  };
+}
+
+function inferTemplateModeFromLanding(landingPath, frameworkDetection) {
+  const ext = path.extname(landingPath).toLowerCase();
+  const normalizedPath = normalizeRelativePath(landingPath);
+
+  if (ext === ".vue") {
+    return "vue";
+  }
+  if (ext === ".svelte") {
+    return "svelte";
+  }
+  if (ext === ".html") {
+    return "html";
+  }
+  if (ext === ".tsx" || ext === ".jsx" || ext === ".ts" || ext === ".js") {
+    if (/\/app\/.+\/page\.[tj]sx?$/i.test(normalizedPath) || /\/app\/page\.[tj]sx?$/i.test(normalizedPath)) {
+      return "next";
+    }
+    if (frameworkDetection.mode === "next") {
+      return "next";
+    }
+    return "react";
+  }
+  return "html";
 }
 
-function buildSkeletonDocument(mapping) {
+function buildHtmlTemplate(mapping, metadata) {
   return [
     "<!doctype html>",
-    '<html lang="en">',
+    "<html lang=\"en\">",
     "<head>",
-    '  <meta charset="utf-8" />',
-    '  <meta name="viewport" content="width=device-width,initial-scale=1" />',
+    "  <meta charset=\"utf-8\" />",
+    "  <meta name=\"viewport\" content=\"width=device-width,initial-scale=1\" />",
     `  <title>${mapping.designPage || "Scaffold Page"}</title>`,
     "</head>",
     "<body>",
     "  <!-- TODO(scaffold): Replace placeholder skeleton with production implementation. -->",
+    `  <!-- template-mode: ${metadata.templateMode} | framework-detection: ${metadata.frameworkMode} | source: ${metadata.source} -->`,
     `  <!-- mapping: ${mapping.implementation} -> ${mapping.designPage}${mapping.screenId ? ` (${mapping.screenId})` : ""} -->`,
     "  <main>",
     "    <section data-scaffold-region=\"hero\">TODO: implement hero region</section>",
@@ -74,10 +382,76 @@ function buildSkeletonDocument(mapping) {
   ].join("\n");
 }
 
+function buildReactTemplate(mapping, metadata) {
+  return [
+    "// TODO(scaffold): Replace this reviewable scaffold component with production implementation.",
+    `// template-mode: ${metadata.templateMode} | framework-detection: ${metadata.frameworkMode} | source: ${metadata.source}`,
+    `// mapping: ${mapping.implementation} -> ${mapping.designPage}${mapping.screenId ? ` (${mapping.screenId})` : ""}`,
+    "",
+    "export default function ScaffoldPage() {",
+    "  return (",
+    "    <main data-scaffold=\"reviewable-only\">",
+    "      <section data-scaffold-region=\"hero\">TODO(scaffold): implement hero region</section>",
+    "      <section data-scaffold-region=\"content\">TODO(scaffold): implement content regions</section>",
+    "      <section data-scaffold-region=\"actions\">TODO(scaffold): implement action regions</section>",
+    "    </main>",
+    "  );",
+    "}",
+    ""
+  ].join("\n");
+}
+
+function buildVueTemplate(mapping, metadata) {
+  return [
+    "<template>",
+    "  <main data-scaffold=\"reviewable-only\">",
+    "    <section data-scaffold-region=\"hero\">TODO(scaffold): implement hero region</section>",
+    "    <section data-scaffold-region=\"content\">TODO(scaffold): implement content regions</section>",
+    "    <section data-scaffold-region=\"actions\">TODO(scaffold): implement action regions</section>",
+    "  </main>",
+    "</template>",
+    "",
+    "<script setup>",
+    "// TODO(scaffold): Replace this reviewable scaffold component with production implementation.",
+    `// template-mode: ${metadata.templateMode} | framework-detection: ${metadata.frameworkMode} | source: ${metadata.source}`,
+    `// mapping: ${mapping.implementation} -> ${mapping.designPage}${mapping.screenId ? ` (${mapping.screenId})` : ""}`,
+    "</script>",
+    ""
+  ].join("\n");
+}
+
+function buildSvelteTemplate(mapping, metadata) {
+  return [
+    "<!-- TODO(scaffold): Replace this reviewable scaffold component with production implementation. -->",
+    `<!-- template-mode: ${metadata.templateMode} | framework-detection: ${metadata.frameworkMode} | source: ${metadata.source} -->`,
+    `<!-- mapping: ${mapping.implementation} -> ${mapping.designPage}${mapping.screenId ? ` (${mapping.screenId})` : ""} -->`,
+    "<main data-scaffold=\"reviewable-only\">",
+    "  <section data-scaffold-region=\"hero\">TODO(scaffold): implement hero region</section>",
+    "  <section data-scaffold-region=\"content\">TODO(scaffold): implement content regions</section>",
+    "  <section data-scaffold-region=\"actions\">TODO(scaffold): implement action regions</section>",
+    "</main>",
+    ""
+  ].join("\n");
+}
+
+function buildScaffoldDocument(mapping, metadata) {
+  if (metadata.templateMode === "next" || metadata.templateMode === "react") {
+    return buildReactTemplate(mapping, metadata);
+  }
+  if (metadata.templateMode === "vue") {
+    return buildVueTemplate(mapping, metadata);
+  }
+  if (metadata.templateMode === "svelte") {
+    return buildSvelteTemplate(mapping, metadata);
+  }
+  return buildHtmlTemplate(mapping, metadata);
+}
+
 function scaffoldFromBindings(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
   const outputDir = path.resolve(options.outputDir || path.join(projectRoot, ".da-vinci", "scaffold"));
+  const frameworkDetection = detectFramework(projectRoot);
   const result = {
     status: STATUS.PASS,
     failures: [],
@@ -87,7 +461,9 @@ function scaffoldFromBindings(projectPathInput, options = {}) {
     changeId: null,
     outputDir,
     files: [],
-    mvpScope: "single static HTML skeleton per binding; multi-framework expansion is intentionally out of scope."
+    frameworkDetection,
+    mvpScope:
+      "framework-aware reviewable scaffold templates only; generated output remains TODO-marked and non-final."
   };
 
   const resolved = resolveChangeDir(projectRoot, requestedChangeId);
@@ -113,11 +489,47 @@ function scaffoldFromBindings(projectPathInput, options = {}) {
     return result;
   }
 
+  if (frameworkDetection.mode === "unknown") {
+    result.warnings.push("Framework detection is unknown; scaffold falls back to HTML template mode when landing shape is not known.");
+  } else if (frameworkDetection.mode === "ambiguous") {
+    result.warnings.push(
+      `Framework detection is ambiguous (${frameworkDetection.candidates.join(", ")}); scaffold falls back to HTML template mode when landing shape is not known.`
+    );
+  } else {
+    result.notes.push(
+      `Framework detection selected ${frameworkDetection.mode} (${frameworkDetection.reasons[frameworkDetection.mode].join(", ")}).`
+    );
+  }
+  if (Array.isArray(frameworkDetection.scanLimitSignals) && frameworkDetection.scanLimitSignals.length > 0) {
+    result.warnings.push(
+      `Framework detection hit scan limits (${TARGET_SCAN_MAX_FILES} files); unresolved probes: ${frameworkDetection.scanLimitSignals.join(", ")}.`
+    );
+  }
+
   fs.mkdirSync(outputDir, { recursive: true });
   const outputRoot = path.resolve(outputDir);
   const outputRootPrefix = outputRoot.endsWith(path.sep) ? outputRoot : `${outputRoot}${path.sep}`;
   for (const mapping of bindings.mappings) {
-    const targetRelativePath = sanitizeRouteToFileName(mapping.implementation);
+    const landing = resolveImplementationLanding(projectRoot, mapping.implementation);
+
+    let templateMode = "html";
+    let source = "framework-fallback";
+    let targetRelativePath = null;
+    if (landing && pathWithinRoot(projectRoot, landing)) {
+      targetRelativePath = normalizeRelativePath(path.relative(projectRoot, landing));
+      templateMode = inferTemplateModeFromLanding(targetRelativePath, frameworkDetection);
+      source = "existing-landing";
+    } else {
+      if (frameworkDetection.mode === "unknown" || frameworkDetection.mode === "ambiguous") {
+        templateMode = "html";
+        source = frameworkDetection.mode === "unknown" ? "unknown-fallback" : "ambiguous-fallback";
+      } else {
+        templateMode = frameworkDetection.mode;
+        source = "framework-detected";
+      }
+      targetRelativePath = deriveFrameworkTargetPath(mapping.implementation, templateMode);
+    }
+
     if (!targetRelativePath) {
       result.failures.push(
         `Blocked scaffold route \`${mapping.implementation}\`: traversal segments are not allowed.`
@@ -132,12 +544,22 @@ function scaffoldFromBindings(projectPathInput, options = {}) {
       );
       continue;
     }
+
     fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-    writeFileAtomic(targetPath, buildSkeletonDocument(mapping));
+    writeFileAtomic(
+      targetPath,
+      buildScaffoldDocument(mapping, {
+        templateMode,
+        frameworkMode: frameworkDetection.mode,
+        source
+      })
+    );
     result.files.push({
       mapping: mapping.implementation,
       designPage: mapping.designPage,
-      path: targetPath
+      path: targetPath,
+      templateMode,
+      source
     });
   }
 
@@ -151,10 +573,10 @@ function scaffoldFromBindings(projectPathInput, options = {}) {
     "Run `da-vinci verify-bindings`, `da-vinci verify-implementation`, and `da-vinci verify-structure` before accepting scaffold output."
   );
   result.notes.push(
-    "Scaffold boundaries are derived from `pencil-bindings.md` implementation-to-design mappings; no framework-specific expansion is performed."
+    "Known implementation landings keep precedence over framework defaults so scaffold targets match existing project shapes."
   );
-  result.warnings = unique(result.warnings);
   result.notes = unique(result.notes);
+  result.warnings = unique(result.warnings);
   return result;
 }
 
@@ -164,7 +586,8 @@ function formatScaffoldReport(result) {
     `Project: ${result.projectRoot}`,
     `Change: ${result.changeId || "(not selected)"}`,
     `Status: ${result.status}`,
-    `Output dir: ${result.outputDir}`
+    `Output dir: ${result.outputDir}`,
+    `Framework detection: ${result.frameworkDetection ? result.frameworkDetection.mode : "unknown"}`
   ];
   if (result.failures.length > 0) {
     lines.push("", "Failures:");
@@ -172,10 +595,18 @@ function formatScaffoldReport(result) {
       lines.push(`- ${failure}`);
     }
   }
+  if (result.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
   if (result.files.length > 0) {
     lines.push("", "Generated files:");
     for (const file of result.files) {
-      lines.push(`- ${file.path} (${file.mapping} -> ${file.designPage})`);
+      lines.push(
+        `- ${file.path} (${file.mapping} -> ${file.designPage}; mode=${file.templateMode}; source=${file.source})`
+      );
     }
   }
   if (result.notes.length > 0) {

package/lib/utils.js

@@ -28,6 +28,23 @@ function readTextIfExists(targetPath, options = {}) {
   return fs.readFileSync(targetPath, encoding);
 }
 
+function normalizeRelativePath(relativePath) {
+  return String(relativePath || "")
+    .split(path.sep)
+    .filter(Boolean)
+    .join("/");
+}
+
+function pathWithinRoot(projectRoot, candidatePath) {
+  const root = path.resolve(projectRoot);
+  const candidate = path.resolve(candidatePath);
+  if (candidate === root) {
+    return true;
+  }
+  const prefix = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+  return candidate.startsWith(prefix);
+}
+
 function uniqueValues(values) {
   return Array.from(new Set((values || []).filter(Boolean)));
 }
@@ -120,6 +137,8 @@ module.exports = {
   escapeRegExp,
   pathExists,
   readTextIfExists,
+  normalizeRelativePath,
+  pathWithinRoot,
   uniqueValues,
   parseJsonText,
   readJsonFile,