@babel/helper-annotate-as-pure 7.29.7: annotate AST node as pure with @babel/helper-annotate-as-pure

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: annotate AST node as pure with @babel/helper-annotate-as-pure
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40babel/helper-annotate-as-pure@7.29.7
Demonstrate these symbols/APIs:
  - annotateAsPure

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:6ab038d1db2e332c056a68ba5af70ffe0ae26a66554ca6787022e84cddd40de7","contract":["annotate AST node with #__PURE__ leading comment","annotate NodePath wrapping an AST node","idempotent when node already has #__PURE__ comment","idempotent when node already has @__PURE__ comment","preserves existing unrelated leading comments when annotating"],"goal":"annotate AST node as pure with @babel/helper-annotate-as-pure","kind":"HOW","packages":["pkg:npm/%40babel/helper-annotate-as-pure@7.29.7"],"schemaVersion":1,"symbols":["annotateAsPure"]},"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/%40babel/helper-annotate-as-pure@7.29.7"],"schemaVersion":1,"subject":"pkg:npm/%40babel/helper-annotate-as-pure@7.29.7","symbols":["annotateAsPure"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-babel-helper-annotate-as-pure",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-babel-helper-annotate-as-pure",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@babel/helper-annotate-as-pure": "7.29.7"
      }
    },
    "node_modules/@babel/helper-annotate-as-pure": {
      "version": "7.29.7",
      "resolved": "https://registry.npmjs.org/@babel/helper-annotate-as-pure/-/helper-annotate-as-pure-7.29.7.tgz",
      "integrity": "sha512-OoK6239jHPuSQOoS0kfTVKn0b/rVTk0seKq4Gd2UMLtmOVLjDC0ki3e+c90Trqv2gMfvJFqkiljrr568+qddiw==",
      "license": "MIT",
      "dependencies": {
        "@babel/types": "^7.29.7"
      },
      "engines": {
        "node": ">=6.9.0"
      }
    },
    "node_modules/@babel/helper-string-parser": {
      "version": "7.29.7",
      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
      "integrity": "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==",
      "license": "MIT",
      "engines": {
        "node": ">=6.9.0"
      }
    },
    "node_modules/@babel/helper-validator-identifier": {
      "version": "7.29.7",
      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz",
      "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==",
      "license": "MIT",
      "engines": {
        "node": ">=6.9.0"
      }
    },
    "node_modules/@babel/types": {
      "version": "7.29.8",
      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.8.tgz",
      "integrity": "sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg==",
      "license": "MIT",
      "dependencies": {
        "@babel/helper-string-parser": "^7.29.7",
        "@babel/helper-validator-identifier": "^7.29.7"
      },
      "engines": {
        "node": ">=6.9.0"
      }
    }
  }
}

{
  "name": "sample-babel-helper-annotate-as-pure",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "@babel/helper-annotate-as-pure": "7.29.7"
  }
}

{
  "schemaVersion": 1,
  "goal": "annotate AST node as pure with @babel/helper-annotate-as-pure",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40babel/helper-annotate-as-pure@7.29.7"
  ],
  "symbols": [
    "annotateAsPure"
  ]
}

import annotateAsPureModule from "@babel/helper-annotate-as-pure";

const annotateAsPure = annotateAsPureModule.default || annotateAsPureModule;

export function markAsPure(target) {
  annotateAsPure(target);
  return target;
}

export function isPure(nodeOrPath) {
  const node = nodeOrPath?.node || nodeOrPath;
  if (!node || !Array.isArray(node.leadingComments)) {
    return false;
  }
  return node.leadingComments.some(comment => /[@#]__PURE__/.test(comment?.value || ""));
}

export { annotateAsPure };

import assert from "node:assert/strict";
import annotateAsPureModule from "@babel/helper-annotate-as-pure";
import { markAsPure, isPure } from "../src/index.mjs";

const annotateAsPure = annotateAsPureModule.default || annotateAsPureModule;

// Contract 1: annotate AST node with #__PURE__ leading comment
{
  const node = {
    type: "CallExpression",
    callee: { type: "Identifier", name: "factory" },
    arguments: []
  };

  assert.equal(isPure(node), false);
  annotateAsPure(node);

  assert.equal(isPure(node), true);
  assert.ok(Array.isArray(node.leadingComments));
  assert.equal(node.leadingComments.length, 1);
  assert.equal(node.leadingComments[0].type, "CommentBlock");
  assert.equal(node.leadingComments[0].value, "#__PURE__");
}

// Contract 2: annotate NodePath wrapping an AST node
{
  const innerNode = {
    type: "NewExpression",
    callee: { type: "Identifier", name: "Widget" },
    arguments: []
  };
  const mockPath = { node: innerNode };

  markAsPure(mockPath);

  assert.equal(isPure(mockPath), true);
  assert.equal(isPure(innerNode), true);
  assert.ok(Array.isArray(innerNode.leadingComments));
  assert.equal(innerNode.leadingComments.length, 1);
  assert.equal(innerNode.leadingComments[0].type, "CommentBlock");
  assert.equal(innerNode.leadingComments[0].value, "#__PURE__");
}

// Contract 3: idempotent when node already has #__PURE__ comment
{
  const node = {
    type: "CallExpression",
    callee: { type: "Identifier", name: "createStore" },
    arguments: []
  };

  annotateAsPure(node);
  assert.equal(node.leadingComments.length, 1);

  // Calling again should not add duplicate comment
  annotateAsPure(node);
  assert.equal(node.leadingComments.length, 1);
  assert.equal(node.leadingComments[0].value, "#__PURE__");

  // markAsPure wrapper should also be idempotent
  markAsPure(node);
  assert.equal(node.leadingComments.length, 1);
}

// Contract 4: idempotent when node already has @__PURE__ comment
{
  const node = {
    type: "CallExpression",
    callee: { type: "Identifier", name: "init" },
    arguments: [],
    leadingComments: [
      {
        type: "CommentBlock",
        value: "@__PURE__"
      }
    ]
  };

  assert.equal(isPure(node), true);
  annotateAsPure(node);
  assert.equal(node.leadingComments.length, 1);
  assert.equal(node.leadingComments[0].value, "@__PURE__");
}

// Contract 5: preserves existing unrelated leading comments when annotating
{
  const node = {
    type: "CallExpression",
    callee: { type: "Identifier", name: "setup" },
    arguments: [],
    leadingComments: [
      {
        type: "CommentLine",
        value: " custom leading comment"
      }
    ]
  };

  assert.equal(isPure(node), false);
  annotateAsPure(node);

  assert.equal(isPure(node), true);
  assert.equal(node.leadingComments.length, 2);
  assert.equal(node.leadingComments[0].type, "CommentBlock");
  assert.equal(node.leadingComments[0].value, "#__PURE__");
  assert.equal(node.leadingComments[1].type, "CommentLine");
  assert.equal(node.leadingComments[1].value, " custom leading comment");
}

console.log("All @babel/helper-annotate-as-pure contract assertions passed.");