Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

17.3 KB
Raw Blame
#!/usr/bin/env npx tsx

/**
 * Documentation Generator Runner
 *
 * Orchestrates documentation generation across all configured libraries.
 * Reads config.json and runs appropriate generators based on what changed.
 *
 * Usage:
 *   pnpm --dir docs docs:generate                  # Generate all enabled docs
 *   pnpm --dir docs docs:check                     # Check for drift (CI mode)
 *   pnpm --dir docs docs:check:lume                # Check one library
 *   pnpm --dir docs docs:list                      # List configured generators
 */

import { execSync, spawnSync } from 'child_process';
import * as fs from 'fs';
import * as path from 'path';
import { parseArgs } from 'node:util';

// ============================================================================
// Types
// ============================================================================

interface GeneratorOutput {
  type: string;
  outputFile: string;
  extractCommand: string | null;
}

interface GeneratorConfig {
  name: string;
  language: string;
  sourcePath: string;
  docsOutputPath: string;
  generatorScript: string;
  watchPaths: string[];
  buildCommand: string | null;
  buildDirectory: string;
  extractionMethod: string;
  outputs: GeneratorOutput[];
  enabled: boolean;
  notes?: string;
}

interface Config {
  description: string;
  generators: Record<string, GeneratorConfig>;
}

// ============================================================================
// Configuration
// ============================================================================

const ROOT_DIR = path.resolve(__dirname, '../..');
const CONFIG_PATH = path.join(__dirname, 'config.json');
const DOCS_TSX_PATH = path.join(ROOT_DIR, 'docs', 'node_modules', 'tsx', 'dist', 'cli.mjs');
const SHARED_GENERATOR_FILES = new Set([
  'scripts/docs-generators/runner.ts',
  // Shared rendering helpers every generator uses.
  'scripts/docs-generators/lib/mdx.ts',
  'scripts/docs-generators/lib/cli-mdx.ts',
  'scripts/docs-generators/lib/mcp-mdx.ts',
  'scripts/docs-generators/lib/headers.ts',
  'scripts/docs-generators/prose-style.ts',
  'scripts/docs-generators/config.json',
  '.github/workflows/ci-check-docs.yml',
  '.gitattributes',
  'docs/package.json',
  'docs/pnpm-lock.yaml',
]);

// ============================================================================
// Main
// ============================================================================

async function main() {
  const { values } = parseArgs({
    options: {
      help: { type: 'boolean' },
      list: { type: 'boolean' },
      library: { type: 'string' },
      check: { type: 'boolean' },
      'check-only': { type: 'boolean' },
      changed: { type: 'boolean' },
      'changed-files-file': { type: 'string' },
      'test-routing': { type: 'boolean' },
    },
  });
  if (values.help) {
    console.log(`Usage: pnpm --dir docs docs:generate [options]

  --help                       Show this help without running generators
  --list                       List configured generators
  --library <name>             Run one configured generator
  --check, --check-only         Check for documentation drift
  --changed                    Select generators from changed files
  --changed-files-file <path>   Print generators selected by a changed-file list
  --test-routing               Verify generator routing`);
    return;
  }

  const checkOnly = Boolean(values.check || values['check-only']);
  const changedFilesFile = values['changed-files-file'];
  const specificLibrary = values.library;

  // Load config
  if (!fs.existsSync(CONFIG_PATH)) {
    console.error(`❌ Config file not found: ${CONFIG_PATH}`);
    process.exit(1);
  }

  const config: Config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));

  if (values['test-routing']) {
    testGeneratorRouting(config);
    return;
  }

  if (changedFilesFile !== undefined) {
    if (!fs.existsSync(changedFilesFile)) {
      console.error(`Changed-files input not found: ${changedFilesFile}`);
      process.exit(1);
    }
    const changedFiles = fs.readFileSync(changedFilesFile, 'utf-8').split(/\r?\n/).filter(Boolean);
    console.log(selectGenerators(config, changedFiles).join(' '));
    return;
  }

  console.log('📚 Documentation Generator Runner');
  console.log('==================================\n');

  // List mode
  if (values.list) {
    listGenerators(config);
    return;
  }

  // Determine which generators to run
  let generatorsToRun: string[] = [];

  if (specificLibrary !== undefined) {
    if (!config.generators[specificLibrary]) {
      console.error(`❌ Unknown library: ${specificLibrary}`);
      console.log('\nAvailable libraries:', Object.keys(config.generators).join(', '));
      process.exit(1);
    }
    generatorsToRun = [specificLibrary];
  } else if (values.changed) {
    generatorsToRun = getChangedGenerators(config);
    if (generatorsToRun.length === 0) {
      console.log('✅ No documentation-related changes detected.');
      return;
    }
  } else {
    // Run all enabled generators
    generatorsToRun = Object.entries(config.generators)
      .filter(([_, cfg]) => cfg.enabled)
      .map(([key, _]) => key);
  }

  if (generatorsToRun.length === 0) {
    console.log('⚠️  No generators to run. Enable generators in config.json.');
    return;
  }

  console.log(`📋 Generators to run: ${generatorsToRun.join(', ')}\n`);

  // Run generators
  let hasErrors = false;

  for (const generatorKey of generatorsToRun) {
    const generator = config.generators[generatorKey];

    console.log(`\n${'='.repeat(50)}`);
    console.log(`📦 ${generator.name} (${generatorKey})`);
    console.log(`${'='.repeat(50)}\n`);

    if (!generator.enabled) {
      console.log(`⏭️  Skipped (disabled)`);
      if (generator.notes) {
        console.log(`   Note: ${generator.notes}`);
      }
      continue;
    }

    const success = await runGenerator(generator, generatorKey, checkOnly);
    if (!success) {
      hasErrors = true;
    }
  }

  // Summary
  console.log(`\n${'='.repeat(50)}`);
  if (hasErrors) {
    console.error('❌ Some generators failed or detected drift.');
    if (checkOnly) {
      console.log("\n💡 Run 'pnpm --dir docs docs:generate' to update documentation");
    }
    process.exit(1);
  } else {
    console.log('✅ All documentation is up to date!');
  }
}

