@arcgis/api-extractor 5.0.0-next.17 → 5.0.0-next.170

package/dist/diff/types.d.ts

@@ -1,66 +1,98 @@
-import { ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiModule, ApiVariableDeclaration } from '../apiJson';
+import type { ApiClassCallSignature, ApiClassConstructor, ApiClassDeclaration, ApiClassField, ApiClassMethod, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiInterfaceDeclaration, ApiMixinDeclaration, ApiModule, ApiVariableDeclaration } from "../apiJson.js";
+
 export interface ApiDiff {
-    modules: ApiModuleDiff[];
+  modules: ApiModuleDiff[];
 }
+
 export interface ApiModuleDiff {
-    path: ApiModule["path"];
-    declarations: ApiDeclarationDiff[];
+  path: ApiModule["path"];
+  declarations: ApiDeclarationDiff[];
 }
+
 export interface ApiDiffBase {
-    name: string;
-    /**
-     * True if this declaration was removed in the new api.json.
-     * If class is removed, members are not listed.
-     * @default false
-     */
-    removed?: true;
-    /**
-     * True if this declaration was added in the new api.json.
-     * If class is added, members are not listed.
-     *
-     * @default false
-     */
-    added?: true;
-    /**
-     * Whether this declaration is deprecated in the new api.json, regardless of
-     * whether it was deprecated in the old api.json.
-     * If the value is a string, it's the reason for the deprecation.
-     * Deprecated takes precedence over added.
-     *
-     * @default false
-     */
-    deprecated?: boolean | string;
+  name: string;
+  /**
+   * True if this declaration was removed in the new api.json.
+   * If class is removed, members are not listed.
+   *
+   * @default false
+   */
+  removed?: true;
+  /**
+   * True if this declaration was added in the new api.json.
+   * If class is added, members are not listed.
+   *
+   * @default false
+   */
+  added?: true;
+  /**
+   * Whether this declaration is deprecated in the new api.json. If declaration
+   * was removed, but was deprecated in the old api.json, this will show the old
+   * deprecation message as it points at the replacement API.
+   * If the value is a string, it's the reason for the deprecation.
+   * Deprecated takes precedence over added.
+   *
+   * @default false
+   */
+  deprecated?: boolean | string;
 }
-export type ApiDeclarationDiff = ApiClassDeclarationDiff | ApiCustomElementDeclarationDiff | ApiFunctionDeclarationDiff | ApiVariableDeclarationDiff;
+
+export type ApiDeclarationDiff = ApiClassDeclarationDiff | ApiCustomElementDeclarationDiff | ApiFunctionDeclarationDiff | ApiInterfaceDeclarationDiff | ApiMixinDeclarationDiff | ApiVariableDeclarationDiff;
+
 export interface ApiClassDeclarationDiff extends ApiDiffBase {
-    kind: ApiClassDeclaration["kind"];
-    /**
-     * Inherited members are not included in the diff.
-     * Also, if entire class is added/removed, members are not included in the diff.
-     */
-    members?: ApiClassMemberDiff[];
-    events?: ApiDiffBase[];
+  kind: ApiClassDeclaration["kind"];
+  /**
+   * Inherited members are not included in the diff.
+   * Also, if entire class is added/removed, members are not included in the diff.
+   */
+  members?: ApiClassMemberDiff[];
+  events?: ApiDiffBase[];
 }
+
+export interface ApiInterfaceDeclarationDiff extends ApiDiffBase {
+  kind: ApiInterfaceDeclaration["kind"];
+  /**
+   * Inherited members are not included in the diff.
+   * Also, if entire class is added/removed, members are not included in the diff.
+   */
+  members?: ApiClassMemberDiff[];
+}
+
+export interface ApiMixinDeclarationDiff extends Omit<ApiClassDeclarationDiff, "kind"> {
+  kind: ApiMixinDeclaration["kind"];
+}
+
 export interface ApiCustomElementDeclarationDiff extends ApiClassDeclarationDiff {
-    /**
-     * Attributes diff is not included as attributes are based on members.
-     */
-    tagName: ApiCustomElementDeclaration["tagName"];
-    slots?: ApiDiffBase[];
-    cssParts?: ApiDiffBase[];
-    cssProperties?: ApiDiffBase[];
-    cssStates?: ApiDiffBase[];
+  /** Attributes diff is not included as attributes are based on members. */
+  tagName: ApiCustomElementDeclaration["tagName"];
+  slots?: ApiDiffBase[];
+  cssParts?: ApiDiffBase[];
+  cssProperties?: ApiDiffBase[];
+  cssStates?: ApiDiffBase[];
 }
