mdld-parse 0.9.8 → 1.0.0

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 (55) hide show
  1. package/README.md +243 -262
  2. package/dist/index.js +1797 -1324
  3. package/package.json +5 -5
  4. package/dist/.nojekyll +0 -0
  5. package/dist/CNAME +0 -1
  6. package/dist/README.md +0 -431
  7. package/dist/docs/API.md +0 -435
  8. package/dist/docs/Architecture.md +0 -190
  9. package/dist/docs/Guide.md +0 -816
  10. package/dist/docs/LLM-MDLD-Inducer.md +0 -550
  11. package/dist/docs/LiterateRDF.md +0 -472
  12. package/dist/docs/Parser.md +0 -720
  13. package/dist/docs/Performance.md +0 -238
  14. package/dist/docs/Spec-render.md +0 -1439
  15. package/dist/docs/Subject.md +0 -180
  16. package/dist/docs/Syntax.md +0 -463
  17. package/dist/docs/TodoList.md +0 -215
  18. package/dist/docs/Use-Cases.md +0 -354
  19. package/dist/docs/guide-m.md +0 -56
  20. package/dist/docs/index.html +0 -108
  21. package/dist/docs/index.md +0 -56
  22. package/dist/docs/one-page.md +0 -322
  23. package/dist/docs/origin.md +0 -459
  24. package/dist/docs/polarity.md +0 -586
  25. package/dist/docs/primary-subject.md +0 -326
  26. package/dist/docs/statements.md +0 -226
  27. package/dist/docs/tokenization-performance-report.md +0 -164
  28. package/dist/examples/Cookbook.md +0 -32
  29. package/dist/examples/Status-SHACL.md +0 -31
  30. package/dist/examples/demo/index.md +0 -35
  31. package/dist/examples/demo/journal.md +0 -60
  32. package/dist/examples/demo/minimal.md +0 -23
  33. package/dist/examples/demo/project.md +0 -84
  34. package/dist/examples/demo/prov.md +0 -107
  35. package/dist/examples/demo/rdf.md +0 -69
  36. package/dist/examples/demo/recipe.md +0 -50
  37. package/dist/examples/demo/research.md +0 -84
  38. package/dist/examples/demo/shacl.md +0 -161
  39. package/dist/examples/demo/space-mission.md +0 -58
  40. package/dist/examples/demo/tasks.md +0 -175
  41. package/dist/examples/demo/xsd.md +0 -91
  42. package/dist/examples/dogfood.md +0 -288
  43. package/dist/examples/few-shot.md +0 -309
  44. package/dist/examples/graph/rdf-graph.html +0 -473
  45. package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
  46. package/dist/examples/index.md +0 -45
  47. package/dist/examples/llm-time-workflow.md +0 -173
  48. package/dist/examples/statements.md +0 -43
  49. package/dist/examples/workflow.md +0 -150
  50. package/dist/index.html +0 -3023
  51. package/dist/logo.svg +0 -7
  52. package/dist/spec/Spec-compact.md +0 -368
  53. package/dist/spec/Spec-ultra.md +0 -232
  54. package/dist/spec/Spec.md +0 -1116
  55. package/dist/spec/index.md +0 -46
