postcss-value-parser 4.2.0: parse CSS values, walk AST nodes to transform url and function calls, and parse units with unit helper

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 CSS values, walk AST nodes to transform url and function calls, and parse units with unit helper
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/postcss-value-parser@4.2.0
Demonstrate these symbols/APIs:
  - postcss-value-parser
  - postcss-value-parser.stringify
  - postcss-value-parser.unit
  - postcss-value-parser.walk

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:bd0111b360b310bb961d8ec9d69191d718c11b47e903eb93a699f6465718561b","contract":["valueParser(value) parses CSS value strings into an AST with top-level and nested nodes","valueParser.unit(value) extracts numeric quantity and unit suffix from CSS dimension strings","valueParser.unit(value) returns false for non-numeric or unparseable input","valueParser.walk(nodes, callback) traverses AST nodes recursively in top-down order","valueParser.walk(nodes, callback) stops descending into child nodes when callback returns false","valueParser.walk(nodes, callback, true) traverses AST nodes in bottom-up order when bubble is true","valueParser.stringify(nodes) converts AST nodes back into a CSS string representation","valueParser.stringify(nodes, custom) transforms serialized output using a custom node replacer function"],"goal":"parse CSS values, walk AST nodes to transform url and function calls, and parse units with unit helper","kind":"HOW","packages":["pkg:npm/postcss-value-parser@4.2.0"],"schemaVersion":1,"symbols":["postcss-value-parser","postcss-value-parser.stringify","postcss-value-parser.unit","postcss-value-parser.walk"]},"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","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/postcss-value-parser@4.2.0"],"schemaVersion":1,"subject":"pkg:npm/postcss-value-parser@4.2.0","symbols":["postcss-value-parser","postcss-value-parser.stringify","postcss-value-parser.unit","postcss-value-parser.walk"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-postcss-value-parser",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-postcss-value-parser",
      "version": "1.0.0",
      "dependencies": {
        "postcss-value-parser": "4.2.0"
      }
    },
    "node_modules/postcss-value-parser": {
      "version": "4.2.0",
      "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz",
      "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-postcss-value-parser",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for postcss-value-parser",
  "main": "src/index.js",
  "dependencies": {
    "postcss-value-parser": "4.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "parse CSS values, walk AST nodes to transform url and function calls, and parse units with unit helper",
  "kind": "HOW",
  "packages": [
    "pkg:npm/postcss-value-parser@4.2.0"
  ],
  "symbols": [
    "postcss-value-parser",
    "postcss-value-parser.stringify",
    "postcss-value-parser.unit",
    "postcss-value-parser.walk"
  ]
}

const valueParser = require('postcss-value-parser');

/**
 * Parse a CSS value string into an AST.
 * @param {string} value - CSS value string
 * @returns {object} Parsed ValueParser instance
 */
function parseValue(value) {
  return valueParser(value);
}

/**
 * Parse a CSS dimension string into number and unit.
 * @param {string} value - Dimension string, e.g. "10px"
 * @returns {{ number: string, unit: string } | false} Parsed unit object or false
 */
function parseUnit(value) {
  return valueParser.unit(value);
}

/**
 * Walk AST nodes with a callback function.
 * @param {Array<object>} nodes - AST nodes array
 * @param {Function} callback - Traversal callback
 * @param {boolean} [bubble=false] - Whether to bubble up
 */
function walkNodes(nodes, callback, bubble = false) {
  valueParser.walk(nodes, callback, bubble);
}

/**
 * Stringify AST nodes back to a CSS string.
 * @param {Array<object>|object} nodes - AST nodes
 * @param {Function} [custom] - Custom stringifier callback
 * @returns {string} Stringified CSS value
 */
function stringifyNodes(nodes, custom) {
  return valueParser.stringify(nodes, custom);
}

module.exports = {
  valueParser,
  parseValue,
  parseUnit,
  walkNodes,
  stringifyNodes
};

const assert = require('node:assert');
const valueParser = require('postcss-value-parser');
const { parseValue, parseUnit, walkNodes, stringifyNodes } = require('../src/index.js');

// 1. valueParser(value) parses CSS value strings into an AST with top-level and nested nodes
const parsed1 = valueParser('rgba(255, 0, 0, 0.8) 10px url("bg.png")');
assert.strictEqual(typeof parsed1, 'object');
assert.ok(Array.isArray(parsed1.nodes));
assert.strictEqual(parsed1.nodes.length, 5);
assert.strictEqual(parsed1.nodes[0].type, 'function');
assert.strictEqual(parsed1.nodes[0].value, 'rgba');
assert.strictEqual(parsed1.nodes[0].nodes.length, 7);
assert.strictEqual(parsed1.nodes[1].type, 'space');
assert.strictEqual(parsed1.nodes[2].type, 'word');
assert.strictEqual(parsed1.nodes[2].value, '10px');
assert.strictEqual(parsed1.nodes[3].type, 'space');
assert.strictEqual(parsed1.nodes[4].type, 'function');
assert.strictEqual(parsed1.nodes[4].value, 'url');

const helperParsed = parseValue('100%');
assert.strictEqual(helperParsed.nodes[0].type, 'word');
assert.strictEqual(helperParsed.nodes[0].value, '100%');

// 2. valueParser.unit(value) extracts numeric quantity and unit suffix from CSS dimension strings
const u1 = valueParser.unit('10px');
assert.deepStrictEqual(u1, { number: '10', unit: 'px' });

const u2 = valueParser.unit('1.5rem');
assert.deepStrictEqual(u2, { number: '1.5', unit: 'rem' });

const u3 = valueParser.unit('-20%');
assert.deepStrictEqual(u3, { number: '-20', unit: '%' });

const u4 = valueParser.unit('+100');
assert.deepStrictEqual(u4, { number: '+100', unit: '' });

const u5 = parseUnit('.5em');
assert.deepStrictEqual(u5, { number: '.5', unit: 'em' });

// 3. valueParser.unit(value) returns false for non-numeric or unparseable input
assert.strictEqual(valueParser.unit('auto'), false);
assert.strictEqual(valueParser.unit('inherit'), false);
assert.strictEqual(valueParser.unit(''), false);
assert.strictEqual(parseUnit('calc'), false);

// 4. valueParser.walk(nodes, callback) traverses AST nodes recursively in top-down order
const parsedWalk = valueParser('calc(10px + 20px) url("test.png")');
const visited = [];
valueParser.walk(parsedWalk.nodes, (node) => {
  visited.push({ type: node.type, value: node.value });
});
assert.strictEqual(visited[0].type, 'function');
assert.strictEqual(visited[0].value, 'calc');
assert.strictEqual(visited[1].type, 'word');
assert.strictEqual(visited[1].value, '10px');

// 5. valueParser.walk(nodes, callback) stops descending into child nodes when callback returns false
const topLevelOnly = [];
walkNodes(parsedWalk.nodes, (node) => {
  topLevelOnly.push(node.value);
  if (node.type === 'function') {
    return false;
  }
});
assert.deepStrictEqual(topLevelOnly, ['calc', ' ', 'url']);

// 6. valueParser.walk(nodes, callback, true) traverses AST nodes in bottom-up order when bubble is true
const bubbleVisited = [];
valueParser.walk(
  valueParser('fn(arg)').nodes,
  (node) => {
    bubbleVisited.push(node.value);
  },
  true
);
assert.strictEqual(bubbleVisited[0], 'arg');
assert.strictEqual(bubbleVisited[1], 'fn');

// 7. valueParser.stringify(nodes) converts AST nodes back into a CSS string representation
const parsedStringify = valueParser('calc(10px + 20px)');
assert.strictEqual(valueParser.stringify(parsedStringify.nodes), 'calc(10px + 20px)');
assert.strictEqual(stringifyNodes(parsedStringify.nodes), 'calc(10px + 20px)');
assert.strictEqual(parsedStringify.toString(), 'calc(10px + 20px)');

// 8. valueParser.stringify(nodes, custom) transforms serialized output using a custom node replacer function
const parsedCustom = valueParser('linear-gradient(to bottom, red 0%, blue 100%)');
const modifiedString = valueParser.stringify(parsedCustom.nodes, (node) => {
  if (node.type === 'word' && node.value === 'red') {
    return 'green';
  }
  if (node.type === 'word' && node.value === 'blue') {
    return 'yellow';
  }
});
assert.strictEqual(
  modifiedString,
  'linear-gradient(to bottom, green 0%, yellow 100%)'
);

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