@macroforge/mcp-server 0.1.17

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { registerTools } from './tools/index.js';
+// Get package info for server metadata
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+const { name, version } = pkg;
+/**
+ * Main function to start the MCP server
+ */
+async function main() {
+    // Create server instance with metadata
+    const server = new Server({
+        name,
+        version,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Register all tools
+    registerTools(server);
+    // Set up error handling
+    server.onerror = (error) => {
+        console.error('[MCP Error]', error);
+    };
+    // Handle process termination
+    process.on('SIGINT', async () => {
+        await server.close();
+        process.exit(0);
+    });
+    // Connect to transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Macroforge MCP server running on stdio');
+}
+// Run the server
+main().catch((error) => {
+    console.error('Failed to start MCP server:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,uCAAuC;AACvC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AACtC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACpF,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;AAE9B;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,uCAAuC;IACvC,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;QACE,IAAI;QACJ,OAAO;KACR,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;SACV;KACF,CACF,CAAC;IAEF,qBAAqB;IACrB,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtB,wBAAwB;IACxB,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE;QACzB,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC;IAEF,6BAA6B;IAC7B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,uBAAuB;IACvB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AAC1D,CAAC;AAED,iBAAiB;AACjB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/docs-loader.d.ts

@@ -0,0 +1,30 @@
+export interface Section {
+    id: string;
+    title: string;
+    category: string;
+    category_title: string;
+    path: string;
+    use_cases: string;
+    content?: string;
+}
+/**
+ * Load all documentation sections from the docs directory
+ */
+export declare function loadSections(): Section[];
+/**
+ * Get a section by ID or title (case-insensitive)
+ */
+export declare function getSection(sections: Section[], query: string): Section | undefined;
+/**
+ * Get multiple sections by IDs or titles
+ */
+export declare function getSections(sections: Section[], queries: string[]): Section[];
+/**
+ * Search sections by use_cases or content
+ */
+export declare function searchSections(sections: Section[], query: string): Section[];
+/**
+ * Get all sections in a category
+ */
+export declare function getSectionsByCategory(sections: Section[], category: string): Section[];
+//# sourceMappingURL=docs-loader.d.ts.map

package/dist/tools/docs-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-loader.d.ts","sourceRoot":"","sources":["../../src/tools/docs-loader.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,EAAE,CAqBxC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAoBlF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAW7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CA0C5E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAOtF"}

package/dist/tools/docs-loader.js

@@ -0,0 +1,112 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const docsDir = join(__dirname, '..', '..', 'docs');
+/**
+ * Load all documentation sections from the docs directory
+ */
+export function loadSections() {
+    const sectionsPath = join(docsDir, 'sections.json');
+    if (!existsSync(sectionsPath)) {
+        console.error('Warning: sections.json not found. Run "npm run build:docs" to generate documentation.');
+        return [];
+    }
+    const sectionsData = JSON.parse(readFileSync(sectionsPath, 'utf-8'));
+    // Load content for each section
+    for (const section of sectionsData) {
+        const contentPath = join(docsDir, section.path);
+        if (existsSync(contentPath)) {
+            section.content = readFileSync(contentPath, 'utf-8');
+        }
+        else {
+            section.content = `Documentation file not found: ${section.path}`;
+        }
+    }
+    return sectionsData;
+}
+/**
+ * Get a section by ID or title (case-insensitive)
+ */
+export function getSection(sections, query) {
+    const normalizedQuery = query.toLowerCase().trim();
+    // Try exact ID match first
+    let match = sections.find((s) => s.id.toLowerCase() === normalizedQuery);
+    if (match)
+        return match;
+    // Try exact title match
+    match = sections.find((s) => s.title.toLowerCase() === normalizedQuery);
+    if (match)
+        return match;
+    // Try partial ID match
+    match = sections.find((s) => s.id.toLowerCase().includes(normalizedQuery));
+    if (match)
+        return match;
+    // Try partial title match
+    match = sections.find((s) => s.title.toLowerCase().includes(normalizedQuery));
+    if (match)
+        return match;
+    return undefined;
+}
+/**
+ * Get multiple sections by IDs or titles
+ */
+export function getSections(sections, queries) {
+    const results = [];
+    for (const query of queries) {
+        const section = getSection(sections, query);
+        if (section && !results.includes(section)) {
+            results.push(section);
+        }
+    }
+    return results;
+}
+/**
+ * Search sections by use_cases or content
+ */
+export function searchSections(sections, query) {
+    const normalizedQuery = query.toLowerCase().trim();
+    const keywords = normalizedQuery.split(/\s+/);
+    const scored = sections.map((section) => {
+        let score = 0;
+        // Check ID
+        if (section.id.toLowerCase().includes(normalizedQuery)) {
+            score += 10;
+        }
+        // Check title
+        if (section.title.toLowerCase().includes(normalizedQuery)) {
+            score += 10;
+        }
+        // Check use_cases
+        const useCases = section.use_cases.toLowerCase();
+        for (const keyword of keywords) {
+            if (useCases.includes(keyword)) {
+                score += 5;
+            }
+        }
+        // Check content (lower weight)
+        if (section.content) {
+            const content = section.content.toLowerCase();
+            for (const keyword of keywords) {
+                if (content.includes(keyword)) {
+                    score += 1;
+                }
+            }
+        }
+        return { section, score };
+    });
+    return scored
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .map((s) => s.section);
+}
+/**
+ * Get all sections in a category
+ */
+export function getSectionsByCategory(sections, category) {
+    const normalizedCategory = category.toLowerCase().trim();
+    return sections.filter((s) => s.category.toLowerCase() === normalizedCategory ||
+        s.category_title.toLowerCase() === normalizedCategory);
+}
+//# sourceMappingURL=docs-loader.js.map

package/dist/tools/docs-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-loader.js","sourceRoot":"","sources":["../../src/tools/docs-loader.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * Register all Macroforge MCP tools with the server
+ */
+export declare function registerTools(server: Server): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAWnE;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAgJlD"}

package/dist/tools/index.js

@@ -0,0 +1,348 @@
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { loadSections, getSection, searchSections } from './docs-loader.js';
+let sections = [];
+/**
+ * Register all Macroforge MCP tools with the server
+ */
+export function registerTools(server) {
+    // Load documentation sections
+    sections = loadSections();
+    // Register tool listing
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                {
+                    name: 'list-sections',
+                    description: `Lists all Macroforge documentation sections.
+
+Returns sections with:
+- title: Section name
+- use_cases: When this doc is useful (comma-separated keywords)
+- path: File path
+- category: Category name
+
+WORKFLOW:
+1. Call list-sections FIRST for any Macroforge-related task
+2. Analyze use_cases to find relevant sections
+3. Call get-documentation with ALL relevant section names
+
+Example use_cases: "setup, install", "serialization, json", "validation, email"`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                {
+                    name: 'get-documentation',
+                    description: `Retrieves full documentation content for Macroforge sections.
+
+Supports flexible search by:
+- Title (e.g., "Debug", "Vite Plugin")
+- ID (e.g., "debug", "vite-plugin")
+- Partial matches
+
+Can accept a single section name or an array of sections.
+After calling list-sections, analyze the use_cases and fetch ALL relevant sections at once.`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            section: {
+                                anyOf: [
+                                    { type: 'string' },
+                                    { type: 'array', items: { type: 'string' } },
+                                ],
+                                description: 'Section name(s) to retrieve. Supports single string or array of strings.',
+                            },
+                        },
+                        required: ['section'],
+                    },
+                },
+                {
+                    name: 'macroforge-autofixer',
+                    description: `Validates TypeScript code with @derive decorators using Macroforge's native validation.
+
+Returns structured JSON diagnostics with:
+- level: error | warning | info
+- message: What's wrong
+- location: Line and column number (when available)
+- help: Suggested fix (when available)
+- notes: Additional context (when available)
+- summary: Count of errors, warnings, and info messages
+
+This tool MUST be used before sending Macroforge code to the user.
+If require_another_tool_call_after_fixing is true, fix the issues and validate again.
+
+Detects:
+- Invalid/unknown macro names
+- Malformed @derive decorators
+- @serde validator issues (email, url, length, etc.)
+- Macro expansion failures
+- Syntax errors in generated code`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            code: {
+                                type: 'string',
+                                description: 'TypeScript code with @derive decorators to validate',
+                            },
+                            filename: {
+                                type: 'string',
+                                description: 'Filename for the code (default: input.ts)',
+                            },
+                        },
+                        required: ['code'],
+                    },
+                },
+                {
+                    name: 'expand-code',
+                    description: `Expands Macroforge macros in TypeScript code and returns the transformed result.
+
+Shows:
+- The fully expanded TypeScript code with all generated methods
+- Any diagnostics (errors, warnings, info) with line/column locations
+- Help text for fixing issues (when available)
+
+Useful for:
+- Seeing what code the macros generate
+- Understanding how @derive decorators transform your classes
+- Debugging macro expansion issues`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            code: {
+                                type: 'string',
+                                description: 'TypeScript code with @derive decorators to expand',
+                            },
+                            filename: {
+                                type: 'string',
+                                description: 'Filename for the code (default: input.ts)',
+                            },
+                        },
+                        required: ['code'],
+                    },
+                },
+            ],
+        };
+    });
+    // Register tool call handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        switch (name) {
+            case 'list-sections':
+                return handleListSections();
+            case 'get-documentation':
+                return handleGetDocumentation(args);
+            case 'macroforge-autofixer':
+                return handleAutofixer(args);
+            case 'expand-code':
+                return handleExpandCode(args);
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+    });
+}
+/**
+ * Handle list-sections tool call
+ */
+function handleListSections() {
+    const formatted = sections
+        .map((s) => `* title: [${s.title}], use_cases: [${s.use_cases}], path: [${s.path}], category: [${s.category_title}]`)
+        .join('\n');
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Available Macroforge documentation sections:\n\n${formatted}`,
+            },
+        ],
+    };
+}
+/**
+ * Handle get-documentation tool call
+ */
+function handleGetDocumentation(args) {
+    const sectionNames = Array.isArray(args.section) ? args.section : [args.section];
+    const results = [];
+    for (const name of sectionNames) {
+        const section = getSection(sections, name);
+        if (section) {
+            results.push(`# ${section.title}\n\n${section.content}`);
+        }
+        else {
+            // Try fuzzy search
+            const matches = searchSections(sections, name);
+            if (matches.length > 0) {
+                results.push(`# ${matches[0].title}\n\n${matches[0].content}`);
+            }
+            else {
+                results.push(`Documentation for "${name}" not found.`);
+            }
+        }
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: results.join('\n\n---\n\n'),
+            },
+        ],
+    };
+}
+/**
+ * Handle macroforge-autofixer tool call
+ * Returns structured diagnostics from Macroforge's native validation
+ */
+async function handleAutofixer(args) {
+    const filename = args.filename || 'input.ts';
+    try {
+        const macroforge = await importMacroforge();
+        if (!macroforge) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            diagnostics: [{
+                                    level: 'error',
+                                    message: 'Native Macroforge bindings not available. Install @macroforge/core.',
+                                }],
+                            summary: { errors: 1, warnings: 0, info: 0 },
+                            require_another_tool_call_after_fixing: false,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const result = macroforge.expandSync(args.code, filename, {});
+        const diagnostics = result.diagnostics || [];
+        const output = {
+            diagnostics: diagnostics.map((d) => ({
+                level: normalizeLevel(d.level),
+                message: d.message,
+                location: d.span ? { line: d.span.start.line, column: d.span.start.column } : undefined,
+                help: d.help || undefined,
+                notes: d.notes && d.notes.length > 0 ? d.notes : undefined,
+            })),
+            summary: {
+                errors: diagnostics.filter((d) => d.level === 'Error').length,
+                warnings: diagnostics.filter((d) => d.level === 'Warning').length,
+                info: diagnostics.filter((d) => d.level === 'Info').length,
+            },
+            require_another_tool_call_after_fixing: diagnostics.some((d) => d.level === 'Error'),
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(output, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        diagnostics: [{
+                                level: 'error',
+                                message: `Error during analysis: ${message}`,
+                            }],
+                        summary: { errors: 1, warnings: 0, info: 0 },
+                        require_another_tool_call_after_fixing: false,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}
+/**
+ * Handle expand-code tool call
+ * Returns expanded code with structured diagnostics
+ */
+async function handleExpandCode(args) {
+    const filename = args.filename || 'input.ts';
+    try {
+        const macroforge = await importMacroforge();
+        if (!macroforge) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Native Macroforge bindings not available. Install @macroforge/core to enable code expansion.',
+                    },
+                ],
+            };
+        }
+        const result = macroforge.expandSync(args.code, filename, {});
+        const diagnostics = result.diagnostics || [];
+        // Build structured output
+        const output = {
+            expandedCode: result.code,
+            diagnostics: diagnostics.map((d) => ({
+                level: normalizeLevel(d.level),
+                message: d.message,
+                location: d.span?.start,
+                help: d.help || undefined,
+            })),
+            hasErrors: diagnostics.some((d) => d.level === 'Error'),
+        };
+        // Format human-readable text
+        let text = `## Expanded Code\n\n\`\`\`typescript\n${result.code}\n\`\`\``;
+        if (diagnostics.length > 0) {
+            text += '\n\n## Diagnostics\n\n';
+            for (const d of diagnostics) {
+                const loc = d.span ? ` (line ${d.span.start.line}, col ${d.span.start.column})` : '';
+                text += `- **[${normalizeLevel(d.level)}]**${loc} ${d.message}\n`;
+                if (d.help) {
+                    text += `  - Help: ${d.help}\n`;
+                }
+                if (d.notes && d.notes.length > 0) {
+                    for (const note of d.notes) {
+                        text += `  - Note: ${note}\n`;
+                    }
+                }
+            }
+        }
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error expanding code: ${message}`,
+                },
+            ],
+        };
+    }
+}
+// ============================================================================
+// Helper functions
+// ============================================================================
+/**
+ * Try to import native Macroforge bindings
+ */
+async function importMacroforge() {
+    try {
+        // Dynamic import to avoid build-time errors
+        // @ts-expect-error - dynamic import of optional dependency
+        const mod = await import('@macroforge/core');
+        return mod;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Normalize diagnostic level to lowercase for output
+ */
+function normalizeLevel(level) {
+    return level.toLowerCase();
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/docs/api/api-overview.md

@@ -0,0 +1,75 @@
+# API Reference
+
+*Macroforge provides a programmatic API for expanding macros in TypeScript code.*
+
+## Overview
+
+```typescript
+import {
+  expandSync,
+  transformSync,
+  checkSyntax,
+  parseImportSources,
+  NativePlugin,
+  PositionMapper
+} from "macroforge";
+```
+
+## Core Functions
+
+| [`expandSync()`]({base}/docs/api/expand-sync) 
+| Expand macros synchronously 
+
+| [`transformSync()`]({base}/docs/api/transform-sync) 
+| Transform code with additional metadata 
+
+| `checkSyntax()` 
+| Validate TypeScript syntax 
+
+| `parseImportSources()` 
+| Extract import information
+
+## Classes
+
+| [`NativePlugin`]({base}/docs/api/native-plugin) 
+| Stateful plugin with caching 
+
+| [`PositionMapper`]({base}/docs/api/position-mapper) 
+| Maps positions between original and expanded code
+
+## Quick Example
+
+```typescript
+import { expandSync } from "macroforge";
+
+const sourceCode = \`
+/** @derive(Debug) */
+class User {
+  name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+\`;
+
+const result = expandSync(sourceCode, "user.ts", {
+  keepDecorators: false
+});
+
+console.log(result.code);
+// Output: class with toString() method generated
+
+if (result.diagnostics.length > 0) {
+  console.error("Errors:", result.diagnostics);
+}
+```
+
+## Detailed Reference
+
+- [`expandSync()`]({base}/docs/api/expand-sync) - Full options and return types
+
+- [`transformSync()`]({base}/docs/api/transform-sync) - Transform with source maps
+
+- [`NativePlugin`]({base}/docs/api/native-plugin) - Caching for language servers
+
+- [`PositionMapper`]({base}/docs/api/position-mapper) - Position mapping utilities