@zenithbuild/language-server 0.2.2

package/src/metadata/directive-metadata.ts

@@ -0,0 +1,109 @@
+/**
+ * Directive Metadata
+ * 
+ * Compile-time directive definitions for Zenith.
+ * These are compiler directives, not runtime attributes.
+ */
+
+export interface DirectiveMetadata {
+    name: string;
+    category: 'control-flow' | 'iteration' | 'reactive-effect' | 'conditional-visibility';
+    description: string;
+    syntax: string;
+    placement: ('element' | 'component')[];
+    example: string;
+    createsScope?: boolean;
+    scopeVariables?: string[];
+}
+
+/**
+ * All Zenith compiler directives
+ * 
+ * These are processed at compile-time and transformed into static DOM instructions.
+ * The LSP must describe these directives without assuming runtime behavior.
+ */
+export const DIRECTIVES: Record<string, DirectiveMetadata> = {
+    'zen:if': {
+        name: 'zen:if',
+        category: 'control-flow',
+        description: 'Compile-time conditional directive. Conditionally renders the element based on a boolean expression.',
+        syntax: 'zen:if="condition"',
+        placement: ['element', 'component'],
+        example: '<div zen:if="isVisible">Conditionally rendered</div>'
+    },
+    'zen:for': {
+        name: 'zen:for',
+        category: 'iteration',
+        description: 'Compile-time iteration directive. Repeats the element for each item in a collection.',
+        syntax: 'zen:for="item in items" or zen:for="item, index in items"',
+        placement: ['element', 'component'],
+        example: '<li zen:for="item in items">{item.name}</li>',
+        createsScope: true,
+        scopeVariables: ['item', 'index']
+    },
+    'zen:effect': {
+        name: 'zen:effect',
+        category: 'reactive-effect',
+        description: 'Compile-time reactive effect directive. Attaches a side effect to the element lifecycle.',
+        syntax: 'zen:effect="expression"',
+        placement: ['element', 'component'],
+        example: '<div zen:effect="console.log(\'rendered\')">Content</div>'
+    },
+    'zen:show': {
+        name: 'zen:show',
+        category: 'conditional-visibility',
+        description: 'Compile-time visibility directive. Toggles element visibility without removing from DOM.',
+        syntax: 'zen:show="condition"',
+        placement: ['element', 'component'],
+        example: '<div zen:show="isOpen">Toggle visibility</div>'
+    }
+};
+
+/**
+ * Check if a string is a valid directive name
+ */
+export function isDirective(name: string): name is keyof typeof DIRECTIVES {
+    return name in DIRECTIVES;
+}
+
+/**
+ * Get directive metadata by name
+ */
+export function getDirective(name: string): DirectiveMetadata | undefined {
+    return DIRECTIVES[name];
+}
+
+/**
+ * Get all directive names
+ */
+export function getDirectiveNames(): string[] {
+    return Object.keys(DIRECTIVES);
+}
+
+/**
+ * Check if a directive can be placed on a specific element type
+ */
+export function canPlaceDirective(directiveName: string, elementType: 'element' | 'component' | 'slot'): boolean {
+    const directive = DIRECTIVES[directiveName];
+    if (!directive) return false;
+    
+    // Directives cannot be placed on <slot>
+    if (elementType === 'slot') return false;
+    
+    return directive.placement.includes(elementType as 'element' | 'component');
+}
+
+/**
+ * Parse a zen:for expression to extract variables
+ */
+export function parseForExpression(expression: string): { itemVar: string; indexVar?: string; source: string } | null {
+    // Match: "item in items" or "item, index in items"
+    const match = expression.match(/^\s*([a-zA-Z_$][\w$]*)(?:\s*,\s*([a-zA-Z_$][\w$]*))?\s+in\s+(.+)\s*$/);
+    if (!match) return null;
+    
+    return {
+        itemVar: match[1],
+        indexVar: match[2],
+        source: match[3].trim()
+    };
+}

package/src/metadata/plugin-imports.ts

