mdld-parse 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mdld-parse",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
 	"type": "module",
 	"main": "index.js",

package/src/generate.js

@@ -1,4 +1,4 @@
-import { shortenIRI, expandIRI, quadIndexKey, createUnifiedSlot, DEFAULT_CONTEXT, DataFactory } from './utils.js';
+import { shortenIRI, expandIRI, DEFAULT_CONTEXT, DataFactory } from './utils.js';
 
 // Helper functions for cleaner term type checking
 function isLiteral(term) {
@@ -29,7 +29,7 @@ function extractLocalName(iri) {
  * Generate deterministic MDLD from RDF quads
  * Purpose: TTL→MDLD conversion with canonical structure
  * Input: RDF quads + context
- * Output: MDLD text + origin + context
+ * Output: MDLD text
  */
 export function generate(quads, context = {}) {
     const fullContext = { ...DEFAULT_CONTEXT, ...context };
@@ -38,13 +38,9 @@ export function generate(quads, context = {}) {
 
     const subjectGroups = groupQuadsBySubject(normalizedQuads);
 
-    const { text, quadMap } = buildDeterministicMDLD(subjectGroups, fullContext);
+    const { text } = buildDeterministicMDLD(subjectGroups, fullContext);
 
-    return {
-        text,
-        origin: { quadMap },
-        context: fullContext
-    };
+    return text;
 }
 
 function normalizeAndSortQuads(quads) {
@@ -86,8 +82,6 @@ function groupQuadsBySubject(quads) {
 
 function buildDeterministicMDLD(subjectGroups, context) {
     let text = '';
-    let currentPos = 0;
-    const quadMap = new Map();
 
     // Add prefixes first (deterministic order), but exclude default context prefixes
     const sortedPrefixes = Object.entries(context).sort(([a], [b]) => a.localeCompare(b));
@@ -96,13 +90,11 @@ function buildDeterministicMDLD(subjectGroups, context) {
         if (prefix !== '@vocab' && !prefix.startsWith('@') && !DEFAULT_CONTEXT[prefix]) {
             const prefixDecl = `[${prefix}] <${namespace}>\n`;
             text += prefixDecl;
-            currentPos += prefixDecl.length;
         }
     }
 
     if (sortedPrefixes.length > 0) {
         text += '\n';
-        currentPos += 1;
     }
 
     // Process subjects in deterministic order
@@ -125,31 +117,7 @@ function buildDeterministicMDLD(subjectGroups, context) {
 
         const headingText = `# ${localSubjectName} {=${shortSubject}${typeAnnotations}}\n\n`;
 
-        const headingBlock = {
-            id: generateBlockId(),
-            range: { start: currentPos, end: currentPos + headingText.length },
-            subject: subjectIRI,
-            types: types.map(t => t.object.value),
-            predicates: [],
-            context: { ...context },
-            carrierType: 'heading',
-            attrsRange: { start: currentPos + headingText.indexOf('{'), end: currentPos + headingText.indexOf('}') + 1 },
-            valueRange: { start: currentPos + 2, end: currentPos + 2 + localSubjectName.length }
-        };
-
-        // Add type quads to quadMap
-        types.forEach((quad, i) => {
-            const key = quadIndexKey(quad.subject, quad.predicate, quad.object);
-            quadMap.set(key, createUnifiedSlot(headingBlock, i, {
-                kind: 'type',
-                subject: quad.subject,
-                predicate: quad.predicate,
-                object: quad.object
-            }));
-        });
-
         text += headingText;
-        currentPos += headingText.length;
 
         // Add literals (deterministic order)
         const sortedLiterals = literals.sort((a, b) => a.predicate.value.localeCompare(b.predicate.value));
@@ -166,30 +134,7 @@ function buildDeterministicMDLD(subjectGroups, context) {
             }
 
             const literalText = `[${quad.object.value}] {${annotation}}\n`;
-            const literalBlock = {
-                id: generateBlockId(),
-                range: { start: currentPos, end: currentPos + literalText.length },
-                subject: subjectIRI,
-                types: [],
-                predicates: [{ iri: quad.predicate.value, form: '' }],
-                context: { ...context },
-                carrierType: 'span',
-                valueRange: { start: currentPos + 1, end: currentPos + 1 + quad.object.value.length },
-                attrsRange: { start: currentPos + literalText.indexOf('{'), end: currentPos + literalText.indexOf('}') + 1 }
-            };
-
-            // Add to quadMap
-            const key = quadIndexKey(quad.subject, quad.predicate, quad.object);
-            quadMap.set(key, createUnifiedSlot(literalBlock, 0, {
-                kind: 'pred',
-                subject: quad.subject,
-                predicate: quad.predicate,
-                object: quad.object,
-                form: ''
-            }));
-
             text += literalText;
-            currentPos += literalText.length;
         }
 
         // Add objects (deterministic order)
@@ -198,40 +143,11 @@ function buildDeterministicMDLD(subjectGroups, context) {
             const objShort = shortenIRI(quad.object.value, context);
             const predShort = shortenIRI(quad.predicate.value, context);
             const objectText = `[${objShort}] {+${objShort} ?${predShort}}\n`;
-
-            const objectBlock = {
-                id: generateBlockId(),
-                range: { start: currentPos, end: currentPos + objectText.length },
-                subject: subjectIRI,
-                types: [],
-                predicates: [{ iri: quad.predicate.value, form: '?' }],
-                context: { ...context },
-                carrierType: 'span',
-                valueRange: { start: currentPos + 1, end: currentPos + 1 + objShort.length },
-                attrsRange: { start: currentPos + objectText.indexOf('{'), end: currentPos + objectText.indexOf('}') + 1 }
-            };
-
-            // Add to quadMap
-            const key = quadIndexKey(quad.subject, quad.predicate, quad.object);
-            quadMap.set(key, createUnifiedSlot(objectBlock, 0, {
-                kind: 'pred',
-                subject: quad.subject,
-                predicate: quad.predicate,
-                object: quad.object,
-                form: '?'
-            }));
-
             text += objectText;
-            currentPos += objectText.length;
         }
 
         text += '\n';
-        currentPos += 1;
     }
 
-    return { text, quadMap };
-}
-
-function generateBlockId() {
-    return Math.random().toString(36).substring(2, 10);
+    return { text };
 }

package/src/index.js

@@ -1,5 +1,5 @@
 export { parse } from './parse.js';
-export { applyDiff } from './applyDiff.js';
+export { merge } from './merge.js';
 export { generate } from './generate.js';
 export { locate } from './locate.js';
 export { render } from './render.js';

package/src/locate.js

@@ -1,75 +1,38 @@
-import { parse } from './parse.js';
-import { normalizeQuad, quadIndexKey } from './utils.js';
+import { quadToKeyForOrigin } from './utils.js';
 
 /**
- * Locate the precise text range of a quad in MDLD text using origin tracking
+ * Locate the origin entry for a quad using the lean origin system
  * 
  * @param {Object} quad - The quad to locate (subject, predicate, object)
- * @param {Object} origin - Origin object containing blocks and quadIndex (optional)
- * @param {string} text - Original MDLD text (optional, parsed if origin not provided)
- * @param {Object} context - Context for parsing (optional, used if text needs parsing)
- * @returns {Object|null} Range information or null if not found
+ * @param {Object} origin - Origin object containing quadIndex
+ * @returns {Object|null} Origin entry or null if not found
  */
-export function locate(quad, origin, text = '', context = {}) {
-    // If origin not provided, parse text to get origin
-    if (!origin && text) {
-        const parseResult = parse(text, { context });
-        origin = parseResult.origin;
-    }
-
-    if (!quad || !origin || !origin.quadMap) {
+export function locate(quad, origin) {
+    if (!quad || !origin || !origin.quadIndex) {
         return null;
     }
 
-    // Normalize the quad for consistent key generation
-    const normalizedQuad = normalizeQuad(quad);
-    if (!normalizedQuad) {
+    // Generate the quad key to lookup in quadIndex
+    const quadKey = quadToKeyForOrigin(quad);
+    if (!quadKey) {
         return null;
     }
 
-    // Generate the quad key to lookup in quadMap
-    const quadKey = quadIndexKey(normalizedQuad.subject, normalizedQuad.predicate, normalizedQuad.object);
-
-    // Find the slot information in quadMap
-    const slotInfo = origin.quadMap.get(quadKey);
-    if (!slotInfo) {
+    // Find the origin entry in quadIndex
+    const entry = origin.quadIndex.get(quadKey);
+    if (!entry) {
         return null;
     }
 
-    // In unified structure, slotInfo contains all block information
-    const block = slotInfo;
-
-    // Extract the actual text content based on carrier type
-    let contentRange = null;
-    let content = '';
-
-    if (block.carrierType === 'heading') {
-        // For headings, use the value range for the heading text
-        contentRange = block.valueRange;
-        content = text.substring(block.valueRange.start, block.valueRange.end);
-    } else if (block.carrierType === 'emphasis' || block.carrierType === 'blockquote' || block.carrierType === 'list' || block.carrierType === 'span') {
-        // For emphasis, blockquotes, lists, and spans, use the value range
-        if (block.valueRange) {
-            contentRange = block.valueRange;
-            content = text.substring(block.valueRange.start, block.valueRange.end);
-        } else {
-            // Fallback to block range
-            contentRange = block.range;
-            content = text.substring(block.range.start, block.range.end);
-        }
-    }
-
+    // Return the lean origin entry structure
     return {
-        blockId: slotInfo.id,
-        entryIndex: slotInfo.entryIndex,
-        kind: slotInfo.kind,
-        subject: normalizedQuad.subject,
-        predicate: normalizedQuad.predicate,
-        object: normalizedQuad.object,
-        range: contentRange,
-        content: content,
-        blockRange: block.range,
-        carrierType: block.carrierType,
-        isVacant: slotInfo.isVacant || false
+        blockId: entry.blockId,
+        range: entry.range,
+        carrierType: entry.carrierType,
+        subject: entry.subject,
+        predicate: entry.predicate,
+        context: entry.context,
+        value: entry.value,
+        polarity: entry.polarity
     };
 }

package/src/merge.js

@@ -0,0 +1,131 @@
+import { parse } from './parse.js';
+import { DEFAULT_CONTEXT } from './utils.js';
+
+/**
+ * Creates a unique key for quad identity matching
+ * @param {Quad} quad 
+ * @returns {string}
+ */
+function quadKey(quad) {
+    const datatype = quad.object.datatype?.value || '';
+    const language = quad.object.language || '';
+    return `${quad.subject.value}|${quad.predicate.value}|${quad.object.value}|${datatype}|${language}`;
+}
+
+/**
+ * Normalizes merge input to ParseResult format
+ * @param {string|ParseResult} input 
+ * @param {Object} options
+ * @param {Object} docContext
+ * @returns {ParseResult}
+ */
+function normalizeInput(input, options, docContext) {
+    if (typeof input === 'string') {
+        return parse(input, {
+            ...options,
+            context: { ...docContext, ...options.context }
+        });
+    }
+    // ParseResult passthrough - no re-parse
+    return input;
+}
+
+/**
+ * Merges multiple MDLD documents with diff polarity resolution
+ * @param {Array<string|ParseResult>} docs 
+ * @param {Object} options
+ * @returns {Object}
+ */
+export function merge(docs, options = {}) {
+    const sessionBuffer = new Map(); // Use Map instead of Set for proper quad storage
+    const sessionRemoveSet = new Set();
+    const allDocuments = [];
+    const quadIndex = new Map();
+
+    // Process each document in order
+    for (let i = 0; i < docs.length; i++) {
+        const input = docs[i];
+
+        // Each document gets the same context (no inheritance)
+        const docContext = { ...DEFAULT_CONTEXT, ...options.context };
+
+        // Normalize input to ParseResult
+        const doc = normalizeInput(input, options, docContext);
+
+        // Create document origin
+        const documentOrigin = {
+            index: i,
+            input: typeof input === 'string' ? 'string' : 'ParseResult',
+            origin: doc.origin,
+            context: doc.context
+        };
+        allDocuments.push(documentOrigin);
+
+        // Fold assertions into session buffer
+        for (const quad of doc.quads) {
+            const key = quadKey(quad);
+            sessionBuffer.set(key, quad);
+
+            // Create quad origin with document index and polarity
+            const existingOrigin = doc.origin.quadIndex.get(quadKey(quad));
+            if (existingOrigin) {
+                quadIndex.set(quadKey(quad), {
+                    ...existingOrigin,
+                    documentIndex: i,
+                    polarity: '+'
+                });
+            }
+        }
+
+        // Fold retractions
+        for (const quad of doc.remove) {
+            const key = quadKey(quad);
+
+            if (sessionBuffer.has(key)) {
+                // Inter-document cancel - remove from buffer
+                sessionBuffer.delete(key);
+            } else {
+                // External retract - add to remove set
+                sessionRemoveSet.add(quad);
+            }
+
+            // Create quad origin for remove quads
+            const existingOrigin = doc.origin.quadIndex.get(quadKey(quad));
+            if (existingOrigin) {
+                quadIndex.set(quadKey(quad), {
+                    ...existingOrigin,
+                    documentIndex: i,
+                    polarity: '-'
+                });
+            }
+        }
+    }
+
+    // Build final result
+    const finalQuads = Array.from(sessionBuffer.values());
+    const finalRemove = Array.from(sessionRemoveSet);
+
+    // Build merge origin
+    const mergeOrigin = {
+        documents: allDocuments,
+        quadIndex: quadIndex
+    };
+
+    // Build final context (union of all contexts)
+    const finalContext = { ...DEFAULT_CONTEXT, ...options.context };
+
+    // Enforce hard invariant
+    const quadKeys = new Set(finalQuads.map(quadKey));
+    const removeKeys = new Set(finalRemove.map(quadKey));
+
+    // Filter out any overlaps (shouldn't happen with correct implementation)
+    const filteredQuads = finalQuads.filter(quad => !removeKeys.has(quadKey(quad)));
+    const filteredRemove = finalRemove.filter(quad => !quadKeys.has(quadKey(quad)));
+
+    return {
+        quads: filteredQuads,
+        remove: filteredRemove,
+        origin: mergeOrigin,
+        context: finalContext
+    };
+}

package/src/parse.js

@@ -4,7 +4,6 @@ import {
     expandIRI,
     parseSemanticBlock,
     quadIndexKey,
-    createUnifiedSlot,
     createLiteral,
     hash
 } from './utils.js';
@@ -343,7 +342,7 @@ function determineCarrierType(url) {
     return { carrierType: 'span', resourceIRI: null };
 }
 
-function createBlock(subject, types, predicates, range, attrsRange, valueRange, carrierType, ctx) {
+function createBlock(subject, types, predicates, range, attrsRange, valueRange, carrierType, ctx, text) {
     const expanded = {
         subject,
         types: types.map(t => expandIRI(typeof t === 'string' ? t : t.iri, ctx)),
@@ -356,30 +355,62 @@ function createBlock(subject, types, predicates, range, attrsRange, valueRange,
     return {
         id: blockId,
         range: { start: range[0], end: range[1] },
-        attrsRange: attrsRange ? { start: attrsRange[0], end: attrsRange[1] } : null,
-        valueRange: valueRange ? { start: valueRange[0], end: valueRange[1] } : null,
         carrierType: carrierType || null,
         subject,
         types: expanded.types,
         predicates: expanded.predicates,
-        context: ctx
+        context: ctx,
+        text: text || ''
     };
 }
 
-function emitQuad(quads, quadMap, block, subject, predicate, object, dataFactory, meta = null) {
+function emitQuad(quads, quadBuffer, removeSet, quadIndex, block, subject, predicate, object, dataFactory, meta = null) {
     if (!subject || !predicate || !object) return;
 
     const quad = dataFactory.quad(subject, predicate, object);
-    quads.push(quad);
-
-    const unifiedSlot = createUnifiedSlot(block, meta?.entryIndex, {
-        ...meta,
-        subject,
-        predicate,
-        object
-    });
-
-    quadMap.set(quadIndexKey(quad.subject, quad.predicate, quad.object), unifiedSlot);
+    const remove = meta?.remove || false;
+
+    if (remove) {
+        // Check if quad exists in current buffer
+        const quadKey = quadIndexKey(quad.subject, quad.predicate, quad.object);
+        if (quadBuffer.has(quadKey)) {
+            // In current state → cancel, appears nowhere
+            quadBuffer.delete(quadKey);
+            // Also remove from quads array if present
+            const index = quads.findIndex(q =>
+                q.subject.value === quad.subject.value &&
+                q.predicate.value === quad.predicate.value &&
+                q.object.value === quad.object.value
+            );
+            if (index !== -1) {
+                quads.splice(index, 1);
+            }
+            // Remove from quadIndex
+            quadIndex.delete(quadKey);
+        } else {
+            // Not in current state → external retract
+            removeSet.add(quad);
+        }
+    } else {
+        // Add to buffer and quads
+        const quadKey = quadIndexKey(quad.subject, quad.predicate, quad.object);
+        quadBuffer.set(quadKey, quad);
+        quads.push(quad);
+
+        // Create lean origin entry
+        const originEntry = {
+            blockId: block.id,
+            range: block.range,
+            carrierType: block.carrierType,
+            subject: subject.value,
+            predicate: predicate.value,
+            context: { ...block.context },
+            polarity: meta?.remove ? '-' : '+',
+            value: block.text || ''
+        };
+
+        quadIndex.set(quadKey, originEntry);
+    }
 }
 
 const resolveFragment = (fragment, state) => {
@@ -406,23 +437,24 @@ function resolveObject(sem, state) {
 
 const createTypeQuad = (typeIRI, subject, state, block, entryIndex = null) => {
     const expandedType = expandIRI(typeIRI, state.ctx);
+    const typeInfo = typeof entryIndex === 'object' ? entryIndex : { entryIndex, remove: false };
     emitQuad(
-        state.quads, state.origin.quadMap, block,
+        state.quads, state.quadBuffer, state.removeSet, state.origin.quadIndex, block,
         subject,
         state.df.namedNode(expandIRI('rdf:type', state.ctx)),
         state.df.namedNode(expandedType),
         state.df,
-        { kind: 'type', token: `.${typeIRI}`, expandedType, entryIndex }
+        { kind: 'type', token: `.${typeIRI}`, expandedType, entryIndex: typeInfo.entryIndex, remove: typeInfo.remove }
     );
 };
 
 function processTypeAnnotations(sem, newSubject, localObject, carrierO, S, block, state, carrier) {
     sem.types.forEach(t => {
         const typeIRI = typeof t === 'string' ? t : t.iri;
-        const entryIndex = typeof t === 'string' ? null : t.entryIndex;
+        const typeInfo = typeof t === 'string' ? { entryIndex: null, remove: false } : t;
         // Type subject priority: explicit subject > soft object > carrier URL > current subject
         let typeSubject = newSubject || localObject || carrierO || S;
-        createTypeQuad(typeIRI, typeSubject, state, block, entryIndex);
+        createTypeQuad(typeIRI, typeSubject, state, block, typeInfo);
     });
 }
 
@@ -453,9 +485,9 @@ function processPredicateAnnotations(sem, newSubject, previousSubject, localObje
         const role = determinePredicateRole(pred, carrier, newSubject, previousSubject, localObject, newSubjectOrCarrierO, S, L);
         if (role) {
             const P = state.df.namedNode(expandIRI(pred.iri, state.ctx));
-            emitQuad(state.quads, state.origin.quadMap, block,
+            emitQuad(state.quads, state.quadBuffer, state.removeSet, state.origin.quadIndex, block,
                 role.subject, P, role.object, state.df,
-                { kind: 'pred', token: `${pred.form}${pred.iri}`, form: pred.form, expandedPredicate: P.value, entryIndex: pred.entryIndex }
+                { kind: 'pred', token: `${pred.form}${pred.iri}`, form: pred.form, expandedPredicate: P.value, entryIndex: pred.entryIndex, remove: pred.remove || false }
             );
         }
     });
@@ -483,7 +515,7 @@ function processAnnotation(carrier, sem, state, options = {}) {
     const block = createBlock(
         S.value, sem.types, sem.predicates,
         carrier.range, carrier.attrsRange || null, carrier.valueRange || null,
-        carrier.type || null, state.ctx
+        carrier.type || null, state.ctx, carrier.text
     );
 
     const L = createLiteral(carrier.text, sem.datatype, sem.language, state.ctx, state.df);
@@ -555,7 +587,9 @@ export function parse(text, options = {}) {
         ctx: { ...DEFAULT_CONTEXT, ...(options.context || {}) },
         df: options.dataFactory || DataFactory,
         quads: [],
-        origin: { quadMap: new Map() },
+        quadBuffer: new Map(),
+        removeSet: new Set(),
+        origin: { quadIndex: new Map() },
         currentSubject: null,
         tokens: null,
         currentTokenIndex: -1
@@ -582,5 +616,18 @@ export function parse(text, options = {}) {
         TOKEN_PROCESSORS[token.type]?.(token, state);
     }
 
-    return { quads: state.quads, origin: state.origin, context: state.ctx };
+    // Convert removeSet to array and ensure hard invariant: quads ∩ remove = ∅
+    const removeArray = Array.from(state.removeSet);
+    const quadKeys = new Set();
+    state.quads.forEach(q => {
+        quadKeys.add(quadIndexKey(q.subject, q.predicate, q.object));
+    });
+
+    // Filter removeArray to ensure no overlap with quads
+    const filteredRemove = removeArray.filter(quad => {
+        const key = quadIndexKey(quad.subject, quad.predicate, quad.object);
+        return !quadKeys.has(key);
+    });
+
+    return { quads: state.quads, remove: filteredRemove, origin: state.origin, context: state.ctx };
 }