builder-util-runtime 9.7.0: parseXml

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: verify builder-util-runtime.parseXml in pkg:npm/builder-util-runtime@9.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/builder-util-runtime@9.7.0
Demonstrate these symbols/APIs:
  - builder-util-runtime.parseXml
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:c82cf34ad50523bf22b084c51e5864967e05843f3a5f2354ea8318c4e94d8594","constraints":{"executionContext":"node"},"contract":["assert parseXml parses hierarchical XML elements and text values into XElement tree","assert parseXml reads attributes and throws ERR_XML_MISSED_ATTRIBUTE when attribute is missing","assert parseXml parses CDATA blocks and sets isCData to true","assert parseXml queries child elements with getElements and elementValueOrEmpty","assert parseXml throws ERR_XML_MISSED_ELEMENT when required element is missing"],"goal":"verify builder-util-runtime.parseXml in pkg:npm/builder-util-runtime@9.7.0","kind":"HOW","packages":["pkg:npm/builder-util-runtime@9.7.0"],"schemaVersion":1,"symbols":["builder-util-runtime.parseXml"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/builder-util-runtime@9.7.0"],"schemaVersion":1,"subject":"pkg:npm/builder-util-runtime@9.7.0","symbols":["builder-util-runtime.parseXml"],"verifierAdapter":"node-typescript@1"}

import { parseXml, XElement } from 'builder-util-runtime';

/**
 * Parses XML text into an XElement root.
 * @param {string} xmlString
 * @returns {XElement}
 */
export function parseXmlDocument(xmlString) {
  return parseXml(xmlString);
}

/**
 * Extracts a required attribute from an XElement.
 * @param {XElement} element
 * @param {string} attrName
 * @returns {string}
 */
export function getAttribute(element, attrName) {
  return element.attribute(attrName);
}

/**
 * Gets all child elements with the specified tag name.
 * @param {XElement} element
 * @param {string} tagName
 * @param {boolean} [ignoreCase=false]
 * @returns {XElement[]}
 */
export function findChildren(element, tagName, ignoreCase = false) {
  return element.getElements(tagName, ignoreCase);
}

export { parseXml, XElement };

{
  "name": "sample-builder-util-runtime-parsexml",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-builder-util-runtime-parsexml",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "builder-util-runtime": "9.7.0"
      }
    },
    "node_modules/builder-util-runtime": {
      "version": "9.7.0",
      "resolved": "https://registry.npmjs.org/builder-util-runtime/-/builder-util-runtime-9.7.0.tgz",
      "integrity": "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw==",
      "license": "MIT",
      "dependencies": {
        "debug": "^4.3.4",
        "sax": "^1.2.4"
      },
      "engines": {
        "node": ">=12.0.0"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/sax": {
      "version": "1.6.1",
      "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.1.tgz",
      "integrity": "sha512-42tBVwLWnaQvW5zc4HbZrTuWccECCZfBi92FDuwtqxasH+JbPB3/FOKb1m222K42R4WxuxzzMsTswfzgtSu64Q==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": ">=11.0.0"
      }
    }
  }
}

{
  "name": "sample-builder-util-runtime-parsexml",
  "version": "1.0.0",
  "description": "Demonstrate builder-util-runtime.parseXml usage and behavior",
  "main": "index.mjs",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "builder-util-runtime": "9.7.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify builder-util-runtime.parseXml in pkg:npm/builder-util-runtime@9.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/builder-util-runtime@9.7.0"
  ],
  "symbols": [
    "builder-util-runtime.parseXml"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import { parseXml, XElement } from 'builder-util-runtime';
import { parseXmlDocument, getAttribute, findChildren } from '../index.mjs';

// 1. assert parseXml parses hierarchical XML elements and text values into XElement tree
{
  const xml = '<root><title>My App</title><version>1.0.0</version></root>';
  const root = parseXmlDocument(xml);
  assert.ok(root instanceof XElement, 'root should be instance of XElement');
  assert.equal(root.name, 'root', 'root element name should match');
  assert.equal(root.element('title').value, 'My App', 'child element value should match');
  assert.equal(root.element('version').value, '1.0.0', 'child element value should match');
}

// 2. assert parseXml reads attributes and throws ERR_XML_MISSED_ATTRIBUTE when attribute is missing
{
  const xml = '<item id="item-42" category="book" empty="" />';
  const root = parseXml(xml);
  assert.equal(getAttribute(root, 'id'), 'item-42', 'attribute id should match');
  assert.equal(getAttribute(root, 'category'), 'book', 'attribute category should match');
  assert.equal(getAttribute(root, 'empty'), '', 'empty attribute should match empty string');
  assert.throws(
    () => getAttribute(root, 'nonexistent'),
    (err) => {
      assert.equal(err.code, 'ERR_XML_MISSED_ATTRIBUTE');
      return true;
    },
    'Missing attribute should throw ERR_XML_MISSED_ATTRIBUTE'
  );
}

// 3. assert parseXml parses CDATA blocks and sets isCData to true
{
  const xml = '<entry><content><![CDATA[<html><body>Hello & World</body></html>]]></content></entry>';
  const root = parseXml(xml);
  const content = root.element('content');
  assert.equal(content.isCData, true, 'isCData flag should be true');
  assert.equal(content.value, '<html><body>Hello & World</body></html>', 'CDATA content should match');
}

// 4. assert parseXml queries child elements with getElements and elementValueOrEmpty
{
  const xml = `
    <catalog>
      <book id="b1"><name>Book One</name></book>
      <book id="b2"><name>Book Two</name></book>
      <optional></optional>
    </catalog>
  `;
  const root = parseXml(xml);
  const books = findChildren(root, 'book');
  assert.equal(books.length, 2, 'Should find 2 book elements');
  assert.equal(books[0].attribute('id'), 'b1');
  assert.equal(books[0].element('name').value, 'Book One');
  assert.equal(books[1].attribute('id'), 'b2');
  assert.equal(books[1].element('name').value, 'Book Two');

  assert.equal(root.elementOrNull('nonexistent'), null, 'elementOrNull should return null for missing element');
  assert.equal(root.elementValueOrEmpty('nonexistent'), '', 'elementValueOrEmpty should return empty string for missing element');
  assert.equal(root.elementValueOrEmpty('optional'), '', 'elementValueOrEmpty should return empty string for empty element');
}

// 5. assert parseXml throws ERR_XML_MISSED_ELEMENT when required element is missing
{
  const xml = '<root><child>value</child></root>';
  const root = parseXml(xml);
  assert.throws(
    () => root.element('missingChild'),
    (err) => {
      assert.equal(err.code, 'ERR_XML_MISSED_ELEMENT');
      return true;
    },
    'Missing required element should throw ERR_XML_MISSED_ELEMENT'
  );
}

console.log('All contract tests passed.');