@@ -0,0 +1,116 @@
+/**
+ * Plugin Import Metadata
+ * 
+ * Static metadata for Zenith plugin modules.
+ * Plugin modules use the zenith:* namespace.
+ * 
+ * Important: The LSP must NOT assume plugin presence.
+ * If a plugin is not installed, diagnostics should be soft warnings, not errors.
+ */
+
+export interface PluginExport {
+    name: string;
+    kind: 'function' | 'type' | 'variable';
+    description: string;
+    signature?: string;
+}
+
+export interface PluginModuleMetadata {
+    module: string;
+    description: string;
+    exports: PluginExport[];
+    required: boolean;
+}
+
+/**
+ * Known Zenith plugin modules
+ */
+export const PLUGIN_MODULES: Record<string, PluginModuleMetadata> = {
+    'zenith:content': {
+        module: 'zenith:content',
+        description: 'Content collections plugin for Zenith. Provides type-safe content management for Markdown, MDX, and JSON files.',
+        exports: [
+            {
+                name: 'zenCollection',
+                kind: 'function',
+                description: 'Define a content collection with schema validation.',
+                signature: 'zenCollection<T>(options: { name: string; schema: T }): Collection<T>'
+            },
+            {
+                name: 'getCollection',
+                kind: 'function',
+                description: 'Get all entries from a content collection.',
+                signature: 'getCollection(name: string): Promise<CollectionEntry[]>'
+            },
+            {
+                name: 'getEntry',
+                kind: 'function',
+                description: 'Get a single entry from a content collection.',
+                signature: 'getEntry(collection: string, slug: string): Promise<CollectionEntry | undefined>'
+            },
+            {
+                name: 'useZenOrder',
+                kind: 'function',
+                description: 'Hook to sort collection entries by frontmatter order field.',
+                signature: 'useZenOrder(entries: CollectionEntry[]): CollectionEntry[]'
+            }
+        ],
+        required: false
+    },
+    'zenith:image': {
+        module: 'zenith:image',
+        description: 'Image optimization plugin for Zenith.',
+        exports: [
+            {
+                name: 'Image',
+                kind: 'function',
+                description: 'Optimized image component with automatic format conversion and lazy loading.',
+                signature: 'Image({ src: string; alt: string; width?: number; height?: number })'
+            },
+            {
+                name: 'getImage',
+                kind: 'function',
+                description: 'Get optimized image metadata.',
+                signature: 'getImage(src: string, options?: ImageOptions): Promise<ImageMetadata>'
+            }
+        ],
+        required: false
+    }
+};
+
+/**
+ * Get a plugin module by name
+ */
+export function getPluginModule(moduleName: string): PluginModuleMetadata | undefined {
+    return PLUGIN_MODULES[moduleName];
+}
+
+/**
+ * Get all plugin module names
+ */
+export function getPluginModuleNames(): string[] {
+    return Object.keys(PLUGIN_MODULES);
+}
+
+/**
+ * Get an export from a plugin module
+ */
+export function getPluginExport(moduleName: string, exportName: string): PluginExport | undefined {
+    const module = PLUGIN_MODULES[moduleName];
+    if (!module) return undefined;
+    return module.exports.find(e => e.name === exportName);
+}
+
+/**
+ * Check if a module is a plugin module (zenith:* namespace)
+ */
+export function isPluginModule(moduleName: string): boolean {
+    return moduleName.startsWith('zenith:');
+}
+
+/**
+ * Check if a plugin module is known
+ */
+export function isKnownPluginModule(moduleName: string): boolean {
+    return moduleName in PLUGIN_MODULES;
+}

package/src/project.ts

