compress-commons 4.1.2: ZipArchiveEntry

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 compress-commons.ZipArchiveEntry in pkg:npm/compress-commons@4.1.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/compress-commons@4.1.2
Demonstrate these symbols/APIs:
  - compress-commons.ZipArchiveEntry
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:2d5435720d314bb1bd94c9c3f681aa11c887db2c1c9ff2e76f4161baadb030c4","constraints":{"executionContext":"node"},"contract":["ZipArchiveEntry instantiates with an entry name and default attributes","ZipArchiveEntry sets and gets last modified timestamp as Date and DOS format","ZipArchiveEntry tracks uncompressed size, compressed size, and CRC32 checksum","ZipArchiveEntry configures entry comments and enables UTF-8 flag for non-ASCII characters","ZipArchiveEntry sets Unix permissions and identifies directory or regular file entries","ZipArchiveEntry detects ZIP64 requirements for entries exceeding standard size limits","ZipArchiveEntry stores and retrieves custom extra field buffers","ZipArchiveEntry validates input arguments and rejects negative sizes or invalid timestamps","inspectArchiveEntry helper produces comprehensive property summary"],"goal":"verify compress-commons.ZipArchiveEntry in pkg:npm/compress-commons@4.1.2","kind":"HOW","packages":["pkg:npm/compress-commons@4.1.2"],"schemaVersion":1,"symbols":["compress-commons.ZipArchiveEntry"]},"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/compress-commons@4.1.2"],"schemaVersion":1,"subject":"pkg:npm/compress-commons@4.1.2","symbols":["compress-commons.ZipArchiveEntry"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-compress-commons-zip-archive-entry",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-compress-commons-zip-archive-entry",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "compress-commons": "4.1.2"
      }
    },
    "node_modules/buffer-crc32": {
      "version": "0.2.13",
      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
      "license": "MIT",
      "engines": {
        "node": "*"
      }
    },
    "node_modules/compress-commons": {
      "version": "4.1.2",
      "resolved": "https://registry.npmjs.org/compress-commons/-/compress-commons-4.1.2.tgz",
      "integrity": "sha512-D3uMHtGc/fcO1Gt1/L7i1e33VOvD4A9hfQLP+6ewd+BvG/gQ84Yh4oftEhAdjSMgBgwGL+jsppT7JYNpo6MHHg==",
      "license": "MIT",
      "dependencies": {
        "buffer-crc32": "^0.2.13",
        "crc32-stream": "^4.0.2",
        "normalize-path": "^3.0.0",
        "readable-stream": "^3.6.0"
      },
      "engines": {
        "node": ">= 10"
      }
    },
    "node_modules/crc-32": {
      "version": "1.2.2",
      "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz",
      "integrity": "sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==",
      "license": "Apache-2.0",
      "bin": {
        "crc32": "bin/crc32.njs"
      },
      "engines": {
        "node": ">=0.8"
      }
    },
    "node_modules/crc32-stream": {
      "version": "4.0.3",
      "resolved": "https://registry.npmjs.org/crc32-stream/-/crc32-stream-4.0.3.tgz",
      "integrity": "sha512-NT7w2JVU7DFroFdYkeq8cywxrgjPHWkdX1wjpRQXPX5Asews3tA+Ght6lddQO5Mkumffp3X7GEqku3epj2toIw==",
      "license": "MIT",
      "dependencies": {
        "crc-32": "^1.2.0",
        "readable-stream": "^3.4.0"
      },
      "engines": {
        "node": ">= 10"
      }
    },
    "node_modules/inherits": {
      "version": "2.0.4",
      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
      "license": "ISC"
    },
    "node_modules/normalize-path": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
      "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/readable-stream": {
      "version": "3.6.2",
      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
      "license": "MIT",
      "dependencies": {
        "inherits": "^2.0.3",
        "string_decoder": "^1.1.1",
        "util-deprecate": "^1.0.1"
      },
      "engines": {
        "node": ">= 6"
      }
    },
    "node_modules/safe-buffer": {
      "version": "5.2.1",
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT"
    },
    "node_modules/string_decoder": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
      "license": "MIT",
      "dependencies": {
        "safe-buffer": "~5.2.0"
      }
    },
    "node_modules/util-deprecate": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-compress-commons-zip-archive-entry",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for compress-commons ZipArchiveEntry",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "compress-commons": "4.1.2"
  },
  "license": "MIT-0"
}

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

const { ZipArchiveEntry } = require('compress-commons');

