mdld-parse 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +29 -4
  2. package/dist/index.js +84 -18
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -139,6 +139,7 @@ Action items:
139
139
  - **🧩 Fragments** — Document structuring with `{=#fragment}`
140
140
  - **⚡ Polarity system** — Sophisticated diff authoring with `+` and `-` prefixes
141
141
  - **📍 Origin tracking** — Complete provenance with lean quad-to-source mapping
142
+ - **🔗 Span chains** — Walkable textual topology between semantic blocks for context recovery and resonance
142
143
  - **🎯 Elevated statements** — Automatic rdf:Statement pattern detection
143
144
  - **🏷️ Primary metadata quartet** — Subject, type, label, comment for document identity
144
145
  - **🔄 Round-trip safety** — Deterministic parse ↔ generate cycles
@@ -263,7 +264,7 @@ Parse MDLD to RDF quads with lean origin tracking.
263
264
  - `quads` — RDF/JS Quads (final resolved graph state)
264
265
  - `remove` — RDF/JS Quads (external retractions for diff workflows)
265
266
  - `statements` — Elevated SPO quads from rdf:Statement patterns
266
- - `origin` — Lean origin tracking for UI navigation
267
+ - `origin` — Lean origin tracking: `quadIndex`, `blocks`, `spans`, `documentStructure`
267
268
  - `context` — Final context with prefixes
268
269
  - `primarySubject` — String IRI or null (canonical append identity)
269
270
  - `primary` — Primary metadata quartet: `{ subject, type, label, comment }`
@@ -290,7 +291,7 @@ Merge multiple MDLD documents with diff polarity resolution.
290
291
 
291
292
  **Use case:** CRDT-style state management with append-only documents.
292
293
 
293
- ### `generate({ quads, context, primarySubject, compactInline, renderReverse, remove })`
294
+ ### `generate({ quads, context, primarySubject, compactInline, renderReverse, remove, lang })`
294
295
 
295
296
  Generate deterministic MDLD from RDF quads.
296
297
 
@@ -301,6 +302,7 @@ Generate deterministic MDLD from RDF quads.
301
302
  - `compactInline` (boolean, optional) — Inline type/label compaction (default: `false`)
302
303
  - `renderReverse` (boolean, optional) — Reverse connections as `!p` (default: `false`)
303
304
  - `remove` (array, optional) — RDF/JS Quads to retract (for diff generation)
305
+ - `lang` (string, optional) — Preferred language for labels (e.g., `'en'`, `'es'`, `'fr'`). Priority: specified lang → untagged → English → any language
304
306
 
305
307
  **Returns:** `{ text, context, compactStats }`
306
308
 
@@ -308,9 +310,17 @@ Generate deterministic MDLD from RDF quads.
308
310
  - `context` — Full context with prefixes
309
311
  - `compactStats` — Compaction metrics
310
312
 
311
- **Features:** Visual styling, label-in-heading, round-trip safe, diff generation.
313
+ **Features:** Visual styling, label-in-heading, round-trip safe, diff generation, language preference.
312
314
 
313
- ### `generateNode({ quads, focusIRI, context, compactInline, renderReverse })`
315
+ **Example with language preference:**
316
+ ```javascript
317
+ const { text } = generate({
318
+ quads: result.quads,
319
+ lang: 'es' // Prefer Spanish labels
320
+ });
321
+ ```
322
+
323
+ ### `generateNode({ quads, focusIRI, context, compactInline, renderReverse, lang })`
314
324
 
315
325
  Generate node-centric MDLD for a specific IRI.
316
326
 
@@ -320,6 +330,7 @@ Generate node-centric MDLD for a specific IRI.
320
330
  - `context` (object, optional) — Prefix mappings
321
331
  - `compactInline` (boolean, optional) — Inline compaction (default: `true`)
322
332
  - `renderReverse` (boolean, optional) — Reverse connections (default: `true`)
333
+ - `lang` (string, optional) — Preferred language for labels (e.g., `'en'`, `'es'`, `'fr'`). Priority: specified lang → untagged → English → any language
323
334
 
