astro-xmdx 0.0.2

package/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Astro integration for Xmdx - high-performance MDX compiler.
+ * Main entry point - re-exports from src/index.ts
+ * @module astro-xmdx
+ */
+
+export { default } from './src/index.js';
+export * from './src/index.js';

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "astro-xmdx",
+  "version": "0.0.2",
+  "description": "Astro integration for xmdx - high-performance MDX compiler",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts",
+      "default": "./index.ts"
+    },
+    "./presets": {
+      "types": "./src/presets/index.ts",
+      "import": "./src/presets/index.ts",
+      "default": "./src/presets/index.ts"
+    },
+    "./vite-plugin": {
+      "types": "./src/vite-plugin.ts",
+      "import": "./src/vite-plugin.ts",
+      "default": "./src/vite-plugin.ts"
+    },
+    "./pipeline": {
+      "types": "./src/pipeline/index.ts",
+      "import": "./src/pipeline/index.ts",
+      "default": "./src/pipeline/index.ts"
+    },
+    "./transforms": {
+      "types": "./src/transforms/index.ts",
+      "import": "./src/transforms/index.ts",
+      "default": "./src/transforms/index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "mdx",
+    "markdown",
+    "xmdx",
+    "vite"
+  ],
+  "author": "jp-knj",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jp-knj/xmdx"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0",
+    "vite": ">=5.0.0"
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "glob": "^11.0.0",
+    "xmdx": "0.0.2",
+    "xmdx-napi": "0.0.2",
+    "parse5": "^7.1.2",
+    "remark-directive": "^3.0.0",
+    "remark-gfm": "^4.0.0",
+    "shiki": "^3.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": ">=0.21.0",
+    "magic-string": "^0.30.0",
+    "rollup": ">=4.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared constants for astro-xmdx
+ * @module constants
+ */
+
+/**
+ * Virtual module prefix for Vite module resolution.
+ * The null byte prefix ensures these are treated as virtual modules.
+ */
+export const VIRTUAL_MODULE_PREFIX = '\0xmdx:';
+
+/**
+ * File extension for compiled xmdx JSX output.
+ */
+export const OUTPUT_EXTENSION = '.xmdx.jsx';
+
+/**
+ * esbuild configuration for JSX transformation.
+ * Used to transform JSX syntax into function calls compatible with Astro's runtime.
+ */
+export const ESBUILD_JSX_CONFIG = {
+  loader: 'jsx' as const,
+  jsx: 'transform' as const,
+  jsxFactory: '_jsx',
+  jsxFragment: '_Fragment',
+  target: 'es2020' as const,
+  minify: false,
+} as const;
+
+/**
+ * Shiki syntax highlighting theme configuration.
+ * Uses CSS variables for theming compatibility with Astro.
+ */
+export const SHIKI_THEME = {
+  /** Theme name used by shiki */
+  name: 'astro-code',
+  /** CSS variable prefix for syntax highlighting colors */
+  variablePrefix: '--astro-code-',
+  /** CSS class name added to highlighted code blocks */
+  className: 'astro-code',
+} as const;
+
+/**
+ * Default glob patterns to ignore when scanning for markdown files.
+ */
+export const DEFAULT_IGNORE_PATTERNS = ['node_modules/**', 'dist/**'] as const;
+
+/**
+ * CSS @layer order declaration for Starlight.
+ * Injected as inline <style> in dev mode, Head.astro overlay in build.
+ */
+export const STARLIGHT_LAYER_ORDER = '@layer starlight.base, starlight.reset, starlight.core, starlight.content, starlight.components, starlight.utils;';

package/src/index.ts

