react-refresh 0.18.0: react-refresh

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 react-refresh in pkg:npm/react-refresh@0.18.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react-refresh@0.18.0
Demonstrate these symbols/APIs:
  - react-refresh
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - 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:feffc064e5a7fc6498c434560a314baea762def7311b26d9a893ba76d05436af","constraints":{"executionContext":"node"},"contract":["isLikelyComponentType returns true for component functions with uppercase names, React.forwardRef, and React.memo objects","isLikelyComponentType returns false for helper functions with lowercase names, primitives, and plain objects","register assigns a component to a family by unique ID, retrievable via getFamilyByID and getFamilyByType","performReactRefresh applies pending updates to component families and tracks updated families","createSignatureFunctionForTransform creates signature helper for hook tracking and hasUnrecoverableErrors returns false"],"goal":"verify react-refresh in pkg:npm/react-refresh@0.18.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.18.0"],"schemaVersion":1,"symbols":["react-refresh"]},"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/react-refresh@0.18.0"],"schemaVersion":1,"subject":"pkg:npm/react-refresh@0.18.0","symbols":["react-refresh"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-refresh",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-refresh",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "react-refresh": "0.18.0"
      }
    },
    "node_modules/react-refresh": {
      "version": "0.18.0",
      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.18.0.tgz",
      "integrity": "sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

{
  "name": "sample-react-refresh",
  "version": "1.0.0",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "react-refresh": "0.18.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify react-refresh in pkg:npm/react-refresh@0.18.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/react-refresh@0.18.0"
  ],
  "symbols": [
    "react-refresh"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const Refresh = require('react-refresh');

function isLikelyComponent(type) {
  return Refresh.isLikelyComponentType(type);
}

function registerComponent(type, id) {
  Refresh.register(type, id);
}

function getFamilyByID(id) {
  return Refresh.getFamilyByID(id);
}

function getFamilyByType(type) {
  return Refresh.getFamilyByType(type);
}

function performRefresh() {
  return Refresh.performReactRefresh();
}

function createSignature() {
  return Refresh.createSignatureFunctionForTransform();
}

function hasErrors() {
  return Refresh.hasUnrecoverableErrors();
}

module.exports = {
  Refresh,
  isLikelyComponent,
  registerComponent,
  getFamilyByID,
  getFamilyByType,
  performRefresh,
  createSignature,
  hasErrors
};

const assert = require('node:assert/strict');
const Refresh = require('react-refresh');
const {
  isLikelyComponent,
  registerComponent,
  getFamilyByID,
  getFamilyByType,
  performRefresh,
  createSignature,
  hasErrors
} = require('../src/index.js');

// 1. Verify component type detection
function HeaderComponent() {
  return 'header';
}

function helperFunction() {
  return 'helper';
}

const forwardRefComponent = {
  $$typeof: Symbol.for('react.forward_ref'),
  render: HeaderComponent
};

const memoComponent = {
  $$typeof: Symbol.for('react.memo'),
  type: HeaderComponent
};

assert.equal(
  isLikelyComponent(HeaderComponent),
  true,
  'Functions with uppercase names should be recognized as components'
);
assert.equal(
  isLikelyComponent(forwardRefComponent),
  true,
  'React forwardRef objects should be recognized as components'
);
assert.equal(
  isLikelyComponent(memoComponent),
  true,
  'React memo objects should be recognized as components'
);

assert.equal(
  isLikelyComponent(helperFunction),
  false,
  'Functions with lowercase names should not be recognized as components'
);
assert.equal(
  isLikelyComponent(null),
  false,
  'null should not be recognized as component'
);
assert.equal(
  isLikelyComponent(undefined),
  false,
  'undefined should not be recognized as component'
);
assert.equal(
  isLikelyComponent({}),
  false,
  'Plain objects should not be recognized as components'
);

// 2. Verify component registration and family retrieval
const componentId = 'src/components/Header.js %exports% HeaderComponent';
registerComponent(HeaderComponent, componentId);

const familyFromId = getFamilyByID(componentId);
assert.ok(familyFromId, 'Family should exist for registered component ID');
assert.equal(
  familyFromId.current,
  HeaderComponent,
  'Family current type should match registered component'
);

const familyFromType = getFamilyByType(HeaderComponent);
assert.equal(
  familyFromType,
  familyFromId,
  'getFamilyByType should return the same family reference as getFamilyByID'
);

// 3. Verify hot reload replacement with performRefresh
function HeaderComponentV2() {
  return 'header v2';
}

registerComponent(HeaderComponentV2, componentId);

// Before performRefresh, family.current is still original component
assert.equal(
  familyFromId.current,
  HeaderComponent,
  'family.current should not change before performRefresh'
);

const refreshResult = performRefresh();
assert.ok(refreshResult, 'performRefresh should return update result');
assert.equal(
  familyFromId.current,
  HeaderComponentV2,
  'family.current should update to new component after performRefresh'
);
assert.equal(
  refreshResult.updatedFamilies.has(familyFromId),
  true,
  'updatedFamilies should contain updated component family'
);

// 4. Verify signature function for transform and error state
const sig = createSignature();
assert.equal(
  typeof sig,
  'function',
  'createSignature should return a transform helper function'
);

function CounterComponent() {
  return 0;
}
sig(CounterComponent, 'useState{[count, setCount](0)}');
sig();

assert.equal(
  isLikelyComponent(CounterComponent),
  true,
  'Signature-wrapped component remains a likely component'
);
assert.equal(
  hasErrors(),
  false,
  'hasUnrecoverableErrors should return false'
);

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