parse5 8.0.1: parse HTML document to AST and serialize with parse5

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: parse HTML document to AST and serialize with parse5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/parse5@8.0.1
Demonstrate these symbols/APIs:
  - parse5.parse
  - parse5.serialize

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:09870cee554684b9147d6c651709a4d56e51d6d794135f18d25b639b9bab66a4","contract":["parse parses full HTML document into an AST with document, doctype, html, head, and body nodes","parse extracts element tag names, attributes, and child text nodes accurately","parse captures source code location info when sourceCodeLocationInfo option is enabled","serialize converts AST document nodes back into compliant HTML string representation","serialize reflects AST tree modifications such as updated attribute values and appended child nodes"],"goal":"parse HTML document to AST and serialize with parse5","kind":"HOW","packages":["pkg:npm/parse5@8.0.1"],"schemaVersion":1,"symbols":["parse5.parse","parse5.serialize"]},"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/parse5@8.0.1"],"schemaVersion":1,"subject":"pkg:npm/parse5@8.0.1","symbols":["parse5.parse","parse5.serialize"],"verifierAdapter":"node-typescript@1"}

import { parse, serialize } from 'parse5';

/**
 * Parses an HTML string into a parse5 Document AST.
 * @param {string} html - Raw HTML document string.
 * @param {object} [options] - Parser options.
 * @returns {object} parse5 Document node.
 */
export function parseHtml(html, options) {
  return parse(html, options);
}

/**
 * Serializes a parse5 AST node back into an HTML string.
 * @param {object} node - parse5 AST node.
 * @param {object} [options] - Serializer options.
 * @returns {string} Serialized HTML string.
 */
export function serializeHtml(node, options) {
  return serialize(node, options);
}

export { parse, serialize };

{
  "name": "sample-parse5",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-parse5",
      "version": "1.0.0",
      "dependencies": {
        "parse5": "8.0.1"
      }
    },
    "node_modules/entities": {
      "version": "8.0.0",
      "resolved": "https://registry.npmjs.org/entities/-/entities-8.0.0.tgz",
      "integrity": "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=20.19.0"
      },
      "funding": {
        "url": "https://github.com/fb55/entities?sponsor=1"
      }
    },
    "node_modules/parse5": {
      "version": "8.0.1",
      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
      "integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
      "license": "MIT",
      "dependencies": {
        "entities": "^8.0.0"
      },
      "funding": {
        "url": "https://github.com/inikulin/parse5?sponsor=1"
      }
    }
  }
}

{
  "name": "sample-parse5",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "Clean-room verification of parse5",
  "dependencies": {
    "parse5": "8.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "parse HTML document to AST and serialize with parse5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/parse5@8.0.1"
  ],
  "symbols": [
    "parse5.parse",
    "parse5.serialize"
  ]
}

import assert from 'node:assert/strict';
import { parse, serialize } from 'parse5';
import { parseHtml, serializeHtml } from '../index.mjs';

// 1. parse parses full HTML document into an AST with document, doctype, html, head, and body nodes
const docHtml = '<!DOCTYPE html><html><head><title>Page Title</title></head><body><h1>Hello</h1></body></html>';
const doc = parse(docHtml);

assert.equal(doc.nodeName, '#document');
assert.ok(Array.isArray(doc.childNodes));
assert.equal(doc.childNodes.length, 2);

const doctypeNode = doc.childNodes.find((n) => n.nodeName === '#documentType');
assert.ok(doctypeNode);
assert.equal(doctypeNode.name, 'html');

const htmlNode = doc.childNodes.find((n) => n.nodeName === 'html');
assert.ok(htmlNode);
assert.equal(htmlNode.tagName, 'html');

const headNode = htmlNode.childNodes.find((n) => n.nodeName === 'head');
assert.ok(headNode);
assert.equal(headNode.tagName, 'head');

const titleNode = headNode.childNodes.find((n) => n.nodeName === 'title');
assert.ok(titleNode);
assert.equal(titleNode.tagName, 'title');
assert.equal(titleNode.childNodes[0].value, 'Page Title');

const bodyNode = htmlNode.childNodes.find((n) => n.nodeName === 'body');
assert.ok(bodyNode);
assert.equal(bodyNode.tagName, 'body');

const h1Node = bodyNode.childNodes.find((n) => n.nodeName === 'h1');
assert.ok(h1Node);
assert.equal(h1Node.tagName, 'h1');
assert.equal(h1Node.childNodes[0].value, 'Hello');

// 2. parse extracts element tag names, attributes, and child text nodes accurately
const fragmentDoc = parseHtml('<html><head></head><body><div id="main" class="container active" data-role="wrapper"><p>Paragraph text</p></div></body></html>');
const body = fragmentDoc.childNodes.find((n) => n.nodeName === 'html').childNodes.find((n) => n.nodeName === 'body');
const div = body.childNodes.find((n) => n.nodeName === 'div');

assert.equal(div.tagName, 'div');
assert.deepEqual(div.attrs, [
  { name: 'id', value: 'main' },
  { name: 'class', value: 'container active' },
  { name: 'data-role', value: 'wrapper' }
]);
const p = div.childNodes.find((n) => n.nodeName === 'p');
assert.equal(p.tagName, 'p');
assert.equal(p.childNodes[0].nodeName, '#text');
assert.equal(p.childNodes[0].value, 'Paragraph text');

// 3. parse captures source code location info when sourceCodeLocationInfo option is enabled
const locatedDoc = parse('<div id="box">\n  <span>Content</span>\n</div>', { sourceCodeLocationInfo: true });
const locBody = locatedDoc.childNodes.find((n) => n.nodeName === 'html').childNodes.find((n) => n.nodeName === 'body');
const box = locBody.childNodes.find((n) => n.nodeName === 'div');

assert.ok(box.sourceCodeLocation);
assert.equal(box.sourceCodeLocation.startLine, 1);
assert.equal(box.sourceCodeLocation.startCol, 1);
assert.equal(box.sourceCodeLocation.startOffset, 0);
assert.ok(box.sourceCodeLocation.endOffset > 0);

// 4. serialize converts AST document nodes back into compliant HTML string representation
const serialized = serializeHtml(doc);
assert.equal(serialized, '<!DOCTYPE html><html><head><title>Page Title</title></head><body><h1>Hello</h1></body></html>');

// 5. serialize reflects AST tree modifications such as updated attribute values and appended child nodes
div.attrs = [{ name: 'id', value: 'updated-main' }];
const newSpan = {
  nodeName: 'span',
  tagName: 'span',
  attrs: [{ name: 'class', value: 'badge' }],
  namespaceURI: 'http://www.w3.org/1999/xhtml',
  childNodes: [
    {
      nodeName: '#text',
      value: 'New Badge',
      parentNode: null
    }
  ],
  parentNode: div
};
newSpan.childNodes[0].parentNode = newSpan;
div.childNodes.push(newSpan);

const modifiedSerialized = serialize(fragmentDoc);
assert.equal(
  modifiedSerialized,
  '<html><head></head><body><div id="updated-main"><p>Paragraph text</p><span class="badge">New Badge</span></div></body></html>'
);

console.log('Contract test passed successfully.');