opentology 0.1.0

package/dist/lib/shacl.js

@@ -0,0 +1,105 @@
+import rdf from 'rdf-ext';
+import { Parser } from 'n3';
+import { Validator } from 'shacl-engine';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Discover .ttl shape files in the given directory (defaults to shapes/ in cwd).
+ */
+export function discoverShapes(dir) {
+    const shapesDir = dir ?? join(process.cwd(), 'shapes');
+    if (!existsSync(shapesDir)) {
+        return [];
+    }
+    return readdirSync(shapesDir)
+        .filter((f) => f.endsWith('.ttl'))
+        .map((f) => join(shapesDir, f));
+}
+/**
+ * Check whether the shapes directory exists and contains at least one .ttl file.
+ */
+export function hasShapes(shapesDir) {
+    return discoverShapes(shapesDir).length > 0;
+}
+/**
+ * Parse a Turtle string into an rdf-ext Dataset using n3.
+ */
+function parseTurtleToDataset(turtle) {
+    return new Promise((resolve, reject) => {
+        const parser = new Parser();
+        const quads = [];
+        parser.parse(turtle, (err, quad) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            if (quad) {
+                quads.push(quad);
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+                resolve(rdf.dataset(quads));
+            }
+        });
+    });
+}
+/**
+ * Load and combine multiple shape .ttl files into a single rdf-ext Dataset.
+ */
+async function loadShapes(shapePaths) {
+    const allQuads = [];
+    for (const shapePath of shapePaths) {
+        const turtle = readFileSync(shapePath, 'utf-8');
+        const dataset = await parseTurtleToDataset(turtle);
+        for (const quad of dataset) {
+            allQuads.push(quad);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    return rdf.dataset(allQuads);
+}
+/**
+ * Extract a string value from a SHACL result message, which may be a Literal object or a plain string.
+ */
+function extractMessageValue(msg) {
+    if (!msg)
+        return '';
+    if (Array.isArray(msg)) {
+        return msg.map(extractMessageValue).join('; ');
+    }
+    if (typeof msg === 'object' && msg !== null && 'value' in msg) {
+        return String(msg.value);
+    }
+    return String(msg);
+}
+/**
+ * Extract the local name from a URI (e.g. "http://...#Violation" → "Violation").
+ */
+function extractLocalName(uri) {
+    const hashIdx = uri.lastIndexOf('#');
+    if (hashIdx !== -1)
+        return uri.slice(hashIdx + 1);
+    const slashIdx = uri.lastIndexOf('/');
+    if (slashIdx !== -1)
+        return uri.slice(slashIdx + 1);
+    return uri;
+}
+/**
+ * Validate a Turtle data string against the given SHACL shape files.
+ */
+export async function validateWithShacl(dataTurtle, shapePaths) {
+    const dataDataset = await parseTurtleToDataset(dataTurtle);
+    const shapesDataset = await loadShapes(shapePaths);
+    const validator = new Validator(shapesDataset, { factory: rdf });
+    const report = await validator.validate({ dataset: dataDataset });
+    const violations = (report.results ?? []).map((result) => ({
+        focusNode: result.focusNode?.value ?? '',
+        path: result.path?.value ?? null,
+        message: extractMessageValue(result.message),
+        severity: extractLocalName(result.severity?.value ?? ''),
+    }));
+    return {
+        conforms: Boolean(report.conforms),
+        violations,
+    };
+}

package/dist/lib/sparql-utils.d.ts

@@ -0,0 +1,28 @@
+import type { Quad } from 'n3';
+export declare const WELL_KNOWN_PREFIXES: Record<string, string>;
+export declare function termToSparql(term: Quad['subject'] | Quad['predicate'] | Quad['object']): string;
+export declare function parseTurtle(turtle: string): Promise<Quad[]>;
+export declare function serializeQuadsToTurtle(quads: Quad[]): Promise<string>;
+export declare function extractPrefixes(uris: string[]): Record<string, string>;
+/**
+ * Returns true if the query already manages its own graph scoping.
+ * Matches GRAPH, FROM NAMED, or FROM < (case-insensitive).
+ */
+export declare function hasGraphScope(sparql: string): boolean;
+/**
+ * Wraps the WHERE body of a SPARQL SELECT/CONSTRUCT/ASK/DESCRIBE query so
+ * that all triple patterns are scoped to `graphUri`.
+ *
+ * Handles:
+ *   SELECT ... WHERE { ... }          -> standard form
+ *   SELECT ... { ... }               -> shorthand (no WHERE keyword)
+ *
+ * Returns null if the outermost `{ ... }` block cannot be located safely.
+ */
+export declare function autoScopeQuery(sparql: string, graphUri: string): string | null;
+/**
+ * Auto-scope a SPARQL query with UNION over asserted + inference graphs.
+ * Returns null if brace matching fails.
+ */
+export declare function autoScopeQueryWithInference(sparql: string, graphUri: string, inferenceGraphUri: string): string | null;
+export declare function getInferenceGraphUri(graphUri: string): string;

package/dist/lib/sparql-utils.js

@@ -0,0 +1,217 @@
+import { Parser, Writer } from 'n3';
+// ── Well-known prefixes ───────────────────────────────────────────────
+export const WELL_KNOWN_PREFIXES = {
+    'http://www.w3.org/1999/02/22-rdf-syntax-ns#': 'rdf',
+    'http://www.w3.org/2000/01/rdf-schema#': 'rdfs',
+    'http://www.w3.org/2002/07/owl#': 'owl',
+    'http://schema.org/': 'schema',
+    'http://xmlns.com/foaf/0.1/': 'foaf',
+    'http://www.w3.org/2001/XMLSchema#': 'xsd',
+    'http://purl.org/dc/elements/1.1/': 'dc',
+    'http://purl.org/dc/terms/': 'dcterms',
+    'http://www.w3.org/2004/02/skos/core#': 'skos',
+    'http://www.w3.org/ns/prov#': 'prov',
+};
+// ── Term / Turtle helpers ─────────────────────────────────────────────
+export function termToSparql(term) {
+    switch (term.termType) {
+        case 'NamedNode':
+            return `<${term.value}>`;
+        case 'BlankNode':
+            return `_:${term.value}`;
+        case 'Literal': {
+            const escaped = term.value
+                .replace(/\\/g, '\\\\')
+                .replace(/"/g, '\\"')
+                .replace(/\n/g, '\\n')
+                .replace(/\r/g, '\\r')
+                .replace(/\t/g, '\\t');
+            if (term.language) {
+                return `"${escaped}"@${term.language}`;
+            }
+            if (term.datatype && term.datatype.value !== 'http://www.w3.org/2001/XMLSchema#string') {
+                return `"${escaped}"^^<${term.datatype.value}>`;
+            }
+            return `"${escaped}"`;
+        }
+        default:
+            throw new Error(`Unsupported term type: ${term.termType}`);
+    }
+}
+export function parseTurtle(turtle) {
+    return new Promise((resolve, reject) => {
+        const parser = new Parser();
+        const quads = [];
+        parser.parse(turtle, (err, quad) => {
+            if (err) {
+                reject(new Error(`Failed to parse Turtle: ${err.message}`));
+                return;
+            }
+            if (quad) {
+                quads.push(quad);
+            }
+            else {
+                resolve(quads);
+            }
+        });
+    });
+}
+export function serializeQuadsToTurtle(quads) {
+    return new Promise((resolve, reject) => {
+        const writer = new Writer({ format: 'Turtle' });
+        writer.addQuads(quads);
+        writer.end((err, result) => {
+            if (err) {
+                reject(new Error(`Failed to serialize Turtle: ${err.message}`));
+            }
+            else {
+                resolve(result);
+            }
+        });
+    });
+}
+// ── Prefix extraction ─────────────────────────────────────────────────
+export function extractPrefixes(uris) {
+    const prefixes = {};
+    for (const uri of uris) {
+        // Check well-known prefixes first
+        for (const [ns, prefix] of Object.entries(WELL_KNOWN_PREFIXES)) {
+            if (uri.startsWith(ns) && !(prefix in Object.values(prefixes))) {
+                prefixes[prefix] = ns;
+                break;
+            }
+        }
+        // If not matched by well-known, derive from URI structure
+        if (!Object.values(prefixes).some((ns) => uri.startsWith(ns))) {
+            // Try hash-based namespace (e.g. http://example.org/ontology#)
+            const hashIdx = uri.lastIndexOf('#');
+            if (hashIdx !== -1) {
+                const ns = uri.slice(0, hashIdx + 1);
+                if (!Object.values(prefixes).includes(ns)) {
+                    // Derive a short prefix from the last path segment before the hash
+                    const pathSegments = ns.replace(/#$/, '').split('/').filter(Boolean);
+                    const candidate = pathSegments[pathSegments.length - 1]
+                        ?.toLowerCase()
+                        .replace(/[^a-z0-9]/g, '')
+                        .slice(0, 8);
+                    if (candidate && !(candidate in prefixes)) {
+                        prefixes[candidate] = ns;
+                    }
+                }
+            }
+            else {
+                // Slash-based namespace (e.g. http://example.org/ontology/)
+                const slashIdx = uri.lastIndexOf('/');
+                if (slashIdx !== -1) {
+                    const ns = uri.slice(0, slashIdx + 1);
+                    if (!Object.values(prefixes).includes(ns)) {
+                        const pathSegments = ns.replace(/\/$/, '').split('/').filter(Boolean);
+                        const candidate = pathSegments[pathSegments.length - 1]
+                            ?.toLowerCase()
+                            .replace(/[^a-z0-9]/g, '')
+                            .slice(0, 8);
+                        if (candidate && !(candidate in prefixes)) {
+                            prefixes[candidate] = ns;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return prefixes;
+}
+// ── Query scoping ─────────────────────────────────────────────────────
+/**
+ * Returns true if the query already manages its own graph scoping.
+ * Matches GRAPH, FROM NAMED, or FROM < (case-insensitive).
+ */
+export function hasGraphScope(sparql) {
+    return /\bGRAPH\b|\bFROM\s+NAMED\b|\bFROM\s*</i.test(sparql);
+}
+/**
+ * Wraps the WHERE body of a SPARQL SELECT/CONSTRUCT/ASK/DESCRIBE query so
+ * that all triple patterns are scoped to `graphUri`.
+ *
+ * Handles:
+ *   SELECT ... WHERE { ... }          -> standard form
+ *   SELECT ... { ... }               -> shorthand (no WHERE keyword)
+ *
+ * Returns null if the outermost `{ ... }` block cannot be located safely.
+ */
+export function autoScopeQuery(sparql, graphUri) {
+    // Find the first `{` that opens the body.
+    // We look for WHERE { or, as a fallback, any { after the projection clause.
+    const whereMatch = sparql.match(/\bWHERE\s*\{/i);
+    let braceStart;
+    if (whereMatch && whereMatch.index !== undefined) {
+        // Position of `{` inside `WHERE {`
+        braceStart = whereMatch.index + whereMatch[0].length - 1;
+    }
+    else {
+        // Shorthand: find the first `{`
+        const firstBrace = sparql.indexOf('{');
+        if (firstBrace === -1)
+            return null;
+        braceStart = firstBrace;
+    }
+    // Walk forward to find the matching closing `}` (respecting nesting).
+    let depth = 0;
+    let braceEnd = -1;
+    for (let i = braceStart; i < sparql.length; i++) {
+        if (sparql[i] === '{')
+            depth++;
+        else if (sparql[i] === '}') {
+            depth--;
+            if (depth === 0) {
+                braceEnd = i;
+                break;
+            }
+        }
+    }
+    if (braceEnd === -1)
+        return null;
+    const before = sparql.slice(0, braceStart + 1); // up to and including `{`
+    const inner = sparql.slice(braceStart + 1, braceEnd); // content between `{ ... }`
+    const after = sparql.slice(braceEnd); // from `}` onwards
+    return `${before} GRAPH <${graphUri}> {${inner}} ${after}`;
+}
+/**
+ * Auto-scope a SPARQL query with UNION over asserted + inference graphs.
+ * Returns null if brace matching fails.
+ */
+export function autoScopeQueryWithInference(sparql, graphUri, inferenceGraphUri) {
+    const whereMatch = sparql.match(/\bWHERE\s*\{/i);
+    let braceStart;
+    if (whereMatch && whereMatch.index !== undefined) {
+        braceStart = whereMatch.index + whereMatch[0].length - 1;
+    }
+    else {
+        const firstBrace = sparql.indexOf('{');
+        if (firstBrace === -1)
+            return null;
+        braceStart = firstBrace;
+    }
+    let depth = 0;
+    let braceEnd = -1;
+    for (let i = braceStart; i < sparql.length; i++) {
+        if (sparql[i] === '{')
+            depth++;
+        else if (sparql[i] === '}') {
+            depth--;
+            if (depth === 0) {
+                braceEnd = i;
+                break;
+            }
+        }
+    }
+    if (braceEnd === -1)
+        return null;
+    const before = sparql.slice(0, braceStart + 1);
+    const inner = sparql.slice(braceStart + 1, braceEnd);
+    const after = sparql.slice(braceEnd);
+    return `${before} GRAPH ?__g {${inner}} FILTER(?__g = <${graphUri}> || ?__g = <${inferenceGraphUri}>) ${after}`;
+}
+// ── Inference graph URI ───────────────────────────────────────────────
+export function getInferenceGraphUri(graphUri) {
+    return `${graphUri}/inferred`;
+}

package/dist/lib/store-adapter.d.ts

@@ -0,0 +1,50 @@
+export interface SparqlResults {
+    head: {
+        vars: string[];
+    };
+    results: {
+        bindings: Array<Record<string, {
+            type: string;
+            value: string;
+            datatype?: string;
+        }>>;
+    };
+}
+export interface StoreAdapter {
+    sparqlQuery(query: string): Promise<SparqlResults>;
+    askQuery(query: string): Promise<boolean>;
+    sparqlUpdate(update: string): Promise<void>;
+    constructQuery(query: string): Promise<string>;
+    insertTurtle(graphUri: string, turtle: string): Promise<void>;
+    dropGraph(graphUri: string): Promise<void>;
+    deleteTriples(graphUri: string, options: {
+        turtle?: string;
+        where?: string;
+    }): Promise<void>;
+    getGraphTripleCount(graphUri: string): Promise<number>;
+    exportGraph(graphUri: string): Promise<string>;
+    diffGraph(graphUri: string, localTurtle: string): Promise<{
+        added: string[];
+        removed: string[];
+        unchanged: number;
+    }>;
+    getSchemaOverview(graphUri: string): Promise<{
+        prefixes: Record<string, string>;
+        classes: string[];
+        properties: string[];
+        tripleCount: number;
+    }>;
+    getClassDetails(graphUri: string, classUri: string): Promise<{
+        classUri: string;
+        instanceCount: number;
+        properties: Array<{
+            property: string;
+            count: number;
+        }>;
+        sampleTriples: Array<{
+            s: string;
+            p: string;
+            o: string;
+        }>;
+    }>;
+}

package/dist/lib/store-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/store-factory.d.ts

@@ -0,0 +1,9 @@
+import type { StoreAdapter } from './store-adapter.js';
+import type { OpenTologyConfig } from './config.js';
+export declare function createAdapter(config: OpenTologyConfig): StoreAdapter;
+/**
+ * Reset the cached embedded adapter. Useful for tests or after config-level
+ * changes that invalidate the entire store (e.g. project re-init).
+ */
+export declare function resetAdapterCache(): void;
+export declare function createReadyAdapter(config: OpenTologyConfig): Promise<StoreAdapter>;

package/dist/lib/store-factory.js

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getTrackedFiles } from './config.js';
+import { HttpAdapter } from './http-adapter.js';
+import { EmbeddedAdapter } from './embedded-adapter.js';
+import { materializeInferences } from './reasoner.js';
+// Singleton cache for embedded mode — keeps data alive across MCP tool calls.
+let cachedAdapter = null;
+let loadedFileKeys = new Set();
+export function createAdapter(config) {
+    if (config.mode === 'embedded') {
+        return new EmbeddedAdapter();
+    }
+    return new HttpAdapter(config.endpoint ?? 'http://localhost:7878');
+}
+/**
+ * Reset the cached embedded adapter. Useful for tests or after config-level
+ * changes that invalidate the entire store (e.g. project re-init).
+ */
+export function resetAdapterCache() {
+    cachedAdapter = null;
+    loadedFileKeys = new Set();
+}
+export async function createReadyAdapter(config) {
+    if (config.mode !== 'embedded') {
+        return new HttpAdapter(config.endpoint ?? 'http://localhost:7878');
+    }
+    // Reuse cached adapter so data persists across MCP tool calls.
+    if (!cachedAdapter) {
+        cachedAdapter = new EmbeddedAdapter();
+        loadedFileKeys = new Set();
+    }
+    const adapter = cachedAdapter;
+    // Incrementally load only newly-tracked files into the existing store.
+    const allGraphs = [config.graphUri, ...Object.keys(config.graphs ?? {}).map(k => config.graphs[k])];
+    let newFilesLoaded = false;
+    for (const graphUri of allGraphs) {
+        const files = getTrackedFiles(config, graphUri);
+        for (const f of files) {
+            const key = `${graphUri}::${resolve(f)}`;
+            if (!loadedFileKeys.has(key)) {
+                try {
+                    const content = readFileSync(resolve(f), 'utf-8');
+                    adapter.loadTurtleIntoGraph(content, graphUri);
+                    loadedFileKeys.add(key);
+                    newFilesLoaded = true;
+                }
+                catch {
+                    // File may have been deleted — skip silently
+                }
+            }
+        }
+    }
+    // Re-materialize inferences only when new file data was loaded.
+    if (newFilesLoaded) {
+        const allGraphUris = new Set();
+        allGraphUris.add(config.graphUri);
+        if (config.graphs) {
+            for (const uri of Object.values(config.graphs)) {
+                allGraphUris.add(uri);
+            }
+        }
+        for (const graphUri of allGraphUris) {
+            const count = await adapter.getGraphTripleCount(graphUri);
+            if (count > 0) {
+                await materializeInferences(adapter, graphUri);
+            }
+        }
+    }
+    return adapter;
+}

package/dist/lib/validator.d.ts

@@ -0,0 +1,10 @@
+export type ValidationResult = {
+    valid: true;
+    tripleCount: number;
+    prefixes: Record<string, string>;
+} | {
+    valid: false;
+    error: string;
+};
+export declare function validateTurtle(content: string): Promise<ValidationResult>;
+export declare function validateTurtleFile(filePath: string): Promise<ValidationResult>;

package/dist/lib/validator.js

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { Parser } from 'n3';
+export async function validateTurtle(content) {
+    return new Promise((resolve) => {
+        const parser = new Parser();
+        const quads = [];
+        const prefixes = {};
+        parser.parse(content, (err, quad, prefixMap) => {
+            if (err) {
+                resolve({ valid: false, error: err.message });
+                return;
+            }
+            if (quad) {
+                quads.push(quad);
+            }
+            else {
+                // Done — prefixMap is provided as the third argument on completion
+                if (prefixMap) {
+                    for (const [prefix, iri] of Object.entries(prefixMap)) {
+                        prefixes[prefix] = iri.value ?? String(iri);
+                    }
+                }
+                resolve({ valid: true, tripleCount: quads.length, prefixes });
+            }
+        });
+    });
+}
+export async function validateTurtleFile(filePath) {
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return {
+            valid: false,
+            error: `Could not read file '${filePath}': ${err.message}`,
+        };
+    }
+    return validateTurtle(content);
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_TRIPLES_PER_PUSH = 100;
+export declare function assertTripleLimit(tripleCount: number): void;
+export declare function startMcpServer(): Promise<void>;