postcss 8.5.26: Container.insertBefore

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 postcss.Container.insertBefore in pkg:npm/postcss@8.5.26
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/postcss@8.5.26
Demonstrate these symbols/APIs:
  - postcss.Container.insertBefore

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:34c481ef688f48892a5e70c0a2d0edba67ea29d58707c17588e7d9c163cb677b","contract":["assert insertBefore inserts a Declaration node before a target Declaration and returns the container","assert insertBefore inserts a node before a numeric child index","assert insertBefore normalizes and inserts a plain declaration object","assert insertBefore normalizes and inserts raw CSS string declarations","assert insertBefore inserts multiple Node instances passed as an array","assert insertBefore reparents an existing node moved from another container","assert insertBefore inserts a Rule into a Root container before another Rule","assert insertDeclarationsBefore helper inserts multiple declaration items before target in sequence"],"goal":"verify postcss.Container.insertBefore in pkg:npm/postcss@8.5.26","kind":"HOW","packages":["pkg:npm/postcss@8.5.26"],"schemaVersion":1,"symbols":["postcss.Container.insertBefore"]},"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/postcss@8.5.26"],"schemaVersion":1,"subject":"pkg:npm/postcss@8.5.26","symbols":["postcss.Container.insertBefore"],"verifierAdapter":"node-typescript@1"}

import postcss from 'postcss';

/**
 * Inserts a new node or specification before an existing child node or index in a PostCSS Container.
 *
 * @param {import('postcss').Container} container - The PostCSS container (Root, Rule, AtRule).
 * @param {import('postcss').ChildNode | number} exist - The child node or child index to insert before.
 * @param {import('postcss').ChildNode | object | string | Array<import('postcss').ChildNode>} add - The node(s) to insert.
 * @returns {import('postcss').Container} The container instance for chaining.
 */
export function insertBefore(container, exist, add) {
  return container.insertBefore(exist, add);
}

/**
 * Inserts one or more CSS declarations before a target declaration or index in a rule.
 *
 * @param {import('postcss').Rule | import('postcss').AtRule} rule - The parent rule or at-rule.
 * @param {import('postcss').ChildNode | number} target - The declaration or index to insert before.
 * @param {Array<import('postcss').Declaration | { prop: string, value: string }>} declarations - The declarations to insert.
 * @returns {import('postcss').Rule | import('postcss').AtRule} The rule instance.
 */
export function insertDeclarationsBefore(rule, target, declarations) {
  for (const decl of declarations) {
    rule.insertBefore(target, decl);
  }
  return rule;
}

export default insertBefore;

{
  "name": "sample-postcss-container-insertbefore",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-postcss-container-insertbefore",
      "version": "1.0.0",
      "dependencies": {
        "postcss": "8.5.26"
      }
    },
    "node_modules/nanoid": {
      "version": "3.3.18",
      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "bin": {
        "nanoid": "bin/nanoid.cjs"
      },
      "engines": {
        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
      }
    },
    "node_modules/picocolors": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
      "license": "ISC"
    },
    "node_modules/postcss": {
      "version": "8.5.26",
      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
      "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
      "funding": [
        {
          "type": "opencollective",
          "url": "https://opencollective.com/postcss/"
        },
        {
          "type": "tidelift",
          "url": "https://tidelift.com/funding/github/npm/postcss"
        },
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "nanoid": "^3.3.17",
        "picocolors": "^1.1.1",
        "source-map-js": "^1.2.1"
      },
      "engines": {
        "node": "^10 || ^12 || >=14"
      }
    },
    "node_modules/source-map-js": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
      "license": "BSD-3-Clause",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

{
  "name": "sample-postcss-container-insertbefore",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "postcss": "8.5.26"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify postcss.Container.insertBefore in pkg:npm/postcss@8.5.26",
  "kind": "HOW",
  "packages": [
    "pkg:npm/postcss@8.5.26"
  ],
  "symbols": [
    "postcss.Container.insertBefore"
  ]
}

import assert from 'node:assert/strict';
import postcss from 'postcss';
import { insertBefore, insertDeclarationsBefore } from '../index.mjs';

// 1. assert insertBefore inserts a Declaration node before a target Declaration and returns the container
{
  const root = postcss.parse('.card { color: red; border: 1px solid black; }');
  const rule = root.first;
  const targetDecl = rule.nodes[1];
  const newDecl = postcss.decl({ prop: 'background', value: 'white' });

  const result = insertBefore(rule, targetDecl, newDecl);

  assert.strictEqual(result, rule, 'insertBefore should return the container for chaining');
  assert.strictEqual(rule.nodes.length, 3);
  assert.strictEqual(rule.nodes[0].prop, 'color');
  assert.strictEqual(rule.nodes[1].prop, 'background');
  assert.strictEqual(rule.nodes[1].value, 'white');
  assert.strictEqual(rule.nodes[2].prop, 'border');
  assert.strictEqual(newDecl.parent, rule, 'New node parent should point to the container');
}