package/package.json CHANGED
@@ -1,20 +1,20 @@
1
1
  {
2
2
  "name": "mdld-parse",
3
- "version": "0.9.8",
3
+ "version": "1.0.0",
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",
7
- "main": "index.js",
7
+ "main": "./dist/index.js",
8
8
  "exports": {
9
9
  ".": "./dist/index.js"
10
10
  },
11
11
  "files": [
12
- "dist"
12
+ "dist/index.js"
13
13
  ],
14
14
  "scripts": {
15
15
  "test": "node tests/index.js",
16
16
  "dev": "vite dev",
17
- "build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
17
+ "build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r grammar/ dist/grammar/ && cp -r ontologies/ dist/ontologies/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
18
18
  },
19
19
  "keywords": [
20
20
  "mdld",
@@ -36,7 +36,7 @@
36
36
  "type": "git",
37
37
  "url": "git+https://github.com/davay42/mdld-parse.git"
38
38
  },
39
- "homepage": "https://mdld.js.org",
39
+ "homepage": "https://mdld.js.org/",
40
40
  "bugs": {
41
41
  "url": "https://github.com/davay42/mdld-parse/issues"
42
42
  },
package/dist/.nojekyll DELETED
File without changes
package/dist/CNAME DELETED
@@ -1 +0,0 @@
1
- mdld.js.org
package/dist/README.md DELETED
@@ -1,431 +0,0 @@
1
- # MD-LD
2
-
3
- **Markdown-Linked Data (MD-LD)** — a deterministic, streaming-friendly RDF authoring format that extends Markdown with explicit `{...}` annotations.
4
-
5
- [![NPM](https://img.shields.io/npm/v/mdld-parse)](https://www.npmjs.com/package/mdld-parse)
6
-
7
- [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
8
-
9
- ## 🚀 Quick Start
10
-
11
- ```bash
12
- pnpm install mdld-parse
13
- ```
14
-
15
- ```javascript
16
- import { parse } from 'mdld-parse';
17
-
18
- const result = parse(`
19
- [ex] <http://example.org/>
20
-
21
- # Document {=ex:doc .ex:Article label}
22
-
23
- [Alice] {?ex:author =ex:alice .prov:Person ex:firstName label}
24
- [Smith] {ex:lastName}`);
25
-
26
- console.log(result.quads);
27
- // RDF/JS quads ready for n3.js, rdflib, etc.
28
- // @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
29
- // @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
30
- // @prefix prov: <http://www.w3.org/ns/prov#>.
31
- // @prefix ex: <http://example.org/>.
32
-
33
- // ex:doc a ex:Article;
34
- // rdfs:label "Document";
35
- // ex:author ex:alice.
36
- // ex:alice a prov:Person;
37
- // rdfs:label "Alice";
38
- // ex:firstName "Alice";
39
- // ex:lastName "Smith".
40
- ```
41
-
42
- ## 📚 Documentation Hub
43
-
44
- - **📖 [Documentation](./docs/index.md)** - Complete documentation with guides and references
45
- - **🎯 [Examples](./examples/index.md)** - Real-world MD-LD examples and use cases
46
- - **📋 [Specification](./spec/index.md)** - Formal specification and test suite
47
-
48
- ## ✨ Core Features
49
-
50
- - **🔗 Prefix folding** - Build hierarchical namespaces with lightweight IRI authoring
51
- - **📍 Subject declarations** - `{=IRI}` and `{=#fragment}` for context setting
52
- - **🎯 Object IRIs** - `{+IRI}` and `{+#fragment}` for temporary object declarations
53
- - **🔄 Three predicate forms** - `p` (S→L), `?p` (S→O), `!p` (O→S)
54
- - **🏷️ Type declarations** - `.Class` for rdf:type triples
55
- - **📅 Datatypes & language** - `^^xsd:date` and `@en` support
56
- - **🧩 Fragments** - Document structuring with `{=#fragment}`
57
- - **⚡ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
58
- - **📍 Origin tracking** - Complete provenance with lean quad-to-source mapping
59
- - **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
60
- - **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
61
-
62
- ## 🌟 What is MD-LD?
63
-
64
- MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
65
-
66
- ```markdown
67
- [my] <tag:alice@example.com,2026:>
68
- # 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
69
- ## A good day {label}
70
- Mood: [Happy] {my:mood}
71
- Energy level: [8] {my:energyLevel ^^xsd:integer}
72
- Met [Sam] {+my:sam .my:Person ?my:attendee} on my regular walk at [Central Park] {+my:central-park ?my:location .my:Place label @en} and talked about [Sunny] {my:weather} weather.
73
- ```
74
-
75
- Generates valid RDF triples with complete provenance tracking.
76
-
77
- ## 📦 Installation
78
-
79
- ### Node.js
80
-
81
- ```bash
82
- pnpm install mdld-parse
83
- ```
84
-
85
- ```javascript
86
- import { parse } from 'mdld-parse';
87
-
88
- const markdown = `[ex] <tag:alice@example.org,2026:>
89
-
90
- # Demo document {=ex:example/doc .prov:Entity label}
91
-
92
- > A demo document for MD-LD {comment}
93
- [Alice] {+ex:alice ?ex:author .prov:Person label}
94
- `;
95
-
96
- const result = parse({ text: markdown });
97
-
98
- console.log(result.quads);
99
- // RDF/JS quads ready for n3.js, rdflib, etc.
100
- ```
101
-
102
- ### Browser (ES Modules)
103
-
104
- ```html
105
- <script type="module">
106
- import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
107
-
108
- const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
109
- </script>
110
- ```
111
-
112
- ## 🧠 Semantic Model
113
-
114
- MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
115
-
116
- - **S** — current subject (IRI)
117
- - **O** — object resource (IRI from link/image)
118
- - **L** — literal value (string + optional datatype/language)
119
-
120
- ### Predicate Routing (§8.1)
121
-
122
- Each predicate form determines the graph edge:
123
-
124
- | Form | Edge | Example | Meaning |
125
- |-------|---------|------------------------------|------------------|
126
- | `p` | S → L | `[Alice] {label}` | literal property |
127
- | `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
128
- | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
129
-
130
- ## 📍 Elevated Statements
131
-
132
- MD-LD automatically detects `rdf:Statement` patterns during parsing and extracts elevated SPO quads for convenient consumption by applications.
133
-
134
- ### Pattern Detection
135
-
136
- When the parser encounters a complete `rdf:Statement` pattern with `rdf:subject`, `rdf:predicate`, and `rdf:object`, it automatically adds the corresponding SPO quad to the `statements` array:
137
-
138
- ```markdown
139
- [ex] <http://example.org/>
140
-
141
- ## Elevated statement {=ex:stmt1 .rdf:Statement}
142
- **Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
143
-
144
- Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
145
- ```
146
-
147
- ## 🎨 Syntax Quick Reference
148
-
149
- ### Subject Declaration
150
- Set current subject (emits no quads):
151
- ```markdown
152
- ## Apollo 11 {=ex:apollo11}
153
- ```
154
-
155
- ### Fragment Syntax
156
- Create fragment IRIs relative to current subject:
157
- ```markdown
158
- # Document {=ex:document}
159
- {=#summary}
160
- [Content] {label}
161
- ```
162
- Fragments replace any existing fragment and require a current subject.
163
-
164
- ### Type Declaration
165
- Emit `rdf:type` triple:
166
- ```markdown
167
- ## Apollo 11 {=ex:apollo11 .ex:SpaceMission .ex:Event}
168
- ```
169
-
170
- ### Literal Properties
171
- Inline value carriers emit literal properties:
172
- ```markdown
173
- # Mission {=ex:apollo11}
174
- [Neil Armstrong] {ex:commander}
175
- [1969] {ex:year ^^xsd:gYear}
176
- [Historic mission] {ex:description @en}
177
- ```
178
-
179
- ### Object Properties
180
- Links create relationships (use `?` prefix):
181
- ```markdown
182
- # Mission {=ex:apollo11}
183
- [NASA] {=ex:nasa ?ex:organizer}
184
- ```
185
-
186
- ### Resource Declaration
187
- Declare resources inline with `{=iri}`:
188
- ```markdown
189
- # Mission {=ex:apollo11}
190
- [Neil Armstrong] {=ex:armstrong ?ex:commander .prov:Person}
191
- ```
192
-
193
- ## 🔧 API Reference
194
-
195
- ### `parse({ text, context, dataFactory, graph })`
196
-
197
- Parse MD-LD markdown and return RDF quads with lean origin tracking.
198
-
199
- **Parameters (named object):**
200
- - `text` (string, required) — MD-LD formatted text
201
- - `context` (object, optional) — Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
202
- - `dataFactory` (object, optional) — Custom RDF/JS DataFactory
203
- - `graph` (string, optional) — Named graph IRI
204
-
205
- **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
206
-
207
- - `quads` — Array of RDF/JS Quads (final resolved graph state)
208
- - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
209
- - `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
210
- - `origin` — Lean origin tracking object with quadIndex for UI navigation
211
- - `context` — Final context used (includes prefixes)
212
- - `primarySubject` — String IRI or null (canonical append identity)
213
- - `primary` — Object containing primary metadata (semantic surface descriptor)
214
- - `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
215
-
216
- **Dual-Layer Architecture:**
217
-
218
- | Layer | Field | Purpose | Use Cases |
219
- |-------|-------|---------|-----------|
220
- | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
221
- | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
222
-
223
- **Primary Object Structure:**
224
- ```javascript
225
- primary: {
226
- subject: string | null, // First non-fragment subject declaration
227
- type: string | null, // First rdf:type declaration
228
- label: string | null // First rdfs:label literal
229
- }
230
- ```
231
-
232
- ### `merge(docs, options)`
233
-
234
- Merge multiple MDLD documents with diff polarity resolution.
235
-
236
- **Parameters:**
237
- - `docs` (array) — Array of markdown strings or ParseResult objects
238
- - `options` (object, optional):
239
- - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
240
-
241
- **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
242
-
243
- - `quads` — Array of RDF/JS Quads (final resolved graph state)
244
- - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
245
- - `origin` — Merge origin with document tracking
246
- - `context` — Final context used (includes prefixes)
247
- - `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
248
- - `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
249
-
250
- **Dual-Layer Architecture:**
251
-
252
- | Layer | Field | Purpose | Use Cases |
253
- |-------|-------|---------|-----------|
254
- | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
255
- | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
256
-
257
- **Primary Object Array Structure:**
258
- ```javascript
259
- primary: [
260
- {
261
- subject: string | null, // First non-fragment subject declaration
262
- type: string | null, // First rdf:type declaration
263
- label: string | null // First rdfs:label literal
264
- },
265
- // ... one object per document
266
- ]
267
- ```
268
-
269
-
270
- ### `generate({ quads, context, primarySubject })`
271
-
272
- Generate deterministic MDLD from RDF quads with visual styling.
273
-
274
- **Parameters (named object):**
275
- - `quads` (array, required) — Array of RDF/JS Quads to convert
276
- - `context` (object, optional) — Prefix mappings (default: `{}`)
277
- - `primarySubject` (string, optional) — String IRI to place first in output (ensures round-trip safety). If not provided, falls back to the first subject from quads.
278
-
279
- **Returns:** `{ text, context }`
280
-
281
- **Features:**
282
- - Visual carrier styles based on datatype (code spans for numbers, bold booleans, etc.)
283
- - Label-in-heading: Uses `rdfs:label` in subject headings when available
284
- - Multiple labels: First label in heading, additional labels rendered as literals
285
- - Round-trip safe: All data preserved through parse → generate → parse
286
- - Composable: `generate(parse(text))` extracts semantics; `parse(generate({quads}))` normalizes quads
287
-
288
- ### `generateNode({ quads, focusIRI, context })`
289
-
290
- Generate node-centric MDLD showing all quads where a specific IRI appears in any position.
291
-
292
- **Parameters (named object):**
293
- - `quads` (array, required) — Array of RDF/JS Quads to search
294
- - `focusIRI` (string, required) — The IRI to center the view on
295
- - `context` (object, optional) — Prefix mappings (default: `{}`)
296
-
297
- **Returns:** `{ text, context }`
298
-
299
- **Behavior (Safety-First):**
300
- - If `focusIRI` is null/undefined: Returns empty text
301
- - If `focusIRI` not in graph: Returns empty text (never falls back to all data)
302
- - If `quads` is empty: Returns empty text
303
-
304
- **Safety rationale:** Prevents accidental rendering of entire databases on misspelled IRIs—critical for production use with LLM cost per token. Explicit emptiness signals "not found" to the caller.
305
-
306
- **Use case:** Perfect for exploring a specific node and all its relationships—where it appears as subject, object, predicate, type, or datatype. Creates an exhaustive view of everything related to the focus IRI. Ideal for node-centric knowledge graph explorers.
307
-
308
- ### Composition Patterns
309
-
310
- With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
311
-
312
- ```javascript
313
- import { parse, generate, generateNode } from 'mdld-parse';
314
-
315
- // Pattern 1: parse → generate (semantic extraction)
316
- const canonical = generate({ ...parse({ text, context }) });
317
- // text → quads → canonical MDLD (deterministic, visual styling applied)
318
-
319
- // Pattern 2: generate → parse (normalize external RDF)
320
- const normalized = parse({ ...generate({ quads: externalQuads, context }) });
321
- // external quads → MDLD → validated quads (DataFactory-safe, no blank nodes)
322
-
323
- // Pattern 3: parse → generateNode (node-centric exploration)
324
- const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
325
- // full graph → isolated node view (safe: returns empty if IRI not found)
326
- ```
327
-
328
- **Why this works:**
329
- - `parse()` returns `{ quads, context, primarySubject, md, ... }`
330
- - `generate()` accepts `{ quads, context, primarySubject }`
331
- - `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
332
- - Perfect shape alignment enables elegant `{ ...spread }` composition
333
-
334
- ### The `md` Field — Clean Markdown Extraction
335
-
336
- Every `parse()` result includes a `md` field containing the original Markdown with all MD-LD annotations stripped:
337
-
338
- ```javascript
339
- const result = parse({
340
- text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
341
- context: { ex: 'http://example.org/' }
342
- });
343
-
344
- console.log(result.md);
345
- // # Document\nContent
346
-
347
- // Round-trip safety: re-parsing clean MD produces zero quads
348
- const reparsed = parse({ text: result.md });
349
- console.log(reparsed.quads.length); // 0
350
- ```
351
-
352
- **Behavior:**
353
- - Valid MD-LD annotations (`{=...}`, `{+...}`, `{...}`) are completely removed
354
- - Content from value carriers (`[text]`, `**bold**`, `` `code` ``) is preserved
355
- - Invalid syntax (annotations not at end-of-line) is preserved as visible markers
356
- - Headings, lists, blockquotes, code blocks maintain their structure
357
- - Prefix declarations at start of line are stripped
358
- - Standalone subject declarations (`{=ex:subject}`) are stripped
359
-
360
- **Use cases:**
361
- - **Content extraction** — Get readable Markdown without semantic markup
362
- - **Syntax validation** — Remaining `{...}` patterns indicate invalid MD-LD syntax
363
- - **Round-trip testing** — `parse(md).md` should parse to zero quads
364
- - **Preview generation** — Show clean document before publishing
365
-
366
- ### `locate(quad, origin)`
367
-
368
- Locate the origin entry for a quad using the lean origin system.
369
-
370
- **Parameters:**
371
- - `quad` (object) — The quad to locate (subject, predicate, object)
372
- - `origin` (object) — Origin object containing quadIndex
373
-
374
- **Returns:** `{ blockId, range, carrierType, subject, predicate, context, value, polarity }` or `null`
375
-
376
- ### `render(quads, options)`
377
-
378
- Render RDF quads as HTML+RDFa for web display.
379
-
380
- **Parameters:**
381
- - `quads` (array) — Array of RDF/JS Quads to render
382
- - `options` (object, optional):
383
- - `context` (object) — Prefix mappings for CURIE shortening
384
- - `baseIRI` (string) — Base IRI for resolving relative references
385
-
386
- **Returns:** `{ html, context }`
387
-
388
- ### Utility Functions
389
-
390
- ```javascript
391
- import {
392
- DEFAULT_CONTEXT, // Default prefix mappings
393
- DataFactory, // RDF/JS DataFactory instance
394
- hash, // String hashing function
395
- expandIRI, // IRI expansion with context
396
- shortenIRI, // IRI shortening with context
397
- parseSemanticBlock // Parse semantic block syntax
398
- } from 'mdld-parse';
399
- ```
400
-
401
- ## 🏗️ Architecture
402
-
403
- ### Design Principles
404
- - **Zero dependencies** — Pure JavaScript, ~15KB minified
405
- - **Streaming-first** — Single-pass parsing, O(n) complexity
406
- - **Standards-compliant** — RDF/JS data model
407
- - **Origin tracking** — Full round-trip support with source maps
408
- - **Explicit semantics** — No guessing, inference, or heuristics
409
-
410
- ### RDF/JS Compatibility
411
- Quads are compatible with:
412
- - [`n3.js`](https://github.com/rdfjs/N3.js) — Turtle/N-Triples serialization
413
- - [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF store and reasoning
414
- - [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) — SPARQL queries
415
- - [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — Extended RDF utilities
416
-
417
- ## 🧪 Testing
418
-
419
- The parser includes comprehensive tests covering all spec requirements:
420
-
421
- ```bash
422
- pnpm test
423
- ```
424
-
425
- Tests validate:
426
- - Subject declaration and context
427
- - All predicate forms (p, ?p, !p)
428
- - Datatypes and language tags
429
- - Explicit list item annotations
430
- - Code blocks and blockquotes
431
- - Round-trip serialization