/**
 * Creates and initializes a ZipArchiveEntry with specified properties.
 *
 * @param {string} name - The entry name / path.
 * @param {Object} [options] - Configuration options.
 * @param {Date} [options.time] - Last modified time.
 * @param {string} [options.comment] - Entry comment.
 * @param {number} [options.mode] - Unix permission mode (e.g. 0o644 or 0o755).
 * @param {number} [options.size] - Uncompressed size in bytes.
 * @param {number} [options.compressedSize] - Compressed size in bytes.
 * @param {number} [options.crc] - CRC32 checksum.
 * @param {Buffer} [options.extra] - Extra field data buffer.
 * @returns {ZipArchiveEntry} The configured archive entry instance.
 */
function createArchiveEntry(name, options = {}) {
  const entry = new ZipArchiveEntry(name);

  if (options.time instanceof Date) {
    entry.setTime(options.time);
  }

  if (typeof options.comment === 'string') {
    entry.setComment(options.comment);
  }

  if (typeof options.mode === 'number') {
    entry.setUnixMode(options.mode);
  }

  if (typeof options.size === 'number') {
    entry.setSize(options.size);
  }

  if (typeof options.compressedSize === 'number') {
    entry.setCompressedSize(options.compressedSize);
  }

  if (typeof options.crc === 'number') {
    entry.setCrc(options.crc);
  }

  if (Buffer.isBuffer(options.extra)) {
    entry.setExtra(options.extra);
  }

  return entry;
}

/**
 * Creates a directory entry (with trailing slash).
 *
 * @param {string} dirName - Directory path name.
 * @param {Object} [options] - Configuration options.
 * @returns {ZipArchiveEntry}
 */
function createDirectoryEntry(dirName, options = {}) {
  const normalizedName = dirName.endsWith('/') ? dirName : `${dirName}/`;
  const defaultMode = options.mode !== undefined ? options.mode : 0o755;
  return createArchiveEntry(normalizedName, { ...options, mode: defaultMode });
}

/**
 * Inspects a ZipArchiveEntry and returns a summary object.
 *
 * @param {ZipArchiveEntry} entry
 * @returns {Object}
 */
function inspectArchiveEntry(entry) {
  return {
    name: entry.getName(),
    isDirectory: entry.isDirectory(),
    size: entry.getSize(),
    compressedSize: entry.getCompressedSize(),
    crc: entry.getCrc(),
    comment: entry.getComment(),
    lastModified: entry.getLastModifiedDate(),
    timeDos: entry.getTimeDos(),
    platform: entry.getPlatform(),
    unixMode: entry.getUnixMode(),
    isUnixSymlink: entry.isUnixSymlink(),
    isZip64: entry.isZip64()
  };
}

module.exports = {
  ZipArchiveEntry,
  createArchiveEntry,
  createDirectoryEntry,
  inspectArchiveEntry
};

const assert = require('node:assert');
const {
  ZipArchiveEntry,
  createArchiveEntry,
  createDirectoryEntry,
  inspectArchiveEntry
} = require('../src/index.js');

