@cloudraker/reki 2.6.1 → 2.7.1

package/scripts/extract-demo-examples.ts

@@ -0,0 +1,323 @@
+#!/usr/bin/env npx tsx
+/**
+ * Extract Demo Examples for AI/Agent Consumption
+ *
+ * This script parses *Demo.tsx files in `src/demos/` and extracts usable code
+ * examples for the component registry and the Storybook story generator. Demo
+ * files contain clean, production-ready examples suitable for AI consumption.
+ *
+ * Run: pnpm codegen:demos
+ * Output: .cache/demo-metadata.json
+ *   (consumed by scripts/component-registry and scripts/generate-stories)
+ *
+ * Demo file naming convention:
+ *   {Component}Demo.tsx -> exports functions like {Component}{Variant}Demo
+ *   e.g., ButtonDemo.tsx -> ButtonBasicDemo, ButtonPrimaryDemo, etc.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  mkdirSync,
+  statSync,
+} from "node:fs";
+import { dirname, join, basename, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as ts from "typescript";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const demosDir = join(__dirname, "../src/demos");
+const outputDir = join(__dirname, "../.cache");
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface ExtractedDemo {
+  /** Function name (e.g., "ButtonPrimaryDemo") */
+  name: string;
+  /** The JSX code extracted from the return statement */
+  code: string;
+  /** Description extracted from JSDoc if present */
+  description?: string;
+}
+
+interface ComponentDemos {
+  /** Component name (e.g., "Button") */
+  componentName: string;
+  /** Source file name (e.g., "ButtonDemo.tsx") */
+  sourceFile: string;
+  /**
+   * Path relative to src/demos without extension, posix-style
+   * (e.g. "ButtonDemo" or "Chart/ChartDemo"). Used by the story generator to
+   * resolve the demo module import.
+   */
+  relativePath: string;
+  /** Extracted demo examples */
+  demos: ExtractedDemo[];
+}
+
+export interface DemoMetadata {
+  /** ISO timestamp of generation */
+  generatedAt: string;
+  /** Version for cache invalidation */
+  version: string;
+  /** Map of component name to its demos */
+  components: Record<string, ComponentDemos>;
+}
+
+// =============================================================================
+// AST Helpers
+// =============================================================================
+
+function getNodeText(node: ts.Node, sourceFile: ts.SourceFile): string {
+  return node.getText(sourceFile);
+}
+
+/**
+ * Extract JSDoc description from a function declaration
+ */
+function extractJSDocDescription(
+  node: ts.FunctionDeclaration,
+  sourceFile: ts.SourceFile,
+): string | undefined {
+  const fullText = sourceFile.getFullText();
+  const nodeStart = node.getFullStart();
+
+  // Look for JSDoc comment before the function
+  const textBefore = fullText.slice(0, nodeStart);
+  const jsdocMatch = textBefore.match(/\/\*\*\s*\n([^]*?)\*\/\s*$/);
+
+  if (jsdocMatch) {
+    const jsdocContent = jsdocMatch[1];
+    const lines = jsdocContent
+      .split("\n")
+      .map((line) => line.replace(/^\s*\*\s?/, "").trim())
+      .filter((line) => line.length > 0 && !line.startsWith("@"));
+
+    if (lines.length > 0) {
+      return lines.join(" ");
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Clean up extracted JSX code for readability
+ */
+function cleanupJSX(jsx: string): string {
+  jsx = jsx.trim();
+
+  // Remove wrapping parentheses (common in return statements)
+  if (jsx.startsWith("(") && jsx.endsWith(")")) {
+    jsx = jsx.slice(1, -1).trim();
+  }
+
+  return jsx;
+}
+
+/**
+ * Extract the return JSX from a function body
+ */
+function extractReturnJSX(
+  body: ts.Block,
+  sourceFile: ts.SourceFile,
+): string | null {
+  let returnJSX: string | null = null;
+
+  ts.forEachChild(body, (child) => {
+    if (ts.isReturnStatement(child) && child.expression) {
+      returnJSX = cleanupJSX(getNodeText(child.expression, sourceFile));
+    }
+  });
+
+  return returnJSX;
+}
+
+/**
+ * Extract the return JSX from an arrow function
+ */
+function extractArrowFunctionJSX(
+  node: ts.ArrowFunction,
+  sourceFile: ts.SourceFile,
+): string | null {
+  // Block body: () => { return <JSX /> }
+  if (ts.isBlock(node.body)) {
+    return extractReturnJSX(node.body, sourceFile);
+  }
+
+  // Expression body: () => <JSX />
+  return cleanupJSX(getNodeText(node.body, sourceFile));
+}
+
+// =============================================================================
+// Demo File Parser
+// =============================================================================
+
+/**
+ * Parse a demo file and extract all exported demo functions
+ */
+function parseDemoFile(filePath: string): ComponentDemos | null {
+  const relativePath = filePath
+    .slice(demosDir.length + 1)
+    .replace(/\.tsx$/, "")
+    .split(sep)
+    .join("/");
+  const content = readFileSync(filePath, "utf-8");
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    content,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+
+  // Extract component name from file path (e.g., ButtonDemo.tsx -> Button)
+  const fileName = basename(filePath, ".tsx");
+  const componentMatch = fileName.match(/^(.+)Demo$/);
+  if (!componentMatch) {
+    console.warn(`Skipping ${fileName}: doesn't match *Demo.tsx pattern`);
+    return null;
+  }
+
+  const componentName = componentMatch[1];
+  const demos: ExtractedDemo[] = [];
+
+  // Find all exported function declarations
+  ts.forEachChild(sourceFile, (node) => {
+    // Handle: export function FooDemo() { ... }
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) &&
+      node.name &&
+      node.body
+    ) {
+      const funcName = node.name.text;
+
+      // Only include functions that end with "Demo"
+      if (!funcName.endsWith("Demo")) {
+        return;
+      }
+
+      const jsx = extractReturnJSX(node.body, sourceFile);
+      if (jsx) {
+        demos.push({
+          name: funcName,
+          code: jsx,
+          description: extractJSDocDescription(node, sourceFile),
+        });
+      }
+    }
+
+    // Handle: export const FooDemo = () => { ... }
+    if (
+      ts.isVariableStatement(node) &&
+      node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      for (const decl of node.declarationList.declarations) {
+        if (
+          ts.isIdentifier(decl.name) &&
+          decl.initializer &&
+          ts.isArrowFunction(decl.initializer)
+        ) {
+          const funcName = decl.name.text;
+
+          // Only include functions that end with "Demo"
+          if (!funcName.endsWith("Demo")) {
+            continue;
+          }
+
+          const jsx = extractArrowFunctionJSX(decl.initializer, sourceFile);
+          if (jsx) {
+            demos.push({
+              name: funcName,
+              code: jsx,
+            });
+          }
+        }
+      }
+    }
+  });
+
+  if (demos.length === 0) {
+    console.warn(`No demos found in ${fileName}`);
+    return null;
+  }
+
+  return {
+    componentName,
+    sourceFile: basename(filePath),
+    relativePath,
+    demos,
+  };
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+/**
+ * Recursively find all *Demo.tsx files in a directory
+ */
+function findDemoFiles(dir: string, baseDir: string = dir): string[] {
+  const entries = readdirSync(dir);
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.startsWith("_")) continue;
+
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      files.push(...findDemoFiles(fullPath, baseDir));
+    } else if (entry.endsWith("Demo.tsx")) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function main() {
+  console.log("Extracting demo examples from src/demos...\n");
+
+  // Find all demo files recursively
+  const files = findDemoFiles(demosDir);
+
+  console.log(`Found ${files.length} demo files\n`);
+
+  const metadata: DemoMetadata = {
+    generatedAt: new Date().toISOString(),
+    version: "1.0.0",
+    components: {},
+  };
+
+  let totalDemos = 0;
+
+  for (const filePath of files) {
+    const result = parseDemoFile(filePath);
+
+    if (result) {
+      metadata.components[result.componentName] = result;
+      totalDemos += result.demos.length;
+      console.log(
+        `  ${result.componentName}: ${result.demos.length} demos extracted`,
+      );
+    }
+  }
+
+  // Ensure output directory exists
+  mkdirSync(outputDir, { recursive: true });
+
+  // Write metadata file
+  const outputPath = join(outputDir, "demo-metadata.json");
+  writeFileSync(outputPath, JSON.stringify(metadata, null, 2));
+
+  console.log(`\n✓ Extracted ${totalDemos} demos from ${files.length} files`);
+  console.log(`✓ Wrote ${outputPath}`);
+}
+
+main();

package/scripts/generate-stories.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env npx tsx
+/**
+ * Generate Storybook stories from demo metadata.
+ *
+ * Reads `.cache/demo-metadata.json` (produced by `extract-demo-examples.ts`)
+ * and emits one colocated `<name>.stories.tsx` next to every demo file under
+ * `src/demos/`. Each exported `*Demo` function becomes a single story that
+ * renders the demo. Demos remain the single source of truth — never edit the
+ * generated stories by hand; edit the demo and re-run `pnpm codegen:stories`.
+ *
+ * Run: pnpm codegen:stories
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  readdirSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const demosDir = join(__dirname, "../src/demos");
+const indexPath = join(__dirname, "../src/index.ts");
+const metadataPath = join(__dirname, "../.cache/demo-metadata.json");
+
+interface ExtractedDemo {
+  name: string;
+  code: string;
+  description?: string;
+}
+interface ComponentDemos {
+  componentName: string;
+  sourceFile: string;
+  relativePath: string;
+  demos: ExtractedDemo[];
+}
+interface DemoMetadata {
+  generatedAt: string;
+  version: string;
+  components: Record<string, ComponentDemos>;
+}
+
+/**
+ * Collect the value (non-type) identifiers re-exported from the package
+ * barrel, so we only wire `component` + autodocs prop tables for demos whose
+ * component is actually exported.
+ */
+function loadExportedSymbols(): Set<string> {
+  const src = readFileSync(indexPath, "utf-8");
+  const symbols = new Set<string>();
+  const blockRe = /export\s*\{([^}]*)\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = blockRe.exec(src))) {
+    for (const raw of m[1].split(",")) {
+      const part = raw.trim();
+      if (!part || part.startsWith("type ")) continue;
+      // Handle `Foo as Bar` -> exported name is the alias.
+      const name = part.includes(" as ")
+        ? part.split(" as ")[1].trim()
+        : part;
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) symbols.add(name);
+    }
+  }
+  return symbols;
+}
+
+/**
+ * Components exported as a compound "parts" namespace (e.g. `Toast.Provider`,
+ * `Toast.Root`) rather than a single renderable component. `satisfies
+ * Meta<typeof X>` rejects these, so we generate them render-only (no autodocs
+ * `component`, hence no prop table).
+ */
+const COMPOUND_NAMESPACE_EXPORTS = new Set<string>([
+  "Toast",
+  "CommandPalette",
+]);
+
+/** Turn a demo function name into a readable, unique story label/identifier. */
+function storyLabel(demoName: string, componentName: string): string {
+  let base = demoName.replace(/Demo$/, "");
+  if (base.startsWith(componentName)) base = base.slice(componentName.length);
+  if (!base) base = "Default";
+  return base;
+}
+
+/** Split a PascalCase identifier into spaced words for the sidebar name. */
+function humanize(label: string): string {
+  return (
+    label
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+      .trim() || label
+  );
+}
+
+function escapeForTemplate(text: string): string {
+  return text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function generateStoryFile(
+  comp: ComponentDemos,
+  exported: Set<string>,
+): string {
+  const { componentName, relativePath, demos } = comp;
+  const demoModule = `./${basename(relativePath)}`;
+  const hasComponent =
+    exported.has(componentName) &&
+    !COMPOUND_NAMESPACE_EXPORTS.has(componentName);
+
+  const lines: string[] = [];
+  lines.push(
+    "// AUTO-GENERATED by scripts/generate-stories.ts — do not edit.",
+    `// Source of truth: src/demos/${relativePath}.tsx`,
+    "// Edit the demo, then run \`pnpm codegen:stories\`.",
+    'import type { Meta, StoryObj } from "@storybook/react-vite";',
+    `import * as demos from "${demoModule}";`,
+  );
+  if (hasComponent) {
+    lines.push(`import { ${componentName} } from "@cloudraker/reki";`);
+  }
+  lines.push("");
+
+  // Explicit `: Meta` annotation (not `satisfies Meta<typeof X>`): keeps the
+  // exported `meta` type portable so compound components with attached
+  // subcomponents (e.g. `Autocomplete.Item`) don't leak private names into the
+  // emitted declarations, while still wiring `component` for autodocs.
+  lines.push("const meta: Meta = {", `  title: "Components/${componentName}",`);
+  if (hasComponent) lines.push(`  component: ${componentName},`);
+  lines.push('  tags: ["autodocs"],', "};");
+  // Plain `StoryObj` (not bound to `typeof meta`) so render-only stories don't
+  // trip the "args required" rule for components with required props.
+  lines.push("", "export default meta;", "type Story = StoryObj;", "");
+
+  const usedIdents = new Set<string>();
+  for (const demo of demos) {
+    let ident = storyLabel(demo.name, componentName);
+    // Ensure a valid, unique export identifier.
+    if (!/^[A-Za-z_$]/.test(ident)) ident = `Story${ident}`;
+    let unique = ident;
+    let n = 2;
+    while (usedIdents.has(unique)) unique = `${ident}${n++}`;
+    usedIdents.add(unique);
+
+    const name = humanize(storyLabel(demo.name, componentName));
+    lines.push(`export const ${unique}: Story = {`);
+    lines.push(`  name: "${escapeForTemplate(name)}",`);
+    lines.push(`  render: () => <demos.${demo.name} />,`);
+    if (demo.description) {
+      lines.push("  parameters: {");
+      lines.push("    docs: {");
+      lines.push(
+        `      description: { story: "${escapeForTemplate(demo.description)}" },`,
+      );
+      lines.push("    },");
+      lines.push("  },");
+    }
+    lines.push("};", "");
+  }
+
+  return lines.join("\n");
+}
+
+/** Remove previously generated story files so deletions/renames don't linger. */
+function cleanExistingStories(dir: string): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      cleanExistingStories(full);
+    } else if (entry.name.endsWith(".stories.tsx")) {
+      unlinkSync(full);
+    }
+  }
+}
+
+function main() {
+  if (!existsSync(metadataPath)) {
+    console.error(
+      `demo-metadata.json not found at ${metadataPath}. Run 'pnpm codegen:demos' first.`,
+    );
+    process.exit(1);
+  }
+
+  const metadata: DemoMetadata = JSON.parse(readFileSync(metadataPath, "utf-8"));
+  const exported = loadExportedSymbols();
+
+  cleanExistingStories(demosDir);
+
+  let count = 0;
+  let withComponent = 0;
+  for (const comp of Object.values(metadata.components)) {
+    const outPath = join(demosDir, `${comp.relativePath}.stories.tsx`);
+    writeFileSync(outPath, generateStoryFile(comp, exported));
+    count++;
+    if (exported.has(comp.componentName)) withComponent++;
+  }
+
+  console.log(
+    `✓ Generated ${count} story files (${withComponent} with autodocs component, ${count - withComponent} render-only).`,
+  );
+}
+
+main();