@gurulu/cli 0.1.0 → 0.1.2

package/scripts/gurulu-scan.lib.cjs

@@ -0,0 +1,989 @@
+// gurulu-scan.lib.cjs — detection logic for the repo scanner spike (Phase 13 B2).
+//
+// Exported as CommonJS so it can be loaded both by the ESM CLI wrapper
+// (`scripts/gurulu-scan.mjs`) via native ESM interop AND by ts-jest tests via
+// `require()`. Keeping the library in a single module avoids duplicating the
+// detection heuristics across CLI and tests.
+
+'use strict';
+
+const fs = require('node:fs').promises;
+const path = require('node:path');
+
+const SCAN_VERSION = '2';
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.next',
+  '.git',
+  'dist',
+  'build',
+  'out',
+  '.turbo',
+  '.vercel',
+  'coverage',
+]);
+
+const CODE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+
+// ---------------------------------------------------------------------------
+// Framework detection
+// ---------------------------------------------------------------------------
+function detectFramework(deps = {}) {
+  const has = (name) => Object.prototype.hasOwnProperty.call(deps, name);
+  const ver = (name) =>
+    deps[name] ? String(deps[name]).replace(/^[^\d]*/, '') || null : null;
+
+  if (has('next')) return { name: 'nextjs', version: ver('next') };
+  if (has('@nestjs/core')) return { name: 'nestjs', version: ver('@nestjs/core') };
+  if (has('@remix-run/dev')) return { name: 'remix', version: ver('@remix-run/dev') };
+  if (has('@sveltejs/kit')) return { name: 'sveltekit', version: ver('@sveltejs/kit') };
+  if (has('astro')) return { name: 'astro', version: ver('astro') };
+  if (has('fastify')) return { name: 'fastify', version: ver('fastify') };
+  if (has('express')) return { name: 'express', version: ver('express') };
+  if (has('vite') && has('react')) return { name: 'vite-react', version: ver('vite') };
+  if (has('vue')) return { name: 'vue', version: ver('vue') };
+  return { name: 'unknown', version: null };
+}
+
+// ---------------------------------------------------------------------------
+// ORM detection
+// ---------------------------------------------------------------------------
+function detectORM(deps = {}, schemaHints = {}) {
+  const has = (name) => Object.prototype.hasOwnProperty.call(deps, name);
+
+  if (has('@prisma/client') || has('prisma')) {
+    return { name: 'prisma', schemaPath: schemaHints.prisma || null };
+  }
+  if (has('drizzle-orm')) {
+    return { name: 'drizzle', schemaPath: schemaHints.drizzle || null };
+  }
+  if (has('typeorm')) return { name: 'typeorm', schemaPath: null };
+  if (has('mongoose')) return { name: 'mongoose', schemaPath: null };
+  if (has('sequelize')) return { name: 'sequelize', schemaPath: null };
+  if (has('kysely')) return { name: 'kysely', schemaPath: null };
+  return { name: 'unknown', schemaPath: null };
+}
+
+// ---------------------------------------------------------------------------
+// Auth detection
+// ---------------------------------------------------------------------------
+function detectAuth(deps = {}) {
+  const has = (name) => Object.prototype.hasOwnProperty.call(deps, name);
+
+  if (has('next-auth') || has('@auth/core')) return { name: 'nextauth' };
+  if (has('@clerk/nextjs') || has('@clerk/clerk-sdk-node') || has('@clerk/clerk-js')) {
+    return { name: 'clerk' };
+  }
+  if (
+    has('@supabase/supabase-js') &&
+    Object.keys(deps).some((d) => d.startsWith('@supabase/auth-helpers'))
+  ) {
+    return { name: 'supabase' };
+  }
+  if (has('firebase-admin') || has('firebase')) return { name: 'firebase' };
+  if (has('lucia')) return { name: 'lucia' };
+  if (has('passport')) return { name: 'passport' };
+  if (has('jsonwebtoken')) return { name: 'custom-jwt' };
+  return { name: 'unknown' };
+}
+
+// ---------------------------------------------------------------------------
+// File walking
+// ---------------------------------------------------------------------------
+async function walk(dir, collected = []) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return collected;
+  }
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    if (entry.name.startsWith('.') && entry.name !== '.gurulu') {
+      if (entry.name === '.next' || entry.name === '.git' || entry.name === '.turbo') continue;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walk(full, collected);
+    } else if (entry.isFile()) {
+      collected.push(full);
+    }
+  }
+  return collected;
+}
+
+// ---------------------------------------------------------------------------
+// Route detection (Next.js App + Pages router)
+// ---------------------------------------------------------------------------
+function routePathFromAppRouterFile(relFile) {
+  const parts = relFile.split(path.sep);
+  const appIdx = parts.indexOf('app');
+  if (appIdx === -1) return null;
+  const afterApp = parts.slice(appIdx + 1);
+  if (!/^route\.(ts|tsx|js|jsx|mjs|cjs)$/.test(afterApp[afterApp.length - 1])) return null;
+  const segments = afterApp
+    .slice(0, -1)
+    .filter((seg) => !(seg.startsWith('(') && seg.endsWith(')')) && !seg.startsWith('@'));
+  return '/' + segments.join('/');
+}
+
+function routePathFromPagesRouterFile(relFile) {
+  const parts = relFile.split(path.sep);
+  const pagesIdx = parts.indexOf('pages');
+  if (pagesIdx === -1) return null;
+  const afterPages = parts.slice(pagesIdx + 1);
+  if (afterPages[0] !== 'api') return null;
+  const last = afterPages[afterPages.length - 1].replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '');
+  const segs = afterPages.slice(0, -1).concat(last === 'index' ? [] : [last]);
+  return '/' + segs.join('/');
+}
+
+async function detectRoutes(rootPath, framework) {
+  if (!framework || framework.name !== 'nextjs') {
+    if (
+      framework &&
+      ['express', 'fastify', 'nestjs'].includes(framework.name)
+    ) {
+      return {
+        routes: [],
+        note: `detection_not_implemented_for_${framework.name}`,
+      };
+    }
+    return { routes: [] };
+  }
+
+  const files = await walk(rootPath);
+  const routes = [];
+
+  for (const abs of files) {
+    const rel = path.relative(rootPath, abs);
+    const base = path.basename(abs);
+
+    if (
+      /(^|[\\/])app[\\/]/.test(rel) &&
+      /[\\/]api[\\/]/.test(rel) &&
+      /^route\.(ts|tsx|js|jsx)$/.test(base)
+    ) {
+      const routePath = routePathFromAppRouterFile(rel);
+      if (!routePath) continue;
+      let content = '';
+      try {
+        content = await fs.readFile(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      const methods = [];
+      for (const m of ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']) {
+        const re = new RegExp(
+          `export\\s+(?:async\\s+)?(?:function\\s+${m}\\b|const\\s+${m}\\s*=)`,
+        );
+        if (re.test(content)) methods.push(m);
+      }
+      routes.push({
+        path: routePath,
+        methods: methods.length ? methods : ['*'],
+        file: rel,
+      });
+      continue;
+    }
+
+    if (
+      /(^|[\\/])pages[\\/]api[\\/]/.test(rel) &&
+      /\.(ts|tsx|js|jsx)$/.test(base) &&
+      base !== '_middleware.ts'
+    ) {
+      const routePath = routePathFromPagesRouterFile(rel);
+      if (!routePath) continue;
+      let content = '';
+      try {
+        content = await fs.readFile(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      const methods = [];
+      const methodRe = /req\.method\s*===?\s*['"`](GET|POST|PUT|DELETE|PATCH)['"`]/g;
+      let match;
+      while ((match = methodRe.exec(content)) !== null) {
+        if (!methods.includes(match[1])) methods.push(match[1]);
+      }
+      routes.push({
+        path: routePath,
+        methods: methods.length ? methods : ['*'],
+        file: rel,
+      });
+    }
+  }
+
+  routes.sort((a, b) => (a.path + a.file).localeCompare(b.path + b.file));
+  return { routes };
+}
+
+// ---------------------------------------------------------------------------
+// Business mutation detection
+// ---------------------------------------------------------------------------
+const MUTATION_PATTERNS = [
+  {
+    kind: 'prisma',
+    re: /prisma\.([a-zA-Z_][a-zA-Z0-9_]*)\.(create|createMany|update|updateMany|upsert|delete|deleteMany)\s*\(/g,
+    extract: (m) => ({ model: m[1], operation: m[2] }),
+  },
+  {
+    kind: 'drizzle',
+    re: /\bdb\.(insert|update|delete)\s*\(\s*([a-zA-Z_][a-zA-Z0-9_]*)?/g,
+    extract: (m) => ({ model: m[2] || 'unknown', operation: m[1] }),
+  },
+  {
+    kind: 'mongoose',
+    re: /\b([A-Z][a-zA-Z0-9_]*)\.(create|findOneAndUpdate|findOneAndDelete|deleteOne|deleteMany|updateOne|updateMany|insertMany)\s*\(/g,
+    extract: (m) => ({ model: m[1], operation: m[2] }),
+  },
+  {
+    kind: 'raw-sql',
+    re: /\b(INSERT\s+INTO|UPDATE|DELETE\s+FROM)\s+([`"']?[a-zA-Z_][a-zA-Z0-9_]*[`"']?)/gi,
+    extract: (m) => ({
+      model: m[2].replace(/[`"']/g, ''),
+      operation: m[1].trim().split(/\s+/)[0].toLowerCase(),
+    }),
+  },
+];
+
+async function detectMutations(rootPath, { limit = 200 } = {}) {
+  const files = await walk(rootPath);
+  const results = [];
+  const seen = new Set();
+
+  outer: for (const abs of files) {
+    const ext = path.extname(abs);
+    if (!CODE_EXTS.has(ext)) continue;
+    const rel = path.relative(rootPath, abs);
+    let content;
+    try {
+      content = await fs.readFile(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (content.length > 1_500_000) continue;
+
+    const lines = content.split(/\r?\n/);
+    for (const pattern of MUTATION_PATTERNS) {
+      const re = new RegExp(pattern.re.source, pattern.re.flags);
+      let match;
+      while ((match = re.exec(content)) !== null) {
+        const info = pattern.extract(match);
+        const upto = content.slice(0, match.index);
+        const line = upto.split(/\r?\n/).length;
+        const snippet = (lines[line - 1] || '').trim().slice(0, 200);
+        const key = `${rel}:${line}:${info.model}:${info.operation}:${snippet}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        results.push({
+          file: rel,
+          line,
+          model: info.model,
+          operation: info.operation,
+          snippet,
+        });
+        if (results.length >= limit) break outer;
+      }
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Schema hint detection
+// ---------------------------------------------------------------------------
+async function detectSchemaHints(rootPath) {
+  const hints = {};
+  try {
+    await fs.access(path.join(rootPath, 'prisma', 'schema.prisma'));
+    hints.prisma = 'prisma/schema.prisma';
+  } catch {
+    /* noop */
+  }
+  for (const candidate of ['drizzle.config.ts', 'drizzle.config.js', 'drizzle.config.mjs']) {
+    try {
+      await fs.access(path.join(rootPath, candidate));
+      hints.drizzle = candidate;
+      break;
+    } catch {
+      /* noop */
+    }
+  }
+  return hints;
+}
+
+// ---------------------------------------------------------------------------
+// Phase 18.6 A1 — Enhanced signal extractors
+// ---------------------------------------------------------------------------
+
+// Simplified Prisma field type classifier.
+function simplifyPrismaType(raw) {
+  const t = String(raw).replace(/[\?\[\]]/g, '');
+  if (/^(String|Int|BigInt|Float|Decimal|Boolean|DateTime|Json|Bytes)$/.test(t)) {
+    return t;
+  }
+  // Anything else is either an enum or a relation.
+  return /^[A-Z]/.test(t) ? `relation:${t}` : t;
+}
+
+/**
+ * extractSchemaTables — parse ORM schema files for model/table structure.
+ *
+ * `orm.name === 'prisma'` parses prisma/schema.prisma. Drizzle/TypeORM get a
+ * best-effort regex sweep. Capped at 50 tables / 200 columns total to keep
+ * LLM prompt size bounded.
+ *
+ * Accepts an optional `schemaContent` argument so tests can pass inline
+ * fixtures without touching the filesystem.
+ */
+async function extractSchemaTables(rootPath, orm, schemaContent) {
+  const MAX_TABLES = 50;
+  const MAX_COLUMNS_TOTAL = 200;
+  const tables = [];
+  let totalColumns = 0;
+
+  if (!orm || !orm.name) return tables;
+
+  let content = schemaContent;
+
+  if (orm.name === 'prisma') {
+    if (!content) {
+      const schemaRel = orm.schemaPath || 'prisma/schema.prisma';
+      try {
+        content = await fs.readFile(path.join(rootPath, schemaRel), 'utf8');
+      } catch {
+        return tables;
+      }
+    }
+    const modelRe = /model\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([\s\S]*?)\}/g;
+    let m;
+    while ((m = modelRe.exec(content)) !== null && tables.length < MAX_TABLES) {
+      const name = m[1];
+      const body = m[2];
+      const columns = [];
+      for (const line of body.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('@@')) continue;
+        const fm = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z_][A-Za-z0-9_\?\[\]]*)/);
+        if (!fm) continue;
+        columns.push({ name: fm[1], type: simplifyPrismaType(fm[2]) });
+        totalColumns++;
+        if (totalColumns >= MAX_COLUMNS_TOTAL) break;
+      }
+      tables.push({ name, columns });
+      if (totalColumns >= MAX_COLUMNS_TOTAL) break;
+    }
+    return tables;
+  }
+
+  if (orm.name === 'drizzle') {
+    if (!content) {
+      // Best-effort sweep through src/ for drizzle table definitions.
+      try {
+        const files = await walk(rootPath);
+        const chunks = [];
+        for (const abs of files) {
+          if (!CODE_EXTS.has(path.extname(abs))) continue;
+          try {
+            const text = await fs.readFile(abs, 'utf8');
+            if (/pgTable\s*\(|mysqlTable\s*\(|sqliteTable\s*\(/.test(text)) {
+              chunks.push(text);
+            }
+          } catch {
+            /* skip */
+          }
+          if (chunks.length > 20) break;
+        }
+        content = chunks.join('\n\n');
+      } catch {
+        return tables;
+      }
+    }
+    const tableRe =
+      /(?:pgTable|mysqlTable|sqliteTable)\s*\(\s*['"`]([A-Za-z_][A-Za-z0-9_]*)['"`]\s*,\s*\{([\s\S]*?)\}\s*\)/g;
+    let m;
+    while ((m = tableRe.exec(content)) !== null && tables.length < MAX_TABLES) {
+      const name = m[1];
+      const body = m[2];
+      const columns = [];
+      const colRe = /([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+      let cm;
+      while ((cm = colRe.exec(body)) !== null) {
+        columns.push({ name: cm[1], type: cm[2] });
+        totalColumns++;
+        if (totalColumns >= MAX_COLUMNS_TOTAL) break;
+      }
+      tables.push({ name, columns });
+      if (totalColumns >= MAX_COLUMNS_TOTAL) break;
+    }
+    return tables;
+  }
+
+  if (orm.name === 'typeorm') {
+    if (!content) {
+      try {
+        const files = await walk(rootPath);
+        const chunks = [];
+        for (const abs of files) {
+          if (!CODE_EXTS.has(path.extname(abs))) continue;
+          try {
+            const text = await fs.readFile(abs, 'utf8');
+            if (/@Entity\s*\(/.test(text)) chunks.push(text);
+          } catch {
+            /* skip */
+          }
+        }
+        content = chunks.join('\n\n');
+      } catch {
+        return tables;
+      }
+    }
+    const entityRe =
+      /@Entity\s*\([^)]*\)\s*export\s+class\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([\s\S]*?)\n\}/g;
+    let m;
+    while ((m = entityRe.exec(content)) !== null && tables.length < MAX_TABLES) {
+      const name = m[1];
+      const body = m[2];
+      const columns = [];
+      const colRe = /@Column\s*\([^)]*\)\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([A-Za-z_][A-Za-z0-9_]*)/g;
+      let cm;
+      while ((cm = colRe.exec(body)) !== null) {
+        columns.push({ name: cm[1], type: cm[2] });
+        totalColumns++;
+        if (totalColumns >= MAX_COLUMNS_TOTAL) break;
+      }
+      tables.push({ name, columns });
+      if (totalColumns >= MAX_COLUMNS_TOTAL) break;
+    }
+    return tables;
+  }
+
+  return tables;
+}
+
+/**
+ * extractDependencyFingerprint — filter package.json deps to curated
+ * business-signal allowlist. Returns unique sorted array of matched names.
+ */
+const BUSINESS_DEPS = [
+  'stripe', '@stripe/stripe-js', '@stripe/react-stripe-js',
+  'plaid', 'dwolla-v2',
+  'twilio', '@sendgrid/mail', 'resend', 'postmark',
+  '@jumio/sdk', 'onfido', 'veriff',
+  'shopify-api', '@shopify/shopify-api', '@medusajs',
+  'next-auth', '@auth/core', '@clerk/nextjs', '@clerk/clerk-sdk-node',
+  '@supabase/supabase-js', '@supabase/auth-helpers-nextjs',
+  '@lemonsqueezy/lemonsqueezy.js', 'revenuecat-node',
+  'algolia', 'meilisearch', 'elasticsearch', '@pinecone-database/pinecone',
+  'openai', '@anthropic-ai/sdk', 'cohere-ai',
+  'mux-node', '@mux/mux-player-react', '@vimeo/player',
+  'mapbox', 'google-maps', '@googlemaps/js-api-loader',
+  '@segment/analytics-next', 'mixpanel', 'amplitude-js',
+  'pusher', '@soketi/soketi', 'ably',
+  'prisma', 'drizzle-orm', 'typeorm', 'mongoose', 'sequelize',
+  'redis', 'ioredis', 'bullmq',
+  'bcrypt', 'argon2', 'jsonwebtoken',
+  'socket.io', 'ws', '@trpc/server',
+  'framer-motion', 'react-hook-form', 'zod', 'yup',
+];
+const BUSINESS_DEPS_SET = new Set(BUSINESS_DEPS);
+
+function extractDependencyFingerprint(packageJson) {
+  if (!packageJson || typeof packageJson !== 'object') return [];
+  const deps = {
+    ...(packageJson.dependencies || {}),
+    ...(packageJson.devDependencies || {}),
+  };
+  const matched = new Set();
+  for (const name of Object.keys(deps)) {
+    if (BUSINESS_DEPS_SET.has(name)) matched.add(name);
+  }
+  return Array.from(matched).sort();
+}
+
+// ---------------------------------------------------------------------------
+// extractUiStrings — harvest user-facing strings from JSX/templates.
+// ---------------------------------------------------------------------------
+
+const UI_PROP_NAMES = new Set([
+  'title', 'label', 'placeholder', 'heading', 'description',
+  'aria-label', 'alt', 'subtitle', 'caption', 'tooltip',
+]);
+
+function looksTechnical(s) {
+  if (s.length < 3) return true;
+  if (/^[a-z-]+$/.test(s)) return true; // slugs
+  if (/^[\w-]+\/[\w\-./]+$/.test(s)) return true; // paths / modules
+  if (/^https?:\/\//.test(s)) return true;
+  if (/^\.\.?\//.test(s)) return true;
+  if (/^[a-z]+:[a-z-]+/.test(s)) return true; // protocol: / css-like
+  // Tailwind / CSS className heuristic: tokens separated by spaces, all lower.
+  if (/\s/.test(s) && /^[\w\s:\-\[\]\/\.]+$/.test(s) && !/[A-Z]/.test(s) && s.split(/\s+/).every((t) => /^[\w:\-\[\]\/\.]+$/.test(t) && /[-:]/.test(t))) {
+    return true;
+  }
+  if (/^[a-z0-9]+(-[a-z0-9]+)+$/.test(s)) return true;
+  // Paths / package-style identifiers: must contain a / or _ and no spaces.
+  if (/^@?[a-z0-9._/-]+$/i.test(s) && /[\/_]/.test(s) && !/\s/.test(s)) return true;
+  if (/^#[0-9a-f]{3,8}$/i.test(s)) return true;
+  return false;
+}
+
+/**
+ * extractUiStringsFromSource — pure function so tests can pass inline source.
+ */
+function extractUiStringsFromSource(source, { limit = 500, existing } = {}) {
+  const out = existing instanceof Set ? existing : new Set();
+
+  // JSX text nodes: >Text here<
+  const jsxTextRe = />([^<>{}]{3,200})</g;
+  let m;
+  while ((m = jsxTextRe.exec(source)) !== null) {
+    const raw = m[1].trim();
+    if (!raw) continue;
+    if (/^\s*$/.test(raw)) continue;
+    if (/^\{.*\}$/.test(raw)) continue;
+    if (looksTechnical(raw)) continue;
+    out.add(raw);
+    if (out.size >= limit) return Array.from(out);
+  }
+
+  // Props: title="...", label={"..."}
+  const propRe = /\b([a-zA-Z-]+)\s*=\s*(?:\{\s*['"`]([^'"`]{3,200})['"`]\s*\}|['"`]([^'"`]{3,200})['"`])/g;
+  while ((m = propRe.exec(source)) !== null) {
+    const prop = m[1];
+    if (!UI_PROP_NAMES.has(prop)) continue;
+    const val = (m[2] || m[3] || '').trim();
+    if (!val) continue;
+    if (looksTechnical(val)) continue;
+    out.add(val);
+    if (out.size >= limit) return Array.from(out);
+  }
+
+  // toast.*(...), alert(...), confirm(...), prompt(...)
+  const callRe = /\b(?:toast(?:\.[a-zA-Z]+)?|alert|confirm|prompt)\s*\(\s*['"`]([^'"`]{3,200})['"`]/g;
+  while ((m = callRe.exec(source)) !== null) {
+    const val = m[1].trim();
+    if (!val || looksTechnical(val)) continue;
+    out.add(val);
+    if (out.size >= limit) return Array.from(out);
+  }
+
+  return Array.from(out);
+}
+
+async function extractUiStrings(rootPath, framework) {
+  const limit = 500;
+  const collected = new Set();
+  const exts = new Set(['.tsx', '.jsx']);
+  if (framework && framework.name === 'vue') exts.add('.vue');
+  if (framework && framework.name === 'sveltekit') exts.add('.svelte');
+
+  let files;
+  try {
+    files = await walk(rootPath);
+  } catch {
+    return [];
+  }
+  for (const abs of files) {
+    if (collected.size >= limit) break;
+    if (!exts.has(path.extname(abs))) continue;
+    let text;
+    try {
+      text = await fs.readFile(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (text.length > 500_000) continue;
+    extractUiStringsFromSource(text, { limit, existing: collected });
+  }
+  return Array.from(collected).slice(0, limit);
+}
+
+// ---------------------------------------------------------------------------
+// extractI18nKeys — recursive key-path harvest from JSON locale files.
+// ---------------------------------------------------------------------------
+
+function harvestKeyPaths(obj, prefix, out, cap) {
+  if (out.size >= cap) return;
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return;
+  for (const k of Object.keys(obj)) {
+    const full = prefix ? `${prefix}.${k}` : k;
+    const v = obj[k];
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      harvestKeyPaths(v, full, out, cap);
+    } else {
+      out.add(full);
+    }
+    if (out.size >= cap) return;
+  }
+}
+
+async function extractI18nKeys(rootPath, { inlineFiles } = {}) {
+  const cap = 200;
+  const keys = new Set();
+
+  if (inlineFiles) {
+    for (const obj of inlineFiles) {
+      harvestKeyPaths(obj, '', keys, cap);
+      if (keys.size >= cap) break;
+    }
+    return Array.from(keys).slice(0, cap);
+  }
+
+  const candidateDirs = [
+    path.join(rootPath, 'src', 'i18n'),
+    path.join(rootPath, 'messages'),
+    path.join(rootPath, 'locales'),
+    path.join(rootPath, 'public', 'locales'),
+    path.join(rootPath, 'src', 'locales'),
+  ];
+
+  for (const dir of candidateDirs) {
+    let files;
+    try {
+      files = await walk(dir);
+    } catch {
+      continue;
+    }
+    for (const abs of files) {
+      if (path.extname(abs) !== '.json') continue;
+      let text;
+      try {
+        text = await fs.readFile(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      try {
+        const parsed = JSON.parse(text);
+        harvestKeyPaths(parsed, '', keys, cap);
+      } catch {
+        /* skip malformed */
+      }
+      if (keys.size >= cap) break;
+    }
+    if (keys.size >= cap) break;
+  }
+
+  return Array.from(keys).slice(0, cap);
+}
+
+// ---------------------------------------------------------------------------
+// extractFolderStructureHints — list significant route / api subfolders.
+// ---------------------------------------------------------------------------
+
+async function extractFolderStructureHints(rootPath, framework) {
+  const cap = 100;
+  const hints = new Set();
+
+  async function listDirs(root) {
+    const out = [];
+    let entries;
+    try {
+      entries = await fs.readdir(root, { withFileTypes: true });
+    } catch {
+      return out;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.startsWith('_')) continue; // private
+      if (SKIP_DIRS.has(e.name)) continue;
+      out.push(e.name);
+    }
+    return out;
+  }
+
+  async function walkDirs(root, prefix, depth) {
+    if (depth < 0 || hints.size >= cap) return;
+    const dirs = await listDirs(root);
+    for (const d of dirs) {
+      const full = prefix ? `${prefix}/${d}` : d;
+      hints.add(full);
+      if (hints.size >= cap) return;
+      await walkDirs(path.join(root, d), full, depth - 1);
+    }
+  }
+
+  if (framework && framework.name === 'nextjs') {
+    // App Router
+    for (const base of ['src/app', 'app']) {
+      const root = path.join(rootPath, base);
+      try {
+        await fs.access(root);
+        await walkDirs(root, base, 3);
+      } catch {
+        /* skip */
+      }
+    }
+    // Pages Router
+    for (const base of ['src/pages/api', 'pages/api']) {
+      const root = path.join(rootPath, base);
+      try {
+        await fs.access(root);
+        await walkDirs(root, base, 3);
+      } catch {
+        /* skip */
+      }
+    }
+  } else if (framework && ['express', 'fastify', 'nestjs'].includes(framework.name)) {
+    for (const base of ['src/routes', 'routes', 'src/controllers', 'src/modules']) {
+      const root = path.join(rootPath, base);
+      try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isFile()) {
+            hints.add(`${base}/${e.name.replace(/\.(ts|js|mjs)$/, '')}`);
+          } else if (e.isDirectory() && !SKIP_DIRS.has(e.name)) {
+            hints.add(`${base}/${e.name}`);
+          }
+          if (hints.size >= cap) break;
+        }
+      } catch {
+        /* skip */
+      }
+    }
+  }
+
+  return Array.from(hints).slice(0, cap);
+}
+
+// ---------------------------------------------------------------------------
+// extractEnvVarHints — parse .env.example/.env for variable NAMES (never values).
+// ---------------------------------------------------------------------------
+
+function extractEnvNamesFromContent(content) {
+  const names = new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const m = trimmed.match(/^(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/);
+    if (m) names.add(m[1]);
+  }
+  return names;
+}
+
+async function extractEnvVarHints(rootPath, { inlineContent } = {}) {
+  const cap = 100;
+  const names = new Set();
+
+  if (inlineContent !== undefined) {
+    for (const n of extractEnvNamesFromContent(inlineContent)) names.add(n);
+    return Array.from(names).slice(0, cap);
+  }
+
+  const candidates = ['.env.example', '.env.sample', '.env.local.example', '.env'];
+  for (const c of candidates) {
+    let text;
+    try {
+      text = await fs.readFile(path.join(rootPath, c), 'utf8');
+    } catch {
+      continue;
+    }
+    for (const n of extractEnvNamesFromContent(text)) {
+      names.add(n);
+      if (names.size >= cap) break;
+    }
+    if (names.size >= cap) break;
+  }
+
+  return Array.from(names).slice(0, cap);
+}
+
+// ---------------------------------------------------------------------------
+// extractCommentBlockHints — grab first lines of JSDoc / block comments that
+// mention business-term trigger words.
+// ---------------------------------------------------------------------------
+
+const BUSINESS_TRIGGER_WORDS = [
+  'order', 'payment', 'checkout', 'subscription', 'user', 'account',
+  'bet', 'odds', 'wager', 'wallet', 'deposit', 'withdrawal', 'kyc',
+  'patient', 'appointment', 'prescription', 'provider',
+  'course', 'lesson', 'enrollment', 'student',
+  'policy', 'claim', 'invoice', 'transaction', 'card',
+  'product', 'cart', 'shipment', 'refund', 'catalog',
+  'listing', 'reservation', 'booking', 'ticket',
+];
+const TRIGGER_RE = new RegExp(`\\b(${BUSINESS_TRIGGER_WORDS.join('|')})s?\\b`, 'i');
+
+function extractCommentsFromSource(source) {
+  const out = [];
+  const blockRe = /\/\*\*?([\s\S]*?)\*\//g;
+  let m;
+  while ((m = blockRe.exec(source)) !== null) {
+    const body = m[1];
+    const firstLine = body
+      .split(/\r?\n/)
+      .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+      .find((l) => l.length > 0);
+    if (!firstLine) continue;
+    if (!TRIGGER_RE.test(firstLine)) continue;
+    out.push(firstLine.slice(0, 160));
+  }
+  return out;
+}
+
+async function extractCommentBlockHints(rootPath) {
+  const cap = 50;
+  const out = [];
+  let files;
+  try {
+    files = await walk(rootPath);
+  } catch {
+    return out;
+  }
+  for (const abs of files) {
+    if (out.length >= cap) break;
+    if (!CODE_EXTS.has(path.extname(abs))) continue;
+    let text;
+    try {
+      text = await fs.readFile(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (text.length > 1_500_000) continue;
+    for (const c of extractCommentsFromSource(text)) {
+      out.push(c);
+      if (out.length >= cap) break;
+    }
+  }
+  return out.slice(0, cap);
+}
+
+// ---------------------------------------------------------------------------
+// Aggregated scan
+// ---------------------------------------------------------------------------
+async function scanRepo(rootPath, { log = () => {} } = {}) {
+  const abs = path.resolve(rootPath);
+  log(`[scan] root: ${abs}`);
+
+  let pkg = {};
+  try {
+    const raw = await fs.readFile(path.join(abs, 'package.json'), 'utf8');
+    pkg = JSON.parse(raw);
+  } catch {
+    log('[scan] no package.json — continuing with empty deps');
+  }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+
+  const framework = detectFramework(deps);
+  log(`[scan] framework: ${framework.name} ${framework.version || ''}`);
+
+  const schemaHints = await detectSchemaHints(abs);
+  const orm = detectORM(deps, schemaHints);
+  log(`[scan] orm: ${orm.name}`);
+
+  const auth = detectAuth(deps);
+  log(`[scan] auth: ${auth.name}`);
+
+  let scanRoot = abs;
+  try {
+    const srcStat = await fs.stat(path.join(abs, 'src'));
+    if (srcStat.isDirectory()) scanRoot = path.join(abs, 'src');
+  } catch {
+    /* fallback to root */
+  }
+  log(`[scan] walk root: ${path.relative(abs, scanRoot) || '.'}`);
+
+  const { routes, note: routeNote } = await detectRoutes(scanRoot, framework);
+  log(`[scan] routes: ${routes.length}${routeNote ? ` (${routeNote})` : ''}`);
+
+  const mutations = await detectMutations(scanRoot);
+  log(`[scan] mutations: ${mutations.length}`);
+
+  // Phase 18.6 A1 — enriched signal extraction
+  const schemaTables = await extractSchemaTables(abs, orm);
+  log(`[scan] schemaTables: ${schemaTables.length}`);
+
+  const dependencyFingerprint = extractDependencyFingerprint(pkg);
+  log(`[scan] dependencyFingerprint: ${dependencyFingerprint.length}`);
+
+  const uiStrings = await extractUiStrings(scanRoot, framework);
+  log(`[scan] uiStrings: ${uiStrings.length}`);
+
+  const i18nKeys = await extractI18nKeys(abs);
+  log(`[scan] i18nKeys: ${i18nKeys.length}`);
+
+  const folderStructureHints = await extractFolderStructureHints(abs, framework);
+  log(`[scan] folderStructureHints: ${folderStructureHints.length}`);
+
+  const envVarHints = await extractEnvVarHints(abs);
+  log(`[scan] envVarHints: ${envVarHints.length}`);
+
+  const commentBlockHints = await extractCommentBlockHints(scanRoot);
+  log(`[scan] commentBlockHints: ${commentBlockHints.length}`);
+
+  // Rough total file count (for metadata only).
+  let totalFiles = 0;
+  try {
+    const files = await walk(scanRoot);
+    totalFiles = files.length;
+  } catch {
+    /* skip */
+  }
+
+  const normalizedRoutes = (routes || []).flatMap((r) =>
+    (r.methods && r.methods.length ? r.methods : ['*']).map((method) => ({
+      method,
+      path: r.path,
+    })),
+  );
+
+  const normalizedMutations = (mutations || []).map((m) => ({
+    file: m.file,
+    op: `${m.model || 'unknown'}.${m.operation}`,
+    model: m.model || undefined,
+  }));
+
+  const plan = {
+    site_id: null,
+    domains: [],
+    framework,
+    orm,
+    auth,
+    routes: normalizedRoutes,
+    rawRoutes: routes,
+    businessSurfaces: [],
+    mutations: normalizedMutations,
+    rawMutations: mutations,
+    schemaTables,
+    dependencyFingerprint,
+    uiStrings,
+    envVarHints,
+    folderStructureHints,
+    commentBlockHints,
+    i18nKeys,
+    metadata: {
+      scannedAt: new Date().toISOString(),
+      scanVersion: SCAN_VERSION,
+      repoPath: abs,
+      totalFiles,
+    },
+    scannedAt: new Date().toISOString(),
+    scanVersion: SCAN_VERSION,
+  };
+  if (routeNote) plan.routeDetectionNote = routeNote;
+  return plan;
+}
+
+module.exports = {
+  SCAN_VERSION,
+  detectFramework,
+  detectORM,
+  detectAuth,
+  detectRoutes,
+  detectMutations,
+  scanRepo,
+  // Phase 18.6 A1
+  extractSchemaTables,
+  extractDependencyFingerprint,
+  extractUiStrings,
+  extractUiStringsFromSource,
+  extractI18nKeys,
+  extractFolderStructureHints,
+  extractEnvVarHints,
+  extractCommentBlockHints,
+  extractCommentsFromSource,
+  BUSINESS_DEPS,
+};