@oml/markdown 0.7.0

package/README.md

@@ -0,0 +1,39 @@
+# OML Markdown
+
+`@oml/markdown` contains the markdown layer for OML.
+
+It is responsible for:
+
+- markdown parsing and front matter handling
+- markdown execution request/result types
+- markdown block execution through `MarkdownExecutor`
+- browser runtime assets
+- shared markdown renderers
+
+## Package Boundary
+
+- `@oml/language` owns the language layer
+- `@oml/owl` owns the semantic web layer
+- `@oml/markdown` depends on `@oml/owl`
+
+This package does not implement the core OML language services directly.
+
+## Main Exports
+
+- `MarkdownPreviewRuntime`
+- `MarkdownExecutionRequest`
+- `MarkdownExecutor`
+- markdown execution/result types
+- `STATIC_MARKDOWN_RUNTIME_BUNDLE_FILE`
+- `STATIC_MARKDOWN_RUNTIME_CSS`
+- shared renderers via `@oml/markdown/renderers`
+
+## Instructions
+
+Use this package when you need markdown preparation, markdown execution contracts, or OML markdown block execution on top of `@oml/owl`.
+
+Typical usage:
+
+```ts
+import { MarkdownExecutor } from '@oml/markdown';
+```

package/out/index.d.ts

@@ -0,0 +1,2 @@
+export * from './md/index.js';
+export * from './static/index.js';

package/out/index.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+export * from './md/index.js';
+export * from './static/index.js';
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/out/md/index.d.ts

@@ -0,0 +1,6 @@
+export * from './md-types.js';
+export * from './md-execution.js';
+export * from './md-frontmatter.js';
+export * from './md-registry.js';
+export * from './md-runtime.js';
+export * from './md-executor.js';

package/out/md/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+export * from './md-types.js';
+export * from './md-execution.js';
+export * from './md-frontmatter.js';
+export * from './md-registry.js';
+export * from './md-runtime.js';
+export * from './md-executor.js';
+//# sourceMappingURL=index.js.map

package/out/md/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/md/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/out/md/md-execution.d.ts

@@ -0,0 +1,33 @@
+export declare const MarkdownExecutionRequest = "oml/markdown/execute";
+export type MdBlockKind = 'table' | 'tree' | 'graph' | 'chart' | 'diagram' | 'list' | 'text' | 'matrix' | 'table-editor';
+export interface MdExecutableBlock {
+    id: string;
+    kind: MdBlockKind;
+    source: string;
+    meta?: string;
+    options?: Record<string, unknown>;
+    lineStart: number;
+    lineEnd: number;
+}
+export interface MdExecuteBlocksParams {
+    documentUri: string;
+    modelUri?: string;
+    blocks: MdExecutableBlock[];
+}
+export type MdExecutionStatus = 'ok' | 'error' | 'unimplemented';
+export interface MdTablePayload {
+    columns: string[];
+    rows: string[][];
+}
+export interface MdBlockExecutionResult {
+    blockId: string;
+    kind: MdBlockKind;
+    status: MdExecutionStatus;
+    format: 'table' | 'message';
+    payload?: MdTablePayload;
+    message?: string;
+}
+export interface MdExecuteBlocksResult {
+    results: MdBlockExecutionResult[];
+    contextQuadCount?: number;
+}

package/out/md/md-execution.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+export const MarkdownExecutionRequest = 'oml/markdown/execute';
+//# sourceMappingURL=md-execution.js.map

package/out/md/md-execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"md-execution.js","sourceRoot":"","sources":["../../src/md/md-execution.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC"}

package/out/md/md-executor.d.ts