// 2. assert insertBefore inserts a node before a numeric child index
{
  const root = postcss.parse('.btn { display: flex; }');
  const rule = root.first;
  const commentNode = postcss.comment({ text: 'button layout' });

  const result = insertBefore(rule, 0, commentNode);

  assert.strictEqual(result, rule);
  assert.strictEqual(rule.nodes.length, 2);
  assert.strictEqual(rule.nodes[0].type, 'comment');
  assert.strictEqual(rule.nodes[0].text, 'button layout');
  assert.strictEqual(rule.nodes[1].prop, 'display');
  assert.strictEqual(commentNode.parent, rule);
}

// 3. assert insertBefore normalizes and inserts a plain declaration object
{
  const root = postcss.parse('.box { margin: 0; }');
  const rule = root.first;
  const targetDecl = rule.first;

  insertBefore(rule, targetDecl, { prop: 'padding', value: '10px' });

  assert.strictEqual(rule.nodes.length, 2);
  assert.strictEqual(rule.nodes[0].prop, 'padding');
  assert.strictEqual(rule.nodes[0].value, '10px');
  assert.strictEqual(rule.nodes[0].type, 'decl');
  assert.strictEqual(rule.nodes[1].prop, 'margin');
}

// 4. assert insertBefore normalizes and inserts raw CSS string declarations
{
  const root = postcss.parse('.banner { opacity: 1; }');
  const rule = root.first;
  const targetDecl = rule.first;

  insertBefore(rule, targetDecl, 'z-index: 100;');

  assert.strictEqual(rule.nodes.length, 2);
  assert.strictEqual(rule.nodes[0].prop, 'z-index');
  assert.strictEqual(rule.nodes[0].value, '100');
  assert.strictEqual(rule.nodes[1].prop, 'opacity');
}

// 5. assert insertBefore inserts multiple Node instances passed as an array
{
  const root = postcss.parse('.nav { width: 100%; }');
  const rule = root.first;
  const targetDecl = rule.first;

  insertBefore(rule, targetDecl, [
    postcss.decl({ prop: 'top', value: '0' }),
    postcss.decl({ prop: 'left', value: '0' })
  ]);

  assert.strictEqual(rule.nodes.length, 3);
  assert.strictEqual(rule.nodes[0].prop, 'top');
  assert.strictEqual(rule.nodes[1].prop, 'left');
  assert.strictEqual(rule.nodes[2].prop, 'width');
}

// 6. assert insertBefore reparents an existing node moved from another container
{
  const sourceRoot = postcss.parse('.source { opacity: 0.5; }');
  const targetRoot = postcss.parse('.target { visibility: visible; }');
  const sourceDecl = sourceRoot.first.first;
  const targetDecl = targetRoot.first.first;

  insertBefore(targetRoot.first, targetDecl, sourceDecl);

  assert.strictEqual(sourceRoot.first.nodes.length, 0, 'Source container should no longer contain moved node');
  assert.strictEqual(targetRoot.first.nodes.length, 2);
  assert.strictEqual(targetRoot.first.nodes[0], sourceDecl);
  assert.strictEqual(sourceDecl.parent, targetRoot.first, 'Parent should be updated to target container');
}

// 7. assert insertBefore inserts a Rule into a Root container before another Rule
{
  const root = postcss.parse('.first { color: blue; } .last { color: green; }');
  const middleRule = postcss.rule({ selector: '.middle' });
  middleRule.append(postcss.decl({ prop: 'color', value: 'yellow' }));

  insertBefore(root, root.nodes[1], middleRule);

  assert.strictEqual(root.nodes.length, 3);
  assert.strictEqual(root.nodes[0].selector, '.first');
  assert.strictEqual(root.nodes[1].selector, '.middle');
  assert.strictEqual(root.nodes[2].selector, '.last');
  assert.strictEqual(middleRule.parent, root);
}

// 8. assert insertDeclarationsBefore helper inserts multiple declaration items before target in sequence
{
  const root = postcss.parse('.widget { color: black; }');
  const rule = root.first;

  insertDeclarationsBefore(rule, rule.first, [
    { prop: 'font-size', value: '14px' },
    postcss.decl({ prop: 'line-height', value: '1.5' })
  ]);

  assert.strictEqual(rule.nodes.length, 3);
  assert.strictEqual(rule.nodes[0].prop, 'font-size');
  assert.strictEqual(rule.nodes[1].prop, 'line-height');
  assert.strictEqual(rule.nodes[2].prop, 'color');
}

console.log('All contracts passed successfully.');