astro-xmdx 0.0.2

package/src/utils/paths.ts

@@ -0,0 +1,92 @@
+/**
+ * Path manipulation and URL derivation utilities
+ * @module utils/paths
+ */
+
+import path from 'node:path';
+
+/**
+ * Default file extensions that should be compiled
+ */
+export const DEFAULT_EXTENSIONS = new Set(['.md', '.mdx']);
+
+/**
+ * Removes query string from a file ID/path
+ */
+export function stripQuery(id: string): string {
+  if (!id) return id;
+  const queryIndex = id.indexOf('?');
+  return queryIndex >= 0 ? id.slice(0, queryIndex) : id;
+}
+
+/**
+ * Normalizes path separators to forward slashes (Unix-style)
+ */
+export function normalizePath(value: string): string {
+  return value.split(path.sep).join('/');
+}
+
+/**
+ * Derives the Astro page URL from a file path.
+ * Converts file system paths to web URLs following Astro's routing conventions.
+ */
+export function deriveAstroUrl(filePath: string, rootDir?: string): string | undefined {
+  if (!filePath) return undefined;
+  const normalizedFile = normalizePath(filePath);
+  const root = rootDir ?? process.cwd();
+  const pagesDir = normalizePath(path.join(root, 'src', 'pages'));
+  if (!normalizedFile.startsWith(pagesDir)) {
+    return undefined;
+  }
+  let relative = normalizedFile.slice(pagesDir.length);
+  if (relative.startsWith('/')) {
+    relative = relative.slice(1);
+  }
+  if (!relative) {
+    return '/';
+  }
+  if (relative.endsWith('.md') || relative.endsWith('.mdx')) {
+    relative = relative.replace(/\.mdx?$/, '');
+  }
+  if (relative === '' || relative === 'index') {
+    return '/';
+  }
+  if (relative.endsWith('/index')) {
+    relative = relative.slice(0, -'/index'.length);
+  }
+  return `/${relative}`;
+}
+
+/**
+ * File options derived from a module ID.
+ */
+export interface FileOptions {
+  /** Absolute file path */
+  file: string;
+  /** Derived URL (if in pages directory) */
+  url?: string;
+}
+
+/**
+ * Derives file options (absolute path and URL) from a Vite module ID.
+ */
+export function deriveFileOptions(id: string, rootDir?: string): FileOptions {
+  const sourcePath = stripQuery(id);
+  let absolutePath = sourcePath;
+  if (rootDir && !path.isAbsolute(sourcePath)) {
+    absolutePath = path.resolve(rootDir, sourcePath);
+  }
+  const url = deriveAstroUrl(absolutePath, rootDir);
+  const options: FileOptions = { file: absolutePath };
+  if (url) {
+    options.url = url;
+  }
+  return options;
+}
+
+/**
+ * Checks if a file should be compiled based on its extension.
+ */
+export function shouldCompile(id: string): boolean {
+  return DEFAULT_EXTENSIONS.has(path.extname(stripQuery(id)));
+}

package/src/utils/validation.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from 'bun:test';
+import { stripHeadingsMeta } from './validation.js';
+
+describe('stripHeadingsMeta', () => {
+  test('returns code unchanged when no headings metadata', () => {
+    const code = `import React from 'react';\n\nexport default () => <div>Hello</div>;`;
+    expect(stripHeadingsMeta(code)).toBe(code);
+  });
+
+  test('removes export const headings', () => {
+    const code = `export const headings = [{depth: 1, text: "Title"}];\n\nContent`;
+    const result = stripHeadingsMeta(code);
+    expect(result).not.toContain('export const headings');
+    expect(result).toContain('Content');
+  });
+
+  test('removes export function getHeadings', () => {
+    const code = `export function getHeadings() { return []; }\n\nContent`;
+    const result = stripHeadingsMeta(code);
+    expect(result).not.toContain('export function getHeadings');
+    expect(result).toContain('Content');
+  });
+
+  test('removes both headings exports', () => {
+    const code = `export const headings = [];\nexport function getHeadings() { return headings; }\n\nContent`;
+    const result = stripHeadingsMeta(code);
+    expect(result).not.toContain('export const headings');
+    expect(result).not.toContain('export function getHeadings');
+    expect(result).toContain('Content');
+  });
+
+  test('handles multiline headings array', () => {
+    const code = `export const headings = [\n  {depth: 1, text: "A"},\n  {depth: 2, text: "B"}\n];\n\nContent`;
+    const result = stripHeadingsMeta(code);
+    expect(result).not.toContain('export const headings');
+    expect(result).toContain('Content');
+  });
+
+  test('handles multiline getHeadings function', () => {
+    const code = `export function getHeadings() {\n  return [\n    {depth: 1}\n  ];\n}\n\nContent`;
+    const result = stripHeadingsMeta(code);
+    expect(result).not.toContain('export function getHeadings');
+    expect(result).toContain('Content');
+  });
+
+  test('preserves other exports', () => {
+    const code = `export const frontmatter = {};\nexport const headings = [];\nexport function MyComponent() {}`;
+    const result = stripHeadingsMeta(code);
+    expect(result).toContain('export const frontmatter');
+    expect(result).not.toContain('export const headings');
+    expect(result).toContain('export function MyComponent');
+  });
+
+  test('handles Windows line endings (CRLF)', () => {
+    const code = `export const headings = [];\r\n\r\nContent`;
+    const result = stripHeadingsMeta(code);
+    expect(result).not.toContain('export const headings');
+    expect(result).toContain('Content');
+  });
+});

