mdld-parse 0.7.5 → 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 }`
 
@@ -293,16 +301,3 @@ Tests validate:
 - Explicit list item annotations
 - Code blocks and blockquotes
 - Round-trip serialization
-
-## 🤝 Contributing
-
-Contributions welcome! Please:
-
-1. Read the [specification](https://mdld.js.org/spec)
-2. Add tests for new features
-3. Ensure all tests pass
-4. Follow existing code style
-
-## 📄 License
-
-See [LICENCE](./LICENCE)

package/package.json

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

package/LICENCE

@@ -1,167 +0,0 @@
-# MDLD / MD-LD Community License
-
-Version 0.3 — 2025
-
-Copyright © 2025–present  
-**Denis Starov**  
-All rights reserved.
-
----
-
-## 0. Definitions
-
-For the purposes of this license:
-
-**“MDLD” or “MD-LD”** refers to the Markdown-Linked Data specification, including all versions, drafts, documentation, reference implementations, tests, examples, and associated materials published by the author.
-
-**“Commercial Use”** means any use of MDLD that is part of, or directly supports, a for-profit activity, including but not limited to the offering of products or services for sale, subscription, advertising, data monetization, or other commercial advantage.
-
-**“Server-side use”** means processing, storing, transforming, or serving MDLD documents on infrastructure operated by a third party for multiple users, including hosted platforms and network-accessible services.
-
-**“For-profit entity”** means any organization or legal entity operating with profit intent, including corporations, subsidiaries, startups, and entities backed by private equity or venture capital, regardless of current revenue.
-
-**“Proprietary AI system”** means any artificial intelligence or machine learning system whose model weights, training data, or full source code are not publicly available under an OSI-approved open-source license.
-
----
-
-## 1. Scope
-
-This license applies to:
-
-- The MDLD / MD-LD specification
-- All reference implementations
-- Documentation, examples, test suites, and published materials
-- Associated repositories and official distributions
-
-This license does not grant rights to independently created works that merely interoperate with MDLD, provided they do not copy or derive from the licensed materials.
-
----
-
-## 2. Guiding intent (non-normative)
-
-MDLD is designed to support individuals, educators, researchers, and communities in creating, exchanging, and working with structured knowledge in an open and durable way.
-
-This license seeks to encourage broad personal and community use while preventing unacknowledged commercial appropriation, standard capture, and extraction of value into proprietary platforms, particularly in the context of hosted services and large-scale AI systems.
-
----
-
-## 3. Permitted use (no permission required)
-
-The following uses are permitted worldwide and royalty-free:
-
-### 3.1 Individual and community use
-
-- Authoring, reading, and sharing MDLD documents
-- Personal, local, or offline tools and workflows
-- Open-source software released under OSI-approved licenses
-- Non-commercial websites, static content, and community projects
-- Internal use by individuals for personal productivity
-
-### 3.2 Research and education
-
-- Academic research conducted by non-profit institutions
-- Teaching, learning, and scholarly experimentation
-- Non-commercial prototypes, demonstrations, and publications
-
-### 3.3 Personal AI and local automation
-
-- Use of MDLD with local or third-party AI tools for personal, educational, or research purposes
-- Interactive or single-user analysis of MDLD documents
-- Automation workflows that do not provide MDLD processing as a hosted service to others
-
----
-
-## 4. Restricted use (explicit permission required)
-
-The following uses are not permitted without explicit written permission from the author:
-
-### 4.1 Commercial server-side services
-
-- Offering MDLD processing, storage, or transformation as part of a hosted, multi-user, or server-side service
-- Software-as-a-Service (SaaS), cloud platforms, or subscription products where MDLD is a core or marketed feature
-- Paid APIs or hosted tools that accept or emit MDLD documents
-
-### 4.2 Artificial intelligence and machine learning systems
-
-- Training, fine-tuning, or evaluating proprietary or closed-source AI or ML models using:
-  - the MDLD specification
-  - reference implementations
-  - example corpora, tests, or documentation
-- Including MDLD materials in commercial datasets, benchmarks, or evaluation suites
-- Providing paid AI features or services that rely on MDLD as an input or output format
-
-### 4.3 For-profit product and platform use
-
-- Use of MDLD by for-profit entities as part of any product, platform, or service offering made available to customers, users, or clients
-- Use that contributes to the development, protection, or monetization of proprietary technology, products, or services
-- Use that is reasonably expected to support commercial differentiation, intellectual property claims, or capital formation
-
-### 4.4 Standard capture and misrepresentation
-
-- Representing MDLD as an independently governed or competing standard without permission
-- Claiming authorship, stewardship, or official status with respect to MDLD
-- Publishing incompatible extensions, variants, or forks under the MDLD or MD-LD name
-
-### 4.5 Internal corporate use
-
-Internal use of MDLD by for-profit entities is permitted solely for temporary evaluation or experimentation.
-
-Continued internal use that supports, informs, or precedes a commercial product or service requires explicit permission.
-
----
-
-## 5. Attribution and naming
-
-Any permitted use must include clear attribution:
-
-> “MDLD / MD-LD — Markdown-Linked Data, by Denis Starov”
-
-The names “MDLD” and “MD-LD” may not be used to identify derivative formats, forks, or extensions without explicit permission.
-
----
-
-## 6. No trademark grant
-
-This license does not grant any trademark rights.
-
-All trademarks, service marks, and names associated with MDLD remain the property of the author.
-
----
-
-## 7. Commercial licensing
-
-Commercial use is possible under a separate written agreement.
-
-Commercial licenses may include rights for:
-
-- SaaS and hosted services
-- AI and machine learning systems
-- Enterprise redistribution
-- Long-term support or collaboration
-
-Contact details for commercial licensing are provided in the official repository.
-
----
-
-## 8. Termination
-
-Any use in violation of this license automatically terminates all rights granted herein.
-
-Upon termination, the violating party must immediately cease all use, distribution, and promotion of the MDLD materials.
-
-Termination does not require notice and does not limit the author’s right to pursue other remedies.
-
----
-
-## 9. No warranty
-
-MDLD and all associated materials are provided “as is”, without warranty of any kind, express or implied.
-
----
-
-## 10. License versions
-
-This license applies on a per-version basis.
-
-Future versions of this license do not retroactively alter rights granted under this version.  
-Users may elect to adopt newer versions at their discretion.