@mnaoumov/typescript-dev-toolkit 1.3.1 → 2.0.0

package/dist/lib/esm/docs-site/api-doc-types.d.mts

@@ -0,0 +1,157 @@
+/// <reference path="../library-references.d.mts" />
+/**
+ * @file
+ *
+ * Shared data-model types for the API documentation generator.
+ */
+/**
+ * A fenced code block of a markdown text, with the language its fence names (empty when none).
+ */
+export interface CodeSegment {
+    lang: string;
+    text: string;
+    type: 'code';
+}
+/**
+ * A documented enum member.
+ */
+export interface EnumMemberInfo {
+    description: string;
+    name: string;
+    value: string;
+}
+/**
+ * A run of a markdown text: prose, or a fenced code block.
+ */
+export type MarkdownSegment = CodeSegment | ProseSegment;
+/**
+ * A documented property, method, constructor or function signature.
+ */
+export interface MemberInfo {
+    description: string;
+    examples: string[];
+    inheritedFrom: string;
+    isStatic: boolean;
+    name: string;
+    overloadKey: string;
+    parameters: ParameterInfo[];
+    remarks: string;
+    returnDescription: string;
+    returnType: string;
+    signature: string;
+    since: string;
+    type: string;
+}
+/**
+ * A generated page's content and the path it is written to.
+ */
+export interface PageContent {
+    content: string;
+    filePath: string;
+}
+/**
+Frontmatter shared by every generated page. `description` and `signature` are optional because not
+every page has them, but a page that HAS one must emit it: both feed the page's OG card.
+ */
+export interface PageFrontMatter {
+    description?: string | undefined;
+    sidebarLabel: string;
+    signature?: string | undefined;
+    slug: string;
+    title: string;
+}
+/**
+ * A documented parameter.
+ */
+export interface ParameterInfo {
+    description: string;
+    name: string;
+    type: string;
+}
+/**
+ * A run of markdown prose between code blocks.
+ */
+export interface ProseSegment {
+    text: string;
+    type: 'prose';
+}
+/**
+ * The part of a ts-morph method or function the declared return type is read from.
+ */
+export interface ReturnTypeProvider {
+    getReturnType: () => TextProvider;
+    getReturnTypeNode?: () => TextProvider | undefined;
+}
+/**
+ * A collapsible Starlight sidebar group.
+ */
+export interface SidebarEntry {
+    collapsed: boolean;
+    items: (SidebarEntry | SidebarLink)[];
+    label: string;
+}
+/**
+ * A Starlight sidebar link.
+ */
+export interface SidebarLink {
+    label: string;
+    link: string;
+}
+/**
+Recursive tree node for building the sidebar
+ */
+export interface SidebarTreeNode {
+    children: Map<string, SidebarTreeNode>;
+    types: TypeInfo[];
+}
+/**
+ * A ts-morph node or type whose text can be printed.
+ */
+export interface TextProvider {
+    getText: () => string;
+}
+/**
+ * A documented export: a class, interface, enum, type alias, function or variable.
+ */
+export interface TypeInfo {
+    baseTypes: string[];
+    /**
+    For classes: the constructor (public/protected), if any
+     */
+    constructorInfo?: MemberInfo | undefined;
+    description: string;
+    /**
+    For enums: the enum members
+     */
+    enumMembers: EnumMemberInfo[];
+    examples: string[];
+    /**
+    For classes: types in the `implements` clause
+     */
+    implementsTypes: string[];
+    kind: 'class' | 'enum' | 'function' | 'interface' | 'type' | 'variable';
+    methods: MemberInfo[];
+    name: string;
+    namespace: string;
+    properties: MemberInfo[];
+    remarks: string;
+    /**
+    For type aliases: the right-hand-side type text
+     */
+    typeAliasText?: string;
+    typeParameters: string[];
+    /**
+    For variables: the declaration keyword (let/const/var)
+     */
+    variableKeyword?: string;
+    /**
+    For variables: the type annotation
+     */
+    variableType?: string;
+}
+/**
+ * An object entry of the `typedoc-plugin-mdn-links` Web API data.
+ */
+export interface WebApiEntry {
+    url: string;
+}

package/dist/lib/esm/docs-site/api-doc-types.mjs

@@ -0,0 +1,6 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFtdLAogICJzb3VyY2VzQ29udGVudCI6IFtdLAogICJtYXBwaW5ncyI6ICIiLAogICJuYW1lcyI6IFtdCn0K

package/dist/lib/esm/docs-site/api-docs.d.mts

@@ -0,0 +1,34 @@
+/// <reference path="../library-references.d.mts" />
+/**
+ * @file
+ *
+ * The API documentation generator: walks a package's `src`, extracts every documentable exported declaration via
+ * ts-morph, and writes Starlight-compatible MDX pages plus a sidebar JSON. The output tree mirrors the package's
+ * module structure: a type's namespace is its source path relative to `src`, which is also its import subpath.
+ */
+import type { ApiDocSettings } from './api-doc-settings.mjs';
+/**
+ * Options for {@link generateApiDocs}.
+ */
+export interface GenerateApiDocsParams {
+    /**
+     * The repository root: the folder holding `tsconfig.json` and `node_modules`.
+     */
+    readonly rootDirectory: string;
+    /**
+     * The settings every page and link is rendered with.
+     */
+    readonly settings: ApiDocSettings;
+    /**
+     * The folder whose modules are documented, normally `<root>/src`.
+     */
+    readonly sourceDirectory: string;
+}
+/**
+ * Generates the API reference pages and the sidebar.
+ *
+ * Skips the work when neither the sources, the settings nor the generator changed since the last run.
+ *
+ * @param options - The options.
+ */
+export declare function generateApiDocs(options: GenerateApiDocsParams): Promise<void>;

package/dist/lib/esm/docs-site/api-docs.mjs

