flora-colossus 2.0.0

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 pkg:npm/flora-colossus@2.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/flora-colossus@2.0.0

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:349ca229e8b88149b6229ac0173ab7082df7f8627a5cbd40e95d8d2b187406bf","contract":["DepType enum defines numeric values for PROD, DEV, OPTIONAL, DEV_OPTIONAL, and ROOT","depTypeGreater returns true when new dependency type has higher precedence than existing type","depTypeGreater returns false when new dependency type has equal or lower precedence than existing type","childDepType resolves child dependency type relative to parent dependency type","childDepType throws an Error if child dependency type is ROOT","Walker constructor throws an Error if modulePath is not provided as a string","Walker getRootModule returns the configured root module path","Walker walkTree traverses dependencies and discovers root, production, and development modules","Walker walkTree detects native module types for NODE_GYP and PREBUILD configurations","Walker walkTree tolerates missing optional dependencies without throwing","Walker walkTree throws an Error when a required production dependency cannot be found"],"goal":"verify pkg:npm/flora-colossus@2.0.0","kind":"HOW","packages":["pkg:npm/flora-colossus@2.0.0"],"schemaVersion":1},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","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/flora-colossus@2.0.0"],"schemaVersion":1,"subject":"pkg:npm/flora-colossus@2.0.0","verifierAdapter":"node-typescript@1"}

'use strict';

const { Walker, DepType, depTypeGreater, childDepType } = require('flora-colossus');

/**
 * Creates a Walker instance for a module directory.
 * @param {string} rootPath - Root module directory path
 * @returns {Walker}
 */
function createWalker(rootPath) {
  return new Walker(rootPath);
}

module.exports = {
  Walker,
  DepType,
  depTypeGreater,
  childDepType,
  createWalker
};

{
  "name": "sample-flora-colossus",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-flora-colossus",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "flora-colossus": "2.0.0"
      }
    },
    "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/flora-colossus": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/flora-colossus/-/flora-colossus-2.0.0.tgz",
      "integrity": "sha512-dz4HxH6pOvbUzZpZ/yXhafjbR2I8cenK5xL0KtBFb7U2ADsR+OwXifnxZjij/pZWF775uSCMzWVd+jDik2H2IA==",
      "license": "MIT",
      "dependencies": {
        "debug": "^4.3.4",
        "fs-extra": "^10.1.0"
      },
      "engines": {
        "node": ">= 12"
      }
    },
    "node_modules/fs-extra": {
      "version": "10.1.0",
      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz",
      "integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==",
      "license": "MIT",
      "dependencies": {
        "graceful-fs": "^4.2.0",
        "jsonfile": "^6.0.1",
        "universalify": "^2.0.0"
      },
      "engines": {
        "node": ">=12"
      }
    },
    "node_modules/graceful-fs": {
      "version": "4.2.11",
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
      "license": "ISC"
    },
    "node_modules/jsonfile": {
      "version": "6.2.1",
      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
      "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
      "license": "MIT",
      "dependencies": {
        "universalify": "^2.0.0"
      },
      "optionalDependencies": {
        "graceful-fs": "^4.1.6"
      }
    },
    "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/universalify": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
      "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
      "license": "MIT",
      "engines": {
        "node": ">= 10.0.0"
      }
    }
  }
}

{
  "name": "sample-flora-colossus",
  "version": "1.0.0",
  "private": true,
  "description": "verify pkg:npm/flora-colossus@2.0.0",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "flora-colossus": "2.0.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/flora-colossus@2.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/flora-colossus@2.0.0"
  ]
}

'use strict';

const assert = require('assert');
const path = require('path');
const fs = require('fs');
const os = require('os');
const { Walker, DepType, depTypeGreater, childDepType, createWalker } = require('../index.js');