package/src/utils/validation.ts

@@ -0,0 +1,15 @@
+/**
+ * Source validation utilities
+ * @module utils/validation
+ */
+
+/**
+ * Strips headings metadata from code for component scanning.
+ * Removes export const headings and export function getHeadings
+ * to avoid false positive component matches in metadata.
+ */
+export function stripHeadingsMeta(code: string): string {
+  return code
+    .replace(/export const headings\s*=\s*\[[\s\S]*?\];\r?\n/g, '')
+    .replace(/export function getHeadings\(\)\s*\{[\s\S]*?\}\r?\n/g, '');
+}

package/src/vite-plugin/binding-loader.ts

@@ -0,0 +1,81 @@
+/**
+ * Native binding loader for Xmdx
+ * @module vite-plugin/binding-loader
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import type { XmdxBinding } from './types.js';
+
+let bindingPromise: Promise<XmdxBinding> | undefined;
+const DEBUG_BINDING = process.env.XMDX_DEBUG_BINDING === '1';
+
+/**
+ * Environment flags for enabling optional features.
+ */
+export const ENABLE_SHIKI = process.env.XMDX_SHIKI === '1';
+export const IS_MDAST = process.env.XMDX_PIPELINE === 'mdast';
+
+const logBindingSource = (source: string): void => {
+  if (!DEBUG_BINDING) return;
+  console.info(`[xmdx] binding source: ${source}`);
+  const nativePath = process.env.NAPI_RS_NATIVE_LIBRARY_PATH;
+  if (nativePath) {
+    console.info(`[xmdx] NAPI_RS_NATIVE_LIBRARY_PATH=${nativePath}`);
+  } else {
+    console.info('[xmdx] NAPI_RS_NATIVE_LIBRARY_PATH is not set');
+  }
+};
+
+/**
+ * Loads the native Xmdx binding.
+ * Uses require() directly on the .node binary to bypass Vite SSR runner.
+ */
+export async function loadXmdxBinding(): Promise<XmdxBinding> {
+  if (!bindingPromise) {
+    bindingPromise = (async () => {
+      const require = createRequire(import.meta.url);
+      const pkgRoot = path.dirname(require.resolve('xmdx-napi/package.json'));
+
+      const guessBinaryName = () => {
+        const triplet = `${process.platform}-${process.arch}`;
+        return [
+          `xmdx.${triplet}.node`,
+          `xmdx-${triplet}.node`,
+          `xmdx.${process.platform}-${process.arch}.node`,
+        ];
+      };
+
+      const findBinaryPath = (): string => {
+        const candidates = guessBinaryName().map((name) =>
+          path.resolve(pkgRoot, name)
+        );
+        for (const candidate of candidates) {
+          if (require('node:fs').existsSync(candidate)) {
+            return candidate;
+          }
+        }
+        // Fallback: first .node in package root
+        const entries = require('node:fs').readdirSync(pkgRoot);
+        const nodeFile = entries.find((f: string) => f.endsWith('.node'));
+        if (nodeFile) {
+          return path.resolve(pkgRoot, nodeFile);
+        }
+        throw new Error('xmdx-napi native binary not found');
+      };
+
+      const binaryPath = findBinaryPath();
+      const binding = require(binaryPath) as XmdxBinding;
+      logBindingSource(binaryPath);
+      return binding;
+    })();
+  }
+  return bindingPromise;
+}
+
+/**
+ * Resets the binding promise (useful for testing).
+ */
+export function resetBindingPromise(): void {
+  bindingPromise = undefined;
+}

