builder-util-runtime 9.7.0: XElement

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.XElement 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.XElement
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:d9a58e6953ade35313b71042c242d79fa0468a7bd217fce33e70a68ccae7b3cc","constraints":{"executionContext":"node"},"contract":["assert XElement instantiates with valid tag name, empty value, and null attributes and elements","assert XElement constructor throws ERR_XML_ELEMENT_NAME_EMPTY when name is empty","assert XElement constructor throws ERR_XML_ELEMENT_INVALID_NAME when name starts with invalid character","assert attribute retrieval returns string value or throws ERR_XML_MISSED_ATTRIBUTE when missing","assert element and elementOrNull query child elements with optional case insensitivity","assert getElements returns matching child elements or empty array","assert elementValueOrEmpty returns child element text or empty string","assert parseXml parses XML document into XElement tree structure"],"goal":"verify builder-util-runtime.XElement 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.XElement"]},"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.XElement"],"verifierAdapter":"node-typescript@1"}

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

/**
 * Creates a new XElement with optional attributes and value.
 * @param {string} name - XML element tag name.
 * @param {Record<string, string>} [attributes] - Optional attributes object.
 * @param {string} [value] - Optional text value.
 * @returns {XElement}
 */
export function createElement(name, attributes = null, value = '') {
  const el = new XElement(name);
  if (attributes !== null) {
    el.attributes = { ...attributes };
  }
  if (value) {
    el.value = value;
  }
  return el;
}

/**
 * Appends a child XElement to a parent XElement.
 * @param {XElement} parent - Parent element.
 * @param {XElement} child - Child element to add.
 * @returns {XElement} The parent element.
 */
export function appendChild(parent, child) {
  if (parent.elements === null) {
    parent.elements = [];
  }
  parent.elements.push(child);
  return parent;
}

/**
 * Parses XML string into an XElement root.
 * @param {string} xml - XML document string.
 * @returns {XElement}
 */
export function parseXmlElement(xml) {
  return parseXml(xml);
}

export { XElement, parseXml };

{
  "name": "builder-util-runtime-xelement-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "builder-util-runtime-xelement-sample",
      "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": "builder-util-runtime-xelement-sample",
  "version": "1.0.0",
  "description": "Demonstrate builder-util-runtime.XElement usage and XML tree manipulation",
  "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.XElement in pkg:npm/builder-util-runtime@9.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/builder-util-runtime@9.7.0"
  ],
  "symbols": [
    "builder-util-runtime.XElement"
  ],
  "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 { XElement, parseXml } from 'builder-util-runtime';
import { createElement, appendChild, parseXmlElement } from '../index.mjs';

// 1. assert XElement instantiates with valid tag name, empty value, and null attributes and elements
{
  const el = createElement('configuration');
  assert.ok(el instanceof XElement, 'Must be instance of XElement');
  assert.equal(el.name, 'configuration', 'Name must match initialized value');
  assert.equal(el.value, '', 'Default value must be empty string');
  assert.equal(el.attributes, null, 'Default attributes must be null');
  assert.equal(el.elements, null, 'Default elements must be null');
  assert.equal(el.isCData, false, 'Default isCData must be false');
}

// 2. assert XElement constructor throws ERR_XML_ELEMENT_NAME_EMPTY when name is empty
{
  assert.throws(
    () => new XElement(''),
    (err) => {
      assert.ok(err instanceof Error);
      assert.equal(err.code, 'ERR_XML_ELEMENT_NAME_EMPTY');
      return true;
    },
    'Should throw ERR_XML_ELEMENT_NAME_EMPTY for empty tag name'
  );
}

// 3. assert XElement constructor throws ERR_XML_ELEMENT_INVALID_NAME when name starts with invalid character
{
  assert.throws(
    () => new XElement('123invalid'),
    (err) => {
      assert.ok(err instanceof Error);
      assert.equal(err.code, 'ERR_XML_ELEMENT_INVALID_NAME');
      return true;
    },
    'Should throw ERR_XML_ELEMENT_INVALID_NAME for tag name starting with a digit'
  );
}

