embridge 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xpiu and other Embridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# Embridge
+
+CLI and parser for validating Embridge Markdown files.
+
+The package validates Embridge Markdown. It does not rewrite files or change the
+Embridge format version declared in a document.
+
+## Quick Start
+
+Validate one or more files without installing the package first:
+
+```sh
+npx embridge validate file.md
+```
+
+Convert one file to the parser JSON result:
+
+```sh
+npx embridge to-json file.md
+```
+
+Install it as a development dependency:
+
+```sh
+npm install --save-dev embridge
+npx embridge validate file.md
+```
+
+## Commands
+
+```sh
+embridge validate <file...>
+embridge to-json <file.md>
+embridge help
+embridge --help
+embridge --version
+```
+
+`validate` parses each file and prints diagnostics to stderr. It prints nothing
+when parsing completes without diagnostics.
+
+Exit codes:
+
+- `0`: parsing completed without diagnostics
+- `1`: parsing completed and one or more diagnostics were found
+- `2`: command usage error, unreadable file, or unexpected runtime failure
+
+Diagnostics include the file name, line number when available, severity, and
+message:
+
+```text
+file.md:12: warning: Duplicate item id "abc123"
+```
+
+`to-json` prints the full parser result as pretty JSON. Parser diagnostics do
+not make `to-json` fail because the JSON output is useful for diagnosis.
+
+## Library Usage
+
+```js
+const { parseEmbridge } = require("embridge");
+
+const tree = parseEmbridge(markdown, { sourceName: "file.md" });
+```
+
+The parser result includes `documentMetadata`, parsed `lists`, and
+`diagnostics`.
+
+## Format Documentation
+
+The Embridge format specification lives in the main repository:
+
+- https://github.com/embridge-foundation/embridge
+- https://embridge.net
+
+This package currently ships the JavaScript reference parser and CLI from the
+repository's `tools/reference-parser/` directory.

package/bin/embridge-parse.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseEmbridge } = require('../src');
+
+const args = process.argv.slice(2);
+
+if (args[0] === '--check') {
+  const fixturesDir = args[1];
+  const expectedDir = args[2];
+  if (!fixturesDir || !expectedDir) usage(1);
+  const ok = checkFixtures(fixturesDir, expectedDir);
+  process.exit(ok ? 0 : 1);
+}
+
+if (args.length !== 1) usage(1);
+
+const inputPath = args[0];
+const input = fs.readFileSync(inputPath, 'utf8');
+const result = parseEmbridge(input, { sourceName: inputPath });
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+
+function usage(exitCode) {
+  const text = [
+    'Usage:',
+    '  embridge-parse <file.md>',
+    '  embridge-parse --check <fixtures-dir> <expected-dir>',
+  ].join('\n');
+  (exitCode === 0 ? console.log : console.error)(text);
+  process.exit(exitCode);
+}
+
+function checkFixtures(fixturesDir, expectedDir) {
+  const fixtures = fs.readdirSync(fixturesDir)
+    .filter((file) => file.endsWith('.md'))
+    .sort();
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const fixture of fixtures) {
+    const base = fixture.replace(/\.md$/, '');
+    const expectedPath = path.join(expectedDir, `${base}.json`);
+    if (!fs.existsSync(expectedPath)) continue;
+
+    const input = fs.readFileSync(path.join(fixturesDir, fixture), 'utf8');
+    const expected = JSON.parse(fs.readFileSync(expectedPath, 'utf8'));
+    const actual = parseEmbridge(input, { sourceName: fixture });
+
+    if (matchesExpected(actual, expected)) {
+      passed += 1;
+      console.log(`PASS ${base}`);
+    } else {
+      failed += 1;
+      console.log(`FAIL ${base}`);
+      const diff = firstDifference(actual, expected);
+      if (diff) console.log(`  ${diff}`);
+    }
+  }
+
+  console.log('');
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  return failed === 0;
+}
+
+function matchesExpected(actual, expected) {
+  return JSON.stringify(normalizeForComparison(actual)) === JSON.stringify(normalizeForComparison(expected));
+}
+
+function normalizeForComparison(tree) {
+  const clone = JSON.parse(JSON.stringify(tree));
+  clone.diagnostics = (clone.diagnostics || []).map((diagnostic) => ({
+    line: diagnostic.line,
+    severity: diagnostic.severity,
+  }));
+  return clone;
+}
+
+function firstDifference(actual, expected) {
+  const actualNorm = normalizeForComparison(actual);
+  const expectedNorm = normalizeForComparison(expected);
+  return walkDiff(actualNorm, expectedNorm, '$');
+}
+
+function walkDiff(actual, expected, pathName) {
+  if (JSON.stringify(actual) === JSON.stringify(expected)) return null;
+  if (typeof actual !== typeof expected) return `${pathName}: got ${typeof actual}, expected ${typeof expected}`;
+  if (actual === null || expected === null || typeof actual !== 'object') {
+    return `${pathName}: got ${JSON.stringify(actual)}, expected ${JSON.stringify(expected)}`;
+  }
+
+  const actualKeys = Array.isArray(actual) ? actual.map((_, i) => String(i)) : Object.keys(actual);
+  const expectedKeys = Array.isArray(expected) ? expected.map((_, i) => String(i)) : Object.keys(expected);
+  const keys = Array.from(new Set([...actualKeys, ...expectedKeys]));
+
+  for (const key of keys) {
+    const diff = walkDiff(actual[key], expected[key], Array.isArray(actual) ? `${pathName}[${key}]` : `${pathName}.${key}`);
+    if (diff) return diff;
+  }
+
+  return `${pathName}: values differ`;
+}

