astro-xmdx 0.0.2

package/src/plugins.test.ts

@@ -0,0 +1,274 @@
+/**
+ * @file Tests for plugin system functionality
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { pipe, when } from './pipeline/pipe.js';
+import type { TransformContext, TransformConfig } from './types.js';
+
+interface TestContext {
+  code: string;
+  config?: { enabled: boolean };
+  source?: string;
+  filename?: string;
+  frontmatter?: Record<string, unknown>;
+  headings?: Array<{ text: string; depth: number }>;
+}
+
+interface PluginLike {
+  name: string;
+  enforce?: 'pre' | 'post';
+  afterParse?: (ctx: TestContext) => TestContext;
+  beforeOutput?: (ctx: TestContext) => TestContext;
+}
+
+/**
+ * Since collectHooks is not exported from index.js, we test the plugin behavior
+ * through the pipeline composition patterns that the plugin system uses.
+ */
+
+describe('plugin hook patterns', () => {
+  describe('hook collection and ordering', () => {
+    test('hooks execute in order', async () => {
+      const order: string[] = [];
+
+      const hooks = [
+        (ctx: TestContext) => {
+          order.push('first');
+          return ctx;
+        },
+        (ctx: TestContext) => {
+          order.push('second');
+          return ctx;
+        },
+        (ctx: TestContext) => {
+          order.push('third');
+          return ctx;
+        },
+      ];
+
+      const pipeline = pipe(...hooks);
+      await pipeline({ code: 'test' });
+
+      expect(order).toEqual(['first', 'second', 'third']);
+    });
+
+    test('async hooks execute in sequence', async () => {
+      const order: string[] = [];
+
+      const hooks = [
+        async (ctx: TestContext) => {
+          await new Promise((r) => setTimeout(r, 10));
+          order.push('first');
+          return ctx;
+        },
+        async (ctx: TestContext) => {
+          await new Promise((r) => setTimeout(r, 5));
+          order.push('second');
+          return ctx;
+        },
+        (ctx: TestContext) => {
+          order.push('third');
+          return ctx;
+        },
+      ];
+
+      const pipeline = pipe(...hooks);
+      await pipeline({ code: 'test' });
+
+      expect(order).toEqual(['first', 'second', 'third']);
+    });
+
+    test('hooks can modify context', async () => {
+      const hooks = [
+        (ctx: TestContext) => ({ ...ctx, code: ctx.code + ' modified1' }),
+        (ctx: TestContext) => ({ ...ctx, code: ctx.code + ' modified2' }),
+      ];
+
+      const pipeline = pipe(...hooks);
+      const result = await pipeline({ code: 'original' });
+
+      expect(result.code).toBe('original modified1 modified2');
+    });
+  });
+
+  describe('preprocess hook pattern', () => {
+    test('preprocess transforms source before parsing', () => {
+      const preprocessors = [
+        (source: string, _filename: string) => source.replace(/WARNING/g, 'CAUTION'),
+        (source: string, _filename: string) => source.replace(/NOTE/g, 'TIP'),
+      ];
+
+      let source = 'This is a WARNING and a NOTE';
+      for (const preprocess of preprocessors) {
+        source = preprocess(source, '/test.md');
+      }
+
+      expect(source).toBe('This is a CAUTION and a TIP');
+    });
+
+    test('preprocess receives filename', () => {
+      const receivedFilenames: string[] = [];
+      const preprocessors = [
+        (source: string, filename: string) => {
+          receivedFilenames.push(filename);
+          return source;
+        },
+      ];
+
+      let source = 'test';
+      for (const preprocess of preprocessors) {
+        source = preprocess(source, '/path/to/file.md');
+      }
+
+      expect(receivedFilenames).toEqual(['/path/to/file.md']);
+    });
+  });
+
+  describe('conditional transforms with hooks', () => {
+    test('hooks can be combined with when()', async () => {
+      const userHook = (ctx: TestContext) => ({ ...ctx, code: ctx.code + ' [user]' });
+      const conditionalTransform = when<TestContext>(
+        (ctx) => ctx.config?.enabled ?? false,
+        (ctx) => ({ ...ctx, code: ctx.code + ' [built-in]' })
+      );
+
+      const pipeline = pipe(userHook, conditionalTransform);
+
+      const result1 = await pipeline({
+        code: 'start',
+        config: { enabled: true },
+      });
+      expect(result1.code).toBe('start [user] [built-in]');
+
+      const result2 = await pipeline({
+        code: 'start',
+        config: { enabled: false },
+      });
+      expect(result2.code).toBe('start [user]');
+    });
+  });
+
+  describe('plugin enforce ordering simulation', () => {
+    test('pre plugins run before normal plugins', async () => {
+      const plugins: PluginLike[] = [
+        { name: 'normal1', enforce: undefined, afterParse: (ctx) => ({ ...ctx, code: ctx.code + ' normal1' }) },
+        { name: 'pre1', enforce: 'pre', afterParse: (ctx) => ({ ...ctx, code: ctx.code + ' pre1' }) },
+        { name: 'post1', enforce: 'post', afterParse: (ctx) => ({ ...ctx, code: ctx.code + ' post1' }) },
+        { name: 'pre2', enforce: 'pre', afterParse: (ctx) => ({ ...ctx, code: ctx.code + ' pre2' }) },
+      ];
+
+      // Simulate collectHooks sorting
+      const sorted = [...plugins].sort((a, b) => {
+        const order: Record<string, number> = { pre: 0, undefined: 1, post: 2 };
+        const aOrder = order[String(a.enforce)] ?? 1;
+        const bOrder = order[String(b.enforce)] ?? 1;
+        return aOrder - bOrder;
+      });
+
+      const hooks = sorted.filter((p) => p.afterParse).map((p) => p.afterParse!);
+      const pipeline = pipe(...hooks);
+      const result = await pipeline({ code: 'start' });
+
+      // pre plugins first, then normal, then post
+      expect(result.code).toBe('start pre1 pre2 normal1 post1');
+    });
+  });
+
+  describe('realistic plugin examples', () => {
+    test('custom directive replacement plugin', async () => {
+      const customDirectivePlugin = {
+        name: 'custom-directive',
+        afterParse(ctx: TestContext) {
+          const newCode = ctx.code
+            .replace(/<Warning>/g, '<Aside type="caution">')
+            .replace(/<\/Warning>/g, '</Aside>');
+          return { ...ctx, code: newCode };
+        },
+      };
+
+      const hooks = [customDirectivePlugin.afterParse];
+      const pipeline = pipe(...hooks);
+      const result = await pipeline({
+        code: '<Warning>Be careful!</Warning>',
+      });
+
+      expect(result.code).toBe('<Aside type="caution">Be careful!</Aside>');
+    });
+
+    test('analytics plugin that doesn\'t modify code', async () => {
+      const processedFiles: string[] = [];
+      const analyticsPlugin = {
+        name: 'analytics',
+        beforeOutput(ctx: TestContext) {
+          if (ctx.filename) {
+            processedFiles.push(ctx.filename);
+          }
+          return ctx; // Return unchanged
+        },
+      };
+
+      const hooks = [analyticsPlugin.beforeOutput];
+      const pipeline = pipe(...hooks);
+      const result = await pipeline({
+        code: 'original code',
+        filename: '/path/to/file.md',
+      });
+
+      expect(result.code).toBe('original code');
+      expect(processedFiles).toEqual(['/path/to/file.md']);
+    });
+
+    test('code wrapper plugin', async () => {
+      const wrapperPlugin = {
+        name: 'wrapper',
+        beforeOutput(ctx: TestContext) {
+          const wrapped = `/* Generated by Xmdx */\n${ctx.code}`;
+          return { ...ctx, code: wrapped };
+        },
+      };
+
+      const hooks = [wrapperPlugin.beforeOutput];
+      const pipeline = pipe(...hooks);
+      const result = await pipeline({ code: 'export default function() {}' });
+
+      expect(result.code).toContain('/* Generated by Xmdx */');
+      expect(result.code).toContain('export default function() {}');
+    });
+  });
+});
+
+describe('TransformContext structure', () => {
+  test('context contains all required properties', async () => {
+    let receivedCtx: TransformContext | null = null;
+
+    const inspectorHook = (ctx: TransformContext) => {
+      receivedCtx = ctx;
+      return ctx;
+    };
+
+    const pipeline = pipe(inspectorHook);
+    await pipeline({
+      code: '<div>Hello</div>',
+      source: '# Hello',
+      filename: '/test.md',
+      frontmatter: { title: 'Test' },
+      headings: [{ text: 'Hello', depth: 1, slug: 'hello' }],
+      config: {
+        expressiveCode: null,
+        starlightComponents: true,
+        shiki: null,
+      },
+    });
+
+    expect(receivedCtx).toHaveProperty('code');
+    expect(receivedCtx).toHaveProperty('source');
+    expect(receivedCtx).toHaveProperty('filename');
+    expect(receivedCtx).toHaveProperty('frontmatter');
+    expect(receivedCtx).toHaveProperty('headings');
+    expect(receivedCtx).toHaveProperty('config');
+    expect(receivedCtx!.config).toHaveProperty('expressiveCode');
+    expect(receivedCtx!.config).toHaveProperty('starlightComponents');
+    expect(receivedCtx!.config).toHaveProperty('shiki');
+  });
+});