async function runContractTests() {
  // Test 1: ZipArchiveEntry instantiates with an entry name and default attributes
  const entry1 = new ZipArchiveEntry('documents/report.txt');
  assert.ok(entry1 instanceof ZipArchiveEntry, 'must be an instance of ZipArchiveEntry');
  assert.strictEqual(entry1.getName(), 'documents/report.txt', 'name must match initial input');
  assert.strictEqual(entry1.isDirectory(), false, 'regular file must not be a directory');
  assert.strictEqual(entry1.getSize(), 0, 'initial size must be 0');
  assert.strictEqual(entry1.getCompressedSize(), 0, 'initial compressed size must be 0');
  assert.strictEqual(entry1.getCrc(), 0, 'initial CRC must be 0');
  assert.strictEqual(entry1.getComment(), '', 'initial comment must be empty string');
  assert.strictEqual(entry1.getTime(), -1, 'initial time must be -1');
  assert.strictEqual(entry1.getTimeDos(), 0, 'initial DOS time must be 0');

  // Test 2: ZipArchiveEntry sets and gets last modified timestamp as Date and DOS format
  const timestamp = new Date('2025-08-20T14:30:00Z');
  entry1.setTime(timestamp);
  const dateResult = entry1.getTime();
  assert.ok(dateResult instanceof Date, 'getTime must return a Date object');
  assert.strictEqual(entry1.getLastModifiedDate() instanceof Date, true, 'getLastModifiedDate must return a Date object');
  assert.ok(entry1.getTimeDos() > 0, 'DOS timestamp must be positive');

  // Test 3: ZipArchiveEntry tracks uncompressed size, compressed size, and CRC32 checksum
  entry1.setSize(2048);
  entry1.setCompressedSize(1024);
  entry1.setCrc(0x9abcdef0);
  assert.strictEqual(entry1.getSize(), 2048, 'size must match');
  assert.strictEqual(entry1.getCompressedSize(), 1024, 'compressed size must match');
  assert.strictEqual(entry1.getCrc(), 0x9abcdef0, 'CRC32 checksum must match');

  // Test 4: ZipArchiveEntry configures entry comments and enables UTF-8 flag for non-ASCII characters
  entry1.setComment('Standard ASCII comment');
  assert.strictEqual(entry1.getComment(), 'Standard ASCII comment');

  const utf8Entry = new ZipArchiveEntry('문서/테스트.txt');
  utf8Entry.setComment('압축 파일 엔트리');
  assert.strictEqual(utf8Entry.getName(), '문서/테스트.txt');
  assert.strictEqual(utf8Entry.getComment(), '압축 파일 엔트리');
  assert.strictEqual(utf8Entry.getGeneralPurposeBit().usesUTF8ForNames(), true, 'UTF-8 bit flag must be enabled for multi-byte characters');

  // Test 5: ZipArchiveEntry sets Unix permissions and identifies directory or regular file entries
  const unixFile = createArchiveEntry('bin/run.sh', { mode: 0o755 });
  assert.strictEqual(unixFile.getPlatform(), 3, 'platform must be set to UNIX (3)');
  assert.strictEqual(unixFile.getUnixMode() & 0o777, 0o755, 'unix mode must preserve 0o755 permissions');
  assert.strictEqual(unixFile.isDirectory(), false, 'file entry should not be directory');
  assert.strictEqual(unixFile.isUnixSymlink(), false, 'regular executable is not a symlink');

  const dirEntry = createDirectoryEntry('nested/dir/');
  assert.strictEqual(dirEntry.isDirectory(), true, 'trailing slash entry must be directory');
  assert.strictEqual(dirEntry.getName(), 'nested/dir/');

  const dirFromBare = createDirectoryEntry('nested/dir2');
  assert.strictEqual(dirFromBare.isDirectory(), true, 'createDirectoryEntry must normalize trailing slash');
  assert.strictEqual(dirFromBare.getName(), 'nested/dir2/');

  // Test 6: ZipArchiveEntry detects ZIP64 requirements for entries exceeding standard size limits
  assert.strictEqual(entry1.isZip64(), false, 'standard sized entry should not be ZIP64');
  entry1.setSize(0x100000000); // 4GB + 1
  assert.strictEqual(entry1.isZip64(), true, 'entry exceeding 4GB must report isZip64 true');

  // Test 7: ZipArchiveEntry stores and retrieves custom extra field buffers
  const extraData = Buffer.from([0x55, 0x54, 0x05, 0x00, 0x07]);
  entry1.setExtra(extraData);
  assert.strictEqual(entry1.getExtra().equals(extraData), true, 'extra buffer must match');
  assert.strictEqual(entry1.getCentralDirectoryExtra().equals(extraData), true, 'central directory extra must match');
  assert.strictEqual(entry1.getLocalFileDataExtra().equals(extraData), true, 'local file data extra must match');

  // Test 8: ZipArchiveEntry validates input arguments and rejects negative sizes or invalid timestamps
  assert.throws(() => entry1.setSize(-1), /invalid entry size/, 'must reject negative size');
  assert.throws(() => entry1.setCompressedSize(-1), /invalid entry compressed size/, 'must reject negative compressed size');
  assert.throws(() => entry1.setCrc(-1), /invalid entry crc32/, 'must reject negative CRC');
  assert.throws(() => entry1.setTime('2025-01-01'), /invalid entry time/, 'must reject non-Date time argument');

  // Test 9: inspectArchiveEntry helper produces comprehensive property summary
  const summary = inspectArchiveEntry(unixFile);
  assert.strictEqual(summary.name, 'bin/run.sh');
  assert.strictEqual(summary.isDirectory, false);
  assert.strictEqual(summary.platform, 3);
  assert.strictEqual(summary.unixMode & 0o777, 0o755);

  console.log('All compress-commons ZipArchiveEntry contract tests passed.');
}

runContractTests().catch(err => {
  console.error('Contract test failed:', err);
  process.exit(1);
});