@fragments-sdk/cli 0.8.1 → 0.9.1

package/src/core/storyFilters.ts

@@ -0,0 +1,253 @@
+/**
+ * Smart filtering for Storybook adapter.
+ *
+ * Two layers:
+ * 1. Per-file heuristics — checkStoryExclusion() checks title, tags, component name, etc.
+ * 2. Cross-file sub-component detection — detectSubComponentPaths() uses directory structure.
+ *
+ * All functions are pure (no I/O, no side effects) for easy testing.
+ */
+
+import type { StorybookFilterConfig } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ExclusionReason =
+  | 'deprecated'       // title contains "Deprecated"
+  | 'test-story'       // title ends /tests? OR file matches *.test.stories.*
+  | 'svg-icon'         // component name starts with Svg[A-Z]
+  | 'tag-excluded'     // meta.tags includes hidden/internal/no-fragment
+  | 'empty-variants'   // zero renderable story exports
+  | 'sub-component'    // directory-based: file in another component's folder
+  | 'config-excluded'; // user explicit exclude pattern
+
+export interface ExclusionResult {
+  excluded: boolean;
+  reason?: ExclusionReason;
+  detail?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Per-file heuristics
+// ---------------------------------------------------------------------------
+
+const EXCLUDED_TAGS = new Set(['hidden', 'internal', 'no-fragment']);
+
+const SVG_ICON_RE = /^Svg[A-Z]/;
+const TEST_TITLE_RE = /\/tests?$/i;
+const TEST_FILE_RE = /\.test\.stories\./;
+const DEPRECATED_TITLE_RE = /\bDeprecated\b/i;
+
+export interface CheckStoryExclusionOpts {
+  storybookTitle?: string;
+  componentName: string;
+  componentDisplayName?: string;
+  componentFunctionName?: string;
+  tags?: string[];
+  variantCount: number;
+  filePath: string;
+  config: StorybookFilterConfig;
+}
+
+/**
+ * Per-file exclusion check. Returns `{ excluded: true, reason, detail }` when
+ * the fragment should be filtered out, or `{ excluded: false }` when it should
+ * be kept.
+ *
+ * Config `include` trumps everything — if a name matches `include`, it is
+ * never excluded by heuristics.
+ */
+export function checkStoryExclusion(opts: CheckStoryExclusionOpts): ExclusionResult {
+  const { config } = opts;
+
+  // Force-included names bypass all heuristic filters
+  if (isForceIncluded(opts.componentName, config)) {
+    return { excluded: false };
+  }
+
+  // Config explicit exclude
+  if (isConfigExcluded(opts.componentName, config)) {
+    return {
+      excluded: true,
+      reason: 'config-excluded',
+      detail: `'${opts.componentName}' matches storybook.exclude pattern`,
+    };
+  }
+
+  // Deprecated
+  if (config.excludeDeprecated !== false && opts.storybookTitle && DEPRECATED_TITLE_RE.test(opts.storybookTitle)) {
+    return {
+      excluded: true,
+      reason: 'deprecated',
+      detail: `Title "${opts.storybookTitle}" contains "Deprecated"`,
+    };
+  }
+
+  // Test stories
+  if (config.excludeTests !== false) {
+    if (opts.storybookTitle && TEST_TITLE_RE.test(opts.storybookTitle)) {
+      return {
+        excluded: true,
+        reason: 'test-story',
+        detail: `Title "${opts.storybookTitle}" ends with /test(s)`,
+      };
+    }
+    if (TEST_FILE_RE.test(opts.filePath)) {
+      return {
+        excluded: true,
+        reason: 'test-story',
+        detail: `File path matches *.test.stories.*`,
+      };
+    }
+  }
+
+  // SVG icons
+  if (config.excludeSvgIcons !== false) {
+    const names = [opts.componentName, opts.componentDisplayName, opts.componentFunctionName].filter(Boolean) as string[];
+    for (const name of names) {
+      if (SVG_ICON_RE.test(name)) {
+        return {
+          excluded: true,
+          reason: 'svg-icon',
+          detail: `Component name "${name}" matches Svg[A-Z] pattern`,
+        };
+      }
+    }
+  }
+
+  // Excluded tags
+  if (opts.tags?.length) {
+    const hit = opts.tags.find(t => EXCLUDED_TAGS.has(t));
+    if (hit) {
+      return {
+        excluded: true,
+        reason: 'tag-excluded',
+        detail: `Tag "${hit}" is in the exclusion set`,
+      };
+    }
+  }
+
+  // Empty variants
+  if (opts.variantCount === 0) {
+    return {
+      excluded: true,
+      reason: 'empty-variants',
+      detail: 'Zero renderable story exports',
+    };
+  }
+
+  return { excluded: false };
+}
+
+// ---------------------------------------------------------------------------
+// Cross-file sub-component detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Given all story file relative paths, detect which ones are sub-components
+ * based on directory structure.
+ *
+ * Heuristic: within a directory, if one story file's base name matches the
+ * directory name, it is the "primary" component. All other story files in
+ * the same directory are considered sub-components.
+ *
+ * Example:
+ *   src/components/Form/Form.stories.tsx        → primary ("Form")
+ *   src/components/Form/Checkbox.stories.tsx     → sub-component of "Form"
+ *   src/components/Form/RadioGroup.stories.tsx   → sub-component of "Form"
+ *
+ * Returns a Map from relative path → parent component name.
+ * Paths NOT in the map are standalone components.
+ */
+export function detectSubComponentPaths(
+  storyFiles: Array<{ relativePath: string }>
+): Map<string, string> {
+  // Group story files by their parent directory
+  const byDir = new Map<string, Array<{ relativePath: string; baseName: string }>>();
+
+  for (const file of storyFiles) {
+    const parts = file.relativePath.split('/');
+    if (parts.length < 2) continue; // skip root-level files
+
+    const fileName = parts[parts.length - 1];
+    // Extract base name: "Form.stories.tsx" → "Form"
+    const baseMatch = fileName.match(/^([^.]+)\.stories\./);
+    if (!baseMatch) continue;
+
+    const dir = parts.slice(0, -1).join('/');
+    const baseName = baseMatch[1];
+
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir)!.push({ relativePath: file.relativePath, baseName });
+  }
+
+  const subComponentMap = new Map<string, string>();
+
+  for (const [dir, files] of byDir) {
+    if (files.length <= 1) continue; // single file in dir → always standalone
+
+    // Directory name is the last segment: "src/components/Form" → "Form"
+    const dirName = dir.split('/').pop()!;
+
+    // Find the primary: story whose base name matches the directory name
+    const primary = files.find(f => f.baseName === dirName);
+    if (!primary) continue; // no clear primary → keep all
+
+    // All others in this dir are sub-components
+    for (const file of files) {
+      if (file.relativePath === primary.relativePath) continue;
+      subComponentMap.set(file.relativePath, primary.baseName);
+    }
+  }
+
+  return subComponentMap;
+}
+
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a component name matches the `storybook.include` patterns.
+ * Include is a force-include that bypasses all heuristic filters.
+ */
+export function isForceIncluded(name: string, config: StorybookFilterConfig): boolean {
+  if (!config.include?.length) return false;
+  return config.include.some(pattern => matchesPattern(name, pattern));
+}
+
+/**
+ * Check if a component name matches the `storybook.exclude` patterns.
+ */
+export function isConfigExcluded(name: string, config: StorybookFilterConfig): boolean {
+  if (!config.exclude?.length) return false;
+  return config.exclude.some(pattern => matchesPattern(name, pattern));
+}
+
+/**
+ * Simple pattern matching: exact match or glob-style prefix/suffix wildcards.
+ *   "Button"   → exact match
+ *   "Svg*"     → prefix match
+ *   "*Icon"    → suffix match
+ *   "*Badge*"  → contains match
+ */
+function matchesPattern(name: string, pattern: string): boolean {
+  if (!pattern.includes('*')) {
+    return name === pattern;
+  }
+
+  const parts = pattern.split('*');
+  if (parts.length === 2) {
+    const [prefix, suffix] = parts;
+    if (prefix && suffix) return name.startsWith(prefix) && name.endsWith(suffix);
+    if (prefix) return name.startsWith(prefix);
+    if (suffix) return name.endsWith(suffix);
+    return true; // pattern is just "*"
+  }
+
+  // Multi-wildcard: convert to regex
+  const escaped = parts.map(p => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*');
+  return new RegExp(`^${escaped}$`).test(name);
+}

package/src/core/types.ts

@@ -454,6 +454,25 @@ export interface SnippetPolicyConfig {
   allowedExternalModules?: string[];
 }
 
+/**
+ * Storybook adapter filtering configuration.
+ * Controls which Storybook stories are included when generating fragments.
+ */
+export interface StorybookFilterConfig {
+  /** Glob-style patterns for component names to explicitly exclude */
+  exclude?: string[];
+  /** Glob-style patterns for component names to force-include (bypasses all heuristic filters) */
+  include?: string[];
+  /** Exclude stories with "Deprecated" in the title (default: true) */
+  excludeDeprecated?: boolean;
+  /** Exclude test stories (title ending /test(s) or *.test.stories.* files) (default: true) */
+  excludeTests?: boolean;
+  /** Exclude SVG icon components (names matching Svg[A-Z]*) (default: true) */
+  excludeSvgIcons?: boolean;
+  /** Exclude sub-components detected by directory structure (default: true) */
+  excludeSubComponents?: boolean;
+}
+
 /**
  * Config file structure
  */
@@ -499,6 +518,9 @@ export interface FragmentsConfig {
 
   /** Performance budgets: preset name or custom config */
   performance?: string | { preset?: string; budgets?: { bundleSize?: number } };
+
+  /** Storybook adapter filtering configuration */
+  storybook?: StorybookFilterConfig;
 }
 
 /**

package/src/migrate/converter.ts

@@ -87,6 +87,7 @@ export function convertToFragment(parsed: ParsedStoryFile): ConversionResult {
   const code = generateFragmentCode({
     componentName,
     componentImport: parsed.meta.componentImport,
+    isDefaultImport: parsed.meta.isDefaultImport,
     description: parsed.meta.description,
     category,
     tags: parsed.meta.tags,
@@ -484,6 +485,7 @@ interface GeneratedMetadata {
 interface GenerateOptions {
   componentName: string;
   componentImport: string;
+  isDefaultImport?: boolean;
   description?: string;
   category: string;
   tags?: string[];
@@ -504,6 +506,7 @@ function generateFragmentCode(options: GenerateOptions): string {
   const {
     componentName,
     componentImport,
+    isDefaultImport,
     description,
     category,
     tags,
@@ -550,8 +553,13 @@ ${generated.skippedVariants.map(sv => `      { name: "${escapeString(sv.name)}",
   }
 
   // Import the actual component - this makes the fragment immediately usable
+  // Use default import when the source component uses export default
+  const componentImportStatement = isDefaultImport
+    ? `import ${componentName} from "${componentImport}";`
+    : `import { ${componentName} } from "${componentImport}";`;
+
   return `import { defineFragment } from "@fragments-sdk/cli/core";
-import { ${componentName} } from "${componentImport}";
+${componentImportStatement}
 
 export default defineFragment({
   component: ${componentName},

package/src/migrate/parser.ts

@@ -235,6 +235,7 @@ function parseMeta(
     );
     if (importMatch) {
       result.componentImport = importMatch[1];
+      result.isDefaultImport = false;
     } else {
       // Try default import
       const defaultImportMatch = content.match(
@@ -244,6 +245,7 @@ function parseMeta(
       );
       if (defaultImportMatch) {
         result.componentImport = defaultImportMatch[1];
+        result.isDefaultImport = true;
       }
     }
   }

package/src/migrate/types.ts

@@ -12,6 +12,8 @@ export interface ParsedMeta {
   componentName: string;
   /** Component import path */
   componentImport?: string;
+  /** Whether the component uses a default import (export default) */
+  isDefaultImport?: boolean;
   /** Tags from the story */
   tags?: string[];
   /** Description from parameters.docs */

package/src/setup.ts

@@ -2,6 +2,7 @@ import pc from 'picocolors';
 import { BRAND } from './core/index.js';
 import { loadConfig, discoverFragmentFiles } from './core/node.js';
 import { buildFragments } from './build.js';
+import { scan } from './commands/scan.js';
 import {
   detectStorybookConfig,
   discoverStoryFiles as discoverStorybookFiles,
@@ -125,48 +126,78 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
     let fragmentFiles = await discoverFragmentFiles(config, configDir);
 
     if (fragmentFiles.length === 0 && !options.skipStorybook) {
-      // No fragment files - check for Storybook
+      // No fragment files - check for Storybook stories that the viewer can load directly
       log(pc.yellow('\n   No fragment files found'));
 
       const sbConfig = await detectStorybookConfig(configDir);
       if (sbConfig) {
         log(pc.dim(`   Found Storybook at ${sbConfig.configPath}`));
-        log(pc.dim('   Converting stories to fragments...\n'));
 
-        // Discover and convert stories
-        const storyFiles = await discoverStorybookFiles(configDir, sbConfig.storyPatterns);
+        // Check if config.include already covers story files
+        const hasStoryPatterns = config.include.some((p: string) => p.includes('.stories.'));
 
-        if (storyFiles.length > 0) {
-          let converted = 0;
-          for (const storyFile of storyFiles) {
-            try {
-              const parsed = await parseStoryFile(storyFile);
-              const fragmentResult = convertToFragment(parsed);
+        if (hasStoryPatterns) {
+          // Stories are in the include config — discover them directly
+          // The viewer handles .stories.tsx natively via storyModuleToFragment()
+          log(pc.dim('   Stories included in config — viewer will load them directly\n'));
+          fragmentFiles = await discoverFragmentFiles(config, configDir);
 
-              // Create directory and write file
-              await fs.mkdir(path.dirname(fragmentResult.outputFile), { recursive: true });
-              await fs.writeFile(fragmentResult.outputFile, fragmentResult.code);
-              converted++;
-            } catch {
-              // Skip files that can't be converted
-            }
+          if (fragmentFiles.length > 0) {
+            log(pc.green(`   Found ${fragmentFiles.length} story/fragment file(s)`));
           }
+        } else {
+          // Stories not in config — fall back to conversion
+          log(pc.dim('   Converting stories to fragments...\n'));
+
+          const storyFiles = await discoverStorybookFiles(configDir, sbConfig.storyPatterns);
+
+          if (storyFiles.length > 0) {
+            let converted = 0;
+            for (const storyFile of storyFiles) {
+              try {
+                const parsed = await parseStoryFile(storyFile);
+                const fragmentResult = convertToFragment(parsed);
+
+                // Create directory and write file
+                await fs.mkdir(path.dirname(fragmentResult.outputFile), { recursive: true });
+                await fs.writeFile(fragmentResult.outputFile, fragmentResult.code);
+                converted++;
+              } catch {
+                // Skip files that can't be converted
+              }
+            }
 
-          result.fragmentFilesCreated = converted;
-          log(pc.green(`   Generated ${converted} fragment file(s)`));
+            result.fragmentFilesCreated = converted;
+            log(pc.green(`   Generated ${converted} fragment file(s)`));
 
-          // Refresh fragment files list
-          fragmentFiles = await discoverFragmentFiles(config, configDir);
+            // Refresh fragment files list
+            fragmentFiles = await discoverFragmentFiles(config, configDir);
+          }
         }
       } else {
+        // No Storybook — auto-scan source code to generate fragments.json
         log(pc.dim('   No Storybook config found'));
-        log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} add <ComponentName>`)} to create your first fragment`));
+        log(pc.dim('   Auto-scanning source code...\n'));
+
+        try {
+          const scanResult = await scan({
+            config: options.configPath,
+            verbose: false,
+          });
+
+          if (scanResult.componentCount > 0) {
+            result.fragmentsBuilt = scanResult.componentCount;
+            log(pc.green(`   Scanned ${scanResult.componentCount} component(s) from source`));
+          }
+        } catch {
+          log(pc.dim(`   Run ${pc.cyan(`${BRAND.cliCommand} scan`)} to generate documentation from source`));
+        }
       }
     } else if (fragmentFiles.length > 0) {
       log(pc.green(`   Found ${fragmentFiles.length} fragment file(s)`));
     }
 
-    // Step 2: Build fragments.json if needed
+    // Step 2: Build fragments.json if needed (only when fragment files exist)
     if (fragmentFiles.length > 0 && !options.skipBuild) {
       const outFile = config.outFile || BRAND.outFile;
       const { stale, missing } = await isFragmentsJsonStale(configDir, outFile);
@@ -185,7 +216,21 @@ export async function runSetup(options: SetupOptions = {}): Promise<SetupResult>
             }
           }
 
