mdld-parse 0.1.0

package/README.md

@@ -0,0 +1,374 @@
+# MD-LD Parser
+
+A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.
+
+## What is MD-LD?
+
+MD-LD allows you to author RDF graphs directly in Markdown using familiar syntax:
+
+```markdown
+---
+"@context":
+  "@vocab": "http://schema.org/"
+"@id": "#doc"
+"@type": Article
+---
+
+# My Article {#article typeof="Article"}
+
+Written by [Alice Johnson](#alice){property="author" typeof="Person"}
+
+[Alice](#alice) works at [Tech Corp](#company){rel="worksFor" typeof="Organization"}
+```
+
+This generates valid RDF triples while remaining readable as plain Markdown.
+
+## Architecture
+
+### Design Principles
+
+1. **Streaming First** — Process documents incrementally without loading entire AST into memory
+2. **Zero Dependencies** — Pure JavaScript, runs in Node.js and browsers
+3. **Standards Compliant** — Outputs RDF quads compatible with RDFa semantics
+4. **Markdown Native** — Plain Markdown yields minimal but valid RDF
+5. **Progressive Enhancement** — Add semantics incrementally via attributes
+
+### Stack Choices
+
+#### Parser: Custom Zero-Dependency Tokenizer
+
+We implement a **minimal, purpose-built parser** for maximum control and zero dependencies:
+
+- **Custom Markdown tokenizer** — Line-by-line parsing of headings, lists, paragraphs, code blocks
+- **Inline attribute parser** — Pandoc-style `{#id .class key="value"}` attribute extraction
+- **YAML-LD frontmatter parser** — Minimal YAML subset for `@context` and `@id` parsing
+- **RDF quad generator** — Direct mapping from tokens to RDF/JS quads
+
+**Why custom?**
+
+- **Zero dependencies** — Runs anywhere JavaScript runs
+- **Lightweight** — ~15KB minified, no AST overhead
+- **Focused** — Optimized specifically for MD-LD semantics
+- **Transparent** — Easy to understand and extend
+- **Fast** — Single-pass parsing with minimal allocations
+
+#### RDF Output: RDF/JS Data Model
+
+We implement the [RDF/JS specification](https://rdf.js.org/data-model-spec/):
+
+```javascript
+{
+  termType: 'NamedNode' | 'BlankNode' | 'Literal',
+  value: string,
+  language?: string,
+  datatype?: NamedNode
+}
+```
+
+This ensures compatibility with:
+
+- `n3.js` — Turtle/N-Triples serialization
+- `rdflib.js` — RDF store and reasoning
+- `sparqljs` — SPARQL query parsing
+- `rdf-ext` — Extended RDF utilities
+
+### Processing Pipeline
+
+```
+Markdown Text
+    ↓
+[Custom Tokenizer] — Extract headings, lists, paragraphs, code blocks
+    ↓
+[YAML-LD Parser] — Extract frontmatter @context and @id
+    ↓
+[Attribute Parser] — Parse {#id property="value"} from tokens
+    ↓
+[Inline Parser] — Extract [text](url){attrs} spans
+    ↓
+[RDF Quad Generator] — Map tokens to RDF/JS quads
+    ↓
+RDF Quads (RDF/JS format)
+    ↓
+[Optional] n3.js Writer → Turtle/N-Triples
+```
+
+### Architecture Benefits
+
+The zero-dependency design provides:
+
+1. **Single-pass parsing** — Process document once, emit quads immediately
+2. **Minimal memory** — No AST construction, only token stream
+3. **Predictable performance** — Linear time complexity, bounded memory
+4. **Easy integration** — Works in Node.js, browsers, and edge runtimes
+
+### Performance Profile
+
+| Document Size | Peak Memory | Parse Time |
+| ------------- | ----------- | ---------- |
+| 10 KB         | ~100 KB     | <2ms       |
+| 100 KB        | ~500 KB     | <20ms      |
+| 1 MB          | ~2 MB       | <100ms     |
+| 10 MB         | ~10 MB      | <1s        |
+
+_Measured on modern JavaScript engines. Actual performance depends on document structure._
+
+## Installation
+
+### Node.js
+
+```bash
+npm install mdld-parse
+```
+
+```javascript
+import { parseMDLD } from "mdld-parse";
+
+const markdown = `# Hello\n{#doc typeof="Article"}`;
+const quads = parseMDLD(markdown, {
+	baseIRI: "http://example.org/doc",
+});
+```
+
+### Browser (via CDN)
+
+```html
+<script type="importmap">
+	{
+		"imports": {
+			"mdld-parse": "https://cdn.jsdelivr.net/npm/mdld-parse/+esm"
+		}
+	}
+</script>
+
+<script type="module">
+	import { parseMDLD } from "mdld-parse";
+	// use parseMDLD...
+</script>
+```
+
+## API
+
+### `parseMDLD(markdown, options)`
+
+Parse MD-LD markdown and return RDF quads.
+
+**Parameters:**
+
+- `markdown` (string) — MD-LD formatted text
+- `options` (object, optional):
+  - `baseIRI` (string) — Base IRI for relative references (default: `''`)
+  - `defaultVocab` (string) — Default vocabulary (default: `'http://schema.org/'`)
+  - `dataFactory` (object) — Custom RDF/JS DataFactory (default: built-in)
+
+**Returns:** Array of RDF/JS Quads
+
+```javascript
+const quads = parseMDLD(
+	`
+# Article Title
+{#article typeof="Article"}
+
+Written by [Alice](#alice){property="author"}
+`,
+	{
+		baseIRI: "http://example.org/doc",
+		defaultVocab: "http://schema.org/",
+	}
+);
+
+// quads[0] = {
+//   subject: { termType: 'NamedNode', value: 'http://example.org/doc#article' },
+//   predicate: { termType: 'NamedNode', value: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type' },
+//   object: { termType: 'NamedNode', value: 'http://schema.org/Article' },
+//   graph: { termType: 'DefaultGraph' }
+// }
+```
+
+### Batch Processing
+
+For multiple documents, process them sequentially:
+
+```javascript
+const documents = [markdown1, markdown2, markdown3];
+const allQuads = documents.flatMap((md) =>
+	parseMDLD(md, { baseIRI: "http://example.org/" })
+);
+```
+
+## Implementation Details
+
+### Subject Resolution
+
+MD-LD follows a clear subject inheritance model:
+
+1. **Root subject** — Declared in YAML-LD `@id` field
+2. **Heading subjects** — `## Title {#id typeof="Type"}`
+3. **Inline subjects** — `[text](#id){typeof="Type"}`
+4. **Blank nodes** — Generated for incomplete triples
+
+```markdown
+# Document
+
+{#doc typeof="Article"}
+
+## Section
+
+{#sec1 typeof="Section"}
+
+[Text]{property="name"} ← property of #sec1
+```
+
+### Property Mapping
+
+| Markdown                | RDF Predicate                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| Top-level H1 (no `#id`) | `rdfs:label` on root subject                                                    |
+| Heading with `{#id}`    | `rdfs:label` on subject                                                         |
+| First paragraph         | `dct:description` on root                                                       |
+| `{property="name"}`     | Resolved via `@vocab` (e.g., `schema:name`)                                     |
+| `{rel="author"}`        | Resolved via `@vocab` (e.g., `schema:author`)                                   |
+| Code block              | `schema:SoftwareSourceCode` with `schema:programmingLanguage` and `schema:text` |
+
+### List Handling
+
+```markdown
+- [Item 1]{property="item"}
+- [Item 2]{property="item"}
+```
+
+Creates **multiple triples** with same predicate (not RDF lists):
+
+```turtle
+<#doc> schema:item "Item 1" .
+<#doc> schema:item "Item 2" .
+```
+
+For RDF lists (`rdf:List`), use `@inlist` in generated HTML.
+
+### Code Block Semantics
+
+Fenced code blocks are automatically mapped to `schema:SoftwareSourceCode`:
+
+```markdown
+\`\`\`sparql {#query-1}
+SELECT * WHERE { ?s ?p ?o }
+\`\`\`
+```
+
+Creates:
+- A `schema:SoftwareSourceCode` resource (or custom type via `typeof`)
+- `schema:programmingLanguage` from the info string (`sparql`)
+- `schema:text` with the raw source code
+- `schema:hasPart` link from the surrounding section
+
+This enables semantic queries like "find all SPARQL queries in my notes."
+
+### Blank Node Strategy
+
+Blank nodes are created for:
+
+1. Task list items without explicit `#id`
+2. Code blocks without explicit `#id`
+3. Inline `typeof` without `id` when used with `rel`
+
+## Testing
+
+```bash
+npm test
+````
+
+Tests cover:
+
+- ✅ YAML-LD frontmatter parsing
+- ✅ Subject inheritance via headings
+- ✅ Property literals and datatypes (`property`, `datatype`)
+- ✅ Object relationships (`rel` on links)
+- ✅ Blank node generation (tasks, code blocks)
+- ✅ List mappings (repeated properties)
+- ✅ Code block semantics (`SoftwareSourceCode`)
+- ✅ Semantic links in lists (`hasPart` TOC)
+- ✅ Cross-references via fragment IDs
+- ✅ Minimal Markdown → RDF (headings, paragraphs)
+
+## Syntax Overview
+
+### Core Features
+
+**YAML-LD Frontmatter** — Define context and root subject:
+
+```yaml
+---
+"@context":
+  "@vocab": "http://schema.org/"
+"@id": "#doc"
+"@type": Article
+---
+```
+
+**Subject Declaration** — Headings create typed subjects:
+
+```markdown
+## Alice Johnson {#alice typeof="Person"}
+```
+
+**Literal Properties** — Inline spans create properties:
+
+```markdown
+[Alice Johnson]{property="name"}
+[30]{property="age" datatype="xsd:integer"}
+```
+
+**Object Properties** — Links create relationships:
+
+```markdown
+[Tech Corp](#company){rel="worksFor"}
+```
+
+**Lists** — Repeated properties:
+
+```markdown
+- [Item 1]{property="tag"}
+- [Item 2]{property="tag"}
+```
+
+**Code Blocks** — Automatic `SoftwareSourceCode` mapping:
+
+````markdown
+```sparql
+SELECT * WHERE { ?s ?p ?o }
+```
+````
+
+````
+
+**Tasks** — Markdown checklists become `schema:Action`:
+```markdown
+- [x] Completed task
+- [ ] Pending task
+````
+
+### Optimization Tips
+
+1. **Reuse DataFactory** — Pass custom factory instance to avoid allocations
+2. **Minimize frontmatter** — Keep `@context` simple for faster parsing
+3. **Batch processing** — Process multiple documents sequentially
+4. **Fragment IDs** — Use `#id` on headings for efficient cross-references
+
+## Future Work
+
+- [ ] Streaming API for large documents
+- [ ] Tables → CSVW integration
+- [ ] Math blocks → MathML + RDF
+- [ ] Image syntax → `schema:ImageObject`
+- [ ] Bare URL links → `dct:references`
+- [ ] Language tags (`lang` attribute)
+- [ ] Source maps for debugging
+
+## Standards Compliance
+
+This parser implements:
+
+- [MD-LD v0.1 Specification](./mdld_spec_dogfood.md)
+- [RDF/JS Data Model](https://rdf.js.org/data-model-spec/)
+- [RDFa Core 1.1](https://www.w3.org/TR/rdfa-core/) (subset)
+- [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/) (frontmatter)