@@ -0,0 +1,21 @@
+import { type OwlConstructResult, type OwlQueryResult } from '@oml/owl';
+import type { 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 declare class MarkdownExecutor {
+    private readonly backend;
+    constructor(backend: MarkdownExecutionBackend);
+    executeBlocks(params: MdExecuteBlocksParams): Promise<MdExecuteBlocksResult>;
+    private executeMatrixBlock;
+    private executeTableBlock;
+    private executeGraphBlock;
+    private executeDiagramBlock;
+    private executeTreeBlock;
+    private executeTextBlock;
+    private executeListBlock;
+}

package/out/md/md-executor.js

@@ -0,0 +1,498 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+import { deriveSelectQueryFromShape } from '@oml/owl';
+export class MarkdownExecutor {
+    constructor(backend) {
+        this.backend = backend;
+    }
+    async executeBlocks(params) {
+        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 = [];
+        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 };
+    }
+    async executeMatrixBlock(modelUri, blockId, source) {
+        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(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);
+    }
+    async executeTableBlock(kind, modelUri, blockId, source, options) {
+        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())
+            : new Map();
+        const optionLabelByVariable = extractColumnLabelOverrides(options);
+        for (const [variable, label] of optionLabelByVariable.entries()) {
+            labelByVariable.set(variable, label);
+        }
+        const columns = variableColumns;
+        const columnSet = new Set(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);
+    }
+    async executeGraphBlock(modelUri, blockId, source) {
+        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);
+    }
+    async executeDiagramBlock(modelUri, blockId, source) {
+        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);
+    }
+    async executeTreeBlock(modelUri, blockId, source, options) {
+        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 = [];
+        const focusSet = new Set();
+        const valuesByFocus = new Map();
+        const predicateToColumn = new Map();
+        const usedColumns = new Set(['focus']);
+        const columnOrder = [];
+        const columnLabelByVariable = new Map([['focus', 'focus']]);
+        const addFocus = (focus) => {
+            if (focusSet.has(focus)) {
+                return;
+            }
+            focusSet.add(focus);
+            focusOrder.push(focus);
+            valuesByFocus.set(focus, new Map());
+        };
+        const addCellValue = (focus, column, value) => {
+            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);
+            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);
+            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();
+            return columns.map((column) => {
+                if (column === 'focus') {
+                    return focus;
+                }
+                return (byColumn.get(column) ?? []).join(', ');
+            });
+        });
+        return okTable(blockId, 'tree', displayColumns, rows);
+    }
+    async executeTextBlock(modelUri, blockId, source) {
+        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(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);
+    }
+    async executeListBlock(modelUri, blockId, source) {
+        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(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, modelUri, source) {
+    if (!source.includes('${contextIri}')) {
+        return source;
+    }
+    return source.split('${contextIri}').join(backend.resolveContextIri(modelUri));
+}
+function missingContext(blockId, kind) {
+    return queryFailed(blockId, kind, 'No contextUri model is available for this markdown document.');
+}
+function queryFailed(blockId, kind, message) {
+    return {
+        blockId,
+        kind,
+        status: 'error',
+        format: 'message',
+        message,
+    };
+}
+function okTable(blockId, kind, columns, rows) {
+    return {
+        blockId,
+        kind,
+        status: 'ok',
+        format: 'table',
+        payload: { columns, rows },
+    };
+}
+function constructRowsResult(blockId, kind, constructResult) {
+    return okTable(blockId, kind, ['subject', 'predicate', 'object'], constructResult.quads.map((quad) => [
+        termToCellValue(quad.subject),
+        termToCellValue(quad.predicate),
+        termToCellValue(quad.object),
+    ]));
+}
+function extractSelectVariables(sparql) {
+    const match = /select\s+(?:distinct\s+|reduced\s+)?([\s\S]*?)\bwhere\b/i.exec(sparql);
+    if (!match) {
+        return [];
+    }
+    const variables = [];
+    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();
+    const result = [];
+    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) {
+    const terms = [];
+    let current = '';
+    let depth = 0;
+    let quote;
+    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, firstVariable) {
+    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) {
+    const labels = new Map();
+    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) {
+    const names = new Set();
+    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) {
+    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) {
+    if (term.termType === 'NamedNode') {
+        return term.value;
+    }
+    if (term.termType === 'BlankNode') {
+        return `_:${term.value}`;
+    }
+    if (term.termType === 'Literal') {
+        return term.value;
+    }
+    return String(term.value ?? '');
+}
+function normalizeSparqlVariableName(raw) {
+    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, used) {
+    if (!used.has(base)) {
+        return base;
+    }
+    let index = 2;
+    while (used.has(`${base}_${index}`)) {
+        index += 1;
+    }
+    return `${base}_${index}`;
+}
+function localName(iri) {
+    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) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=md-executor.js.map