package/bin/embridge.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/cli').main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "embridge",
+  "version": "0.2.2",
+  "description": "CLI and parser for validating Embridge Markdown files",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "bin": {
+    "embridge": "bin/embridge.js",
+    "embridge-parse": "bin/embridge-parse.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/conformance.test.js && node test/release-consistency.test.js && node test/cli.test.js",
+    "check": "node bin/embridge-parse.js --check ../../tests/fixtures ../../tests/expected"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/embridge-foundation/embridge.git",
+    "directory": "tools/reference-parser"
+  },
+  "bugs": {
+    "url": "https://github.com/embridge-foundation/embridge/issues"
+  },
+  "homepage": "https://github.com/embridge-foundation/embridge#readme",
+  "keywords": [
+    "embridge",
+    "markdown",
+    "tasks",
+    "todo",
+    "parser",
+    "validator",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/ast.js

@@ -0,0 +1,45 @@
+'use strict';
+
+function createDocument(documentMetadata) {
+  return {
+    documentMetadata: documentMetadata || null,
+    lists: [],
+    diagnostics: [],
+  };
+}
+
+function createList(title) {
+  return {
+    title: title === undefined ? null : title,
+    preamble: null,
+    items: [],
+  };
+}
+
+function createItem(title, completed, marker) {
+  return {
+    title,
+    completed,
+    marker,
+    fields: {},
+    description: null,
+    comments: [],
+    subitems: [],
+  };
+}
+
+function createComment(replyDepth, author, timestamp, text) {
+  return {
+    replyDepth,
+    author,
+    timestamp,
+    text,
+  };
+}
+
+module.exports = {
+  createDocument,
+  createList,
+  createItem,
+  createComment,
+};

package/src/cli.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseEmbridge } = require('./index');
+
+function main(args, options = {}) {
+  const code = run(args, options);
+  if (!options.noExit) process.exitCode = code;
+  return code;
+}
+
+function run(args, options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+
+  if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+    write(stdout, helpText());
+    return 0;
+  }
+
+  if (args[0] === '--version' || args[0] === '-v') {
+    write(stdout, `${readPackageVersion()}\n`);
+    return 0;
+  }
+
+  if (args[0] === 'validate') {
+    return validate(args.slice(1), stderr);
+  }
+
+  if (args[0] === 'to-json') {
+    return toJson(args.slice(1), stdout, stderr);
+  }
+
+  write(stderr, `Unknown command: ${args[0]}\n\n${usageText()}\n`);
+  return 2;
+}
+
+function validate(files, stderr) {
+  if (files.length === 0) {
+    write(stderr, `Missing file path.\n\n${usageText()}\n`);
+    return 2;
+  }
+
+  let hasDiagnostics = false;
+
+  for (const file of files) {
+    let input;
+    try {
+      input = fs.readFileSync(file, 'utf8');
+    } catch (error) {
+      write(stderr, `${file}: ${error.message}\n`);
+      return 2;
+    }
+
+    let result;
+    try {
+      result = parseEmbridge(input, { sourceName: file });
+    } catch (error) {
+      write(stderr, `${file}: ${error.message}\n`);
+      return 2;
+    }
+
+    for (const diagnostic of result.diagnostics || []) {
+      hasDiagnostics = true;
+      write(stderr, formatDiagnostic(file, diagnostic));
+    }
+  }
+
+  return hasDiagnostics ? 1 : 0;
+}
+
+function toJson(files, stdout, stderr) {
+  if (files.length !== 1) {
+    write(stderr, `Expected exactly one file path.\n\n${usageText()}\n`);
+    return 2;
+  }
+
+  const file = files[0];
+  let input;
+  try {
+    input = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    write(stderr, `${file}: ${error.message}\n`);
+    return 2;
+  }
+
+  let result;
+  try {
+    result = parseEmbridge(input, { sourceName: file });
+  } catch (error) {
+    write(stderr, `${file}: ${error.message}\n`);
+    return 2;
+  }
+
+  write(stdout, `${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+function formatDiagnostic(file, diagnostic) {
+  const location = diagnostic.line ? `${file}:${diagnostic.line}` : file;
+  const severity = diagnostic.severity || 'warning';
+  const message = diagnostic.message || 'diagnostic';
+  return `${location}: ${severity}: ${message}\n`;
+}
+
+function readPackageVersion() {
+  const packagePath = path.join(__dirname, '..', 'package.json');
+  return JSON.parse(fs.readFileSync(packagePath, 'utf8')).version;
+}
+
+function helpText() {
+  return [
+    usageText(),
+    '',
+    'Commands:',
+    '  validate <file...>  Validate Embridge Markdown files',
+    '  to-json <file.md>   Parse an Embridge Markdown file as JSON',
+    '',
+    'Options:',
+    '  -h, --help          Show this help',
+    '  -v, --version       Show the package version',
+    '',
+  ].join('\n');
+}
+
+function usageText() {
+  return 'Usage: embridge <command> [options]';
+}
+
+function write(stream, text) {
+  stream.write(text);
+}
+
+module.exports = {
+  main,
+  run,
+  toJson,
+  validate,
+};

package/src/comments.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { createComment } = require('./ast');
+
+function parseCommentLine(line) {
+  const match = line.match(/^(\s*)(>+)\s?(.*)$/);
+  if (!match) return null;
+
+  const indent = match[1].length;
+  const replyDepth = match[2].length;
+  const raw = match[3].trim();
+
+  let prefix = raw.match(/^@([^\[\s:]+)\s+\[([^\]]+)\]\s*:\s*(.*)$/);
+  if (prefix) {
+    return {
+      indent,
+      comment: createComment(replyDepth, prefix[1], prefix[2], prefix[3]),
+      hasPrefix: true,
+    };
+  }
+
+  prefix = raw.match(/^@([^\[\s:]+)\s*:\s*(.*)$/);
+  if (prefix) {
+    return {
+      indent,
+      comment: createComment(replyDepth, prefix[1], null, prefix[2]),
+      hasPrefix: true,
+    };
+  }
+
+  prefix = raw.match(/^\[([^\]]+)\]\s*:\s*(.*)$/);
+  if (prefix) {
+    return {
+      indent,
+      comment: createComment(replyDepth, null, prefix[1], prefix[2]),
+      hasPrefix: true,
+    };
+  }
+
+  return {
+    indent,
+    comment: createComment(replyDepth, null, null, raw),
+    hasPrefix: false,
+  };
+}
+
+function appendOrAddComment(item, parsed) {
+  const previous = item.comments[item.comments.length - 1];
+
+  if (!parsed.hasPrefix && previous && previous.replyDepth === parsed.comment.replyDepth) {
+    previous.text += `\n${parsed.comment.text}`;
+    return;
+  }
+
+  item.comments.push(parsed.comment);
+}
+
+module.exports = {
+  parseCommentLine,
+  appendOrAddComment,
+};

package/src/diagnostics.js

@@ -0,0 +1,13 @@
+'use strict';
+
+function warning(line, message) {
+  return {
+    line,
+    severity: 'warning',
+    message,
+  };
+}
+
+module.exports = {
+  warning,
+};

package/src/document-metadata.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const SHORT_INLINE_FORMAT_RE = /^embridge\s+v\d+\.\d+\.\d+(?:,\s*.+)?$/i;
+
+function extractDocumentMetadata(markdown) {
+  const source = markdown.replace(/^\uFEFF/, '');
+  const comments = findBoundaryHtmlComments(source);
+  const skippedLines = new Set();
+
+  if (comments.length === 0) {
+    return {
+      documentMetadata: null,
+      skippedLines,
+    };
+  }
+
+  const metadataCandidates = [];
+  for (const comment of comments) {
+    for (let line = comment.startLine; line <= comment.endLine; line += 1) {
+      skippedLines.add(line);
+    }
+
+    const documentMetadata = parseDocumentMetadata(comment.content);
+    if (documentMetadata) {
+      metadataCandidates.push({
+        documentMetadata,
+        kind: isInlineFormatTag(comment.content) ? 'inline' : 'block',
+      });
+    }
+  }
+
+  const blockCandidate = lastCandidateOfKind(metadataCandidates, 'block');
+  const inlineCandidate = lastCandidateOfKind(metadataCandidates, 'inline');
+  const selected = blockCandidate || inlineCandidate;
+
+  return {
+    documentMetadata: selected ? selected.documentMetadata : null,
+    skippedLines,
+  };
+}
+
+function findBoundaryHtmlComments(source) {
+  const lines = source.split(/\r?\n/);
+  const comments = [];
+  const seen = new Set();
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (/^\s*$/.test(lines[index])) continue;
+
+    const comment = readStandaloneHtmlCommentAt(lines, index);
+    if (!comment) break;
+    addComment(comments, seen, comment);
+    index = comment.endIndex;
+  }
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    if (/^\s*$/.test(lines[index])) continue;
+
+    const comment = readStandaloneHtmlCommentEndingAt(lines, index);
+    if (!comment) break;
+    addComment(comments, seen, comment);
+    index = comment.startIndex;
+  }
+
+  comments.sort((a, b) => a.startLine - b.startLine);
+  return comments;
+}
+
+function readStandaloneHtmlCommentAt(lines, startIndex) {
+  const singleLine = lines[startIndex].match(/^\s*<!--([\s\S]*?)-->\s*$/);
+  if (singleLine) return toComment(singleLine[1], startIndex, startIndex);
+
+  if (!/^\s*<!--\s*$/.test(lines[startIndex])) return null;
+
+  const content = [];
+  let index = startIndex + 1;
+  while (index < lines.length && lines[index].trim() !== '-->') {
+    content.push(lines[index]);
+    index += 1;
+  }
+
+  return index < lines.length ? toComment(content.join('\n'), startIndex, index) : null;
+}
+
+function readStandaloneHtmlCommentEndingAt(lines, endIndex) {
+  const singleLine = lines[endIndex].match(/^\s*<!--([\s\S]*?)-->\s*$/);
+  if (singleLine) return toComment(singleLine[1], endIndex, endIndex);
+  if (lines[endIndex].trim() !== '-->') return null;
+
+  for (let index = endIndex - 1; index >= 0; index -= 1) {
+    if (/^\s*<!--\s*$/.test(lines[index])) {
+      return toComment(lines.slice(index + 1, endIndex).join('\n'), index, endIndex);
+    }
+  }
+  return null;
+}
+
+function toComment(content, startIndex, endIndex) {
+  return {
+    content,
+    startIndex,
+    endIndex,
+    startLine: startIndex + 1,
+    endLine: endIndex + 1,
+  };
+}
+
+function addComment(comments, seen, comment) {
+  const key = `${comment.startLine}:${comment.endLine}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  comments.push(comment);
+}
+
+function lastCandidateOfKind(candidates, kind) {
+  for (let index = candidates.length - 1; index >= 0; index -= 1) {
+    if (candidates[index].kind === kind) return candidates[index];
+  }
+  return null;
+}
+
+function isInlineFormatTag(content) {
+  const trimmed = content.trim();
+  return SHORT_INLINE_FORMAT_RE.test(trimmed) ||
+    /^format\s*:\s*.+$/i.test(trimmed);
+}
+
+function emptyDocumentMetadata() {
+  return {
+    title: null,
+    sync: null,
+    uuid: null,
+    lists: null,
+    fields: null,
+    syntax: null,
+    format: null,
+  };
+}
+
+function parseDocumentMetadata(content) {
+  const trimmed = content.trim();
+  const result = emptyDocumentMetadata();
+  let recognized = false;
+
+  if (!trimmed) return null;
+  if (SHORT_INLINE_FORMAT_RE.test(trimmed)) {
+    result.format = trimmed;
+    return result;
+  }
+
+  for (const rawLine of trimmed.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    const match = line.match(/^([A-Za-z][A-Za-z0-9-]*)\s*:\s*(.*)$/);
+    if (!match) continue;
+
+    const key = match[1].toLowerCase();
+    const value = match[2].trim();
+
+    if (key === 'title') {
+      result.title = value;
+      recognized = true;
+    } else if (key === 'sync') {
+      result.sync = value;
+      recognized = true;
+    } else if (key === 'uuid') {
+      result.uuid = value;
+      recognized = true;
+    } else if (key === 'lists') {
+      result.lists = parseLists(value);
+      recognized = true;
+    } else if (key === 'fields') {
+      result.fields = parseFields(value);
+      recognized = true;
+    } else if (key === 'syntax') {
+      result.syntax = parseSyntax(value);
+      recognized = true;
+    } else if (key === 'format') {
+      result.format = value;
+      recognized = true;
+    } else if (key === 'embridge') {
+      result.format = `embridge:${value}`;
+      recognized = true;
+    }
+  }
+
+  return recognized ? result : null;
+}
+
+function parseFields(value) {
+  const fields = value.split(',').map((part) => part.trim()).filter(Boolean);
+  return fields.length > 0 ? fields : null;
+}
+
+function parseSyntax(value) {
+  const match = value.match(/(?:^|,\s*)mode\s*:\s*(marker|blank-lines)\s*(?:,|$)/);
+  return match ? { mode: match[1] } : null;
+}
+
+function parseLists(value) {
+  const lists = [];
+  const re = /"((?:[^"]|"")*)"\s*([^\s,]+)/g;
+  let match;
+  while ((match = re.exec(value)) !== null) {
+    lists.push({
+      title: match[1].replace(/""/g, '"'),
+      id: match[2],
+    });
+  }
+  return lists.length > 0 ? lists : null;
+}
+
+module.exports = {
+  extractDocumentMetadata,
+  parseDocumentMetadata,
+};