package/src/vite-plugin/directive-rewriter.test.ts

@@ -0,0 +1,331 @@
+import { describe, test, expect } from 'bun:test';
+import { createRegistry, starlightLibrary, astroLibrary } from 'xmdx/registry';
+import { rewriteFallbackDirectives, injectFallbackImports } from './directive-rewriter.js';
+
+const testRegistry = createRegistry([starlightLibrary, astroLibrary]);
+
+describe('rewriteFallbackDirectives', () => {
+  describe('core functionality', () => {
+    test('converts :::note to <Aside type="note">', () => {
+      const source = `:::note
+This is a note.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('<Aside');
+      expect(result.code).toContain('type="note"');
+      expect(result.code).toContain('</Aside>');
+      expect(result.usedComponents.has('Aside')).toBe(true);
+    });
+
+    test('converts :::tip to <Aside type="tip">', () => {
+      const source = `:::tip
+This is a tip.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('<Aside');
+      expect(result.code).toContain('type="tip"');
+      expect(result.code).toContain('</Aside>');
+    });
+
+    test('converts :::caution to <Aside type="caution">', () => {
+      const source = `:::caution
+Be careful!
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('type="caution"');
+    });
+
+    test('converts :::danger to <Aside type="danger">', () => {
+      const source = `:::danger
+This is dangerous!
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('type="danger"');
+    });
+
+    test('extracts bracket title: :::note[Custom Title]', () => {
+      const source = `:::note[Custom Title]
+This is a note with a title.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('title="Custom Title"');
+    });
+
+    test('handles multiple directives in sequence', () => {
+      const source = `:::note
+First note.
+:::
+
+:::tip
+A tip here.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('type="note"');
+      expect(result.code).toContain('type="tip"');
+    });
+  });
+
+  describe('code fence handling', () => {
+    test('ignores directives inside code fences', () => {
+      const source = `\`\`\`md
+:::note
+This is inside a code fence.
+:::
+\`\`\``;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(false);
+      expect(result.code).toBe(source);
+    });
+
+    test('ignores directives inside triple tilde fences', () => {
+      const source = `~~~md
+:::note
+This is inside a tilde fence.
+:::
+~~~`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(false);
+      expect(result.code).toBe(source);
+    });
+
+    test('processes directives after code fence closes', () => {
+      const source = `\`\`\`js
+const x = 1;
+\`\`\`
+
+:::note
+Real note.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('<Aside');
+      expect(result.code).toContain('const x = 1;');
+    });
+  });
+
+  describe('nesting and blockquotes', () => {
+    test('handles directives in blockquotes', () => {
+      const source = `> :::note
+> This is a note in a blockquote.
+> :::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('<Aside');
+    });
+
+    test('preserves indentation prefix', () => {
+      const source = `  :::note
+  Indented content.
+  :::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('  <Aside');
+      expect(result.code).toContain('  </Aside>');
+    });
+  });
+
+  describe('registry integration', () => {
+    test('uses registry directive mappings when available', () => {
+      const source = `:::note
+Content here.
+:::`;
+      const result = rewriteFallbackDirectives(source, testRegistry, false);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('<Aside');
+      expect(result.usedComponents.has('Aside')).toBe(true);
+    });
+
+    test('returns unchanged when registry has no matching directive', () => {
+      const source = `:::unknown
+Unknown directive.
+:::`;
+      const result = rewriteFallbackDirectives(source, testRegistry, false);
+      expect(result.changed).toBe(false);
+      expect(result.code).toBe(source);
+    });
+  });
+
+  describe('edge cases', () => {
+    test('handles empty source', () => {
+      const result = rewriteFallbackDirectives('', null, true);
+      expect(result.changed).toBe(false);
+      expect(result.code).toBe('');
+      expect(result.usedComponents.size).toBe(0);
+    });
+
+    test('handles source with no directives', () => {
+      const source = `# Hello World
+
+This is regular markdown.`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(false);
+      expect(result.code).toBe(source);
+    });
+
+    test('handles unclosed directives by auto-closing', () => {
+      const source = `:::note
+This directive is never closed.`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('<Aside');
+      expect(result.code).toContain('</Aside>');
+    });
+
+    test('handles directive with extra attributes', () => {
+      const source = `:::note{id="my-note" class="custom"}
+Content with attributes.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('id="my-note"');
+      expect(result.code).toContain('class="custom"');
+    });
+
+    test('filters out type attribute from extras', () => {
+      const source = `:::note{type="custom"}
+Should not duplicate type.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      // Type should appear exactly once (from directive name, not from attrs)
+      const matches = result.code.match(/type="/g);
+      expect(matches?.length).toBe(1);
+    });
+
+    test('filters out title attribute when bracket title exists', () => {
+      const source = `:::note[Bracket Title]{title="Attr Title"}
+Should use bracket title.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.changed).toBe(true);
+      expect(result.code).toContain('title="Bracket Title"');
+      // Should not contain the attribute title
+      expect(result.code).not.toContain('title="Attr Title"');
+    });
+
+    test('does not rewrite when hasStarlightConfigured is false and no registry', () => {
+      const source = `:::note
+Not configured.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, false);
+      expect(result.changed).toBe(false);
+      expect(result.code).toBe(source);
+    });
+
+    test('adds data-mf-source attribute', () => {
+      const source = `:::note
+Content.
+:::`;
+      const result = rewriteFallbackDirectives(source, null, true);
+      expect(result.code).toContain('data-mf-source="directive"');
+    });
+  });
+});
+
+describe('injectFallbackImports', () => {
+  test('injects import for used component not already imported', () => {
+    const source = `# Hello
+
+<Aside type="note">Content</Aside>`;
+    const usedComponents = new Set(['Aside']);
+    const result = injectFallbackImports(source, usedComponents, null, true);
+    expect(result).toContain("import { Aside } from '@astrojs/starlight/components';");
+  });
+
+  test('skips already imported components', () => {
+    const source = `import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="note">Content</Aside>`;
+    const usedComponents = new Set(['Aside']);
+    const result = injectFallbackImports(source, usedComponents, null, true);
+    // Should not duplicate the import
+    const importCount = (result.match(/import.*Aside/g) || []).length;
+    expect(importCount).toBe(1);
+  });
+
+  test('handles named exports from registry', () => {
+    const source = `# Content
+
+<Aside type="note">Content</Aside>`;
+    const usedComponents = new Set(['Aside']);
+    const result = injectFallbackImports(source, usedComponents, testRegistry, false);
+    expect(result).toContain("import { Aside }");
+  });
+
+  test('returns source unchanged when no components used', () => {
+    const source = `# Hello World`;
+    const usedComponents = new Set<string>();
+    const result = injectFallbackImports(source, usedComponents, null, true);
+    expect(result).toBe(source);
+  });
+
+  test('returns source unchanged when source is empty', () => {
+    const result = injectFallbackImports('', new Set(['Aside']), null, true);
+    expect(result).toBe('');
+  });
+
+  test('does not inject Aside import when hasStarlightConfigured is false and no registry', () => {
+    const source = `# Content
+
+<Aside type="note">Content</Aside>`;
+    const usedComponents = new Set(['Aside']);
+    const result = injectFallbackImports(source, usedComponents, null, false);
+    // Should not add any import since Starlight is not configured
+    expect(result).not.toContain("import { Aside }");
+  });
+
+  test('injects imports after existing imports', () => {
+    const source = `import React from 'react';
+
+# Content
+
+<Aside type="note">Content</Aside>`;
+    const usedComponents = new Set(['Aside']);
+    const result = injectFallbackImports(source, usedComponents, null, true);
+    const lines = result.split('\n');
+    const reactIndex = lines.findIndex((l) => l.includes('React'));
+    const asideIndex = lines.findIndex((l) => l.includes('Aside'));
+    expect(asideIndex).toBeGreaterThan(reactIndex);
+  });
+
+  test('handles multiple used components', () => {
+    const source = `# Content
+
+<Aside>Note</Aside>
+<Card>Info</Card>`;
+    const usedComponents = new Set(['Aside', 'Card']);
+    const result = injectFallbackImports(source, usedComponents, testRegistry, false);
+    expect(result).toContain('Aside');
+    // Card may or may not be in registry, but Aside should be imported
+  });
+});
+
+describe('integration', () => {
+  test('rewrite + inject works together', () => {
+    const source = `import { something } from 'somewhere';
+
+:::note[My Note]
+This is my note content.
+:::`;
+    const rewriteResult = rewriteFallbackDirectives(source, null, true);
+    expect(rewriteResult.changed).toBe(true);
+
+    const finalCode = injectFallbackImports(
+      rewriteResult.code,
+      rewriteResult.usedComponents,
+      null,
+      true
+    );
+
+    expect(finalCode).toContain('<Aside');
+    expect(finalCode).toContain('title="My Note"');
+    expect(finalCode).toContain("import { Aside } from '@astrojs/starlight/components';");
+    expect(finalCode).toContain("import { something } from 'somewhere';");
+  });
+});