mdld-parse 0.9.2 → 0.9.4

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 (64) hide show
  1. package/dist/.nojekyll +0 -0
  2. package/dist/CNAME +1 -0
  3. package/dist/README.md +425 -0
  4. package/dist/docs/API.md +397 -0
  5. package/dist/docs/Architecture.md +190 -0
  6. package/dist/docs/Guide.md +816 -0
  7. package/dist/docs/LLM-MDLD-Inducer.md +550 -0
  8. package/dist/docs/Parser.md +654 -0
  9. package/dist/docs/Performance.md +238 -0
  10. package/dist/docs/Spec-render.md +1439 -0
  11. package/dist/docs/Subject.md +180 -0
  12. package/dist/docs/Syntax.md +463 -0
  13. package/dist/docs/TodoList.md +215 -0
  14. package/dist/docs/Use-Cases.md +354 -0
  15. package/dist/docs/guide-m.md +56 -0
  16. package/dist/docs/index.html +108 -0
  17. package/dist/docs/index.md +56 -0
  18. package/dist/docs/one-page.md +322 -0
  19. package/dist/docs/origin.md +459 -0
  20. package/dist/docs/polarity.md +586 -0
  21. package/dist/docs/primary-subject.md +199 -0
  22. package/dist/docs/statements.md +226 -0
  23. package/dist/docs/tokenization-performance-report.md +164 -0
  24. package/dist/examples/Cookbook.md +32 -0
  25. package/dist/examples/Status-SHACL.md +31 -0
  26. package/dist/examples/demo/index.md +35 -0
  27. package/dist/examples/demo/journal.md +119 -0
  28. package/dist/examples/demo/minimal.md +23 -0
  29. package/dist/examples/demo/project.md +98 -0
  30. package/dist/examples/demo/prov.md +107 -0
  31. package/dist/examples/demo/rdf.md +69 -0
  32. package/dist/examples/demo/recipe.md +95 -0
  33. package/dist/examples/demo/research.md +126 -0
  34. package/dist/examples/demo/shacl.md +161 -0
  35. package/dist/examples/demo/space-mission.md +129 -0
  36. package/dist/examples/demo/tasks.md +175 -0
  37. package/dist/examples/demo/xsd.md +91 -0
  38. package/dist/examples/dogfood.md +288 -0
  39. package/dist/examples/few-shot.md +309 -0
  40. package/dist/examples/graph/rdf-graph.html +473 -0
  41. package/dist/examples/graph/rdf_force_graph_web_component.html +506 -0
  42. package/dist/examples/index.md +45 -0
  43. package/dist/examples/llm-time-workflow.md +173 -0
  44. package/dist/examples/statements.md +43 -0
  45. package/dist/examples/workflow.md +150 -0
  46. package/dist/index.html +3253 -0
  47. package/dist/index.js +1770 -0
  48. package/dist/logo.svg +7 -0
  49. package/dist/spec/Spec-compact.md +363 -0
  50. package/dist/spec/Spec-ultra.md +221 -0
  51. package/dist/spec/Spec.md +1068 -0
  52. package/dist/spec/index.md +46 -0
  53. package/package.json +7 -8
  54. package/src/constants.js +0 -31
  55. package/src/generate.js +0 -245
  56. package/src/highlight.js +0 -362
  57. package/src/index.js +0 -13
  58. package/src/locate.js +0 -23
  59. package/src/merge.js +0 -157
  60. package/src/parse.js +0 -711
  61. package/src/render.js +0 -576
  62. package/src/shared.js +0 -577
  63. package/src/tokenizers.js +0 -594
  64. package/src/utils.js +0 -430
