astro-xmdx 0.0.2

package/src/vite-plugin/mdx-wrapper.ts

@@ -0,0 +1,328 @@
+/**
+ * MDX wrapper module for Astro component integration.
+ * Wraps mdxjs-rs compiled output in Astro-compatible component format.
+ * @module vite-plugin/mdx-wrapper
+ */
+
+import type { Registry } from 'xmdx/registry';
+
+/**
+ * Options for wrapping MDX module output.
+ */
+export interface WrapMdxOptions {
+  /** Frontmatter extracted from the MDX file */
+  frontmatter: Record<string, unknown>;
+  /** Headings extracted from the MDX file */
+  headings: Array<{ depth: number; slug: string; text: string }>;
+  /** Component registry for import generation */
+  registry: Registry;
+}
+
+/**
+ * Wraps mdxjs-rs compiled JavaScript output in an Astro-compatible module.
+ *
+ * The mdxjs-rs output is a complete JavaScript module with an MDXContent function
+ * that accepts a `components` prop for runtime component resolution. This wrapper:
+ *
+ * 1. Imports the compiled MDX content via a virtual module
+ * 2. Generates imports for components used in the document
+ * 3. Creates an Astro component that injects components at render time
+ * 4. Exports frontmatter, getHeadings, and Content for Astro compatibility
+ *
+ * @param mdxCode - The compiled JavaScript code from mdxjs-rs
+ * @param options - Wrapper options including frontmatter, headings, and registry
+ * @param filename - The original MDX file path
+ * @returns Astro-compatible module code
+ *
+ * @example
+ * ```typescript
+ * const wrappedModule = wrapMdxModule(compiledCode, {
+ *   frontmatter: { title: 'Hello' },
+ *   headings: [{ depth: 1, slug: 'hello', text: 'Hello' }],
+ *   registry,
+ * }, 'page.mdx');
+ * ```
+ */
+export function wrapMdxModule(
+  mdxCode: string,
+  options: WrapMdxOptions,
+  filename: string
+): string {
+  const { frontmatter, headings, registry } = options;
+  const frontmatterJson = JSON.stringify(frontmatter);
+  const headingsJson = JSON.stringify(headings);
+
+  // Analyze the MDX code to find components that need to be injected
+  const usedComponents = detectUsedComponents(mdxCode, registry);
+
+  // Generate import statements for used components
+  const componentImports = generateComponentImports(usedComponents, registry);
+
+  // Generate the components object for injection
+  // Always include Fragment for MDX compatibility
+  const componentNames = usedComponents.map(c => c.name);
+  const allComponents = ['Fragment', ...componentNames];
+  const componentsObject = `{ ${allComponents.join(', ')}, ...(props?.components ?? {}) }`;
+
+  // The mdxjs-rs output needs to be normalized to work with our wrapper.
+  // It exports `default` as the MDXContent function.
+  // We need to handle both:
+  // 1. Direct function: `export default function MDXContent(props) { ... }`
+  // 2. Function reference: `function _createMdxContent(props) { ... } export default _createMdxContent;`
+  const normalizedMdxCode = normalizeMdxExport(mdxCode);
+
+  return `import { createComponent, renderJSX } from 'astro/runtime/server/index.js';
+import { Fragment } from 'astro/jsx-runtime';
+${componentImports}
+
+// MDX compiled content
+${normalizedMdxCode}
+
+// Astro exports
+export const frontmatter = ${frontmatterJson};
+export function getHeadings() { return ${headingsJson}; }
+export const file = ${JSON.stringify(filename)};
+export const url = undefined;
+
+// Wrap MDXContent in Astro component with component injection
+const XmdxContent = createComponent(
+  (result, props, _slots) =>
+    renderJSX(
+      result,
+      MDXContent({
+        ...(props ?? {}),
+        components: ${componentsObject},
+      })
+    ),
+  ${JSON.stringify(filename)}
+);
+
+export const Content = XmdxContent;
+export default XmdxContent;
+`;
+}
+
+/**
+ * Component usage information.
+ */
+interface UsedComponent {
+  name: string;
+  modulePath: string;
+  exportType: 'named' | 'default';
+}
+
+/**
+ * Extracts already-imported component names from the mdxjs-rs output.
+ * This prevents duplicate imports when we add our component injections.
+ *
+ * Only scans top-level import statements by processing lines at the start
+ * of the file, stopping when we hit actual code (function definitions, etc.).
+ * This avoids matching import statements inside code strings/samples.
+ */
+function extractExistingImports(code: string): Set<string> {
+  const imported = new Set<string>();
+  const lines = code.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines and comments at the top
+    if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) {
+      continue;
+    }
+
+    // Stop scanning when we hit non-import code
+    if (!trimmed.startsWith('import ') && !trimmed.startsWith('import{')) {
+      break;
+    }
+
+    // Process this import line
+    const importPattern = /import\s+([\s\S]*?)\s+from\s+['"][^'"]+['"]/;
+    const match = importPattern.exec(trimmed);
+    if (!match) continue;
+
+    if (/^import\s+type\s/.test(trimmed)) {
+      continue;
+    }
+
+    let clause = match[1]?.trim() ?? '';
+    if (clause.startsWith('type ')) {
+      clause = clause.slice('type '.length).trim();
+    }
+
+    // Default import: import Foo from 'module' or import Foo, { Bar } from 'module'
+    const defaultMatch = clause.match(/^([A-Za-z$_][\w$]*)\s*(?:,|$)/);
+    if (defaultMatch?.[1]) {
+      imported.add(defaultMatch[1]);
+    }
+
+    // Namespace import: import * as Foo from 'module'
+    const namespaceMatch = clause.match(/\*\s+as\s+([A-Za-z$_][\w$]*)/);
+    if (namespaceMatch?.[1]) {
+      imported.add(namespaceMatch[1]);
+    }
+
+    // Named imports: import { Foo, Bar as Baz } from 'module'
+    // Also handles: import Default, { Foo, Bar } from 'module'
+    const namedMatch = clause.match(/\{([^}]+)\}/);
+    if (namedMatch?.[1]) {
+      const parts = namedMatch[1].split(',');
+      for (const part of parts) {
+        const item = part.trim();
+        if (!item) continue;
+        const withoutType = item.replace(/^type\s+/, '');
+        const segments = withoutType.split(/\s+as\s+/);
+        const name = segments[1] ?? segments[0];
+        if (name) {
+          imported.add(name.trim());
+        }
+      }
+    }
+  }
+
+  return imported;
+}
+
+/**
+ * Extracts locally declared component names from the MDX module.
+ * This prevents injecting registry imports that would conflict with local declarations.
+ *
+ * Matches patterns like:
+ * - const Name = ...
+ * - let Name = ...
+ * - function Name(...
+ * - class Name ...
+ * - export const Name = ...
+ * - export function Name(...
+ * - export class Name ...
+ *
+ * Only matches PascalCase names (starting with uppercase) since those are component names.
+ */
+function extractLocalDeclarations(code: string): Set<string> {
+  const declarations = new Set<string>();
+
+  // Match: const/let/var NAME, function NAME, class NAME
+  // Also match export variants
+  const patterns = [
+    /(?:export\s+)?(?:const|let|var)\s+([A-Z][a-zA-Z0-9]*)\s*=/g,
+    /(?:export\s+)?function\s+([A-Z][a-zA-Z0-9]*)\s*\(/g,
+    /(?:export\s+)?class\s+([A-Z][a-zA-Z0-9]*)\s*[{<]/g,
+  ];
+
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(code)) !== null) {
+      if (match[1]) declarations.add(match[1]);
+    }
+  }
+
+  return declarations;
+}
+
+/**
+ * Detects which components from the registry are used in the MDX code.
+ * Looks for PascalCase JSX tags in the compiled output.
+ * Excludes components that are already imported or locally declared in the mdxjs-rs output.
+ */
+function detectUsedComponents(code: string, registry: Registry): UsedComponent[] {
+  const usedComponents: UsedComponent[] = [];
+  const seenNames = new Set<string>();
+
+  // Get components already imported in the mdxjs-rs output
+  const existingImports = extractExistingImports(code);
+  // Get locally declared components (const Foo = ..., function Foo, etc.)
+  const localDeclarations = extractLocalDeclarations(code);
+
+  // Match potential component references in JSX
+  // This includes both direct usage like <Tabs> and indirect like jsx(Tabs, ...)
+  const componentPattern = /\b([A-Z][a-zA-Z0-9]*)\b/g;
+  let match;
+
+  while ((match = componentPattern.exec(code)) !== null) {
+    const name = match[1]!;
+
+    // Skip common JSX/React internals and already seen components
+    if (seenNames.has(name)) continue;
+    if (['Fragment', 'Component', 'MDXContent', 'React', 'Props'].includes(name)) continue;
+
+    // Skip if already imported or locally declared in the mdxjs-rs output
+    if (existingImports.has(name) || localDeclarations.has(name)) continue;
+
+    // Check if this component is in the registry
+    const definition = registry.getComponent(name);
+    if (definition) {
+      seenNames.add(name);
+      usedComponents.push({
+        name: definition.name,
+        modulePath: definition.modulePath,
+        exportType: definition.exportType as 'named' | 'default',
+      });
+    }
+  }
+
+  return usedComponents;
+}
+
+/**
+ * Generates import statements for the used components.
+ * For default exports, uses the convention: ${modulePath}/${name}.astro
+ * to match the rest of the codebase (blocks-to-jsx, inject-components, directive-rewriter).
+ */
+function generateComponentImports(components: UsedComponent[], registry: Registry): string {
+  // Group components by module path for cleaner imports (named exports only)
+  const byModule = new Map<string, UsedComponent[]>();
+  const defaultExports: UsedComponent[] = [];
+
+  for (const component of components) {
+    if (component.exportType === 'default') {
+      // Default exports use individual imports with full path
+      defaultExports.push(component);
+    } else {
+      const existing = byModule.get(component.modulePath) ?? [];
+      existing.push(component);
+      byModule.set(component.modulePath, existing);
+    }
+  }
+
+  const imports: string[] = [];
+
+  // Generate named imports grouped by module
+  for (const [modulePath, moduleComponents] of byModule) {
+    const namedImports = moduleComponents.map(c => c.name);
+    if (namedImports.length > 0) {
+      imports.push(`import { ${namedImports.join(', ')} } from '${modulePath}';`);
+    }
+  }
+
+  // Generate individual default imports with full path convention
+  for (const comp of defaultExports) {
+    imports.push(`import ${comp.name} from '${comp.modulePath}/${comp.name}.astro';`);
+  }
+
+  return imports.join('\n');
+}
+
+/**
+ * Normalizes the mdxjs-rs export to ensure MDXContent is available.
+ * Handles both direct exports and function reference exports.
+ */
+function normalizeMdxExport(code: string): string {
+  // Remove the default export line(s) - we'll create our own wrapper
+  let normalized = code
+    // Remove: export default function MDXContent
+    .replace(/export\s+default\s+function\s+MDXContent/g, 'function MDXContent')
+    // Remove: export default MDXContent;
+    .replace(/export\s+default\s+MDXContent\s*;?/g, '')
+    // Remove: export { MDXContent as default };
+    .replace(/export\s*\{\s*MDXContent\s+as\s+default\s*\}\s*;?/g, '')
+    // Remove: export default _createMdxContent;
+    .replace(/export\s+default\s+_createMdxContent\s*;?/g, '');
+
+  // If there's a _createMdxContent function that was the default export,
+  // alias it to MDXContent for consistency
+  if (normalized.includes('function _createMdxContent') && !normalized.includes('function MDXContent')) {
+    normalized += '\nconst MDXContent = _createMdxContent;';
+  }
+
+  return normalized;
+}