@@ -0,0 +1,150 @@
+/**
+ * Astro integration for Xmdx - high-performance MDX compiler.
+ * @module astro-xmdx
+ */
+
+import type { AstroIntegration } from 'astro';
+import type { ComponentLibrary } from 'xmdx/registry';
+import { xmdxPlugin } from './vite-plugin.js';
+import { mergePresets, STARLIGHT_DEFAULT_ALLOW_IMPORTS, type PresetConfig } from './presets/index.js';
+import type { XmdxPlugin, MdxImportHandlingOptions } from './types.js';
+
+/**
+ * Options for the Xmdx integration.
+ */
+export interface XmdxOptions {
+  /**
+   * File filter function. Defaults to .md and .mdx files.
+   */
+  include?: (id: string) => boolean;
+
+  /**
+   * Component libraries to register.
+   */
+  libraries?: ComponentLibrary[];
+
+  /**
+   * Presets to apply. Presets are merged in order.
+   */
+  presets?: PresetConfig[];
+
+  /**
+   * Enable Starlight component injection.
+   */
+  starlightComponents?: boolean | {
+    enabled: boolean;
+    importSource?: string;
+  };
+
+  /**
+   * Enable ExpressiveCode block rewriting.
+   */
+  expressiveCode?: boolean | {
+    enabled: boolean;
+    componentName?: string;
+    importSource?: string;
+  };
+
+  /**
+   * Compiler configuration.
+   */
+  compiler?: {
+    jsx?: {
+      code_sample_components?: string[];
+    };
+  };
+
+  /**
+   * Xmdx plugins for transform hooks.
+   */
+  plugins?: XmdxPlugin[];
+
+  /**
+   * MDX import handling configuration.
+   * Controls which imports are allowed vs trigger fallback to @mdx-js/mdx.
+   */
+  mdx?: MdxImportHandlingOptions;
+}
+
+/**
+ * Astro integration for Xmdx.
+ *
+ * @example
+ * ```js
+ * // astro.config.mjs
+ * import { defineConfig } from 'astro/config';
+ * import xmdx from 'astro-xmdx';
+ *
+ * export default defineConfig({
+ *   integrations: [xmdx()],
+ * });
+ * ```
+ *
+ * @example
+ * ```js
+ * // With presets
+ * import xmdx from 'astro-xmdx';
+ * import { starlightPreset } from 'astro-xmdx/presets';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     xmdx({
+ *       presets: [starlightPreset()],
+ *     })
+ *   ],
+ * });
+ * ```
+ */
+export default function xmdx(options: XmdxOptions = {}): AstroIntegration {
+  // Handle presets if provided
+  let resolvedOptions = { ...options };
+
+  if (Array.isArray(options.presets) && options.presets.length > 0) {
+    const presetConfig = mergePresets(options.presets);
+
+    // Apply preset config (user options override preset defaults)
+    resolvedOptions = {
+      libraries: options.libraries ?? presetConfig.libraries,
+      starlightComponents: options.starlightComponents ?? presetConfig.starlightComponents,
+      expressiveCode: options.expressiveCode ?? presetConfig.expressiveCode,
+      mdx: options.mdx ?? presetConfig.mdx,
+      ...options,
+    };
+
+    // Remove presets from final options (not needed by vite plugin)
+    delete (resolvedOptions as Record<string, unknown>).presets;
+  }
+
+  // Auto-apply Starlight default allowImports when starlightComponents is enabled
+  // This ensures imports like @astrojs/starlight/components don't trigger fallback
+  const hasStarlightComponents = resolvedOptions.starlightComponents === true ||
+    (typeof resolvedOptions.starlightComponents === 'object' && resolvedOptions.starlightComponents.enabled);
+  const hasAllowImports = resolvedOptions.mdx?.allowImports && resolvedOptions.mdx.allowImports.length > 0;
+
+  if (hasStarlightComponents && !hasAllowImports) {
+    resolvedOptions.mdx = {
+      ...resolvedOptions.mdx,
+      allowImports: [...STARLIGHT_DEFAULT_ALLOW_IMPORTS],
+      ignoreCodeFences: resolvedOptions.mdx?.ignoreCodeFences ?? true,
+    };
+  }
+
+  return {
+    name: 'astro-xmdx',
+    hooks: {
+      'astro:config:setup': ({ updateConfig }) => {
+        updateConfig({
+          vite: {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            plugins: [xmdxPlugin(resolvedOptions) as any],
+          },
+        });
+      },
+    },
+  };
+}
+
+// Re-export presets for convenience
+export { starlightPreset, expressiveCodePreset, astroPreset, mergePresets } from './presets/index.js';
+export type { PresetConfig } from './presets/index.js';
+export type { XmdxPlugin, TransformContext, PluginHooks, MdxImportHandlingOptions } from './types.js';