@@ -0,0 +1,459 @@
1
+ # Origin System - Lean Quad Tracking
2
+
3
+ The MDLD parser includes a sophisticated **origin tracking system** that provides complete provenance for every RDF quad generated from markdown. This system enables powerful use cases like UI navigation, debugging, and audit trails.
4
+
5
+ ## Overview
6
+
7
+ The origin system is a **lean, read-only source map** that connects each RDF quad back to its exact location in the original markdown text. Unlike complex mutable systems, the lean origin focuses on three core use cases:
8
+
9
+ 1. **UI Navigation** - Click-to-jump functionality in editors
10
+ 2. **Provenance Audit** - Complete relationship tracking for knowledge graphs
11
+ 3. **Parser Error Reporting** - Precise error location reporting
12
+
13
+ ## Architecture
14
+
15
+ ### Lean Origin Structure
16
+
17
+ ```javascript
18
+ {
19
+ quadIndex: Map<string, OriginEntry>
20
+ }
21
+ ```
22
+
23
+ Each `OriginEntry` contains:
24
+
25
+ ```javascript
26
+ {
27
+ blockId: string, // Unique identifier for the containing block
28
+ range: { start: number, end: number }, // Character range in source text
29
+ carrierType: string, // 'heading', 'blockquote', 'span'
30
+ subject: string, // Subject IRI of the quad
31
+ predicate: string, // Predicate IRI of the quad
32
+ context: object, // Context object inherited from parsing
33
+ value: string, // Raw carrier text content
34
+ polarity: '+' | '-' // Assertion (+) or retraction (-)
35
+ }
36
+ ```
37
+
38
+ ### Key Benefits
39
+
40
+ #### 🎯 Complete Audit Trails
41
+ Track full subject-predicate-object relationships with precise source locations:
42
+
43
+ ```javascript
44
+ const location = locate(quad, origin);
45
+ console.log(location);
46
+ // {
47
+ // blockId: '4ac750c12',
48
+ // range: { start: 33, end: 53 },
49
+ // carrierType: 'blockquote',
50
+ // subject: 'http://example.org/alice',
51
+ // predicate: 'http://www.w3.org/2000/01/rdf-schema#name',
52
+ // context: { ex: 'http://example.org/' },
53
+ // value: 'Alice Smith',
54
+ // polarity: '+'
55
+ // }
56
+ ```
57
+
58
+ #### 🔍 Better Debugging
59
+ Full quad information available for debugging and validation:
60
+
61
+ ```javascript
62
+ // Find all quads from a specific block
63
+ const blockQuads = Array.from(origin.quadIndex.entries())
64
+ .filter(([key, entry]) => entry.blockId === '4ac750c12')
65
+ .map(([key, entry]) => ({ key, entry }));
66
+
67
+ // Debug specific predicate usage
68
+ const nameQuads = Array.from(origin.quadIndex.entries())
69
+ .filter(([key, entry]) => entry.predicate.includes('name'));
70
+ ```
71
+
72
+ #### 📊 Enhanced Provenance
73
+ Complete relationship tracking for knowledge graphs:
74
+
75
+ ```javascript
76
+ // Build provenance chain
77
+ function buildProvenanceChain(quads, origin) {
78
+ return quads.map(quad => {
79
+ const location = locate(quad, origin);
80
+ return {
81
+ quad,
82
+ source: {
83
+ text: location.value,
84
+ range: location.range,
85
+ blockId: location.blockId
86
+ },
87
+ relationship: {
88
+ subject: location.subject,
89
+ predicate: location.predicate,
90
+ polarity: location.polarity
91
+ }
92
+ };
93
+ });
94
+ }
95
+ ```
96
+
97
+ ## API Reference
98
+
99
+ ### `locate(quad, origin)`
100
+
101
+ Locate the origin entry for a quad using the lean origin system.
102
+
103
+ **Parameters:**
104
+ - `quad` (object) — The quad to locate (subject, predicate, object)
105
+ - `origin` (object) — Origin object containing quadIndex
106
+
107
+ **Returns:** Origin entry or `null`
108
+
109
+ **Example:**
110
+ ```javascript
111
+ import { parse, locate } from 'mdld-parse';
112
+
113
+ const result = parse({ text: mdldText, context: { ex: 'http://example.org/' } });
114
+ const quad = result.quads[0];
115
+
116
+ const location = locate(quad, result.origin);
117
+
118
+ if (location) {
119
+ console.log(`Found "${location.value}" at ${location.range.start}-${location.range.end}`);
120
+ console.log(`Subject: ${location.subject}`);
121
+ console.log(`Predicate: ${location.predicate}`);
122
+ console.log(`Carrier: ${location.carrierType}`);
123
+ }
124
+ ```
125
+
126
+ ## Use Cases
127
+
128
+ ### 1. UI Navigation
129
+
130
+ Create click-to-jump functionality in MDLD editors:
131
+
132
+ ```javascript
133
+ // Handle quad click in UI
134
+ function onQuadClick(quad, origin, editor) {
135
+ const location = locate(quad, origin);
136
+ if (location) {
137
+ // Jump to source location
138
+ editor.setSelection(location.range.start, location.range.end);
139
+ editor.focus();
140
+
141
+ // Highlight the block
142
+ editor.highlightBlock(location.blockId);
143
+ }
144
+ }
145
+
146
+ // Hover preview
147
+ function onQuadHover(quad, origin) {
148
+ const location = locate(quad, origin);
149
+ if (location) {
150
+ showTooltip({
151
+ text: location.value,
152
+ range: location.range,
153
+ predicate: location.predicate
154
+ });
155
+ }
156
+ }
157
+ ```
158
+
159
+ ### 2. Provenance Audit
160
+
161
+ Build complete audit trails for knowledge graphs:
162
+
163
+ ```javascript
164
+ function buildAuditReport(quads, origin) {
165
+ const report = {
166
+ totalQuads: quads.length,
167
+ blocks: new Map(),
168
+ predicates: new Map(),
169
+ polarities: { '+': 0, '-': 0 }
170
+ };
171
+
172
+ quads.forEach(quad => {
173
+ const location = locate(quad, origin);
174
+ if (!location) return;
175
+
176
+ // Track block usage
177
+ if (!report.blocks.has(location.blockId)) {
178
+ report.blocks.set(location.blockId, {
179
+ carrierType: location.carrierType,
180
+ quads: []
181
+ });
182
+ }
183
+ report.blocks.get(location.blockId).quads.push(quad);
184
+
185
+ // Track predicate usage
186
+ const predCount = report.predicates.get(location.predicate) || 0;
187
+ report.predicates.set(location.predicate, predCount + 1);
188
+
189
+ // Track polarity
190
+ report.polarities[location.polarity]++;
191
+ });
192
+
193
+ return report;
194
+ }
195
+ ```
196
+
197
+ ### 3. Error Reporting
198
+
199
+ Provide precise error location information:
200
+
201
+ ```javascript
202
+ function validateQuad(quad, origin, rules) {
203
+ const location = locate(quad, origin);
204
+ const errors = [];
205
+
206
+ rules.forEach(rule => {
207
+ if (!rule.validate(quad)) {
208
+ errors.push({
209
+ message: rule.message,
210
+ quad,
211
+ location: {
212
+ text: location.value,
213
+ range: location.range,
214
+ blockId: location.blockId,
215
+ line: getLineNumber(location.range.start, sourceText)
216
+ }
217
+ });
218
+ }
219
+ });
220
+
221
+ return errors;
222
+ }
223
+ ```
224
+
225
+ ### 4. Multi-Document Merging
226
+
227
+ Track provenance across merged documents:
228
+
229
+ ```javascript
230
+ import { merge } from 'mdld-parse';
231
+
232
+ const merged = merge([doc1, doc2, doc3]);
233
+
234
+ // Build document provenance
235
+ function buildDocumentProvenance(merged) {
236
+ const provenance = new Map();
237
+
238
+ merged.origin.documents.forEach((doc, index) => {
239
+ doc.quads.forEach(quad => {
240
+ const location = locate(quad, merged.origin);
241
+ if (location) {
242
+ provenance.set(quadKey(quad), {
243
+ documentIndex: index,
244
+ originalLocation: location,
245
+ mergedLocation: location
246
+ });
247
+ }
248
+ });
249
+ });
250
+
251
+ return provenance;
252
+ }
253
+ ```
254
+
255
+ ## Performance Considerations
256
+
257
+ The lean origin system is optimized for performance:
258
+
259
+ - **Memory Efficient**: Uses Map data structure for O(1) lookups
260
+ - **Streaming Friendly**: Built during single-pass parsing
261
+ - **Immutable**: Origin entries never change after creation
262
+ - **Minimal Overhead**: Only stores essential information
263
+
264
+ ```javascript
265
+ // Performance characteristics
266
+ const origin = parse({text: largeMarkdown}).origin;
267
+
268
+ // O(1) lookup by quad
269
+ const location = locate(quad, origin);
270
+
271
+ // O(n) iteration over all entries
272
+ for (const [key, entry] of origin.quadIndex) {
273
+ // Process entry
274
+ }
275
+
276
+ // Memory usage scales linearly with quad count
277
+ // ~200 bytes per quad entry
278
+ ```
279
+
280
+ ## Migration from Legacy Origin
281
+
282
+ If you were using the pre-v0.7.0 origin system, here's how to migrate:
283
+
284
+ ### Old System (pre-v0.7.0)
285
+ ```javascript
286
+ // Complex mutable origin with slot management
287
+ {
288
+ blocks: Map<string, Block>,
289
+ quadMap: Map<string, QuadSlot>,
290
+ entries: Array<OriginEntry>
291
+ }
292
+
293
+ // Complex locate with auto-parsing
294
+ locate(quad, origin, text, context)
295
+ ```
296
+
297
+ ### New Lean System (v0.7.0+)
298
+ ```javascript
299
+ // Simple immutable origin
300
+ {
301
+ quadIndex: Map<string, OriginEntry>
302
+ }
303
+
304
+ // Simple locate
305
+ locate(quad, origin)
306
+ ```
307
+
308
+ ### Migration Steps
309
+
310
+ 1. **Update locate calls**:
311
+ ```javascript
312
+ // Old
313
+ const location = locate(quad, origin, text, context);
314
+
315
+ // New
316
+ const location = locate(quad, origin);
317
+ ```
318
+
319
+ 2. **Update origin access**:
320
+ ```javascript
321
+ // Old
322
+ const block = origin.blocks.get(blockId);
323
+ const slot = origin.quadMap.get(quadKey);
324
+
325
+ // New
326
+ const entry = origin.quadIndex.get(quadKey);
327
+ ```
328
+
329
+ 3. **Remove applyDiff usage**:
330
+ ```javascript
331
+ // Old - no longer available
332
+ const updated = applyDiff({ text, diff, origin });
333
+
334
+ // New - use merge for document updates
335
+ const updated = merge([original, diffText]);
336
+ ```
337
+
338
+ ## Best Practices
339
+
340
+ ### 1. Cache Location Lookups
341
+ ```javascript
342
+ // Cache frequently accessed locations
343
+ const locationCache = new Map();
344
+
345
+ function getCachedLocation(quad, origin) {
346
+ const key = quadKey(quad);
347
+ if (!locationCache.has(key)) {
348
+ locationCache.set(key, locate(quad, origin));
349
+ }
350
+ return locationCache.get(key);
351
+ }
352
+ ```
353
+
354
+ ### 2. Batch Processing
355
+ ```javascript
356
+ // Process multiple quads efficiently
357
+ function processQuads(quads, origin, processor) {
358
+ return quads.map(quad => {
359
+ const location = locate(quad, origin);
360
+ return processor(quad, location);
361
+ });
362
+ }
363
+ ```
364
+
365
+ ### 3. Error Handling
366
+ ```javascript
367
+ // Always handle null returns
368
+ function safeLocate(quad, origin) {
369
+ const location = locate(quad, origin);
370
+ if (!location) {
371
+ console.warn('Quad not found in origin:', quad);
372
+ return null;
373
+ }
374
+ return location;
375
+ }
376
+ ```
377
+
378
+ ### 4. Memory Management
379
+ ```javascript
380
+ // Clear caches when no longer needed
381
+ function cleanup() {
382
+ locationCache.clear();
383
+ // Allow garbage collection
384
+ }
385
+ ```
386
+
387
+ ## Examples
388
+
389
+ ### Complete UI Integration
390
+ ```javascript
391
+ class MDLDEditor {
392
+ constructor() {
393
+ this.origin = null;
394
+ this.quads = [];
395
+ }
396
+
397
+ async parse(text) {
398
+ const result = parse({ text, context: this.context });
399
+ this.origin = result.origin;
400
+ this.quads = result.quads;
401
+ this.render();
402
+ }
403
+
404
+ onQuadClick(quad) {
405
+ const location = locate(quad, this.origin);
406
+ if (location) {
407
+ this.editor.setSelection(location.range.start, location.range.end);
408
+ this.showQuadInfo(quad, location);
409
+ }
410
+ }
411
+
412
+ showQuadInfo(quad, location) {
413
+ const info = `
414
+ <div class="quad-info">
415
+ <h4>Quad Information</h4>
416
+ <p><strong>Subject:</strong> ${location.subject}</p>
417
+ <p><strong>Predicate:</strong> ${location.predicate}</p>
418
+ <p><strong>Value:</strong> ${location.value}</p>
419
+ <p><strong>Type:</strong> ${location.carrierType}</p>
420
+ <p><strong>Range:</strong> ${location.range.start}-${location.range.end}</p>
421
+ <p><strong>Polarity:</strong> ${location.polarity}</p>
422
+ </div>
423
+ `;
424
+ this.sidebar.innerHTML = info;
425
+ }
426
+ }
427
+ ```
428
+
429
+ ### Audit Trail Generator
430
+ ```javascript
431
+ function generateAuditTrail(quads, origin) {
432
+ const trail = {
433
+ timestamp: new Date().toISOString(),
434
+ totalQuads: quads.length,
435
+ entries: []
436
+ };
437
+
438
+ quads.forEach((quad, index) => {
439
+ const location = locate(quad, origin);
440
+ if (location) {
441
+ trail.entries.push({
442
+ index,
443
+ subject: location.subject,
444
+ predicate: location.predicate,
445
+ object: quad.object.value,
446
+ sourceText: location.value,
447
+ sourceRange: location.range,
448
+ blockId: location.blockId,
449
+ carrierType: location.carrierType,
450
+ polarity: location.polarity
451
+ });
452
+ }
453
+ });
454
+
455
+ return trail;
456
+ }
457
+ ```
458
+
459
+ The lean origin system provides a powerful, efficient foundation for building sophisticated MDLD applications with complete provenance tracking.