@usefragments/core 1.10.2 → 2.0.0

package/src/fragment-types.ts

@@ -1,214 +0,0 @@
-/**
- * TypeScript types for Fragment JSON files.
- * These types correspond to the JSON schemas in ./schema/
- */
-
-/**
- * Figma design links and mappings
- */
-export interface FragmentFigma {
-  /** Figma file URL */
-  file?: string;
-  /** Default Figma node ID for this component */
-  nodeId?: string;
-  /** Mapping of variant names to Figma node IDs */
-  variants?: Record<string, string>;
-}
-
-/**
- * Anti-pattern with optional alternative
- */
-export interface FragmentDoNotItem {
-  /** What not to do */
-  text: string;
-  /** Component name to use instead */
-  instead?: string;
-}
-
-/**
- * Usage pattern with code example
- */
-export interface FragmentPattern {
-  /** Pattern name */
-  name: string;
-  /** Code example */
-  code: string;
-  /** When to use this pattern */
-  description?: string;
-}
-
-/**
- * Usage guidelines for AI agents and developers
- */
-export interface FragmentUsage {
-  /** Scenarios when this component should be used */
-  when?: string[];
-  /** Anti-patterns and what to use instead */
-  doNot?: (string | FragmentDoNotItem)[];
-  /** Common usage patterns with code examples */
-  patterns?: FragmentPattern[];
-}
-
-/**
- * Accessibility requirements and guidelines
- */
-export interface FragmentAccessibility {
-  /** ARIA role this component implements */
-  role?: string;
-  /** Accessibility requirements */
-  requirements?: string[];
-  /** Keyboard interaction patterns (key -> description) */
-  keyboard?: Record<string, string>;
-}
-
-/**
- * Relationships to other components
- */
-export interface FragmentRelated {
-  /** Similar components that might be alternatives */
-  similar?: string[];
-  /** Components commonly used together with this one */
-  composedWith?: string[];
-  /** Parent components or patterns where this is commonly used */
-  usedIn?: string[];
-}
-
-/**
- * Administrative metadata
- */
-export interface FragmentMeta {
-  /** Team or person responsible for this component */
-  owner?: string;
-  /** Component lifecycle status */
-  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
-  /** Version when this component was introduced */
-  since?: string;
-  /** Version when this component was deprecated */
-  deprecatedSince?: string;
-  /** Why this component was deprecated and what to use instead */
-  deprecatedReason?: string;
-  /** Tags for categorization and search */
-  tags?: string[];
-}
-
-/**
- * Fragment JSON file structure (.fragment.json)
- * Contains enrichment metadata for a component
- */
-export interface Fragment {
-  /** JSON Schema reference */
-  $schema?: string;
-  /** Component name (must match the component export name) */
-  name: string;
-  /** Brief description of the component's purpose */
-  description?: string;
-  /** Figma design links and mappings */
-  figma?: FragmentFigma;
-  /** Usage guidelines for AI agents and developers */
-  usage?: FragmentUsage;
-  /** Accessibility requirements and guidelines */
-  accessibility?: FragmentAccessibility;
-  /** Relationships to other components */
-  related?: FragmentRelated;
-  /** Administrative metadata */
-  meta?: FragmentMeta;
-}
-
-/**
- * Prop entry in the registry
- */
-export interface RegistryPropEntry {
-  /** TypeScript type (e.g., 'string', 'boolean', enum values) */
-  type?: string;
-  /** Simplified type category */
-  typeKind?: "string" | "number" | "boolean" | "enum" | "object" | "array" | "function" | "node" | "element" | "union" | "unknown";
-  /** For enum types, the allowed values */
-  options?: string[];
-  /** Default value if specified */
-  default?: unknown;
-  /** Whether this prop is required */
-  required?: boolean;
-  /** Prop description from JSDoc or TypeScript */
-  description?: string;
-}
-
-/**
- * Component entry in the registry (simplified - focuses on paths and enrichment)
- */
-export interface RegistryComponentEntry {
-  /** Relative path to the component source file */
-  path: string;
-  /** Relative path to the .fragment.json file (if exists) */
-  fragmentPath?: string;
-  /** Relative path to the .stories.tsx file (if exists) */
-  storyPath?: string;
-  /** Component category (inferred from directory or fragment) */
-  category?: string;
-  /** Component lifecycle status (from fragment) */
-  status?: "draft" | "experimental" | "beta" | "stable" | "deprecated";
-  /** Component description (from fragment or JSDoc) */
-  description?: string;
-  /** Has human-authored enrichment (fragment file exists with content beyond skeleton) */
-  hasEnrichment?: boolean;
-  /** Extracted prop definitions - only included if config.registry.includeProps is true */
-  props?: Record<string, RegistryPropEntry>;
-  /** Named exports from the component file */
-  exports?: string[];
-  /** Component dependencies (other components used) */
-  dependencies?: string[];
-  /** Merged fragment enrichment data - only included if config.registry.embedFragments is true */
-  fragment?: Fragment;
-}
-
-/**
- * Minimal component index (.fragments/index.json)
- * Ultra-light name → path mapping for quick lookups
- */
-export interface FragmentIndex {
-  /** Schema version */
-  version: string;
-  /** When this index was generated */
-  generatedAt: string;
-  /** Simple name → path mapping */
-  components: Record<string, string>;
-  /** Categories for grouping */
-  categories?: Record<string, string[]>;
-}
-
-/**
- * Registry file structure (.fragments/registry.json)
- * Component index with resolved paths and optional metadata
- */
-export interface FragmentRegistry {
-  /** JSON Schema reference */
-  $schema?: string;
-  /** Schema version */
-  version: string;
-  /** When this registry was generated */
-  generatedAt: string;
-  /** Component count for quick reference */
-  componentCount: number;
-  /** Component index keyed by component name */
-  components: Record<string, RegistryComponentEntry>;
-  /** Components grouped by category */
-  categories?: Record<string, string[]>;
-}
-
-/**
- * Context file options for generation
- */
-export interface FragmentContextOptions {
-  /** Output format */
-  format?: "markdown" | "json";
-  /** Compact mode - minimal output for token efficiency */
-  compact?: boolean;
-  /** What to include in the output */
-  include?: {
-    /** Include prop details (default: true) */
-    props?: boolean;
-    /** Include code examples (default: false) */
-    code?: boolean;
-    /** Include related components (default: true) */
-    relations?: boolean;
-  };
-}