// 4. assert attribute retrieval returns string value or throws ERR_XML_MISSED_ATTRIBUTE when missing
{
  const el = createElement('package', { id: 'sample-app', version: '1.2.3' });
  assert.equal(el.attribute('id'), 'sample-app', 'Should return attribute value');
  assert.equal(el.attribute('version'), '1.2.3', 'Should return attribute value');

  assert.throws(
    () => el.attribute('nonexistent'),
    (err) => {
      assert.ok(err instanceof Error);
      assert.equal(err.code, 'ERR_XML_MISSED_ATTRIBUTE');
      return true;
    },
    'Should throw ERR_XML_MISSED_ATTRIBUTE when attribute is missing'
  );

  el.removeAttribute('version');
  assert.equal(el.attributes.version, undefined, 'Attribute should be removed');
  assert.throws(
    () => el.attribute('version'),
    (err) => {
      assert.ok(err instanceof Error);
      assert.equal(err.code, 'ERR_XML_MISSED_ATTRIBUTE');
      return true;
    },
    'Should throw ERR_XML_MISSED_ATTRIBUTE after removal'
  );
}

// 5. assert element and elementOrNull query child elements with optional case insensitivity
{
  const root = createElement('root');
  const child = createElement('targetComponent', null, 'active');
  appendChild(root, child);

  assert.equal(root.element('targetComponent'), child, 'Should return matching child element');
  assert.equal(root.element('TARGETCOMPONENT', true), child, 'Should find child element ignoring case');
  assert.equal(root.elementOrNull('targetComponent'), child, 'elementOrNull should return child');
  assert.equal(root.elementOrNull('missing'), null, 'elementOrNull should return null for missing child');

  assert.throws(
    () => root.element('missing'),
    (err) => {
      assert.ok(err instanceof Error);
      assert.equal(err.code, 'ERR_XML_MISSED_ELEMENT');
      return true;
    },
    'Should throw ERR_XML_MISSED_ELEMENT when child is missing'
  );
}

// 6. assert getElements returns matching child elements or empty array
{
  const parent = createElement('group');
  assert.deepEqual(parent.getElements('item'), [], 'Should return empty array when elements is null');

  const item1 = createElement('item', { id: '1' });
  const item2 = createElement('ITEM', { id: '2' });
  const other = createElement('other', { id: '3' });

  appendChild(parent, item1);
  appendChild(parent, item2);
  appendChild(parent, other);

  const exactMatches = parent.getElements('item');
  assert.equal(exactMatches.length, 1, 'Exact match should return 1 element');
  assert.equal(exactMatches[0], item1);

  const caseInsensitiveMatches = parent.getElements('item', true);
  assert.equal(caseInsensitiveMatches.length, 2, 'Case-insensitive match should return 2 elements');
  assert.equal(caseInsensitiveMatches[0], item1);
  assert.equal(caseInsensitiveMatches[1], item2);
}

// 7. assert elementValueOrEmpty returns child element text or empty string
{
  const container = createElement('settings');
  assert.equal(container.elementValueOrEmpty('timeout'), '', 'Should return empty string for non-existent child');

  const timeout = createElement('timeout', null, '5000');
  appendChild(container, timeout);
  assert.equal(container.elementValueOrEmpty('timeout'), '5000', 'Should return child element value');
  assert.equal(container.elementValueOrEmpty('TIMEOUT', true), '5000', 'Should return child element value ignoring case');
}

// 8. assert parseXml parses XML document into XElement tree structure
{
  const xmlString = '<app id="testApp"><title>CodeSampleX</title><version>1.0.0</version></app>';
  const doc = parseXmlElement(xmlString);

  assert.ok(doc instanceof XElement, 'Parsed root should be an XElement');
  assert.equal(doc.name, 'app');
  assert.equal(doc.attribute('id'), 'testApp');
  assert.equal(doc.elementValueOrEmpty('title'), 'CodeSampleX');
  assert.equal(doc.elementValueOrEmpty('version'), '1.0.0');
}

console.log('All contract assertions verified successfully.');