package/src/presets/index.ts

@@ -0,0 +1,225 @@
+/**
+ * Astro Xmdx presets for common UI libraries.
+ * @module presets
+ */
+
+import type { ComponentLibrary } from 'xmdx/registry';
+import { starlightLibrary, expressiveCodeLibrary, astroLibrary } from 'xmdx/registry';
+import type { MdxImportHandlingOptions } from '../types.js';
+
+/**
+ * Preset configuration.
+ */
+export interface PresetConfig {
+  /** Component libraries to register */
+  libraries: ComponentLibrary[];
+  /** ExpressiveCode configuration */
+  expressiveCode?: boolean | { enabled: boolean; componentName?: string; importSource?: string };
+  /** Starlight components configuration */
+  starlightComponents?: boolean | { enabled: boolean; importSource?: string };
+  /** MDX import handling configuration */
+  mdx?: MdxImportHandlingOptions;
+}
+
+/**
+ * Default import patterns allowed for Starlight projects.
+ * These patterns won't trigger fallback to @mdx-js/mdx.
+ */
+export const STARLIGHT_DEFAULT_ALLOW_IMPORTS = [
+  // Starlight components and subpackages
+  '@astrojs/starlight/components',
+  '@astrojs/starlight/*',
+  // Astro virtual modules
+  'astro:*',
+  // Local project components (common Astro convention)
+  '~/components/*',
+  // Common image imports
+  '*.svg',
+  '*.png',
+  '*.jpg',
+  '*.jpeg',
+  '*.gif',
+  '*.webp',
+  '*.avif',
+] as const;
+
+/**
+ * Options for the Starlight preset.
+ */
+export interface StarlightPresetOptions {
+  /** Enable ExpressiveCode integration (default: true) */
+  expressiveCode?: boolean;
+  /** Strip Starlight imports - registry handles injection. @default true */
+  stripStarlightImports?: boolean;
+  /**
+   * Additional import patterns to allow beyond the defaults.
+   * Patterns matching these won't trigger fallback to @mdx-js/mdx.
+   * Supports glob patterns (e.g., '~/components/*').
+   * @example ['~/components/*', '../components/*', 'my-package']
+   */
+  allowImports?: string[];
+}
+
+/**
+ * Creates a Starlight preset with Starlight components and optionally ExpressiveCode.
+ *
+ * @example
+ * import xmdx from 'astro-xmdx';
+ * import { starlightPreset } from 'astro-xmdx/presets';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     xmdx({
+ *       presets: [starlightPreset()],
+ *     })
+ *   ]
+ * });
+ */
+export function starlightPreset(options: StarlightPresetOptions = {}): PresetConfig {
+  const { expressiveCode = true, stripStarlightImports = true, allowImports = [] } = options;
+
+  const libraries = [astroLibrary, starlightLibrary];
+  if (expressiveCode) {
+    libraries.push(expressiveCodeLibrary);
+  }
+
+  // Merge default patterns with user-provided patterns
+  const mergedAllowImports = [
+    ...STARLIGHT_DEFAULT_ALLOW_IMPORTS,
+    ...allowImports,
+  ];
+
+  return {
+    libraries,
+    starlightComponents: true,
+    expressiveCode: expressiveCode ? { enabled: true } : false,
+    mdx: stripStarlightImports
+      ? { allowImports: mergedAllowImports, ignoreCodeFences: true }
+      : undefined,
+  };
+}
+
+/**
+ * Options for the ExpressiveCode preset.
+ */
+export interface ExpressiveCodePresetOptions {
+  /** Component name to use (default: 'Code') */
+  componentName?: string;
+  /** Import source (default: 'astro-expressive-code/components') */
+  importSource?: string;
+}
+
+/**
+ * Creates an ExpressiveCode preset for syntax highlighting.
+ *
+ * @example
+ * import xmdx from 'astro-xmdx';
+ * import { expressiveCodePreset } from 'astro-xmdx/presets';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     xmdx({
+ *       presets: [expressiveCodePreset()],
+ *     })
+ *   ]
+ * });
+ */
+export function expressiveCodePreset(options: ExpressiveCodePresetOptions = {}): PresetConfig {
+  const {
+    componentName = 'Code',
+    importSource = 'astro-expressive-code/components',
+  } = options;
+
+  return {
+    libraries: [astroLibrary, expressiveCodeLibrary],
+    expressiveCode: {
+      enabled: true,
+      componentName,
+      importSource,
+    },
+  };
+}
+
+/**
+ * Creates a base Astro preset with core components.
+ *
+ * @example
+ * import xmdx from 'astro-xmdx';
+ * import { astroPreset } from 'astro-xmdx/presets';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     xmdx({
+ *       presets: [astroPreset()],
+ *     })
+ *   ]
+ * });
+ */
+export function astroPreset(): PresetConfig {
+  return {
+    libraries: [astroLibrary],
+  };
+}
+
+/**
+ * Merges multiple presets into a single configuration.
+ * Later presets override earlier ones for conflicting options.
+ */
+export function mergePresets(presets: PresetConfig[]): PresetConfig {
+  if (!presets || presets.length === 0) {
+    return { libraries: [astroLibrary] };
+  }
+
+  const merged: PresetConfig = {
+    libraries: [],
+    expressiveCode: false,
+    starlightComponents: false,
+    mdx: undefined,
+  };
+
+  const libraryIds = new Set<string>();
+
+  for (const preset of presets) {
+    // Merge libraries (deduplicate by id)
+    if (Array.isArray(preset.libraries)) {
+      for (const lib of preset.libraries) {
+        if (!libraryIds.has(lib.id)) {
+          libraryIds.add(lib.id);
+          merged.libraries.push(lib);
+        }
+      }
+    }
+
+    // Merge expressiveCode (last wins)
+    if (preset.expressiveCode !== undefined) {
+      merged.expressiveCode = preset.expressiveCode;
+    }
+
+    // Merge starlightComponents (last wins)
+    if (preset.starlightComponents !== undefined) {
+      merged.starlightComponents = preset.starlightComponents;
+    }
+
+    // Merge mdx (combine allowImports, last wins for others)
+    if (preset.mdx) {
+      if (!merged.mdx) {
+        merged.mdx = { ...preset.mdx };
+      } else {
+        const existingAllows = merged.mdx.allowImports ?? [];
+        const newAllows = preset.mdx.allowImports ?? [];
+        merged.mdx = {
+          ...merged.mdx,
+          ...preset.mdx,
+          allowImports: [...new Set([...existingAllows, ...newAllows])],
+        };
+      }
+    }
+  }
+
+  // Ensure at least astroLibrary is present
+  if (merged.libraries.length === 0) {
+    merged.libraries.push(astroLibrary);
+  }
+
+  return merged;
+}