@@ -0,0 +1,139 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+(function () {
+function ensureBrowserProcess() {
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+
+  const existingProcess = globalThis.process;
+
+  if (!existingProcess) {
+    globalThis.process = browserProcess;
+    return;
+  }
+
+  if (existingProcess.versions?.node) {
+    return;
+  }
+
+  const existingProcessRecord = existingProcess;
+
+  for (const [key, value] of Object.entries(browserProcess)) {
+    existingProcessRecord[key] ??= value;
+  }
+
+  existingProcessRecord['browser'] = true;
+}
+
+ensureBrowserProcess();
+})();
+
+import {
+  existsSync,
+  readFileSync
+} from "node:fs";
+import {
+  mkdir,
+  rm,
+  writeFile
+} from "node:fs/promises";
+import {
+  dirname,
+  join,
+  normalize
+} from "node:path";
+import { fileURLToPath } from "node:url";
+import { Project } from "ts-morph";
+import { extractFileOverview } from "./api-doc-jsdoc.mjs";
+import {
+  loadExternalTypeMaps,
+  registerMemberPages,
+  registerRouteSegments
+} from "./api-doc-link-rendering.mjs";
+import { clearPackageDeclarations } from "./api-doc-package-sites.mjs";
+import {
+  appendBacklinksAndWrite,
+  generateMemberPages,
+  generateNamespaceIndexPages,
+  generateOverviewPage,
+  generateSidebarJson
+} from "./api-doc-page-generation.mjs";
+import { configureApiDocs } from "./api-doc-settings.mjs";
+import {
+  collectFunctions,
+  collectPackageDeclarations,
+  collectVariables,
+  computeCacheHash,
+  computeNamespace,
+  findEntryFiles,
+  processSourceFile,
+  registerGenericTypeParams
+} from "./api-doc-source-processing.mjs";
+import { resolveInheritedMembers } from "./api-doc-type-merging.mjs";
+const CACHE_FILE_NAME = ".cache-hash";
+async function generateApiDocs(options) {
+  const { rootDirectory, settings, sourceDirectory } = options;
+  configureApiDocs(settings);
+  loadExternalTypeMaps(rootDirectory);
+  const entryFiles = findEntryFiles(sourceDirectory);
+  console.warn(`Found ${String(entryFiles.length)} entry source files`);
+  const cacheFile = join(settings.outputDirectory, CACHE_FILE_NAME);
+  const currentHash = computeCacheHash(entryFiles, dirname(fileURLToPath(import.meta.url)));
+  if (existsSync(cacheFile) && existsSync(settings.sidebarFile) && readFileSync(cacheFile, "utf-8").trim() === currentHash) {
+    console.warn("Source files and generator unchanged \u2014 skipping generation.");
+    return;
+  }
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    tsConfigFilePath: join(rootDirectory, "tsconfig.json")
+  });
+  const sourceFiles = project.addSourceFilesAtPaths(entryFiles);
+  const types = /* @__PURE__ */ new Map();
+  const moduleOverviews = /* @__PURE__ */ new Map();
+  clearPackageDeclarations();
+  for (const src of sourceFiles) {
+    const namespace = computeNamespace(sourceDirectory, normalize(src.getFilePath()));
+    const overview = extractFileOverview(src);
+    if (overview) {
+      moduleOverviews.set(namespace, overview);
+    }
+    collectPackageDeclarations(src);
+    processSourceFile(src, types, namespace);
+    collectFunctions(src, types, namespace);
+    collectVariables(src, types, namespace);
+  }
+  resolveInheritedMembers(types);
+  for (const info of types.values()) {
+    info.properties.sort((a, b) => a.name.localeCompare(b.name));
+    info.methods.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  registerGenericTypeParams(types);
+  registerRouteSegments(types);
+  registerMemberPages(types);
+  await rm(settings.outputDirectory, { force: true, recursive: true });
+  await mkdir(settings.outputDirectory, { recursive: true });
+  await generateNamespaceIndexPages(types, types, moduleOverviews);
+  const pageContents = /* @__PURE__ */ new Map();
+  for (const [key, info] of types) {
+    pageContents.set(key, await generateOverviewPage(info.name, info, types));
+    if (info.kind === "class" || info.kind === "interface") {
+      await generateMemberPages(info.name, info, types);
+    }
+  }
+  await appendBacklinksAndWrite(pageContents, types);
+  await generateSidebarJson(types);
+  await writeFile(cacheFile, currentHash, "utf-8");
+  console.warn(`Generated docs for ${String(types.size)} types across ${String(moduleOverviews.size)} documented modules`);
+}
+export {
+  generateApiDocs
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9kb2NzLXNpdGUvYXBpLWRvY3MudHMiXSwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBAZmlsZVxuICpcbiAqIFRoZSBBUEkgZG9jdW1lbnRhdGlvbiBnZW5lcmF0b3I6IHdhbGtzIGEgcGFja2FnZSdzIGBzcmNgLCBleHRyYWN0cyBldmVyeSBkb2N1bWVudGFibGUgZXhwb3J0ZWQgZGVjbGFyYXRpb24gdmlhXG4gKiB0cy1tb3JwaCwgYW5kIHdyaXRlcyBTdGFybGlnaHQtY29tcGF0aWJsZSBNRFggcGFnZXMgcGx1cyBhIHNpZGViYXIgSlNPTi4gVGhlIG91dHB1dCB0cmVlIG1pcnJvcnMgdGhlIHBhY2thZ2Unc1xuICogbW9kdWxlIHN0cnVjdHVyZTogYSB0eXBlJ3MgbmFtZXNwYWNlIGlzIGl0cyBzb3VyY2UgcGF0aCByZWxhdGl2ZSB0byBgc3JjYCwgd2hpY2ggaXMgYWxzbyBpdHMgaW1wb3J0IHN1YnBhdGguXG4gKi9cblxuaW1wb3J0IHtcbiAgZXhpc3RzU3luYyxcbiAgcmVhZEZpbGVTeW5jXG59IGZyb20gJ25vZGU6ZnMnO1xuaW1wb3J0IHtcbiAgbWtkaXIsXG4gIHJtLFxuICB3cml0ZUZpbGVcbn0gZnJvbSAnbm9kZTpmcy9wcm9taXNlcyc7XG5pbXBvcnQge1xuICBkaXJuYW1lLFxuICBqb2luLFxuICBub3JtYWxpemVcbn0gZnJvbSAnbm9kZTpwYXRoJztcbmltcG9ydCB7IGZpbGVVUkxUb1BhdGggfSBmcm9tICdub2RlOnVybCc7XG5pbXBvcnQgeyBQcm9qZWN0IH0gZnJvbSAndHMtbW9ycGgnO1xuXG5pbXBvcnQgdHlwZSB7IEFwaURvY1NldHRpbmdzIH0gZnJvbSAnLi9hcGktZG9jLXNldHRpbmdzLnRzJztcbmltcG9ydCB0eXBlIHtcbiAgUGFnZUNvbnRlbnQsXG4gIFR5cGVJbmZvXG59IGZyb20gJy4vYXBpLWRvYy10eXBlcy50cyc7XG5cbmltcG9ydCB7IGV4dHJhY3RGaWxlT3ZlcnZpZXcgfSBmcm9tICcuL2FwaS1kb2MtanNkb2MudHMnO1xuaW1wb3J0IHtcbiAgbG9hZEV4dGVybmFsVHlwZU1hcHMsXG4gIHJlZ2lzdGVyTWVtYmVyUGFnZXMsXG4gIHJlZ2lzdGVyUm91dGVTZWdtZW50c1xufSBmcm9tICcuL2FwaS1kb2MtbGluay1yZW5kZXJpbmcudHMnO1xuaW1wb3J0IHsgY2xlYXJQYWNrYWdlRGVjbGFyYXRpb25zIH0gZnJvbSAnLi9hcGktZG9jLXBhY2thZ2Utc2l0ZXMudHMnO1xuaW1wb3J0IHtcbiAgYXBwZW5kQmFja2xpbmtzQW5kV3JpdGUsXG4gIGdlbmVyYXRlTWVtYmVyUGFnZXMsXG4gIGdlbmVyYXRlTmFtZXNwYWNlSW5kZXhQYWdlcyxcbiAgZ2VuZXJhdGVPdmVydmlld1BhZ2UsXG4gIGdlbmVyYXRlU2lkZWJhckpzb25cbn0gZnJvbSAnLi9hcGktZG9jLXBhZ2UtZ2VuZXJhdGlvbi50cyc7XG5pbXBvcnQgeyBjb25maWd1cmVBcGlEb2NzIH0gZnJvbSAnLi9hcGktZG9jLXNldHRpbmdzLnRzJztcbmltcG9ydCB7XG4gIGNvbGxlY3RGdW5jdGlvbnMsXG4gIGNvbGxlY3RQYWNrYWdlRGVjbGFyYXRpb25zLFxuICBjb2xsZWN0VmFyaWFibGVzLFxuICBjb21wdXRlQ2FjaGVIYXNoLFxuICBjb21wdXRlTmFtZXNwYWNlLFxuICBmaW5kRW50cnlGaWxlcyxcbiAgcHJvY2Vzc1NvdXJjZUZpbGUsXG4gIHJlZ2lzdGVyR2VuZXJpY1R5cGVQYXJhbXNcbn0gZnJvbSAnLi9hcGktZG9jLXNvdXJjZS1wcm9jZXNzaW5nLnRzJztcbmltcG9ydCB7IHJlc29sdmVJbmhlcml0ZWRNZW1iZXJzIH0gZnJvbSAnLi9hcGktZG9jLXR5cGUtbWVyZ2luZy50cyc7XG5cbi8qKlxuICogT3B0aW9ucyBmb3Ige0BsaW5rIGdlbmVyYXRlQXBpRG9jc30uXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgR2VuZXJhdGVBcGlEb2NzUGFyYW1zIHtcbiAgLyoqXG4gICAqIFRoZSByZXBvc2l0b3J5IHJvb3Q6IHRoZSBmb2xkZXIgaG9sZGluZyBgdHNjb25maWcuanNvbmAgYW5kIGBub2RlX21vZHVsZXNgLlxuICAgKi9cbiAgcmVhZG9ubHkgcm9vdERpcmVjdG9yeTogc3RyaW5nO1xuXG4gIC8qKlxuICAgKiBUaGUgc2V0dGluZ3MgZXZlcnkgcGFnZSBhbmQgbGluayBpcyByZW5kZXJlZCB3aXRoLlxuICAgKi9cbiAgcmVhZG9ubHkgc2V0dGluZ3M6IEFwaURvY1NldHRpbmdzO1xuXG4gIC8qKlxuICAgKiBUaGUgZm9sZGVyIHdob3NlIG1vZHVsZXMgYXJlIGRvY3VtZW50ZWQsIG5vcm1hbGx5IGA8cm9vdD4vc3JjYC5cbiAgICovXG4gIHJlYWRvbmx5IHNvdXJjZURpcmVjdG9yeTogc3RyaW5nO1xufVxuXG5jb25zdCBDQUNIRV9GSUxFX05BTUUgPSAnLmNhY2hlLWhhc2gnO1xuXG4vKipcbiAqIEdlbmVyYXRlcyB0aGUgQVBJIHJlZmVyZW5jZSBwYWdlcyBhbmQgdGhlIHNpZGViYXIuXG4gKlxuICogU2tpcHMgdGhlIHdvcmsgd2hlbiBuZWl0aGVyIHRoZSBzb3VyY2VzLCB0aGUgc2V0dGluZ3Mgbm9yIHRoZSBnZW5lcmF0b3IgY2hhbmdlZCBzaW5jZSB0aGUgbGFzdCBydW4uXG4gKlxuICogQHBhcmFtIG9wdGlvbnMgLSBUaGUgb3B0aW9ucy5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGdlbmVyYXRlQXBpRG9jcyhvcHRpb25zOiBHZW5lcmF0ZUFwaURvY3NQYXJhbXMpOiBQcm9taXNlPHZvaWQ+IHtcbiAgY29uc3QgeyByb290RGlyZWN0b3J5LCBzZXR0aW5ncywgc291cmNlRGlyZWN0b3J5IH0gPSBvcHRpb25zO1xuICBjb25maWd1cmVBcGlEb2NzKHNldHRpbmdzKTtcbiAgbG9hZEV4dGVybmFsVHlwZU1hcHMocm9vdERpcmVjdG9yeSk7XG5cbiAgY29uc3QgZW50cnlGaWxlcyA9IGZpbmRFbnRyeUZpbGVzKHNvdXJjZURpcmVjdG9yeSk7XG4gIGNvbnNvbGUud2FybihgRm91bmQgJHtTdHJpbmcoZW50cnlGaWxlcy5sZW5ndGgpfSBlbnRyeSBzb3VyY2UgZmlsZXNgKTtcblxuICBjb25zdCBjYWNoZUZpbGUgPSBqb2luKHNldHRpbmdzLm91dHB1dERpcmVjdG9yeSwgQ0FDSEVfRklMRV9OQU1FKTtcbiAgY29uc3QgY3VycmVudEhhc2ggPSBjb21wdXRlQ2FjaGVIYXNoKGVudHJ5RmlsZXMsIGRpcm5hbWUoZmlsZVVSTFRvUGF0aChpbXBvcnQubWV0YS51cmwpKSk7XG4gIGlmIChleGlzdHNTeW5jKGNhY2hlRmlsZSkgJiYgZXhpc3RzU3luYyhzZXR0aW5ncy5zaWRlYmFyRmlsZSkgJiYgcmVhZEZpbGVTeW5jKGNhY2hlRmlsZSwgJ3V0Zi04JykudHJpbSgpID09PSBjdXJyZW50SGFzaCkge1xuICAgIGNvbnNvbGUud2FybignU291cmNlIGZpbGVzIGFuZCBnZW5lcmF0b3IgdW5jaGFuZ2VkIOKAlCBza2lwcGluZyBnZW5lcmF0aW9uLicpO1xuICAgIHJldHVybjtcbiAgfVxuXG4gIC8vIExvYWQgdmlhIHRoZSByZXBvJ3MgdHNjb25maWcgc28gaW5mZXJyZWQgdHlwZXMgcmVzb2x2ZS5cbiAgY29uc3QgcHJvamVjdCA9IG5ldyBQcm9qZWN0KHtcbiAgICBza2lwQWRkaW5nRmlsZXNGcm9tVHNDb25maWc6IHRydWUsXG4gICAgdHNDb25maWdGaWxlUGF0aDogam9pbihyb290RGlyZWN0b3J5LCAndHNjb25maWcuanNvbicpXG4gIH0pO1xuICBjb25zdCBzb3VyY2VGaWxlcyA9IHByb2plY3QuYWRkU291cmNlRmlsZXNBdFBhdGhzKGVudHJ5RmlsZXMpO1xuXG4gIGNvbnN0IHR5cGVzID0gbmV3IE1hcDxzdHJpbmcsIFR5cGVJbmZvPigpO1xuICBjb25zdCBtb2R1bGVPdmVydmlld3MgPSBuZXcgTWFwPHN0cmluZywgc3RyaW5nPigpO1xuICBjbGVhclBhY2thZ2VEZWNsYXJhdGlvbnMoKTtcblxuICBmb3IgKGNvbnN0IHNyYyBvZiBzb3VyY2VGaWxlcykge1xuICAgIGNvbnN0IG5hbWVzcGFjZSA9IGNvbXB1dGVOYW1lc3BhY2Uoc291cmNlRGlyZWN0b3J5LCBub3JtYWxpemUoc3JjLmdldEZpbGVQYXRoKCkpKTtcbiAgICBjb25zdCBvdmVydmlldyA9IGV4dHJhY3RGaWxlT3ZlcnZpZXcoc3JjKTtcbiAgICBpZiAob3ZlcnZpZXcpIHtcbiAgICAgIG1vZHVsZU92ZXJ2aWV3cy5zZXQobmFtZXNwYWNlLCBvdmVydmlldyk7XG4gICAgfVxuICAgIGNvbGxlY3RQYWNrYWdlRGVjbGFyYXRpb25zKHNyYyk7XG4gICAgcHJvY2Vzc1NvdXJjZUZpbGUoc3JjLCB0eXBlcywgbmFtZXNwYWNlKTtcbiAgICBjb2xsZWN0RnVuY3Rpb25zKHNyYywgdHlwZXMsIG5hbWVzcGFjZSk7XG4gICAgY29sbGVjdFZhcmlhYmxlcyhzcmMsIHR5cGVzLCBuYW1lc3BhY2UpO1xuICB9XG5cbiAgcmVzb2x2ZUluaGVyaXRlZE1lbWJlcnModHlwZXMpO1xuXG4gIGZvciAoY29uc3QgaW5mbyBvZiB0eXBlcy52YWx1ZXMoKSkge1xuICAgIGluZm8ucHJvcGVydGllcy5zb3J0KChhLCBiKSA9PiBhLm5hbWUubG9jYWxlQ29tcGFyZShiLm5hbWUpKTtcbiAgICBpbmZvLm1ldGhvZHMuc29ydCgoYSwgYikgPT4gYS5uYW1lLmxvY2FsZUNvbXBhcmUoYi5uYW1lKSk7XG4gIH1cblxuICByZWdpc3RlckdlbmVyaWNUeXBlUGFyYW1zKHR5cGVzKTtcbiAgcmVnaXN0ZXJSb3V0ZVNlZ21lbnRzKHR5cGVzKTtcbiAgcmVnaXN0ZXJNZW1iZXJQYWdlcyh0eXBlcyk7XG5cbiAgYXdhaXQgcm0oc2V0dGluZ3Mub3V0cHV0RGlyZWN0b3J5LCB7IGZvcmNlOiB0cnVlLCByZWN1cnNpdmU6IHRydWUgfSk7XG4gIGF3YWl0IG1rZGlyKHNldHRpbmdzLm91dHB1dERpcmVjdG9yeSwgeyByZWN1cnNpdmU6IHRydWUgfSk7XG5cbiAgYXdhaXQgZ2VuZXJhdGVOYW1lc3BhY2VJbmRleFBhZ2VzKHR5cGVzLCB0eXBlcywgbW9kdWxlT3ZlcnZpZXdzKTtcblxuICAvLyBQYXNzIDE6IGdlbmVyYXRlIGFsbCBwYWdlcyB3aXRob3V0IGJhY2tsaW5rcywgY29sbGVjdCBjb250ZW50IChrZXllZCBieSBxdWFsaWZpZWQgaWQpXG4gIGNvbnN0IHBhZ2VDb250ZW50cyA9IG5ldyBNYXA8c3RyaW5nLCBQYWdlQ29udGVudD4oKTtcbiAgZm9yIChjb25zdCBba2V5LCBpbmZvXSBvZiB0eXBlcykge1xuICAgIHBhZ2VDb250ZW50cy5zZXQoa2V5LCBhd2FpdCBnZW5lcmF0ZU92ZXJ2aWV3UGFnZShpbmZvLm5hbWUsIGluZm8sIHR5cGVzKSk7XG4gICAgaWYgKGluZm8ua2luZCA9PT0gJ2NsYXNzJyB8fCBpbmZvLmtpbmQgPT09ICdpbnRlcmZhY2UnKSB7XG4gICAgICBhd2FpdCBnZW5lcmF0ZU1lbWJlclBhZ2VzKGluZm8ubmFtZSwgaW5mbywgdHlwZXMpO1xuICAgIH1cbiAgfVxuXG4gIC8vIFBhc3MgMjogc2NhbiBjb250ZW50IGZvciBsaW5rcywgYXBwZW5kIGJhY2tsaW5rcywgd3JpdGUgZmlsZXNcbiAgYXdhaXQgYXBwZW5kQmFja2xpbmtzQW5kV3JpdGUocGFnZUNvbnRlbnRzLCB0eXBlcyk7XG5cbiAgYXdhaXQgZ2VuZXJhdGVTaWRlYmFySnNvbih0eXBlcyk7XG4gIGF3YWl0IHdyaXRlRmlsZShjYWNoZUZpbGUsIGN1cnJlbnRIYXNoLCAndXRmLTgnKTtcblxuICBjb25zb2xlLndhcm4oYEdlbmVyYXRlZCBkb2NzIGZvciAke1N0cmluZyh0eXBlcy5zaXplKX0gdHlwZXMgYWNyb3NzICR7U3RyaW5nKG1vZHVsZU92ZXJ2aWV3cy5zaXplKX0gZG9jdW1lbnRlZCBtb2R1bGVzYCk7XG59XG4iXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBUUE7QUFBQSxFQUNFO0FBQUEsRUFDQTtBQUFBLE9BQ0s7QUFDUDtBQUFBLEVBQ0U7QUFBQSxFQUNBO0FBQUEsRUFDQTtBQUFBLE9BQ0s7QUFDUDtBQUFBLEVBQ0U7QUFBQSxF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

package/dist/lib/esm/docs-site/astro-config.d.mts

@@ -0,0 +1,23 @@
+/// <reference path="../library-references.d.mts" />
+/**
+ * @file
+ *
+ * The Astro + Starlight configuration every documentation site is built with.
+ *
+ * A site's own `astro.config.ts` is one call, `export default defineDocsSiteConfig({ repo, title })`: the base path,
+ * the edit and GitHub links, the sidebar, the shared components and stylesheet, the Open Graph metadata and the
+ * Markdown plugins all follow from the repository's name.
+ */
+import type { AstroUserConfig } from 'astro';
+import type { DocsSiteConfig } from './docs-site-config.mjs';
+/**
+ * Builds a documentation site's Astro configuration.
+ *
+ * The site's source lives under `<docs>/src` (`srcDir`), so it never collides with the package's own `src/` and
+ * `dist/`. The API reference is generated into `<docs>/src/content/docs/api` with a matching
+ * `<docs>/src/generated-sidebar.json`, which this reads; run the generator first.
+ *
+ * @param config - The site's configuration.
+ * @returns The Astro configuration.
+ */
+export declare function defineDocsSiteConfig(config: DocsSiteConfig): AstroUserConfig;

package/dist/lib/esm/docs-site/astro-config.mjs

@@ -0,0 +1,135 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+(function () {
+function ensureBrowserProcess() {
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+
+  const existingProcess = globalThis.process;
+
+  if (!existingProcess) {
+    globalThis.process = browserProcess;
+    return;
+  }
+
+  if (existingProcess.versions?.node) {
+    return;
+  }
+
+  const existingProcessRecord = existingProcess;
+
+  for (const [key, value] of Object.entries(browserProcess)) {
+    existingProcessRecord[key] ??= value;
+  }
+
+  existingProcessRecord['browser'] = true;
+}
+
+ensureBrowserProcess();
+})();
+
+import { satteri } from "@astrojs/markdown-satteri";
+import starlight from "@astrojs/starlight";
+import {
+  extname,
+  join,
+  toPosixPath
+} from "@mnaoumov/typescript-lib/path";
+import { defineConfig } from "astro/config";
+import {
+  existsSync,
+  readFileSync
+} from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  API_COMPONENTS_IMPORT_PREFIX,
+  getDocsSiteAssetsDirectory
+} from "./docs-site-assets.mjs";
+import { resolveDocsSiteConfig } from "./docs-site-config.mjs";
+import { satteriGitHubAlerts } from "./satteri-github-alerts.mjs";
+import { satteriRelativeLinks } from "./satteri-relative-links.mjs";
+function defineDocsSiteConfig(config) {
+  const resolved = resolveDocsSiteConfig(config);
+  const assetsDirectory = toPosixPath(getDocsSiteAssetsDirectory());
+  return defineConfig({
+    base: resolved.basePath,
+    integrations: [
+      starlight({
+        components: {
+          SiteTitle: join(assetsDirectory, "components", "SiteTitle.astro")
+        },
+        customCss: [
+          join(assetsDirectory, "styles", "global.css")
+        ],
+        editLink: {
+          baseUrl: resolved.editLinkBaseUrl
+        },
+        favicon: "/favicon.svg",
+        routeMiddleware: getRouteDataModulePath(),
+        sidebar: [
+          {
+            items: [{ autogenerate: { directory: resolved.guidesDirectory } }],
+            label: "Guides"
+          },
+          ...readApiSidebar(resolved.apiDocSettings.sidebarFile)
+        ],
+        social: [
+          { href: resolved.githubUrl, icon: "github", label: "GitHub" }
+        ],
+        title: resolved.title
+      })
+    ],
+    markdown: {
+      // Astro 7.3 made Sätteri the default Markdown processor; `markdown.remarkPlugins` now runs only on the
+      // `unified` processor from `@astrojs/markdown-remark`, which Astro no longer installs. Naming the
+      // Sätteri processor here keeps the pipeline on it, carrying the link rewrite as one of its mdast plugins.
+      // The GitHub-alert conversion rides here too, ahead of the asides plugin Starlight appends after these:
+      // `starlight-github-alerts` cannot find that plugin on Starlight 0.42 and silently skipped every page.
+      processor: satteri({ mdastPlugins: [satteriGitHubAlerts(), satteriRelativeLinks(resolved.basePath)] })
+    },
+    // eslint-disable-next-line unicorn/name-replacements -- `outDir` is an Astro config key.
+    outDir: resolved.distDirectory,
+    // eslint-disable-next-line unicorn/name-replacements -- `publicDir` is an Astro config key.
+    publicDir: resolved.publicDirectory,
+    root: resolved.rootDirectory,
+    site: resolved.siteOrigin,
+    // eslint-disable-next-line unicorn/name-replacements -- `srcDir` is an Astro config key.
+    srcDir: resolved.docsSourceDirectory,
+    trailingSlash: "always",
+    vite: {
+      define: {
+        // The site title shows the documented package's version; `SiteTitle.astro` reads it from here.
+        "import.meta.env.DOCS_SITE_PACKAGE_VERSION": JSON.stringify(resolved.packageVersion)
+      },
+      resolve: {
+        alias: [
+          { find: API_COMPONENTS_IMPORT_PREFIX, replacement: join(assetsDirectory, "components") }
+        ]
+      }
+    }
+  });
+}
+function getRouteDataModulePath() {
+  const thisModulePath = toPosixPath(fileURLToPath(import.meta.url));
+  return join(thisModulePath, "..", `route-data${extname(thisModulePath)}`);
+}
+function readApiSidebar(sidebarFile) {
+  if (!existsSync(sidebarFile)) {
+    console.warn(`[astro.config] ${sidebarFile} not found. Generate the API reference first (npm run docs:build).`);
+    return [];
+  }
+  const parsed = JSON.parse(readFileSync(sidebarFile, "utf-8"));
+  return Array.isArray(parsed) ? parsed : [];
+}
+export {
+  defineDocsSiteConfig
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9kb2NzLXNpdGUvYXN0cm8tY29uZmlnLnRzIl0sInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQGZpbGVcbiAqXG4gKiBUaGUgQXN0cm8gKyBTdGFybGlnaHQgY29uZmlndXJhdGlvbiBldmVyeSBkb2N1bWVudGF0aW9uIHNpdGUgaXMgYnVpbHQgd2l0aC5cbiAqXG4gKiBBIHNpdGUncyBvd24gYGFzdHJvLmNvbmZpZy50c2AgaXMgb25lIGNhbGwsIGBleHBvcnQgZGVmYXVsdCBkZWZpbmVEb2NzU2l0ZUNvbmZpZyh7IHJlcG8sIHRpdGxlIH0pYDogdGhlIGJhc2UgcGF0aCxcbiAqIHRoZSBlZGl0IGFuZCBHaXRIdWIgbGlua3MsIHRoZSBzaWRlYmFyLCB0aGUgc2hhcmVkIGNvbXBvbmVudHMgYW5kIHN0eWxlc2hlZXQsIHRoZSBPcGVuIEdyYXBoIG1ldGFkYXRhIGFuZCB0aGVcbiAqIE1hcmtkb3duIHBsdWdpbnMgYWxsIGZvbGxvdyBmcm9tIHRoZSByZXBvc2l0b3J5J3MgbmFtZS5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7IFN0YXJsaWdodFVzZXJDb25maWcgfSBmcm9tICdAYXN0cm9qcy9zdGFybGlnaHQvdHlwZXMnO1xuaW1wb3J0IHR5cGUgeyBBc3Ryb1VzZXJDb25maWcgfSBmcm9tICdhc3Rybyc7XG5cbmltcG9ydCB7IHNhdHRlcmkgfSBmcm9tICdAYXN0cm9qcy9tYXJrZG93bi1zYXR0ZXJpJztcbi8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBpbXBvcnQteC9uby1yZW5hbWUtZGVmYXVsdCAtLSBUaGUgZGVmYXVsdCBleHBvcnQgbmFtZSBgU3RhcmxpZ2h0SW50ZWdyYXRpb25gIGlzIHRvbyB2ZXJib3NlLlxuaW1wb3J0IHN0YXJsaWdodCBmcm9tICdAYXN0cm9qcy9zdGFybGlnaHQnO1xuaW1wb3J0IHtcbiAgZXh0bmFtZSxcbiAgam9pbixcbiAgdG9Qb3NpeFBhdGhcbn0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL3BhdGgnO1xuaW1wb3J0IHsgZGVmaW5lQ29uZmlnIH0gZnJvbSAnYXN0cm8vY29uZmlnJztcbmltcG9ydCB7XG4gIGV4aXN0c1N5bmMsXG4gIHJlYWRGaWxlU3luY1xufSBmcm9tICdub2RlOmZzJztcbmltcG9ydCB7IGZpbGVVUkxUb1BhdGggfSBmcm9tICdub2RlOnVybCc7XG5cbmltcG9ydCB0eXBlIHsgRG9jc1NpdGVDb25maWcgfSBmcm9tICcuL2RvY3Mtc2l0ZS1jb25maWcudHMnO1xuXG5pbXBvcnQge1xuICBBUElfQ09NUE9ORU5UU19JTVBPUlRfUFJFRklYLFxuICBnZXREb2NzU2l0ZUFzc2V0c0RpcmVjdG9yeVxufSBmcm9tICcuL2RvY3Mtc2l0ZS1hc3NldHMudHMnO1xuaW1wb3J0IHsgcmVzb2x2ZURvY3NTaXRlQ29uZmlnIH0gZnJvbSAnLi9kb2NzLXNpdGUtY29uZmlnLnRzJztcbmltcG9ydCB7IHNhdHRlcmlHaXRIdWJBbGVydHMgfSBmcm9tICcuL3NhdHRlcmktZ2l0aHViLWFsZXJ0cy50cyc7XG5pbXBvcnQgeyBzYXR0ZXJpUmVsYXRpdmVMaW5rcyB9IGZyb20gJy4vc2F0dGVyaS1yZWxhdGl2ZS1saW5rcy50cyc7XG5cbnR5cGUgU2lkZWJhckl0ZW1zID0gTm9uTnVsbGFibGU8U3RhcmxpZ2h0VXNlckNvbmZpZ1snc2lkZWJhciddPjtcblxuLyoqXG4gKiBCdWlsZHMgYSBkb2N1bWVudGF0aW9uIHNpdGUncyBBc3RybyBjb25maWd1cmF0aW9uLlxuICpcbiAqIFRoZSBzaXRlJ3Mgc291cmNlIGxpdmVzIHVuZGVyIGA8ZG9jcz4vc3JjYCAoYHNyY0RpcmApLCBzbyBpdCBuZXZlciBjb2xsaWRlcyB3aXRoIHRoZSBwYWNrYWdlJ3Mgb3duIGBzcmMvYCBhbmRcbiAqIGBkaXN0L2AuIFRoZSBBUEkgcmVmZXJlbmNlIGlzIGdlbmVyYXRlZCBpbnRvIGA8ZG9jcz4vc3JjL2NvbnRlbnQvZG9jcy9hcGlgIHdpdGggYSBtYXRjaGluZ1xuICogYDxkb2NzPi9zcmMvZ2VuZXJhdGVkLXNpZGViYXIuanNvbmAsIHdoaWNoIHRoaXMgcmVhZHM7IHJ1biB0aGUgZ2VuZXJhdG9yIGZpcnN0LlxuICpcbiAqIEBwYXJhbSBjb25maWcgLSBUaGUgc2l0ZSdzIGNvbmZpZ3VyYXRpb24uXG4gKiBAcmV0dXJucyBUaGUgQXN0cm8gY29uZmlndXJhdGlvbi5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGRlZmluZURvY3NTaXRlQ29uZmlnKGNvbmZpZzogRG9jc1NpdGVDb25maWcpOiBBc3Ryb1VzZXJDb25maWcge1xuICBjb25zdCByZXNvbHZlZCA9IHJlc29sdmVEb2NzU2l0ZUNvbmZpZyhjb25maWcpO1xuICBjb25zdCBhc3NldHNEaXJlY3RvcnkgPSB0b1Bvc2l4UGF0aChnZXREb2NzU2l0ZUFzc2V0c0RpcmVjdG9yeSgpKTtcblxuICByZXR1cm4gZGVmaW5lQ29uZmlnKHtcbiAgICBiYXNlOiByZXNvbHZlZC5iYXNlUGF0aCxcbiAgICBpbnRlZ3JhdGlvbnM6IFtcbiAgICAgIHN0YXJsaWdodCh7XG4gICAgICAgIGNvbXBvbmVudHM6IHtcbiAgICAgICAgICBTaXRlVGl0bGU6IGpvaW4oYXNzZXRzRGlyZWN0b3J5LCAnY29tcG9uZW50cycsICdTaXRlVGl0bGUuYXN0cm8nKVxuICAgICAgICB9LFxuICAgICAgICBjdXN0b21Dc3M6IFtcbiAgICAgICAgICBqb2luKGFzc2V0c0RpcmVjdG9yeSwgJ3N0eWxlcycsICdnbG9iYWwuY3NzJylcbiAgICAgICAgXSxcbiAgICAgICAgZWRpdExpbms6IHtcbiAgICAgICAgICBiYXNlVXJsOiByZXNvbHZlZC5lZGl0TGlua0Jhc2VVcmxcbiAgICAgICAgfSxcbiAgICAgICAgZmF2aWNvbjogJy9mYXZpY29uLnN2ZycsXG4gICAgICAgIHJvdXRlTWlkZGxld2FyZTogZ2V0Um91dGVEYXRhTW9kdWxlUGF0aCgpLFxuICAgICAgICBzaWRlYmFyOiBbXG4gICAgICAgICAge1xuICAgICAgICAgICAgaXRlbXM6IFt7IGF1dG9nZW5lcmF0ZTogeyBkaXJlY3Rvcnk6IHJlc29sdmVkLmd1aWRlc0RpcmVjdG9yeSB9IH1dLFxuICAgICAgICAgICAgbGFiZWw6ICdHdWlkZXMnXG4gICAgICAgICAgfSxcbiAgICAgICAgICAuLi5yZWFkQXBpU2lkZWJhcihyZXNvbHZlZC5hcGlEb2NTZXR0aW5ncy5zaWRlYmFyRmlsZSlcbiAgICAgICAgXSxcbiAgICAgICAgc29jaWFsOiBbXG4gICAgICAgICAgeyBocmVmOiByZXNvbHZlZC5naXRodWJVcmwsIGljb246ICdnaXRodWInLCBsYWJlbDogJ0dpdEh1YicgfVxuICAgICAgICBdLFxuICAgICAgICB0aXRsZTogcmVzb2x2ZWQudGl0bGVcbiAgICAgIH0pXG4gICAgXSxcbiAgICBtYXJrZG93bjoge1xuICAgICAgLy8gQXN0cm8gNy4zIG1hZGUgU8OkdHRlcmkgdGhlIGRlZmF1bHQgTWFya2Rvd24gcHJvY2Vzc29yOyBgbWFya2Rvd24ucmVtYXJrUGx1Z2luc2Agbm93IHJ1bnMgb25seSBvbiB0aGVcbiAgICAgIC8vIGB1bmlmaWVkYCBwcm9jZXNzb3IgZnJvbSBgQGFzdHJvanMvbWFya2Rvd24tcmVtYXJrYCwgd2hpY2ggQXN0cm8gbm8gbG9uZ2VyIGluc3RhbGxzLiBOYW1pbmcgdGhlXG4gICAgICAvLyBTw6R0dGVyaSBwcm9jZXNzb3IgaGVyZSBrZWVwcyB0aGUgcGlwZWxpbmUgb24gaXQsIGNhcnJ5aW5nIHRoZSBsaW5rIHJld3JpdGUgYXMgb25lIG9mIGl0cyBtZGFzdCBwbHVnaW5zLlxuICAgICAgLy8gVGhlIEdpdEh1Yi1hbGVydCBjb252ZXJzaW9uIHJpZGVzIGhlcmUgdG9vLCBhaGVhZCBvZiB0aGUgYXNpZGVzIHBsdWdpbiBTdGFybGlnaHQgYXBwZW5kcyBhZnRlciB0aGVzZTpcbiAgICAgIC8vIGBzdGFybGlnaHQtZ2l0aHViLWFsZXJ0c2AgY2Fubm90IGZpbmQgdGhhdCBwbHVnaW4gb24gU3RhcmxpZ2h0IDAuNDIgYW5kIHNpbGVudGx5IHNraXBwZWQgZXZlcnkgcGFnZS5cbiAgICAgIHByb2Nlc3Nvcjogc2F0dGVyaSh7IG1kYXN0UGx1Z2luczogW3NhdHRlcmlHaXRIdWJBbGVydHMoKSwgc2F0dGVyaVJlbGF0aXZlTGlua3MocmVzb2x2ZWQuYmFzZVBhdGgpXSB9KVxuICAgIH0sXG4gICAgLy8gZXNsaW50LWRpc2FibGUtbmV4dC1saW5lIHVuaWNvcm4vbmFtZS1yZXBsYWNlbWVudHMgLS0gYG91dERpcmAgaXMgYW4gQXN0cm8gY29uZmlnIGtleS5cbiAgICBvdXREaXI6IHJlc29sdmVkLmRpc3REaXJlY3RvcnksXG4gICAgLy8gZXNsaW50LWRpc2FibGUtbmV4dC1saW5lIHVuaWNvcm4vbmFtZS1yZXBsYWNlbWVudHMgLS0gYHB1YmxpY0RpcmAgaXMgYW4gQXN0cm8gY29uZmlnIGtleS5cbiAgICBwdWJsaWNEaXI6IHJlc29sdmVkLnB1YmxpY0RpcmVjdG9yeSxcbiAgICByb290OiByZXNvbHZlZC5yb290RGlyZWN0b3J5LFxuICAgIHNpdGU6IHJlc29sdmVkLnNpdGVPcmlnaW4sXG4gICAgLy8gZXNsaW50LWRpc2FibGUtbmV4dC1saW5lIHVuaWNvcm4vbmFtZS1yZXBsYWNlbWVudHMgLS0gYHNyY0RpcmAgaXMgYW4gQXN0cm8gY29uZmlnIGtleS5cbiAgICBzcmNEaXI6IHJlc29sdmVkLmRvY3NTb3VyY2VEaXJlY3RvcnksXG4gICAgdHJhaWxpbmdTbGFzaDogJ2Fsd2F5cycsXG4gICAgdml0ZToge1xuICAgICAgZGVmaW5lOiB7XG4gICAgICAgIC8vIFRoZSBzaXRlIHRpdGxlIHNob3dzIHRoZSBkb2N1bWVudGVkIHBhY2thZ2UncyB2ZXJzaW9uOyBgU2l0ZVRpdGxlLmFzdHJvYCByZWFkcyBpdCBmcm9tIGhlcmUuXG4gICAgICAgICdpbXBvcnQubWV0YS5lbnYuRE9DU19TSVRFX1BBQ0tBR0VfVkVSU0lPTic6IEpTT04uc3RyaW5naWZ5KHJlc29sdmVkLnBhY2thZ2VWZXJzaW9uKVxuICAgICAgfSxcbiAgICAgIHJlc29sdmU6IHtcbiAgICAgICAgYWxpYXM6IFtcbiAgICAgICAgICB7IGZpbmQ6IEFQSV9DT01QT05FTlRTX0lNUE9SVF9QUkVGSVgsIHJlcGxhY2VtZW50OiBqb2luKGFzc2V0c0RpcmVjdG9yeSwgJ2NvbXBvbmVudHMnKSB9XG4gICAgICAgIF1cbiAgICAgIH1cbiAgICB9XG4gIH0pO1xufVxuXG4vLyBgcm91dGUtZGF0YWAgc2l0cyBiZXNpZGUgdGhpcyBtb2R1bGUgaW4gZXZlcnkgYnVpbGQgb2YgaXQsIHdpdGggdGhlIHNhbWUgZXh0ZW5zaW9uOiBgLnRzYCBpbiB0aGlzIHJlcG9zaXRvcnksXG4vLyBgLm1qc2AgLyBgLmNqc2Agb25jZSBpbnN0YWxsZWQuXG5mdW5jdGlvbiBnZXRSb3V0ZURhdGFNb2R1bGVQYXRoKCk6IHN0cmluZyB7XG4gIGNvbnN0IHRoaXNNb2R1bGVQYXRoID0gdG9Qb3NpeFBhdGgoZmlsZVVSTFRvUGF0aChpbXBvcnQubWV0YS51cmwpKTtcbiAgcmV0dXJuIGpvaW4odGhpc01vZHVsZVBhdGgsICcuLicsIGByb3V0ZS1kYXRhJHtleHRuYW1lKHRoaXNNb2R1bGVQYXRoKX1gKTtcbn1cblxuZnVuY3Rpb24gcmVhZEFwaVNpZGViYXIoc2lkZWJhckZpbGU6IHN0cmluZyk6IFNpZGViYXJJdGVtcyB7XG4gIGlmICghZXhpc3RzU3luYyhzaWRlYmFyRmlsZSkpIHtcbiAgICBjb25zb2xlLndhcm4oYFthc3Ryby5jb25maWddICR7c2lkZWJhckZpbGV9IG5vdCBmb3VuZC4gR2VuZXJhdGUgdGhlIEFQSSByZWZlcmVuY2UgZmlyc3QgKG5wbSBydW4gZG9jczpidWlsZCkuYCk7XG4gICAgcmV0dXJuIFtdO1xuICB9XG5cbiAgY29uc3QgcGFyc2VkOiB1bmtub3duID0gSlNPTi5wYXJzZShyZWFkRmlsZVN5bmMoc2lkZWJhckZpbGUsICd1dGYtOCcpKTtcbiAgcmV0dXJuIEFycmF5LmlzQXJyYXkocGFyc2VkKSA/IHBhcnNlZCBhcyBTaWRlYmFySXRlbXMgOiBbXTtcbn1cbiJdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7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

package/dist/lib/esm/docs-site/docs-links.d.mts

@@ -0,0 +1,32 @@
+/// <reference path="../library-references.d.mts" />
+/**
+ * @file
+ *
+ * Validates the links emitted by a built documentation site.
+ *
+ * Internal links are resolved offline against the build output; external links are validated over the network,
+ * deduplicated so each unique URL is fetched at most once. See {@link ./link-check.ts} for the decision logic.
+ *
+ * It also fails on a GitHub alert that reached a page as a plain blockquote (see {@link ./unrendered-alerts.ts}),
+ * since nothing else notices when the conversion stops.
+ */
+/**
+ * Options for {@link assertDocsLinksResolve}.
+ */
+export interface AssertDocsLinksResolveParams {
+    /**
+     * The build output folder, normally `<docs>/dist`.
+     */
+    readonly outputDirectory: string;
+    /**
+     * The absolute URL the site is served from, with a trailing slash, e.g. `https://mnaoumov.dev/typescript-lib/`.
+     */
+    readonly siteBaseUrl: string;
+}
+/**
+ * Checks every link of the built site, and that every GitHub alert rendered as an aside.
+ *
+ * @param options - The options.
+ * @throws If an alert rendered as a plain blockquote, or a link does not resolve.
+ */
+export declare function assertDocsLinksResolve(options: AssertDocsLinksResolveParams): Promise<void>;