vitepress-plugin-api-extractor 0.1.2 → 0.2.1

package/ApiExtractor.js

@@ -5,20 +5,6 @@ import { TwoslashCacheStore } from "./TwoslashCache.js";
 import { Effect, Layer, ManagedRuntime } from "effect";
 
 //#region src/ApiExtractor.ts
-/**
-* The public helper a site's `.vitepress/config.mts` awaits at config-load
-* time: generates the pages, opens the Twoslash result cache and returns the
-* sidebar, the code transformer and the `buildEnd` hook that persists the
-* cache.
-*
-* @remarks
-* Generation happens HERE, at config load, because VitePress has no
-* pre-scan hook comparable to RSPress's `config()`: its config file is ESM
-* and may top-level await, and `buildEnd` / `postRender` run after the fact.
-* The result is merged into `defineConfig` by the site.
-*
-* @packageDocumentation
-*/
 const AppLive = Layer.mergeAll(PlatformLive, RegistryLive, TwoslashCacheStore.layer);
 /**
 * Generate the API pages and return what the site's config needs.
@@ -55,7 +41,8 @@ async function apiExtractor(options) {
 		categories: options.categories,
 		externalPackages: options.externalPackages,
 		suppressExampleErrors: options.suppressExampleErrors,
-		source: options.source
+		source: options.source,
+		ogImage: options.ogImage
 	}));
 	const envHash = environmentHash(generated.vfs);
 	const typesCache = await runtime.runPromise(Effect.gen(function* () {

package/Generate.js

@@ -5,9 +5,9 @@ import { sidebarFor } from "./emit/sidebar.js";
 import { externalPackagesOf, loadExternalTypes } from "./Registry.js";
 import { Effect, FileSystem, Option, Path } from "effect";
 import { PackageManifest } from "@effected/package-json";
-import { discoverBundle } from "@tsdoctor/bundle";
+import { loadBundle, publishBundleAssets, resolveBundleFrom } from "@tsdoctor/bundle";
 import { ApiExtractedPackage, CrossLinker, Model, TypeReferenceExtractor } from "@tsdoctor/model";
-import { buildIndexPage, buildNav, buildPage, prepareWorkItems } from "@tsdoctor/pages";
+import { buildIndexPage, buildNav, buildPage, prepareWorkItems, unscopedName } from "@tsdoctor/pages";
 import { attributionFacts, deriveScriptBody, deriveSiteUrl, headTags, packageContext } from "@tsdoctor/seo";
 import { resolveTypeScriptConfig } from "@tsdoctor/vfs";
 
@@ -74,7 +74,8 @@ const fileFor = (docsDir, route) => `${docsDir}${route}.md`;
 const generate = Effect.fn("Generate.generate")(function* (input) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
-	const descriptor = yield* discoverBundle(input.dir, { cwd: input.cwd });
+	const bundle = yield* loadBundle(input.dir, { cwd: input.cwd });
+	const descriptor = bundle.descriptor;
 	const apiPackage = yield* Model.load(descriptor.modelPath);
 	const packageName = descriptor.name;
 	const packageJson = descriptor.packageJsonPath === void 0 ? void 0 : yield* fs.readFileString(descriptor.packageJsonPath).pipe(Effect.map((text) => JSON.parse(text)), Effect.orElseSucceed(() => void 0));
@@ -92,6 +93,17 @@ const generate = Effect.fn("Generate.generate")(function* (input) {
 	if (prepared.collisions.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`route collisions under ${input.baseRoute}: ${prepared.collisions.map((c) => `${c.route} <- ${c.items.map((i) => i.displayName).join(", ")}`).join("; ")}`));
 	const linker = CrossLinker.fromRoutes(prepared.crossLinkData.routes);
 	const siteUrl = deriveSiteUrl(input.siteOrigin, input.base);
+	const docsDir = path.resolve(input.cwd, input.docsDir);
+	const platform = input.ogImage === void 0 ? {} : { openGraph: { images: [typeof input.ogImage === "string" ? /^https?:\/\//.test(input.ogImage) ? { url: input.ogImage } : { path: input.ogImage } : input.ogImage] } };
+	const resolvedBundle = resolveBundleFrom(bundle, platform);
+	const siteName = resolvedBundle.project?.value.name ?? resolvedBundle.name.value;
+	const ogImage = (resolvedBundle.openGraph === void 0 ? [] : yield* publishBundleAssets({
+		bundleDir: descriptor.dir,
+		images: resolvedBundle.openGraph.value.images,
+		publicDir: path.join(docsDir, "public"),
+		siteUrl,
+		unscopedName: unscopedName(packageName)
+	}).pipe(Effect.orElseSucceed(() => [])))[0];
 	const structuredDataPkg = manifest === void 0 ? void 0 : packageContext({
 		siteUrl,
 		baseRoute: input.baseRoute,
@@ -101,7 +113,6 @@ const generate = Effect.fn("Generate.generate")(function* (input) {
 		attribution: attributionFacts(manifest)
 	});
 	const buildTime = (/* @__PURE__ */ new Date()).toISOString();
-	const docsDir = path.resolve(input.cwd, input.docsDir);
 	const entries = [];
 	const routes = [];
 	const formatFailures = [];
