sdocs 0.0.3 → 0.0.4

package/dist/server/meta-parser.js

@@ -0,0 +1,107 @@
+import { parse } from 'svelte/compiler';
+import { readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+/** Extract meta and imports from a .sdoc file */
+export async function parseDocFile(filePath) {
+    const source = await readFile(filePath, 'utf-8');
+    return parseDocSource(source, filePath);
+}
+/** Parse meta from .sdoc source */
+export function parseDocSource(source, filePath) {
+    const ast = parse(source, { modern: true });
+    const scriptContent = extractScriptContent(source);
+    if (!scriptContent) {
+        return {
+            meta: { title: guessTitle(filePath) },
+            componentPath: null,
+            imports: [],
+        };
+    }
+    const imports = extractImports(scriptContent);
+    const meta = extractMeta(scriptContent);
+    const componentPath = resolveComponentPath(meta, imports, filePath);
+    return { meta, componentPath, imports };
+}
+/** Extract the content of the <script> tag */
+function extractScriptContent(source) {
+    const match = source.match(/<script[^>]*>([\s\S]*?)<\/script>/);
+    return match ? match[1] : null;
+}
+/** Extract import statements */
+function extractImports(scriptContent) {
+    const imports = [];
+    const regex = /^\s*import\s+.+$/gm;
+    let match;
+    while ((match = regex.exec(scriptContent)) !== null) {
+        imports.push(match[0].trim());
+    }
+    return imports;
+}
+/** Extract meta object from `export const meta = { ... }` using brace counting */
+function extractMeta(scriptContent) {
+    // Find where the meta object starts
+    const startMatch = scriptContent.match(/export\s+const\s+meta\s*(?::\s*\w+\s*)?=\s*\{/);
+    if (!startMatch || startMatch.index === undefined)
+        return { title: 'Untitled' };
+    // Find the opening brace
+    const braceStart = startMatch.index + startMatch[0].length - 1;
+    let depth = 1;
+    let i = braceStart + 1;
+    // Count braces to find the matching closing brace
+    while (i < scriptContent.length && depth > 0) {
+        const ch = scriptContent[i];
+        if (ch === '{')
+            depth++;
+        else if (ch === '}')
+            depth--;
+        // Skip strings
+        else if (ch === "'" || ch === '"' || ch === '`') {
+            i++;
+            while (i < scriptContent.length && scriptContent[i] !== ch) {
+                if (scriptContent[i] === '\\')
+                    i++; // skip escaped chars
+                i++;
+            }
+        }
+        i++;
+    }
+    const metaStr = scriptContent.slice(braceStart, i);
+    try {
+        // Replace component: Identifier with component: 'Identifier'
+        const cleaned = metaStr.replace(/component:\s*([A-Z]\w*)/, "component: '$1'");
+        const fn = new Function(`return (${cleaned})`);
+        const result = fn();
+        return result;
+    }
+    catch {
+        return extractMetaFields(metaStr);
+    }
+}
+/** Fallback: extract meta fields with regex */
+function extractMetaFields(metaStr) {
+    const title = metaStr.match(/title:\s*['"](.+?)['"]/)?.[1] ?? 'Untitled';
+    const description = metaStr.match(/description:\s*['"](.+?)['"]/)?.[1];
+    return { title, description };
+}
+/** Resolve the component import path to an absolute path */
+function resolveComponentPath(meta, imports, docFilePath) {
+    // meta.component is the identifier name (e.g. 'Button')
+    const componentName = typeof meta.component === 'string' ? meta.component : null;
+    if (!componentName)
+        return null;
+    // Find the import that imports this name
+    for (const imp of imports) {
+        // Match: import Name from './path'
+        const match = imp.match(new RegExp(`import\\s+${componentName}\\s+from\\s+['"](.+?)['"]`));
+        if (match) {
+            const importPath = match[1];
+            return resolve(dirname(docFilePath), importPath);
+        }
+    }
+    return null;
+}
+/** Guess a title from the file path */
+function guessTitle(filePath) {
+    const fileName = filePath.split('/').pop() ?? '';
+    return fileName.replace(/\.(sdoc|sdocx)$/, '').replace(/\./g, ' ');
+}

package/dist/server/prop-parser.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentData } from '../types.js';
+/** Parse all component data from a Svelte component file */
+export declare function parseComponent(filePath: string): Promise<ComponentData>;
+/** Parse component data from source */
+export declare function parseComponentSource(source: string): ComponentData;

package/dist/server/prop-parser.js

@@ -0,0 +1,275 @@
+import { readFile } from 'node:fs/promises';
+import ts from 'typescript';
+/** Parse all component data from a Svelte component file */
+export async function parseComponent(filePath) {
+    const source = await readFile(filePath, 'utf-8');
+    return parseComponentSource(source);
+}
+/** Parse component data from source */
+export function parseComponentSource(source) {
+    const scriptContent = extractScriptContent(source);
+    const styleContent = extractStyleContent(source);
+    let props = [];
+    let methods = [];
+    let state = [];
+    if (scriptContent) {
+        const tsAst = ts.createSourceFile('component.ts', scriptContent, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const interfaceProps = parseInterfaceProps(tsAst);
+        const destructuredProps = parsePropsDestructuring(tsAst);
+        const jsdocData = parseJsdocComments(tsAst);
+        props = mergeProps(interfaceProps, destructuredProps, jsdocData);
+        methods = parseExportedFunctions(tsAst);
+        state = parseExportedState(tsAst);
+    }
+    const cssProps = styleContent ? parseCssProps(source, styleContent) : [];
+    return { props, methods, state, cssProps };
+}
+// ─── Script extraction ───
+function extractScriptContent(source) {
+    const match = source.match(/<script[^>]*>([\s\S]*?)<\/script>/);
+    return match ? match[1] : null;
+}
+function extractStyleContent(source) {
+    const match = source.match(/<style[^>]*>([\s\S]*?)<\/style>/);
+    return match ? match[1] : null;
+}
+function parseInterfaceProps(sourceFile) {
+    const props = [];
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isInterfaceDeclaration(node) && node.name.text === 'Props') {
+            for (const member of node.members) {
+                if (ts.isPropertySignature(member) && member.name) {
+                    const name = member.name.getText(sourceFile);
+                    const type = member.type
+                        ? member.type.getText(sourceFile)
+                        : 'unknown';
+                    const optional = !!member.questionToken;
+                    const description = getJsdocComment(member, sourceFile);
+                    props.push({ name, type, optional, description });
+                }
+            }
+        }
+    });
+    return props;
+}
+function parsePropsDestructuring(sourceFile) {
+    const props = [];
+    function visit(node) {
+        // Match: let { ... } = $props()
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            node.initializer.expression.getText(sourceFile) === '$props' &&
+            node.name &&
+            ts.isObjectBindingPattern(node.name)) {
+            for (const element of node.name.elements) {
+                if (ts.isBindingElement(element)) {
+                    const name = element.name.getText(sourceFile);
+                    const defaultValue = element.initializer
+                        ? element.initializer.getText(sourceFile)
+                        : null;
+                    props.push({ name, default: defaultValue });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return props;
+}
+function parseJsdocComments(sourceFile) {
+    // JSDoc data is already captured from interface Props via getJsdocComment
+    // This handles per-prop JSDoc in destructuring (JS components)
+    const data = [];
+    function visit(node) {
+        if (ts.isVariableDeclaration(node) &&
+            node.name &&
+            ts.isObjectBindingPattern(node.name)) {
+            for (const element of node.name.elements) {
+                if (ts.isBindingElement(element)) {
+                    const desc = getJsdocComment(element, sourceFile);
+                    if (desc) {
+                        data.push({
+                            name: element.name.getText(sourceFile),
+                            description: desc,
+                            type: null,
+                        });
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return data;
+}
+// ─── Merge props from all sources ───
+function mergeProps(interfaceProps, destructuredProps, jsdocData) {
+    const propMap = new Map();
+    // Start with interface props
+    for (const ip of interfaceProps) {
+        propMap.set(ip.name, {
+            name: ip.name,
+            type: ip.type,
+            default: null,
+            description: ip.description,
+            required: !ip.optional,
+            category: classifyProp(ip.name, ip.type),
+        });
+    }
+    // Merge destructured defaults
+    for (const dp of destructuredProps) {
+        const existing = propMap.get(dp.name);
+        if (existing) {
+            existing.default = dp.default;
+            if (dp.default !== null)
+                existing.required = false;
+        }
+        else {
+            propMap.set(dp.name, {
+                name: dp.name,
+                type: null,
+                default: dp.default,
+                description: null,
+                required: dp.default === null,
+                category: 'prop',
+            });
+        }
+    }
+    // Merge JSDoc descriptions
+    for (const jd of jsdocData) {
+        const existing = propMap.get(jd.name);
+        if (existing && !existing.description && jd.description) {
+            existing.description = jd.description;
+        }
+        if (existing && !existing.type && jd.type) {
+            existing.type = jd.type;
+        }
+    }
+    return Array.from(propMap.values());
+}
+// ─── Classify prop ───
+function classifyProp(name, type) {
+    if (name.startsWith('on') && type?.includes('=>'))
+        return 'event';
+    if (type?.startsWith('Snippet'))
+        return 'snippet';
+    return 'prop';
+}
+// ─── Exported functions ───
+function parseExportedFunctions(sourceFile) {
+    const methods = [];
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isFunctionDeclaration(node) &&
+            node.name &&
+            hasExportModifier(node)) {
+            const params = node.parameters
+                .map((p) => p.getText(sourceFile))
+                .join(', ');
+            const returnType = node.type
+                ? node.type.getText(sourceFile)
+                : null;
+            const description = getJsdocComment(node, sourceFile);
+            methods.push({
+                name: node.name.text,
+                params,
+                returnType,
+                description,
+            });
+        }
+    });
+    return methods;
+}
+// ─── Exported state ───
+function parseExportedState(sourceFile) {
+    const state = [];
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isVariableStatement(node) &&
+            hasExportModifier(node)) {
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name)) {
+                    const init = decl.initializer?.getText(sourceFile) ?? '';
+                    if (init.includes('$state') ||
+                        init.includes('$derived')) {
+                        const description = getJsdocComment(node, sourceFile);
+                        state.push({
+                            name: decl.name.text,
+                            type: decl.type
+                                ? decl.type.getText(sourceFile)
+                                : null,
+                            description,
+                        });
+                    }
+                }
+            }
+        }
+    });
+    return state;
+}
+// ─── CSS custom properties ───
+function parseCssProps(fullSource, styleContent) {
+    const propMap = new Map();
+    // Extract var(--name) and var(--name, default) from <style>
+    const varRegex = /var\(\s*(--[\w-]+)(?:\s*,\s*([^)]+))?\s*\)/g;
+    let match;
+    while ((match = varRegex.exec(styleContent)) !== null) {
+        const name = match[1];
+        const defaultVal = match[2]?.trim() ?? null;
+        propMap.set(name, {
+            name,
+            type: null,
+            default: defaultVal,
+            description: null,
+        });
+    }
+    // Extract @cssvar JSDoc annotations from <script>
+    const cssvarRegex = /@cssvar\s+\{(\w+)\}\s+(--[\w-]+)\s*-?\s*(.*?)(?:\(default:\s*([^)]+)\))?$/gm;
+    while ((match = cssvarRegex.exec(fullSource)) !== null) {
+        const type = match[1];
+        const name = match[2];
+        const description = match[3]?.trim() || null;
+        const defaultVal = match[4]?.trim() ?? null;
+        const existing = propMap.get(name);
+        if (existing) {
+            existing.type = type;
+            if (description)
+                existing.description = description;
+            if (defaultVal && !existing.default)
+                existing.default = defaultVal;
+        }
+        else {
+            propMap.set(name, { name, type, default: defaultVal, description });
+        }
+    }
+    return Array.from(propMap.values());
+}
+// ─── Helpers ───
+function getJsdocComment(node, sourceFile) {
+    const fullText = sourceFile.getFullText();
+    const ranges = ts.getLeadingCommentRanges(fullText, node.getFullStart());
+    if (!ranges)
+        return null;
+    for (const range of ranges) {
+        const comment = fullText.slice(range.pos, range.end);
+        if (comment.startsWith('/**')) {
+            // Extract text between /** and */
+            const text = comment
+                .replace(/^\/\*\*\s*/, '')
+                .replace(/\s*\*\/$/, '')
+                .replace(/^\s*\*\s?/gm, '')
+                .trim();
+            // Skip @tags
+            const firstLine = text.split('\n')[0];
+            if (firstLine && !firstLine.startsWith('@')) {
+                return firstLine;
+            }
+        }
+    }
+    return null;
+}
+function hasExportModifier(node) {
+    const modifiers = ts.canHaveModifiers(node)
+        ? ts.getModifiers(node)
+        : undefined;
+    return modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}