package/src/react-create-element.test.ts

@@ -1,22 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-describe("getCreateElement", () => {
-  afterEach(() => {
-    vi.resetModules();
-    vi.doUnmock("node:module");
-  });
-
-  it("throws a clear error when react cannot be resolved", async () => {
-    vi.doMock("node:module", () => ({
-      createRequire: () => () => {
-        throw new Error("Cannot find module 'react'");
-      },
-    }));
-
-    const { getCreateElement } = await import("./react-create-element.js");
-
-    expect(() => getCreateElement()).toThrow(
-      '@usefragments/core: story rendering requires the optional peer dependency "react" (>=18). Install react to use storyModuleToFragment default render paths.',
-    );
-  });
-});

package/src/react-create-element.ts

@@ -1,12 +0,0 @@
-import { createRequire } from "node:module";
-
-export function getCreateElement(): typeof import("react")["createElement"] {
-  try {
-    return (createRequire(import.meta.url)("react") as typeof import("react")).createElement;
-  } catch (error) {
-    throw new Error(
-      '@usefragments/core: story rendering requires the optional peer dependency "react" (>=18). Install react to use storyModuleToFragment default render paths.',
-      { cause: error instanceof Error ? error : undefined },
-    );
-  }
-}

package/src/storyFilters.test.ts

@@ -1,350 +0,0 @@
-/**
- * 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);
-  });
-});