tar 6.2.1: t

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 tar.t in pkg:npm/tar@6.2.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tar@6.2.1
Demonstrate these symbols/APIs:
  - tar.t

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:b5cfa997a0d93d0adaaa92a0fa6cc8c1dbf9889e4c3219113d7e0f8008520682","contract":["t is an exported function identical to tar.list","tar.t lists archive entries synchronously with entry path size and type details","tar.t lists archive entries asynchronously returning a promise","tar.t filters archive entries during listing with a filter predicate function","tar.t creates a writable stream parser when invoked without the file option"],"goal":"verify tar.t in pkg:npm/tar@6.2.1","kind":"HOW","packages":["pkg:npm/tar@6.2.1"],"schemaVersion":1,"symbols":["tar.t"]},"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/tar@6.2.1"],"schemaVersion":1,"subject":"pkg:npm/tar@6.2.1","symbols":["tar.t"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar-t",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-t",
      "version": "1.0.0",
      "dependencies": {
        "tar": "6.2.1"
      }
    },
    "node_modules/chownr": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/chownr/-/chownr-2.0.0.tgz",
      "integrity": "sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==",
      "license": "ISC",
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/fs-minipass": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-2.1.0.tgz",
      "integrity": "sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==",
      "license": "ISC",
      "dependencies": {
        "minipass": "^3.0.0"
      },
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/fs-minipass/node_modules/minipass": {
      "version": "3.3.6",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
      "license": "ISC",
      "dependencies": {
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/minipass": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-5.0.0.tgz",
      "integrity": "sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==",
      "license": "ISC",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/minizlib": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-2.1.2.tgz",
      "integrity": "sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==",
      "license": "MIT",
      "dependencies": {
        "minipass": "^3.0.0",
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/minizlib/node_modules/minipass": {
      "version": "3.3.6",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
      "license": "ISC",
      "dependencies": {
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/mkdirp": {
      "version": "1.0.4",
      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz",
      "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==",
      "license": "MIT",
      "bin": {
        "mkdirp": "bin/cmd.js"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/tar": {
      "version": "6.2.1",
      "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.1.tgz",
      "integrity": "sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==",
      "deprecated": "Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
      "license": "ISC",
      "dependencies": {
        "chownr": "^2.0.0",
        "fs-minipass": "^2.0.0",
        "minipass": "^5.0.0",
        "minizlib": "^2.1.1",
        "mkdirp": "^1.0.3",
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/yallist": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample-tar-t",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of tar.t archive listing API in tar 6.2.1",
  "type": "module",
  "main": "src/index.js",
  "dependencies": {
    "tar": "6.2.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify tar.t in pkg:npm/tar@6.2.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tar@6.2.1"
  ],
  "symbols": [
    "tar.t"
  ]
}

import tar from 'tar';

/**
 * List entries from a tar archive synchronously.
 *
 * @param {string} tarFilePath - Path to the tar archive file.
 * @param {object} [options={}] - Additional options for tar.t.
 * @returns {Array<object>} Collected entry details (path, size, type).
 */
export function listEntriesSync(tarFilePath, options = {}) {
  const entries = [];
  tar.t({
    file: tarFilePath,
    sync: true,
    onentry: (entry) => {
      entries.push({
        path: entry.path,
        size: entry.size,
        type: entry.type
      });
    },
    ...options
  });
  return entries;
}

/**
 * List entries from a tar archive asynchronously returning a Promise.
 *
 * @param {string} tarFilePath - Path to the tar archive file.
 * @param {object} [options={}] - Additional options for tar.t.
 * @returns {Promise<Array<string>>} Promise resolving to array of entry paths.
 */
export async function listEntriesAsync(tarFilePath, options = {}) {
  const entries = [];
  await tar.t({
    file: tarFilePath,
    onentry: (entry) => {
      entries.push(entry.path);
    },
    ...options
  });
  return entries;
}

/**
 * Filter and list entries from a tar archive synchronously.
 *
 * @param {string} tarFilePath - Path to the tar archive file.
 * @param {Function} filterFn - Filter predicate (path, entry) => boolean.
 * @returns {Array<string>} Filtered list of entry paths.
 */
export function filterEntriesSync(tarFilePath, filterFn) {
  const entries = [];
  tar.t({
    file: tarFilePath,
    sync: true,
    filter: filterFn,
    onentry: (entry) => {
      entries.push(entry.path);
    }
  });
  return entries;
}

/**
 * Create a tar parser stream using tar.t without a file argument.
 *
 * @param {Function} onEntry - Callback invoked for each parsed entry.
 * @returns {import('stream').Writable} Tar parser stream instance.
 */
export function createParser(onEntry) {
  return tar.t({
    onentry: onEntry
  });
}

export const { t, list, create, c, extract, x } = tar;

import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import {
  t,
  list,
  c,
  listEntriesSync,
  listEntriesAsync,
  filterEntriesSync,
  createParser
} from '../src/index.js';

// 1. Function export and alias verification
assert.equal(typeof t, 'function', 't should be an exported function');
assert.equal(typeof list, 'function', 'list should be an exported function');
assert.equal(t, list, 'tar.t must be an exact alias for tar.list');

// Setup temporary directory and test files
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-tar-test-'));
const file1 = path.join(tmpDir, 'alpha.txt');
const file2 = path.join(tmpDir, 'beta.txt');
const file3 = path.join(tmpDir, 'gamma.log');
const tarPath = path.join(tmpDir, 'bundle.tar');

try {
  fs.writeFileSync(file1, 'Hello from alpha');
  fs.writeFileSync(file2, 'Hello from beta content');
  fs.writeFileSync(file3, 'Log entry line');

  // Create tar archive for testing listing
  c(
    {
      sync: true,
      file: tarPath,
      cwd: tmpDir
    },
    ['alpha.txt', 'beta.txt', 'gamma.log']
  );

  // 2. Synchronous listing verification
  const syncEntries = listEntriesSync(tarPath);
  assert.equal(syncEntries.length, 3, 'Should list exactly 3 entries synchronously');
  const syncPaths = syncEntries.map(e => e.path);
  assert.deepEqual(syncPaths, ['alpha.txt', 'beta.txt', 'gamma.log']);
  const alphaEntry = syncEntries.find(e => e.path === 'alpha.txt');
  assert.ok(alphaEntry, 'alpha.txt entry must exist');
  assert.equal(alphaEntry.size, 16, 'alpha.txt size should match written length');
  assert.equal(alphaEntry.type, 'File', 'alpha.txt entry type should be File');

  // 3. Asynchronous promise-based listing verification
  const asyncPaths = await listEntriesAsync(tarPath);
  assert.deepEqual(asyncPaths, ['alpha.txt', 'beta.txt', 'gamma.log'], 'Async listing paths must match archive contents');

  // 4. Filtering entries during listing
  const txtOnly = filterEntriesSync(tarPath, (p) => p.endsWith('.txt'));
  assert.deepEqual(txtOnly, ['alpha.txt', 'beta.txt'], 'Filter should retain only .txt entries');

  const betaOnly = filterEntriesSync(tarPath, (p) => p === 'beta.txt');
  assert.deepEqual(betaOnly, ['beta.txt'], 'Filter should retain exact beta.txt entry');

  // 5. Stream parser mode (without file option)
  const streamEntries = [];
  const parser = createParser((entry) => {
    streamEntries.push(entry.path);
  });

  await new Promise((resolve, reject) => {
    const readStream = fs.createReadStream(tarPath);
    readStream.on('error', reject);
    parser.on('error', reject);
    parser.on('finish', resolve);
    readStream.pipe(parser);
  });

  assert.deepEqual(streamEntries, ['alpha.txt', 'beta.txt', 'gamma.log'], 'Stream parser should emit all archive entries');

} finally {
  // Cleanup temporary directory
  fs.rmSync(tmpDir, { recursive: true, force: true });
}

console.log('tar.t contract tests passed successfully.');