jmd-format 0.1.0 → 0.1.2

package/README.md

@@ -94,6 +94,11 @@ string chunks into an async iterable of complete lines.
 - Thematic breaks (`---`) as array-item separators (§8.6). Consumed by
   the innermost enclosing array whose most-recent item is a dict with
   nested structures.
+- Depth-qualified array items (`##N -`, §8.6a) and depth+1 items
+  (`##N - key: val`, §8.6b). Parser-tolerance forms: the canonical
+  serializer emits bare `- ` items with thematic-break separators, but
+  the parser accepts the depth-annotated forms that LLMs tend to
+  produce when items sit one heading level below the array heading.
 - **Streaming parser** via async generator: events match the sequence
   defined in §18.2 (document_start, field, field_start, field_content,
   object_start/end, array_start/end, item_start/value/end, scope_reset,
@@ -101,14 +106,11 @@ string chunks into an async iterable of complete lines.
 - **Streaming serializer** via sync generator (`serializeLines`).
 - Line adapter (`toLines`) to convert chunked input to lines.
 
-## Not yet supported
+## Not yet structured
 
-Planned for subsequent releases; parser throws a clear error if encountered.
-
-- Depth-qualified items (`## -`, `### -`).
-- Depth+1 items (items one heading level deeper than the array heading).
-- Schema-specific type expressions, QBE filter conditions — parsed as raw
-  strings today; structured interpretation will follow.
+Schema-specific type expressions (§14) and QBE filter conditions (§13)
+are parsed as raw strings on both this implementation and the Python
+reference. Structured interpretation will follow in a later release.
 
 ## Design
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jmd-format",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "JMD (JSON Markdown) — structured data format for LLM-driven infrastructure. JavaScript reference implementation.",
   "type": "module",
   "main": "./src/index.js",

package/src/parser.js

@@ -206,6 +206,15 @@ export function createParser() {
       throw parseError('Mode markers (!, ?, -) are only valid on the root heading')
     }
 
+    // Depth-qualified array item (§8.6a) or depth+1 item (§8.6b):
+    // `##N -` or `##N - key: val` starts a new item in an enclosing array.
+    // Resolution prefers the innermost array at depth N; failing that, an
+    // array at depth N-1 (the LLM-natural "items under the heading" form).
+    if (text === '-' || text.startsWith('- ')) {
+      onDepthQualifiedItem(depth, text)
+      return
+    }
+
     popToDepth(depth)
 
     if (text === '' || text === undefined) {
@@ -213,11 +222,6 @@ export function createParser() {
       return
     }
 
-    // Depth-qualified array item: `## -` or `## - key: val` — deferred.
-    if (text === '-' || text.startsWith('- ')) {
-      throw parseError('Depth-qualified array items (## -) are not yet supported')
-    }
-
     // Anonymous sub-array: `### []` — handled below with the other array forms.
     if (text === '[]') {
       openSubArray(depth)
@@ -356,6 +360,31 @@ export function createParser() {
 
   // --- Array items ---------------------------------------------------------
 
+  function onDepthQualifiedItem(headingDepth, text) {
+    // Find target: innermost array at depth == headingDepth wins (§8.6a).
+    // Else fall back to array at depth == headingDepth - 1 (§8.6b — the
+    // LLM-natural pattern of writing items one heading-level under the
+    // array heading).
+    let sameDepthIdx = -1
+    let parentDepthIdx = -1
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const s = stack[i]
+      if (s.kind !== 'array') continue
+      if (sameDepthIdx === -1 && s.depth === headingDepth) sameDepthIdx = i
+      if (parentDepthIdx === -1 && s.depth === headingDepth - 1) {
+        parentDepthIdx = i
+      }
+    }
+    const targetIdx = sameDepthIdx !== -1 ? sameDepthIdx : parentDepthIdx
+    if (targetIdx === -1) {
+      throw parseError('Depth-qualified item has no matching array scope')
+    }
+    // Close any scopes nested inside the target array.
+    while (stack.length - 1 > targetIdx) popScope()
+    // Reuse the regular item handler with the target array on top.
+    onItem(text)
+  }
+
   function onItem(line) {
     const top = stack[stack.length - 1]
     if (top.kind !== 'array') throw parseError('Array item outside array scope')

package/src/serializer.js

@@ -29,6 +29,19 @@ export function* serializeLines(value, label = 'Document', frontmatter = null) {
   for (const ln of lines) yield ln + '\n'
 }
 
+// Mode markers attach directly to `#` in the root heading: `#- Order`,
+// `#? Order`, `#! Order`. Callers pass the mark as a `- `, `? ` or `! `
+// prefix on `label`; the serializer attaches it to `#` without a space
+// between them. Plain data documents (no prefix) emit `# Label`.
+function splitLabel(label) {
+  if (label.length >= 2
+      && (label[0] === '-' || label[0] === '?' || label[0] === '!')
+      && label[1] === ' ') {
+    return { mark: label[0], rest: label.slice(2) }
+  }
+  return { mark: '', rest: label }
+}
+
 function emitDocument(value, label, frontmatter, lines) {
   if (frontmatter && Object.keys(frontmatter).length > 0) {
     for (const [k, v] of Object.entries(frontmatter)) {
@@ -38,12 +51,15 @@ function emitDocument(value, label, frontmatter, lines) {
     lines.push('')
   }
 
+  const { mark, rest } = splitLabel(label)
+  const prefix = '#' + mark + ' '
+
   if (Array.isArray(value)) {
-    const head = label === '[]' ? '# []' : '# ' + label + '[]'
+    const head = rest === '[]' ? prefix + '[]' : prefix + rest + '[]'
     lines.push(head)
     writeArrayItems(value, lines, 1)
   } else if (value !== null && typeof value === 'object') {
-    lines.push('# ' + label)
+    lines.push(prefix + rest)
     writeObjectFields(value, lines, 1)
   } else {
     throw new TypeError('Root value must be an object or array')