magic-string 0.30.21: MagicString, MagicString.prototype.overwrite, MagicString.prototype.appendLeft

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/magic-string@0.30.21
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/magic-string@0.30.21
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:ea12cc7562238118421343b4b24bd38f4519a86cb5af1a3b09c0ff56d09cf3fd","constraints":{"executionContext":"node"},"contract":["MagicString(input) instantiates a mutable string manipulator with unchanged initial state","s.overwrite(start, end, replacement) replaces a substring range and sets hasChanged() to true","s.prepend(str) and s.append(str) insert content at start and end boundaries","s.appendLeft(index, str) inserts content at specific character index","s.toString() returns transformed string","s.generateMap(options) returns a v3 SourceMap with mappings, sources, and sourcesContent","map.toUrl() generates a base64 data URL for inline sourcemaps","Bundle merges multiple MagicString instances into a single bundle with sourcemap"],"goal":"verify pkg:npm/magic-string@0.30.21","kind":"HOW","packages":["pkg:npm/magic-string@0.30.21"],"schemaVersion":1,"symbols":["MagicString","MagicString.prototype.overwrite","MagicString.prototype.appendLeft","MagicString.prototype.generateMap","MagicString.prototype.toString"]},"contractCommand":["node","test/contract.js"],"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/magic-string@0.30.21"],"schemaVersion":1,"subject":"pkg:npm/magic-string@0.30.21","symbols":["MagicString","MagicString.prototype.overwrite","MagicString.prototype.appendLeft","MagicString.prototype.generateMap","MagicString.prototype.toString"],"verifierAdapter":"node-typescript@1"}

const MagicString = require('magic-string');

function transformCode(sourceCode, replacements) {
  const s = new MagicString(sourceCode);
  for (const { start, end, replacement } of replacements) {
    s.overwrite(start, end, replacement);
  }
  return {
    code: s.toString(),
    map: s.generateMap({ hires: true })
  };
}

module.exports = { transformCode };

{
  "name": "verify-magic-string",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "verify-magic-string",
      "version": "1.0.0",
      "dependencies": {
        "magic-string": "0.30.21"
      }
    },
    "node_modules/@jridgewell/sourcemap-codec": {
      "version": "1.5.5",
      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
      "license": "MIT"
    },
    "node_modules/magic-string": {
      "version": "0.30.21",
      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
      "license": "MIT",
      "dependencies": {
        "@jridgewell/sourcemap-codec": "^1.5.5"
      }
    }
  }
}

{
  "name": "verify-magic-string",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for magic-string",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "magic-string": "0.30.21"
  }
}

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

const assert = require('node:assert');
const MagicString = require('magic-string');
const { Bundle } = require('magic-string');
const { transformCode } = require('../index.js');

function testMagicStringCore() {
  const input = 'export const answer = 42;\nconsole.log(answer);';
  const s = new MagicString(input);

  // 1. Initial state
  assert.strictEqual(s.hasChanged(), false);
  assert.strictEqual(s.toString(), input);
  assert.strictEqual(s.length(), input.length);

  // 2. Overwrite range: 'answer' (indices 13..19) -> 'result'
  s.overwrite(13, 19, 'result');
  assert.strictEqual(s.hasChanged(), true);

  // 3. Append / Prepend mutations
  s.prepend('// Header\n');
  s.append('\n// Footer');
  s.appendLeft(25, ' /* semicolon */');

  const transformed = s.toString();
  assert.ok(transformed.startsWith('// Header\nexport const result = 42; /* semicolon */'));
  assert.ok(transformed.endsWith('\n// Footer'));

  // 4. Sourcemap generation
  const map = s.generateMap({
    source: 'input.js',
    file: 'output.js',
    hires: true,
    includeContent: true
  });

  assert.strictEqual(map.version, 3);
  assert.strictEqual(map.file, 'output.js');
  assert.deepStrictEqual(map.sources, ['input.js']);
  assert.ok(typeof map.mappings === 'string' && map.mappings.length > 0);
  assert.ok(Array.isArray(map.sourcesContent) && map.sourcesContent.length === 1);
  assert.strictEqual(map.sourcesContent[0], input);

  // 5. Sourcemap serialisation
  const mapJson = map.toString();
  const parsed = JSON.parse(mapJson);
  assert.strictEqual(parsed.version, 3);
  assert.strictEqual(parsed.file, 'output.js');

  const dataUrl = map.toUrl();
  assert.ok(dataUrl.startsWith('data:application/json;charset=utf-8;base64,'));

  // 6. Bundle support
  const bundle = new Bundle({ separator: '\n' });
  bundle.addSource({
    filename: 'moduleA.js',
    content: new MagicString('export const a = 1;')
  });
  bundle.addSource({
    filename: 'moduleB.js',
    content: new MagicString('export const b = 2;')
  });

  const bundledCode = bundle.toString();
  assert.ok(bundledCode.includes('export const a = 1;'));
  assert.ok(bundledCode.includes('export const b = 2;'));

  const bundleMap = bundle.generateMap({ file: 'bundle.js', includeContent: true });
  assert.strictEqual(bundleMap.version, 3);
  assert.deepStrictEqual(bundleMap.sources, ['moduleA.js', 'moduleB.js']);

  // 7. Helper verification
  const helperResult = transformCode('const x = 1;', [{ start: 6, end: 7, replacement: 'y' }]);
  assert.strictEqual(helperResult.code, 'const y = 1;');
  assert.strictEqual(helperResult.map.version, 3);

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

testMagicStringCore();