package/src/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const { parseEmbridge } = require('./parser');
+
+module.exports = {
+  parseEmbridge,
+};

package/src/metadata.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const DESCRIPTION_KEYS = new Set(['description', 'desc', 'descr']);
+
+function parseMetadataFields(raw) {
+  return parseMetadataLine(raw).fields;
+}
+
+function parseMetadataLine(raw) {
+  const fields = {};
+  const repeatedKeys = [];
+  let i = 0;
+  let unparsedTail = null;
+
+  while (i < raw.length) {
+    while (i < raw.length && /[\s,]/.test(raw[i])) i += 1;
+    if (i >= raw.length) break;
+
+    const keyMatch = raw.slice(i).match(/^([A-Za-z][A-Za-z0-9-]*)\s*:\s*/);
+    if (!keyMatch) {
+      unparsedTail = raw.slice(i).trim();
+      break;
+    }
+
+    const key = keyMatch[1];
+    i += keyMatch[0].length;
+
+    let value = '';
+    if (raw[i] === '"') {
+      i += 1;
+      while (i < raw.length) {
+        if (raw[i] === '"' && raw[i + 1] === '"') {
+          value += '"';
+          i += 2;
+        } else if (raw[i] === '"') {
+          i += 1;
+          break;
+        } else {
+          value += raw[i];
+          i += 1;
+        }
+      }
+      while (i < raw.length && raw[i] !== ',') i += 1;
+    } else {
+      const start = i;
+      while (i < raw.length && raw[i] !== ',') i += 1;
+      value = raw.slice(start, i).trim();
+    }
+
+    if (Object.prototype.hasOwnProperty.call(fields, key)) repeatedKeys.push(key);
+    fields[key] = value;
+    if (raw[i] === ',') i += 1;
+  }
+
+  return { fields, repeatedKeys, unparsedTail };
+}
+
+function hasAnyKeyValue(raw) {
+  return /[A-Za-z][A-Za-z0-9-]*\s*:/.test(raw);
+}
+
+function descriptionFromFields(fields) {
+  for (const key of Object.keys(fields)) {
+    if (isDescriptionKey(key)) return fields[key];
+  }
+  return null;
+}
+
+function isDescriptionKey(key) {
+  return DESCRIPTION_KEYS.has(String(key || '').toLowerCase());
+}
+
+module.exports = {
+  parseMetadataLine,
+  parseMetadataFields,
+  hasAnyKeyValue,
+  descriptionFromFields,
+  isDescriptionKey,
+};

