@fragments-sdk/cli 0.14.3 → 0.15.0

package/dist/{scan-generate-TFZVL3BT.js → scan-generate-TWRHNU5M.js}

@@ -1,22 +1,145 @@
 import { createRequire as __banner_createRequire } from 'module'; const require = __banner_createRequire(import.meta.url);
 import {
   createComponentExtractor
-} from "./chunk-EYXVAMEX.js";
-import "./chunk-55KERLWL.js";
+} from "./chunk-MN3TJ3D5.js";
 import {
   discoverAllComponents
-} from "./chunk-ZKTFKHWN.js";
+} from "./chunk-65WSVDV5.js";
 import "./chunk-D2CDBRNU.js";
 import {
   BRAND
-} from "./chunk-I34BC3CU.js";
+} from "./chunk-32LIWN2P.js";
 import "./chunk-Z7EY4VHE.js";
 
 // src/commands/scan-generate.ts
 import { readFile, writeFile, access, mkdir } from "fs/promises";
 import { resolve, basename, dirname, relative, join } from "path";
+import { execSync } from "child_process";
 import * as ts from "typescript";
 import pc from "picocolors";
+async function findNearestAncestor(scanPath, targetFile) {
+  let dir = resolve(scanPath);
+  for (let i = 0; i < 20; i++) {
+    try {
+      await access(join(dir, targetFile));
+      return dir;
+    } catch {
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return null;
+}
+async function findNearestPackageJsonDir(scanPath) {
+  return findNearestAncestor(scanPath, "package.json");
+}
+async function detectPackageManagerForProject(projectDir) {
+  let dir = resolve(projectDir);
+  for (let i = 0; i < 20; i++) {
+    for (const [fileName, manager] of [
+      ["pnpm-lock.yaml", "pnpm"],
+      ["pnpm-workspace.yaml", "pnpm"],
+      ["yarn.lock", "yarn"],
+      ["package-lock.json", "npm"]
+    ]) {
+      try {
+        await access(join(dir, fileName));
+        return { manager, lockfileDir: dir };
+      } catch {
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { manager: "npm", lockfileDir: null };
+}
+function resolveCoreInstallCommand(manager) {
+  switch (manager) {
+    case "pnpm":
+      return "pnpm add -D @fragments-sdk/core";
+    case "yarn":
+      return "yarn add -D @fragments-sdk/core";
+    default:
+      return "npm install -D @fragments-sdk/core";
+  }
+}
+async function ensureCoreDependency(scanPath) {
+  const projectDir = await findNearestPackageJsonDir(scanPath);
+  if (!projectDir) return;
+  const pkgJsonPath = join(projectDir, "package.json");
+  try {
+    const pkgRaw = await readFile(pkgJsonPath, "utf-8");
+    const pkg = JSON.parse(pkgRaw);
+    const deps = pkg.dependencies || {};
+    const devDeps = pkg.devDependencies || {};
+    if (deps["@fragments-sdk/core"] || devDeps["@fragments-sdk/core"]) {
+      console.log(pc.dim("  \xB7 @fragments-sdk/core already installed"));
+      return;
+    }
+    const { manager } = await detectPackageManagerForProject(projectDir);
+    const cmd = resolveCoreInstallCommand(manager);
+    execSync(cmd, { cwd: projectDir, stdio: "ignore" });
+    console.log(pc.green("  \u2713 Installed @fragments-sdk/core"));
+  } catch (e) {
+    console.log(
+      pc.yellow(
+        `  \u26A0 Could not auto-install @fragments-sdk/core: ${e instanceof Error ? e.message : String(e)}`
+      )
+    );
+  }
+}
+async function excludeFragmentsFromTsconfig(scanPath) {
+  const projectDir = await findNearestPackageJsonDir(scanPath);
+  if (!projectDir) return;
+  let tsconfigPath = null;
+  let tsconfigName = "";
+  for (const name of ["tsconfig.app.json", "tsconfig.json"]) {
+    const candidate = join(projectDir, name);
+    try {
+      await access(candidate);
+      tsconfigPath = candidate;
+      tsconfigName = name;
+      break;
+    } catch {
+    }
+  }
+  if (!tsconfigPath) return;
+  try {
+    const raw = await readFile(tsconfigPath, "utf-8");
+    const parsed = ts.parseConfigFileTextToJson(tsconfigPath, raw);
+    if (parsed.error || !parsed.config) {
+      throw new Error(parsed.error?.messageText?.toString() ?? "Unable to parse tsconfig");
+    }
+    const config = parsed.config;
+    const exclude = Array.isArray(config.exclude) ? [...config.exclude] : [];
+    const ext = BRAND.fileExtension;
+    const alreadyExcluded = exclude.some(
+      (pattern) => pattern.includes(`*${ext}`) || pattern.includes("*.fragment.*") || pattern.includes("*.contract.*")
+    );
+    if (alreadyExcluded) {
+      console.log(
+        pc.dim(`  \xB7 ${ext} already excluded in ${tsconfigName}`)
+      );
+      return;
+    }
+    exclude.push(`**/*${ext}`);
+    config.exclude = exclude;
+    const updated = `${JSON.stringify(config, null, 2)}
+`;
+    await writeFile(tsconfigPath, updated, "utf-8");
+    console.log(
+      pc.green(`  \u2713 Added ${ext} exclusion to ${tsconfigName}`)
+    );
+  } catch (e) {
+    console.log(
+      pc.yellow(
+        `  \u26A0 Could not update ${tsconfigName}: ${e instanceof Error ? e.message : String(e)}`
+      )
+    );
+  }
+}
 async function scanGenerate(options) {
   const scanPath = resolve(options.scanPath);
   const generated = [];
@@ -168,13 +291,26 @@ Phase ${options.enrich ? "4" : "3"}: Generating fragment files...`));
         comp.sourcePath,
         componentBaseName
       );
-      const content = generateFragmentWithTodos(
-        comp.name,
-        importPath,
-        data,
-        confidence,
-        enrichment
-      );
+      let content;
+      if (fragmentPath.endsWith(".contract.json")) {
+        content = generateContractJsonFromScan(
+          comp.name,
+          componentBaseName,
+          data,
+          confidence,
+          comp.sourcePath,
+          scanPath,
+          enrichment
+        );
+      } else {
+        content = generateFragmentWithTodos(
+          comp.name,
+          importPath,
+          data,
+          confidence,
+          enrichment
+        );
+      }
       await writeFile(fragmentPath, content, "utf-8");
       const relPath = relative(process.cwd(), fragmentPath);
       generated.push({
@@ -196,6 +332,10 @@ Phase ${options.enrich ? "4" : "3"}: Generating fragment files...`));
       console.log(pc.red(`  \u2717 ${comp.name}: ${e instanceof Error ? e.message : String(e)}`));
     }
   }
+  if (generated.length > 0) {
+    await ensureCoreDependency(scanPath);
+    await excludeFragmentsFromTsconfig(scanPath);
+  }
   const avgConfidence = generated.length > 0 ? Math.round(
     generated.reduce((sum, g) => sum + g.confidence, 0) / generated.length
   ) : 0;
@@ -450,12 +590,12 @@ Rules:
 }
 function buildEnrichmentUserPrompt(name, data) {
   const props = data.meta?.props ?? {};
-  const localProps = Object.entries(props).filter(([_, p]) => p.source === "local");
+  const fragmentProps = getFragmentPropEntries(props);
   const composition = data.meta?.composition ?? null;
   const description = data.meta?.description || "";
   const category = inferCategoryFromMeta(
     name,
-    Object.fromEntries(localProps)
+    Object.fromEntries(fragmentProps)
   );
   const lines = [
     `Component: ${name}`,
@@ -464,10 +604,10 @@ function buildEnrichmentUserPrompt(name, data) {
   if (description) {
     lines.push(`Description: ${description}`);
   }
-  if (localProps.length > 0) {
+  if (fragmentProps.length > 0) {
     lines.push("");
     lines.push("Props:");
-    for (const [propName, prop] of localProps) {
+    for (const [propName, prop] of fragmentProps) {
       let propLine = `  - ${propName}: ${prop.typeKind}`;
       if (prop.values && prop.values.length > 0) {
         propLine += ` (${prop.values.join(" | ")})`;
@@ -606,8 +746,8 @@ function calculateFieldConfidence(data, enrichment) {
   let score = 0;
   const todoFields = [];
   const props = data.meta?.props ?? {};
-  const localEntries = Object.values(props).filter((p) => p.source === "local");
-  const hasProps = localEntries.length > 0;
+  const fragmentPropEntries = getFragmentPropEntries(props);
+  const hasProps = fragmentPropEntries.length > 0;
   if (hasProps) {
     score += 30;
   }
@@ -616,10 +756,8 @@ function calculateFieldConfidence(data, enrichment) {
   } else {
     todoFields.push("meta.description");
   }
-  const localProps = Object.fromEntries(
-    Object.entries(props).filter(([_, p]) => p.source === "local")
-  );
-  const category = inferCategoryFromMeta(data.component.name, localProps);
+  const fragmentProps = Object.fromEntries(fragmentPropEntries);
+  const category = inferCategoryFromMeta(data.component.name, fragmentProps);
   if (category !== "Components") {
     score += 10;
   } else {
@@ -629,7 +767,7 @@ function calculateFieldConfidence(data, enrichment) {
     score += 25;
   }
   if (hasProps) {
-    const allResolved = localEntries.every((p) => p.typeKind !== "custom");
+    const allResolved = fragmentPropEntries.every(([_, p]) => p.typeKind !== "custom");
     if (allResolved) {
       score += 10;
     }
@@ -638,7 +776,7 @@ function calculateFieldConfidence(data, enrichment) {
     score += 10;
   }
   if (hasProps) {
-    const hasDefaults = localEntries.some((p) => p.default !== void 0);
+    const hasDefaults = fragmentPropEntries.some(([_, p]) => p.default !== void 0);
     if (hasDefaults) {
       score += 5;
     }
@@ -792,13 +930,55 @@ function inferAccessibilityFromMeta(props) {
   if (requirements.length > 0) accessibility.requirements = requirements;
   return accessibility;
 }
-function buildContractBlock(componentName, props, composition, accessibility) {
-  const localEntries = Object.entries(props).filter(([_, p]) => p.source === "local");
-  if (localEntries.length === 0 && !composition && !accessibility.requirements?.length) {
+var INHERITED_PROP_PRIORITY = [
+  "htmlFor",
+  "type",
+  "value",
+  "defaultValue",
+  "checked",
+  "defaultChecked",
+  "disabled",
+  "required",
+  "placeholder",
+  "name",
+  "id",
+  "form",
+  "accept",
+  "multiple",
+  "min",
+  "max",
+  "step",
+  "pattern",
+  "role",
+  "children"
+];
+function getFragmentPropEntries(props) {
+  const entries = Object.entries(props);
+  const localEntries = entries.filter(([_, prop]) => prop.source === "local");
+  if (localEntries.length > 0) {
+    return localEntries;
+  }
+  const prioritized = new Set(INHERITED_PROP_PRIORITY);
+  const inheritedEntries = entries.filter(([name, prop]) => {
+    if (prop.source !== "inherited") return false;
+    if (name === "key" || name === "ref" || name === "className" || name === "style") return false;
+    if (name.startsWith("on")) return false;
+    if (name.startsWith("aria-") || name.startsWith("data-")) return false;
+    return prioritized.has(name);
+  }).sort(([nameA], [nameB]) => {
+    const rankA = INHERITED_PROP_PRIORITY.indexOf(nameA);
+    const rankB = INHERITED_PROP_PRIORITY.indexOf(nameB);
+    return rankA - rankB;
+  });
+  return inheritedEntries.slice(0, 8);
+}
+function buildContractBlock(componentName, props, composition, accessibility, compoundPartRefs = []) {
+  const relevantEntries = getFragmentPropEntries(props);
+  if (relevantEntries.length === 0 && !composition && !accessibility.requirements?.length) {
     return null;
   }
   const contract = { propsSummary: [] };
-  for (const [name, prop] of localEntries) {
+  for (const [name, prop] of relevantEntries) {
     let summary = name + ": ";
     if (prop.typeKind === "enum" && prop.values && prop.values.length > 0) {
       summary += prop.values.join(" | ");
@@ -825,7 +1005,8 @@ function buildContractBlock(componentName, props, composition, accessibility) {
     contract.compoundChildren = children;
   }
   if (composition && composition.parts.length > 0) {
-    const innerLines = composition.parts.map((part) => `  <${componentName}.${part.name}>...</${componentName}.${part.name}>`).join("\n");
+    const resolvedParts = compoundPartRefs.length > 0 ? compoundPartRefs : composition.parts.map((part) => ({ partName: part.name, tagName: `${componentName}.${part.name}` }));
+    const innerLines = resolvedParts.map((part) => `  <${part.tagName}>...</${part.tagName}>`).join("\n");
     contract.canonicalUsage = [
       `<${componentName}>
 ${innerLines}
@@ -909,20 +1090,53 @@ function computeImportPath(fragmentDir, sourcePath, componentBaseName) {
 function escapeQuotes(str) {
   return str.replace(/'/g, "\\'");
 }
+function resolveCompoundPartReferences(componentName, composition, exportNames) {
+  if (!composition || composition.parts.length === 0) return [];
+  return composition.parts.map((part) => {
+    const directExportName = `${componentName}${part.name}`;
+    if (exportNames.includes(directExportName)) {
+      return {
+        partName: part.name,
+        tagName: directExportName,
+        importName: directExportName
+      };
+    }
+    return {
+      partName: part.name,
+      tagName: `${componentName}.${part.name}`
+    };
+  });
+}
 function generateFragmentWithTodos(componentName, importPath, data, confidence, enrichment) {
   const props = data.meta?.props ?? {};
   const localProps = Object.fromEntries(
     Object.entries(props).filter(([_, p]) => p.source === "local")
   );
+  const fragmentProps = Object.fromEntries(getFragmentPropEntries(props));
+  const inferenceProps = Object.keys(localProps).length > 0 ? localProps : fragmentProps;
   const composition = data.meta?.composition ?? null;
-  const description = data.meta?.description || inferDescriptionFromMeta(componentName, localProps);
+  const description = data.meta?.description || inferDescriptionFromMeta(componentName, inferenceProps);
   const descriptionTodo = data.meta?.description ? "" : " // TODO: Review description";
-  const category = inferCategoryFromMeta(componentName, localProps);
+  const category = inferCategoryFromMeta(componentName, inferenceProps);
   const categoryTodo = category === "Components" ? " // TODO: Set correct category" : "";
   const status = inferStatus(data.component.sourcePath);
-  const accessibility = inferAccessibilityFromMeta(localProps);
+  const accessibility = inferAccessibilityFromMeta(inferenceProps);
+  const exportNames = data.meta?.exports ?? [];
+  const compoundPartRefs = resolveCompoundPartReferences(componentName, composition, exportNames);
+  const importNames = Array.from(
+    /* @__PURE__ */ new Set([
+      componentName,
+      ...compoundPartRefs.flatMap((part) => part.importName ? [part.importName] : [])
+    ])
+  );
   const propsBlock = buildPropsBlockFromMeta(props);
-  const contract = buildContractBlock(componentName, props, composition, accessibility);
+  const contract = buildContractBlock(
+    componentName,
+    props,
+    composition,
+    accessibility,
+    compoundPartRefs
+  );
   if (contract && enrichment) {
     if (enrichment.a11yRules.length > 0) {
       contract.a11yRules = enrichment.a11yRules;
@@ -950,17 +1164,17 @@ function generateFragmentWithTodos(componentName, importPath, data, confidence,
   const variantsBlock = buildVariantsBlock(
     componentName,
     data.storyVariants,
-    composition
+    composition,
+    compoundPartRefs
   );
-  const aiBlock = buildAIBlock(composition);
+  const aiBlock = buildAIBlock(composition, compoundPartRefs);
   const provenanceBlock = buildProvenanceBlock(confidence, props);
   const compoundComment = composition && composition.parts.length > 0 ? `
 // Compound sub-components detected: ${composition.parts.map((p) => p.name).join(", ")}` : "";
   return `// Auto-generated by fragments init --scan | Confidence: ${confidence.score}/100
 // ${confidence.todoFields.length} TODO(s) \u2014 search for "TODO:" and fill in human knowledge${compoundComment}
-import React from 'react';
 import { defineFragment } from '@fragments-sdk/core';
-import { ${componentName} } from '${importPath}';
+import { ${importNames.join(", ")} } from '${importPath}';
 
 export default defineFragment({
   component: ${componentName},
@@ -983,7 +1197,7 @@ ${provenanceBlock}});
 `;
 }
 function buildPropsBlockFromMeta(props) {
-  const entries = Object.entries(props).filter(([_, p]) => p.source === "local");
+  const entries = getFragmentPropEntries(props);
   if (entries.length === 0) return "{}";
   const lines = entries.map(([name, prop]) => {
     const type = prop.typeKind;
@@ -1009,12 +1223,12 @@ ${parts.join(",\n")},
 ${lines.join("\n")}
   }`;
 }
-function buildVariantsBlock(componentName, storyVariants, composition) {
+function buildVariantsBlock(componentName, storyVariants, composition, compoundPartRefs = []) {
   const entries = [];
   const hasDefault = storyVariants.some((v) => v.name === "Default");
   if (!hasDefault) {
     if (composition && composition.pattern === "compound" && composition.parts.length > 0) {
-      entries.push(formatCompoundVariantEntry(componentName, composition));
+      entries.push(formatCompoundVariantEntry(componentName, composition, compoundPartRefs));
     } else {
       entries.push(formatVariantEntry(componentName, "Default", `Default ${componentName}`, {}));
     }
@@ -1041,9 +1255,9 @@ function formatVariantEntry(componentName, name, description, args) {
       render: () => ${jsxCode},
     },`;
 }
-function formatCompoundVariantEntry(componentName, composition) {
-  const parts = composition.parts;
-  const innerJsx = parts.map((part) => `    <${componentName}.${part.name}>...</${componentName}.${part.name}>`).join("\n");
+function formatCompoundVariantEntry(componentName, composition, compoundPartRefs = []) {
+  const resolvedParts = compoundPartRefs.length > 0 ? compoundPartRefs : composition.parts.map((part) => ({ partName: part.name, tagName: `${componentName}.${part.name}` }));
+  const innerJsx = resolvedParts.map((part) => `    <${part.tagName}>...</${part.tagName}>`).join("\n");
   const jsxCode = `<${componentName}>
 ${innerJsx}
   </${componentName}>`;
@@ -1056,12 +1270,16 @@ ${innerJsx}
       ),
     },`;
 }
-function buildAIBlock(composition) {
+function buildAIBlock(composition, compoundPartRefs = []) {
   if (!composition || composition.parts.length === 0) return "";
-  const subComponents = composition.parts.map((p) => `'${p.name}'`).join(", ");
+  const resolvedParts = compoundPartRefs.length > 0 ? compoundPartRefs : composition.parts.map((part) => ({
+    partName: part.name,
+    tagName: `Component.${part.name}`
+  }));
+  const subComponents = resolvedParts.map((part) => `'${part.importName ?? part.partName}'`).join(", ");
   const pattern = `
       <Component>
-${composition.parts.map((p) => `        <Component.${p.name}>...</Component.${p.name}>`).join("\n")}
+${resolvedParts.map((part) => `        <${part.tagName}>...</${part.tagName}>`).join("\n")}
       </Component>`;
   return `
 
@@ -1100,6 +1318,73 @@ function buildJsxString(componentName, args) {
   }
   return `<${componentName}${propsStr} />`;
 }
+function generateContractJsonFromScan(componentName, _baseName, data, confidence, sourcePath, scanPath, enrichment) {
+  const props = data.meta?.props ?? {};
+  const localProps = Object.fromEntries(
+    Object.entries(props).filter(([, p]) => p.source === "local")
+  );
+  const effectiveProps = Object.keys(localProps).length > 0 ? localProps : props;
+  const composition = data.meta?.composition ?? null;
+  const description = data.meta?.description || `${componentName} component`;
+  const category = inferCategoryFromMeta(componentName, effectiveProps);
+  const propsSchema = {};
+  for (const [name, prop] of Object.entries(effectiveProps)) {
+    propsSchema[name] = {
+      type: prop.typeKind,
+      description: prop.description ?? "",
+      ...prop.values?.length && { values: prop.values },
+      ...prop.default !== void 0 && { default: prop.default },
+      ...prop.required && { required: true }
+    };
+  }
+  const propsSummary = Object.entries(effectiveProps).map(([name, prop]) => {
+    let summary = `${name}: `;
+    if (prop.values?.length) {
+      summary += prop.values.join("|");
+    } else {
+      summary += prop.typeKind;
+    }
+    if (prop.default !== void 0) summary += ` (default: ${prop.default})`;
+    if (prop.required) summary += " (required)";
+    return summary;
+  });
+  let ai;
+  if (composition) {
+    ai = {
+      compositionPattern: composition.pattern,
+      subComponents: composition.parts.map((p) => p.name),
+      ...composition.required.length > 0 && { requiredChildren: composition.required }
+    };
+  }
+  const relativeSourcePath = relative(scanPath, sourcePath);
+  const usage = enrichment ? {
+    when: enrichment.when ?? [],
+    whenNot: enrichment.whenNot ?? [],
+    ...enrichment.guidelines?.length && { guidelines: enrichment.guidelines }
+  } : {
+    when: [],
+    whenNot: []
+  };
+  const contract = {
+    $schema: "https://usefragments.com/schemas/contract.v1.json",
+    name: componentName,
+    description,
+    category,
+    sourcePath: relativeSourcePath,
+    exportName: componentName,
+    propsSummary,
+    props: propsSchema,
+    usage,
+    ...ai && { ai },
+    provenance: {
+      source: "extracted",
+      verified: confidence.score >= 70,
+      frameworkSupport: "native",
+      extractedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+  return JSON.stringify(contract, null, 2) + "\n";
+}
 export {
   buildEnrichedUsageBlock,
   buildEnrichmentSystemPrompt,
@@ -1107,9 +1392,13 @@ export {
   calculateFieldConfidence,
   detectCompoundComponents,
   detectCompoundComponentsFromSource,
+  detectPackageManagerForProject,
+  ensureCoreDependency,
+  excludeFragmentsFromTsconfig,
   extractComponentJSDoc,
   extractComponentJSDocFromSource,
   parseEnrichmentResponse,
+  resolveCoreInstallCommand,
   scanGenerate
 };
-//# sourceMappingURL=scan-generate-TFZVL3BT.js.map
+//# sourceMappingURL=scan-generate-TWRHNU5M.js.map