galactus 1.0.0: Walker

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 galactus.Walker in pkg:npm/galactus@1.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/galactus@1.0.0
Demonstrate these symbols/APIs:
  - galactus.Walker

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:429b37ec807cd5485d2d6333868f3728ec5e1438a5df0c3fe10514f93b672994","contract":["galactus.Walker constructor creates instance with valid modulePath string and throws Error on invalid or non-string arguments","galactus.Walker.getRootModule returns the configured modulePath","galactus.Walker.walkTree resolves standalone package and assigns DepType.ROOT","galactus.Walker.walkTree traverses production and development dependencies in node_modules","galactus.Walker.walkTree caches walk results across repeated calls","galactus.Walker.walkTree tolerates missing optionalDependencies without failing","galactus.Walker.walkTree rejects with descriptive error when a required dependency is missing from node_modules"],"goal":"verify galactus.Walker in pkg:npm/galactus@1.0.0","kind":"HOW","packages":["pkg:npm/galactus@1.0.0"],"schemaVersion":1,"symbols":["galactus.Walker"]},"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/galactus@1.0.0"],"schemaVersion":1,"subject":"pkg:npm/galactus@1.0.0","symbols":["galactus.Walker"],"verifierAdapter":"node-typescript@1"}

import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const galactus = require('galactus');

export const Walker = galactus.Walker;
export const DestroyerOfModules = galactus.DestroyerOfModules;
export const DepType = galactus.DepType;
export default galactus;

