file-entry-cache 8.0.0: createFromFile

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 file-entry-cache.createFromFile in pkg:npm/file-entry-cache@8.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/file-entry-cache@8.0.0
Demonstrate these symbols/APIs:
  - file-entry-cache.createFromFile

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:59d4aa4758b5d31f946c179498ab627cda8a34c81958965661badfe5795554bd","contract":["fileEntryCache.createFromFile returns a cache instance with tracking methods","createFromFile tracks new files as changed and unchanged files after reconcile","createFromFile creates cache file at target filePath upon reconcile","createFromFile detects file modifications by mtime and size","createFromFile getUpdatedFiles returns list of modified files","createFromFile persists custom metadata across cache reloads from same file path","createFromFile removeEntry resets tracked state for a specific file","createFromFile deleteCacheFile removes persisted cache file from disk","createFromFile with useChecksum true tracks file changes via MD5 content hash","createFromFile destroy clears in-memory tracking and removes persisted file"],"goal":"verify file-entry-cache.createFromFile in pkg:npm/file-entry-cache@8.0.0","kind":"HOW","packages":["pkg:npm/file-entry-cache@8.0.0"],"schemaVersion":1,"symbols":["file-entry-cache.createFromFile"]},"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/file-entry-cache@8.0.0"],"schemaVersion":1,"subject":"pkg:npm/file-entry-cache@8.0.0","symbols":["file-entry-cache.createFromFile"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-file-entry-cache-create-from-file",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-file-entry-cache-create-from-file",
      "version": "1.0.0",
      "dependencies": {
        "file-entry-cache": "8.0.0"
      }
    },
    "node_modules/file-entry-cache": {
      "version": "8.0.0",
      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
      "integrity": "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==",
      "license": "MIT",
      "dependencies": {
        "flat-cache": "^4.0.0"
      },
      "engines": {
        "node": ">=16.0.0"
      }
    },
    "node_modules/flat-cache": {
      "version": "4.0.1",
      "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-4.0.1.tgz",
      "integrity": "sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==",
      "license": "MIT",
      "dependencies": {
        "flatted": "^3.2.9",
        "keyv": "^4.5.4"
      },
      "engines": {
        "node": ">=16"
      }
    },
    "node_modules/flatted": {
      "version": "3.4.4",
      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.4.tgz",
      "integrity": "sha512-5+ybhBZANEJxaH3X5evAFatUxLfEHSr7n6kYJ+1Qd0mUqr4eu9gIf6GDbWHf8RJijHrjjO8G+la14SlL2SeS1Q==",
      "license": "ISC"
    },
    "node_modules/json-buffer": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
      "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==",
      "license": "MIT"
    },
    "node_modules/keyv": {
      "version": "4.5.4",
      "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
      "integrity": "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==",
      "license": "MIT",
      "dependencies": {
        "json-buffer": "3.0.1"
      }
    }
  }
}

{
  "name": "sample-file-entry-cache-create-from-file",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of file-entry-cache.createFromFile in pkg:npm/file-entry-cache@8.0.0",
  "main": "src/index.js",
  "dependencies": {
    "file-entry-cache": "8.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify file-entry-cache.createFromFile in pkg:npm/file-entry-cache@8.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/file-entry-cache@8.0.0"
  ],
  "symbols": [
    "file-entry-cache.createFromFile"
  ]
}

const fileEntryCache = require('file-entry-cache');

/**
 * Creates or loads a file entry cache using a target file path.
 *
 * @param {string} filePath - Path to the cache file (dirname is used as cache directory, basename as cache ID).
 * @param {boolean} [useChecksum=false] - Whether to use MD5 checksums instead of mtime/size.
 * @returns {object} The cache instance.
 */
function createCacheFromFile(filePath, useChecksum = false) {
  return fileEntryCache.createFromFile(filePath, useChecksum);
}

module.exports = {
  fileEntryCache,
  createCacheFromFile
};

import assert from 'node:assert';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const { fileEntryCache, createCacheFromFile } = require('../src/index.js');

// 1. fileEntryCache.createFromFile returns a cache instance with tracking methods
assert.strictEqual(typeof fileEntryCache.createFromFile, 'function', 'fileEntryCache.createFromFile should be a function');
assert.strictEqual(typeof createCacheFromFile, 'function', 'createCacheFromFile helper should be a function');

const sandbox = path.join(__dirname, 'tmp_test_sandbox');
fs.mkdirSync(sandbox, { recursive: true });

