symbol-tree 3.2.4

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 pkg:npm/symbol-tree@3.2.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/symbol-tree@3.2.4
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - 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:28e0919ac84bcb458685f46dd3d9caa23a9436aceffdbed8787e0bb5bb0481ae","constraints":{"executionContext":"node"},"contract":["SymbolTree instantiates and manages tree relations on objects using Symbol properties","appendChild, prependChild, insertBefore, and insertAfter manipulate node hierarchy and sibling pointers","childrenToArray, ancestorsToArray, and treeToArray serialize tree structures in traversal order","childrenIterator iterates over child elements in sequence","compareTreePosition computes relative tree position flags according to DOM tree order","remove unlinks an object from its parent and sibling chain updating adjacent references"],"goal":"verify pkg:npm/symbol-tree@3.2.4","kind":"HOW","packages":["pkg:npm/symbol-tree@3.2.4"],"schemaVersion":1},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/symbol-tree@3.2.4"],"schemaVersion":1,"subject":"pkg:npm/symbol-tree@3.2.4","verifierAdapter":"node-typescript@1"}

'use strict';

const SymbolTree = require('symbol-tree');

/**
 * Creates a new SymbolTree instance.
 * @param {string} [description] - Description for the underlying symbol.
 * @returns {SymbolTree} A new SymbolTree instance.
 */
function createTree(description) {
  return new SymbolTree(description);
}

/**
 * Appends multiple children to a parent object.
 * @param {SymbolTree} tree - The SymbolTree instance.
 * @param {Object} parent - The parent object.
 * @param {Object[]} children - Array of child objects.
 * @returns {Object} The parent object.
 */
function appendChildren(tree, parent, children) {
  for (const child of children) {
    tree.appendChild(parent, child);
  }
  return parent;
}

/**
 * Collects all descendant objects in tree order into an array.
 * @param {SymbolTree} tree - The SymbolTree instance.
 * @param {Object} root - The root object.
 * @returns {Object[]} Descendants including root in tree order.
 */
function collectTree(tree, root) {
  return tree.treeToArray(root);
}

module.exports = {
  SymbolTree,
  createTree,
  appendChildren,
  collectTree
};

{
  "name": "sample-symbol-tree",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-symbol-tree",
      "version": "1.0.0",
      "dependencies": {
        "symbol-tree": "3.2.4"
      }
    },
    "node_modules/symbol-tree": {
      "version": "3.2.4",
      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-symbol-tree",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of symbol-tree",
  "dependencies": {
    "symbol-tree": "3.2.4"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/symbol-tree@3.2.4",
  "kind": "HOW",
  "packages": [
    "pkg:npm/symbol-tree@3.2.4"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

'use strict';

const assert = require('node:assert/strict');
const SymbolTree = require('symbol-tree');
const { createTree, appendChildren, collectTree } = require('../index.cjs');

// 1. Instantiation and basic properties
assert.equal(typeof SymbolTree, 'function', 'SymbolTree must be a constructor function');
const tree = createTree('test-tree');
assert.ok(tree instanceof SymbolTree, 'createTree should return a SymbolTree instance');
assert.equal(typeof tree.symbol, 'symbol', 'tree.symbol must be a Symbol');

// 2. Tree construction: appendChild, prependChild, insertBefore, insertAfter
const root = { name: 'root' };
const childA = { name: 'childA' };
const childB = { name: 'childB' };
const childC = { name: 'childC' };
const childD = { name: 'childD' };

tree.appendChild(root, childB);
assert.equal(tree.hasChildren(root), true, 'root should have children');
assert.equal(tree.firstChild(root), childB, 'firstChild should be childB');
assert.equal(tree.lastChild(root), childB, 'lastChild should be childB');
assert.equal(tree.parent(childB), root, 'parent of childB should be root');

// Prepend childA before childB
tree.prependChild(root, childA);
assert.equal(tree.firstChild(root), childA, 'firstChild should now be childA');
assert.equal(tree.nextSibling(childA), childB, 'nextSibling of childA should be childB');
assert.equal(tree.previousSibling(childB), childA, 'previousSibling of childB should be childA');

// Insert childC after childB
tree.insertAfter(childB, childC);
assert.equal(tree.lastChild(root), childC, 'lastChild should now be childC');
assert.equal(tree.nextSibling(childB), childC, 'nextSibling of childB should be childC');
assert.equal(tree.previousSibling(childC), childB, 'previousSibling of childC should be childB');

// Insert childD before childC
tree.insertBefore(childC, childD);
assert.equal(tree.nextSibling(childB), childD, 'nextSibling of childB should be childD');
assert.equal(tree.nextSibling(childD), childC, 'nextSibling of childD should be childC');
assert.equal(tree.previousSibling(childC), childD, 'previousSibling of childC should be childD');

// Verify counts and indices
assert.equal(tree.childrenCount(root), 4, 'root should have 4 children');
assert.equal(tree.index(childA), 0, 'childA index should be 0');
assert.equal(tree.index(childB), 1, 'childB index should be 1');
assert.equal(tree.index(childD), 2, 'childD index should be 2');
assert.equal(tree.index(childC), 3, 'childC index should be 3');

// 3. Serialization and Array conversion
const children = tree.childrenToArray(root);
assert.deepEqual(children, [childA, childB, childD, childC], 'childrenToArray must match insertion order');

const subTree = { name: 'subTree' };
const leaf1 = { name: 'leaf1' };
const leaf2 = { name: 'leaf2' };
appendChildren(tree, subTree, [leaf1, leaf2]);
tree.appendChild(childA, subTree);

const allNodes = collectTree(tree, root);
assert.deepEqual(allNodes, [root, childA, subTree, leaf1, leaf2, childB, childD, childC], 'treeToArray must traverse in tree order');

const ancestorsOfLeaf = tree.ancestorsToArray(leaf1);
assert.deepEqual(ancestorsOfLeaf, [leaf1, subTree, childA, root], 'ancestorsToArray must traverse up to root');

// 4. Tree Iterator
const iteratedChildren = [];
for (const node of tree.childrenIterator(root)) {
  iteratedChildren.push(node);
}
assert.deepEqual(iteratedChildren, [childA, childB, childD, childC], 'childrenIterator must iterate over direct children');

// 5. Position comparison
const { TreePosition } = SymbolTree;
assert.ok(TreePosition, 'TreePosition constants must exist');
assert.equal(tree.compareTreePosition(root, childA), TreePosition.CONTAINED_BY | TreePosition.FOLLOWING, 'childA is contained by and follows root');
assert.equal(tree.compareTreePosition(childA, root), TreePosition.CONTAINS | TreePosition.PRECEDING, 'root contains and precedes childA');
assert.equal(tree.compareTreePosition(childA, childB), TreePosition.FOLLOWING, 'childB follows childA');
assert.equal(tree.compareTreePosition(childB, childA), TreePosition.PRECEDING, 'childA precedes childB');

const detached = { name: 'detached' };
assert.equal(tree.compareTreePosition(root, detached), TreePosition.DISCONNECTED, 'detached node must return DISCONNECTED');

// 6. Node removal
tree.remove(childB);
assert.equal(tree.childrenCount(root), 3, 'childrenCount should decrease after remove');
assert.equal(tree.nextSibling(childA), childD, 'nextSibling of childA should now be childD');
assert.equal(tree.previousSibling(childD), childA, 'previousSibling of childD should now be childA');
assert.equal(tree.parent(childB), null, 'removed node parent must be null');

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