@@ -111,6 +122,8 @@ const generate = Effect.fn("Generate.generate")(function* (input) {
 			packageName,
 			linker,
 			siteUrl,
+			siteName,
+			ogImage,
 			structuredDataPkg,
 			buildTime,
 			docsDir,
@@ -190,11 +203,14 @@ const writePage = Effect.fn("Generate.writePage")(function* (workItem, ctx) {
 	const tags = headTags({
 		siteUrl: ctx.siteUrl,
 		pageRoute: page.route,
+		title: item.displayName,
+		siteName: ctx.siteName,
 		description: page.description,
 		publishedTime: ctx.buildTime,
 		modifiedTime: ctx.buildTime,
 		section: categoryConfig.displayName,
 		packageName: ctx.packageName,
+		...ctx.ogImage !== void 0 ? { ogImage: ctx.ogImage } : {},
 		...structuredData !== void 0 && structuredData._tag === "Success" ? { structuredData: structuredData.success } : {}
 	});
 	const body = yield* Effect.fromResult(emitMarkdownBody(page)).pipe(Effect.orDie);

package/index.d.ts

@@ -1,3 +1,4 @@
+import { OpenGraphImage } from "@tsdoctor/bundle";
 import { ShikiTransformer } from "shiki";
 import { Block, CrossLinkData, NavTree, Page, WorkItemCategory } from "@tsdoctor/pages";
 import { Model } from "@tsdoctor/model";
@@ -164,6 +165,13 @@ interface GenerateInput {
     readonly url: string;
     readonly ref?: string | undefined;
   } | undefined;
+  /**
+   * The `manifest.platform` Open Graph image override, ranked above the
+   * bundle's own `tsdoctor.json`. A string is an absolute `http(s)://` URL or
+   * a path relative to the bundle directory; an object is the manifest image
+   * shape (`path` XOR `url`, plus `type`/`width`/`height`/`alt`).
+   */
+  readonly ogImage?: string | OpenGraphImage | undefined;
 }
 /**
  * What generation produced, for the site's config and for the report.
@@ -235,7 +243,7 @@ declare const generate: (input: GenerateInput) => Effect.Effect<{
   };
   uncategorized: string[];
   formatFailures: string[];
-}, import("@tsdoctor/bundle").BundleDiscoveryError | import("@tsdoctor/bundle").BundleLayerError | Model.ModelNotFoundError | Model.ModelParseError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path | TypeRegistry>;
+}, import("@tsdoctor/bundle").BundleDiscoveryError | import("@tsdoctor/bundle").BundleLayerError | import("@tsdoctor/bundle").BundleManifestError | Model.ModelNotFoundError | Model.ModelParseError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path | TypeRegistry>;
 /**
  * The services {@link generate} runs over: the platform plus the registry.
  *
@@ -326,6 +334,13 @@ interface ApiExtractorOptions {
     readonly url: string;
     readonly ref?: string | undefined;
   } | undefined;
+  /**
+   * The `manifest.platform` Open Graph image override, ranked above the
+   * bundle's own `tsdoctor.json`. A string is an absolute `http(s)://` URL or
+   * a path relative to the bundle directory; an object is the manifest image
+   * shape (`path` XOR `url`, plus `type`/`width`/`height`/`alt`).
+   */
+  readonly ogImage?: string | OpenGraphImage | undefined;
   /** Whether to print a one-line summary. Defaults to `true`. */
   readonly log?: boolean | undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vitepress-plugin-api-extractor",
-	"version": "0.1.2",
+	"version": "0.2.1",
 	"private": false,
 	"description": "VitePress adapter for generating API documentation from TypeScript API Extractor models: markdown pages over the @tsdoctor/pages IR, a sidebar from its navigation tree, and Twoslash type-checking over the same virtual file system the RSPress plugin resolves.",
 	"keywords": [
@@ -38,7 +38,7 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.109",
-		"@effected/markdown": "^0.8.0",
+		"@effected/markdown": "^0.8.1",
 		"@effected/package-json": "^0.13.0",
 		"@effected/store": "^0.6.0",
 		"@effected/tsconfig-json": "^0.7.0",
@@ -46,13 +46,15 @@
 		"@microsoft/api-extractor-model": "^7.33.11",
 		"@shikijs/twoslash": "^4.4.3",
 		"@shikijs/vitepress-twoslash": "^4.4.3",
-		"@tsdoctor/bundle": "0.2.4",
-		"@tsdoctor/model": "0.6.1",
-		"@tsdoctor/pages": "0.1.1",
-		"@tsdoctor/registry": "0.3.2",
-		"@tsdoctor/seo": "0.1.2",
+		"@tsdoctor/bundle": "0.3.0",
+		"@tsdoctor/manifest": "0.1.0",
+		"@tsdoctor/model": "0.6.2",
+		"@tsdoctor/pages": "0.1.3",
+		"@tsdoctor/registry": "0.3.3",
+		"@tsdoctor/seo": "0.2.0",
 		"@tsdoctor/vfs": "0.2.1",
 		"effect": "4.0.0-rc.109",
+		"image-size": "^2.0.2",
 		"shiki": "^4.4.3",
 		"typescript": "^6.0.3"
 	},