package/dist/server/sdocx-parser.d.ts

@@ -0,0 +1,11 @@
+import type { SdocMeta, ExtractedSnippet, TocHeading } from '../types.js';
+interface SdocxParseResult {
+    meta: SdocMeta;
+    componentPath: string | null;
+    imports: string[];
+    snippets: ExtractedSnippet[];
+    toc?: TocHeading[];
+}
+/** Parse a .sdocx file (markdown format) */
+export declare function parseSdocx(source: string, filePath: string, kind: 'component' | 'page' | 'layout'): Promise<SdocxParseResult>;
+export {};

package/dist/server/sdocx-parser.js

@@ -0,0 +1,197 @@
+import { compile } from 'mdsvex';
+import { resolve, dirname } from 'node:path';
+import { extractTocFromMarkdown } from './toc-extractor.js';
+/** Parse a .sdocx file (markdown format) */
+export async function parseSdocx(source, filePath, kind) {
+    // Compile the full source through mdsvex to extract frontmatter metadata
+    const compiled = await compile(source, { extension: '.sdocx' });
+    if (!compiled) {
+        return {
+            meta: { title: guessTitle(filePath) },
+            componentPath: null,
+            imports: [],
+            snippets: [],
+        };
+    }
+    // Extract metadata from the module script mdsvex generates
+    const metadata = extractMetadata(compiled.code);
+    const { title, description } = extractTitleAndDescription(source);
+    const meta = {
+        title: title ?? guessTitle(filePath),
+        description,
+        args: metadata.args,
+        settings: metadata.settings,
+    };
+    // Resolve component path for component kind
+    let componentPath = null;
+    if (kind === 'component' && metadata.component) {
+        componentPath = resolve(dirname(filePath), metadata.component);
+    }
+    // Extract user <script> imports (not the module script mdsvex adds)
+    const imports = extractUserImports(source);
+    // Auto-import the component if specified and not already imported
+    if (componentPath && metadata.component) {
+        const componentName = componentPath.split('/').pop()?.replace('.svelte', '') ?? '';
+        const hasImport = imports.some((imp) => imp.includes(componentName));
+        if (!hasImport && componentName) {
+            imports.unshift(`import ${componentName} from '${metadata.component}'`);
+        }
+    }
+    let snippets;
+    let toc;
+    if (kind === 'component') {
+        snippets = await extractComponentSnippets(source, compiled.code);
+    }
+    else {
+        // Page/layout: the entire body is one "Content" snippet
+        const body = extractMarkdownBody(source);
+        const compiledBody = await compile(body, { extension: '.sdocx' });
+        const htmlBody = compiledBody
+            ? removeModuleScript(compiledBody.code)
+            : body;
+        snippets = [{ name: 'Content', body: htmlBody }];
+        if (kind === 'page') {
+            toc = extractTocFromMarkdown(body);
+        }
+    }
+    return { meta, componentPath, imports, snippets, toc };
+}
+/** Extract metadata from the mdsvex-generated module script */
+function extractMetadata(code) {
+    const match = code.match(/export\s+const\s+metadata\s*=\s*(\{[\s\S]*?\});/);
+    if (!match)
+        return {};
+    try {
+        return JSON.parse(match[1]);
+    }
+    catch {
+        return {};
+    }
+}
+/** Extract title (# heading) and description (first paragraph after #) from raw markdown */
+function extractTitleAndDescription(source) {
+    // Remove frontmatter
+    const body = source.replace(/^---[\s\S]*?---\s*/, '');
+    const lines = body.split('\n');
+    let title = null;
+    let description = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        if (line.startsWith('# ') && !title) {
+            title = line.slice(2).trim();
+            // Look for the first paragraph after the heading
+            for (let j = i + 1; j < lines.length; j++) {
+                const next = lines[j].trim();
+                if (!next)
+                    continue;
+                if (next.startsWith('#') || next.startsWith('<'))
+                    break;
+                description = next;
+                break;
+            }
+            break;
+        }
+    }
+    return { title, description };
+}
+/** Extract user-written <script> imports from raw markdown source */
+function extractUserImports(source) {
+    // Remove frontmatter first
+    const body = source.replace(/^---[\s\S]*?---\s*/, '');
+    const scriptMatch = body.match(/<script[^>]*>([\s\S]*?)<\/script>/);
+    if (!scriptMatch)
+        return [];
+    const imports = [];
+    const regex = /^\s*import\s+.+$/gm;
+    let match;
+    while ((match = regex.exec(scriptMatch[1])) !== null) {
+        imports.push(match[0].trim());
+    }
+    return imports;
+}
+/** Extract the markdown body after frontmatter, removing the # title and first description paragraph */
+function extractMarkdownBody(source) {
+    const body = source.replace(/^---[\s\S]*?---\s*/, '');
+    const lines = body.split('\n');
+    let startIndex = 0;
+    let foundTitle = false;
+    let skippedDescription = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        if (line.startsWith('# ') && !foundTitle) {
+            foundTitle = true;
+            startIndex = i + 1;
+            // Skip the description paragraph
+            for (let j = i + 1; j < lines.length; j++) {
+                const next = lines[j].trim();
+                if (!next)
+                    continue;
+                if (next.startsWith('#') || next.startsWith('<script')) {
+                    startIndex = j;
+                    skippedDescription = true;
+                    break;
+                }
+                // This is the description paragraph, skip it
+                startIndex = j + 1;
+                skippedDescription = true;
+                break;
+            }
+            break;
+        }
+    }
+    return lines.slice(startIndex).join('\n').trim();
+}
+/** Extract component snippets from ## sections in markdown */
+async function extractComponentSnippets(source, _compiledCode) {
+    const body = extractMarkdownBody(source);
+    const sections = splitBySections(body);
+    const snippets = [];
+    for (const section of sections) {
+        const compiled = await compile(section.body, { extension: '.sdocx' });
+        const html = compiled ? removeModuleScript(compiled.code) : section.body;
+        snippets.push({
+            name: section.name,
+            body: html.trim(),
+        });
+    }
+    return snippets;
+}
+/** Split markdown body by ## headings into named sections */
+function splitBySections(body) {
+    const sections = [];
+    const lines = body.split('\n');
+    let currentName = null;
+    let currentLines = [];
+    for (const line of lines) {
+        const headingMatch = line.match(/^##\s+(.+)$/);
+        if (headingMatch) {
+            if (currentName !== null) {
+                sections.push({ name: currentName, body: currentLines.join('\n').trim() });
+            }
+            currentName = headingMatch[1].trim();
+            currentLines = [];
+        }
+        else if (currentName !== null) {
+            currentLines.push(line);
+        }
+    }
+    if (currentName !== null) {
+        sections.push({ name: currentName, body: currentLines.join('\n').trim() });
+    }
+    return sections;
+}
+/** Remove the mdsvex-generated module script from compiled code */
+function removeModuleScript(code) {
+    return code.replace(/<script context="module">[\s\S]*?<\/script>\s*/, '').trim();
+}
+/** Guess a title from the file path */
+function guessTitle(filePath) {
+    const fileName = filePath.split('/').pop() ?? '';
+    return fileName
+        .replace(/\.(page|layout|component)?\.(sdoc|sdocx)$/, '')
+        .replace(/\./g, ' ');
+}

package/dist/server/snippet-compiler.d.ts

@@ -0,0 +1,27 @@
+/** Base64url encode a string (URL-safe, no padding) */
+export declare function base64urlEncode(str: string): string;
+/** Base64url decode */
+export declare function base64urlDecode(str: string): string;
+/** Resolve relative imports to absolute paths for use in virtual components */
+export declare function resolveImportsToAbsolute(imports: string[], docFilePath: string): string[];
+/** Generate a virtual Svelte iframe wrapper component for a snippet.
+ * Includes $state for reactive prop updates via postMessage. */
+export declare function generateIframeComponent(absoluteImports: string[], snippetBody: string): string;
+/** Generate the HTML page served inside the iframe */
+export declare function generatePreviewHtml(iframeComponentId: string, css: string | Record<string, string> | null): string;
+/** Build the virtual module ID for an iframe wrapper component */
+export declare function iframeVirtualId(docFilePath: string, snippetName: string): string;
+/** Build the preview URL for an iframe HTML page (dev mode) */
+export declare function previewUrl(docFilePath: string, snippetName: string): string;
+/** Build the preview URL for static build output */
+export declare function buildPreviewUrl(docFilePath: string, snippetName: string): string;
+/** Parse an iframe virtual ID back into its parts */
+export declare function parseIframeId(id: string): {
+    docFilePath: string;
+    snippetName: string;
+} | null;
+/** Parse a preview URL back into its parts */
+export declare function parsePreviewUrl(url: string): {
+    docFilePath: string;
+    snippetName: string;
+} | null;