@fragments-sdk/cli 0.9.0 → 0.10.0

package/src/commands/scan-generate.ts

@@ -0,0 +1,1013 @@
+/**
+ * fragments init --scan - Generate fragment files from any TypeScript component library
+ *
+ * Phase 2 of the Universal GenUI strategy. Scans a component directory and
+ * generates .fragment.tsx files with TODO markers for uncertain fields.
+ *
+ * Combines:
+ * - Component discovery (core/discovery.ts)
+ * - Props extraction (service/enhance/props-extractor.ts)
+ * - JSDoc extraction (new: TypeScript AST)
+ * - Compound component detection (new: Object.assign pattern)
+ * - Confidence scoring with TODO markers
+ */
+
+import { readFile, writeFile, access, mkdir } from "node:fs/promises";
+import { resolve, basename, dirname, relative, join } from "node:path";
+import * as ts from "typescript";
+import pc from "picocolors";
+import { BRAND } from "../core/index.js";
+import {
+  discoverAllComponents,
+  type DiscoveredComponent,
+} from "../core/node.js";
+import {
+  extractPropsFromFile,
+  convertToFragmentProps,
+  type PropsExtractionResult,
+  type ExtractedProp,
+} from "../service/index.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ScanGenerateOptions {
+  /** Path to scan for components */
+  scanPath: string;
+  /** Output directory (default: colocated with source) */
+  outputDir?: string;
+  /** Overwrite existing fragment files */
+  force?: boolean;
+  /** Custom component file patterns */
+  patterns?: string[];
+  /** Skip Storybook story extraction */
+  skipStorybook?: boolean;
+  /** Verbose logging */
+  verbose?: boolean;
+}
+
+export interface ScanGenerateResult {
+  success: boolean;
+  generated: Array<{
+    name: string;
+    path: string;
+    confidence: number;
+    todoCount: number;
+  }>;
+  skipped: Array<{ name: string; reason: string }>;
+  errors: Array<{ name: string; error: string }>;
+  averageConfidence: number;
+}
+
+interface ComponentData {
+  component: DiscoveredComponent;
+  props: PropsExtractionResult | null;
+  jsDoc: string | null;
+  compoundChildren: string[];
+  storyVariants: StoryVariant[];
+}
+
+interface StoryVariant {
+  name: string;
+  args: Record<string, unknown>;
+}
+
+interface FieldConfidence {
+  score: number;
+  todoFields: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Main orchestrator
+// ---------------------------------------------------------------------------
+
+export async function scanGenerate(
+  options: ScanGenerateOptions
+): Promise<ScanGenerateResult> {
+  const scanPath = resolve(options.scanPath);
+  const generated: ScanGenerateResult["generated"] = [];
+  const skipped: ScanGenerateResult["skipped"] = [];
+  const errors: ScanGenerateResult["errors"] = [];
+
+  console.log(pc.cyan(`\n${BRAND.name} Scan → Generate\n`));
+  console.log(pc.dim(`Scanning: ${scanPath}\n`));
+
+  // Phase 1: Discover components
+  console.log(pc.dim("Phase 1: Discovering components..."));
+
+  // Use broader patterns than default — the scan path IS the component root,
+  // not a project root with src/components/ inside it
+  const defaultScanPatterns = [
+    "**/*.tsx",
+    "**/*.ts",
+  ];
+
+  const components = await discoverAllComponents(scanPath, {
+    patterns: options.patterns || defaultScanPatterns,
+    exclude: [
+      "**/*.test.*",
+      "**/*.spec.*",
+      "**/*.stories.*",
+      "**/*.fragment.*",
+      "**/*.d.ts",
+      "**/__tests__/**",
+      "**/__mocks__/**",
+      "**/node_modules/**",
+      "**/dist/**",
+    ],
+  });
+
+  if (components.length === 0) {
+    console.log(
+      pc.yellow("No components found. Check the path or file patterns.")
+    );
+    return {
+      success: false,
+      generated: [],
+      skipped: [],
+      errors: [{ name: "*", error: "No components found" }],
+      averageConfidence: 0,
+    };
+  }
+
+  console.log(pc.green(`  Found ${components.length} components`));
+
+  // Phase 2: Extract data for each component
+  console.log(pc.dim("\nPhase 2: Extracting component metadata..."));
+
+  const componentDataList: ComponentData[] = [];
+
+  for (const comp of components) {
+    let propsResult: PropsExtractionResult | null = null;
+    try {
+      propsResult = await extractPropsFromFile(comp.sourcePath, {
+        propsTypeName: `${comp.name}Props`,
+      });
+    } catch {
+      // Props extraction can fail for complex types — continue gracefully
+    }
+
+    let jsDoc: string | null = null;
+    try {
+      jsDoc = await extractComponentJSDoc(comp.sourcePath, comp.name);
+    } catch {
+      // JSDoc extraction failure is non-fatal
+    }
+
+    let compoundChildren: string[] = [];
+    try {
+      compoundChildren = await detectCompoundComponents(comp.sourcePath);
+    } catch {
+      // Compound detection failure is non-fatal
+    }
+
+    let storyVariants: StoryVariant[] = [];
+    if (!options.skipStorybook && comp.storyPath) {
+      try {
+        storyVariants = await extractStoryVariantsFromFile(comp.storyPath);
+      } catch {
+        // Story extraction failure is non-fatal
+      }
+    }
+
+    componentDataList.push({
+      component: comp,
+      props: propsResult,
+      jsDoc,
+      compoundChildren,
+      storyVariants,
+    });
+  }
+
+  const propsExtracted = componentDataList.filter(
+    (d) => d.props?.success && d.props.props.length > 0
+  ).length;
+  console.log(pc.green(`  Extracted props for ${propsExtracted} components`));
+
+  // Phase 3: Generate fragment files
+  console.log(pc.dim("\nPhase 3: Generating fragment files..."));
+
+  for (const data of componentDataList) {
+    const comp = data.component;
+    const componentDir = dirname(comp.sourcePath);
+    const componentBaseName = basename(comp.sourcePath, ".tsx");
+
+    // Determine output path
+    let fragmentDir: string;
+    if (options.outputDir) {
+      fragmentDir = resolve(options.outputDir, comp.name);
+      await mkdir(fragmentDir, { recursive: true });
+    } else {
+      fragmentDir = componentDir;
+    }
+
+    const fragmentPath = join(
+      fragmentDir,
+      `${componentBaseName}${BRAND.fileExtension}`
+    );
+
+    // Check if fragment already exists
+    let fragmentExists = false;
+    try {
+      await access(fragmentPath);
+      fragmentExists = true;
+    } catch {
+      // Doesn't exist
+    }
+
+    if (fragmentExists && !options.force) {
+      skipped.push({ name: comp.name, reason: "Fragment already exists" });
+      if (options.verbose) {
+        console.log(pc.dim(`  Skipping ${comp.name} (fragment exists)`));
+      }
+      continue;
+    }
+
+    try {
+      // Calculate confidence
+      const confidence = calculateFieldConfidence(data);
+
+      // Compute import path
+      const importPath = computeImportPath(
+        fragmentDir,
+        comp.sourcePath,
+        componentBaseName
+      );
+
+      // Generate the fragment file
+      const content = generateFragmentWithTodos(
+        comp.name,
+        importPath,
+        data,
+        confidence
+      );
+
+      await writeFile(fragmentPath, content, "utf-8");
+
+      const relPath = relative(process.cwd(), fragmentPath);
+      generated.push({
+        name: comp.name,
+        path: relPath,
+        confidence: confidence.score,
+        todoCount: confidence.todoFields.length,
+      });
+
+      const confColor =
+        confidence.score >= 70
+          ? pc.green
+          : confidence.score >= 40
+            ? pc.yellow
+            : pc.red;
+      console.log(
+        pc.green(`  ✓ ${comp.name}`) +
+          pc.dim(` (confidence: `) +
+          confColor(`${confidence.score}`) +
+          pc.dim(`, TODOs: ${confidence.todoFields.length})`)
+      );
+    } catch (e) {
+      errors.push({
+        name: comp.name,
+        error: e instanceof Error ? e.message : String(e),
+      });
+      console.log(pc.red(`  ✗ ${comp.name}: ${e instanceof Error ? e.message : String(e)}`));
+    }
+  }
+
+  // Summary
+  const avgConfidence =
+    generated.length > 0
+      ? Math.round(
+          generated.reduce((sum, g) => sum + g.confidence, 0) /
+            generated.length
+        )
+      : 0;
+
+  console.log(pc.dim("\n────────────────────────────────────────"));
+  console.log(pc.green(`\n✓ Generated ${generated.length} fragment file(s)`));
+
+  if (skipped.length > 0) {
+    console.log(
+      pc.dim(`  Skipped ${skipped.length} (use --force to overwrite)`)
+    );
+  }
+  if (errors.length > 0) {
+    console.log(pc.yellow(`  ${errors.length} error(s)`));
+  }
+
+  console.log(pc.dim(`  Average confidence: ${avgConfidence}/100`));
+
+  const totalTodos = generated.reduce((sum, g) => sum + g.todoCount, 0);
+  if (totalTodos > 0) {
+    console.log(
+      pc.dim(`  Total TODOs: ${totalTodos}`) +
+        pc.dim(` — search for "TODO:" in generated files`)
+    );
+  }
+
+  console.log();
+
+  return {
+    success: errors.length === 0,
+    generated,
+    skipped,
+    errors,
+    averageConfidence: avgConfidence,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// JSDoc Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the JSDoc description from a component's exported declaration.
+ * Uses TypeScript AST — no program needed, just source file parsing.
+ */
+export async function extractComponentJSDoc(
+  filePath: string,
+  componentName?: string
+): Promise<string | null> {
+  const content = await readFile(filePath, "utf-8");
+  return extractComponentJSDocFromSource(content, filePath, componentName);
+}
+
+export function extractComponentJSDocFromSource(
+  source: string,
+  filePath: string,
+  componentName?: string
+): string | null {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.ESNext,
+    true,
+    filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+
+  const targetName =
+    componentName || basename(filePath).replace(/\.(tsx?|jsx?)$/, "");
+
+  let componentDoc: string | null = null;
+  let propsInterfaceDoc: string | null = null;
+
+  for (const statement of sourceFile.statements) {
+    // export function ComponentName(...)
+    if (
+      ts.isFunctionDeclaration(statement) &&
+      statement.name?.text === targetName &&
+      hasExportModifier(statement)
+    ) {
+      const doc = getLeadingJSDoc(statement, sourceFile);
+      if (doc) componentDoc = doc;
+    }
+
+    // export const ComponentName = ...
+    if (
+      ts.isVariableStatement(statement) &&
+      hasExportModifier(statement)
+    ) {
+      for (const decl of statement.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.name.text === targetName) {
+          const doc = getLeadingJSDoc(statement, sourceFile);
+          if (doc) componentDoc = doc;
+        }
+      }
+    }
+
+    // export default function ...
+    if (
+      ts.isFunctionDeclaration(statement) &&
+      hasDefaultExportModifier(statement)
+    ) {
+      const doc = getLeadingJSDoc(statement, sourceFile);
+      if (doc) componentDoc = doc;
+    }
+
+    // Fallback: JSDoc on the {Name}Props interface
+    if (
+      ts.isInterfaceDeclaration(statement) &&
+      (statement.name.text === `${targetName}Props` ||
+        statement.name.text === `${targetName}Properties`)
+    ) {
+      const doc = getLeadingJSDoc(statement, sourceFile);
+      if (doc) propsInterfaceDoc = doc;
+    }
+  }
+
+  // Prefer component-level JSDoc; fall back to props interface JSDoc
+  return componentDoc || propsInterfaceDoc;
+}
+
+function hasExportModifier(node: ts.Node): boolean {
+  const modifiers = ts.canHaveModifiers(node)
+    ? ts.getModifiers(node)
+    : undefined;
+  return modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+
+function hasDefaultExportModifier(node: ts.Node): boolean {
+  const modifiers = ts.canHaveModifiers(node)
+    ? ts.getModifiers(node)
+    : undefined;
+  if (!modifiers) return false;
+  return (
+    modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) &&
+    modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)
+  );
+}
+
+function getLeadingJSDoc(
+  node: ts.Node,
+  sourceFile: ts.SourceFile
+): string | null {
+  const fullText = sourceFile.getFullText();
+  const nodeStart = node.getFullStart();
+  const nodePos = node.getStart(sourceFile);
+  const leadingText = fullText.slice(nodeStart, nodePos);
+
+  const jsDocMatch = leadingText.match(/\/\*\*([\s\S]*?)\*\//);
+  if (!jsDocMatch) return null;
+
+  // Parse JSDoc content — extract description lines, skip tags
+  const lines = jsDocMatch[1].split("\n");
+  const descriptionLines: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.replace(/^\s*\*?\s?/, "").trim();
+    if (trimmed.startsWith("@")) break; // Stop at first tag
+    if (trimmed) descriptionLines.push(trimmed);
+  }
+
+  return descriptionLines.length > 0
+    ? descriptionLines.join(" ")
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// Compound Component Detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect compound component patterns (Object.assign) in a source file.
+ * Returns the names of sub-components found.
+ */
+export async function detectCompoundComponents(
+  filePath: string
+): Promise<string[]> {
+  const content = await readFile(filePath, "utf-8");
+  return detectCompoundComponentsFromSource(content, filePath);
+}
+
+export function detectCompoundComponentsFromSource(
+  source: string,
+  filePath: string
+): string[] {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.ESNext,
+    true,
+    filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+
+  const subComponents: string[] = [];
+
+  function visit(node: ts.Node) {
+    // Look for Object.assign(Root, { Sub1, Sub2 }) or Object.assign(Root, { Sub1: SubComponent })
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      ts.isIdentifier(node.expression.expression) &&
+      node.expression.expression.text === "Object" &&
+      node.expression.name.text === "assign" &&
+      node.arguments.length >= 2
+    ) {
+      const secondArg = node.arguments[1];
+      if (ts.isObjectLiteralExpression(secondArg)) {
+        for (const prop of secondArg.properties) {
+          if (ts.isShorthandPropertyAssignment(prop)) {
+            subComponents.push(prop.name.text);
+          } else if (
+            ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name)
+          ) {
+            subComponents.push(prop.name.text);
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  ts.forEachChild(sourceFile, visit);
+  return subComponents;
+}
+
+// ---------------------------------------------------------------------------
+// Story Variant Extraction (lightweight, from generate.ts patterns)
+// ---------------------------------------------------------------------------
+
+async function extractStoryVariantsFromFile(
+  storyPath: string
+): Promise<StoryVariant[]> {
+  const content = await readFile(storyPath, "utf-8");
+  const variants: StoryVariant[] = [];
+
+  const exportMatches = content.matchAll(
+    /export\s+const\s+([A-Z][a-zA-Z0-9]*)\s*[=:]/g
+  );
+
+  for (const match of exportMatches) {
+    const name = match[1];
+    if (name === "default" || name.endsWith("Args") || name.endsWith("Meta")) {
+      continue;
+    }
+
+    const args = extractStoryArgs(content, name);
+    variants.push({ name, args });
+  }
+
+  return variants;
+}
+
+function extractStoryArgs(
+  content: string,
+  storyName: string
+): Record<string, unknown> {
+  const storyPattern = new RegExp(
+    `export\\s+const\\s+${storyName}[^=]*=\\s*\\{([\\s\\S]*?)\\n\\};`
+  );
+  const storyMatch = content.match(storyPattern);
+  if (!storyMatch) return {};
+
+  const storyBody = storyMatch[1];
+  const argsStart = storyBody.indexOf("args:");
+  if (argsStart === -1) return {};
+
+  const braceStart = storyBody.indexOf("{", argsStart);
+  if (braceStart === -1) return {};
+
+  let depth = 0;
+  let braceEnd = -1;
+  for (let i = braceStart; i < storyBody.length; i++) {
+    if (storyBody[i] === "{") depth++;
+    else if (storyBody[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        braceEnd = i;
+        break;
+      }
+    }
+  }
+  if (braceEnd === -1) return {};
+
+  const argsBlock = storyBody.slice(braceStart + 1, braceEnd).trim();
+  return parseArgsBlock(argsBlock);
+}
+
+function parseArgsBlock(argsBlock: string): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  const pairPattern =
+    /(\w+)\s*:\s*(?:['"]([^'"]*?)['"]|(true|false)|(\d+(?:\.\d+)?))/g;
+  let pairMatch: RegExpExecArray | null;
+
+  while ((pairMatch = pairPattern.exec(argsBlock)) !== null) {
+    const key = pairMatch[1];
+    if (pairMatch[2] !== undefined) {
+      args[key] = pairMatch[2];
+    } else if (pairMatch[3] !== undefined) {
+      args[key] = pairMatch[3] === "true";
+    } else if (pairMatch[4] !== undefined) {
+      args[key] = Number(pairMatch[4]);
+    }
+  }
+
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Confidence Scoring
+// ---------------------------------------------------------------------------
+
+export function calculateFieldConfidence(data: ComponentData): FieldConfidence {
+  let score = 0;
+  const todoFields: string[] = [];
+
+  // Props extracted: +30
+  const hasProps =
+    data.props?.success && data.props.props.length > 0;
+  if (hasProps) {
+    score += 30;
+  }
+
+  // JSDoc description found: +15
+  if (data.jsDoc) {
+    score += 15;
+  } else {
+    todoFields.push("meta.description");
+  }
+
+  // Category inferred from path/name (not fallback): +10
+  const category = inferCategory(
+    data.component.name,
+    data.props?.success ? data.props.props : []
+  );
+  if (category !== "Components") {
+    score += 10;
+  } else {
+    todoFields.push("meta.category");
+  }
+
+  // Story variants found: +25
+  if (data.storyVariants.length > 0) {
+    score += 25;
+  }
+
+  // All prop types resolved (no "custom"): +10
+  if (hasProps) {
+    const allResolved = data.props!.props.every(
+      (p) => p.propType.type !== "custom"
+    );
+    if (allResolved) {
+      score += 10;
+    }
+  }
+
+  // Compound component detected: +5
+  if (data.compoundChildren.length > 0) {
+    score += 5;
+  }
+
+  // Has default values: +5
+  if (hasProps) {
+    const hasDefaults = data.props!.props.some(
+      (p) => p.defaultValue !== undefined
+    );
+    if (hasDefaults) {
+      score += 5;
+    }
+  }
+
+  // usage.when and usage.whenNot always get TODOs (human knowledge needed)
+  todoFields.push("usage.when");
+  todoFields.push("usage.whenNot");
+
+  return { score: Math.min(score, 100), todoFields };
+}
+
+// ---------------------------------------------------------------------------
+// Category / Status / Description inference (adapted from generate.ts + scan.ts)
+// ---------------------------------------------------------------------------
+
+const CATEGORY_PATTERNS: Record<string, string[]> = {
+  Actions: ["button", "action", "cta", "fab", "floatingaction"],
+  Forms: [
+    "form", "input", "select", "checkbox", "radio", "textarea", "field",
+    "textfield", "datepicker", "switch", "slider", "segmented",
+  ],
+  Layout: [
+    "layout", "container", "grid", "flex", "stack", "box", "divider", "spacer",
+    "sidebar",
+  ],
+  Navigation: [
+    "nav", "menu", "breadcrumb", "tab", "link", "pagination", "stepper",
+    "topbar",
+  ],
+  Feedback: [
+    "alert", "toast", "notification", "message", "badge", "indicator",
+    "progress", "spinner", "loading", "loader", "lozenge", "chip",
+  ],
+  "Data Display": [
+    "table", "list", "card", "avatar", "stat", "timeline", "tree", "datalist",
+    "datacard",
+  ],
+  Overlays: [
+    "modal", "dialog", "drawer", "popover", "tooltip", "dropdown",
+    "slidepanel",
+  ],
+  Typography: ["text", "heading", "title", "label", "paragraph"],
+  Media: ["image", "video", "icon", "carousel"],
+};
+
+function inferCategory(
+  componentName: string,
+  props: ExtractedProp[]
+): string {
+  const lower = componentName.toLowerCase();
+
+  for (const [category, patterns] of Object.entries(CATEGORY_PATTERNS)) {
+    for (const pattern of patterns) {
+      if (lower.includes(pattern)) {
+        return category;
+      }
+    }
+  }
+
+  // Prop-based fallbacks
+  const propNames = new Set(props.map((p) => p.name));
+  if (propNames.has("onClick") || propNames.has("onPress")) return "Actions";
+  if (propNames.has("value") || propNames.has("defaultValue")) return "Forms";
+  if (propNames.has("children")) return "Layout";
+
+  return "Components";
+}
+
+function inferStatus(
+  filePath: string
+): "draft" | "experimental" | "beta" | "stable" | "deprecated" {
+  const lowerPath = filePath.toLowerCase();
+  if (lowerPath.includes("/experimental/") || lowerPath.includes("/labs/"))
+    return "experimental";
+  if (lowerPath.includes("/beta/")) return "beta";
+  if (lowerPath.includes("/deprecated/") || lowerPath.includes("/legacy/"))
+    return "deprecated";
+  if (lowerPath.includes("/draft/") || lowerPath.includes("/wip/"))
+    return "draft";
+  return "stable";
+}
+
+function inferDescription(
+  componentName: string,
+  props: ExtractedProp[]
+): string {
+  const words = componentName
+    .replace(/([A-Z])/g, " $1")
+    .trim()
+    .toLowerCase();
+
+  const propNames = new Set(props.map((p) => p.name));
+  const hasOnClick =
+    propNames.has("onClick") || propNames.has("onPress");
+  const hasValue =
+    propNames.has("value") || propNames.has("defaultValue");
+  const hasChildren = propNames.has("children");
+
+  if (hasOnClick && !hasValue)
+    return `Interactive ${words} element for triggering actions`;
+  if (hasValue) return `Form ${words} for user input`;
+  if (hasChildren) return `Container ${words} for grouping content`;
+  return `${words.charAt(0).toUpperCase() + words.slice(1)} component`;
+}
+
+function inferAccessibility(props: ExtractedProp[]): {
+  role?: string;
+  requirements?: string[];
+} {
+  const propNames = new Set(props.map((p) => p.name));
+  const accessibility: { role?: string; requirements?: string[] } = {};
+
+  const hasOnClick =
+    propNames.has("onClick") || propNames.has("onPress");
+  const hasAriaLabel =
+    propNames.has("ariaLabel") || propNames.has("aria-label");
+  const hasDisabled = propNames.has("disabled");
+  const hasHref = propNames.has("href");
+
+  if (hasOnClick && !hasHref) accessibility.role = "button";
+  else if (hasHref) accessibility.role = "link";
+
+  const requirements: string[] = [];
+  if (hasOnClick && !hasAriaLabel)
+    requirements.push("Should have visible text or aria-label");
+  if (hasDisabled)
+    requirements.push(
+      "Disabled state should be conveyed to assistive technology"
+    );
+  if (requirements.length > 0) accessibility.requirements = requirements;
+
+  return accessibility;
+}
+
+// ---------------------------------------------------------------------------
+// Import path computation
+// ---------------------------------------------------------------------------
+
+function computeImportPath(
+  fragmentDir: string,
+  sourcePath: string,
+  componentBaseName: string
+): string {
+  const sourceDir = dirname(sourcePath);
+
+  // Colocated: fragment sits next to the source file
+  if (fragmentDir === sourceDir) {
+    // If source is index.tsx, import from '.'
+    if (componentBaseName === "index") {
+      return ".";
+    }
+    return `./${componentBaseName}`;
+  }
+
+  // Different directory: compute relative path
+  let rel = relative(fragmentDir, sourceDir);
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  if (componentBaseName !== "index") {
+    rel = `${rel}/${componentBaseName}`;
+  }
+  return rel;
+}
+
+// ---------------------------------------------------------------------------
+// Fragment file generation with TODO markers
+// ---------------------------------------------------------------------------
+
+function escapeQuotes(str: string): string {
+  return str.replace(/'/g, "\\'");
+}
+
+function generateFragmentWithTodos(
+  componentName: string,
+  importPath: string,
+  data: ComponentData,
+  confidence: FieldConfidence
+): string {
+  const props = data.props?.success ? data.props.props : [];
+  const isDefaultExport = data.props?.success
+    ? !data.props.propsTypeName // heuristic: if no explicit props type, might be default export
+    : false;
+  // For scan-generated files we always use named import
+  const description = data.jsDoc || inferDescription(componentName, props);
+  const descriptionTodo = data.jsDoc ? "" : " // TODO: Review description";
+  const category = inferCategory(componentName, props);
+  const categoryTodo = category === "Components" ? " // TODO: Set correct category" : "";
+  const status = inferStatus(data.component.sourcePath);
+  const accessibility = inferAccessibility(props);
+
+  // Build props block
+  const propsBlock = buildPropsBlock(props);
+
+  // Build accessibility block
+  const accessibilityBlock = buildAccessibilityBlock(accessibility);
+
+  // Build variants
+  const variantsBlock = buildVariantsBlock(
+    componentName,
+    data.storyVariants
+  );
+
+  // Build compound children comment
+  const compoundComment =
+    data.compoundChildren.length > 0
+      ? `\n  // Compound sub-components detected: ${data.compoundChildren.join(", ")}`
+      : "";
+
+  return `// Auto-generated by fragments init --scan | Confidence: ${confidence.score}/100
+// ${confidence.todoFields.length} TODO(s) — search for "TODO:" and fill in human knowledge
+import React from 'react';
+import { defineFragment } from '@fragments-sdk/core';
+import { ${componentName} } from '${importPath}';
+
+export default defineFragment({
+  component: ${componentName},
+${compoundComment}
+  meta: {
+    name: '${escapeQuotes(componentName)}',
+    description: '${escapeQuotes(description)}',${descriptionTodo}
+    category: '${escapeQuotes(category)}',${categoryTodo}
+    status: '${status}',
+  },
+
+  usage: {
+    when: [
+      // TODO: Describe when to use ${componentName}
+    ],
+    whenNot: [
+      // TODO: Describe when NOT to use ${componentName}
+    ],
+  },
+
+  props: ${propsBlock},${accessibilityBlock}
+
+  variants: [
+${variantsBlock}
+  ],
+});
+`;
+}
+
+function buildPropsBlock(props: ExtractedProp[]): string {
+  if (props.length === 0) return "{}";
+
+  const lines = props.map((prop) => {
+    const type = prop.propType.type;
+    const parts: string[] = [`      type: '${type}'`];
+
+    if (prop.description) {
+      parts.push(
+        `      description: '${escapeQuotes(prop.description.replace(/\n/g, " "))}'`
+      );
+    }
+
+    parts.push(`      required: ${prop.required}`);
+
+    if (prop.defaultValue !== undefined) {
+      parts.push(`      default: ${JSON.stringify(prop.defaultValue)}`);
+    }
+
+    if (prop.enumValues && prop.enumValues.length > 0) {
+      parts.push(`      values: ${JSON.stringify(prop.enumValues)}`);
+    }
+
+    const todoComment =
+      type === "custom" ? " // TODO: Review type" : "";
+
+    return `    ${prop.name}: {\n${parts.join(",\n")},\n    },${todoComment}`;
+  });
+
+  return `{\n${lines.join("\n")}\n  }`;
+}
+
+function buildAccessibilityBlock(accessibility: {
+  role?: string;
+  requirements?: string[];
+}): string {
+  if (
+    !accessibility.role &&
+    (!accessibility.requirements || accessibility.requirements.length === 0)
+  ) {
+    return "";
+  }
+
+  const parts: string[] = [];
+  if (accessibility.role) {
+    parts.push(`    role: '${accessibility.role}'`);
+  }
+  if (accessibility.requirements && accessibility.requirements.length > 0) {
+    const reqs = accessibility.requirements
+      .map((r) => `'${escapeQuotes(r)}'`)
+      .join(", ");
+    parts.push(`    requirements: [${reqs}]`);
+  }
+
+  return `\n\n  accessibility: {\n${parts.join(",\n")},\n  },`;
+}
+
+function buildVariantsBlock(
+  componentName: string,
+  storyVariants: StoryVariant[]
+): string {
+  const entries: string[] = [];
+
+  // Always include a Default variant
+  const hasDefault = storyVariants.some((v) => v.name === "Default");
+  if (!hasDefault) {
+    entries.push(formatVariantEntry(componentName, "Default", `Default ${componentName}`, {}));
+  }
+
+  for (const variant of storyVariants) {
+    const description = variant.name.replace(/([A-Z])/g, " $1").trim();
+    entries.push(
+      formatVariantEntry(
+        componentName,
+        variant.name,
+        `${description} ${componentName}`,
+        variant.args
+      )
+    );
+  }
+
+  return entries.join("\n");
+}
+
+function formatVariantEntry(
+  componentName: string,
+  name: string,
+  description: string,
+  args: Record<string, unknown>
+): string {
+  const jsxCode = buildJsxString(componentName, args);
+  return `    {
+      name: '${escapeQuotes(name)}',
+      description: '${escapeQuotes(description)}',
+      code: \`${jsxCode}\`,
+      render: () => ${jsxCode},
+    },`;
+}
+
+function buildJsxString(
+  componentName: string,
+  args: Record<string, unknown>
+): string {
+  const { children, ...restArgs } = args;
+  const propParts: string[] = [];
+
+  for (const [key, value] of Object.entries(restArgs)) {
+    if (typeof value === "string") {
+      propParts.push(`${key}="${escapeQuotes(value)}"`);
+    } else if (typeof value === "boolean") {
+      propParts.push(value ? key : `${key}={false}`);
+    } else if (typeof value === "number") {
+      propParts.push(`${key}={${value}}`);
+    }
+  }
+
+  const propsStr = propParts.length > 0 ? " " + propParts.join(" ") : "";
+
+  if (typeof children === "string") {
+    return `<${componentName}${propsStr}>${children}</${componentName}>`;
+  }
+
+  return `<${componentName}${propsStr} />`;
+}