@effinrich/forgekit-storybook-plugin 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,206 @@
+interface PropInfo {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: string;
+    description?: string;
+    isCallback: boolean;
+    unionValues?: string[];
+}
+interface ComponentAnalysis {
+    name: string;
+    fileName: string;
+    filePath: string;
+    props: PropInfo[];
+    hasChildren: boolean;
+    imports: ImportInfo[];
+    usesRouter: boolean;
+    usesReactQuery: boolean;
+    usesChakra: boolean;
+    exportType: 'default' | 'named' | 'both';
+}
+interface ImportInfo {
+    source: string;
+    specifiers: string[];
+}
+interface ForgeStoryOptions {
+    componentPath: string;
+    storyTitle?: string;
+    skipInteractionTests?: boolean;
+    overwrite?: boolean;
+    dryRun?: boolean;
+    quiet?: boolean;
+}
+interface ForgeStoriesOptions {
+    dir: string;
+    skipInteractionTests?: boolean;
+    overwrite?: boolean;
+    dryRun?: boolean;
+    includeA11y?: boolean;
+    includeComponentTests?: boolean;
+    quiet?: boolean;
+}
+interface ForgeTestOptions {
+    componentPath: string;
+    overwrite?: boolean;
+    dryRun?: boolean;
+    quiet?: boolean;
+}
+interface WatchOptions {
+    dir: string;
+    ignore?: string[];
+    debounceMs?: number;
+    skipInteractionTests?: boolean;
+    quiet?: boolean;
+}
+interface ScanResult {
+    components: ScannedComponent[];
+    withStories: string[];
+    withoutStories: string[];
+    notAnalyzable: string[];
+    total: number;
+}
+interface ScannedComponent {
+    filePath: string;
+    analysis: ComponentAnalysis | null;
+    hasStory: boolean;
+}
+interface CoverageReport {
+    covered: number;
+    total: number;
+    percentage: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+}
+interface StoryContentOptions {
+    analysis: ComponentAnalysis;
+    storyTitle: string;
+    importPath: string;
+    skipInteractionTests: boolean;
+}
+interface PlaywrightTestOptions {
+    analysis: ComponentAnalysis;
+    importPath: string;
+    hasStories: boolean;
+    storyImportPath?: string;
+}
+
+/**
+ * Analyze a React component file to extract metadata for story generation.
+ *
+ * @param filePath - Absolute or relative path to the component file
+ * @param content  - Optional file content (reads from disk if omitted)
+ */
+declare function analyzeComponent(filePath: string, content?: string): ComponentAnalysis | null;
+
+/**
+ * Scan a directory for React components and classify them by story coverage.
+ */
+declare function scanDirectory(dir: string): Promise<ScanResult>;
+
+/**
+ * Generate the full content of a .stories.tsx file from component analysis.
+ */
+declare function generateStoryContent(options: StoryContentOptions): string;
+
+/**
+ * Generate interaction test stories (play functions) based on component analysis.
+ * Returns an array of lines to append to the story file.
+ */
+declare function generateInteractionTests(analysis: ComponentAnalysis): string[];
+
+/**
+ * Generate a co-located Playwright component test (.ct.tsx) that:
+ * - Mounts the component using @playwright/experimental-ct-react
+ * - Tests rendering, visual regression (screenshot), interactions, and a11y
+ * - Optionally imports stories for story-driven testing
+ */
+declare function generatePlaywrightTest(options: PlaywrightTestOptions): string;
+
+/**
+ * Calculate a coverage score and letter grade from covered/total counts.
+ */
+declare function scoreCoverage(covered: number, total: number): CoverageReport;
+
+/**
+ * Infer a Storybook title from a component's file path.
+ *
+ * Strategy:
+ * 1. Compute relative path from the target directory
+ * 2. Strip common prefixes: src/, lib/, components/
+ * 3. Convert directory segments to PascalCase
+ * 4. Deduplicate consecutive identical segments
+ *
+ * Examples:
+ *   src/components/Button/Button.tsx         → "Components / Button"
+ *   src/components/forms/TextInput.tsx       → "Components / Forms / TextInput"
+ *   src/lib/ui/Modal/Modal.tsx               → "UI / Modal"
+ *   libs/shared/ui/src/lib/button/button.tsx → "Button"
+ */
+declare function inferStoryTitle(filePath: string, baseDir?: string): string;
+
+interface WatchHandle {
+    close(): Promise<void>;
+}
+type WatchEvent = {
+    type: 'ready';
+} | {
+    type: 'generate';
+    file: string;
+    storyPath: string;
+} | {
+    type: 'update';
+    file: string;
+    storyPath: string;
+} | {
+    type: 'error';
+    file: string;
+    error: Error;
+};
+type WatchCallback = (event: WatchEvent) => void;
+/**
+ * Watch a directory for component changes and auto-generate stories.
+ * Returns a handle with .close() for cleanup.
+ */
+declare function watchDirectory(options: WatchOptions, callback?: WatchCallback): WatchHandle;
+
+interface ForgeStoryResult {
+    storyPath: string;
+    content: string;
+    analysis: ComponentAnalysis;
+    storiesGenerated: string[];
+    written: boolean;
+}
+/**
+ * High-level: analyze a component, generate a story, and write it to disk.
+ */
+declare function forgeStory(options: ForgeStoryOptions): Promise<ForgeStoryResult>;
+
+interface ForgeStoriesResult {
+    generated: number;
+    failed: number;
+    alreadyCovered: number;
+    notAnalyzable: number;
+    total: number;
+    coverage: CoverageReport;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/**
+ * High-level: scan a directory, generate stories for all uncovered components.
+ */
+declare function forgeStories(options: ForgeStoriesOptions): Promise<ForgeStoriesResult>;
+
+interface ForgeTestResult {
+    testPath: string;
+    content: string;
+    analysis: ComponentAnalysis;
+    written: boolean;
+}
+/**
+ * High-level: analyze a component, generate a Playwright component test, and write it.
+ */
+declare function forgeTest(options: ForgeTestOptions): Promise<ForgeTestResult>;
+
+export { type ComponentAnalysis, type CoverageReport, type ForgeStoriesOptions, type ForgeStoriesResult, type ForgeStoryOptions, type ForgeStoryResult, type ForgeTestOptions, type ForgeTestResult, type ImportInfo, type PlaywrightTestOptions, type PropInfo, type ScanResult, type ScannedComponent, type StoryContentOptions, type WatchCallback, type WatchEvent, type WatchHandle, type WatchOptions, analyzeComponent, forgeStories, forgeStory, forgeTest, generateInteractionTests, generatePlaywrightTest, generateStoryContent, inferStoryTitle, scanDirectory, scoreCoverage, watchDirectory };

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+interface PropInfo {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: string;
+    description?: string;
+    isCallback: boolean;
+    unionValues?: string[];
+}
+interface ComponentAnalysis {
+    name: string;
+    fileName: string;
+    filePath: string;
+    props: PropInfo[];
+    hasChildren: boolean;
+    imports: ImportInfo[];
+    usesRouter: boolean;
+    usesReactQuery: boolean;
+    usesChakra: boolean;
+    exportType: 'default' | 'named' | 'both';
+}
+interface ImportInfo {
+    source: string;
+    specifiers: string[];
+}
+interface ForgeStoryOptions {
+    componentPath: string;
+    storyTitle?: string;
+    skipInteractionTests?: boolean;
+    overwrite?: boolean;
+    dryRun?: boolean;
+    quiet?: boolean;
+}
+interface ForgeStoriesOptions {
+    dir: string;
+    skipInteractionTests?: boolean;
+    overwrite?: boolean;
+    dryRun?: boolean;
+    includeA11y?: boolean;
+    includeComponentTests?: boolean;
+    quiet?: boolean;
+}
+interface ForgeTestOptions {
+    componentPath: string;
+    overwrite?: boolean;
+    dryRun?: boolean;
+    quiet?: boolean;
+}
+interface WatchOptions {
+    dir: string;
+    ignore?: string[];
+    debounceMs?: number;
+    skipInteractionTests?: boolean;
+    quiet?: boolean;
+}
+interface ScanResult {
+    components: ScannedComponent[];
+    withStories: string[];
+    withoutStories: string[];
+    notAnalyzable: string[];
+    total: number;
+}
+interface ScannedComponent {
+    filePath: string;
+    analysis: ComponentAnalysis | null;
+    hasStory: boolean;
+}
+interface CoverageReport {
+    covered: number;
+    total: number;
+    percentage: number;
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+}
+interface StoryContentOptions {
+    analysis: ComponentAnalysis;
+    storyTitle: string;
+    importPath: string;
+    skipInteractionTests: boolean;
+}
+interface PlaywrightTestOptions {
+    analysis: ComponentAnalysis;
+    importPath: string;
+    hasStories: boolean;
+    storyImportPath?: string;
+}
+
+/**
+ * Analyze a React component file to extract metadata for story generation.
+ *
+ * @param filePath - Absolute or relative path to the component file
+ * @param content  - Optional file content (reads from disk if omitted)
+ */
+declare function analyzeComponent(filePath: string, content?: string): ComponentAnalysis | null;
+
+/**
+ * Scan a directory for React components and classify them by story coverage.
+ */
+declare function scanDirectory(dir: string): Promise<ScanResult>;
+
+/**
+ * Generate the full content of a .stories.tsx file from component analysis.
+ */
+declare function generateStoryContent(options: StoryContentOptions): string;
+
+/**
+ * Generate interaction test stories (play functions) based on component analysis.
+ * Returns an array of lines to append to the story file.
+ */
+declare function generateInteractionTests(analysis: ComponentAnalysis): string[];
+
+/**
+ * Generate a co-located Playwright component test (.ct.tsx) that:
+ * - Mounts the component using @playwright/experimental-ct-react
+ * - Tests rendering, visual regression (screenshot), interactions, and a11y
+ * - Optionally imports stories for story-driven testing
+ */
+declare function generatePlaywrightTest(options: PlaywrightTestOptions): string;
+
+/**
+ * Calculate a coverage score and letter grade from covered/total counts.
+ */
+declare function scoreCoverage(covered: number, total: number): CoverageReport;
+
+/**
+ * Infer a Storybook title from a component's file path.
+ *
+ * Strategy:
+ * 1. Compute relative path from the target directory
+ * 2. Strip common prefixes: src/, lib/, components/
+ * 3. Convert directory segments to PascalCase
+ * 4. Deduplicate consecutive identical segments
+ *
+ * Examples:
+ *   src/components/Button/Button.tsx         → "Components / Button"
+ *   src/components/forms/TextInput.tsx       → "Components / Forms / TextInput"
+ *   src/lib/ui/Modal/Modal.tsx               → "UI / Modal"
+ *   libs/shared/ui/src/lib/button/button.tsx → "Button"
+ */
+declare function inferStoryTitle(filePath: string, baseDir?: string): string;
+
+interface WatchHandle {
+    close(): Promise<void>;
+}
+type WatchEvent = {
+    type: 'ready';
+} | {
+    type: 'generate';
+    file: string;
+    storyPath: string;
+} | {
+    type: 'update';
+    file: string;
+    storyPath: string;
+} | {
+    type: 'error';
+    file: string;
+    error: Error;
+};
+type WatchCallback = (event: WatchEvent) => void;
+/**
+ * Watch a directory for component changes and auto-generate stories.
+ * Returns a handle with .close() for cleanup.
+ */
+declare function watchDirectory(options: WatchOptions, callback?: WatchCallback): WatchHandle;
+
+interface ForgeStoryResult {
+    storyPath: string;
+    content: string;
+    analysis: ComponentAnalysis;
+    storiesGenerated: string[];
+    written: boolean;
+}
+/**
+ * High-level: analyze a component, generate a story, and write it to disk.
+ */
+declare function forgeStory(options: ForgeStoryOptions): Promise<ForgeStoryResult>;
+
+interface ForgeStoriesResult {
+    generated: number;
+    failed: number;
+    alreadyCovered: number;
+    notAnalyzable: number;
+    total: number;
+    coverage: CoverageReport;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/**
+ * High-level: scan a directory, generate stories for all uncovered components.
+ */
+declare function forgeStories(options: ForgeStoriesOptions): Promise<ForgeStoriesResult>;
+
+interface ForgeTestResult {
+    testPath: string;
+    content: string;
+    analysis: ComponentAnalysis;
+    written: boolean;
+}
+/**
+ * High-level: analyze a component, generate a Playwright component test, and write it.
+ */
+declare function forgeTest(options: ForgeTestOptions): Promise<ForgeTestResult>;
+
+export { type ComponentAnalysis, type CoverageReport, type ForgeStoriesOptions, type ForgeStoriesResult, type ForgeStoryOptions, type ForgeStoryResult, type ForgeTestOptions, type ForgeTestResult, type ImportInfo, type PlaywrightTestOptions, type PropInfo, type ScanResult, type ScannedComponent, type StoryContentOptions, type WatchCallback, type WatchEvent, type WatchHandle, type WatchOptions, analyzeComponent, forgeStories, forgeStory, forgeTest, generateInteractionTests, generatePlaywrightTest, generateStoryContent, inferStoryTitle, scanDirectory, scoreCoverage, watchDirectory };

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+var _chunkT4UFXGMCjs = require('./chunk-T4UFXGMC.js');
+
+
+
+
+var _chunkWUKJNZOFjs = require('./chunk-WUKJNZOF.js');
+
+
+
+
+
+
+
+
+
+
+
+
+exports.analyzeComponent = _chunkWUKJNZOFjs.analyzeComponent; exports.forgeStories = _chunkT4UFXGMCjs.forgeStories; exports.forgeStory = _chunkT4UFXGMCjs.forgeStory; exports.forgeTest = _chunkWUKJNZOFjs.forgeTest; exports.generateInteractionTests = _chunkT4UFXGMCjs.generateInteractionTests; exports.generatePlaywrightTest = _chunkWUKJNZOFjs.generatePlaywrightTest; exports.generateStoryContent = _chunkT4UFXGMCjs.generateStoryContent; exports.inferStoryTitle = _chunkT4UFXGMCjs.inferStoryTitle; exports.scanDirectory = _chunkT4UFXGMCjs.scanDirectory; exports.scoreCoverage = _chunkT4UFXGMCjs.scoreCoverage; exports.watchDirectory = _chunkT4UFXGMCjs.watchDirectory;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/richtillman/Documents/GitHub/forgekit-storybook-plugin-1/dist/index.js"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,sDAA4B;AAC5B;AACE;AACA;AACA;AACF,sDAA4B;AAC5B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,ypBAAC","file":"/Users/richtillman/Documents/GitHub/forgekit-storybook-plugin-1/dist/index.js"}

package/dist/index.mjs

@@ -0,0 +1,29 @@
+import {
+  forgeStories,
+  forgeStory,
+  generateInteractionTests,
+  generateStoryContent,
+  inferStoryTitle,
+  scanDirectory,
+  scoreCoverage,
+  watchDirectory
+} from "./chunk-C2HX5UGS.mjs";
+import {
+  analyzeComponent,
+  forgeTest,
+  generatePlaywrightTest
+} from "./chunk-D2RQPIRR.mjs";
+export {
+  analyzeComponent,
+  forgeStories,
+  forgeStory,
+  forgeTest,
+  generateInteractionTests,
+  generatePlaywrightTest,
+  generateStoryContent,
+  inferStoryTitle,
+  scanDirectory,
+  scoreCoverage,
+  watchDirectory
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@effinrich/forgekit-storybook-plugin",
+  "version": "2.0.0",
+  "description": "Auto-generate Storybook stories, interaction tests, Playwright component tests, and accessibility audits from React component analysis",
+  "author": "Rich Tillman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/effinrich/forgekit-storybook-plugin"
+  },
+  "keywords": [
+    "storybook",
+    "react",
+    "testing",
+    "code-generation",
+    "interaction-tests",
+    "playwright",
+    "accessibility",
+    "a11y",
+    "story-generation"
+  ],
+  "bin": {
+    "forgekit-storybook-plugin": "./bin/forgekit.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18.17.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "typecheck": "npx tsc --noEmit",
+    "release": "commit-and-tag-version",
+    "release:minor": "commit-and-tag-version --release-as minor",
+    "release:major": "commit-and-tag-version --release-as major",
+    "postrelease": "git push --follow-tags origin main && npm publish --access public"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "chokidar": "^4.0.3",
+    "fast-glob": "^3.3.3",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "@types/yargs": "^17.0.33",
+    "commit-and-tag-version": "^12.7.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "storybook": ">=8.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "storybook": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  }
+}