async function run() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'flora-colossus-contract-'));

  try {
    // 1. DepType enum defines numeric values for PROD, DEV, OPTIONAL, DEV_OPTIONAL, and ROOT
    assert.strictEqual(DepType.PROD, 0, 'DepType.PROD must be 0');
    assert.strictEqual(DepType.DEV, 1, 'DepType.DEV must be 1');
    assert.strictEqual(DepType.OPTIONAL, 2, 'DepType.OPTIONAL must be 2');
    assert.strictEqual(DepType.DEV_OPTIONAL, 3, 'DepType.DEV_OPTIONAL must be 3');
    assert.strictEqual(DepType.ROOT, 4, 'DepType.ROOT must be 4');

    // 2. depTypeGreater returns true when new dependency type has higher precedence than existing type
    assert.strictEqual(depTypeGreater(DepType.PROD, DepType.DEV), true, 'PROD must take precedence over DEV');
    assert.strictEqual(depTypeGreater(DepType.OPTIONAL, DepType.DEV), true, 'OPTIONAL must take precedence over DEV');
    assert.strictEqual(depTypeGreater(DepType.PROD, DepType.OPTIONAL), true, 'PROD must take precedence over OPTIONAL');
    assert.strictEqual(depTypeGreater(DepType.ROOT, DepType.PROD), true, 'ROOT must take precedence over PROD');

    // 3. depTypeGreater returns false when new dependency type has equal or lower precedence than existing type
    assert.strictEqual(depTypeGreater(DepType.DEV, DepType.PROD), false, 'DEV must not override PROD');
    assert.strictEqual(depTypeGreater(DepType.DEV, DepType.OPTIONAL), false, 'DEV must not override OPTIONAL');
    assert.strictEqual(depTypeGreater(DepType.PROD, DepType.PROD), false, 'Identical types must return false');

    // 4. childDepType resolves child dependency type relative to parent dependency type
    assert.strictEqual(childDepType(DepType.ROOT, DepType.PROD), DepType.PROD, 'Root child prod must remain PROD');
    assert.strictEqual(childDepType(DepType.ROOT, DepType.DEV), DepType.DEV, 'Root child dev must remain DEV');
    assert.strictEqual(childDepType(DepType.DEV, DepType.OPTIONAL), DepType.DEV_OPTIONAL, 'Dev optional child must become DEV_OPTIONAL');
    assert.strictEqual(childDepType(DepType.PROD, DepType.OPTIONAL), DepType.OPTIONAL, 'Prod optional child must remain OPTIONAL');

    // 5. childDepType throws an Error if child dependency type is ROOT
    assert.throws(
      () => childDepType(DepType.ROOT, DepType.ROOT),
      /Something went wrong, a child dependency can't be marked as the ROOT/,
      'childDepType must reject ROOT as child type'
    );

    // 6. Walker constructor throws an Error if modulePath is not provided as a string
    assert.throws(
      () => new Walker(),
      /modulePath must be provided as a string/,
      'Walker constructor must require string modulePath'
    );
    assert.throws(
      () => new Walker(12345),
      /modulePath must be provided as a string/,
      'Walker constructor must reject non-string modulePath'
    );

    // 7. Walker getRootModule returns the configured root module path
    const walker = createWalker(tmpDir);
    assert.strictEqual(walker.getRootModule(), tmpDir, 'getRootModule must return target path');

    // Setup dummy project tree for walkTree tests
    const rootPkgJson = {
      name: 'sample-project',
      version: '1.0.0',
      dependencies: {
        'prod-pkg': '1.0.0',
        'optional-dep': '1.0.0'
      },
      devDependencies: {
        'dev-pkg': '1.0.0'
      },
      optionalDependencies: {
        'optional-dep': '1.0.0'
      }
    };
    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify(rootPkgJson, null, 2));

    const nodeModulesDir = path.join(tmpDir, 'node_modules');
    fs.mkdirSync(nodeModulesDir, { recursive: true });

    // Setup prod-pkg with binding.gyp (NODE_GYP = 1)
    const prodDir = path.join(nodeModulesDir, 'prod-pkg');
    fs.mkdirSync(prodDir, { recursive: true });
    fs.writeFileSync(path.join(prodDir, 'package.json'), JSON.stringify({
      name: 'prod-pkg',
      version: '1.0.0'
    }, null, 2));
    fs.writeFileSync(path.join(prodDir, 'binding.gyp'), '{}');

    // Setup dev-pkg with prebuild-install dependency (PREBUILD = 2)
    const devDir = path.join(nodeModulesDir, 'dev-pkg');
    fs.mkdirSync(devDir, { recursive: true });
    fs.writeFileSync(path.join(devDir, 'package.json'), JSON.stringify({
      name: 'dev-pkg',
      version: '1.0.0',
      dependencies: {
        'prebuild-install': '7.0.0'
      }
    }, null, 2));

    const prebuildDir = path.join(nodeModulesDir, 'prebuild-install');
    fs.mkdirSync(prebuildDir, { recursive: true });
    fs.writeFileSync(path.join(prebuildDir, 'package.json'), JSON.stringify({
      name: 'prebuild-install',
      version: '7.0.0'
    }, null, 2));

    // 8. Walker walkTree traverses dependencies and discovers root, production, and development modules
    const modules = await walker.walkTree();
    assert(Array.isArray(modules), 'walkTree must return an array of modules');

    const rootModule = modules.find((m) => m.name === 'sample-project');
    const prodModule = modules.find((m) => m.name === 'prod-pkg');
    const devModule = modules.find((m) => m.name === 'dev-pkg');

    assert(rootModule, 'sample-project root module must be found');
    assert.strictEqual(rootModule.depType, DepType.ROOT, 'Root module must have DepType.ROOT');

    assert(prodModule, 'prod-pkg module must be found');
    assert.strictEqual(prodModule.depType, DepType.PROD, 'prod-pkg must have DepType.PROD');

    assert(devModule, 'dev-pkg module must be found');
    assert.strictEqual(devModule.depType, DepType.DEV, 'dev-pkg must have DepType.DEV');

    // 9. Walker walkTree detects native module types for NODE_GYP and PREBUILD configurations
    assert.strictEqual(rootModule.nativeModuleType, 0, 'Root module has no native build');
    assert.strictEqual(prodModule.nativeModuleType, 1, 'prod-pkg with binding.gyp must be NODE_GYP (1)');
    assert.strictEqual(devModule.nativeModuleType, 2, 'dev-pkg with prebuild-install must be PREBUILD (2)');

    // 10. Walker walkTree tolerates missing optional dependencies without throwing
    const optionalModule = modules.find((m) => m.name === 'optional-dep');
    assert.strictEqual(optionalModule, undefined, 'Missing optional dep should be skipped without error');

    // 11. Walker walkTree throws an Error when a required production dependency cannot be found
    const missingDepDir = fs.mkdtempSync(path.join(os.tmpdir(), 'flora-missing-dep-'));
    try {
      fs.writeFileSync(path.join(missingDepDir, 'package.json'), JSON.stringify({
        name: 'missing-dep-test',
        version: '1.0.0',
        dependencies: {
          'uninstalled-dependency': '1.0.0'
        }
      }, null, 2));

      const brokenWalker = new Walker(missingDepDir);
      await assert.rejects(
        async () => {
          await brokenWalker.walkTree();
        },
        /Failed to locate module "uninstalled-dependency"/,
        'Walker must reject when required module is missing'
      );
    } finally {
      fs.rmSync(missingDepDir, { recursive: true, force: true });
    }

    console.log('Contract tests passed successfully.');
    process.exit(0);
  } finally {
    try {
      if (fs.existsSync(tmpDir)) {
        fs.rmSync(tmpDir, { recursive: true, force: true });
      }
    } catch (e) {
      // Ignore cleanup error
    }
  }
}

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