@oml/server 0.14.0

package/src/rest/validation.ts

@@ -0,0 +1,555 @@
+// 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 { createHash } from 'node:crypto';
+import { checkConsistency, type ConsistencyResult } from '@oml/reasoner';
+import { extractLeadingFrontMatter, MarkdownHandlerRegistry, MarkdownPreviewRuntime } from '@oml/markdown';
+import { createDefaultShaclService } from '@oml/owl';
+import { getOntologyModelIndex } from '@oml/language';
+import {
+    buildTemplateCatalog,
+    expandTemplateComposeBlocks,
+    findFilesByExtension,
+    frontMatterString,
+    isTemplateMarkdownFile,
+    normalizeContextOntologyIri,
+} from './template.js';
+
+export interface RestLintProblem {
+    uri: string;
+    line: number;
+    column: number;
+    kind: 'error' | 'warning' | 'information' | 'hint' | 'unknown';
+    severity: number;
+    message: string;
+    source?: string;
+    code?: string | number;
+}
+
+export interface RestLintResult {
+    success: boolean;
+    filesChecked: number;
+    errors: number;
+    warnings: number;
+    elapsedMs: number;
+    totalProblems: number;
+    returnedProblems: number;
+    truncated: boolean;
+    limit?: number;
+    problems: RestLintProblem[];
+    problemsByModelUri: Array<{
+        modelUri: string;
+        errors: number;
+        warnings: number;
+        problems: RestLintProblem[];
+    }>;
+}
+
+type RdfFormat = 'ttl' | 'trig' | 'nt' | 'nq' | 'n3';
+
+type WorkspaceOwlEntry = { modelUri: string; ontologyIri: string; owlPath: string };
+
+type ValidateBlockCachedResult = {
+    errors: number;
+    warnings: number;
+    detail: Record<string, unknown>;
+};
+
+type ValidateBlockCacheEntry = {
+    fingerprint: string;
+    result: ValidateBlockCachedResult;
+};
+
+type ReasonModelCachedResult = {
+    consistent: boolean;
+    ontologyIri: string;
+    result?: ConsistencyResult;
+    error?: string;
+};
+
+type ReasonModelCacheEntry = {
+    fingerprint: string;
+    result: ReasonModelCachedResult;
+};
+
+type ValidationRuntimeCache = {
+    validateBlockCache: Map<string, ValidateBlockCacheEntry>;
+    reasonModelCache: Map<string, ReasonModelCacheEntry>;
+};
+
+const validationRuntimeCaches = new WeakMap<object, ValidationRuntimeCache>();
+
+export type RestValidationContext = {
+    workspaceRoot: string;
+    runtime: { shared: any; Oml: any };
+    ensureInitialized: () => Promise<void>;
+    ensureWorkspaceCurrent: () => Promise<void>;
+    getWorkspaceOmlDocuments: () => any[];
+    writeWorkspaceAssertedOwl: (
+        outputDir: string,
+        format: RdfFormat,
+        pretty: boolean,
+    ) => Promise<WorkspaceOwlEntry[]>;
+};
+
+function normalizeRdfFormat(value: string | undefined): RdfFormat {
+    if (!value) {
+        return 'ttl';
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'trig' || normalized === 'nt' || normalized === 'nq' || normalized === 'n3') {
+        return normalized;
+    }
+    return 'ttl';
+}
+
+function diagnosticKindFromSeverity(severity: unknown): RestLintProblem['kind'] {
+    if (severity === 1) return 'error';
+    if (severity === 2) return 'warning';
+    if (severity === 3) return 'information';
+    if (severity === 4) return 'hint';
+    return 'unknown';
+}
+
+function hashText(value: string): string {
+    return createHash('sha256').update(value, 'utf-8').digest('hex');
+}
+
+function getValidationRuntimeCache(client: RestValidationContext): ValidationRuntimeCache {
+    const key = client.runtime.shared as object;
+    const existing = validationRuntimeCaches.get(key);
+    if (existing) {
+        return existing;
+    }
+    const created: ValidationRuntimeCache = {
+        validateBlockCache: new Map(),
+        reasonModelCache: new Map(),
+    };
+    validationRuntimeCaches.set(key, created);
+    return created;
+}
+
+function getModelContentFingerprints(client: RestValidationContext): Map<string, string> {
+    const fingerprints = new Map<string, string>();
+    const docs = client.getWorkspaceOmlDocuments();
+    for (const doc of docs) {
+        const modelUri = String(doc?.uri ?? '').trim();
+        if (!modelUri) {
+            continue;
+        }
+        const text = typeof doc?.textDocument?.getText === 'function'
+            ? String(doc.textDocument.getText())
+            : '';
+        fingerprints.set(modelUri, hashText(text));
+    }
+    return fingerprints;
+}
+
+export async function lintWorkspace(client: RestValidationContext, params: Record<string, unknown> = {}): Promise<RestLintResult> {
+    const startedAt = Date.now();
+    await client.ensureInitialized();
+    await client.ensureWorkspaceCurrent();
+    const rawLimit = params.limit;
+    const limit = typeof rawLimit === 'number' && Number.isFinite(rawLimit) && rawLimit > 0
+        ? Math.floor(rawLimit)
+        : undefined;
+    const docs = client.getWorkspaceOmlDocuments();
+    const allProblems: RestLintProblem[] = [];
+    let errors = 0;
+    let warnings = 0;
+    for (const doc of docs) {
+        const modelUri = String(doc?.uri ?? '').trim();
+        const diagnostics = Array.isArray(doc?.diagnostics) ? doc.diagnostics : [];
+        for (const diagnostic of diagnostics) {
+            const severity = typeof diagnostic?.severity === 'number' ? diagnostic.severity : 0;
+            const kind = diagnosticKindFromSeverity(severity);
+            if (kind === 'error') {
+                errors += 1;
+            } else if (kind === 'warning') {
+                warnings += 1;
+            }
+            allProblems.push({
+                uri: modelUri,
+                line: Number(diagnostic?.range?.start?.line ?? 0) + 1,
+                column: Number(diagnostic?.range?.start?.character ?? 0) + 1,
+                kind,
+                severity,
+                message: String(diagnostic?.message ?? ''),
+                source: typeof diagnostic?.source === 'string' ? diagnostic.source : undefined,
+                code: typeof diagnostic?.code === 'string' || typeof diagnostic?.code === 'number'
+                    ? diagnostic.code
+                    : undefined,
+            });
+        }
+    }
+    allProblems.sort((left, right) =>
+        left.uri.localeCompare(right.uri)
+        || left.message.localeCompare(right.message)
+        || left.line - right.line
+        || left.column - right.column
+    );
+    const limitedProblems = limit === undefined ? allProblems : allProblems.slice(0, limit);
+    const grouped = new Map<string, RestLintProblem[]>();
+    for (const problem of limitedProblems) {
+        const existing = grouped.get(problem.uri) ?? [];
+        existing.push(problem);
+        grouped.set(problem.uri, existing);
+    }
+    const problemsByModelUri = Array.from(grouped.entries())
+        .map(([modelUri, problems]) => ({
+            modelUri,
+            errors: problems.filter((problem) => problem.kind === 'error').length,
+            warnings: problems.filter((problem) => problem.kind === 'warning').length,
+            problems: problems.sort((left, right) =>
+                left.message.localeCompare(right.message) || left.line - right.line || left.column - right.column
+            ),
+        }))
+        .sort((left, right) => left.modelUri.localeCompare(right.modelUri));
+
+    return {
+        success: errors === 0 && warnings === 0,
+        filesChecked: docs.length,
+        errors,
+        warnings,
+        elapsedMs: Math.max(0, Date.now() - startedAt),
+        totalProblems: allProblems.length,
+        returnedProblems: limitedProblems.length,
+        truncated: limitedProblems.length < allProblems.length,
+        limit,
+        problems: limitedProblems,
+        problemsByModelUri,
+    };
+}
+
+export async function reasonWorkspace(client: RestValidationContext, params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const startedAt = Date.now();
+    await client.ensureInitialized();
+    await client.ensureWorkspaceCurrent();
+    let validateResult: Record<string, unknown> | undefined;
+    if (params.only !== true) {
+        validateResult = await validateWorkspace(client, {
+            only: false,
+            lintLimit: params.lintLimit,
+        });
+        if (validateResult.success !== true) {
+            return {
+                success: false,
+                ontologiesReasoned: 0,
+                elapsedMs: Math.max(0, Date.now() - startedAt),
+                inconsistent: [],
+                failed: [{
+                    modelUri: '',
+                    error: String(validateResult.error ?? 'validate failed'),
+                }],
+                validate: validateResult,
+            };
+        }
+    }
+    const format = normalizeRdfFormat(typeof params.format === 'string' ? params.format : undefined);
+    const tempRoot = await fs.mkdtemp(path.join(client.workspaceRoot, '.oml-reason-'));
+    const entries = await client.writeWorkspaceAssertedOwl(tempRoot, format, false);
+    if (entries.length === 0) {
+        await fs.rm(tempRoot, { recursive: true, force: true });
+        return { success: true, ontologiesReasoned: 0, inconsistent: [], failed: [] };
+    }
+
+    const explanation = params.explanation !== false;
+    const uniqueNamesAssumption = params.uniqueNamesAssumption === true;
+    const profile = params.profile === true;
+    const timeout = typeof params.timeout === 'number' && Number.isFinite(params.timeout) && params.timeout > 0
+        ? Math.floor(params.timeout)
+        : 120_000;
+    const inconsistent: Array<{ modelUri: string; validationWarnings: string[] }> = [];
+    const failed: Array<{ modelUri: string; error: string }> = [];
+    const results: Array<{
+        modelUri: string;
+        ontologyIri: string;
+        consistent: boolean;
+        result?: ConsistencyResult;
+        error?: string;
+    }> = [];
+    const runtimeCache = getValidationRuntimeCache(client);
+    const modelFingerprints = getModelContentFingerprints(client);
+    const seenReasonKeys = new Set<string>();
+
+    const reasonStartedAt = Date.now();
+    for (const entry of entries) {
+        const modelFingerprint = modelFingerprints.get(entry.modelUri) ?? '';
+        const reasonFingerprint = hashText([
+            modelFingerprint,
+            String(explanation),
+            String(uniqueNamesAssumption),
+            String(profile),
+            String(timeout),
+        ].join('\n'));
+        seenReasonKeys.add(entry.modelUri);
+        const cached = runtimeCache.reasonModelCache.get(entry.modelUri);
+        if (cached?.fingerprint === reasonFingerprint) {
+            const cachedResult = cached.result;
+            const warnings = Array.isArray(cachedResult.result?.reports) ? cachedResult.result.reports : [];
+            if (!cachedResult.consistent) {
+                inconsistent.push({
+                    modelUri: entry.modelUri,
+                    validationWarnings: warnings,
+                });
+            }
+            if (cachedResult.error) {
+                failed.push({
+                    modelUri: entry.modelUri,
+                    error: cachedResult.error,
+                });
+            }
+            results.push({
+                modelUri: entry.modelUri,
+                ontologyIri: entry.ontologyIri,
+                consistent: cachedResult.consistent,
+                result: cachedResult.result,
+                error: cachedResult.error,
+            });
+            continue;
+        }
+        try {
+            const result = await checkConsistency({
+                input: entry.owlPath,
+                inputRoot: tempRoot,
+                explanations: explanation,
+                uniqueNamesAssumption,
+                checkOnly: true,
+                profile,
+                timeout,
+            });
+            const warnings = Array.isArray(result.reports) ? result.reports : [];
+            const modelResult: ReasonModelCachedResult = {
+                consistent: result.consistent,
+                ontologyIri: entry.ontologyIri,
+                result,
+            };
+            runtimeCache.reasonModelCache.set(entry.modelUri, {
+                fingerprint: reasonFingerprint,
+                result: modelResult,
+            });
+            if (!result.consistent) {
+                inconsistent.push({
+                    modelUri: entry.modelUri,
+                    validationWarnings: warnings,
+                });
+            }
+            results.push({
+                modelUri: entry.modelUri,
+                ontologyIri: entry.ontologyIri,
+                consistent: result.consistent,
+                result,
+            });
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const modelError = message || 'reason failed';
+            runtimeCache.reasonModelCache.set(entry.modelUri, {
+                fingerprint: reasonFingerprint,
+                result: {
+                    consistent: false,
+                    ontologyIri: entry.ontologyIri,
+                    error: modelError,
+                },
+            });
+            failed.push({
+                modelUri: entry.modelUri,
+                error: modelError,
+            });
+            results.push({
+                modelUri: entry.modelUri,
+                ontologyIri: entry.ontologyIri,
+                consistent: false,
+                error: modelError,
+            });
+        }
+    }
+    for (const key of runtimeCache.reasonModelCache.keys()) {
+        if (!seenReasonKeys.has(key)) {
+            runtimeCache.reasonModelCache.delete(key);
+        }
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+
+    return {
+        success: failed.length === 0 && inconsistent.length === 0,
+        ontologiesReasoned: entries.length,
+        elapsedMs: Math.max(0, Date.now() - reasonStartedAt),
+        totalElapsedMs: Math.max(0, Date.now() - startedAt),
+        inconsistent,
+        failed,
+        results,
+        validate: validateResult,
+    };
+}
+
+export async function validateWorkspace(client: RestValidationContext, params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const startedAt = Date.now();
+    await client.ensureInitialized();
+    await client.ensureWorkspaceCurrent();
+    let lint: RestLintResult | undefined;
+    if (params.only !== true) {
+        lint = await lintWorkspace(client, { limit: params.lintLimit });
+        if (lint.errors > 0 || lint.warnings > 0) {
+            return {
+                success: false,
+                filesChecked: 0,
+                errors: 0,
+                warnings: 0,
+                elapsedMs: Math.max(0, Date.now() - startedAt),
+                error: `lint failed with ${lint.errors} error(s) and ${lint.warnings} warning(s)`,
+                lint,
+            };
+        }
+    }
+    const workspaceRoot = path.resolve(client.workspaceRoot);
+    const markdownFiles = await findFilesByExtension(workspaceRoot, '.md');
+    const templateCatalog = await buildTemplateCatalog(workspaceRoot);
+    const runtime = new MarkdownPreviewRuntime(new MarkdownHandlerRegistry());
+    const ontologyIndex = getOntologyModelIndex(client.runtime.shared as any);
+    const reasoningService = client.runtime.Oml.reasoning.ReasoningService as any;
+    const shaclService = createDefaultShaclService(
+        reasoningService.getSparqlService(),
+        (uri) => reasoningService.ensureQueryContext(uri),
+        (uri) => reasoningService.getContextIri(uri),
+    );
+    const runtimeCache = getValidationRuntimeCache(client);
+    const modelFingerprints = getModelContentFingerprints(client);
+    const seenValidateKeys = new Set<string>();
+    let filesChecked = 0;
+    let errors = 0;
+    let warnings = 0;
+    const details: Array<Record<string, unknown>> = [];
+
+    for (const markdownPath of markdownFiles) {
+        const markdown = await fs.readFile(markdownPath, 'utf-8');
+        if (isTemplateMarkdownFile(markdown)) {
+            continue;
+        }
+        const frontMatter = extractLeadingFrontMatter(markdown);
+        const contextOntologyIri = normalizeContextOntologyIri(
+            frontMatter?.contextOntologyIri
+                ?? frontMatterString(frontMatter?.data, 'ontologyIri')
+                ?? frontMatterString(frontMatter?.data, 'ontology')
+        );
+        const contextMemberIri = frontMatterString(frontMatter?.data, 'memberIri')
+            ?? frontMatterString(frontMatter?.data, 'contextMemberIri');
+        const markdownUri = pathToFileURL(markdownPath).toString();
+        const modelUri = contextOntologyIri
+            ? ontologyIndex.resolveModelUri(contextOntologyIri, markdownUri)
+            : undefined;
+        const expanded = await expandTemplateComposeBlocks(markdown, templateCatalog, {
+            workspaceRoot,
+            sourceMarkdownPath: markdownPath,
+            contextOntologyIri,
+            contextModelUri: modelUri,
+            contextMemberIri,
+        });
+        const prepared = runtime.prepare(expanded);
+        const executableBlocks = prepared.codeBlocks
+            .filter((block) => block.language === 'table-editor')
+            .map((block) => ({ id: block.id, source: block.content }));
+        if (executableBlocks.length === 0) {
+            continue;
+        }
+        for (const block of executableBlocks) {
+            filesChecked += 1;
+            const shacl = block.source.trim();
+            if (!contextOntologyIri) {
+                errors += 1;
+                details.push({
+                    markdownUri,
+                    blockId: block.id,
+                    status: 'error',
+                    message: 'Missing ontologyIri in markdown frontmatter for table-editor block.',
+                });
+                continue;
+            }
+            if (!modelUri) {
+                errors += 1;
+                details.push({
+                    markdownUri,
+                    blockId: block.id,
+                    status: 'error',
+                    message: `Unable to resolve modelUri for ontologyIri '${contextOntologyIri}'.`,
+                });
+                continue;
+            }
+            if (!shacl) {
+                errors += 1;
+                const detail = {
+                    markdownUri,
+                    blockId: block.id,
+                    modelUri,
+                    status: 'error',
+                    message: 'Empty SHACL shape.',
+                };
+                details.push(detail);
+                continue;
+            }
+            const modelFingerprint = modelFingerprints.get(modelUri) ?? '';
+            const cacheKey = `${markdownUri}::${block.id}`;
+            const validateFingerprint = hashText([modelUri, modelFingerprint, shacl].join('\n'));
+            seenValidateKeys.add(cacheKey);
+            const cached = runtimeCache.validateBlockCache.get(cacheKey);
+            if (cached?.fingerprint === validateFingerprint) {
+                errors += cached.result.errors;
+                warnings += cached.result.warnings;
+                details.push(cached.result.detail);
+                continue;
+            }
+            const result = await shaclService.validateShacl(modelUri, shacl);
+            let blockErrors = 0;
+            let blockWarnings = 0;
+            if (result.error) {
+                blockErrors += 1;
+            } else if (!result.conforms) {
+                for (const issue of result.issues) {
+                    if (String(issue.severity ?? '').toLowerCase().includes('warning')) {
+                        blockWarnings += 1;
+                    } else {
+                        blockErrors += 1;
+                    }
+                }
+                if (result.issues.length === 0) {
+                    blockErrors += 1;
+                }
+            }
+            errors += blockErrors;
+            warnings += blockWarnings;
+            const detail = {
+                markdownUri,
+                blockId: block.id,
+                modelUri,
+                status: result.error ? 'error' : (result.conforms ? 'ok' : 'failed'),
+                conforms: result.conforms,
+                error: result.error,
+                issues: result.issues,
+            };
+            details.push(detail);
+            runtimeCache.validateBlockCache.set(cacheKey, {
+                fingerprint: validateFingerprint,
+                result: {
+                    errors: blockErrors,
+                    warnings: blockWarnings,
+                    detail,
+                },
+            });
+        }
+    }
+    for (const key of runtimeCache.validateBlockCache.keys()) {
+        if (!seenValidateKeys.has(key)) {
+            runtimeCache.validateBlockCache.delete(key);
+        }
+    }
+    return {
+        success: errors === 0 && warnings === 0,
+        filesChecked,
+        errors,
+        warnings,
+        elapsedMs: Math.max(0, Date.now() - startedAt),
+        details,
+        lint,
+    };
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "out",
+    "declarationDir": "out"
+  },
+  "references": [
+    {
+      "path": "../owl/tsconfig.json"
+    },
+    {
+      "path": "../markdown/tsconfig.json"
+    },
+    {
+      "path": "../language/tsconfig.src.json"
+    }
+  ],
+  "include": [
+    "src/**/*.ts"
+  ]
+}