package/src/vite-plugin/normalize-config.test.ts

@@ -0,0 +1,78 @@
+import { describe, test, expect } from 'bun:test';
+import { normalizeStarlightComponents } from './normalize-config.js';
+
+describe('normalizeStarlightComponents', () => {
+  test('returns true for boolean true input', () => {
+    const result = normalizeStarlightComponents(true);
+    expect(result).toBe(true);
+  });
+
+  test('returns false for boolean false input', () => {
+    const result = normalizeStarlightComponents(false);
+    expect(result).toBe(false);
+  });
+
+  test('returns false when enabled is explicitly false', () => {
+    const result = normalizeStarlightComponents({ enabled: false });
+    expect(result).toBe(false);
+  });
+
+  test('returns false when enabled is false with other properties', () => {
+    const result = normalizeStarlightComponents({
+      enabled: false,
+      components: ['Aside', 'Tabs'],
+      module: '@custom/module',
+    });
+    expect(result).toBe(false);
+  });
+
+  test('strips enabled property and preserves components when enabled is true', () => {
+    const result = normalizeStarlightComponents({
+      enabled: true,
+      components: ['Aside', 'Tabs'],
+    });
+    expect(result).toEqual({ components: ['Aside', 'Tabs'], module: undefined });
+  });
+
+  test('strips enabled property and preserves module', () => {
+    const result = normalizeStarlightComponents({
+      enabled: true,
+      module: '@custom/starlight/components',
+    });
+    expect(result).toEqual({ components: undefined, module: '@custom/starlight/components' });
+  });
+
+  test('preserves both components and module', () => {
+    const result = normalizeStarlightComponents({
+      components: ['Aside', 'Card'],
+      module: '@astrojs/starlight/components',
+    });
+    expect(result).toEqual({
+      components: ['Aside', 'Card'],
+      module: '@astrojs/starlight/components',
+    });
+  });
+
+  test('handles object without enabled property', () => {
+    const result = normalizeStarlightComponents({
+      components: ['Aside'],
+    });
+    expect(result).toEqual({ components: ['Aside'], module: undefined });
+  });
+
+  test('handles empty object', () => {
+    const result = normalizeStarlightComponents({});
+    expect(result).toEqual({ components: undefined, module: undefined });
+  });
+
+  test('handles null input by returning false', () => {
+    // Cast to expected type since null is a valid falsy value
+    const result = normalizeStarlightComponents(null as unknown as boolean);
+    expect(result).toBe(false);
+  });
+
+  test('handles undefined input by returning false', () => {
+    const result = normalizeStarlightComponents(undefined as unknown as boolean);
+    expect(result).toBe(false);
+  });
+});

