@savvy-web/tsdown-plugins 2.8.21 → 2.9.0

package/index.d.ts

@@ -1090,6 +1090,17 @@ interface OgImageInfo {
     readonly tagline?: string | undefined;
   } | undefined;
 }
+/**
+ * An `openGraph.generate` renderer. A renderer whose output is fully determined by its input can
+ * carry its own `cacheSalt`, naming everything else that shapes the bytes (its version, its
+ * options); that turns on the cross-build cache without any config. `ogImage.satori()` does.
+ *
+ * @public
+ */
+interface OgImageGenerator {
+  (info: OgImageInfo): Promise<Uint8Array>;
+  readonly cacheSalt?: string | undefined;
+}
 /**
  * The `meta.tsdoctor` block: the CONFIG tier of the emitted `tsdoctor.json`,
  * ranked over the package's `tsdoctor.json` (leaf) and the workspace root's
@@ -1105,8 +1116,15 @@ interface TsdoctorMetaOptions {
     /** Static images, path (bundle-relative) or url. Listed after a generated image. */
     readonly images?: ReadonlyArray<OpenGraphImage> | undefined;
     readonly themeColor?: string | undefined;
-    /** Render an image at build time; the bytes are written to `meta/og/<unscoped>.png` and listed first. */
-    readonly generate?: ((info: OgImageInfo) => Promise<Uint8Array>) | undefined;
+    /** Render an image at build time; the bytes are written to `meta/og/<unscoped>.<png|jpg|webp>` and listed first. */
+    readonly generate?: OgImageGenerator | undefined;
+    /**
+     * The cross-build image cache, keyed on the {@link OgImageInfo} plus this salt. A string
+     * caches under it: change it whenever the generator's output changes for the same input,
+     * since the cache cannot see code. `false` always regenerates. Omitted, the generator's own
+     * {@link OgImageGenerator.cacheSalt} is used when it has one, otherwise it always regenerates.
+     */
+    readonly cacheSalt?: string | false | undefined;
   } | undefined;
   /** Registries; `false` disables the default derived from `targets.json`. */
   readonly registries?: ReadonlyArray<RegistryRef> | false | undefined;
@@ -1668,6 +1686,23 @@ export declare class OgGenerateError extends OgGenerateError_base<{
 }> {
   get message(): string;
 }
+/**
+ * Where generated images persist across builds, and the salt naming the generator's identity.
+ *
+ * @public
+ */
+interface OgImageCacheOptions {
+  readonly directory: string;
+  /** Change it whenever the generator's output changes for the same input; the cache cannot see code. */
+  readonly salt: string;
+}
+/**
+ * The salt the cross-build cache runs under, or `undefined` to always regenerate: an explicit
+ * `cacheSalt` string wins, `false` disables, and otherwise the generator's own salt applies.
+ *
+ * @public
+ */
+export declare function resolveOgCacheSalt(generate: OgImageGenerator, cacheSalt: string | false | undefined): string | undefined;
 /**
  * Options for {@link writeGeneratedOgImage}.
  *
@@ -1679,10 +1714,12 @@ interface WriteGeneratedOgImageOptions {
   /** The meta bundle dir; the image lands at `og/<unscopedName>.<ext>` beneath it. */
   readonly outMetaDir: string;
   readonly unscopedName: string;
+  /** Reuse a previous build's image for the same info and salt; omitted, the generator always runs. */
+  readonly cache?: OgImageCacheOptions | undefined;
 }
 /**
- * Run the generator, size the bytes, and write `og/<unscoped>.<ext>` under the meta dir. Returns the
- * manifest image entry (bundle-relative path, MIME type, dimensions).
+ * Run the generator (or reuse a cached render), size the bytes, and write `og/<unscoped>.<ext>`
+ * under the meta dir. Returns the manifest image entry (bundle-relative path, MIME type, dimensions).
  *
  * @public
  */
