import type { ApiJson, ApiJsonCompiler } from "../apiJson.js";
import type { ApiDiff } from "./types.js";

/**
 * @param oldApiJson
 * @param newApiJson
 * @example
 * ```js
 * import { diffApiJson } from "@arcgis/api-extractor/diff/diffApiJson";
 * import { fetchApiJsonFromNpm } from "@arcgis/api-extractor/diff/fetchApiJsonFromNpm";
 *
 * // Read -next api.json from file system:
 * const apiJson = JSON.parse(
 * readFileSync("packages/map-packages/map-components/dist/docs/api.json", "utf8"),
 * );
 * // Read -latest api.json from NPM
 * const npmApiJson = await fetchApiJsonFromNpm("@arcgis/map-components", "latest");
 *
 * // Compute diff
 * const diff = diffApiJson(npmApiJson, apiJson);
 *
 * // Do something with the diff
 * writeFileSync("api-diff.json", JSON.stringify(diff, null, 2));
 * ```
 */
export function diffApiJson(oldApiJson: Pick<ApiJson, "modules"> & { compiler?: ApiJsonCompiler; }, newApiJson: Pick<ApiJson, "modules"> & { compiler?: ApiJsonCompiler; }): ApiDiff;