324
335
  **Returns:** `{ text, context, compactStats }`
325
336
 
@@ -367,6 +378,20 @@ import {
367
378
  - **Standards-compliant** — RDF/JS data model, W3C CURIE 1.0 syntax
368
379
  - **Deterministic** — Same input always produces same output
369
380
  - **Explicit semantics** — No guessing, inference, or heuristics
381
+ - **Dual-layer origin** — Every parse emits both a semantic quad graph and a walkable textual topology graph simultaneously
382
+
383
+ ### Origin: Blocks and Spans
384
+
385
+ The parser output includes a complete document chain at no extra cost:
386
+
387
+ ```
388
+ [Block] --(Span)-- [Block] --(Span)-- [Block]
389
+ ```
390
+
391
+ - **Blocks** (`origin.blocks`) — semantic anchors: tokens that produced RDF quads, with `prevSpanId`/`nextSpanId` links
392
+ - **Spans** (`origin.spans`) — textual observations: raw byte ranges between blocks, with bidirectional block and span links
393
+
394
+ Spans store no text — content is always recovered via `sourceText.slice(span.range[0], span.range[1])`. This unlocks context-aware UI, autocomplete neighborhood retrieval, and cross-document topology without any parser-level interpretation.
370
395
 
371
396
  ### Performance Characteristics
372
397
  - **Real-time (60fps):** Up to 4,527 quads per frame
package/dist/index.js CHANGED
@@ -1053,6 +1053,7 @@ function parse(firstArg, secondArg = {}) {
1053
1053
  origin: {
1054
1054
  quadIndex: /* @__PURE__ */ new Map(),
1055
1055
  blocks: /* @__PURE__ */ new Map(),
1056
+ spans: /* @__PURE__ */ new Map(),
1056
1057
  documentStructure: []
1057
1058
  },
1058
1059
  currentSubject: null,
@@ -1064,7 +1065,10 @@ function parse(firstArg, secondArg = {}) {
1064
1065
  statements: [],
1065
1066
  statementCandidates: /* @__PURE__ */ new Map(),
1066
1067
  currentBlock: null,
1067
- blockStack: []
1068
+ blockStack: [],
1069
+ lastBlockEnd: 0,
1070
+ lastBlockId: null,
1071
+ lastSpanId: null
1068
1072
  };
1069
1073
  const scanResult = scanTokens(text);
1070
1074
  state.tokens = scanResult.tokens;
@@ -1289,6 +1293,36 @@ function createBlockEntry(token, state) {
1289
1293
  token._blockId = blockId;
1290
1294
  const carriers = getCarriers(token);
1291
1295
  const cleanText = extractCleanText(token);
1296
+ const blockStart = token.range[0];
1297
+ const blockEnd = token.range[1];
1298
+ let prevSpanId = null;
1299
+ if (state.lastBlockId !== null) {
1300
+ const spanStart = state.lastBlockEnd;
1301
+ const spanEnd = blockStart;
1302
+ if (spanEnd > spanStart) {
1303
+ const spanId = hash(`span:${spanStart}:${spanEnd}`);
1304
+ const span = {
1305
+ id: spanId,
1306
+ range: [spanStart, spanEnd],
1307
+ prevBlockId: state.lastBlockId,
1308
+ nextBlockId: blockId,
1309
+ prevSpanId: state.lastSpanId || null,
1310
+ nextSpanId: null,
1311
+ byteLength: spanEnd - spanStart
1312
+ };
1313
+ state.origin.spans.set(spanId, span);
1314
+ if (state.lastSpanId) {
1315
+ const prevSpan = state.origin.spans.get(state.lastSpanId);
1316
+ if (prevSpan) prevSpan.nextSpanId = spanId;
1317
+ }
1318
+ const prevBlock = state.origin.blocks.get(state.lastBlockId);
1319
+ if (prevBlock) prevBlock.nextSpanId = spanId;
1320
+ state.lastSpanId = spanId;
1321
+ prevSpanId = spanId;
1322
+ }
1323
+ }
1324
+ state.lastBlockEnd = blockEnd;
1325
+ state.lastBlockId = blockId;
1292
1326
  const blockEntry = {
1293
1327
  id: blockId,
1294
1328
  type: token.type,
@@ -1300,7 +1334,9 @@ function createBlockEntry(token, state) {
1300
1334
  carriers: [],
1301
1335
  listLevel: token.indent || 0,
1302
1336
  parentBlockId: state.blockStack.length > 0 ? state.blockStack[state.blockStack.length - 1] : null,
1303
- quadKeys: []
1337
+ quadKeys: [],
1338
+ prevSpanId,
1339
+ nextSpanId: null
1304
1340
  };
1305
1341
  for (const carrier of carriers) {
1306
1342
  const carrierInfo = {
@@ -1700,16 +1736,16 @@ function extractLocalName(iri, ctx = {}) {
1700
1736
  /**
1701
1737
  * Generate deterministic MDLD from RDF quads
1702
1738
  * Purpose: TTL→MDLD conversion with canonical structure
1703
- * Input: RDF quads + context + optional primarySubject (string IRI) + compactInline (boolean) + remove (array)
1739
+ * Input: RDF quads + context + optional primarySubject (string IRI) + compactInline (boolean) + remove (array) + lang (string)
1704
1740
  * Output: MDLD text + context + compactStats
1705
1741
  */
1706
- function generate({ quads, context = {}, primarySubject = null, compactInline = false, renderReverse = false, remove = [] }) {
1742
+ function generate({ quads, context = {}, primarySubject = null, compactInline = false, renderReverse = false, remove = [], lang = null }) {
1707
1743
  const fullContext = Object.assign({}, DEFAULT_CONTEXT, context);
1708
1744
  const normalizedQuads = normalizeAndSortQuads(quads);
1709
1745
  const normalizedRemove = normalizeAndSortQuads(remove);
1710
1746
  const { subjectGroups, reverseIndex } = groupQuadsBySubject(normalizedQuads);
1711
1747
  const removeBySubject = groupQuadsBySubject(normalizedRemove).subjectGroups;
1712
- const { text, compactStats } = buildDeterministicMDLD(subjectGroups, fullContext, primarySubject, primarySubject && renderReverse ? reverseIndex : null, compactInline, removeBySubject);
1748
+ const { text, compactStats } = buildDeterministicMDLD(subjectGroups, fullContext, primarySubject, primarySubject && renderReverse ? reverseIndex : null, compactInline, removeBySubject, lang);
1713
1749
  return {
1714
1750
  text,
1715
1751
  context: fullContext,
@@ -1721,7 +1757,7 @@ function generate({ quads, context = {}, primarySubject = null, compactInline =
1721
1757
  * in any position: subject, object, predicate, type, or datatype.
1722
1758
  * Perfect for exploring individual nodes and their complete relationship graph.
1723
1759
  */
1724
- function generateNode({ quads, focusIRI, context = {}, compactInline = true, renderReverse = true }) {
1760
+ function generateNode({ quads, focusIRI, context = {}, compactInline = true, renderReverse = true, lang = null }) {
1725
1761
  if (!quads?.length || !focusIRI) return {
1726
1762
  text: "",
1727
1763
  context: Object.assign({}, DEFAULT_CONTEXT, context),
@@ -1734,7 +1770,7 @@ function generateNode({ quads, focusIRI, context = {}, compactInline = true, ren
1734
1770
  context: fullContext,
1735
1771
  compactStats: null
1736
1772
  };
1737
- const { text, compactStats } = buildDeterministicMDLD(nodeGroups, fullContext, focusIRI, renderReverse ? reverseIndex : null, compactInline);
1773
+ const { text, compactStats } = buildDeterministicMDLD(nodeGroups, fullContext, focusIRI, renderReverse ? reverseIndex : null, compactInline, /* @__PURE__ */ new Map(), lang);
1738
1774
  return {
1739
1775
  text,
1740
1776
  context: fullContext,
@@ -1809,10 +1845,10 @@ function groupQuadsByNode(quads) {
1809
1845
  reverseIndex
1810
1846
  };
1811
1847
  }
1812
- function buildDeterministicMDLD(subjectGroups, context, primarySubject = null, reverseIndex = null, compactInline = true, removeBySubject = /* @__PURE__ */ new Map()) {
1848
+ function buildDeterministicMDLD(subjectGroups, context, primarySubject = null, reverseIndex = null, compactInline = true, removeBySubject = /* @__PURE__ */ new Map(), lang = null) {
1813
1849
  const textParts = [];
1814
1850
  const usedPrefixes = collectUsedPrefixes(subjectGroups, context);
1815
- const labelLookup = buildLabelLookup(subjectGroups);
1851
+ const labelLookup = buildLabelLookup(subjectGroups, lang);
1816
1852
  const compactStats = {
1817
1853
  compactedSubjects: 0,
1818
1854
  skippedHeadings: 0,
@@ -1837,17 +1873,21 @@ function buildDeterministicMDLD(subjectGroups, context, primarySubject = null, r
1837
1873
  }
1838
1874
  const { types, literals, objects } = filteredGroups.get(subjectIRI);
1839
1875
  const shortSubject = getCachedShortIRI(subjectIRI, context);
1840
- const hasLabel = labelLookup.has(subjectIRI);
1841
- const displayName = hasLabel ? labelLookup.get(subjectIRI) : extractLocalName(subjectIRI, context);
1876
+ const labelEntry = labelLookup.get(subjectIRI);
1877
+ const hasLabel = !!labelEntry;
1878
+ const displayName = hasLabel ? labelEntry.value : extractLocalName(subjectIRI, context);
1842
1879
  const typesNotRendered = types.filter((t) => !renderedQuads.has(t));
1843
1880
  let annotations = typesNotRendered.length > 0 ? typesNotRendered.map((t) => "." + getCachedShortIRI(t.object.value, context)).sort().join(" ") : "";
1844
1881
  const labelQuad = subjectQuads.find((q) => q.predicate.value === RDFS_LABEL);
1845
- if (hasLabel && (!labelQuad || !renderedQuads.has(labelQuad))) annotations += (annotations ? " " : "") + "label";
1882
+ if (hasLabel && (!labelQuad || !renderedQuads.has(labelQuad))) {
1883
+ const langTag = labelEntry.language ? " @" + labelEntry.language : "";
1884
+ annotations += (annotations ? " " : "") + "label" + langTag;
1885
+ }
1846
1886
  const annotationStr = annotations ? " " + annotations : "";
1847
1887
  textParts.push(`# ${displayName} {=${shortSubject}${annotationStr}}\n`);
1848
1888
  types.forEach((t) => renderedQuads.add(t));
1849
1889
  if (labelQuad) renderedQuads.add(labelQuad);
1850
- const headingLabel = hasLabel ? labelLookup.get(subjectIRI) : null;
1890
+ const headingLabel = hasLabel ? labelEntry.value : null;
1851
1891
  sortQuadsByPredicate(literals).forEach((quad) => {
1852
1892
  if (quad.predicate.value === "http://www.w3.org/2000/01/rdf-schema#label" && quad.object.value === headingLabel) return;
1853
1893
  textParts.push(generateLiteralText(quad, context));
@@ -1862,15 +1902,17 @@ function buildDeterministicMDLD(subjectGroups, context, primarySubject = null, r
1862
1902
  for (const quad of reverseQuads) {
1863
1903
  renderedQuads.add(quad);
1864
1904
  const subjectQuads = subjectGroups.get(quad.subject.value);
1865
- const subjectLabel = labelLookup.has(quad.subject.value) ? labelLookup.get(quad.subject.value) : extractLocalName(quad.subject.value, context);
1905
+ const subjectLabelEntry = labelLookup.get(quad.subject.value);
1906
+ const subjectLabel = subjectLabelEntry ? subjectLabelEntry.value : extractLocalName(quad.subject.value, context);
1866
1907
  const shortSubject = getCachedShortIRI(quad.subject.value, context);
1867
1908
  const shortPredicate = getCachedShortIRI(quad.predicate.value, context);
1868
1909
  let inlineAnnotation = "";
1869
1910
  if (compactInline && subjectQuads) {
1870
1911
  const { types } = filteredGroups.get(quad.subject.value) || { types: [] };
1871
- const hasLabel = labelLookup.has(quad.subject.value);
1912
+ const reverseSubjectLabelEntry = labelLookup.get(quad.subject.value);
1913
+ const hasLabel = !!reverseSubjectLabelEntry;
1872
1914
  const typeAnnotations = types.length > 0 ? types.map((t) => "." + getCachedShortIRI(t.object.value, context)).sort().join(" ") : "";
1873
- const labelAnnotation = hasLabel ? "label" : "";
1915
+ const labelAnnotation = hasLabel ? "label" + (reverseSubjectLabelEntry.language ? " @" + reverseSubjectLabelEntry.language : "") : "";
1874
1916
  if (typeAnnotations || labelAnnotation) {
1875
1917
  inlineAnnotation = " " + [typeAnnotations, labelAnnotation].filter(Boolean).join(" ");
1876
1918
  compactStats.inlineAnnotations++;
@@ -1907,9 +1949,33 @@ function buildDeterministicMDLD(subjectGroups, context, primarySubject = null, r
1907
1949
  compactStats
1908
1950
  };
1909
1951
  }
1910
- function buildLabelLookup(subjectGroups) {
1952
+ function buildLabelLookup(subjectGroups, lang = null) {
1911
1953
  const labelLookup = /* @__PURE__ */ new Map();
1912
- for (const subjectQuads of subjectGroups.values()) for (const quad of subjectQuads) if (quad.predicate.value === "http://www.w3.org/2000/01/rdf-schema#label" && quad.object.termType === "Literal") labelLookup.set(quad.subject.value, quad.object.value);
1954
+ const labelsBySubject = /* @__PURE__ */ new Map();
1955
+ for (const subjectQuads of subjectGroups.values()) for (const quad of subjectQuads) if (quad.predicate.value === "http://www.w3.org/2000/01/rdf-schema#label" && quad.object.termType === "Literal") {
1956
+ const subjectIRI = quad.subject.value;
1957
+ if (!labelsBySubject.has(subjectIRI)) labelsBySubject.set(subjectIRI, []);
1958
+ labelsBySubject.get(subjectIRI).push(quad.object);
1959
+ }
1960
+ const selectBestLabel = (candidates) => {
1961
+ if (candidates.length === 0) return null;
1962
+ candidates.sort((a, b) => {
1963
+ const lenDiff = a.value.length - b.value.length;
1964
+ return lenDiff !== 0 ? lenDiff : a.value.localeCompare(b.value);
1965
+ });
1966
+ return candidates[0];
1967
+ };
1968
+ for (const [subjectIRI, labels] of labelsBySubject) {
1969
+ let selectedLabel = null;
1970
+ if (lang) selectedLabel = selectBestLabel(labels.filter((lit) => lit.language === lang));
1971
+ if (!selectedLabel) selectedLabel = selectBestLabel(labels.filter((lit) => !lit.language));
1972
+ if (!selectedLabel) selectedLabel = selectBestLabel(labels.filter((lit) => lit.language === "en"));
1973
+ if (!selectedLabel) selectedLabel = selectBestLabel(labels.filter((lit) => lit.language));
1974
+ if (selectedLabel) labelLookup.set(subjectIRI, {
1975
+ value: selectedLabel.value,
1976
+ language: selectedLabel.language || null
1977
+ });
1978
+ }
1913
1979
  return labelLookup;
1914
1980
  }
1915
1981
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mdld-parse",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800",