Skip to content

3D engine that AI agents drive

6.0 KB
Raw Blame
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync, readdirSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, relative } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';

const projectRoot = fileURLToPath(new URL('../', import.meta.url));
const packageExports = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).exports;
const libraryConfig = readFileSync(new URL('../config/vite.lib.config.js', import.meta.url), 'utf8');
const PACKAGE_NAMES = ['crucible', '@codepawlhq/crucible'];

function readText(relativePath) {
  return readFileSync(join(projectRoot, relativePath), 'utf8').replace(/\r\n/g, '\n');
}

function markdownFiles(folder) {
  const found = [];
  for (const entry of readdirSync(join(projectRoot, folder), { withFileTypes: true })) {
    const path = `${folder}/${entry.name}`;
    if (entry.isDirectory()) found.push(...markdownFiles(path));
    else if (entry.name.endsWith('.md')) found.push(path);
  }
  return found;
}

const shippedFiles = [...markdownFiles('docs'), ...markdownFiles('skills')];

/** The import statements inside fenced js blocks: { file, specifier, names }. */
function importsOf(file) {
  const imports = [];
  for (const [, code] of readText(file).matchAll(/```(?:js|javascript|mjs|html)\n([\s\S]*?)```/g)) {
    for (const match of code.matchAll(/import\s+(?:([\w$]+)\s*,?\s*)?(?:\{([^}]*)\}|\*\s+as\s+[\w$]+)?\s*from\s*['"]([^'"]+)['"]/g)) {
      const names = match[2] === undefined
        ? []
        : match[2].split(',').map(name => name.trim().split(/\s+as\s+/)[0]).filter(Boolean);
      imports.push({ file, specifier: match[3], names });
    }
  }
  return imports;
}

const allImports = shippedFiles.flatMap(importsOf);

function packageSubpath(specifier) {
  const name = PACKAGE_NAMES.find(candidate => specifier === candidate || specifier.startsWith(`${candidate}/`));
  return name === undefined ? null : `.${specifier.slice(name.length)}`;
}

/** The source file that the built entry of a package subpath comes from. */
function sourceOfSubpath(subpath) {
  const target = packageExports[subpath];
  if (typeof target !== 'string') return null;
  const entryName = target.match(/^\.\/build\/(.+)\.js$/)?.[1];
  if (subpath === '.') return 'src/index.js';
  const escaped = entryName.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
  const entry = libraryConfig.match(new RegExp(`(?:^|\\s)['"]?${escaped}['"]?:\\s*'([^']+)'`));
  return entry === null ? null : entry[1];
}

test('shipped docs and skills never import a repository path the npm package does not contain', () => {
  const offenders = allImports.filter(item => /^\.{1,2}\//.test(item.specifier));
  assert.deepEqual(offenders.map(item => `${item.file}: ${item.specifier}`), []);
});

test('every package import in docs and skills names a subpath that package.json exports', () => {
  const problems = [];
  for (const item of allImports) {
    const subpath = packageSubpath(item.specifier);
    if (subpath === null) continue;
    if (!Object.hasOwn(packageExports, subpath)) {
      problems.push(`${item.file}: ${item.specifier} is not in package.json exports`);
    } else if (sourceOfSubpath(subpath) === null) {
      problems.push(`${item.file}: ${item.specifier} has no entry in config/vite.lib.config.js`);
    }
  }
  assert.deepEqual(problems, []);
});

test('every named import from a package subpath is exported by that entry', async () => {
  const moduleCache = new Map();
  const problems = [];
  for (const item of allImports) {
    const subpath = packageSubpath(item.specifier);
    const source = subpath === null ? null : sourceOfSubpath(subpath);
    if (source === null || item.names.length === 0) continue;
    if (!moduleCache.has(source)) moduleCache.set(source, await import(pathToFileURL(join(projectRoot, source)).href));
    const exported = moduleCache.get(source);
    for (const name of item.names) {
      if (!(name in exported)) problems.push(`${item.file}: ${name} is not exported by ${item.specifier}`);
    }
  }
  assert.deepEqual(problems, []);
});

test('the export-glb example builds its matrix without a mat4 helper and names the import of clipFromGltfAnimation', () => {
  const text = readText('docs/export-glb.md');
  assert.ok(!/\bmat4\b/.test(text), 'the core exports no mat4; pass a Float32Array');
  assert.match(text, /import \{ clipFromGltfAnimation \} from 'crucible\/addons\/skeleton-pose'/);
});

test('the navmesh example in the terrain guide finds a path as written', async () => {
  const section = readText('docs/terrain.md').split('## Navigation')[1];
  const code = section.match(/```js\n([\s\S]*?)```/)[1];
  const rewritten = code.replace(/from '(crucible\/addons\/[\w-]+)'/g, (_, specifier) => {
    const source = sourceOfSubpath(packageSubpath(specifier));
    return `from '${pathToFileURL(join(projectRoot, source)).href}'`;
  });
  const folder = mkdtempSync(join(tmpdir(), 'crucible-doc-'));
  try {
    const file = join(folder, 'example.mjs');
    writeFileSync(file, `${rewritten}\nexport { points, length };\n`);
    const result = await import(pathToFileURL(file).href);
    assert.ok(result.points.length > 1, `no path came back; ran from ${relative(projectRoot, file)}`);
    assert.ok(result.length > 0);
  } finally {
    rmSync(folder, { recursive: true, force: true });
  }
});

test('the MCP limits table agrees with the scene cap stated in the same guide', () => {
  const text = readText('docs/mcp.md');
  assert.match(text, /keeps up to 4 scenes open, within 96 MiB/);
  assert.ok(!/Active render scenes \| 1 \|/.test(text));
  assert.match(text, /\| Open scenes \| 4, within 96 MiB/);
});

test('the agent workflow guide describes the capabilities index and tells the reader to pass a topic', () => {
  const text = readText('docs/learn/agent-workflows.md');
  assert.ok(!/about 24 KB/.test(text), 'scene_capabilities no longer returns 24 KB');
  assert.match(text, /topic: 'sceneLimits'/);
  assert.match(text, /topic: 'unsupported'/);
});