package/src/parser.js

@@ -0,0 +1,577 @@
+'use strict';
+
+const { createDocument, createList, createItem } = require('./ast');
+const { warning } = require('./diagnostics');
+const { extractDocumentMetadata } = require('./document-metadata');
+const { parseCommentLine, appendOrAddComment } = require('./comments');
+const {
+  parseMetadataLine,
+  hasAnyKeyValue,
+  descriptionFromFields,
+  isDescriptionKey,
+} = require('./metadata');
+
+function parseEmbridge(markdown, options) {
+  const source = String(markdown || '').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+  const metadataInfo = extractDocumentMetadata(source);
+  const document = createDocument(metadataInfo.documentMetadata);
+  const state = createState(document, metadataInfo.skippedLines);
+  const lines = source.split('\n');
+  const mode = (options && options.mode) ||
+    (metadataInfo.documentMetadata && metadataInfo.documentMetadata.syntax && metadataInfo.documentMetadata.syntax.mode) ||
+    'marker';
+
+  if (mode === 'blank-lines') parseBlankLinesMode(lines, state);
+  else parseMarkerMode(lines, state);
+
+  resolveListRegistry(document);
+
+  return document;
+}
+
+function resolveListRegistry(document) {
+  const registry = document.documentMetadata && document.documentMetadata.lists;
+  if (!registry || registry.length === 0) return;
+
+  const entriesByTitle = groupByTitle(registry);
+  const listsByTitle = groupByTitle(document.lists);
+
+  for (const [title, lists] of listsByTitle.entries()) {
+    if (title === null) continue;
+    const entries = entriesByTitle.get(title);
+    if (!entries || entries.length === 0) {
+      applyInlineListIds(lists);
+      continue;
+    }
+
+    const pairCount = Math.min(entries.length, lists.length);
+    for (let index = 0; index < pairCount; index += 1) {
+      lists[index].id = entries[index].id;
+    }
+
+    for (let index = pairCount; index < lists.length; index += 1) {
+      applyInlineListId(lists[index]);
+    }
+  }
+}
+
+function groupByTitle(values) {
+  const groups = new Map();
+  for (const value of values) {
+    const title = value.title;
+    if (!groups.has(title)) groups.set(title, []);
+    groups.get(title).push(value);
+  }
+  return groups;
+}
+
+function applyInlineListIds(lists) {
+  for (const list of lists) applyInlineListId(list);
+}
+
+function applyInlineListId(list) {
+  if (list.fields && Object.prototype.hasOwnProperty.call(list.fields, 'id')) {
+    list.id = list.fields.id;
+  }
+}
+
+function createState(document, skippedLines) {
+  return {
+    document,
+    skippedLines,
+    currentList: null,
+    itemStack: [],
+    seenItemIds: new Map(),
+    itemIds: new WeakMap(),
+    sectionMetaEligible: false,
+    itemMetaEligible: false,
+  };
+}
+
+function parseMarkerMode(lines, state) {
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineNo = index + 1;
+    if (state.skippedLines.has(lineNo)) continue;
+
+    const line = lines[index];
+    if (/^\s*$/.test(line)) {
+      if (sectionMetadataTarget(state)) state.sectionMetaEligible = false;
+      state.itemMetaEligible = false;
+      continue;
+    }
+
+    const heading = line.match(/^# (.+)$/);
+    if (heading) {
+      state.currentList = createList(heading[1].trim());
+      state.document.lists.push(state.currentList);
+      state.itemStack = [];
+      state.sectionMetaEligible = true;
+      state.itemMetaEligible = false;
+      continue;
+    }
+
+    const sectionTarget = sectionMetadataTarget(state);
+
+    const invalid = invalidMarkerDiagnostic(line, lineNo);
+    if (invalid) {
+      state.sectionMetaEligible = false;
+      state.itemMetaEligible = false;
+      state.document.diagnostics.push(invalid);
+      continue;
+    }
+
+    const itemToken = parseMarkerItem(line);
+    if (itemToken) {
+      state.sectionMetaEligible = false;
+      addItem(state, itemToken, lineNo);
+      state.itemMetaEligible = true;
+      continue;
+    }
+
+    const parsedComment = parseCommentLine(line);
+    if (parsedComment) {
+      state.sectionMetaEligible = false;
+      state.itemMetaEligible = false;
+      const target = findItemForIndent(state, parsedComment.indent) || mostRecentItem(state);
+      if (target) appendOrAddComment(target, parsedComment);
+      continue;
+    }
+
+    if (/^\s*"/.test(line)) {
+      if (!sectionTarget && !state.itemMetaEligible) {
+        warnNonConformantMetadataLikeLine(state, lineNo);
+        continue;
+      }
+      const result = readDescription(lines, index, state.skippedLines);
+      index = result.endIndex;
+      if (sectionTarget) applyDescription(state, sectionTarget, result, lineNo, {
+        mergeFields: true,
+        trackItemIds: false,
+      });
+      else attachDescription(state, result, lineNo);
+      continue;
+    }
+
+    if (hasAnyKeyValue(line)) {
+      if (sectionTarget) applyMetadata(state, sectionTarget, line.trim(), lineNo, {
+        mergeFields: true,
+        trackItemIds: false,
+      });
+      else if (state.itemMetaEligible) attachMetadata(state, line.trim(), lineNo);
+      else warnNonConformantMetadataLikeLine(state, lineNo);
+      continue;
+    }
+
+    if (sectionTarget) {
+      state.sectionMetaEligible = false;
+      state.document.diagnostics.push(warning(lineNo, 'non-conformant section metadata (not key: value metadata)'));
+      continue;
+    }
+
+    if (mostRecentItem(state)) {
+      state.itemMetaEligible = false;
+      state.document.diagnostics.push(warning(lineNo, 'non-conformant free-form text (not key: value metadata)'));
+    }
+  }
+}
+
+function parseBlankLinesMode(lines, state) {
+  let inPreamble = false;
+  let blockOpen = false;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineNo = index + 1;
+    if (state.skippedLines.has(lineNo)) continue;
+
+    const line = lines[index];
+    if (/^\s*$/.test(line)) {
+      blockOpen = false;
+      state.sectionMetaEligible = false;
+      state.itemMetaEligible = false;
+      if (inPreamble) {
+        if (state.currentList && state.currentList.preamble && state.currentList.preamble.length === 0) {
+          state.currentList.preamble = null;
+        }
+        inPreamble = false;
+      }
+      continue;
+    }
+
+    const heading = line.match(/^# (.+)$/);
+    if (heading) {
+      state.currentList = createList(heading[1].trim());
+      state.currentList.preamble = [];
+      state.document.lists.push(state.currentList);
+      state.itemStack = [];
+      inPreamble = true;
+      state.sectionMetaEligible = true;
+      state.itemMetaEligible = false;
+      blockOpen = false;
+      continue;
+    }
+
+    const invalid = invalidMarkerDiagnostic(line, lineNo);
+    if (invalid) {
+      state.sectionMetaEligible = false;
+      state.itemMetaEligible = false;
+      state.document.diagnostics.push(invalid);
+      continue;
+    }
+
+    const itemToken = parseMarkerItem(line);
+    if (itemToken) {
+      state.sectionMetaEligible = false;
+      if (inPreamble) {
+        if (state.currentList && state.currentList.preamble && state.currentList.preamble.length === 0) {
+          state.currentList.preamble = null;
+        }
+        inPreamble = false;
+      }
+      addItem(state, itemToken, lineNo);
+      state.itemMetaEligible = true;
+      blockOpen = true;
+      continue;
+    }
+
+    if (inPreamble && state.currentList && state.currentList.items.length === 0) {
+      if (state.sectionMetaEligible && /^\s*"/.test(line)) {
+        const result = readDescription(lines, index, state.skippedLines);
+        index = result.endIndex;
+        applyDescription(state, state.currentList, result, lineNo, {
+          mergeFields: true,
+          trackItemIds: false,
+        });
+        continue;
+      }
+
+      if (state.sectionMetaEligible && hasAnyKeyValue(line)) {
+        applyMetadata(state, state.currentList, line.trim(), lineNo, {
+          mergeFields: true,
+          trackItemIds: false,
+        });
+        continue;
+      }
+
+      state.sectionMetaEligible = false;
+      state.itemMetaEligible = false;
+      state.currentList.preamble.push(line.trim());
+      continue;
+    }
+
+    const parsedComment = parseCommentLine(line);
+    if (parsedComment) {
+      if (!blockOpen) {
+        state.document.diagnostics.push(warning(lineNo, 'orphaned comment after blank-line boundary with no parent item in current block'));
+        continue;
+      }
+      state.itemMetaEligible = false;
+      const target = findItemForIndent(state, parsedComment.indent) || mostRecentItem(state);
+      if (target) appendOrAddComment(target, parsedComment);
+      continue;
+    }
+
+    if (/^\s*"/.test(line)) {
+      if (!blockOpen) continue;
+      if (!state.itemMetaEligible) {
+        warnNonConformantMetadataLikeLine(state, lineNo);
+        continue;
+      }
+      const result = readDescription(lines, index, state.skippedLines);
+      index = result.endIndex;
+      attachDescription(state, result, lineNo);
+      continue;
+    }
+
+    if (hasAnyKeyValue(line) && blockOpen) {
+      if (state.itemMetaEligible) attachMetadata(state, line.trim(), lineNo);
+      else warnNonConformantMetadataLikeLine(state, lineNo);
+      continue;
+    }
+
+    const blankItem = parseBlankLineItem(line);
+    addItem(state, blankItem, lineNo);
+    state.itemMetaEligible = true;
+    blockOpen = true;
+  }
+
+  if (state.currentList && state.currentList.preamble && state.currentList.preamble.length === 0) {
+    state.currentList.preamble = null;
+  }
+}
+
+function parseMarkerItem(line) {
+  const match = line.match(/^(\s*)(?:- |((?:0|[1-9]\d*)\.) )(\[[ xX]\] )?(.*)$/);
+  if (!match) return null;
+
+  const indent = match[1].length;
+  const numberText = match[2] ? match[2].slice(0, -1) : null;
+  const markerWidth = match[2] ? match[2].length + 1 : 2;
+  const marker = numberText === null
+    ? { type: 'bullet' }
+    : { type: 'ordered', number: Number(numberText) };
+  const completed = parseCheckbox(match[3]);
+  const title = match[4].trim();
+
+  return { indent, marker, markerWidth, completed, title };
+}
+
+function parseBlankLineItem(line) {
+  const indent = (line.match(/^\s*/) || [''])[0].length;
+  let title = line.trim();
+  let completed = null;
+
+  const checkbox = title.match(/^\[([ xX])\]\s+(.*)$/);
+  if (checkbox) {
+    completed = checkbox[1] === 'x' || checkbox[1] === 'X';
+    title = checkbox[2].trim();
+  }
+
+  return {
+    indent,
+    marker: { type: 'none' },
+    markerWidth: null,
+    completed,
+    title,
+  };
+}
+
+function parseCheckbox(raw) {
+  if (!raw) return null;
+  if (raw === '[ ] ') return false;
+  return true;
+}
+
+function invalidMarkerDiagnostic(line, lineNo) {
+  const leadingZero = line.match(/^\s*(0\d+)\. /);
+  if (leadingZero) {
+    return warning(lineNo, `'${leadingZero[1]}.' has leading zeros and is not recognized as an ordered marker`);
+  }
+
+  const dashNoSpace = line.match(/^\s*(-(?:\S|[^\S ]).*)/);
+  if (dashNoSpace) {
+    return warning(lineNo, `'${dashNoSpace[1]}' is not a valid item (space required after marker)`);
+  }
+
+  const orderedNoSpace = line.match(/^\s*(\d+\.(?:\S|[^\S ]).*)/);
+  if (orderedNoSpace) {
+    return warning(lineNo, `'${orderedNoSpace[1]}' is not a valid item (space required after marker)`);
+  }
+
+  return null;
+}
+
+function addItem(state, token, lineNo) {
+  ensureList(state);
+
+  const item = createItem(token.title, token.completed, token.marker);
+
+  while (state.itemStack.length > 0 && state.itemStack[state.itemStack.length - 1].indent >= token.indent) {
+    state.itemStack.pop();
+  }
+
+  if (state.itemStack.length === 0) {
+    state.currentList.items.push(item);
+  } else {
+    const parent = state.itemStack[state.itemStack.length - 1];
+    warnForNonCanonicalIndent(state, token, parent, lineNo);
+    parent.item.subitems.push(item);
+  }
+
+  state.itemStack.push({ item, indent: token.indent, markerWidth: token.markerWidth });
+}
+
+function warnForNonCanonicalIndent(state, token, parent, lineNo) {
+  if (parent.markerWidth === null) return;
+
+  const canonicalIndent = parent.indent + parent.markerWidth;
+  if (token.indent === canonicalIndent) return;
+
+  state.document.diagnostics.push(warning(
+    lineNo,
+    `non-canonical indentation (${token.indent} space${token.indent === 1 ? '' : 's'}); child SHOULD align to parent content column (${canonicalIndent} spaces)`,
+  ));
+}
+
+function attachMetadata(state, raw, lineNo) {
+  const item = mostRecentItem(state);
+  if (!item) return;
+
+  applyMetadata(state, item, raw, lineNo, { mergeFields: true, trackItemIds: true });
+}
+
+function attachDescription(state, result, lineNo) {
+  const item = mostRecentItem(state);
+  if (!item) return;
+
+  applyDescription(state, item, result, lineNo, { mergeFields: true, trackItemIds: true });
+}
+
+// Shared by item and section (list) targets. Unknown fields are preserved for
+// forward compatibility; tooling SHOULD normalize canonical list fields into
+// document metadata.
+function applyMetadata(state, target, raw, lineNo, options) {
+  const result = parseMetadataLine(raw);
+  const fields = result.fields;
+  if (Object.keys(fields).length === 0) {
+    state.document.diagnostics.push(warning(lineNo, 'non-conformant free-form text (not key: value metadata)'));
+    return;
+  }
+
+  recordRepeatedMetadataFields(state, target, fields, result.repeatedKeys, lineNo);
+  assignFields(target, fields, options);
+  const description = descriptionFromFields(fields);
+  if (description !== null) target.description = description;
+  if (options && options.trackItemIds) recordDuplicateItemId(state, target, fields, lineNo);
+  recordUnparsedMetadataTail(state, result, lineNo);
+}
+
+function applyDescription(state, target, result, lineNo, options) {
+  if (target.description != null) {
+    state.document.diagnostics.push(warning(lineNo, "repeated metadata field 'description'"));
+  }
+  target.description = result.value;
+  if (result.trailingMeta) {
+    const metadata = parseMetadataLine(result.trailingMeta);
+    const fields = metadata.fields;
+    recordRepeatedMetadataFields(state, target, fields, metadata.repeatedKeys, lineNo);
+    if (Object.keys(fields).length > 0) assignFields(target, fields, options);
+    if (options && options.trackItemIds) recordDuplicateItemId(state, target, fields, lineNo);
+    recordUnparsedMetadataTail(state, metadata, lineNo);
+  }
+}
+
+function recordRepeatedMetadataFields(state, target, fields, repeatedKeys, lineNo) {
+  const warned = new Set();
+  for (const key of repeatedKeys || []) warnRepeatedMetadataField(state, warned, key, lineNo);
+
+  for (const key of Object.keys(fields)) {
+    if (Object.prototype.hasOwnProperty.call(target.fields || {}, key)) {
+      warnRepeatedMetadataField(state, warned, key, lineNo);
+      continue;
+    }
+
+    if (isDescriptionKey(key) && target.description != null) {
+      warnRepeatedMetadataField(state, warned, 'description', lineNo);
+    }
+  }
+}
+
+function warnRepeatedMetadataField(state, warned, key, lineNo) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  state.document.diagnostics.push(warning(lineNo, `repeated metadata field '${key}'`));
+}
+
+function assignFields(target, fields, options) {
+  if (options && options.mergeFields) {
+    target.fields = Object.assign({}, target.fields || {}, fields);
+  } else {
+    target.fields = fields;
+  }
+}
+
+function readDescription(lines, startIndex, skippedLines) {
+  let lineIndex = startIndex;
+  let line = lines[lineIndex];
+  let pos = line.indexOf('"') + 1;
+  let value = '';
+
+  while (lineIndex < lines.length) {
+    if (skippedLines.has(lineIndex + 1)) break;
+    line = lines[lineIndex];
+
+    while (pos < line.length) {
+      const ch = line[pos];
+      if (ch === '"' && line[pos + 1] === '"') {
+        value += '"';
+        pos += 2;
+      } else if (ch === '"') {
+        const trailing = line.slice(pos + 1).trim();
+        return {
+          value,
+          trailingMeta: trailing.replace(/^,\s*/, '') || null,
+          endIndex: lineIndex,
+        };
+      } else {
+        value += ch;
+        pos += 1;
+      }
+    }
+
+    lineIndex += 1;
+    if (lineIndex < lines.length && !skippedLines.has(lineIndex + 1)) {
+      value += '\n';
+      pos = 0;
+    }
+  }
+
+  return {
+    value,
+    trailingMeta: null,
+    endIndex: Math.max(startIndex, lineIndex - 1),
+  };
+}
+
+function recordDuplicateItemId(state, item, fields, lineNo) {
+  for (const key of Object.keys(fields)) {
+    if (key.toLowerCase() !== 'id') continue;
+    const id = fields[key];
+    if (!id) continue;
+
+    const previousId = state.itemIds.get(item);
+    if (previousId && state.seenItemIds.get(previousId) === item) {
+      state.seenItemIds.delete(previousId);
+    }
+
+    const existingItem = state.seenItemIds.get(id);
+    if (existingItem && existingItem !== item) {
+      state.document.diagnostics.push(warning(lineNo, `duplicate item id '${id}'`));
+    } else {
+      state.seenItemIds.set(id, item);
+    }
+    state.itemIds.set(item, id);
+  }
+}
+
+function recordUnparsedMetadataTail(state, result, lineNo) {
+  if (!result.unparsedTail) return;
+  state.document.diagnostics.push(warning(
+    lineNo,
+    `metadata text after comma ignored; quote values containing commas ('${result.unparsedTail}')`,
+  ));
+}
+
+function ensureList(state) {
+  if (!state.currentList) {
+    state.currentList = createList(null);
+    state.document.lists.push(state.currentList);
+  }
+}
+
+function mostRecentItem(state) {
+  return state.itemStack.length > 0 ? state.itemStack[state.itemStack.length - 1].item : null;
+}
+
+function sectionMetadataTarget(state) {
+  return (state.sectionMetaEligible && state.currentList && !mostRecentItem(state))
+    ? state.currentList
+    : null;
+}
+
+function warnNonConformantMetadataLikeLine(state, lineNo) {
+  state.document.diagnostics.push(warning(
+    lineNo,
+    'metadata-like line appears after metadata eligibility closed',
+  ));
+}
+
+function findItemForIndent(state, indent) {
+  for (let i = state.itemStack.length - 1; i >= 0; i -= 1) {
+    if (state.itemStack[i].indent === indent) return state.itemStack[i].item;
+  }
+  return null;
+}
+
+module.exports = {
+  parseEmbridge,
+};