package/src/pipeline/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Xmdx transform pipeline - public API
+ *
+ * This module provides tools for creating and composing transform pipelines.
+ * It can be used standalone (without Vite) for processing markdown/MDX files.
+ *
+ * @module pipeline
+ *
+ * @example
+ * // Standalone usage (without Vite)
+ * import { createPipeline, createContext } from 'astro-xmdx/pipeline';
+ * import { compile } from 'some-markdown-compiler';
+ *
+ * const pipeline = createPipeline({
+ *   afterParse: [myCustomTransform],
+ * });
+ *
+ * const compiled = compile(markdownSource);
+ * const ctx = createContext({
+ *   code: compiled.code,
+ *   source: markdownSource,
+ *   filename: '/path/to/file.md',
+ *   frontmatter: compiled.frontmatter,
+ *   headings: compiled.headings,
+ * });
+ *
+ * const result = await pipeline(ctx);
+ * console.log(result.code);
+ */
+
+// Pipe utilities for composing transforms
+export { pipe, when, tap } from './pipe.js';
+
+// Pipeline orchestrator for creating standard and custom pipelines
+export { createPipeline, createCustomPipeline, createContext } from './orchestrator.js';
+
+// Type exports
+export type { TransformContext, TransformConfig, Transform, PipelineOptions } from './types.js';

package/src/pipeline/orchestrator.test.ts

