@arcgis/api-extractor 5.0.0-next.8 → 5.0.0-next.81

package/dist/diffTypes/index.js

@@ -0,0 +1,69 @@
+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,138 @@
+import { ApiClassMethod, ApiClassDeclaration, ApiCustomElementField, ApiDeclaration, ApiEvent, ApiJson, ApiModule, ApiCustomElementDeclaration, ApiFunctionDeclaration, ApiVariableDeclaration, ApiInterfaceDeclaration, ApiObjectLikeDeclaration, ApiCustomElementMember, ApiReference, ApiClassMember, ApiAttribute, ApiSlot, ApiCssPart, ApiCssCustomProperty, ApiCssCustomState, ApiMixinDeclaration, ApiClassField, ApiReferenceWithTypeArguments } from '../apiJson.ts';
+import { default as ts } from 'typescript';
+import { CopyDocDefinitions } from '../types.ts';
+export type ApiExtractorOptions = {
+    sortModules: boolean;
+    /** The path relative to which module.path will be resolved */
+    cwd: string;
+    environment: "development" | "production";
+};
+/**
+ * This is a base abstract class. It should be subclassed to implement the
+ * specific extraction logic.
+ */
+export declare abstract class ApiExtractor {
+    constructor(options: ApiExtractorOptions);
+    options: ApiExtractorOptions;
+    /** File that is currently being extracted */
+    file: ts.SourceFile;
+    /** The module that is currently being produced */
+    apiModule: ApiModule;
+    /** Given an array of TypeScript source files, generate an api.json file */
+    extract(files: readonly ts.SourceFile[]): ApiJson;
+    /**
+     * Hostname of the documentation site for the current environment.
+     */
+    normalizedDocumentationHost: string;
+    /**
+     * Hostname of the documentation site that is not for the current environment.
+     * These references will be replaced by the extractor to point to the
+     * normalizedDocumentationHost instead.
+     *
+     * Use case:
+     * - In source code, link to internal docs only. This gives more up to date
+     *   docs and avoids 404 errors for pages that are not yet part of public
+     *   release.
+     * - In production builds, the URLs are replaced with the public docs hostname.
+     */
+    alternativeDocumentationHost: string;
+    extractModules(files: readonly ts.SourceFile[]): ApiModule[];
+    /**
+     * @param module
+     * @param sourcePath cwd-relative path to the source file (esri/core/Accessor.ts)
+     * @param importPath public import path of the module without package name or file extension (core/Accessor)
+     */
+    extractModule(module: ts.SourceFile, sourcePath?: string, importPath?: string): ApiModule;
+    /**
+     * For a given module, extract all public declarations.
+     */
+    protected extractDeclarations(module: ts.SourceFile): void;
+    /**
+     * For each statement in a module, extract a declaration if it is a public API
+     */
+    protected abstract extractDeclaration(statement: ts.Statement, index: number): ApiDeclaration | undefined;
+    /**
+     * Add ApiModule.exports entry based on ApiDeclaration
+     *
+     * To reduce the size of the api.json, we only add exports entries for web
+     * components or default exports.
+     */
+    addExport(declaration: ApiDeclaration, isDefault: boolean): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["properties"], apiProperty: ApiCustomElementField, apiComponent: ApiObjectLikeDeclaration, apiModule: ApiModule): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["methods"], method: ApiClassMethod, component: ApiObjectLikeDeclaration, apiModule: ApiModule): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["events"], event: ApiEvent, component: ApiObjectLikeDeclaration, apiModule: ApiModule): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["functions"], apiFunction: ApiFunctionDeclaration, apiModule: ApiModule): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["variables"], variable: ApiVariableDeclaration, apiModule: ApiModule): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["classes"], classDeclaration: ApiClassDeclaration, apiModule: ApiModule): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["customElements"], componentDeclaration: ApiCustomElementDeclaration, apiModule: ApiModule): void;
+    copyDoc(errorReportingNode: ts.Node, copyDocDefinitions: CopyDocDefinitions["interfaces"], interfaceDeclaration: ApiInterfaceDeclaration, apiModule: ApiModule): void;
+    /**
+     * Inherit public members from mixins and superclass.
+     *
+     * In cast of Lumina, for this to work, the superclass needs to be in a file
+     * named like a component (src/components/name/name.tsx), even if it is not a
+     * standalone component. See
+     * https://devtopia.esri.com/WebGIS/arcgis-web-components/issues/3212
+     */
+    inheritMembers(moduleName: string, component: ApiClassDeclaration | ApiMixinDeclaration, modules: ApiModule[]): void;
+    /**
+     * Inherit members from a superclass or mixin.
+     */
+    protected inheritMembersFrom(parent: ApiExtractorInheritanceData, destination: ApiClassDeclaration | ApiMixinDeclaration, destinationModuleName: string): void;
+    protected inheritMembersOfKind<T extends ApiAttribute | ApiCssCustomProperty | ApiCssCustomState | ApiCssPart | ApiEvent | ApiSlot>(members: T[] | undefined, parentMembers: T[], parentIndexedMembers: Record<string, T>, inheritedFrom?: ApiReference): T[];
+    resolvedInheritance: Record<string, 
+    /**
+     * `false` means don't inherit (or resolution failed).
+     *
+     * `undefined` means we already inherited the members, but have not yet
+     * computed the inheritance data for this module (almost every class
+     * inherits some class, but only a few are inherited by other classes, so
+     * we compute inheritance data lazily).
+     */
+    ApiExtractorInheritanceData | false | undefined>;
+    noInheritMembers: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Based on the superclass name, find the actual declaration in the modules.
+     */
+    protected resolveInheritance(superClassModule: string, modules: ApiModule[]): ApiExtractorInheritanceData | false;
+    /**
+     * Overwrite point
+     *
+     * FINAL: jsapi-extractor has a more efficient implementation because it
+     * has to deal with inheritance a lot. Unify it with Lumina.
+     */
+    protected findSuperclassDeclaration(moduleName: string, modules: ApiModule[]): readonly [string, ApiClassDeclaration | ApiMixinDeclaration] | false;
+    protected handleEventTypesProperty(_apiMember: ApiClassMember, _apiComponent: ApiClassDeclaration | ApiMixinDeclaration, _moduleName: string): void;
+    /**
+     * This method should check if the super property is an accessor, then the
+     * override property should be promoted to an accessor too.
+     * This is necessary until we migrate to standard decorators since - after
+     * that internal accessor status will match the status in the public typings.
+     */
+    protected maybePromotePropertyToAutoAccessor(_apiProperty: ApiClassField, _superApiProperty: ApiClassField): void;
+    protected maybeResolveMixinBaseClass(_apiReference: ApiReferenceWithTypeArguments, _currentModule: string): ApiInterfaceDeclaration | undefined;
+}
+type ApiExtractorInheritanceData = {
+    inheritanceData: ApiReference;
+    declaration: ApiClassDeclaration | ApiMixinDeclaration;
+    /**
+     * Used for validation only. If class has any settable fields, and class is
+     * extended by another one, require that the class module exports the
+     * `<className>Properties` interface. It will be extended by the superclass'
+     * properties interface.
+     */
+    hasSettableField: boolean;
+    /**
+     * Indexed by name for quick lookup of "overridden" status.
+     * Using a map because we do .get() during constructor of the Map, and because
+     * there are often 10+ items with random access.
+     */
+    indexedMembers: Map<string, ApiClassMember | ApiCustomElementMember | undefined> | undefined;
+    indexedEvents: Record<string, ApiEvent> | undefined;
+    indexedAttributes: Record<string, ApiAttribute> | undefined;
+    indexedSlots: Record<string, ApiSlot> | undefined;
+    indexedCssParts: Record<string, ApiCssPart> | undefined;
+    indexedCssProperties: Record<string, ApiCssCustomProperty> | undefined;
+    indexedCssStates: Record<string, ApiCssCustomState> | undefined;
+};
+export {};

