sumchecker 3.0.1: verify files against checksum file with sumchecker

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 files against checksum file with sumchecker
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/sumchecker@3.0.1
Demonstrate these symbols/APIs:
  - sumchecker
  - sumchecker.ChecksumMismatchError
  - sumchecker.ChecksumParseError
  - sumchecker.ChecksumValidator
  - sumchecker.NoChecksumFoundError

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:f937932c1966f7c7847661dab6e7865e52b5d0d2e292282e4931a986434e3095","contract":["sumchecker exports function and error classes ChecksumMismatchError, ChecksumParseError, NoChecksumFoundError, and ChecksumValidator","sumchecker validates files matching sha256 checksums in specified checksum file and resolves successfully","sumchecker accepts a single filename string or an array of filename strings","ChecksumValidator validate, validateFile, and validateFiles resolve successfully on valid files","ChecksumValidator respects custom defaultTextEncoding option","sumchecker rejects with ChecksumMismatchError and filename property when file content does not match checksum","sumchecker rejects with NoChecksumFoundError and filename property when target file is not present in checksum file","sumchecker rejects with ChecksumParseError with lineNumber and line properties when checksum file is malformed"],"goal":"verify files against checksum file with sumchecker","kind":"HOW","packages":["pkg:npm/sumchecker@3.0.1"],"schemaVersion":1,"symbols":["sumchecker","sumchecker.ChecksumMismatchError","sumchecker.ChecksumParseError","sumchecker.ChecksumValidator","sumchecker.NoChecksumFoundError"]},"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/sumchecker@3.0.1"],"schemaVersion":1,"subject":"pkg:npm/sumchecker@3.0.1","symbols":["sumchecker","sumchecker.ChecksumMismatchError","sumchecker.ChecksumParseError","sumchecker.ChecksumValidator","sumchecker.NoChecksumFoundError"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-sumchecker-verification",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-sumchecker-verification",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "sumchecker": "3.0.1"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/sumchecker": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/sumchecker/-/sumchecker-3.0.1.tgz",
      "integrity": "sha512-MvjXzkz/BOfyVDkG0oFOtBxHX2u3gKbMHIF/dXblZsgD3BWOFLmHovIpZY7BykJdAjcqRCBi1WYBNdEC9yI7vg==",
      "license": "Apache-2.0",
      "dependencies": {
        "debug": "^4.1.0"
      },
      "engines": {
        "node": ">= 8.0"
      }
    }
  }
}

