file-entry-cache 8.0.0: create

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.create 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.create

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:a0aa52151df73ad36d4004228e08ae5c8d1d02db2feab2a57f84608538de60be","contract":["fileEntryCache.create returns a cache instance with tracking methods","create tracks new files as changed and unchanged files after reconcile","create detects file content modification when mtime and size change","create getUpdatedFiles returns list of modified files","create allows storing custom metadata in file descriptor across reconciles","create removeEntry resets tracked state for a specific file","create deleteCacheFile removes persisted cache file from disk","create with useChecksum true tracks file changes via MD5 content hash","create destroy clears in-memory tracking and removes persisted file"],"goal":"verify file-entry-cache.create 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.create"]},"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.create"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-file-entry-cache-create",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-file-entry-cache-create",
      "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",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of file-entry-cache.create 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.create in pkg:npm/file-entry-cache@8.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/file-entry-cache@8.0.0"
  ],
  "symbols": [
    "file-entry-cache.create"
  ]
}

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

/**
 * Creates or loads a file entry cache instance.
 * @param {string} cacheId - Cache identifier.
 * @param {string} [cacheDir] - Directory where cache file is stored.
 * @param {boolean} [useChecksum=false] - Whether to use checksums instead of mtime/size.
 * @returns {object} Cache instance.
 */
function createCache(cacheId, cacheDir, useChecksum = false) {
  return fileEntryCache.create(cacheId, cacheDir, useChecksum);
}

module.exports = {
  fileEntryCache,
  createCache
};

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, createCache } = require('../src/index.js');

// 1. fileEntryCache.create is a function that returns a cache instance
assert.strictEqual(typeof fileEntryCache.create, 'function', 'fileEntryCache.create should be a function');
assert.strictEqual(typeof createCache, 'function', 'createCache 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, 'hello world 1');
  fs.writeFileSync(file2, 'hello world 2');

  // 2. create returns cache instance with tracking methods
  const cacheDir = path.join(sandbox, '.cache_dir');
  const cache = createCache('demo_cache', cacheDir, 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');

  // 3. create 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');
  cache.reconcile();
  assert.strictEqual(cache.hasFileChanged(file1), false, 'Reconciled file should report unchanged');
  assert.strictEqual(cache.hasFileChanged(file2), false, 'Reconciled file should report unchanged');

  // 4. create detects file content modification when mtime and size change
  const stat1 = fs.statSync(file1);
  fs.writeFileSync(file1, 'hello world 1 - updated with more content');
  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');

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

  // 5. create allows storing custom metadata in file descriptor across reconciles
  const desc2 = cache.getFileDescriptor(file2);
  desc2.meta.data = { processed: true, score: 99 };
  cache.reconcile();

  // Reload cache from same cacheId and cacheDir
  const reloadedCache = createCache('demo_cache', cacheDir, false);
  const reloadedDesc2 = reloadedCache.getFileDescriptor(file2);
  assert.ok(reloadedDesc2 && reloadedDesc2.meta && reloadedDesc2.meta.data, 'Metadata should persist');
  assert.strictEqual(reloadedDesc2.meta.data.processed, true);
  assert.strictEqual(reloadedDesc2.meta.data.score, 99);

  // 6. create removeEntry resets tracked state for a specific file
  reloadedCache.removeEntry(file2);
  assert.strictEqual(reloadedCache.hasFileChanged(file2), true, 'Removed entry should be detected as changed');

  // 7. create deleteCacheFile removes persisted cache file from disk
  const cacheFilePath = path.join(cacheDir, 'demo_cache');
  assert.strictEqual(fs.existsSync(cacheFilePath), true, 'Cache file should exist on disk');
  reloadedCache.deleteCacheFile();
  assert.strictEqual(fs.existsSync(cacheFilePath), false, 'Cache file should be deleted');

  // 8. create with useChecksum true tracks file changes via MD5 content hash
  const fileHash = path.join(sandbox, 'hash_test.txt');
  fs.writeFileSync(fileHash, 'original hash content');
  const checksumCache = createCache('checksum_cache', cacheDir, true);
  const hashDesc = checksumCache.getFileDescriptor(fileHash);
  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(checksumCache.hasFileChanged(fileHash), false, 'File should be unchanged after reconcile');

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

  // 9. create destroy clears in-memory tracking and removes persisted file
  const checksumCacheFile = path.join(cacheDir, 'checksum_cache');
  assert.strictEqual(fs.existsSync(checksumCacheFile), true, 'Checksum cache file should exist on disk');
  checksumCache.destroy();
  assert.strictEqual(fs.existsSync(checksumCacheFile), false, 'Destroy should delete cache file from disk');
} finally {
  fs.rmSync(sandbox, { recursive: true, force: true });
}

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