@fragments-sdk/cli 0.8.1 → 0.9.1

package/src/commands/init.ts

@@ -462,9 +462,9 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
 
   // Step 3: Gather configuration (interactive unless --yes)
   let componentPath = detection.suggestedComponentPath;
-  let runScan = scenario === "components";
+  let runScan = scenario === "components" || scenario === "stories";
   let createExample = scenario === "fresh";
-  let startServer = true;
+  let startServer = false;
 
   if (!options.yes) {
     // Ask about component location
@@ -473,13 +473,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
       default: detection.suggestedComponentPath,
     });
 
-    if (scenario === "components") {
-      // For component-only projects, ask about scanning
-      runScan = await confirm({
-        message: "Auto-generate documentation from TypeScript?",
-        default: true,
-      });
-    } else {
+    if (scenario === "fresh") {
       // Fresh project - ask about example
       createExample = await confirm({
         message: "Create an example Button component to get started?",
@@ -502,7 +496,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     `${componentPath}/**/*.fragment.tsx`,
   ];
 
-  // Include story files when Storybook is detected
+  // If Storybook stories detected, also include them for direct rendering
   if (scenario === 'stories') {
     includePaths.push(`${componentPath}/**/*.stories.tsx`);
     includePaths.push(`${componentPath}/**/*.stories.ts`);
@@ -557,39 +551,9 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     }
   }
 
-  if (scenario === "components" && runScan) {
-    // Generate .fragment.tsx stubs for discovered components
-    let stubsCreated = 0;
-    for (const compFile of detection.componentFiles) {
-      const absPath = join(projectRoot, compFile);
-      const dir = dirname(absPath);
-      const fileName = basename(compFile, ".tsx");
-      const componentName = toPascalCase(fileName);
-      const fragmentPath = join(dir, `${fileName}.fragment.tsx`);
-
-      // Skip if fragment already exists
-      try {
-        await access(fragmentPath);
-        continue; // already exists
-      } catch {
-        // doesn't exist, create it
-      }
-
-      try {
-        const stub = generateFragmentStub(componentName, `./${fileName}`);
-        await writeFile(fragmentPath, stub, "utf-8");
-        stubsCreated++;
-      } catch {
-        // skip files we can't write to
-      }
-    }
-
-    if (stubsCreated > 0) {
-      console.log(pc.green(`✓ Generated ${stubsCreated} fragment stub(s)`));
-    }
-
-    // Run scan to generate fragments.json
-    console.log(pc.dim("\nGenerating documentation from source code...\n"));
+  if (runScan) {
+    // Run scan to generate fragments.json from source code
+    console.log(pc.dim("\nScanning source code for documentation...\n"));
     try {
       const { scan } = await import("./scan.js");
       await scan({
@@ -641,14 +605,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     console.log(pc.green("\n✓ Setup complete!\n"));
 
     if (startServer) {
-      const serverMessage =
-        scenario === "stories"
-          ? `Your ${detection.storyFiles.length} stories are loading...`
-          : scenario === "components"
-          ? `Your ${detection.componentFiles.length} components are being documented...`
-          : `Your first component is ready!`;
-
-      console.log(pc.cyan(serverMessage));
+      console.log(pc.cyan("Starting viewer...\n"));
       startDevServer(projectRoot);
     } else {
       console.log(pc.cyan("Next steps:"));
@@ -656,6 +613,7 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
       if (scenario === "fresh") {
         console.log(`  2. Edit ${pc.bold(`${componentPath}/Button/Button.fragment.tsx`)}`);
       }
+      console.log(`  3. Run ${pc.bold(`${BRAND.cliCommand} generate`)} to create fragment files for your components`);
       console.log();
     }
   }

package/src/core/config.ts

@@ -2,9 +2,16 @@ import { existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { createJiti } from 'jiti';
 import { BRAND } from './constants.js';
-import type { FragmentsConfig } from './types.js';
+import type { FragmentsConfig, StorybookFilterConfig } from './types.js';
 import { fragmentsConfigSchema } from './schema.js';
 
+const STORYBOOK_FILTER_DEFAULTS: StorybookFilterConfig = {
+  excludeDeprecated: true,
+  excludeTests: true,
+  excludeSvgIcons: true,
+  excludeSubComponents: true,
+};
+
 const DEFAULT_CONFIG: FragmentsConfig = {
   include: [
     `src/**/*${BRAND.fileExtension}`,  // *.fragment.tsx files
@@ -13,6 +20,7 @@ const DEFAULT_CONFIG: FragmentsConfig = {
   exclude: ['**/node_modules/**'],
   components: ['src/**/index.tsx', 'src/**/*.tsx'],
   framework: 'react',
+  storybook: STORYBOOK_FILTER_DEFAULTS,
   snippets: {
     mode: 'warn',
     scope: 'snippet+render',
@@ -77,8 +85,13 @@ export async function loadConfig(configPath?: string): Promise<{
       throw new Error(`Invalid config in ${resolvedPath}:\n${errors}`);
     }
 
+    const merged: FragmentsConfig = { ...DEFAULT_CONFIG, ...result.data };
+
+    // Deep-merge storybook filter defaults so consumers only override what they need
+    merged.storybook = { ...STORYBOOK_FILTER_DEFAULTS, ...result.data?.storybook };
+
     return {
-      config: { ...DEFAULT_CONFIG, ...result.data },
+      config: merged,
       configDir: dirname(resolvedPath),
     };
   } catch (error) {

package/src/core/generators/typescript-extractor.ts

@@ -13,6 +13,8 @@ import type { RegistryPropEntry } from "../fragment-types.js";
 export interface ExtractedProps {
   /** Component name */
   componentName: string;
+  /** Whether the component uses export default */
+  isDefaultExport?: boolean;
   /** Props interface name (e.g., "ButtonProps") */
   propsInterfaceName?: string;
   /** Extracted props */
@@ -56,6 +58,7 @@ export function extractPropsFromSource(
   // Find all exports and props interfaces
   const propsInterfaces = new Map<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration>();
   const componentExports: string[] = [];
+  const defaultExports = new Set<string>();
   const importedModules: string[] = [];
 
   ts.forEachChild(sourceFile, (node) => {
@@ -88,8 +91,14 @@ export function extractPropsFromSource(
       const hasExport = node.modifiers?.some(
         (m) => m.kind === ts.SyntaxKind.ExportKeyword
       );
+      const hasDefault = node.modifiers?.some(
+        (m) => m.kind === ts.SyntaxKind.DefaultKeyword
+      );
       if (hasExport) {
         componentExports.push(node.name.text);
+        if (hasDefault) {
+          defaultExports.add(node.name.text);
+        }
       }
     }
 
@@ -130,6 +139,7 @@ export function extractPropsFromSource(
   }
 
   result.componentName = mainComponent;
+  result.isDefaultExport = defaultExports.has(mainComponent);
 
   // Find matching props interface
   const propsInterfaceName = `${mainComponent}Props`;

package/src/core/index.ts

@@ -57,6 +57,8 @@ export type {
   FigmaInstanceMapping,
   FigmaChildrenMapping,
   FigmaTextContentMapping,
+  // Storybook filter configuration
+  StorybookFilterConfig,
   // Token configuration
   TokenConfig,
   // Compiled token types
@@ -141,6 +143,19 @@ export type {
   CSF2Story,
 } from "./storyAdapter.js";
 
+// Storybook adapter filtering
+export {
+  checkStoryExclusion,
+  detectSubComponentPaths,
+  isForceIncluded,
+  isConfigExcluded,
+} from "./storyFilters.js";
+export type {
+  ExclusionReason,
+  ExclusionResult,
+  CheckStoryExclusionOpts,
+} from "./storyFilters.js";
+
 // Context generation for AI agents
 export { generateContext } from "./context.js";
 export type { ContextOptions, ContextResult } from "./context.js";

package/src/core/schema.ts

@@ -63,8 +63,8 @@ export const fragmentMetaSchema = z.object({
 });
 
 export const fragmentUsageSchema = z.object({
-  when: z.array(z.string()).min(1),
-  whenNot: z.array(z.string()).min(1),
+  when: z.array(z.string()),
+  whenNot: z.array(z.string()),
   guidelines: z.array(z.string()).optional(),
   accessibility: z.array(z.string()).optional(),
 });
@@ -213,6 +213,14 @@ export const fragmentsConfigSchema = z.object({
       }).optional(),
     }),
   ]).optional(),
+  storybook: z.object({
+    exclude: z.array(z.string()).optional(),
+    include: z.array(z.string()).optional(),
+    excludeDeprecated: z.boolean().optional(),
+    excludeTests: z.boolean().optional(),
+    excludeSvgIcons: z.boolean().optional(),
+    excludeSubComponents: z.boolean().optional(),
+  }).optional(),
 });
 
 /**

package/src/core/storyFilters.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Unit tests for Storybook adapter filtering.
+ * Tests per-file heuristics, cross-file sub-component detection, and config precedence.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  checkStoryExclusion,
+  detectSubComponentPaths,
+  isForceIncluded,
+  isConfigExcluded,
+  type ExclusionResult,
+} from './storyFilters.js';
+import type { StorybookFilterConfig } from './types.js';
+
+const DEFAULTS: StorybookFilterConfig = {
+  excludeDeprecated: true,
+  excludeTests: true,
+  excludeSvgIcons: true,
+  excludeSubComponents: true,
+};
+
+// ---------------------------------------------------------------------------
+// detectSubComponentPaths
+// ---------------------------------------------------------------------------
+
+describe('detectSubComponentPaths', () => {
+  it('identifies sub-components when one story matches the directory name', () => {
+    const files = [
+      { relativePath: 'src/components/Form/Form.stories.tsx' },
+      { relativePath: 'src/components/Form/Checkbox.stories.tsx' },
+      { relativePath: 'src/components/Form/RadioGroup.stories.tsx' },
+    ];
+    const result = detectSubComponentPaths(files);
+
+    expect(result.size).toBe(2);
+    expect(result.get('src/components/Form/Checkbox.stories.tsx')).toBe('Form');
+    expect(result.get('src/components/Form/RadioGroup.stories.tsx')).toBe('Form');
+    expect(result.has('src/components/Form/Form.stories.tsx')).toBe(false);
+  });
+
+  it('treats story in its own sub-directory as standalone', () => {
+    const files = [
+      { relativePath: 'src/components/Form/Form.stories.tsx' },
+      { relativePath: 'src/components/Button/Button.stories.tsx' },
+    ];
+    const result = detectSubComponentPaths(files);
+    expect(result.size).toBe(0);
+  });
+
+  it('keeps single story in a directory as standalone', () => {
+    const files = [
+      { relativePath: 'src/components/Button/Button.stories.tsx' },
+    ];
+    const result = detectSubComponentPaths(files);
+    expect(result.size).toBe(0);
+  });
+
+  it('keeps all stories when no story matches the directory name', () => {
+    const files = [
+      { relativePath: 'src/components/Inputs/Checkbox.stories.tsx' },
+      { relativePath: 'src/components/Inputs/RadioGroup.stories.tsx' },
+      { relativePath: 'src/components/Inputs/Toggle.stories.tsx' },
+    ];
+    const result = detectSubComponentPaths(files);
+    expect(result.size).toBe(0);
+  });
+
+  it('detects three stories with one primary → two sub-components', () => {
+    const files = [
+      { relativePath: 'src/components/Table/Table.stories.tsx' },
+      { relativePath: 'src/components/Table/TableHeader.stories.tsx' },
+      { relativePath: 'src/components/Table/TableRow.stories.tsx' },
+    ];
+    const result = detectSubComponentPaths(files);
+
+    expect(result.size).toBe(2);
+    expect(result.get('src/components/Table/TableHeader.stories.tsx')).toBe('Table');
+    expect(result.get('src/components/Table/TableRow.stories.tsx')).toBe('Table');
+  });
+
+  it('ignores non-story file patterns', () => {
+    const files = [
+      { relativePath: 'src/components/Form/Form.fragment.tsx' },
+      { relativePath: 'src/components/Form/Checkbox.fragment.tsx' },
+    ];
+    const result = detectSubComponentPaths(files);
+    expect(result.size).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkStoryExclusion
+// ---------------------------------------------------------------------------
+
+describe('checkStoryExclusion', () => {
+  const base = {
+    componentName: 'Button',
+    variantCount: 3,
+    filePath: 'src/components/Button/Button.stories.tsx',
+    config: DEFAULTS,
+  };
+
+  it('keeps a normal component', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      storybookTitle: 'Components/Actions/Button',
+    });
+    expect(result.excluded).toBe(false);
+  });
+
+  it('excludes deprecated titles', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      storybookTitle: 'Deprecated/OldButton',
+    });
+    expect(result).toEqual<ExclusionResult>({
+      excluded: true,
+      reason: 'deprecated',
+      detail: expect.stringContaining('Deprecated'),
+    });
+  });
+
+  it('excludes titles ending with /test', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      storybookTitle: 'Components/Button/Test',
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('test-story');
+  });
+
+  it('excludes titles ending with /tests', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      storybookTitle: 'Components/Button/Tests',
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('test-story');
+  });
+
+  it('excludes *.test.stories.* file paths', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      filePath: 'src/components/Button/Button.test.stories.tsx',
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('test-story');
+  });
+
+  it('excludes SVG icons by displayName', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      componentName: 'HomeLarge',
+      componentDisplayName: 'SvgHomeLarge',
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('svg-icon');
+  });
+
+  it('excludes SVG icons by function name', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      componentName: 'HomeLarge',
+      componentFunctionName: 'SvgHomeLarge',
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('svg-icon');
+  });
+
+  it('excludes SVG icons by component name', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      componentName: 'SvgArrowRight',
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('svg-icon');
+  });
+
+  it('excludes hidden-tagged stories', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      tags: ['hidden'],
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('tag-excluded');
+  });
+
+  it('excludes internal-tagged stories', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      tags: ['internal'],
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('tag-excluded');
+  });
+
+  it('excludes no-fragment-tagged stories', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      tags: ['no-fragment'],
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('tag-excluded');
+  });
+
+  it('excludes stories with zero variants', () => {
+    const result = checkStoryExclusion({
+      ...base,
+      variantCount: 0,
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('empty-variants');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Config precedence
+// ---------------------------------------------------------------------------
+
+describe('config precedence', () => {
+  it('force-includes a component despite SVG icon rule', () => {
+    const result = checkStoryExclusion({
+      componentName: 'SvgHomeLarge',
+      variantCount: 1,
+      filePath: 'src/icons/SvgHomeLarge.stories.tsx',
+      config: { ...DEFAULTS, include: ['SvgHomeLarge'] },
+    });
+    expect(result.excluded).toBe(false);
+  });
+
+  it('force-includes a component despite deprecated rule', () => {
+    const result = checkStoryExclusion({
+      componentName: 'OldButton',
+      storybookTitle: 'Deprecated/OldButton',
+      variantCount: 1,
+      filePath: 'src/components/OldButton.stories.tsx',
+      config: { ...DEFAULTS, include: ['OldButton'] },
+    });
+    expect(result.excluded).toBe(false);
+  });
+
+  it('keeps deprecated when excludeDeprecated is false', () => {
+    const result = checkStoryExclusion({
+      componentName: 'OldButton',
+      storybookTitle: 'Deprecated/OldButton',
+      variantCount: 1,
+      filePath: 'src/components/OldButton.stories.tsx',
+      config: { ...DEFAULTS, excludeDeprecated: false },
+    });
+    expect(result.excluded).toBe(false);
+  });
+
+  it('keeps test stories when excludeTests is false', () => {
+    const result = checkStoryExclusion({
+      componentName: 'Button',
+      storybookTitle: 'Components/Button/Tests',
+      variantCount: 1,
+      filePath: 'src/components/Button.stories.tsx',
+      config: { ...DEFAULTS, excludeTests: false },
+    });
+    expect(result.excluded).toBe(false);
+  });
+
+  it('keeps SVG icons when excludeSvgIcons is false', () => {
+    const result = checkStoryExclusion({
+      componentName: 'SvgArrowRight',
+      variantCount: 1,
+      filePath: 'src/icons/SvgArrowRight.stories.tsx',
+      config: { ...DEFAULTS, excludeSvgIcons: false },
+    });
+    expect(result.excluded).toBe(false);
+  });
+
+  it('config-excludes a component by name', () => {
+    const result = checkStoryExclusion({
+      componentName: 'JCB',
+      variantCount: 1,
+      filePath: 'src/components/JCB.stories.tsx',
+      config: { ...DEFAULTS, exclude: ['JCB'] },
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('config-excluded');
+  });
+
+  it('config-excludes with wildcard pattern', () => {
+    const result = checkStoryExclusion({
+      componentName: 'SvgHomeLarge',
+      variantCount: 1,
+      filePath: 'src/icons/SvgHomeLarge.stories.tsx',
+      config: { ...DEFAULTS, exclude: ['Svg*'] },
+    });
+    expect(result.excluded).toBe(true);
+    expect(result.reason).toBe('config-excluded');
+  });
+
+  it('include wins over exclude', () => {
+    const result = checkStoryExclusion({
+      componentName: 'SvgHomeLarge',
+      variantCount: 1,
+      filePath: 'src/icons/SvgHomeLarge.stories.tsx',
+      config: { ...DEFAULTS, include: ['SvgHomeLarge'], exclude: ['Svg*'] },
+    });
+    expect(result.excluded).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isForceIncluded / isConfigExcluded helpers
+// ---------------------------------------------------------------------------
+
+describe('isForceIncluded', () => {
+  it('returns false with no include patterns', () => {
+    expect(isForceIncluded('Button', {})).toBe(false);
+  });
+
+  it('matches exact name', () => {
+    expect(isForceIncluded('Button', { include: ['Button'] })).toBe(true);
+  });
+
+  it('matches wildcard prefix', () => {
+    expect(isForceIncluded('SvgArrowRight', { include: ['Svg*'] })).toBe(true);
+  });
+
+  it('does not match non-matching pattern', () => {
+    expect(isForceIncluded('Button', { include: ['Svg*'] })).toBe(false);
+  });
+
+  it('matches suffix wildcard', () => {
+    expect(isForceIncluded('BigButton', { include: ['*Button'] })).toBe(true);
+  });
+
+  it('matches contains wildcard', () => {
+    expect(isForceIncluded('MyButtonGroup', { include: ['*Button*'] })).toBe(true);
+  });
+});
+
+describe('isConfigExcluded', () => {
+  it('returns false with no exclude patterns', () => {
+    expect(isConfigExcluded('Button', {})).toBe(false);
+  });
+
+  it('matches exact name', () => {
+    expect(isConfigExcluded('JCB', { exclude: ['JCB'] })).toBe(true);
+  });
+
+  it('matches wildcard', () => {
+    expect(isConfigExcluded('SvgHomeLarge', { exclude: ['Svg*'] })).toBe(true);
+  });
+});