package/dist/extractor/config.d.ts

@@ -0,0 +1,66 @@
+import { CopyDocDefinitions } from '../types.ts';
+export interface ApiExtractorConfig {
+    /**
+     * The environment in which the extractor is running.
+     *
+     * @public
+     * @default "production"
+     */
+    readonly environment?: "development" | "production";
+    /**
+     * The path to the root of the project to extract.
+     *
+     * @public
+     * @default process.cwd()
+     */
+    readonly cwd?: string;
+    /**
+     * @public
+     * @default undefined
+     */
+    readonly copyDocDefinitions?: CopyDocDefinitions;
+    /** @public */
+    readonly typeReplacements?: TypeReplacements;
+    /**
+     * api-extractor automatically discovers files that contain `@public`. Not
+     * having to manually maintain a list of entries saves labor.
+     *
+     * As a performance optimization, you can exclude some directories from
+     * `@public` file discovery. This should be a flat list of folders inside
+     * basePath without slashes or deep paths.
+     *
+     * @public
+     * @example ["tests"]
+     */
+    readonly excludedDirectories?: Set<string>;
+    /** @public */
+    readonly noInheritMembers?: NoInheritMembers;
+}
+/**
+ * Privately, arcgis-js-api has interfaces that mirror some of the most widely
+ * used types. They are in the process of refactoring out many of them. Until
+ * that is complete, this hardcoded table is used to replace the usages of these
+ * interfaces with their concrete types.
+ *
+ * Keep this list minimal. Type replacements have pitfalls:
+ * - In a .ts file there is no indication that a given type will be replaced.
+ *   It can be surprising why some types are replaced and some are not.
+ * - The replaced type is not equivalent (LayerUnion=>Layer). These do affect
+ *   type checking in some cases.
+ * - If the name we are replacing with is already present in the current scope,
+ *   there will be a collision. Detecting such collisions is tricky - extractor
+ *   does it minimally.
+ *
+ * @public
+ * @see https://devtopia.esri.com/WebGIS/arcgis-js-api/discussions/60843
+ * @see https://devtopia.esri.com/WebGIS/arcgis-js-api/issues/69911
+ * @see https://devtopia.esri.com/WebGIS/arcgis-js-api/issues/73395
+ */
+export type TypeReplacements = Record<string, Record<string, readonly [modulePath: string, name: string, type: "default" | "named"] | undefined> | undefined>;
+/**
+ * Don't include these members in each subclass to keep api reference pages cleaner.
+ * These has no typings impact since their inheritance is still done by TypeScript.
+ *
+ * @public
+ */
+export type NoInheritMembers = Readonly<Record<string, readonly string[]>>;

