yaml 2.9.0: Merge YAML mapping keys with merge option and schema yaml-1.1 using parse and parseDocument

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: Merge YAML mapping keys with merge option and schema yaml-1.1 using parse and parseDocument
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/yaml@2.9.0
Demonstrate these symbols/APIs:
  - Document
  - parse
  - parseDocument

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:fb8133f494a455e9ad1d4049489ee71f50617ac336105ff238598b9c2af1728b","contract":["assert YAML.parse with merge option resolves single mapping merge key \u003c\u003c from referenced anchor","assert YAML.parse with merge option overrides merged anchor keys with explicitly defined mapping keys","assert YAML.parse supports sequence of merge keys with earlier mappings taking precedence over later ones","assert YAML.parseDocument with merge option or yaml-1.1 schema parses merge keys into AST and resolves them in Document.toJS","assert YAML.parseDocument preserves merge key AST structure in Document.toString serialization","assert Document.toJS throws an error when a merge key references a non-mapping scalar or non-mapping sequence item"],"goal":"Merge YAML mapping keys with merge option and schema yaml-1.1 using parse and parseDocument","kind":"HOW","packages":["pkg:npm/yaml@2.9.0"],"schemaVersion":1,"symbols":["Document","parse","parseDocument"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/yaml@2.9.0"],"schemaVersion":1,"subject":"pkg:npm/yaml@2.9.0","symbols":["Document","parse","parseDocument"],"verifierAdapter":"node-typescript@1"}

import YAML from 'yaml';

/**
 * Parse a YAML string with merge keys enabled.
 * @param {string} text
 * @param {import('yaml').ParseOptions} [options]
 * @returns {any}
 */
export function parseWithMerge(text, options = {}) {
  return YAML.parse(text, { merge: true, ...options });
}

/**
 * Parse a YAML string into a Document AST with merge key support.
 * @param {string} text
 * @param {import('yaml').DocumentOptions & import('yaml').SchemaOptions & import('yaml').ParseOptions} [options]
 * @returns {YAML.Document}
 */
export function parseDocWithMerge(text, options = {}) {
  return YAML.parseDocument(text, { merge: true, ...options });
}

/**
 * Convert a Document AST to JS object with merge keys resolved.
 * @param {YAML.Document} doc
 * @param {import('yaml').ToJSOptions} [options]
 * @returns {any}
 */
export function documentToJS(doc, options = {}) {
  return doc.toJS(options);
}

/**
 * Stringify a Document AST preserving YAML formatting.
 * @param {YAML.Document} doc
 * @param {import('yaml').ToStringOptions} [options]
 * @returns {string}
 */
export function stringifyDoc(doc, options = {}) {
  return doc.toString(options);
}

{
  "name": "sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample",
      "version": "1.0.0",
      "dependencies": {
        "yaml": "2.9.0"
      }
    },
    "node_modules/yaml": {
      "version": "2.9.0",
      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="
    }
  }
}

{
  "name": "sample",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "yaml": "2.9.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "Merge YAML mapping keys with merge option and schema yaml-1.1 using parse and parseDocument",
  "kind": "HOW",
  "packages": [
    "pkg:npm/yaml@2.9.0"
  ],
  "symbols": [
    "Document",
    "parse",
    "parseDocument"
  ]
}

import assert from 'node:assert/strict';
import YAML from 'yaml';
import {
  parseWithMerge,
  parseDocWithMerge,
  documentToJS,
  stringifyDoc
} from '../index.mjs';

// 1. assert YAML.parse with merge option resolves single mapping merge key << from referenced anchor
{
  const yamlText = `
base: &base_config
  host: localhost
  port: 8080
  timeout: 30

service:
  <<: *base_config
  name: api-server
`;
  const result = parseWithMerge(yamlText);
  assert.equal(result.service.host, 'localhost');
  assert.equal(result.service.port, 8080);
  assert.equal(result.service.timeout, 30);
  assert.equal(result.service.name, 'api-server');
}

// 2. assert YAML.parse with merge option overrides merged anchor keys with explicitly defined mapping keys
{
  const yamlText = `
defaults: &default_env
  NODE_ENV: production
  LOG_LEVEL: info
  PORT: 3000

custom_service:
  <<: *default_env
  LOG_LEVEL: debug
  PORT: 8080
`;
  const result = parseWithMerge(yamlText);
  assert.equal(result.custom_service.NODE_ENV, 'production');
  assert.equal(result.custom_service.LOG_LEVEL, 'debug');
  assert.equal(result.custom_service.PORT, 8080);
}

// 3. assert YAML.parse supports sequence of merge keys with earlier mappings taking precedence over later ones
{
  const yamlText = `
primary: &primary_map
  timeout: 5000
  retries: 3
  driver: sqlite

fallback: &fallback_map
  timeout: 10000
  retries: 1
  cache: redis

client:
  <<: [ *primary_map, *fallback_map ]
  name: test-client
`;
  const result = parseWithMerge(yamlText);
  assert.equal(result.client.timeout, 5000);
  assert.equal(result.client.retries, 3);
  assert.equal(result.client.driver, 'sqlite');
  assert.equal(result.client.cache, 'redis');
  assert.equal(result.client.name, 'test-client');
}

// 4. assert YAML.parseDocument with merge option or yaml-1.1 schema parses merge keys into AST and resolves them in Document.toJS
{
  const yamlText = `
db_base: &db_base
  adapter: postgres
  pool: 10

production:
  <<: *db_base
  database: prod_db
`;
  // Test with merge: true option
  const doc = parseDocWithMerge(yamlText);
  assert.ok(doc instanceof YAML.Document);
  assert.equal(doc.errors.length, 0);

  const jsFromDoc = documentToJS(doc);
  assert.deepEqual(jsFromDoc.production, {
    adapter: 'postgres',
    pool: 10,
    database: 'prod_db'
  });

  // Test with schema: 'yaml-1.1'
  const doc11 = YAML.parseDocument(yamlText, { schema: 'yaml-1.1' });
  const js11 = doc11.toJS();
  assert.deepEqual(js11.production, {
    adapter: 'postgres',
    pool: 10,
    database: 'prod_db'
  });
}

// 5. assert YAML.parseDocument preserves merge key AST structure in Document.toString serialization
{
  const yamlText = `base: &base
  host: 127.0.0.1
  port: 80
app:
  <<: *base
  port: 443
`;
  const doc = parseDocWithMerge(yamlText);
  const serialized = stringifyDoc(doc);
  assert.ok(serialized.includes('&base'));
  assert.ok(serialized.includes('<<: *base'));
  assert.ok(serialized.includes('port: 443'));
}

// 6. assert Document.toJS throws an error when a merge key references a non-mapping scalar or non-mapping sequence item
{
  const invalidMergeScalar = `
anchor: &scalar_anchor not_a_map
target:
  <<: *scalar_anchor
`;
  const docScalar = parseDocWithMerge(invalidMergeScalar);
  assert.throws(() => {
    docScalar.toJS();
  }, /Merge sources must be maps or map aliases/);

  const invalidMergeSeq = `
anchor: &scalar_item invalid
target:
  <<: [ *scalar_item ]
`;
  const docSeq = parseDocWithMerge(invalidMergeSeq);
  assert.throws(() => {
    docSeq.toJS();
  }, /Merge sources must be maps or map aliases/);
}

console.log('PASS: all contract assertions satisfied');