package/src/vite-plugin/normalize-config.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration normalization utilities for Xmdx Vite plugin
+ * @module vite-plugin/normalize-config
+ */
+
+/**
+ * Normalized starlightComponents configuration.
+ * Strips the `enabled` property which is only used for initial boolean check.
+ */
+export type NormalizedStarlightComponents = boolean | { components?: string[]; module?: string };
+
+/**
+ * Normalizes starlightComponents configuration from plugin options.
+ * Converts `{ enabled?: boolean; components?: string[]; module?: string }` to `boolean | { components?; module? }`.
+ *
+ * @param value - The raw starlightComponents option value
+ * @returns Normalized configuration suitable for TransformContext
+ */
+export function normalizeStarlightComponents(
+  value: boolean | { enabled?: boolean; components?: string[]; module?: string }
+): NormalizedStarlightComponents {
+  if (typeof value === 'object' && value !== null) {
+    if (value.enabled === false) {
+      return false;
+    }
+    return { components: value.components, module: value.module };
+  }
+  return Boolean(value);
+}

package/src/vite-plugin/shiki-highlighter.ts

@@ -0,0 +1,46 @@
+/**
+ * Shiki highlighter creation utilities
+ * @module vite-plugin/shiki-highlighter
+ */
+
+import { codeToHtml, createCssVariablesTheme } from 'shiki';
+import { SHIKI_THEME } from '../constants.js';
+import type { ShikiHighlighter } from '../transforms/shiki.js';
+
+// Re-export for convenience
+export type { ShikiHighlighter } from '../transforms/shiki.js';
+
+/**
+ * Creates a Shiki highlighter with CSS variables theme.
+ * The highlighter is configured to use Xmdx's CSS variable theme for styling.
+ *
+ * @returns A function that highlights code and returns HTML
+ */
+export async function createShikiHighlighter(): Promise<ShikiHighlighter> {
+  const theme = createCssVariablesTheme({
+    name: SHIKI_THEME.name,
+    variablePrefix: SHIKI_THEME.variablePrefix,
+  });
+  const cache = new Map<string, { lang: string }>();
+
+  return async (code: string, lang?: string): Promise<string> => {
+    const key = `${lang || 'text'}`;
+    let cached = cache.get(key);
+    if (!cached) {
+      cached = { lang: lang || 'text' };
+      cache.set(key, cached);
+    }
+    const html = await codeToHtml(code, {
+      lang: cached.lang,
+      theme,
+    });
+    return html.replace(/<pre class="([^"]*)"/, (_match, classes: string) => {
+      const normalized = classes
+        .split(/\s+/)
+        .filter((value) => value && value !== 'shiki')
+        .join(' ');
+      const next = normalized ? `${SHIKI_THEME.className} ${normalized}` : SHIKI_THEME.className;
+      return `<pre class="${next}"`;
+    });
+  };
+}

