@fragments-sdk/core 0.1.0

package/src/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);
+  });
+});

package/src/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/storybook-csf.ts

@@ -0,0 +1,11 @@
+import {
+  toId as storybookToId,
+  storyNameFromExport as storybookStoryNameFromExport,
+  isExportStory as storybookIsExportStory,
+} from "@storybook/csf";
+
+export const toId: typeof storybookToId = (...args) => storybookToId(...args);
+export const storyNameFromExport: typeof storybookStoryNameFromExport = (...args) =>
+  storybookStoryNameFromExport(...args);
+export const isExportStory: typeof storybookIsExportStory = (...args) =>
+  storybookIsExportStory(...args);