try {
  const file1 = path.join(sandbox, 'file1.txt');
  const file2 = path.join(sandbox, 'file2.txt');
  fs.writeFileSync(file1, 'content 1');
  fs.writeFileSync(file2, 'content 2');

  const cacheFilePath = path.join(sandbox, 'cache_store', 'my-cache-file');
  fs.mkdirSync(path.dirname(cacheFilePath), { recursive: true });

  const cache = createCacheFromFile(cacheFilePath, false);
  assert.ok(cache, 'Cache instance should be created');
  assert.strictEqual(typeof cache.hasFileChanged, 'function');
  assert.strictEqual(typeof cache.reconcile, 'function');
  assert.strictEqual(typeof cache.getFileDescriptor, 'function');
  assert.strictEqual(typeof cache.getUpdatedFiles, 'function');
  assert.strictEqual(typeof cache.deleteCacheFile, 'function');
  assert.strictEqual(typeof cache.destroy, 'function');

  // 2. createFromFile tracks new files as changed and unchanged files after reconcile
  assert.strictEqual(cache.hasFileChanged(file1), true, 'New file should report changed');
  assert.strictEqual(cache.hasFileChanged(file2), true, 'New file should report changed');

  // 3. createFromFile creates cache file at target filePath upon reconcile
  assert.strictEqual(fs.existsSync(cacheFilePath), false, 'Cache file should not exist before reconcile');
  cache.reconcile();
  assert.strictEqual(fs.existsSync(cacheFilePath), true, 'Cache file should exist at filePath after reconcile');
  assert.strictEqual(cache.hasFileChanged(file1), false, 'Reconciled file should report unchanged');
  assert.strictEqual(cache.hasFileChanged(file2), false, 'Reconciled file should report unchanged');

  // 4. createFromFile detects file modifications by mtime and size
  const stat1 = fs.statSync(file1);
  fs.writeFileSync(file1, 'content 1 modified with additional bytes');
  fs.utimesSync(file1, stat1.atime.getTime() / 1000 + 5, stat1.mtime.getTime() / 1000 + 5);
  assert.strictEqual(cache.hasFileChanged(file1), true, 'Modified file should report changed');
  assert.strictEqual(cache.hasFileChanged(file2), false, 'Unmodified file should report unchanged');

  // 5. createFromFile getUpdatedFiles returns list of modified files
  const updated = cache.getUpdatedFiles([file1, file2]);
  assert.strictEqual(updated.length, 1);
  assert.strictEqual(updated[0], file1);

  // 6. createFromFile persists custom metadata across cache reloads from same file path
  const desc2 = cache.getFileDescriptor(file2);
  desc2.meta.data = { tagged: true, score: 42 };
  cache.reconcile();

  const reloadedCache = createCacheFromFile(cacheFilePath, false);
  const reloadedDesc2 = reloadedCache.getFileDescriptor(file2);
  assert.ok(reloadedDesc2 && reloadedDesc2.meta && reloadedDesc2.meta.data, 'Metadata should persist');
  assert.strictEqual(reloadedDesc2.meta.data.tagged, true);
  assert.strictEqual(reloadedDesc2.meta.data.score, 42);

  // 7. createFromFile removeEntry resets tracked state for a specific file
  reloadedCache.removeEntry(file2);
  assert.strictEqual(reloadedCache.hasFileChanged(file2), true, 'Removed entry should report changed');

  // 8. createFromFile deleteCacheFile removes persisted cache file from disk
  assert.strictEqual(fs.existsSync(cacheFilePath), true, 'Cache file should exist before deletion');
  reloadedCache.deleteCacheFile();
  assert.strictEqual(fs.existsSync(cacheFilePath), false, 'Cache file should be deleted from disk');

  // 9. createFromFile with useChecksum true tracks file changes via MD5 content hash
  const checksumFilePath = path.join(sandbox, 'checksum_store', 'checksum-cache-file');
  fs.mkdirSync(path.dirname(checksumFilePath), { recursive: true });
  const hashFile = path.join(sandbox, 'hash_test.txt');
  fs.writeFileSync(hashFile, 'initial hash content');

  const checksumCache = createCacheFromFile(checksumFilePath, true);
  assert.strictEqual(checksumCache.hasFileChanged(hashFile), true, 'Hash file should report changed initially');
  const hashDesc = checksumCache.getFileDescriptor(hashFile);
  assert.ok(hashDesc.meta && hashDesc.meta.hash, 'Descriptor should contain hash in checksum mode');
  assert.strictEqual(hashDesc.meta.mtime, undefined, 'Descriptor should not store mtime in checksum mode');
  assert.strictEqual(hashDesc.meta.size, undefined, 'Descriptor should not store size in checksum mode');
  checksumCache.reconcile();
  assert.strictEqual(fs.existsSync(checksumFilePath), true, 'Checksum cache file should exist on disk after reconcile');
  assert.strictEqual(checksumCache.hasFileChanged(hashFile), false, 'File should be unchanged after reconcile');

  fs.writeFileSync(hashFile, 'modified hash content');
  assert.strictEqual(checksumCache.hasFileChanged(hashFile), true, 'File with changed content should report changed');

  // 10. createFromFile destroy clears in-memory tracking and removes persisted file
  checksumCache.destroy();
  assert.strictEqual(fs.existsSync(checksumFilePath), false, 'Destroy should delete cache file from disk');
} finally {
  fs.rmSync(sandbox, { recursive: true, force: true });
}

console.log('file-entry-cache.createFromFile contract verification passed.');