Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
5.3 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Generate the published type surface from the JSDoc source of truth.
 *
 * Functions own their types: a leaf's `@returns` + its colocated `.type.mjs`
 * typedefs ARE the contract. This script runs TypeScript's `tsc` script
 * through this Node, with no shell and no `pnpm` on PATH. It runs it over the
 * source trees (allowJs + checkJs + declaration + emitDeclarationOnly) into a
 * throwaway temp dir. Then it copies the emitted `.d.mts` trees back beside
 * their sources, so relative imports and shared `types` declarations resolve.
 * `api/index.d.mts` is the entry `package.json` exports["./api"].types
 * points at.
 *
 * Three trees are emitted (see TREES): `api` and `authoring` are published
 * entry points, and `foundation` is included because the `api` declarations
 * re-export from it — without it a consumer resolving those re-exports hits
 * TS7016 on the packed surface.
 *
 * The emitted `.d.mts` are NOT committed (they're gitignored, like the other
 * packages' `dist/`). This script runs automatically at `prepack`, so
 * `pnpm pack`/`pnpm publish` always ships a freshly generated, in-sync surface.
 * Run `pnpm sync:api-types` to produce them locally; the published surface is
 * verified end-to-end by `.github/scripts/cli-api-types-verify.mjs`.
 *
 * @position packages/cli/scripts — build tooling; not shipped runtime
 */

import {execFileSync} from 'node:child_process';
import * as fs from 'node:fs';
import {createRequire} from 'node:module';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';

const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');

/**
 * The source trees whose `.mjs` JSDoc is the contract. Emitted in one tsc pass
 * (they share types), then copied back beside their sources.
 *
 * `foundation` is here because the published `./api` declarations re-export
 * from it (e.g. api/template re-exports the template adapter): a consumer
 * resolving those re-exports needs foundation's declarations too, or it hits
 * TS7016 on the packed surface.
 */
const TREES = ['api', 'authoring', 'foundation'];

/**
 * Banner prepended to every emitted declaration so it's obvious the file is
 * generated and must not be hand-edited — edit the `.mjs` JSDoc and re-run
 * `pnpm sync:api-types` instead. The `@generated` tag is the standard marker
 * tooling and reviewers recognize.
 * @param {string} tree
 */
const banner = tree =>
  `// @generated by scripts/sync-api-types.mjs from the JSDoc in ${tree}/**/*.mjs.\n` +
  '// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.\n\n';

/**
 * Recursively copy every emitted declaration from `src` to `dest`, preserving
 * structure and prepending the generated banner.
 * @param {string} src
 * @param {string} dest
 * @param {string} tree
 */
function copyDts(src, dest, tree) {
  for (const entry of fs.readdirSync(src, {withFileTypes: true})) {
    const s = path.join(src, entry.name);
    const d = path.join(dest, entry.name);
    if (entry.isDirectory()) {
      copyDts(s, d, tree);
    } else if (entry.name.endsWith('.d.mts')) {
      fs.mkdirSync(dest, {recursive: true});
      fs.writeFileSync(d, banner(tree) + fs.readFileSync(s, 'utf8'));
    }
  }
}

/**
 * Recursively delete every `.d.mts` under `dir` so a regen builds from pure
 * `.mjs` source. Committed declarations sit next to their `.mjs`, and tsc would
 * otherwise resolve an import to the stale `.d.mts` instead of re-inferring from
 * the (possibly edited) source — making generation non-idempotent.
 * @param {string} dir
 */
function cleanDts(dir) {
  if (!fs.existsSync(dir)) return;
  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
    const p = path.join(dir, entry.name);
    if (entry.isDirectory()) cleanDts(p);
    else if (entry.name.endsWith('.d.mts')) fs.rmSync(p);
  }
}

/**
 * The TypeScript compiler's `tsc` script, as the CLI package resolves
 * `typescript`. It runs through this Node: Windows cannot spawn `pnpm` by name
 * without a shell.
 * @returns {string}
 */
function tscScript() {
  const manifest = createRequire(path.join(CLI_ROOT, 'package.json')).resolve(
    'typescript/package.json',
  );
  const {bin} = JSON.parse(fs.readFileSync(manifest, 'utf8'));
  return path.join(path.dirname(manifest), typeof bin === 'string' ? bin : bin.tsc);
}

for (const tree of TREES) cleanDts(path.join(CLI_ROOT, tree));
// Each run emits into a temp directory of its own, passed to tsc as --outDir.
// Two builds on one machine (two checkouts, or two jobs) can run this at once.
// With a shared directory, one run's cleanup deletes what the other just
// emitted.
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-dts-build-'));
try {
  execFileSync(
    process.execPath,
    [tscScript(), '--project', 'tsconfig.api-dts.json', '--outDir', tmp],
    {cwd: CLI_ROOT, stdio: 'inherit'},
  );
  for (const tree of TREES) {
    const emitted = path.join(tmp, 'packages', 'cli', tree);
    if (!fs.existsSync(emitted)) {
      throw new Error(`Expected emitted declarations at ${emitted} — tsc produced nothing.`);
    }
    copyDts(emitted, path.join(CLI_ROOT, tree), tree);
  }
} finally {
  fs.rmSync(tmp, {recursive: true, force: true});
}
console.log(`Synced ${TREES.join(' + ')} declarations from the JSDoc source of truth.`);