@@ -0,0 +1,324 @@
+import { describe, it, expect } from 'bun:test';
+import { createPipeline, createCustomPipeline, createContext } from './orchestrator.js';
+import type { TransformContext } from './types.js';
+
+describe('createContext', () => {
+  it('should create context with default values', () => {
+    const ctx = createContext();
+
+    expect(ctx.code).toBe('');
+    expect(ctx.source).toBe('');
+    expect(ctx.filename).toBe('');
+    expect(ctx.frontmatter).toEqual({});
+    expect(ctx.headings).toEqual([]);
+    expect(ctx.registry).toBeUndefined();
+    expect(ctx.config).toEqual({
+      expressiveCode: null,
+      starlightComponents: false,
+      shiki: null,
+    });
+  });
+
+  it('should override default values with provided values', () => {
+    const ctx = createContext({
+      code: '<h1>Hello</h1>',
+      source: '# Hello',
+      filename: '/path/to/file.md',
+      frontmatter: { title: 'Test' },
+      headings: [{ depth: 1, text: 'Hello', slug: 'hello' }],
+    });
+
+    expect(ctx.code).toBe('<h1>Hello</h1>');
+    expect(ctx.source).toBe('# Hello');
+    expect(ctx.filename).toBe('/path/to/file.md');
+    expect(ctx.frontmatter).toEqual({ title: 'Test' });
+    expect(ctx.headings).toEqual([{ depth: 1, text: 'Hello', slug: 'hello' }]);
+  });
+
+  it('should merge config with defaults', () => {
+    const ctx = createContext({
+      config: {
+        expressiveCode: { component: 'Code', moduleId: 'test' },
+        starlightComponents: false,
+        shiki: null,
+      },
+    });
+
+    expect(ctx.config.expressiveCode).toEqual({ component: 'Code', moduleId: 'test' });
+    expect(ctx.config.starlightComponents).toBe(false);
+    expect(ctx.config.shiki).toBeNull();
+  });
+
+  it('should preserve registry when provided', () => {
+    const mockRegistry = { lookup: () => null } as unknown as TransformContext['registry'];
+    const ctx = createContext({ registry: mockRegistry });
+
+    expect(ctx.registry).toBe(mockRegistry);
+  });
+});
+
+describe('createPipeline', () => {
+  it('should create pipeline with empty hooks', async () => {
+    const pipeline = createPipeline();
+    const ctx = createContext({
+      code: '<p>test</p>',
+      source: 'test',
+      filename: 'test.md',
+    });
+
+    const result = await pipeline(ctx);
+
+    // Pipeline should return context (transforms may or may not modify it)
+    expect(result).toBeDefined();
+    expect(result.code).toBeDefined();
+  });
+
+  it('should execute afterParse hooks first', async () => {
+    const order: string[] = [];
+    const afterParseHook = (ctx: TransformContext): TransformContext => {
+      order.push('afterParse');
+      return { ...ctx, code: ctx.code + ':afterParse' };
+    };
+
+    const pipeline = createPipeline({
+      afterParse: [afterParseHook],
+    });
+
+    const ctx = createContext({ code: 'start' });
+    const result = await pipeline(ctx);
+
+    expect(order).toEqual(['afterParse']);
+    expect(result.code).toContain('afterParse');
+  });
+
+  it('should execute hooks in correct order', async () => {
+    const order: string[] = [];
+
+    const afterParseHook = (ctx: TransformContext): TransformContext => {
+      order.push('afterParse');
+      return ctx;
+    };
+
+    const beforeInjectHook = (ctx: TransformContext): TransformContext => {
+      order.push('beforeInject');
+      return ctx;
+    };
+
+    const beforeOutputHook = (ctx: TransformContext): TransformContext => {
+      order.push('beforeOutput');
+      return ctx;
+    };
+
+    const pipeline = createPipeline({
+      afterParse: [afterParseHook],
+      beforeInject: [beforeInjectHook],
+      beforeOutput: [beforeOutputHook],
+    });
+
+    const ctx = createContext({ code: 'test' });
+    await pipeline(ctx);
+
+    // Verify hook order: afterParse -> (built-in transforms) -> beforeInject -> (built-in transforms) -> beforeOutput
+    expect(order.indexOf('afterParse')).toBeLessThan(order.indexOf('beforeInject'));
+    expect(order.indexOf('beforeInject')).toBeLessThan(order.indexOf('beforeOutput'));
+  });
+
+  it('should handle multiple hooks per phase', async () => {
+    const order: string[] = [];
+
+    const pipeline = createPipeline({
+      afterParse: [
+        (ctx: TransformContext) => { order.push('afterParse1'); return ctx; },
+        (ctx: TransformContext) => { order.push('afterParse2'); return ctx; },
+      ],
+      beforeOutput: [
+        (ctx: TransformContext) => { order.push('beforeOutput1'); return ctx; },
+        (ctx: TransformContext) => { order.push('beforeOutput2'); return ctx; },
+      ],
+    });
+
+    const ctx = createContext({ code: 'test' });
+    await pipeline(ctx);
+
+    // Hooks should run in order within each phase
+    expect(order.indexOf('afterParse1')).toBeLessThan(order.indexOf('afterParse2'));
+    expect(order.indexOf('beforeOutput1')).toBeLessThan(order.indexOf('beforeOutput2'));
+  });
+
+  it('should handle async hooks', async () => {
+    const asyncHook = async (ctx: TransformContext): Promise<TransformContext> => {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return { ...ctx, code: ctx.code + ':async' };
+    };
+
+    const pipeline = createPipeline({
+      afterParse: [asyncHook],
+    });
+
+    const ctx = createContext({ code: 'start' });
+    const result = await pipeline(ctx);
+
+    expect(result.code).toContain('async');
+  });
+
+  it('should pass context through all transforms', async () => {
+    const addMetadata = (ctx: TransformContext): TransformContext => ({
+      ...ctx,
+      frontmatter: { ...ctx.frontmatter, transformed: true },
+    });
+
+    const pipeline = createPipeline({
+      afterParse: [addMetadata],
+    });
+
+    const ctx = createContext({
+      code: 'test',
+      frontmatter: { title: 'Original' },
+    });
+    const result = await pipeline(ctx);
+
+    expect(result.frontmatter.title).toBe('Original');
+    expect(result.frontmatter.transformed).toBe(true);
+  });
+});
+
+describe('createCustomPipeline', () => {
+  it('should create pipeline with only specified transforms', async () => {
+    const transform1 = (ctx: TransformContext): TransformContext => ({ ...ctx, code: ctx.code + ':t1' });
+    const transform2 = (ctx: TransformContext): TransformContext => ({ ...ctx, code: ctx.code + ':t2' });
+
+    const pipeline = createCustomPipeline(transform1, transform2);
+    const ctx = createContext({ code: 'start' });
+    const result = await pipeline(ctx);
+
+    expect(result.code).toBe('start:t1:t2');
+  });
+
+  it('should not include any built-in transforms', async () => {
+    // Create a custom pipeline with only a simple transform
+    const simpleTransform = (ctx: TransformContext): TransformContext & { customOnly: boolean } => ({ ...ctx, customOnly: true });
+
+    const pipeline = createCustomPipeline(simpleTransform);
+    const ctx = createContext({ code: '<pre><code>test</code></pre>' });
+    const result = await pipeline(ctx);
+
+    // The code should not be modified by built-in transforms
+    expect(result.code).toBe('<pre><code>test</code></pre>');
+    expect((result as TransformContext & { customOnly?: boolean }).customOnly).toBe(true);
+  });
+
+  it('should compose async transforms', async () => {
+    const asyncTransform1 = async (ctx: TransformContext): Promise<TransformContext> => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      return { ...ctx, code: ctx.code + ':async1' };
+    };
+
+    const asyncTransform2 = async (ctx: TransformContext): Promise<TransformContext> => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      return { ...ctx, code: ctx.code + ':async2' };
+    };
+
+    const pipeline = createCustomPipeline(asyncTransform1, asyncTransform2);
+    const ctx = createContext({ code: 'start' });
+    const result = await pipeline(ctx);
+
+    expect(result.code).toBe('start:async1:async2');
+  });
+
+  it('should work with empty transforms', async () => {
+    const pipeline = createCustomPipeline();
+    const ctx = createContext({ code: 'unchanged' });
+    const result = await pipeline(ctx);
+
+    expect(result.code).toBe('unchanged');
+  });
+});
+
+describe('standalone usage', () => {
+  it('should work without Vite context', async () => {
+    // Simulate standalone usage: create context manually and run pipeline
+    const ctx = createContext({
+      code: `
+import { Fragment } from 'astro/jsx-runtime';
+export default function Content() {
+  return <Fragment><h1>Hello</h1><p>World</p></Fragment>;
+}`,
+      source: '# Hello\n\nWorld',
+      filename: '/standalone/test.md',
+      frontmatter: { title: 'Standalone Test' },
+      headings: [{ depth: 1, text: 'Hello', slug: 'hello' }],
+    });
+
+    const pipeline = createPipeline();
+    const result = await pipeline(ctx);
+
+    expect(result.code).toBeDefined();
+    expect(result.filename).toBe('/standalone/test.md');
+    expect(result.frontmatter.title).toBe('Standalone Test');
+  });
+
+  it('should allow custom transforms in standalone mode', async () => {
+    const addBanner = (ctx: TransformContext): TransformContext => ({
+      ...ctx,
+      code: `// Generated by custom pipeline\n${ctx.code}`,
+    });
+
+    const pipeline = createCustomPipeline(addBanner);
+
+    const ctx = createContext({
+      code: 'export default function() {}',
+      source: 'test',
+      filename: 'test.md',
+    });
+
+    const result = await pipeline(ctx);
+
+    expect(result.code).toStartWith('// Generated by custom pipeline');
+  });
+
+  it('should support composing multiple custom pipelines', async () => {
+    const pipeline1 = createCustomPipeline(
+      (ctx: TransformContext) => ({ ...ctx, code: ctx.code + ':p1' })
+    );
+
+    const pipeline2 = createCustomPipeline(
+      (ctx: TransformContext) => ({ ...ctx, code: ctx.code + ':p2' })
+    );
+
+    // Compose pipelines manually
+    const combinedPipeline = async (ctx: TransformContext): Promise<TransformContext> => {
+      const intermediate = await pipeline1(ctx);
+      return pipeline2(intermediate);
+    };
+
+    const ctx = createContext({ code: 'start' });
+    const result = await combinedPipeline(ctx);
+
+    expect(result.code).toBe('start:p1:p2');
+  });
+});
+
+describe('error handling', () => {
+  it('should propagate errors from transforms', async () => {
+    const failingTransform = (): TransformContext => {
+      throw new Error('Transform failed');
+    };
+
+    const pipeline = createCustomPipeline(failingTransform);
+    const ctx = createContext({ code: 'test' });
+
+    await expect(pipeline(ctx)).rejects.toThrow('Transform failed');
+  });
+
+  it('should propagate errors from async transforms', async () => {
+    const asyncFailingTransform = async (): Promise<TransformContext> => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      throw new Error('Async transform failed');
+    };
+
+    const pipeline = createCustomPipeline(asyncFailingTransform);
+    const ctx = createContext({ code: 'test' });
+
+    await expect(pipeline(ctx)).rejects.toThrow('Async transform failed');
+  });
+});