-export type ApiClassMemberDiff = ApiClassFieldDiff | ApiClassMethodDiff;
+
+export type ApiClassMemberDiff = ApiClassCallSignatureDiff | ApiClassConstructorDiff | ApiClassFieldDiff | ApiClassMethodDiff;
+
 export interface ApiClassFieldDiff extends ApiDiffBase {
-    kind: ApiClassField["kind"];
+  kind: ApiClassField["kind"];
 }
+
 export interface ApiClassMethodDiff extends ApiDiffBase {
-    kind: ApiClassMethod["kind"];
+  kind: ApiClassMethod["kind"];
+}
+
+export interface ApiClassConstructorDiff extends Omit<ApiDiffBase, "name"> {
+  kind: ApiClassConstructor["kind"];
 }
+
+export interface ApiClassCallSignatureDiff extends Omit<ApiDiffBase, "name"> {
+  kind: ApiClassCallSignature["kind"];
+}
+
 export interface ApiFunctionDeclarationDiff extends ApiDiffBase {
-    kind: ApiFunctionDeclaration["kind"];
+  kind: ApiFunctionDeclaration["kind"];
 }
+
 export interface ApiVariableDeclarationDiff extends ApiDiffBase {
-    kind: ApiVariableDeclaration["kind"];
-}
+  kind: ApiVariableDeclaration["kind"];
+}

package/dist/diffTypes/index.d.ts

@@ -0,0 +1,21 @@
+export interface DiffTypesOptions {
+  /** Path to the original types folder. */
+  originalDtsPath: string;
+  /** Path to the new types folder. */
+  newDtsPath: string;
+  /**
+   * Path to the output markdown file.
+   *
+   * @default "types-diff.md"
+   */
+  outputMdPath: string;
+  /**
+   * Whether to truncate output if the diff is longer than 1000 lines.
+   *
+   * @default true
+   */
+  truncate?: boolean;
+}
+
+/** @param options */
+export function diffTypes(options: DiffTypesOptions): Promise<void>;

package/dist/diffTypes/index.js

