@oml/server 0.14.0

package/src/rest/template.ts

@@ -0,0 +1,276 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+    extractLeadingFrontMatter,
+    parseTemplateComposeDirective,
+    parseTemplateDefinition,
+    renderTemplate,
+    type TemplateBindingSource,
+    type TemplateDefinition,
+    type TemplateInvocation,
+    type TemplateValue,
+} from '@oml/markdown';
+
+export type TemplateCatalogEntry = {
+    sourcePath: string;
+    definition: TemplateDefinition;
+};
+
+export type TemplateRenderContext = {
+    workspaceRoot: string;
+    sourceMarkdownPath: string;
+    contextOntologyIri?: string;
+    contextModelUri?: string;
+    contextMemberIri?: string;
+};
+
+export function isTemplateMarkdownFile(content: string): boolean {
+    const frontMatter = extractLeadingFrontMatter(content);
+    if (!frontMatter?.data || typeof frontMatter.data !== 'object' || Array.isArray(frontMatter.data)) {
+        return false;
+    }
+    return Object.prototype.hasOwnProperty.call(frontMatter.data, 'template');
+}
+
+export function frontMatterString(data: Record<string, unknown> | undefined, key: string): string | undefined {
+    if (!data) {
+        return undefined;
+    }
+    const value = data[key];
+    return typeof value === 'string' ? value : undefined;
+}
+
+export function normalizeContextOntologyIri(value: string | undefined): string | undefined {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return trimmed.replace(/^<|>$/g, '').replace(/[\/#]+$/, '');
+}
+
+export async function findFilesByExtension(root: string, extension: string): Promise<string[]> {
+    const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+    const files: string[] = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+                continue;
+            }
+            files.push(...await findFilesByExtension(fullPath, extension));
+            continue;
+        }
+        if (entry.isFile() && fullPath.toLowerCase().endsWith(extension.toLowerCase())) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+
+export async function buildTemplateCatalog(workspaceRoot: string): Promise<ReadonlyMap<string, TemplateCatalogEntry[]>> {
+    const byId = new Map<string, TemplateCatalogEntry[]>();
+    const markdownFiles = await findFilesByExtension(workspaceRoot, '.md');
+    for (const filePath of markdownFiles) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const sourceUri = pathToFileURL(filePath).toString();
+        const definition = parseTemplateDefinition(content, sourceUri);
+        if (!definition) {
+            continue;
+        }
+        appendTemplateEntry(byId, filePath, definition);
+    }
+    for (const [id, entries] of byId.entries()) {
+        entries.sort((left, right) => {
+            const leftRank = Number.isFinite(left.definition.rank) ? Number(left.definition.rank) : 0;
+            const rightRank = Number.isFinite(right.definition.rank) ? Number(right.definition.rank) : 0;
+            if (leftRank !== rightRank) {
+                return rightRank - leftRank;
+            }
+            return left.sourcePath.localeCompare(right.sourcePath);
+        });
+        byId.set(id, entries);
+    }
+    return byId;
+}
+
+function appendTemplateEntry(
+    index: Map<string, TemplateCatalogEntry[]>,
+    sourcePath: string,
+    definition: TemplateDefinition,
+): void {
+    const id = normalizeTemplateId(definition.id);
+    if (!id) {
+        return;
+    }
+    const existing = index.get(id) ?? [];
+    existing.push({ sourcePath, definition: { ...definition, id } });
+    index.set(id, existing);
+}
+
+export async function expandTemplateComposeBlocks(
+    markdown: string,
+    templateCatalog: ReadonlyMap<string, TemplateCatalogEntry[]>,
+    context: TemplateRenderContext,
+): Promise<string> {
+    const maxExpansionPasses = 12;
+    let current = markdown;
+    for (let pass = 0; pass < maxExpansionPasses; pass++) {
+        const composeBlockPattern = /```template[^\n]*\r?\n([\s\S]*?)\r?\n```/g;
+        let replaced = '';
+        let lastIndex = 0;
+        let expandedAny = false;
+        let match: RegExpExecArray | null;
+        while ((match = composeBlockPattern.exec(current)) !== null) {
+            expandedAny = true;
+            const blockStart = match.index;
+            const blockEnd = match.index + match[0].length;
+            replaced += current.slice(lastIndex, blockStart);
+            const directiveSource = match[1] ?? '';
+            const directive = parseTemplateComposeDirective(directiveSource);
+            if (!directive) {
+                throw new Error(`Invalid template compose block in ${context.sourceMarkdownPath}.`);
+            }
+            const template = selectTemplateDefinition(templateCatalog, directive.id);
+            if (!template) {
+                throw new Error(`No markdown template found for id '${directive.id}' in ${context.sourceMarkdownPath}.`);
+            }
+            const invocationArgs: Record<string, TemplateValue> = { ...directive.args };
+            for (const [parameterId, source] of Object.entries(directive.bind)) {
+                const value = resolveTemplateBindingValue(source, context);
+                if (value !== undefined) {
+                    invocationArgs[parameterId] = value;
+                }
+            }
+            const selection = context.contextMemberIri ? [context.contextMemberIri.trim()] : [];
+            const invocation: TemplateInvocation = {
+                templateId: template.definition.id,
+                mode: 'compose',
+                context: {
+                    invocation: {
+                        mode: 'compose',
+                        sourceDocumentUri: pathToFileURL(context.sourceMarkdownPath).toString(),
+                        referenceDocumentUri: pathToFileURL(context.sourceMarkdownPath).toString(),
+                    },
+                    model: {
+                        ontologyIri: context.contextOntologyIri,
+                        modelUri: context.contextModelUri,
+                    },
+                    focus: {
+                        memberIri: context.contextMemberIri,
+                    },
+                    selection: {
+                        iris: selection,
+                    },
+                },
+                args: invocationArgs,
+            };
+            const rendered = renderTemplate(template.definition, invocation);
+            if (rendered.missingRequired.length > 0) {
+                throw new Error(
+                    `Template '${template.definition.id}' is missing required parameter(s): ${rendered.missingRequired.join(', ')}.`
+                );
+            }
+            replaced += absolutizeTemplateHrefValues(
+                rendered.output,
+                template.sourcePath,
+                context.sourceMarkdownPath,
+                context.workspaceRoot
+            );
+            lastIndex = blockEnd;
+        }
+        if (!expandedAny) {
+            return current;
+        }
+        replaced += current.slice(lastIndex);
+        current = replaced;
+    }
+    throw new Error(`Template compose expansion exceeded ${maxExpansionPasses} passes in ${context.sourceMarkdownPath}.`);
+}
+
+function selectTemplateDefinition(
+    templateCatalog: ReadonlyMap<string, TemplateCatalogEntry[]>,
+    templateId: string,
+): TemplateCatalogEntry | undefined {
+    const normalized = normalizeTemplateId(templateId);
+    if (!normalized) {
+        return undefined;
+    }
+    const candidates = templateCatalog.get(normalized);
+    return candidates?.[0];
+}
+
+function resolveTemplateBindingValue(
+    source: TemplateBindingSource,
+    context: TemplateRenderContext,
+): TemplateValue | undefined {
+    const member = context.contextMemberIri?.trim();
+    const ontology = context.contextOntologyIri?.trim();
+    const modelUri = context.contextModelUri?.trim();
+    const selection = member ? [member] : [];
+    if (source === 'context.member') {
+        return member || undefined;
+    }
+    if (source === 'context.ontology') {
+        return ontology || undefined;
+    }
+    if (source === 'context.modelUri') {
+        return modelUri || undefined;
+    }
+    if (source === 'context.selection[*]') {
+        return selection;
+    }
+    if (source === 'user') {
+        return undefined;
+    }
+    const indexedSelection = /^context\.selection\[(\d+)]$/.exec(source);
+    if (!indexedSelection) {
+        return undefined;
+    }
+    const index = Number.parseInt(indexedSelection[1] ?? '', 10);
+    if (!Number.isFinite(index) || index < 0 || index >= selection.length) {
+        return undefined;
+    }
+    return selection[index];
+}
+
+function normalizeTemplateId(value: string): string {
+    let normalized = value.trim();
+    const wikilinkMatch = /^\[\[([^\]]+)\]\]$/.exec(normalized);
+    if (wikilinkMatch) {
+        normalized = (wikilinkMatch[1] ?? '').trim();
+    }
+    return normalized.replace(/^<|>$/g, '');
+}
+
+function absolutizeTemplateHrefValues(
+    markdown: string,
+    templateSourcePath: string,
+    referenceMarkdownPath: string,
+    workspaceRoot: string,
+): string {
+    const templateDir = path.dirname(templateSourcePath);
+    return markdown.replace(/(\bhref\s*:\s*)(["']?)([^"'\r\n]+)\2/g, (_m, prefix: string, quote: string, raw: string) => {
+        const value = raw.trim();
+        if (!value || value.startsWith('#') || value.startsWith('data:') || value.startsWith('workspace:/')) {
+            return `${prefix}${quote}${value}${quote}`;
+        }
+        if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
+            return `${prefix}${quote}${value}${quote}`;
+        }
+        const resolved = path.resolve(templateDir, value);
+        const relative = path.relative(workspaceRoot, resolved);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            return `${prefix}${quote}${value}${quote}`;
+        }
+        const referenceDir = path.dirname(referenceMarkdownPath);
+        const fromReference = path.relative(referenceDir, resolved).split(path.sep).join('/');
+        const normalized = fromReference.startsWith('.') ? fromReference : `./${fromReference}`;
+        return `${prefix}${quote}${normalized}${quote}`;
+    });
+}