package/dist/index.d.ts

@@ -1,8 +1,12 @@
-export { ApiExtractor, type ApiExtractorOptions } from './extractor';
-export type * from './apiJson';
-export { hasIgnoredModifier, setDefaultFromInitializer, getMemberName, findDecorator } from './utils/astHelpers';
-export { isApiMethod, isApiProperty, globalPackageIdentifier, multipleJsDocTags } from './utils/apiHelpers';
-export { apiExtractorError, apiExtractorErrorCount, apiExtractorErrorFiles, setApiExtractorErrorLogger, type ApiExtractorErrorContext, } from './utils/error';
-export { debugPrintNode, printNode } from './utils/print';
-export type { CopyDocDefinitions } from './types';
-export { symbolToDocs, apiMemberToSynthesizedComments, setApiDocFromJsDoc } from './utils/docHelpers';
+export type * from './apiJson.ts';
+export { ApiExtractor, type ApiExtractorOptions } from './extractor/ApiExtractor.ts';
+export { unsafeGetUndocumentedPrinter, unsafeUndocumentedTs } from './internalTypeScriptApis.ts';
+export type { CopyDocDefinitions, NodeDoc } from './types.ts';
+export { findReferenceRanges, getApiMemberName, getMaybeStaticApiMemberName, getApiNodeLabel, globalPackageIdentifier, isApiMethod, isApiProperty, multipleJsDocTags, naturalSortModules, postProcessLinks, apiExtractorJsDocError, compareClassMembers, compareNamedNodes, compareStrings, } from './utils/apiHelpers.ts';
+export { extractBooleanInitializer, findDecorator, getMemberName, hasIgnoredModifier, setDefaultFromInitializer, getBasename, } from './utils/astHelpers.ts';
+export { alternativeDocumentationHost, normalizedDocumentationHost } from './utils/jsDocHelpers.ts';
+export { apiMemberToNodeDoc, nodeDocToString, nodeDocToSynthesizedComment } from './utils/jsDocPrinter.ts';
+export { setApiDocFromJsDoc, setApiDocFromSymbol, symbolToDocs, getNodeDoc } from './utils/jsDocParser.ts';
+export { typeScriptGlobals, typeScriptGlobalsViewUrlCommonPrefix } from './config/typeReferences/globals.ts';
+export { printClass, printInterface, printMethod, printFunction, printSignature, printProperty, printGetterSetter, printVariable, printTypeAlias, printTypeParameters, } from './utils/partPrinter.ts';
+export { apiExtractorError, apiExtractorErrorCount, resetApiExtractorErrorCount, setApiExtractorErrorLogger, apiExtractorDiagnosticContext, type ApiExtractorErrorContext, } from './utils/error.ts';