@@ -2114,5 +2151,5 @@ export declare function resolveTargets(options: {
   baseName: string;
 }): TargetResolution;
 //#endregion
-export { type AmbientDtsEntry, type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildIssues, type BuildPlatform, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, type ComposeManifestInput, type CopyAmbientDtsOptions, type CssOptions, DependencyResolutionError, type DeriveOptions, type DerivedTsdownOptions, type DiagnosticEntry, type DiagnosticInput, type DtsExportClass, type DualExports, type EmitManifestOptions, type EmittedFile, type EntryOverride, type Environment, type ExeBuild, type ExeConfig, type ExeRewrite, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, type ExtractAmbientOptions, type ExtractOptions, type ExtractResult, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, type JsxConfig, type LooseFileSpec, type LooseFiles, ManifestDecodeError, type ManifestLike, type ManifestRepository, type ManifestTarget, type MetaOptions, type MetaResult, type ModuleExportNames, type NextVersions, type NormalizedExe, type NormalizedLooseFile, type NormalizedMeta, type OgImageInfo, type OutputFormat, type PackageJsonEntriesOptions, type PackageJsonLike, type PassKind, type PassReport, type PkgOsCpu, type PlainDiagnostic, type PortableTsconfig, type PublishTargetObject, type PublishTargetValue, type PublishTargets, type ReexportBarrelAnalysis, type RenderReportOptions, type RenderedOutput, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, type RunMetaPassOptions, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, type Timer, type TransformManifestOptions, type TsconfigJsx, type TsdocOptions, type TsdocTagDefinition, type TsdoctorMetaOptions, type TsdoctorSources, type TsdownBuild, type TsdownLogger, UnresolvedDependencyError, type ValidationInput, type WarningSuppressionRule, type WriteGeneratedOgImageOptions };
+export { type AmbientDtsEntry, type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildIssues, type BuildPlatform, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, type ComposeManifestInput, type CopyAmbientDtsOptions, type CssOptions, DependencyResolutionError, type DeriveOptions, type DerivedTsdownOptions, type DiagnosticEntry, type DiagnosticInput, type DtsExportClass, type DualExports, type EmitManifestOptions, type EmittedFile, type EntryOverride, type Environment, type ExeBuild, type ExeConfig, type ExeRewrite, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, type ExtractAmbientOptions, type ExtractOptions, type ExtractResult, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, type JsxConfig, type LooseFileSpec, type LooseFiles, ManifestDecodeError, type ManifestLike, type ManifestRepository, type ManifestTarget, type MetaOptions, type MetaResult, type ModuleExportNames, type NextVersions, type NormalizedExe, type NormalizedLooseFile, type NormalizedMeta, type OgImageCacheOptions, type OgImageGenerator, type OgImageInfo, type OutputFormat, type PackageJsonEntriesOptions, type PackageJsonLike, type PassKind, type PassReport, type PkgOsCpu, type PlainDiagnostic, type PortableTsconfig, type PublishTargetObject, type PublishTargetValue, type PublishTargets, type ReexportBarrelAnalysis, type RenderReportOptions, type RenderedOutput, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, type RunMetaPassOptions, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, type Timer, type TransformManifestOptions, type TsconfigJsx, type TsdocOptions, type TsdocTagDefinition, type TsdoctorMetaOptions, type TsdoctorSources, type TsdownBuild, type TsdownLogger, UnresolvedDependencyError, type ValidationInput, type WarningSuppressionRule, type WriteGeneratedOgImageOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -27,7 +27,7 @@ import { runExeBuild } from "./exe/build.js";
 import { computeExeFileName } from "./exe/filename.js";
 import { readTsconfigJsx, resolveJsxConfig } from "./jsx/config.js";
 import { normalizeMetaOptions } from "./meta/config.js";
-import { OgGenerateError, writeGeneratedOgImage } from "./meta/og-image.js";
+import { OgGenerateError, resolveOgCacheSalt, writeGeneratedOgImage } from "./meta/og-image.js";
 import { resolvePortableTsconfig } from "./meta/tsconfig-resolver.js";
 import { composeTsdoctorManifest, githubOwnerRepo, ogImageInfoOf, registriesFromTargets } from "./meta/tsdoctor-manifest.js";
 import { generateMeta } from "./meta/generate.js";
@@ -50,4 +50,4 @@ import { ReportPipeline, renderReport } from "./report/pipeline.js";
 import { writeTargetsBinding } from "./targets/binding.js";
 import { CatalogAssemblyError, DependencyResolutionError, ManifestDecodeError, UnresolvedDependencyError } from "@effected/npm";
 
-export { BuildCollector, BuildCollectorTag, BuildReport as BuildReportSchema, CatalogAssemblyError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, DEFAULT_EXE_NODE_VERSION, DependencyResolutionError, EnvironmentDetector, ExecutorResolver, FormatSelector, JsonFormatter, ManifestDecodeError, MarkdownFormatter, MetaGenerationError, OgGenerateError, OutputRenderer, ReportPipeline, ReportTimings, SilentFormatter, TargetGroupReport as TargetGroupReportSchema, TerminalFormatter, TsdoctorEmitError, TsdoctorSourceError, UnresolvedDependencyError, ambientOutName, analyzeReexportBarrel, applySubdirMetaEntries, assertNoEntryCollisions, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, classifyDtsExport, collectExportNames, composeTsdoctorManifest, computeExeFileName, copyAmbientDts, copyPublicDir, createEntryName, createTimer, createTsdownLogger, declarationExt, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractAmbientDts, extractEntries, findRelativeSpecifiers, flattenIssues, formatTime, generateMeta, githubOwnerRepo, isTargetObject, loadTsdoctorSources, mixedDtsExportError, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, ogImageInfoOf, packageJsonEntries, readTsconfigJsx, registriesFromTargets, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, writeGeneratedOgImage, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };
+export { BuildCollector, BuildCollectorTag, BuildReport as BuildReportSchema, CatalogAssemblyError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, DEFAULT_EXE_NODE_VERSION, DependencyResolutionError, EnvironmentDetector, ExecutorResolver, FormatSelector, JsonFormatter, ManifestDecodeError, MarkdownFormatter, MetaGenerationError, OgGenerateError, OutputRenderer, ReportPipeline, ReportTimings, SilentFormatter, TargetGroupReport as TargetGroupReportSchema, TerminalFormatter, TsdoctorEmitError, TsdoctorSourceError, UnresolvedDependencyError, ambientOutName, analyzeReexportBarrel, applySubdirMetaEntries, assertNoEntryCollisions, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, classifyDtsExport, collectExportNames, composeTsdoctorManifest, computeExeFileName, copyAmbientDts, copyPublicDir, createEntryName, createTimer, createTsdownLogger, declarationExt, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractAmbientDts, extractEntries, findRelativeSpecifiers, flattenIssues, formatTime, generateMeta, githubOwnerRepo, isTargetObject, loadTsdoctorSources, mixedDtsExportError, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, ogImageInfoOf, packageJsonEntries, readTsconfigJsx, registriesFromTargets, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolveOgCacheSalt, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, writeGeneratedOgImage, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };

package/meta/generate.js

@@ -1,7 +1,7 @@
 import { TsdoctorEmitError } from "../errors.js";
 import { runApiExtractor } from "./api-extractor.js";
 import { mergeApiModels } from "./merge-models.js";
-import { writeGeneratedOgImage } from "./og-image.js";
+import { resolveOgCacheSalt, writeGeneratedOgImage } from "./og-image.js";
 import { resolvePortableTsconfig } from "./tsconfig-resolver.js";
 import { writeTsdocConfig } from "./tsdoc-config.js";
 import { composeTsdoctorManifest, ogImageInfoOf } from "./tsdoctor-manifest.js";
@@ -152,6 +152,7 @@ async function generateMeta(options) {
 		};
 		const generate = options.tsdoctor.config?.openGraph?.generate;
 		if (generate !== void 0) {
+			const cacheSalt = resolveOgCacheSalt(generate, options.tsdoctor.config?.openGraph?.cacheSalt);
 			const generated = await writeGeneratedOgImage({
 				generate,
 				info: ogImageInfoOf({
@@ -159,7 +160,11 @@ async function generateMeta(options) {
 					version: String(finalPkg.version ?? "0.0.0")
 				}),
 				outMetaDir,
-				unscopedName: unscopedName(packageName)
+				unscopedName: unscopedName(packageName),
+				...cacheSalt === void 0 ? {} : { cache: {
+					directory: join(cwd, "node_modules", ".cache", "tsdown-plugins", "og"),
+					salt: cacheSalt
+				} }
 			});
 			composeInput.generatedImage = generated;
 			generatedImageRelative = generated.path;

package/meta/og-image.js

@@ -1,7 +1,8 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { Data } from "effect";
-import { imageSize } from "image-size";
+import { Data, Effect, Layer, Option, Result, Schema } from "effect";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { ImageBackend, ImageCache, ImageCacheKey } from "@effected/images/cache";
 
 //#region src/meta/og-image.ts
 /**
@@ -17,63 +18,90 @@ var OgGenerateError = class extends Data.TaggedError("OgGenerateError") {
 	}
 };
 /** The image types an Open Graph consumer can render; anything else fails rather than shipping a mislabeled file. */
-const MIME_BY_TYPE = {
-	png: "image/png",
-	jpg: "image/jpeg",
-	webp: "image/webp"
-};
+const ACCEPT = [
+	"png",
+	"jpeg",
+	"webp"
+];
+/**
+* The cache key's params: exactly what the generator receives, so any change to its input is a miss.
+* `Schema.Struct` drops undeclared keys, so the `satisfies` clauses fail to compile when a field is
+* added to {@link OgImageInfo} without being keyed here (or removed from it but kept here).
+*/
+const OgImageInfoKey = Schema.Struct({
+	name: Schema.String,
+	packageName: Schema.String,
+	version: Schema.String,
+	tagline: Schema.optional(Schema.String),
+	description: Schema.optional(Schema.String),
+	project: Schema.optional(Schema.Struct({
+		name: Schema.optional(Schema.String),
+		tagline: Schema.optional(Schema.String)
+	}))
+});
+/**
+* The cache is an optimization, never a reason to fail a build that rendered a valid image: an
+* unreadable entry is a miss and a failed store is dropped. Generator and validation failures still
+* surface, because those come from `ImageCache` itself, not the backend.
+*/
+const tolerantDirectory = (directory) => Layer.effect(ImageBackend, Effect.gen(function* () {
+	const backend = yield* ImageBackend;
+	return {
+		get: (key) => backend.get(key).pipe(Effect.orElseSucceed(() => Option.none())),
+		set: (params) => backend.set(params).pipe(Effect.ignore)
+	};
+})).pipe(Layer.provide(ImageBackend.layerDirectory({ directory })));
+/**
+* The salt the cross-build cache runs under, or `undefined` to always regenerate: an explicit
+* `cacheSalt` string wins, `false` disables, and otherwise the generator's own salt applies.
+*
+* @public
+*/
+function resolveOgCacheSalt(generate, cacheSalt) {
+	if (cacheSalt === false) return void 0;
+	return cacheSalt ?? generate.cacheSalt;
+}
 /**
-* Run the generator, size the bytes, and write `og/<unscoped>.<ext>` under the meta dir. Returns the
-* manifest image entry (bundle-relative path, MIME type, dimensions).
+* Run the generator (or reuse a cached render), size the bytes, and write `og/<unscoped>.<ext>`
+* under the meta dir. Returns the manifest image entry (bundle-relative path, MIME type, dimensions).
 *
 * @public
 */
 async function writeGeneratedOgImage(options) {
-	let bytes;
-	try {
-		bytes = await options.generate(options.info);
-	} catch (cause) {
-		throw new OgGenerateError({
-			packageName: options.info.packageName,
-			cause
-		});
-	}
-	if (bytes.byteLength === 0) throw new OgGenerateError({
-		packageName: options.info.packageName,
-		cause: /* @__PURE__ */ new Error("generator returned no bytes")
-	});
-	let size;
-	try {
-		size = imageSize(bytes);
-	} catch (cause) {
-		throw new OgGenerateError({
-			packageName: options.info.packageName,
-			cause
+	const { packageName } = options.info;
+	const backend = options.cache === void 0 ? ImageBackend.layerNone : tolerantDirectory(options.cache.directory);
+	const result = await Effect.gen(function* () {
+		const key = yield* ImageCacheKey.fromParams(OgImageInfoKey, options.info, {
+			salt: options.cache?.salt ?? "",
+			namespace: "og"
 		});
-	}
-	const ext = size.type ?? "png";
-	const type = MIME_BY_TYPE[ext];
-	if (type === void 0) throw new OgGenerateError({
-		packageName: options.info.packageName,
-		cause: /* @__PURE__ */ new Error(`generator returned a ${ext} image; Open Graph images must be png, jpg or webp`)
+		return yield* (yield* ImageCache).getOrGenerate(key, () => Effect.tryPromise({
+			try: () => options.generate(options.info),
+			catch: (cause) => cause
+		}), { accept: ACCEPT });
+	}).pipe(Effect.provide(ImageCache.layer.pipe(Layer.provide(backend), Layer.provideMerge(NodeServices.layer))), Effect.result, Effect.runPromise);
+	if (Result.isFailure(result)) throw new OgGenerateError({
+		packageName,
+		cause: result.failure
 	});
-	const relative = `og/${options.unscopedName}.${ext}`;
+	const { bytes, facts } = result.success;
+	const relative = `og/${options.unscopedName}.${facts.extension}`;
 	try {
 		mkdirSync(join(options.outMetaDir, "og"), { recursive: true });
 		writeFileSync(join(options.outMetaDir, relative), bytes);
 	} catch (cause) {
 		throw new OgGenerateError({
-			packageName: options.info.packageName,
+			packageName,
 			cause
 		});
 	}
 	return {
 		path: relative,
-		type,
-		width: size.width,
-		height: size.height
+		type: facts.mimeType,
+		width: facts.width,
+		height: facts.height
 	};
 }
 
 //#endregion
-export { OgGenerateError, writeGeneratedOgImage };
+export { OgGenerateError, resolveOgCacheSalt, writeGeneratedOgImage };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/tsdown-plugins",
-	"version": "2.8.21",
+	"version": "2.9.0",
 	"private": false,
 	"description": "Interface-only tsdown/rolldown plugin pack powering @savvy-web/bundler",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/tsdown-plugins",
@@ -32,6 +32,7 @@
 		"@changesets/get-release-plan": "^5.0.2",
 		"@effect/platform-node": "^4.0.2",
 		"@effected/glob": "^0.10.0",
+		"@effected/images": "^0.1.0",
 		"@effected/jsonc": "^0.15.1",
 		"@effected/npm": "^0.20.0",
 		"@effected/package-json": "^0.20.1",
@@ -42,9 +43,8 @@
 		"@microsoft/api-extractor": "7.59.1",
 		"@microsoft/tsdoc": "~0.16.0",
 		"@microsoft/tsdoc-config": "0.18.1",
-		"@tsdoctor/manifest": "^0.2.4",
+		"@tsdoctor/manifest": "^0.2.5",
 		"effect": "^4.0.2",
-		"image-size": "^2.0.4",
 		"picocolors": "^1.1.1",
 		"std-env": "^4.3.0",
 		"tsdown": "^0.23.0",