fix(yaml): resolve empty props blocks instead of throwing (#324)

Co-authored-by: Farnabaz <farnabaz@gmail.com>

Author: adamdehaven

packages/comark/src/internal/frontmatter.ts

@@ -19,7 +19,7 @@ export function parseFrontmatter(content: string) {
       const hasCarriageReturn = content[idx - 1] === CR
       frontmatter = content.slice(4, idx - (hasCarriageReturn ? 1 : 0))
       if (frontmatter) {
-        data = parseYaml(frontmatter)
+        data = parseYaml(frontmatter) ?? {}
         content = content.slice(idx + 4 + (hasCarriageReturn ? 1 : 0))
       }
     }

packages/comark/src/internal/yaml.ts

@@ -1,12 +1,18 @@
-import { dump, JSON_SCHEMA, load, type DumpOptions } from 'js-yaml'
+import { dump, JSON_SCHEMA, loadAll, YAMLException, type DumpOptions } from 'js-yaml'
 
 /**
- * Parse YAML content
+ * Parse YAML content.
+ *
  * @param content - The content to parse
- * @returns The parsed data
+ * @returns The parsed data, or `undefined` when the content has no YAML document
  */
-export function parseYaml(content: string): Record<string, unknown> {
-  return load(content, { schema: JSON_SCHEMA }) as Record<string, unknown>
+export function parseYaml(content: string): Record<string, unknown> | undefined {
+  const documents = loadAll(content, { schema: JSON_SCHEMA }) as Record<string, unknown>[]
+  // Preserve `load()`'s single-document guard rather than silently taking the first.
+  if (documents.length > 1) {
+    throw new YAMLException('expected a single document in the stream, but found more')
+  }
+  return documents[0]
 }
 
 /**

packages/comark/test/empty-props.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { parse } from '../src/index'
+import type { ComarkNode } from 'comark'
+
+// Helper to check if a node is an element with a specific tag
+function isElement(node: ComarkNode, tag: string): boolean {
+  return Array.isArray(node) && node[0] === tag
+}
+
+// Helper to get the attrs object of an element
+function getAttrs(node: ComarkNode): Record<string, unknown> {
+  return Array.isArray(node) ? ((node[1] as Record<string, unknown>) ?? {}) : {}
+}
+
+describe('empty component props block (#319)', () => {
+  it('parses an empty props block without throwing', async () => {
+    const result = await parse('::page-section\n---\n---\n#title\nHello\n::')
+    const section = result.nodes[0] as ComarkNode
+
+    expect(isElement(section, 'page-section')).toBe(true)
+    // No YAML-derived keys should be present on the props object
+    const attrs = getAttrs(section)
+    const yamlKeys = Object.keys(attrs).filter((key) => key !== '$')
+    expect(yamlKeys).toHaveLength(0)
+  })
+
+  it('preserves slot content when the props block is empty', async () => {
+    const result = await parse('::page-section\n---\n---\n#title\nHello\n::')
+    const md = JSON.stringify(result.nodes)
+    expect(md).toContain('Hello')
+  })
+
+  it('parses a whitespace-only props block without throwing', async () => {
+    const result = await parse('::hero\n---\n   \n---\ncontent\n::')
+    const hero = result.nodes[0] as ComarkNode
+
+    expect(isElement(hero, 'hero')).toBe(true)
+    expect(JSON.stringify(result.nodes)).toContain('content')
+  })
+
+  it('parses a comment-only props block without throwing', async () => {
+    const result = await parse('::hero\n---\n# todo\n---\ncontent\n::')
+    const hero = result.nodes[0] as ComarkNode
+
+    expect(isElement(hero, 'hero')).toBe(true)
+    const attrs = getAttrs(hero)
+    const yamlKeys = Object.keys(attrs).filter((key) => key !== '$')
+    expect(yamlKeys).toHaveLength(0)
+  })
+
+  it('still applies props from a non-empty props block', async () => {
+    const result = await parse('::hero\n---\ntitle: x\n---\n#title\nHi\n::')
+    const hero = result.nodes[0] as ComarkNode
+
+    expect(isElement(hero, 'hero')).toBe(true)
+    expect(getAttrs(hero).title).toBe('x')
+  })
+
+  it('round-trips a multi-key, typed props block', async () => {
+    const result = await parse('::hero\n---\ncount: 3\nlabel: hello\n---\ncontent\n::')
+    const hero = result.nodes[0] as ComarkNode
+
+    expect(isElement(hero, 'hero')).toBe(true)
+    // Non-string attribute values are JSON-stringified onto the element (see syntax.ts)
+    expect(getAttrs(hero).count).toBe('3')
+    expect(getAttrs(hero).label).toBe('hello')
+  })
+
+  it('parses document-level comment-only frontmatter without throwing', async () => {
+    const result = await parse('---\n# comment only\n---\n\n# Heading')
+
+    const hasHeading = result.nodes.some((node) => isElement(node, 'h1'))
+    expect(hasHeading).toBe(true)
+  })
+
+  it('rejects a malformed (non-empty, invalid) props block', async () => {
+    await expect(parse('::hero\n---\nfoo: [1,2\n---\ncontent\n::')).rejects.toThrow()
+  })
+})

packages/comark/test/frontmatter.test.ts

@@ -107,6 +107,33 @@ Content`
     expect(result.content).toBe(input)
   })
 
+  it('should handle comment-only frontmatter without throwing', () => {
+    const input = `---
+# no metadata yet
+---
+
+Content`
+    const result = parseFrontmatter(input)
+    expect(result.data).toEqual({})
+    expect(result.content.trim()).toBe('Content')
+  })
+
+  it('should handle whitespace-only frontmatter without throwing', () => {
+    const input = '---\n   \n---\n\nContent'
+    const result = parseFrontmatter(input)
+    expect(result.data).toEqual({})
+    expect(result.content.trim()).toBe('Content')
+  })
+
+  it('should still throw for malformed YAML in frontmatter', () => {
+    const input = `---
+foo: [1,2
+---
+
+Content`
+    expect(() => parseFrontmatter(input)).toThrow()
+  })
+
   it('should handle frontmatter with special characters', () => {
     const input = `---
 title: "Hello: World"

packages/comark/test/yaml.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { parseYaml } from '../src/internal/yaml'
+
+describe('parseYaml', () => {
+  describe('empty documents resolve to undefined', () => {
+    it('returns undefined for an empty string', () => {
+      expect(parseYaml('')).toBeUndefined()
+    })
+
+    it('returns undefined for spaces only', () => {
+      expect(parseYaml('   ')).toBeUndefined()
+    })
+
+    it('returns undefined for a tab', () => {
+      expect(parseYaml('\t')).toBeUndefined()
+    })
+
+    it('returns undefined for mixed whitespace', () => {
+      expect(parseYaml('\t\n ')).toBeUndefined()
+    })
+
+    it('returns undefined for newlines only', () => {
+      expect(parseYaml('\n\n')).toBeUndefined()
+    })
+
+    it('returns undefined for a single comment line', () => {
+      expect(parseYaml('# only a comment')).toBeUndefined()
+    })
+
+    it('returns undefined for multiple comment lines', () => {
+      expect(parseYaml('# first comment\n# second comment\n')).toBeUndefined()
+    })
+  })
+
+  describe('valid YAML parses normally', () => {
+    it('parses a flat mapping', () => {
+      expect(parseYaml('a: 1\nb: two')).toEqual({ a: 1, b: 'two' })
+    })
+
+    it('parses nested objects and arrays', () => {
+      const yaml = `title: Nested
+meta:
+  description: A description
+  keywords:
+    - one
+    - two`
+      expect(parseYaml(yaml)).toEqual({
+        title: 'Nested',
+        meta: {
+          description: 'A description',
+          keywords: ['one', 'two'],
+        },
+      })
+    })
+  })
+
+  describe('falsy scalar documents are preserved, not coerced', () => {
+    it('returns the number 0 for a bare "0" document', () => {
+      expect(parseYaml('0')).toBe(0)
+    })
+
+    it('returns false for a bare "false" document', () => {
+      expect(parseYaml('false')).toBe(false)
+    })
+
+    it('returns null for a bare "null" document', () => {
+      expect(parseYaml('null')).toBeNull()
+    })
+  })
+
+  describe('malformed YAML still throws', () => {
+    it('throws on an unterminated flow sequence', () => {
+      expect(() => parseYaml('foo: [1,2')).toThrow()
+    })
+
+    it('throws on a structural indentation error', () => {
+      expect(() =>
+        parseYaml(`foo:
+  bar: 1
+ baz: 2`)
+      ).toThrow()
+    })
+
+    it('throws when the input contains more than one document', () => {
+      expect(() => parseYaml('x: 1\n---\ny: 2')).toThrow()
+    })
+  })
+})

test/bundle.test.ts

@@ -67,7 +67,7 @@ describe('package bundle size', { timeout: 60_000 }, () => {
         "@comark/react": "47.8k (68 files)",
         "@comark/svelte": "47.6k (76 files)",
         "@comark/vue": "63.3k (68 files)",
-        "comark": "374k (136 files)",
+        "comark": "375k (136 files)",
       }
     `)
   })