@oml/markdown 0.7.0

package/src/md/md-executor.ts

@@ -0,0 +1,598 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import { deriveSelectQueryFromShape, type OwlConstructResult, type OwlQueryResult } from '@oml/owl';
+import type { Term } from '@rdfjs/types';
+import type { MdBlockExecutionResult, MdExecuteBlocksParams, MdExecuteBlocksResult } from './md-execution.js';
+
+export interface MarkdownExecutionBackend {
+    ensureContext(modelUri: string): Promise<void>;
+    resolveContextIri(modelUri: string): string;
+    countContextQuads?: (modelUri: string) => Promise<number>;
+    query(modelUri: string, sparql: string): Promise<OwlQueryResult>;
+    construct(modelUri: string, sparql: string): Promise<OwlConstructResult>;
+}
+
+export class MarkdownExecutor {
+    constructor(private readonly backend: MarkdownExecutionBackend) {}
+
+    async executeBlocks(params: MdExecuteBlocksParams): Promise<MdExecuteBlocksResult> {
+        const resolvedModelUri = params.modelUri?.trim() || undefined;
+        const contextQuadCount = resolvedModelUri && this.backend.countContextQuads
+            ? await this.backend.countContextQuads(resolvedModelUri)
+            : undefined;
+
+        if (resolvedModelUri) {
+            await this.backend.ensureContext(resolvedModelUri);
+        }
+
+        const results: MdBlockExecutionResult[] = [];
+        for (const block of params.blocks) {
+            try {
+                if (block.kind === 'table' || block.kind === 'table-editor' || block.kind === 'chart') {
+                    results.push(await this.executeTableBlock(block.kind, resolvedModelUri, block.id, block.source, block.options));
+                    continue;
+                }
+                if (block.kind === 'matrix') {
+                    results.push(await this.executeMatrixBlock(resolvedModelUri, block.id, block.source));
+                    continue;
+                }
+                if (block.kind === 'tree') {
+                    results.push(await this.executeTreeBlock(resolvedModelUri, block.id, block.source, block.options));
+                    continue;
+                }
+                if (block.kind === 'graph') {
+                    results.push(await this.executeGraphBlock(resolvedModelUri, block.id, block.source));
+                    continue;
+                }
+                if (block.kind === 'diagram') {
+                    results.push(await this.executeDiagramBlock(resolvedModelUri, block.id, block.source));
+                    continue;
+                }
+                if (block.kind === 'text') {
+                    results.push(await this.executeTextBlock(resolvedModelUri, block.id, block.source));
+                    continue;
+                }
+                if (block.kind === 'list') {
+                    results.push(await this.executeListBlock(resolvedModelUri, block.id, block.source));
+                    continue;
+                }
+                results.push({
+                    blockId: block.id,
+                    kind: block.kind,
+                    status: 'unimplemented',
+                    format: 'message',
+                    message: `${block.kind} blocks are not implemented yet.`
+                });
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                results.push({
+                    blockId: block.id,
+                    kind: block.kind,
+                    status: 'error',
+                    format: 'message',
+                    message: message || `${block.kind} block execution failed.`
+                });
+            }
+        }
+        return { results, contextQuadCount };
+    }
+
+    private async executeMatrixBlock(
+        modelUri: string | undefined,
+        blockId: string,
+        source: string
+    ): Promise<MdBlockExecutionResult> {
+        if (!modelUri) {
+            return missingContext(blockId, 'matrix');
+        }
+
+        const sparql = preprocessQuerySource(this.backend, modelUri, source);
+        const queryResult = await this.backend.query(modelUri, sparql);
+        if (!queryResult.success) {
+            return queryFailed(blockId, 'matrix', queryResult.error ?? 'SPARQL SELECT failed.');
+        }
+
+        const columns = extractSelectVariables(sparql);
+        const columnSet = new Set<string>(columns);
+        for (const row of queryResult.rows) {
+            for (const key of row.keys()) {
+                if (columnSet.has(key)) {
+                    continue;
+                }
+                columnSet.add(key);
+                columns.push(key);
+            }
+        }
+
+        const rows = queryResult.rows.map((row) => columns.map((column) => row.get(column)?.value ?? ''));
+        return okTable(blockId, 'matrix', columns, rows);
+    }
+
+    private async executeTableBlock(
+        kind: 'table' | 'table-editor' | 'chart',
+        modelUri: string | undefined,
+        blockId: string,
+        source: string,
+        options?: Record<string, unknown>
+    ): Promise<MdBlockExecutionResult> {
+        if (!modelUri) {
+            return missingContext(blockId, kind);
+        }
+
+        const preparedSource = preprocessQuerySource(this.backend, modelUri, source);
+        const ownGraphIri = this.backend.resolveContextIri(modelUri);
+        const derivedQuery = kind === 'table-editor'
+            ? deriveSelectQueryFromShape(preparedSource, ownGraphIri)
+            : undefined;
+        const sparql = kind === 'table-editor'
+            ? ensureOrderedByFirstVariable(derivedQuery?.sparql ?? preparedSource, derivedQuery?.columnVariables?.[0])
+            : (derivedQuery?.sparql ?? preparedSource);
+        if (kind === 'table-editor' && !derivedQuery) {
+            return queryFailed(blockId, kind, 'Unable to derive SPARQL SELECT query from table-editor block shape.');
+        }
+
+        const queryResult = await this.backend.query(modelUri, sparql);
+        if (!queryResult.success) {
+            return queryFailed(blockId, kind, queryResult.error ?? 'SPARQL SELECT failed.');
+        }
+
+        const variableColumns = kind === 'table-editor'
+            ? derivedQuery?.columnVariables.slice() ?? []
+            : extractSelectVariables(sparql);
+        const labelByVariable = kind === 'table-editor'
+            ? (derivedQuery?.columnLabels ?? new Map<string, string>())
+            : new Map<string, string>();
+        const optionLabelByVariable = extractColumnLabelOverrides(options);
+        for (const [variable, label] of optionLabelByVariable.entries()) {
+            labelByVariable.set(variable, label);
+        }
+        const columns = variableColumns;
+        const columnSet = new Set<string>(columns);
+        for (const row of queryResult.rows) {
+            for (const key of row.keys()) {
+                if (columnSet.has(key)) {
+                    continue;
+                }
+                columnSet.add(key);
+                columns.push(key);
+            }
+        }
+
+        const rows = queryResult.rows.map((row) => columns.map((column) => row.get(column)?.value ?? ''));
+        const displayColumns = columns.map((column) => labelByVariable.get(column) ?? column);
+        return okTable(blockId, kind, displayColumns, rows);
+    }
+
+    private async executeGraphBlock(
+        modelUri: string | undefined,
+        blockId: string,
+        source: string
+    ): Promise<MdBlockExecutionResult> {
+        if (!modelUri) {
+            return missingContext(blockId, 'graph');
+        }
+
+        const sparql = preprocessQuerySource(this.backend, modelUri, source);
+        const constructResult = await this.backend.construct(modelUri, sparql);
+        if (!constructResult.success) {
+            return queryFailed(blockId, 'graph', constructResult.error ?? 'SPARQL CONSTRUCT failed.');
+        }
+
+        return constructRowsResult(blockId, 'graph', constructResult);
+    }
+
+    private async executeDiagramBlock(
+        modelUri: string | undefined,
+        blockId: string,
+        source: string
+    ): Promise<MdBlockExecutionResult> {
+        if (!modelUri) {
+            return missingContext(blockId, 'diagram');
+        }
+
+        const sparql = preprocessQuerySource(this.backend, modelUri, source);
+        const constructResult = await this.backend.construct(modelUri, sparql);
+        if (!constructResult.success) {
+            return queryFailed(blockId, 'diagram', constructResult.error ?? 'SPARQL CONSTRUCT failed.');
+        }
+
+        return constructRowsResult(blockId, 'diagram', constructResult);
+    }
+
+    private async executeTreeBlock(
+        modelUri: string | undefined,
+        blockId: string,
+        source: string,
+        options?: Record<string, unknown>
+    ): Promise<MdBlockExecutionResult> {
+        if (!modelUri) {
+            return missingContext(blockId, 'tree');
+        }
+
+        const sparql = preprocessQuerySource(this.backend, modelUri, source);
+        const constructResult = await this.backend.construct(modelUri, sparql);
+        if (!constructResult.success) {
+            return queryFailed(blockId, 'tree', constructResult.error ?? 'SPARQL CONSTRUCT failed.');
+        }
+
+        const containmentNames = extractContainmentPropertyNames(options);
+        const focusOrder: string[] = [];
+        const focusSet = new Set<string>();
+        const valuesByFocus = new Map<string, Map<string, string[]>>();
+        const predicateToColumn = new Map<string, string>();
+        const usedColumns = new Set<string>(['focus']);
+        const columnOrder: string[] = [];
+        const columnLabelByVariable = new Map<string, string>([['focus', 'focus']]);
+
+        const addFocus = (focus: string): void => {
+            if (focusSet.has(focus)) {
+                return;
+            }
+            focusSet.add(focus);
+            focusOrder.push(focus);
+            valuesByFocus.set(focus, new Map<string, string[]>());
+        };
+        const addCellValue = (focus: string, column: string, value: string): void => {
+            const byColumn = valuesByFocus.get(focus);
+            if (!byColumn) {
+                return;
+            }
+            const values = byColumn.get(column) ?? [];
+            if (!values.includes(value)) {
+                values.push(value);
+                byColumn.set(column, values);
+            }
+        };
+
+        for (const quad of constructResult.quads) {
+            const focus = termToCellValue(quad.subject as Term);
+            addFocus(focus);
+
+            const predicateIri = quad.predicate.value;
+            let column = predicateToColumn.get(predicateIri);
+            if (!column) {
+                const base = normalizeSparqlVariableName(localName(predicateIri) || 'value');
+                column = uniqueVariableName(base, usedColumns);
+                usedColumns.add(column);
+                predicateToColumn.set(predicateIri, column);
+                columnOrder.push(column);
+                columnLabelByVariable.set(column, localName(predicateIri) || column);
+            }
+
+            const objectValue = termToCellValue(quad.object as Term);
+            addCellValue(focus, column, objectValue);
+
+            if (containmentNames.size > 0
+                && (quad.object.termType === 'NamedNode' || quad.object.termType === 'BlankNode')
+                && containmentNames.has(normalizePropertyIdentifier(predicateIri))) {
+                addFocus(objectValue);
+            }
+        }
+
+        const optionLabelByVariable = extractColumnLabelOverrides(options);
+        for (const [variable, label] of optionLabelByVariable.entries()) {
+            columnLabelByVariable.set(variable, label);
+        }
+
+        const columns = ['focus', ...columnOrder];
+        const displayColumns = columns.map((column) => columnLabelByVariable.get(column) ?? column);
+        const rows = focusOrder.map((focus) => {
+            const byColumn = valuesByFocus.get(focus) ?? new Map<string, string[]>();
+            return columns.map((column) => {
+                if (column === 'focus') {
+                    return focus;
+                }
+                return (byColumn.get(column) ?? []).join(', ');
+            });
+        });
+        return okTable(blockId, 'tree', displayColumns, rows);
+    }
+
+    private async executeTextBlock(
+        modelUri: string | undefined,
+        blockId: string,
+        source: string
+    ): Promise<MdBlockExecutionResult> {
+        if (!modelUri) {
+            return missingContext(blockId, 'text');
+        }
+
+        const sparql = preprocessQuerySource(this.backend, modelUri, source);
+        const queryResult = await this.backend.query(modelUri, sparql);
+        if (!queryResult.success) {
+            return queryFailed(blockId, 'text', queryResult.error ?? 'SPARQL SELECT failed.');
+        }
+
+        const selected = extractSelectVariables(sparql);
+        const firstVariable = selected[0] ?? queryResult.rows[0]?.keys().next().value;
+        if (!firstVariable) {
+            return queryFailed(blockId, 'text', 'Text block requires at least one SELECT variable.');
+        }
+
+        const columns = [firstVariable];
+        const columnSet = new Set<string>(columns);
+        for (const row of queryResult.rows) {
+            for (const key of row.keys()) {
+                if (columnSet.has(key)) {
+                    continue;
+                }
+                columnSet.add(key);
+                columns.push(key);
+            }
+        }
+        const rows = queryResult.rows.map((row) => columns.map((column) => row.get(column)?.value ?? ''));
+        return okTable(blockId, 'text', columns, rows);
+    }
+
+    private async executeListBlock(
+        modelUri: string | undefined,
+        blockId: string,
+        source: string
+    ): Promise<MdBlockExecutionResult> {
+        if (!modelUri) {
+            return missingContext(blockId, 'list');
+        }
+
+        const sparql = preprocessQuerySource(this.backend, modelUri, source);
+        const queryResult = await this.backend.query(modelUri, sparql);
+        if (!queryResult.success) {
+            return queryFailed(blockId, 'list', queryResult.error ?? 'SPARQL SELECT failed.');
+        }
+
+        const selected = extractSelectVariables(sparql);
+        const firstVariable = selected[0] ?? queryResult.rows[0]?.keys().next().value;
+        if (!firstVariable) {
+            return queryFailed(blockId, 'list', 'List block requires at least one SELECT variable.');
+        }
+
+        const columns = [firstVariable];
+        const columnSet = new Set<string>(columns);
+        for (const row of queryResult.rows) {
+            for (const key of row.keys()) {
+                if (columnSet.has(key)) {
+                    continue;
+                }
+                columnSet.add(key);
+                columns.push(key);
+            }
+        }
+        const rows = queryResult.rows.map((row) => columns.map((column) => row.get(column)?.value ?? ''));
+        return okTable(blockId, 'list', columns, rows);
+    }
+}
+
+function preprocessQuerySource(backend: MarkdownExecutionBackend, modelUri: string, source: string): string {
+    if (!source.includes('${contextIri}')) {
+        return source;
+    }
+    return source.split('${contextIri}').join(backend.resolveContextIri(modelUri));
+}
+
+function missingContext(blockId: string, kind: MdBlockExecutionResult['kind']): MdBlockExecutionResult {
+    return queryFailed(blockId, kind, 'No contextUri model is available for this markdown document.');
+}
+
+function queryFailed(blockId: string, kind: MdBlockExecutionResult['kind'], message: string): MdBlockExecutionResult {
+    return {
+        blockId,
+        kind,
+        status: 'error',
+        format: 'message',
+        message,
+    };
+}
+
+function okTable(blockId: string, kind: MdBlockExecutionResult['kind'], columns: string[], rows: string[][]): MdBlockExecutionResult {
+    return {
+        blockId,
+        kind,
+        status: 'ok',
+        format: 'table',
+        payload: { columns, rows },
+    };
+}
+
+function constructRowsResult(
+    blockId: string,
+    kind: 'graph' | 'diagram',
+    constructResult: OwlConstructResult
+): MdBlockExecutionResult {
+    return okTable(
+        blockId,
+        kind,
+        ['subject', 'predicate', 'object'],
+        constructResult.quads.map((quad) => [
+            termToCellValue(quad.subject as Term),
+            termToCellValue(quad.predicate as Term),
+            termToCellValue(quad.object as Term),
+        ]),
+    );
+}
+
+function extractSelectVariables(sparql: string): string[] {
+    const match = /select\s+(?:distinct\s+|reduced\s+)?([\s\S]*?)\bwhere\b/i.exec(sparql);
+    if (!match) {
+        return [];
+    }
+    const variables: string[] = [];
+    for (const term of splitTopLevelProjectionTerms(match[1])) {
+        const trimmed = term.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const directVariable = /^\?([A-Za-z_][A-Za-z0-9_-]*)$/i.exec(trimmed);
+        if (directVariable) {
+            variables.push(`?${directVariable[1]}`);
+            continue;
+        }
+        const alias = /\bas\s+\?([A-Za-z_][A-Za-z0-9_-]*)\b/i.exec(trimmed);
+        if (alias) {
+            variables.push(`?${alias[1]}`);
+        }
+    }
+    const seen = new Set<string>();
+    const result: string[] = [];
+    for (const variable of variables) {
+        const name = variable.slice(1);
+        if (seen.has(name)) {
+            continue;
+        }
+        seen.add(name);
+        result.push(name);
+    }
+    return result;
+}
+
+function splitTopLevelProjectionTerms(rawProjection: string): string[] {
+    const terms: string[] = [];
+    let current = '';
+    let depth = 0;
+    let quote: '"' | '\'' | undefined;
+    for (let index = 0; index < rawProjection.length; index += 1) {
+        const char = rawProjection[index];
+        if (quote) {
+            current += char;
+            if (char === quote && rawProjection[index - 1] !== '\\') {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (char === '"' || char === '\'') {
+            quote = char;
+            current += char;
+            continue;
+        }
+        if (char === '(') {
+            depth += 1;
+            current += char;
+            continue;
+        }
+        if (char === ')') {
+            depth = Math.max(0, depth - 1);
+            current += char;
+            continue;
+        }
+        if (/\s/.test(char) && depth === 0) {
+            if (current.trim()) {
+                terms.push(current.trim());
+                current = '';
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim()) {
+        terms.push(current.trim());
+    }
+    return terms;
+}
+
+function ensureOrderedByFirstVariable(sparql: string, firstVariable: string | undefined): string {
+    const variable = (firstVariable ?? '').trim().replace(/^\?/, '');
+    if (!variable || /\border\s+by\b/i.test(sparql)) {
+        return sparql;
+    }
+    return `${sparql.trimEnd()}\nORDER BY ?${variable}`;
+}
+
+function extractColumnLabelOverrides(options: Record<string, unknown> | undefined): Map<string, string> {
+    const labels = new Map<string, string>();
+    const columns = options?.columns;
+    if (!isPlainObject(columns)) {
+        return labels;
+    }
+    for (const [variable, rawConfig] of Object.entries(columns)) {
+        if (typeof rawConfig === 'string') {
+            labels.set(variable, rawConfig);
+            continue;
+        }
+        if (!isPlainObject(rawConfig)) {
+            continue;
+        }
+        const label = rawConfig.label;
+        if (typeof label === 'string' && label.trim().length > 0) {
+            labels.set(variable, label);
+        }
+    }
+    return labels;
+}
+
+function extractContainmentPropertyNames(options: Record<string, unknown> | undefined): Set<string> {
+    const names = new Set<string>();
+    const containment = options?.containment;
+    if (!Array.isArray(containment)) {
+        return names;
+    }
+    for (const entry of containment) {
+        if (typeof entry !== 'string') {
+            continue;
+        }
+        const normalized = normalizePropertyIdentifier(entry);
+        if (normalized) {
+            names.add(normalized);
+        }
+    }
+    return names;
+}
+
+function normalizePropertyIdentifier(raw: string): string {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return '';
+    }
+    if (trimmed.includes(':')) {
+        return trimmed.slice(trimmed.lastIndexOf(':') + 1).trim().toLowerCase();
+    }
+    return localName(trimmed).trim().toLowerCase();
+}
+
+function termToCellValue(term: Term): string {
+    if (term.termType === 'NamedNode') {
+        return term.value;
+    }
+    if (term.termType === 'BlankNode') {
+        return `_:${term.value}`;
+    }
+    if (term.termType === 'Literal') {
+        return term.value;
+    }
+    return String((term as { value?: unknown }).value ?? '');
+}
+
+function normalizeSparqlVariableName(raw: string): string {
+    const normalized = raw.replace(/[^A-Za-z0-9_]/g, '_');
+    if (!normalized) {
+        return 'value';
+    }
+    if (!/^[A-Za-z_]/.test(normalized)) {
+        return `v_${normalized}`;
+    }
+    return normalized;
+}
+
+function uniqueVariableName(base: string, used: ReadonlySet<string>): string {
+    if (!used.has(base)) {
+        return base;
+    }
+    let index = 2;
+    while (used.has(`${base}_${index}`)) {
+        index += 1;
+    }
+    return `${base}_${index}`;
+}
+
+function localName(iri: string): string {
+    const hash = iri.lastIndexOf('#');
+    if (hash >= 0 && hash < iri.length - 1) {
+        return iri.slice(hash + 1);
+    }
+    const slash = iri.lastIndexOf('/');
+    if (slash >= 0 && slash < iri.length - 1) {
+        return iri.slice(slash + 1);
+    }
+    return iri;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/md/md-frontmatter.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import type { MarkdownFrontMatter } from './md-types.js';
+import { parseYamlMap } from './md-yaml.js';
+
+export function stripLeadingFrontMatter(markdown: string): string {
+    const normalized = markdown.replace(/^\uFEFF/, '');
+    const frontMatter = extractLeadingFrontMatter(normalized);
+    if (!frontMatter) {
+        return normalized;
+    }
+    return normalized.slice(frontMatter.raw.length);
+}
+
+export function extractLeadingFrontMatter(markdown: string): MarkdownFrontMatter | undefined {
+    const normalized = markdown.replace(/^\uFEFF/, '');
+    const yamlMatch = /^(---\s*\r?\n[\s\S]*?\r?\n---(?:\s*\r?\n|$))/.exec(normalized);
+    if (yamlMatch) {
+        const yamlBody = yamlMatch[1]
+            .replace(/^---\s*\r?\n/, '')
+            .replace(/\r?\n---(?:\s*\r?\n|$)$/, '');
+        const yamlData = parseYamlMap(yamlBody);
+        return {
+            raw: yamlMatch[1],
+            contextUri: extractContextUriFromData(yamlData) ?? extractContextUri(yamlMatch[1]),
+            data: yamlData,
+        };
+    }
+    const tomlMatch = /^(\+\+\+\s*\r?\n[\s\S]*?\r?\n\+\+\+(?:\s*\r?\n|$))/.exec(normalized);
+    if (tomlMatch) {
+        return {
+            raw: tomlMatch[1],
+            contextUri: extractContextUri(tomlMatch[1])
+        };
+    }
+    return undefined;
+}
+
+export function extractContextUri(frontMatterRaw: string): string | undefined {
+    const match = /^contextUri\s*:\s*(.+)$/m.exec(frontMatterRaw);
+    if (!match) {
+        return undefined;
+    }
+    return match[1].trim().replace(/^['"]|['"]$/g, '');
+}
+
+function extractContextUriFromData(data: Record<string, unknown> | undefined): string | undefined {
+    if (!data) {
+        return undefined;
+    }
+    const value = data.contextUri;
+    return typeof value === 'string' ? value : undefined;
+}

package/src/md/md-registry.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import type { CodeBlockHandler, ParsedCodeBlock } from './md-types.js';
+
+export class MarkdownHandlerRegistry {
+    private readonly handlers: CodeBlockHandler[] = [];
+
+    register(handler: CodeBlockHandler): void {
+        if (this.handlers.some((h) => h.id === handler.id)) {
+            throw new Error(`Duplicate markdown handler id: ${handler.id}`);
+        }
+        this.handlers.push(handler);
+    }
+
+    match(block: ParsedCodeBlock): CodeBlockHandler | undefined {
+        return this.handlers.find((handler) => handler.supports(block));
+    }
+
+    list(): ReadonlyArray<CodeBlockHandler> {
+        return this.handlers;
+    }
+}