// ============================================================================
// Generator Execution
// ============================================================================

async function runGenerator(
  generator: GeneratorConfig,
  key: string,
  checkOnly: boolean
): Promise<boolean> {
  const generatorPath = path.join(ROOT_DIR, generator.generatorScript);

  // Check if generator script exists
  if (!fs.existsSync(generatorPath)) {
    console.log(`⚠️  Generator script not found: ${generator.generatorScript}`);
    console.log(`   Create this file to enable documentation generation.`);
    return true; // Not an error, just not implemented
  }

  try {
    // Use the docs app's lockfile-installed tsx; never fall back to npx downloads.
    requireDocsTsx();
    const args = checkOnly ? ['--check'] : [];
    const result = spawnSync(process.execPath, [DOCS_TSX_PATH, generatorPath, ...args], {
      cwd: ROOT_DIR,
      stdio: 'inherit',
      encoding: 'utf-8',
    });

    return result.status === 0;
  } catch (error) {
    console.error(`❌ Error running generator for ${key}:`, error);
    return false;
  }
}

// ============================================================================
// Changed Files Detection (for CI)
// ============================================================================

function requireDocsTsx(): string {
  if (!fs.existsSync(DOCS_TSX_PATH)) {
    throw new Error(
      `Pinned tsx executable not found at ${DOCS_TSX_PATH}. Run pnpm --dir docs install --frozen-lockfile.`
    );
  }

  const packagePath = path.join(ROOT_DIR, 'docs', 'node_modules', 'tsx', 'package.json');
  const lockfilePath = path.join(ROOT_DIR, 'docs', 'pnpm-lock.yaml');
  const installedVersion = JSON.parse(fs.readFileSync(packagePath, 'utf-8')).version as string;
  const lockfile = fs.readFileSync(lockfilePath, 'utf-8');

  if (!lockfile.includes(`tsx@${installedVersion}:`)) {
    throw new Error(`Installed tsx ${installedVersion} is not pinned by docs/pnpm-lock.yaml`);
  }

  return installedVersion;
}

function globToRegExp(glob: string): RegExp {
  let pattern = '';

  for (let index = 0; index < glob.length; index += 1) {
    const character = glob[index];

    if (character === '*' && glob[index + 1] === '*') {
      if (glob[index + 2] === '/') {
        pattern += '(?:.*/)?';
        index += 2;
      } else {
        pattern += '.*';
        index += 1;
      }
    } else if (character === '*') {
      pattern += '[^/]*';
    } else {
      pattern += character.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
    }
  }

  return new RegExp(`^${pattern}$`);
}

