basic-ftp 5.3.1: FileInfo

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 basic-ftp.FileInfo in pkg:npm/basic-ftp@5.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/basic-ftp@5.3.1
Demonstrate these symbols/APIs:
  - basic-ftp.FileInfo

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:4a3b13edeca9bd44d352a091fde7030812805d47b75d8032b7d2b662902a0bd8","constraints":{"executionContext":"node"},"contract":["FileInfo instantiates with name, unknown type, zero size, empty rawModifiedAt, and undefined optional fields","FileInfo boolean getters isFile, isDirectory, and isSymbolicLink reflect FileType enum values","FileInfo date getter and setter provide backwards compatibility with rawModifiedAt","FileInfo.UnixPermission defines Read, Write, and Execute bitmask values (4, 2, 1)","parseList populates FileInfo with Unix permissions, owner, group, and size from Unix listing format","parseList populates FileInfo with parsed modifiedAt Date, size, and uniqueID from MLSD listing format"],"goal":"verify basic-ftp.FileInfo in pkg:npm/basic-ftp@5.3.1","kind":"HOW","packages":["pkg:npm/basic-ftp@5.3.1"],"schemaVersion":1,"symbols":["basic-ftp.FileInfo"]},"contractCommand":["node","test/contract.mjs"],"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/basic-ftp@5.3.1"],"schemaVersion":1,"subject":"pkg:npm/basic-ftp@5.3.1","symbols":["basic-ftp.FileInfo"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-basic-ftp-fileinfo",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-basic-ftp-fileinfo",
      "version": "1.0.0",
      "dependencies": {
        "basic-ftp": "5.3.1"
      }
    },
    "node_modules/basic-ftp": {
      "version": "5.3.1",
      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.3.1.tgz",
      "integrity": "sha512-bopVNp6ugyA150DDuZfPFdt1KZ5a94ZDiwX4hMgZDzF+GttD80lEy8kj98kbyhLXnPvhtIo93mdnLIjpCAeeOw==",
      "license": "MIT",
      "engines": {
        "node": ">=10.0.0"
      }
    }
  }
}

{
  "name": "sample-basic-ftp-fileinfo",
  "version": "1.0.0",
  "private": true,
  "description": "CodeSampleX sample for basic-ftp FileInfo",
  "main": "src/index.js",
  "dependencies": {
    "basic-ftp": "5.3.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify basic-ftp.FileInfo in pkg:npm/basic-ftp@5.3.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/basic-ftp@5.3.1"
  ],
  "symbols": [
    "basic-ftp.FileInfo"
  ]
}

const { FileInfo, FileType, parseList } = require('basic-ftp');

/**
 * Creates a new FileInfo instance with default attributes.
 *
 * @param {string} name - File name.
 * @returns {FileInfo} FileInfo instance.
 */
function createFileInfo(name) {
  return new FileInfo(name);
}

/**
 * Inspects a FileInfo instance and returns a plain metadata summary object.
 *
 * @param {FileInfo} info - FileInfo instance.
 * @returns {object} Summary of file attributes.
 */
function inspectFileInfo(info) {
  return {
    name: info.name,
    type: info.type,
    size: info.size,
    rawModifiedAt: info.rawModifiedAt,
    modifiedAt: info.modifiedAt,
    permissions: info.permissions,
    hardLinkCount: info.hardLinkCount,
    link: info.link,
    group: info.group,
    user: info.user,
    uniqueID: info.uniqueID,
    isFile: info.isFile,
    isDirectory: info.isDirectory,
    isSymbolicLink: info.isSymbolicLink
  };
}

/**
 * Parses a raw FTP directory listing string into an array of FileInfo instances.
 *
 * @param {string} rawListing - Raw FTP listing (Unix, DOS, or MLSD format).
 * @returns {FileInfo[]} Array of FileInfo instances.
 */
function parseDirectoryListing(rawListing) {
  return parseList(rawListing);
}

module.exports = {
  FileInfo,
  FileType,
  parseList,
  createFileInfo,
  inspectFileInfo,
  parseDirectoryListing
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  FileInfo,
  FileType,
  parseList,
  createFileInfo,
  inspectFileInfo,
  parseDirectoryListing
} = require('../src/index.js');

