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.
- package/README.md +29 -4
- package/dist/index.js +84 -18
- 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
|
|
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
|
-
|
|
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
|
|
1841
|
-
const
|
|
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)))
|
|
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 ?
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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",
|