Stop checking in generated .d.ts; keep only public API snapshots (#1801)

.gitignore

@@ -5,6 +5,9 @@
 /reports
 npm-debug.log*
 packages/*/build/
+# Generated TypeScript definitions. Build artifacts produced on demand from
+# Flow sources (for npm publish and public API snapshotting); not checked in.
+packages/*/types/
 
 website/build/
 website/i18n/*

flow-typed/microsoft-api-extractor.js

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ * @format
+ */
+
+// Minimal libdef covering only the subset of API Extractor's programmatic API
+// used by scripts/generateApiSnapshots.js. See https://api-extractor.com/.
+declare module '@microsoft/api-extractor' {
+  // The `configObject` accepts API Extractor's `IConfigFile` shape, which is
+  // large and only partially populated by callers; modelled as an inexact
+  // object so any subset of its fields is accepted.
+  declare export type IConfigFile = {...};
+
+  declare export type IExtractorConfigPrepareOptions = {
+    configObject: IConfigFile,
+    // Absolute path from which relative paths in `configObject` are resolved.
+    configObjectFullPath: string | void,
+    // Absolute path to the entry point package's package.json.
+    packageJsonFullPath: string,
+    ...
+  };
+
+  declare export class ExtractorConfig {
+    static prepare(options: IExtractorConfigPrepareOptions): ExtractorConfig;
+    // Load an api-extractor.json config file from disk and prepare it.
+    static loadFileAndPrepare(configJsonFilePath: string): ExtractorConfig;
+  }
+
+  declare export type IExtractorInvokeOptions = {
+    // When true, update the API report on disk; when false (CI), leave it
+    // untouched and flag any difference via `apiReportChanged`.
+    localBuild?: boolean,
+    showVerboseMessages?: boolean,
+    showDiagnostics?: boolean,
+    ...
+  };
+
+  declare export type ExtractorResult = {
+    readonly succeeded: boolean,
+    readonly apiReportChanged: boolean,
+    readonly errorCount: number,
+    readonly warningCount: number,
+    ...
+  };
+
+  declare export class Extractor {
+    static invoke(
+      config: ExtractorConfig,
+      options?: IExtractorInvokeOptions,
+    ): ExtractorResult;
+  }
+}

package.json

@@ -9,9 +9,11 @@
     "@babel/plugin-transform-modules-commonjs": "^7.24.8",
     "@babel/plugin-transform-react-jsx": "^7.25.2",
     "@babel/types": "^7.29.0",
+    "@microsoft/api-extractor": "^7.52.2",
     "@tsconfig/node20": "^20.1.4",
     "@typescript-eslint/eslint-plugin": "^8.59.2",
     "@typescript-eslint/parser": "^8.59.2",
+    "@types/node": "^22.0.0",
     "acorn": "^8.7.1",
     "babel-jest": "^29.7.0",
     "babel-plugin-syntax-hermes-parser": "0.37.0",
@@ -46,8 +48,10 @@
   },
   "scripts": {
     "build-clean": "rm -rf ./packages/*/build",
-    "build": "node ./scripts/build.js",
+    "build": "yarn run build-ts-defs && node ./scripts/build.js",
     "build-ts-defs": "node -r @babel/register ./scripts/generateTypeScriptDefinitions.js",
+    "build-api-snapshots": "node -r @babel/register ./scripts/generateApiSnapshots.js",
+    "verify-api-snapshots": "node -r @babel/register ./scripts/generateApiSnapshots.js --verify",
     "clean-all": "rm -rf ./node_modules && rm -rf ./packages/*/node_modules && yarn run build-clean",
     "lint-fix": "eslint . --fix --cache && prettier --write .",
     "lint": "eslint . --cache && prettier --check .",
@@ -58,7 +62,7 @@
     "test-coverage": "yarn run build && yarn run jest --coverage -i && node scripts/mapCoverage.js",
     "test-smoke": "yarn start build --config packages/metro/src/integration_tests/metro.config.js TestBundle.js --out /tmp/TestBundle",
     "typecheck": "flow check",
-    "typecheck-ts": "tsc --project tsconfig.json",
+    "typecheck-ts": "yarn run build-ts-defs && tsc --project tsconfig.json",
     "update-babel-flow-lib-defs": "node -r @babel/register ./scripts/updateBabelFlowLibraryDefinitions",
     "update-version": "node ./scripts/updateVersion"
   },
@@ -70,8 +74,5 @@
   "dependencies": {},
   "engines": {
     "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
-  },
-  "resolutions": {
-    "**/json5": "2.2.3"
   }
 }

packages/buck-worker-tool/API.md

@@ -0,0 +1,15 @@
+## API Report File for "buck-worker-tool"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { Duplex } from 'node:stream';
+
+export function buckWorker(commands: Commands): Duplex;
+
+export type Command = (argv: Array<string>, structuredArgs: unknown, console: Console) => Promise<void> | void;
+
+export type Commands = {[key: string]: Command};
+
+```

packages/metro-babel-transformer/API.md

@@ -0,0 +1,59 @@
+## API Report File for "metro-babel-transformer"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { BabelFileMetadata } from '@babel/core';
+import type { File as File_2 } from '@babel/types';
+import { transformFromAstSync } from '@babel/core';
+
+export type BabelFileFunctionMapMetadata = Readonly<{
+    names: ReadonlyArray<string>;
+    mappings: string;
+}>;
+
+export type BabelFileImportLocsMetadata = ReadonlySet<string>;
+
+export type BabelTransformer = Readonly<{
+    transform: ($$PARAM_0$$: BabelTransformerArgs) => Readonly<{
+        ast: File_2;
+        functionMap?: BabelFileFunctionMapMetadata;
+        metadata?: MetroBabelFileMetadata;
+    }>;
+    getCacheKey?: (options?: BabelTransformerCacheKeyOptions) => string;
+}>;
+
+export type BabelTransformerArgs = Readonly<{
+    filename: string;
+    options: BabelTransformerOptions;
+    plugins?: BabelTransformOptions['plugins'];
+    src: string;
+}>;
+
+export type BabelTransformerCacheKeyOptions = Readonly<{
+    projectRoot?: string;
+    enableBabelRCLookup?: boolean;
+}>;
+
+export type CustomTransformOptions = {
+    [$$Key$$: string]: unknown;
+};
+
+export function getCacheKey(options?: BabelTransformerCacheKeyOptions): string;
+
+export type MetroBabelFileMetadata = Omit<BabelFileMetadata, 'metro'> & {
+    metro?:
+    | null
+    | undefined
+    | {
+        functionMap?: null | undefined | BabelFileFunctionMapMetadata;
+        unstable_importDeclarationLocs?: null | undefined | BabelFileImportLocsMetadata;
+    };
+};
+
+export function transform($$PARAM_0$$: BabelTransformerArgs): ReturnType<BabelTransformer['transform']>;
+
+export type TransformProfile = 'default' | 'hermes-stable' | 'hermes-canary';
+
+```

packages/metro-cache-key/API.md

@@ -0,0 +1,9 @@
+## API Report File for "metro-cache-key"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+export function getCacheKey(files: ReadonlyArray<string>): string;
+
+```