{
  "name": "sample-sumchecker-verification",
  "version": "1.0.0",
  "private": true,
  "license": "MIT-0",
  "main": "src/index.js",
  "dependencies": {
    "sumchecker": "3.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify files against checksum file with sumchecker",
  "kind": "HOW",
  "packages": [
    "pkg:npm/sumchecker@3.0.1"
  ],
  "symbols": [
    "sumchecker",
    "sumchecker.ChecksumMismatchError",
    "sumchecker.ChecksumParseError",
    "sumchecker.ChecksumValidator",
    "sumchecker.NoChecksumFoundError"
  ]
}

const sumchecker = require('sumchecker');

/**
 * Validates files against a checksum file.
 *
 * @param {string} algorithm - Hash algorithm (e.g., 'sha256').
 * @param {string} checksumFilename - Path to the checksum file.
 * @param {string} baseDir - Base directory containing target files.
 * @param {string|string[]} filesToCheck - Relative paths of files to validate.
 * @returns {Promise<void>} Resolves when valid, rejects on failure.
 */
async function validateChecksum(algorithm, checksumFilename, baseDir, filesToCheck) {
  return sumchecker(algorithm, checksumFilename, baseDir, filesToCheck);
}

/**
 * Creates a ChecksumValidator instance.
 *
 * @param {string} algorithm - Hash algorithm (e.g., 'sha256').
 * @param {string} checksumFilename - Path to the checksum file.
 * @param {object} [options] - Configuration options.
 * @param {string} [options.defaultTextEncoding] - Default text encoding.
 * @returns {sumchecker.ChecksumValidator} ChecksumValidator instance.
 */
function createValidator(algorithm, checksumFilename, options) {
  return new sumchecker.ChecksumValidator(algorithm, checksumFilename, options);
}

module.exports = {
  sumchecker,
  validateChecksum,
  createValidator,
  ChecksumValidator: sumchecker.ChecksumValidator,
  ChecksumMismatchError: sumchecker.ChecksumMismatchError,
  ChecksumParseError: sumchecker.ChecksumParseError,
  NoChecksumFoundError: sumchecker.NoChecksumFoundError
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import crypto from 'node:crypto';

const require = createRequire(import.meta.url);
const {
  sumchecker,
  validateChecksum,
  createValidator,
  ChecksumValidator,
  ChecksumMismatchError,
  ChecksumParseError,
  NoChecksumFoundError
} = require('../src/index.js');
const rawSumchecker = require('sumchecker');

// 1. Verify module exports and error classes
assert.equal(typeof sumchecker, 'function', 'sumchecker must be a function');
assert.strictEqual(sumchecker, rawSumchecker, 'sumchecker must match raw library export');
assert.equal(typeof validateChecksum, 'function', 'validateChecksum helper must be a function');
assert.equal(typeof createValidator, 'function', 'createValidator helper must be a function');
assert.equal(typeof ChecksumValidator, 'function', 'ChecksumValidator must be a constructor function');
assert.strictEqual(ChecksumValidator, rawSumchecker.ChecksumValidator, 'ChecksumValidator must match export');
assert.strictEqual(ChecksumMismatchError, rawSumchecker.ChecksumMismatchError, 'ChecksumMismatchError must match export');
assert.strictEqual(ChecksumParseError, rawSumchecker.ChecksumParseError, 'ChecksumParseError must match export');
assert.strictEqual(NoChecksumFoundError, rawSumchecker.NoChecksumFoundError, 'NoChecksumFoundError must match export');

// Create an isolated temporary test directory
const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sumchecker-contract-'));

try {
  // Setup sample test files
  const fileAContent = 'Hello World from file A\n';
  const fileBContent = 'Binary or text content for file B\n';
  const fileAPath = path.join(testDir, 'fileA.txt');
  const fileBPath = path.join(testDir, 'fileB.txt');

  fs.writeFileSync(fileAPath, fileAContent);
  fs.writeFileSync(fileBPath, fileBContent);

  const hashA = crypto.createHash('sha256').update(fileAContent).digest('hex');
  const hashB = crypto.createHash('sha256').update(fileBContent).digest('hex');

  // Checksum file format: "<hash> <marker><filename>"
  // Marker ' ' (space) is text mode, '*' is binary mode
  const checksumFileValid = path.join(testDir, 'SHA256SUMS');
  fs.writeFileSync(
    checksumFileValid,
    `${hashA}  fileA.txt\n${hashB} *fileB.txt\n`
  );

  // 2. Validate files with sumchecker() function
  await sumchecker('sha256', checksumFileValid, testDir, ['fileA.txt', 'fileB.txt']);
  await sumchecker('sha256', checksumFileValid, testDir, 'fileA.txt');
  await validateChecksum('sha256', checksumFileValid, testDir, ['fileA.txt', 'fileB.txt']);

  // 3. Validate files with ChecksumValidator instance
  const validator = createValidator('sha256', checksumFileValid);
  assert.equal(validator.encoding(false), 'utf8', 'Default encoding for text mode must be utf8');
  assert.equal(validator.encoding(true), 'binary', 'Encoding for binary mode must be binary');

  await validator.validate(testDir, ['fileA.txt', 'fileB.txt']);
  await validator.validateFile(testDir, 'fileA.txt');
  await validator.validateFiles(testDir, ['fileA.txt', 'fileB.txt']);

  // Test custom options
  const customValidator = new ChecksumValidator('sha256', checksumFileValid, { defaultTextEncoding: 'latin1' });
  assert.equal(customValidator.encoding(false), 'latin1', 'Custom defaultTextEncoding must be respected');

  // 4. ChecksumMismatchError when content does not match
  const corruptedFilePath = path.join(testDir, 'corrupt.txt');
  fs.writeFileSync(corruptedFilePath, 'Corrupted file content');
  const mismatchChecksumFile = path.join(testDir, 'SHA256SUMS_MISMATCH');
  fs.writeFileSync(mismatchChecksumFile, `${hashA}  corrupt.txt\n`);

  await assert.rejects(
    async () => {
      await sumchecker('sha256', mismatchChecksumFile, testDir, ['corrupt.txt']);
    },
    (err) => {
      assert.ok(err instanceof ChecksumMismatchError, 'Error must be instance of ChecksumMismatchError');
      assert.equal(err.filename, 'corrupt.txt', 'Error must contain the filename of the mismatched file');
      return true;
    },
    'Should reject with ChecksumMismatchError on hash mismatch'
  );

  // 5. NoChecksumFoundError when target file is not present in checksum file
  await assert.rejects(
    async () => {
      await sumchecker('sha256', checksumFileValid, testDir, ['missing.txt']);
    },
    (err) => {
      assert.ok(err instanceof NoChecksumFoundError, 'Error must be instance of NoChecksumFoundError');
      assert.equal(err.filename, 'missing.txt', 'Error must contain the missing filename');
      return true;
    },
    'Should reject with NoChecksumFoundError for unlisted file'
  );

  // 6. ChecksumParseError when checksum file has invalid syntax
  const malformedChecksumFile = path.join(testDir, 'SHA256SUMS_MALFORMED');
  fs.writeFileSync(malformedChecksumFile, `This is an invalid checksum line\n`);

  await assert.rejects(
    async () => {
      await sumchecker('sha256', malformedChecksumFile, testDir, ['fileA.txt']);
    },
    (err) => {
      assert.ok(err instanceof ChecksumParseError, 'Error must be instance of ChecksumParseError');
      assert.equal(err.lineNumber, 1, 'Error must report correct line number');
      assert.equal(err.line, 'This is an invalid checksum line', 'Error must contain the unparsed line');
      return true;
    },
    'Should reject with ChecksumParseError on malformed checksum file'
  );

  console.log('Contract tests passed successfully.');
} finally {
  fs.rmSync(testDir, { recursive: true, force: true });
}