{
  "name": "sample-galactus-walker",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-galactus-walker",
      "version": "1.0.0",
      "dependencies": {
        "galactus": "1.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/galactus": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/galactus/-/galactus-1.0.0.tgz",
      "integrity": "sha512-R1fam6D4CyKQGNlvJne4dkNF+PvUUl7TAJInvTGa9fti9qAv95quQz29GXapA4d8Ec266mJJxFVh82M4GIIGDQ==",
      "license": "MIT",
      "dependencies": {
        "debug": "^4.3.4",
        "flora-colossus": "^2.0.0",
        "fs-extra": "^10.1.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-galactus-walker",
  "version": "1.0.0",
  "type": "module",
  "main": "index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "galactus": "1.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify galactus.Walker in pkg:npm/galactus@1.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/galactus@1.0.0"
  ],
  "symbols": [
    "galactus.Walker"
  ]
}

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

const require = createRequire(import.meta.url);
const galactus = require('galactus');
const { Walker, DepType } = galactus;

// Assertion 1: Walker constructor creates instance and validates arguments
{
  assert.equal(typeof Walker, 'function', 'Walker should be a constructor function');

  assert.throws(
    () => new Walker(),
    /modulePath must be provided as a string/,
    'Walker constructor should throw if modulePath is undefined'
  );
  assert.throws(
    () => new Walker(null),
    /modulePath must be provided as a string/,
    'Walker constructor should throw if modulePath is null'
  );
  assert.throws(
    () => new Walker(123),
    /modulePath must be provided as a string/,
    'Walker constructor should throw if modulePath is not a string'
  );
  assert.throws(
    () => new Walker(''),
    /modulePath must be provided as a string/,
    'Walker constructor should throw if modulePath is empty string'
  );
}

// Assertion 2: getRootModule returns the configured module path
{
  const testPath = '/test/dummy/path';
  const walker = new Walker(testPath);
  assert.equal(walker.getRootModule(), testPath, 'getRootModule must return the modulePath string provided to constructor');
}

// Assertion 3: walkTree discovers root module and assigns DepType.ROOT
{
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'walker-root-test-'));
  try {
    fs.writeFileSync(
      path.join(tmpDir, 'package.json'),
      JSON.stringify({
        name: 'test-standalone-pkg',
        version: '1.0.0',
        dependencies: {}
      })
    );

    const walker = new Walker(tmpDir);
    const modules = await walker.walkTree();

    assert.ok(Array.isArray(modules), 'walkTree must return an array of modules');
    assert.equal(modules.length, 1, 'modules array should contain only root when there are no dependencies');

    const rootMod = modules[0];
    assert.equal(rootMod.name, 'test-standalone-pkg');
    assert.equal(rootMod.path, tmpDir);
    assert.equal(rootMod.depType, DepType.ROOT);
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

// Assertion 4: walkTree traverses production and development dependencies correctly
{
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'walker-deps-test-'));
  try {
    fs.writeFileSync(
      path.join(tmpDir, 'package.json'),
      JSON.stringify({
        name: 'test-parent-pkg',
        version: '1.0.0',
        dependencies: {
          'test-prod-dep': '^1.0.0'
        },
        devDependencies: {
          'test-dev-dep': '^1.0.0'
        }
      })
    );

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

    // Set up test-prod-dep
    const prodDir = path.join(nmDir, 'test-prod-dep');
    fs.mkdirSync(prodDir, { recursive: true });
    fs.writeFileSync(
      path.join(prodDir, 'package.json'),
      JSON.stringify({
        name: 'test-prod-dep',
        version: '1.0.0',
        dependencies: {}
      })
    );

    // Set up test-dev-dep
    const devDir = path.join(nmDir, 'test-dev-dep');
    fs.mkdirSync(devDir, { recursive: true });
    fs.writeFileSync(
      path.join(devDir, 'package.json'),
      JSON.stringify({
        name: 'test-dev-dep',
        version: '1.0.0',
        dependencies: {}
      })
    );

    const walker = new Walker(tmpDir);
    const modules = await walker.walkTree();

    assert.equal(modules.length, 3, 'modules array should contain root, prod, and dev dependencies');

    const rootMod = modules.find((m) => m.name === 'test-parent-pkg');
    assert.ok(rootMod, 'root module must be present');
    assert.equal(rootMod.depType, DepType.ROOT);

    const prodMod = modules.find((m) => m.name === 'test-prod-dep');
    assert.ok(prodMod, 'production dependency must be present');
    assert.equal(prodMod.depType, DepType.PROD);

    const devMod = modules.find((m) => m.name === 'test-dev-dep');
    assert.ok(devMod, 'dev dependency must be present');
    assert.equal(devMod.depType, DepType.DEV);
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

// Assertion 5: walkTree caches result on repeated calls
{
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'walker-cache-test-'));
  try {
    fs.writeFileSync(
      path.join(tmpDir, 'package.json'),
      JSON.stringify({
        name: 'test-cache-pkg',
        version: '1.0.0'
      })
    );

    const walker = new Walker(tmpDir);
    const firstCall = await walker.walkTree();
    const secondCall = await walker.walkTree();

    assert.equal(firstCall, secondCall, 'repeated walkTree calls should return cached module list');
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

// Assertion 6: walkTree tolerates missing optionalDependencies without throwing
{
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'walker-opt-test-'));
  try {
    fs.writeFileSync(
      path.join(tmpDir, 'package.json'),
      JSON.stringify({
        name: 'test-opt-pkg',
        version: '1.0.0',
        optionalDependencies: {
          'missing-optional-dep': '^1.0.0'
        }
      })
    );

    const walker = new Walker(tmpDir);
    const modules = await walker.walkTree();

    assert.equal(modules.length, 1, 'missing optional dependency should be skipped safely');
    assert.equal(modules[0].name, 'test-opt-pkg');
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

// Assertion 7: walkTree rejects when required dependency is missing from node_modules
{
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'walker-missing-test-'));
  try {
    fs.writeFileSync(
      path.join(tmpDir, 'package.json'),
      JSON.stringify({
        name: 'test-missing-pkg',
        version: '1.0.0',
        dependencies: {
          'non-existent-dep': '^1.0.0'
        }
      })
    );

    const walker = new Walker(tmpDir);
    await assert.rejects(
      async () => {
        await walker.walkTree();
      },
      /Failed to locate module "non-existent-dep"/,
      'walkTree should reject with descriptive error if required dependency is missing'
    );
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

console.log('All galactus.Walker contract assertions passed successfully.');