async function runContractTests() {
  // 1. FileInfo instantiates with name, unknown type, zero size, empty rawModifiedAt, and undefined optional fields
  const file = createFileInfo('example.txt');
  assert.equal(typeof FileInfo, 'function', 'FileInfo must be a constructor function');
  assert.equal(file.name, 'example.txt', 'FileInfo name must match constructor argument');
  assert.equal(file.type, FileType.Unknown, 'Initial type must be FileType.Unknown (0)');
  assert.equal(file.size, 0, 'Initial size must be 0');
  assert.equal(file.rawModifiedAt, '', 'Initial rawModifiedAt must be an empty string');
  assert.equal(file.modifiedAt, undefined, 'Initial modifiedAt must be undefined');
  assert.equal(file.permissions, undefined, 'Initial permissions must be undefined');
  assert.equal(file.hardLinkCount, undefined, 'Initial hardLinkCount must be undefined');
  assert.equal(file.link, undefined, 'Initial link must be undefined');
  assert.equal(file.group, undefined, 'Initial group must be undefined');
  assert.equal(file.user, undefined, 'Initial user must be undefined');
  assert.equal(file.uniqueID, undefined, 'Initial uniqueID must be undefined');

  const summary = inspectFileInfo(file);
  assert.equal(summary.name, 'example.txt');
  assert.equal(summary.isFile, false);
  assert.equal(summary.isDirectory, false);
  assert.equal(summary.isSymbolicLink, false);

  // 2. FileInfo boolean getters isFile, isDirectory, and isSymbolicLink reflect FileType enum values
  file.type = FileType.File;
  assert.equal(file.isFile, true, 'isFile must be true when type is FileType.File');
  assert.equal(file.isDirectory, false, 'isDirectory must be false when type is FileType.File');
  assert.equal(file.isSymbolicLink, false, 'isSymbolicLink must be false when type is FileType.File');

  file.type = FileType.Directory;
  assert.equal(file.isFile, false, 'isFile must be false when type is FileType.Directory');
  assert.equal(file.isDirectory, true, 'isDirectory must be true when type is FileType.Directory');
  assert.equal(file.isSymbolicLink, false, 'isSymbolicLink must be false when type is FileType.Directory');

  file.type = FileType.SymbolicLink;
  assert.equal(file.isFile, false, 'isFile must be false when type is FileType.SymbolicLink');
  assert.equal(file.isDirectory, false, 'isDirectory must be false when type is FileType.SymbolicLink');
  assert.equal(file.isSymbolicLink, true, 'isSymbolicLink must be true when type is FileType.SymbolicLink');

  // 3. FileInfo date getter and setter provide backwards compatibility with rawModifiedAt
  file.date = '2026-08-26 12:00:00';
  assert.equal(file.date, '2026-08-26 12:00:00', 'date getter returns updated rawModifiedAt');
  assert.equal(file.rawModifiedAt, '2026-08-26 12:00:00', 'setting date updates rawModifiedAt property');

  // 4. FileInfo.UnixPermission defines Read, Write, and Execute bitmask values (4, 2, 1)
  assert.equal(FileInfo.UnixPermission.Read, 4, 'UnixPermission.Read must equal 4');
  assert.equal(FileInfo.UnixPermission.Write, 2, 'UnixPermission.Write must equal 2');
  assert.equal(FileInfo.UnixPermission.Execute, 1, 'UnixPermission.Execute must equal 1');

  // 5. parseList populates FileInfo with Unix permissions, owner, group, and size from Unix listing format
  const unixListing = '-rwxr-xr-- 1 user1 group1 1024 Jan 01 12:00 app.bin\r\n';
  const unixFiles = parseDirectoryListing(unixListing);
  assert.equal(Array.isArray(unixFiles), true, 'parseList must return an array');
  assert.equal(unixFiles.length, 1, 'parseList must parse 1 FileInfo item');
  const [unixFile] = unixFiles;
  assert(unixFile instanceof FileInfo, 'Parsed item must be an instance of FileInfo');
  assert.equal(unixFile.name, 'app.bin');
  assert.equal(unixFile.size, 1024);
  assert.equal(unixFile.isFile, true);
  assert.equal(unixFile.user, 'user1');
  assert.equal(unixFile.group, 'group1');
  assert.deepEqual(unixFile.permissions, {
    user: FileInfo.UnixPermission.Read | FileInfo.UnixPermission.Write | FileInfo.UnixPermission.Execute,
    group: FileInfo.UnixPermission.Read | FileInfo.UnixPermission.Execute,
    world: FileInfo.UnixPermission.Read
  });

  // 6. parseList populates FileInfo with parsed modifiedAt Date, size, and uniqueID from MLSD listing format
  const mlsdListing = 'type=file;size=4096;modify=20260826120000;unique=1001U; data.json\r\n';
  const mlsdFiles = parseDirectoryListing(mlsdListing);
  assert.equal(mlsdFiles.length, 1, 'parseList must parse 1 FileInfo item from MLSD');
  const [mlsdFile] = mlsdFiles;
  assert(mlsdFile instanceof FileInfo, 'Parsed item must be an instance of FileInfo');
  assert.equal(mlsdFile.name, 'data.json');
  assert.equal(mlsdFile.size, 4096);
  assert.equal(mlsdFile.isFile, true);
  assert.equal(mlsdFile.uniqueID, '1001U');
  assert(mlsdFile.modifiedAt instanceof Date, 'modifiedAt must be parsed into a Date instance');
  assert.equal(mlsdFile.modifiedAt.getUTCFullYear(), 2026);
  assert.equal(mlsdFile.modifiedAt.getUTCMonth(), 7); // August (0-indexed)
  assert.equal(mlsdFile.modifiedAt.getUTCDate(), 26);

  console.log('All basic-ftp FileInfo contract assertions passed successfully.');
}

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