function selectGenerators(config: Config, changedFiles: readonly string[]): string[] {
  const enabledGenerators = Object.entries(config.generators).filter(([_, cfg]) => cfg.enabled);
  const normalizedFiles = changedFiles.map((file) => file.replace(/\\/g, '/'));

  if (normalizedFiles.some((file) => SHARED_GENERATOR_FILES.has(file))) {
    return enabledGenerators.map(([key]) => key);
  }

  return enabledGenerators.flatMap(([key, generator]) => {
    const ownedFiles = new Set([
      generator.generatorScript,
      ...generator.outputs.map((output) =>
        path.posix.join(generator.docsOutputPath, output.outputFile)
      ),
    ]);
    const watchPatterns = generator.watchPaths.map(globToRegExp);
    const selected = normalizedFiles.some(
      (file) =>
        file.startsWith(`${generator.sourcePath}/`) ||
        ownedFiles.has(file) ||
        watchPatterns.some((pattern) => pattern.test(file))
    );

    return selected ? [key] : [];
  });
}

function assertSelection(
  config: Config,
  changedFiles: readonly string[],
  expected: readonly string[]
): void {
  const actual = selectGenerators(config, changedFiles);
  if (actual.join('\n') !== expected.join('\n')) {
    throw new Error(
      `Routing assertion failed for ${changedFiles.join(', ')}: expected ${expected.join(', ')}, got ${actual.join(', ')}`
    );
  }
}

function testGeneratorRouting(config: Config): void {
  const tsxVersion = requireDocsTsx();

  assertSelection(config, ['docs/content/docs/cua-driver/guides/connect-your-agent.mdx'], []);
  assertSelection(
    config,
    [
      'libs/cua-driver/rust/crates/cua-driver/src/main.rs',
      'docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx',
      'scripts/docs-generators/cua-driver.ts',
    ],
    ['cua-driver']
  );
  // Every platform's registry snapshot and every generated page routes to it.
  for (const file of [
    'scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json',
    'scripts/docs-generators/headers/cua-driver/mcp-tools.md',
    'docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx',
    'docs/content/docs/cua-driver/reference/index.mdx',
  ]) {
    assertSelection(config, [file], ['cua-driver']);
  }
  assertSelection(
    config,
    [
      'libs/cua-bench/cua_bench/cli/commands/run.py',
      'libs/cua-bench/cua_bench/results.py',
      'docs/content/docs/cua-bench/reference/cli.mdx',
      'scripts/docs-generators/extract_cb_docs.py',
    ],
    ['cua-bench']
  );
  assertSelection(config, ['docs/content/docs/cua-bench/guides/benchmarks.mdx'], []);
  assertSelection(
    config,
    [
      'libs/lume/src/Commands/List.swift',
      'docs/content/docs/lume/reference/http-api.mdx',
      'scripts/docs-generators/lume.ts',
    ],
    ['lume']
  );
  assertSelection(
    config,
    [
      'libs/python/cua-sandbox/cua_sandbox/image.py',
      'docs/content/docs/cua-sdk/reference/os-image-catalog.mdx',
      'scripts/docs-generators/sandbox-facts.json',
    ],
    ['sandbox', 'cua-sdk-python']
  );
  assertSelection(
    config,
    [
      'libs/cua/crates/cua-cli/src/main.rs',
      'docs/content/docs/cua-cli/reference/mcp-tools.mdx',
      'scripts/docs-generators/cua-cli.ts',
    ],
    ['cua-cli']
  );
  assertSelection(config, ['libs/cua/spaces-contract/manifest.json'], ['cua-cli', 'spaces']);
  assertSelection(
    config,
    ['libs/cua/crates/cua-spaces-contract/src/lib.rs', 'docs/content/docs/spaces/reference/agents.mdx', 'scripts/docs-generators/spaces.ts'],
    ['cua-cli', 'spaces']
  );
  assertSelection(config, ['libs/cua/crates/cua-sandbox-core/src/lib.rs'], ['cua-rust']);
  assertSelection(config, ['docs/content/docs/cua-cli/guides/mcp-server.mdx'], []);
  assertSelection(config, ['docs/content/docs/lume/reference/cli.mdx'], ['lume']);
  assertSelection(
    config,
    [
      'libs/cua/crates/cua-sdk/src/native/sandbox.rs',
      'libs/cua/crates/cua-bindgen/src/docs.rs',
      'docs/content/docs/cua-sdk/reference/sandbox/index.mdx',
    ],
    ['cua-sdk', 'cua-rust']
  );
  assertSelection(config, ['libs/cua/crates/cua-sdk/uniffi.toml'], ['cua-sdk', 'cua-rust']);
  // The reference index is the object generator's; the Rust pages read its anchors.
  assertSelection(config, ['docs/content/docs/cua-sdk/reference/index.mdx'], ['cua-sdk', 'cua-rust']);
  // Curated headers and tested examples route to the generator that embeds them.
  assertSelection(config, ['scripts/docs-generators/examples/cua-sdk/Sandboxes.create.py'], ['cua-sdk']);
  assertSelection(config, ['scripts/docs-generators/headers/cua-sdk/python/index.md'], ['cua-sdk-python']);
  assertSelection(
    config,
    [
      'libs/cua/python/src/cua/images.py',
      'docs/content/docs/cua-sdk/reference/python/index.mdx',
      'docs/content/docs/cua-sdk/reference/python/interfaces.mdx',
      'scripts/docs-generators/extract_python_docs.py',
    ],
    ['cua-sdk-python']
  );
  assertSelection(
    config,
    [
      'libs/cua/typescript/src/spaces/thread.ts',
      'libs/cua/typescript/package-lock.json',
      'docs/content/docs/cua-sdk/reference/typescript/spaces.mdx',
    ],
    ['cua-sdk-ts']
  );
  assertSelection(
    config,
    [
      'libs/cua/crates/cua-spaces/src/client/model.rs',
      'scripts/docs-generators/rustdoc-json/src/main.rs',
      'docs/content/docs/cua-sdk/reference/rust/cua-spacesd-client.mdx',
    ],
    ['cua-rust']
  );
  // The Rust pages link UniFFI-exported items to the object pages.
  assertSelection(config, ['docs/content/docs/cua-sdk/reference/spacesd/files.mdx'], ['cua-sdk', 'cua-rust']);
  // Unrelated crates do not trigger it.
  assertSelection(config, ['libs/cua/crates/cua-vmm/src/lib.rs'], []);
  assertSelection(
    config,
    [
      'libs/cua/proto/cua/env/v1/process.proto',
      'libs/cua/crates/cua-proto/src/lib.rs',
      'docs/content/docs/cua-sdk/reference/protocol/env-process.mdx',
    ],
    ['cua-proto']
  );
  assertSelection(config, ['scripts/docs-generators/headers/cua-sdk/protocol/index.md'], ['cua-proto']);
  // A shared file routes to every enabled generator.
  const enabled = Object.entries(config.generators)
    .filter(([, generator]) => generator.enabled)
    .map(([key]) => key);
  assertSelection(config, ['scripts/docs-generators/runner.ts'], enabled);
  assertSelection(config, ['scripts/docs-generators/config.json'], enabled);
  assertSelection(config, ['scripts/docs-generators/lib/mdx.ts'], enabled);
  assertSelection(config, ['scripts/docs-generators/lib/cli-mdx.ts'], enabled);
  assertSelection(config, ['scripts/docs-generators/lib/mcp-mdx.ts'], enabled);

  console.log(`Generator routing assertions passed with pinned tsx ${tsxVersion}`);
}