package/src/vite-plugin/shiki-manager.test.ts

@@ -0,0 +1,175 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from 'bun:test';
+import { ShikiManager } from './shiki-manager.js';
+
+// Mock the shiki-highlighter module
+const mockHighlighter = mock(async (code: string, lang?: string) => {
+  return `<pre class="shiki"><code class="language-${lang || 'text'}">${code}</code></pre>`;
+});
+
+let createShikiHighlighterMock: ReturnType<typeof mock>;
+
+beforeEach(() => {
+  createShikiHighlighterMock = mock(() => Promise.resolve(mockHighlighter));
+  mock.module('./shiki-highlighter.js', () => ({
+    createShikiHighlighter: createShikiHighlighterMock,
+  }));
+});
+
+afterEach(() => {
+  mock.restore();
+});
+
+describe('ShikiManager', () => {
+  describe('constructor', () => {
+    test('creates manager with enabled=true', () => {
+      const manager = new ShikiManager(true);
+      expect(manager).toBeInstanceOf(ShikiManager);
+    });
+
+    test('creates manager with enabled=false', () => {
+      const manager = new ShikiManager(false);
+      expect(manager).toBeInstanceOf(ShikiManager);
+    });
+  });
+
+  describe('getFor', () => {
+    test('returns null when disabled', async () => {
+      const manager = new ShikiManager(false);
+      const result = await manager.getFor('<pre><code>const x = 1;</code></pre>');
+      expect(result).toBeNull();
+    });
+
+    test('returns null when code has no <pre> tags', async () => {
+      const manager = new ShikiManager(true);
+      const result = await manager.getFor('<div>No code blocks here</div>');
+      expect(result).toBeNull();
+    });
+
+    test('returns highlighter when enabled and code has <pre>', async () => {
+      const manager = new ShikiManager(true);
+      const result = await manager.getFor('<pre><code>const x = 1;</code></pre>');
+      expect(result).not.toBeNull();
+      expect(typeof result).toBe('function');
+    });
+
+    test('initializes highlighter lazily on first call', async () => {
+      const manager = new ShikiManager(true);
+
+      // First call with code that has <pre>
+      const result1 = await manager.getFor('<pre><code>first</code></pre>');
+      expect(result1).not.toBeNull();
+
+      // Second call should return same instance
+      const result2 = await manager.getFor('<pre><code>second</code></pre>');
+      expect(result2).toBe(result1);
+    });
+
+    test('handles highlighter initialization failure gracefully', async () => {
+      // Create a manager where initialization will fail
+      mock.module('./shiki-highlighter.js', () => ({
+        createShikiHighlighter: () => Promise.reject(new Error('Shiki init failed')),
+      }));
+
+      const manager = new ShikiManager(true);
+      const result = await manager.getFor('<pre><code>code</code></pre>');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('init', () => {
+    test('returns null when disabled', async () => {
+      const manager = new ShikiManager(false);
+      const result = await manager.init();
+      expect(result).toBeNull();
+    });
+
+    test('returns highlighter when enabled', async () => {
+      const manager = new ShikiManager(true);
+      const result = await manager.init();
+      expect(result).not.toBeNull();
+      expect(typeof result).toBe('function');
+    });
+
+    test('initializes only once on multiple calls', async () => {
+      const manager = new ShikiManager(true);
+
+      const result1 = await manager.init();
+      const result2 = await manager.init();
+
+      expect(result1).toBe(result2);
+    });
+
+    test('handles initialization failure gracefully', async () => {
+      mock.module('./shiki-highlighter.js', () => ({
+        createShikiHighlighter: () => Promise.reject(new Error('Init failed')),
+      }));
+
+      const manager = new ShikiManager(true);
+      const result = await manager.init();
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('forCode', () => {
+    test('returns null when disabled', () => {
+      const manager = new ShikiManager(false);
+      const resolved = mockHighlighter as unknown as Awaited<ReturnType<typeof mockHighlighter>>;
+      const result = manager.forCode('<pre><code>code</code></pre>', resolved);
+      expect(result).toBeNull();
+    });
+
+    test('returns null when resolved is null', () => {
+      const manager = new ShikiManager(true);
+      const result = manager.forCode('<pre><code>code</code></pre>', null);
+      expect(result).toBeNull();
+    });
+
+    test('returns null when code has no <pre> tags', () => {
+      const manager = new ShikiManager(true);
+      const resolved = mockHighlighter as unknown as Awaited<ReturnType<typeof mockHighlighter>>;
+      const result = manager.forCode('<div>no pre</div>', resolved);
+      expect(result).toBeNull();
+    });
+
+    test('returns resolved highlighter when all conditions met', () => {
+      const manager = new ShikiManager(true);
+      const resolved = mockHighlighter as unknown as Awaited<ReturnType<typeof mockHighlighter>>;
+      const result = manager.forCode('<pre><code>code</code></pre>', resolved);
+      expect(result).toBe(resolved);
+    });
+  });
+
+  describe('hasCodeBlocks (static)', () => {
+    test('returns true for code with <pre>', () => {
+      expect(ShikiManager.hasCodeBlocks('<pre><code>code</code></pre>')).toBe(true);
+    });
+
+    test('returns true for code with <pre and space', () => {
+      expect(ShikiManager.hasCodeBlocks('<pre class="foo"><code>code</code></pre>')).toBe(true);
+    });
+
+    test('returns true for code with <pre>', () => {
+      expect(ShikiManager.hasCodeBlocks('<pre>')).toBe(true);
+    });
+
+    test('returns false for code without <pre', () => {
+      expect(ShikiManager.hasCodeBlocks('<div>no pre here</div>')).toBe(false);
+    });
+
+    test('returns false for empty string', () => {
+      expect(ShikiManager.hasCodeBlocks('')).toBe(false);
+    });
+
+    test('returns false for text containing "pre" without tag', () => {
+      expect(ShikiManager.hasCodeBlocks('This is a preview of the content')).toBe(false);
+    });
+
+    test('returns true for pre tag at start of string', () => {
+      expect(ShikiManager.hasCodeBlocks('<pre>code</pre>')).toBe(true);
+    });
+
+    test('returns true for pre tag with attributes', () => {
+      expect(ShikiManager.hasCodeBlocks('<pre data-language="js"><code>code</code></pre>')).toBe(true);
+    });
+  });
+});