@@ -0,0 +1,167 @@
+/**
+ * Zenith Project Graph
+ * 
+ * Uses the compiler's discovery logic to build a project graph
+ * Ensures LSP understands the same structure as the compiler
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface ComponentInfo {
+    name: string;
+    filePath: string;
+    type: 'layout' | 'component' | 'page';
+    props: string[];
+}
+
+export interface ProjectGraph {
+    root: string;
+    layouts: Map<string, ComponentInfo>;
+    components: Map<string, ComponentInfo>;
+    pages: Map<string, ComponentInfo>;
+}
+
+/**
+ * Detect Zenith project root
+ * Looks for zenith.config.ts, src/, or app/
+ */
+export function detectProjectRoot(startPath: string): string | null {
+    let current = startPath;
+
+    while (current !== path.dirname(current)) {
+        // Check for zenith.config.ts
+        if (fs.existsSync(path.join(current, 'zenith.config.ts'))) {
+            return current;
+        }
+        // Check for src/ directory with Zenith files
+        const srcDir = path.join(current, 'src');
+        if (fs.existsSync(srcDir)) {
+            const hasPages = fs.existsSync(path.join(srcDir, 'pages'));
+            const hasLayouts = fs.existsSync(path.join(srcDir, 'layouts'));
+            if (hasPages || hasLayouts) {
+                return current;
+            }
+        }
+        // Check for app/ directory
+        const appDir = path.join(current, 'app');
+        if (fs.existsSync(appDir)) {
+            const hasPages = fs.existsSync(path.join(appDir, 'pages'));
+            const hasLayouts = fs.existsSync(path.join(appDir, 'layouts'));
+            if (hasPages || hasLayouts) {
+                return current;
+            }
+        }
+        current = path.dirname(current);
+    }
+
+    return null;
+}
+
+/**
+ * Extract props from a .zen file
+ * Infers props from usage patterns (Astro/Vue style)
+ */
+function extractPropsFromFile(filePath: string): string[] {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const props: string[] = [];
+
+        // Look for Props interface/type
+        const propsMatch = content.match(/(?:interface|type)\s+Props\s*[={]\s*\{([^}]+)\}/);
+        if (propsMatch && propsMatch[1]) {
+            const propNames = propsMatch[1].match(/([a-zA-Z_$][a-zA-Z0-9_$?]*)\s*[?:]?\s*:/g);
+            if (propNames) {
+                for (const p of propNames) {
+                    const name = p.replace(/[?:\s]/g, '');
+                    if (name && !props.includes(name)) {
+                        props.push(name);
+                    }
+                }
+            }
+        }
+
+        // Look for common prop patterns in expressions
+        const usagePatterns = content.matchAll(/\{(title|lang|className|children|href|src|alt|id|name)\}/g);
+        for (const match of usagePatterns) {
+            if (match[1] && !props.includes(match[1])) {
+                props.push(match[1]);
+            }
+        }
+
+        return props;
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Discover all .zen files in a directory
+ */
+function discoverZenFiles(dir: string, type: 'layout' | 'component' | 'page'): Map<string, ComponentInfo> {
+    const result = new Map<string, ComponentInfo>();
+
+    if (!fs.existsSync(dir)) {
+        return result;
+    }
+
+    function scanDir(currentDir: string) {
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+
+            if (entry.isDirectory()) {
+                scanDir(fullPath);
+            } else if (entry.name.endsWith('.zen')) {
+                const name = path.basename(entry.name, '.zen');
+                const props = extractPropsFromFile(fullPath);
+
+                result.set(name, {
+                    name,
+                    filePath: fullPath,
+                    type,
+                    props
+                });
+            }
+        }
+    }
+
+    scanDir(dir);
+    return result;
+}
+
+/**
+ * Build project graph from root directory
+ */
+export function buildProjectGraph(root: string): ProjectGraph {
+    const srcDir = fs.existsSync(path.join(root, 'src')) ? path.join(root, 'src') : path.join(root, 'app');
+
+    const layouts = discoverZenFiles(path.join(srcDir, 'layouts'), 'layout');
+    const components = discoverZenFiles(path.join(srcDir, 'components'), 'component');
+    const pages = discoverZenFiles(path.join(srcDir, 'pages'), 'page');
+
+    return {
+        root,
+        layouts,
+        components,
+        pages
+    };
+}
+
+/**
+ * Resolve a component/layout by name
+ */
+export function resolveComponent(graph: ProjectGraph, name: string): ComponentInfo | undefined {
+    // Check layouts first (common pattern for <DefaultLayout>)
+    if (graph.layouts.has(name)) {
+        return graph.layouts.get(name);
+    }
+
+    // Then components
+    if (graph.components.has(name)) {
+        return graph.components.get(name);
+    }
+
+    return undefined;
+}

package/src/router.ts