@@ -0,0 +1,71 @@
+import { path as s } from "@arcgis/components-build-utils";
+import { execSync as c } from "node:child_process";
+import { mkdir as m, writeFile as d } from "node:fs/promises";
+const a = "diff --new-file --recursive", u = `${a} --unified=2`;
+async function b({
+  originalDtsPath: t,
+  newDtsPath: n,
+  outputMdPath: e = "types-diff.md",
+  truncate: i = !0
+}) {
+  n = s.join(s.resolve(n), "/");
+  const r = c(`${u} ${t} ${n} || true`, {
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024 * 20
+  }).trim();
+  let o = "";
+  if (r.length === 0)
+    console.log("Public types did not change.");
+  else {
+    o = `### Public types changes
+
+🧐 please verify that the changes to the public API/doc below are intentional.
+🟥 If removing/changing APIs, remember the semver promise.
+🟩 If adding APIs, add to release notes.
+
+`;
+    let f = g(r.split(`
+`), n);
+    i && f.length > l && (o += `> [!WARNING]
+> Too many changes. Only displaying the first ${l} lines (total ${f.length}) of the diff. If you need to see complete diff, re-run this command with --no-truncate.
+
+`, f = f.slice(0, l)), o += `${h(f)}
+
+`, console.log(`Wrote diff to ${e}`);
+  }
+  await m(s.dirname(e), { recursive: !0 }), await d(e, o);
+}
+function g(t, n) {
+  for (let e = 0; e < t.length; ++e) {
+    const i = t[e];
+    if (
+      // Make diff smaller by excluding the `diff ...` lines
+      (i.startsWith(a) || // Redundant line - make file header smaller
+      i.startsWith("---") || // Not important
+      i === "\") && (t.splice(e, 1), e--), i.startsWith("+++")
+    ) {
+      const r = i.indexOf("	");
+      let o = i.slice(4, r === -1 ? i.length : r);
+      o.startsWith(n) && (o = o.slice(n.length)), t[e] = `🟦 ${o}`;
+    }
+  }
+  return t;
+}
+const l = 1e3;
+function h(t) {
+  const n = t.length, e = p(t.join(`
+`));
+  return n <= 10 ? e : `<details><summary>See diff</summary>
+
+${e}
+
+</details>`;
+}
+function p(t) {
+  return `\`\`\`diff
+${t}
+\`\`\``;
+}
+export {
+  b as diffTypes
+};

package/dist/extractor/ApiExtractor.d.ts

@@ -0,0 +1,66 @@
+import type ts from "typescript";
+import type { ApiExtractorConfig, ResolvedApiExtractorConfig } from "./config.js";
+import type { ApiExtractorResult, ApiExtractorWatcher } from "./types.js";
+
+/**
+ * ApiExtractor's main JavaScript entrypoint.
+ *
+ * @example
+ * ```js
+ *
+ *  import { loadApiExtractorConfig, mergeApiExtractorConfigs } from "@arcgis/api-extractor/extractor/config";
+ *  import { ApiExtractor } from "@arcgis/api-extractor/extractor/ApiExtractor";
+ *
+ *  const baseConfig = await loadApiExtractorConfig(process.cwd(), "api-extractor.config.ts");
+ *
+ *  // Optionally override parts of the config
+ *  const mergedConfig = mergeApiExtractorConfigs(baseConfig, {
+ *    types: {
+ *      fullTypeCheck: true,
+ *    },
+ *  });
+ *
+ *  const extractor = new ApiExtractor(mergedConfig);
+ *
+ *  const { apiJson, dtsFiles } = await extractor.run();
+ *  // OR, start a watcher:
+ *  const watcher = await extractor.watch();
+ * ```
+ */
+export class ApiExtractor {
+  constructor(rawConfig?: ApiExtractorConfig);
+  readonly config: ResolvedApiExtractorConfig;
+  /**
+   * Number of errors logged during the extraction process.
+   * Errors will be logged using the `config.logger.error` callback if provided.
+   * Otherwise, they will be logged using `console.error`.
+   *
+   * @default 0
+   */
+  errorCount: number;
+  /**
+   * If doing typed extraction or full type check, this will be the ts.Program.
+   * If doing untyped watch, this will be a minimal Program-like object to reuse
+   * SourceFiles for unchanged files.
+   * Otherwise, undefined.
+   */
+  program?: {
+      getSourceFile: ts.Program["getSourceFile"];
+      getSourceFiles: ts.Program["getSourceFiles"];
+      getTypeChecker?: ts.Program["getTypeChecker"];
+  };
+  /**
+   * @deprecated
+   * @default 0
+   */
+  silencedBrokenLinkCount: number;
+  /** The high-level API for running the extractor on the current project. */
+  run(): Promise<ApiExtractorResult>;
+  /**
+   * The high-level API for starting a watch-mode extraction on the current project.
+   * When watching, double check that the configuration options the ApiExtractor
+   * was created with are appropriate for watch mode (disable full type check
+   * and type verifier if not necessary).
+   */
+  watch(): Promise<ApiExtractorWatcher>;
+}

package/dist/extractor/ApiExtractor.js

@@ -0,0 +1,9 @@
+import "../typeScript-DMWUxd36.js";
+import "../worker-BkDzhZMK.js";
+import "./processing/links.js";
+import "typescript";
+import { A as x } from "../ApiExtractor-nkPAVjKb.js";
+import "@arcgis/toolkit/function";
+export {
+  x as ApiExtractor
+};