-          log(pc.green(`   Built ${buildResult.fragmentCount} fragment(s)`));
+          if (buildResult.fragmentCount > 0) {
+            log(pc.green(`   Built ${buildResult.fragmentCount} fragment(s)`));
+          } else {
+            // Build found 0 fragments — fallback to scan
+            log(pc.dim('   No compilable fragments found, falling back to source scan...'));
+            try {
+              const scanResult = await scan({ verbose: false });
+              if (scanResult.componentCount > 0) {
+                result.fragmentsBuilt = scanResult.componentCount;
+                log(pc.green(`   Scanned ${scanResult.componentCount} component(s) from source`));
+              }
+            } catch {
+              // scan failed silently
+            }
+          }
         } catch (error) {
           result.errors.push(`Build failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }

package/src/viewer/__tests__/viewer-integration.test.ts

@@ -91,7 +91,7 @@ describe("virtual module @fragments-sdk/cli/core import", () => {
 
     // The generated virtual module string should reference @fragments-sdk/cli/core
     expect(content).toContain(
-      'import { storyModuleToFragment, setPreviewConfig } from "@fragments-sdk/cli/core"'
+      'import { storyModuleToFragment, setPreviewConfig, checkStoryExclusion, isForceIncluded, isConfigExcluded } from "@fragments-sdk/cli/core"'
     );
   });