@@ -0,0 +1,180 @@
+/**
+ * Router Awareness
+ * 
+ * Special support for Zenith Router features.
+ * The LSP provides router-aware completions and hovers when zenith/router is imported.
+ * 
+ * Important: No route file system assumptions or runtime navigation simulation.
+ */
+
+export interface RouterHookMetadata {
+    name: string;
+    owner: string;
+    description: string;
+    restrictions: string;
+    returns: string;
+    signature: string;
+}
+
+export interface ZenLinkPropMetadata {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+}
+
+export interface RouteFieldMetadata {
+    name: string;
+    type: string;
+    description: string;
+}
+
+/**
+ * Router hook definitions
+ */
+export const ROUTER_HOOKS: Record<string, RouterHookMetadata> = {
+    useRoute: {
+        name: 'useRoute',
+        owner: 'Router Hook (zenith/router)',
+        description: 'Provides reactive access to the current route state.',
+        restrictions: 'Must be called at top-level script scope.',
+        returns: '{ path: string; params: Record<string, string>; query: Record<string, string> }',
+        signature: 'useRoute(): RouteState'
+    },
+    useRouter: {
+        name: 'useRouter',
+        owner: 'Router Hook (zenith/router)',
+        description: 'Provides programmatic navigation methods.',
+        restrictions: 'Must be called at top-level script scope.',
+        returns: '{ navigate, back, forward, go }',
+        signature: 'useRouter(): Router'
+    }
+};
+
+/**
+ * ZenLink component props
+ */
+export const ZENLINK_PROPS: ZenLinkPropMetadata[] = [
+    {
+        name: 'to',
+        type: 'string',
+        required: true,
+        description: 'The route path to navigate to.'
+    },
+    {
+        name: 'preload',
+        type: 'boolean',
+        required: false,
+        description: 'Whether to prefetch the route on hover.'
+    },
+    {
+        name: 'replace',
+        type: 'boolean',
+        required: false,
+        description: 'Whether to replace the current history entry instead of pushing a new one.'
+    },
+    {
+        name: 'class',
+        type: 'string',
+        required: false,
+        description: 'CSS class to apply to the link.'
+    },
+    {
+        name: 'activeClass',
+        type: 'string',
+        required: false,
+        description: 'CSS class to apply when the link is active.'
+    }
+];
+
+/**
+ * Route state fields available from useRoute()
+ */
+export const ROUTE_FIELDS: RouteFieldMetadata[] = [
+    {
+        name: 'path',
+        type: 'string',
+        description: 'The current route path (e.g., "/blog/my-post").'
+    },
+    {
+        name: 'params',
+        type: 'Record<string, string>',
+        description: 'Dynamic route parameters (e.g., { slug: "my-post" }).'
+    },
+    {
+        name: 'query',
+        type: 'Record<string, string>',
+        description: 'Query string parameters (e.g., { page: "1" }).'
+    }
+];
+
+/**
+ * Router navigation functions
+ */
+export const ROUTER_FUNCTIONS = [
+    {
+        name: 'navigate',
+        description: 'Navigate to a route programmatically.',
+        signature: 'navigate(to: string, options?: { replace?: boolean }): void'
+    },
+    {
+        name: 'prefetch',
+        description: 'Prefetch a route for faster navigation.',
+        signature: 'prefetch(path: string): Promise<void>'
+    },
+    {
+        name: 'isActive',
+        description: 'Check if a route is currently active.',
+        signature: 'isActive(path: string, exact?: boolean): boolean'
+    },
+    {
+        name: 'back',
+        description: 'Navigate back in history.',
+        signature: 'back(): void'
+    },
+    {
+        name: 'forward',
+        description: 'Navigate forward in history.',
+        signature: 'forward(): void'
+    },
+    {
+        name: 'go',
+        description: 'Navigate to a specific history entry.',
+        signature: 'go(delta: number): void'
+    }
+];
+
+/**
+ * Get router hook metadata
+ */
+export function getRouterHook(name: string): RouterHookMetadata | undefined {
+    return ROUTER_HOOKS[name];
+}
+
+/**
+ * Check if a name is a router hook
+ */
+export function isRouterHook(name: string): boolean {
+    return name in ROUTER_HOOKS;
+}
+
+/**
+ * Get ZenLink prop metadata
+ */
+export function getZenLinkProp(name: string): ZenLinkPropMetadata | undefined {
+    return ZENLINK_PROPS.find(p => p.name === name);
+}
+
+/**
+ * Get all ZenLink prop names
+ */
+export function getZenLinkPropNames(): string[] {
+    return ZENLINK_PROPS.map(p => p.name);
+}
+
+/**
+ * Get route field metadata
+ */
+export function getRouteField(name: string): RouteFieldMetadata | undefined {
+    return ROUTE_FIELDS.find(f => f.name === name);
+}