mdld-parse 0.7.6 → 0.7.7

package/README.md

@@ -198,13 +198,14 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
   - `context` (object) — Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
   - `dataFactory` (object) — Custom RDF/JS DataFactory
 
-**Returns:** `{ quads, remove, statements, origin, context }`
+**Returns:** `{ quads, remove, statements, origin, context, primarySubject }`
 
 - `quads` — Array of RDF/JS Quads (final resolved graph state)
 - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
 - `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
 - `origin` — Lean origin tracking object with quadIndex for UI navigation
 - `context` — Final context used (includes prefixes)
+- `primarySubject` — String IRI or null (first non-fragment subject declaration)
 
 ### `merge(docs, options)`
 
@@ -215,15 +216,22 @@ Merge multiple MDLD documents with diff polarity resolution.
 - `options` (object, optional):
   - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
 
-**Returns:** `{ quads, remove, origin, context }`
+**Returns:** `{ quads, remove, origin, context, primarySubjects }`
 
-### `generate(quads, context)`
+- `quads` — Array of RDF/JS Quads (final resolved graph state)
+- `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
+- `origin` — Merge origin tracking with document index and polarity
+- `context` — Final merged context
+- `primarySubjects` — Array of string IRIs (primary subjects from each document, in merge order)
+
+### `generate(quads, context, primarySubject)`
 
 Generate deterministic MDLD from RDF quads.
 
 **Parameters:**
 - `quads` (array) — Array of RDF/JS Quads to convert
 - `context` (object, optional) — Prefix mappings (default: `{}`)
+- `primarySubject` (string, optional) — String IRI to place first in output (ensures round-trip safety)
 
 **Returns:** `{ text, context }`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mdld-parse",
-	"version": "0.7.6",
+	"version": "0.7.7",
 	"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

@@ -34,17 +34,17 @@ export function extractLocalName(iri, ctx = {}) {
 /**
  * Generate deterministic MDLD from RDF quads
  * Purpose: TTL→MDLD conversion with canonical structure
- * Input: RDF quads + context
+ * Input: RDF quads + context + optional primarySubject (string IRI)
  * Output: MDLD text
  */
-export function generate(quads, context = {}) {
+export function generate(quads, context = {}, primarySubject = null) {
     const fullContext = { ...DEFAULT_CONTEXT, ...context };
 
     const normalizedQuads = normalizeAndSortQuads(quads);
 
     const subjectGroups = groupQuadsBySubject(normalizedQuads);
 
-    const { text } = buildDeterministicMDLD(subjectGroups, fullContext);
+    const { text } = buildDeterministicMDLD(subjectGroups, fullContext, primarySubject);
 
     return text;
 }
@@ -86,7 +86,7 @@ function groupQuadsBySubject(quads) {
     return groups;
 }
 
-function buildDeterministicMDLD(subjectGroups, context) {
+function buildDeterministicMDLD(subjectGroups, context, primarySubject = null) {
     let text = '';
     const usedPrefixes = collectUsedPrefixes(subjectGroups, context);
 
@@ -103,10 +103,16 @@ function buildDeterministicMDLD(subjectGroups, context) {
         text += '\n';
     }
 
-    // Process subjects in deterministic order
+    // Process subjects in deterministic order, with primary subject first
     const sortedSubjects = Array.from(subjectGroups.keys()).sort();
+    const primarySubjectIRI = primarySubject; // Already a string IRI
 
-    for (const subjectIRI of sortedSubjects) {
+    // If primary subject exists, place it first
+    const orderedSubjects = primarySubjectIRI
+        ? [primarySubjectIRI, ...sortedSubjects.filter(s => s !== primarySubjectIRI)]
+        : sortedSubjects;
+
+    for (const subjectIRI of orderedSubjects) {
         const subjectQuads = subjectGroups.get(subjectIRI);
         const shortSubject = shortenIRI(subjectIRI, context);
 
@@ -119,7 +125,7 @@ function buildDeterministicMDLD(subjectGroups, context) {
             ? ' ' + types.map(t => '.' + shortenIRI(t.object.value, context)).sort().join(' ')
             : '';
 
-        text += `# ${localSubjectName} {=${shortSubject}${typeAnnotations}}\n`;
+        text += `# ${localSubjectName} {=${shortSubject}${typeAnnotations}}\n\n`;
 
         // Add literals and objects using shared utilities
         sortQuadsByPredicate(literals).forEach(quad => {

package/src/merge.js

@@ -42,6 +42,7 @@ export function merge(docs, options = {}) {
     const quadIndex = new Map();
     const allStatements = []; // Collect statements from all documents
     const accumulatedContext = new Map(); // Track all unique prefixes across documents
+    const primarySubjects = []; // Collect primary subjects from all documents
 
     // Process each document in order
     for (let i = 0; i < docs.length; i++) {
@@ -78,6 +79,11 @@ export function merge(docs, options = {}) {
             allStatements.push(...doc.statements);
         }
 
+        // Collect primary subject from this document (already a string IRI)
+        if (doc.primarySubject) {
+            primarySubjects.push(doc.primarySubject);
+        }
+
         // Fold assertions into session buffer
         for (const quad of doc.quads) {
             const key = quadKey(quad);
@@ -144,6 +150,7 @@ export function merge(docs, options = {}) {
         remove: filteredRemove,
         statements: allStatements, // Include all collected statements
         origin: mergeOrigin,
-        context: finalContext
+        context: finalContext,
+        primarySubjects: primarySubjects // Include all collected primary subjects
     };
 }

package/src/parse.js

@@ -49,6 +49,7 @@ export function parse(text, options = {}) {
     const state = {
         ctx: { ...DEFAULT_CONTEXT, ...(options.context || {}) },
         df: options.dataFactory || DataFactory,
+        graph: DataFactory.namedNode(options.graph) || DataFactory.defaultGraph(),
         quads: [],
         quadBuffer: new Map(),
         removeSet: new Set(),
@@ -58,6 +59,7 @@ export function parse(text, options = {}) {
             documentStructure: []
         },
         currentSubject: null,
+        primarySubject: null,
         tokens: null,
         currentTokenIndex: -1,
         statements: [],
@@ -107,7 +109,7 @@ export function parse(text, options = {}) {
         }
     }
 
-    return { quads: state.quads, remove: filteredRemove, statements: state.statements, origin: state.origin, context: state.ctx };
+    return { quads: state.quads, remove: filteredRemove, statements: state.statements, origin: state.origin, context: state.ctx, primarySubject: state.primarySubject };
 }
 
 
@@ -387,6 +389,11 @@ function processAnnotationWithBlockTracking(carrier, sem, state, options = {}) {
     const newSubject = resolveSubject(sem, state);
     const localObject = resolveObject(sem, state);
 
+    // Track primary subject: first non-fragment subject declaration (fixed once detected)
+    if (newSubject && !state.primarySubject && !sem.subject.startsWith('=#')) {
+        state.primarySubject = newSubject.value; // Store as string IRI
+    }
+
     const effectiveSubject = implicitSubject || (newSubject && !preserveGlobalSubject ? newSubject : previousSubject);
     if (newSubject && !preserveGlobalSubject && !implicitSubject) {
         state.currentSubject = newSubject;