function getChangedGenerators(config: Config): string[] {
  try {
    // Get changed files from git
    // This works for both PRs (comparing to base) and pushes
    const gitDiff = execSync(
      'git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only HEAD',
      { cwd: ROOT_DIR, encoding: 'utf-8' }
    );

    const changedFiles = gitDiff.split('\n').filter(Boolean);

    console.log(`📝 Changed files: ${changedFiles.length}`);

    const changedGenerators = selectGenerators(config, changedFiles);
    for (const key of changedGenerators) console.log(`   📌 ${key}: changes detected`);
    return changedGenerators;
  } catch (error) {
    console.warn('⚠️  Could not detect changed files, running all generators');
    return Object.entries(config.generators)
      .filter(([_, cfg]) => cfg.enabled)
      .map(([key, _]) => key);
  }
}

// ============================================================================
// List Generators
// ============================================================================

function listGenerators(config: Config): void {
  console.log('Configured Documentation Generators:\n');

  const maxKeyLen = Math.max(...Object.keys(config.generators).map((k) => k.length));

  for (const [key, generator] of Object.entries(config.generators)) {
    const status = generator.enabled ? '✅' : '⏸️ ';
    const paddedKey = key.padEnd(maxKeyLen);
    console.log(`${status} ${paddedKey}  ${generator.name} (${generator.language})`);

    if (!generator.enabled && generator.notes) {
      console.log(`   ${''.padEnd(maxKeyLen)}  └─ ${generator.notes}`);
    }
  }

  console.log('\n');
  console.log('Legend:');
  console.log('  ✅ = Enabled (will run)');
  console.log('  ⏸️  = Disabled (not yet implemented)');
}

// ============================================================================
// Run
// ============================================================================

main().catch((error) => {
  console.error('Error:', error);
  process.exit(1);
});