@savvy-web/tsdown-plugins 2.5.10 → 2.6.0

package/errors.js

@@ -39,6 +39,18 @@ var ConfigValidationError = class extends Data.TaggedError("ConfigValidationErro
 		return `Config validation failed at "${this.path}": ${this.reason}`;
 	}
 };
+/**
+* Writing the `tsdoctor.json` sidecar failed — the composed manifest did not encode, or the file
+* could not be written (a read-only or full disk). Recorded in `issues.json` as a `meta` error.
+*
+* @public
+*/
+var TsdoctorEmitError = class extends Data.TaggedError("TsdoctorEmitError") {
+	get message() {
+		const reason = this.cause instanceof Error ? this.cause.message : String(this.cause);
+		return `Could not emit ${this.path} for ${this.packageName}: ${reason}`;
+	}
+};
 
 //#endregion
-export { ConfigValidationError, MetaGenerationError };
+export { ConfigValidationError, MetaGenerationError, TsdoctorEmitError };

package/index.d.ts

@@ -9,6 +9,7 @@
 import { CatalogAssemblyError, DependencyResolutionError, ManifestDecodeError, UnresolvedDependencyError } from "@effected/npm";
 import { Plugin } from "rolldown";
 import { Context, Effect, Layer, Schema } from "effect";
+import { BundleManifest, ManifestSource, OpenGraphImage, RegistryRef } from "@tsdoctor/manifest";
 //#region src/manifest/transform.d.ts
 /** @public */
 type Json = Record<string, unknown>;
@@ -174,7 +175,7 @@ declare const ReportTimings_base: Schema.Class<ReportTimings, Schema.Struct<{
 /** @public */
 declare class ReportTimings extends ReportTimings_base {}
 declare const DiagnosticEntry_base: Schema.Class<DiagnosticEntry, Schema.Struct<{
-  readonly source: Schema.Literals<readonly ["tsdown", "rolldown", "api-extractor"]>;
+  readonly source: Schema.Literals<readonly ["tsdown", "rolldown", "api-extractor", "meta"]>;
   readonly level: Schema.Literals<readonly ["warn", "error"]>;
   readonly text: Schema.String;
   /**
@@ -189,7 +190,8 @@ declare const DiagnosticEntry_base: Schema.Class<DiagnosticEntry, Schema.Struct<
   readonly column: Schema.optional<Schema.Number>;
 }>, {}>;
 /**
- * A captured warning or error, from tsdown's logger, rolldown's onLog, or API Extractor.
+ * A captured warning or error, from tsdown's logger, rolldown's onLog, API Extractor, or the meta
+ * pass's own sidecar work (`tsdoctor.json` sources, Open Graph generation).
  *
  * @public
  */
@@ -783,6 +785,22 @@ declare class ConfigValidationError extends ConfigValidationError_base<{
 }> {
   get message(): string;
 }
+declare const TsdoctorEmitError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "TsdoctorEmitError";
+} & Readonly<A>;
+/**
+ * Writing the `tsdoctor.json` sidecar failed — the composed manifest did not encode, or the file
+ * could not be written (a read-only or full disk). Recorded in `issues.json` as a `meta` error.
+ *
+ * @public
+ */
+declare class TsdoctorEmitError extends TsdoctorEmitError_base<{
+  readonly packageName: string;
+  readonly path: string;
+  readonly cause: unknown;
+}> {
+  get message(): string;
+}
 //#endregion
 //#region src/entry/extract.d.ts
 /** @public */
@@ -1047,6 +1065,50 @@ interface PkgOsCpu {
  */
 declare function normalizeExeOptions(exe: ExeConfig | ReadonlyArray<ExeConfig>, pkg: PkgOsCpu): ReadonlyArray<NormalizedExe>;
 //#endregion
+//#region src/meta/tsdoctor-config.d.ts
+/**
+ * What an Open Graph image generator receives: the merged identity of the
+ * package being built, after the config, leaf and project tiers resolved.
+ *
+ * @public
+ */
+interface OgImageInfo {
+  /** Display name — the merged `name`, falling back to the npm name. */
+  readonly name: string;
+  /** The npm package name. */
+  readonly packageName: string;
+  /** The emitted version (the optimistic next version when enabled). */
+  readonly version: string;
+  readonly tagline?: string | undefined;
+  readonly description?: string | undefined;
+  /** The inherited project tier, when the workspace root declares one. */
+  readonly project?: {
+    readonly name?: string | undefined;
+    readonly tagline?: string | undefined;
+  } | 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
+ * (project).
+ *
+ * @public
+ */
+interface TsdoctorMetaOptions {
+  readonly name?: string | undefined;
+  readonly tagline?: string | undefined;
+  readonly description?: string | undefined;
+  readonly openGraph?: {
+    /** 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;
+  } | undefined;
+  /** Registries; `false` disables the default derived from `targets.json`. */
+  readonly registries?: ReadonlyArray<RegistryRef> | false | undefined;
+}
+//#endregion
 //#region src/meta/config.d.ts
 /**
  * A single TSDoc tag definition (parity with api-extractor's TSDoc config).
@@ -1091,6 +1153,14 @@ interface MetaOptions {
    */
   readonly optimistic?: "auto" | boolean | undefined;
   readonly tsdoc?: TsdocOptions | undefined;
+  /**
+   * The CONFIG tier of the emitted `tsdoctor.json` sidecar (ranked over the package's and the
+   * workspace root's `tsdoctor.json` source files) and the optional build-time Open Graph image.
+   * The project tier is found through workspace discovery, which requires the workspace root's
+   * `package.json` to declare a `version`; without one, discovery fails silently and no `project`
+   * tier is emitted.
+   */
+  readonly tsdoctor?: TsdoctorMetaOptions | undefined;
 }
 /**
  * Fully-resolved meta options (no optionals).
@@ -1104,6 +1174,8 @@ interface NormalizedMeta {
     readonly suppressWarnings: ReadonlyArray<WarningSuppressionRule>;
     readonly tagDefinitions: ReadonlyArray<TsdocTagDefinition>;
   };
+  /** Passed through verbatim; `undefined` means no config tier (the source tiers still apply). */
+  readonly tsdoctor: TsdoctorMetaOptions | undefined;
 }
 /**
  * Fill defaults so downstream code never branches on undefined.
@@ -1437,6 +1509,83 @@ declare function resolveJsxConfig(tsconfig: TsconfigJsx, override: JsxConfig | u
  */
 declare function readTsconfigJsx(cwd: string): TsconfigJsx;
 //#endregion
+//#region src/meta/tsdoctor-manifest.d.ts
+/**
+ * A `targets.json` target as the manifest composer sees it: the human label and the registry endpoint.
+ *
+ * @public
+ */
+interface ManifestTarget {
+  readonly name: string;
+  readonly registry: string;
+}
+/**
+ * Everything {@link composeTsdoctorManifest} needs: the three authoring tiers plus the build facts
+ * that derive the rest.
+ *
+ * @public
+ */
+interface ComposeManifestInput {
+  readonly config: TsdoctorMetaOptions | undefined;
+  readonly leaf: ManifestSource | undefined;
+  readonly project: ManifestSource | undefined;
+  readonly packageName: string;
+  readonly isPrivate: boolean;
+  /** `targets.json` targets for the group being emitted. */
+  readonly targets: ReadonlyArray<ManifestTarget>;
+  /** The image `og-image.ts` wrote, already sized. */
+  readonly generatedImage: OpenGraphImage | undefined;
+  /** The emitted manifest's `repository` field; a GitHub Packages target derives its page URL from it. */
+  readonly repository?: ManifestRepository | undefined;
+}
+/**
+ * The `repository` field of the emitted `package.json`, as far as the manifest composer reads it.
+ *
+ * @public
+ */
+interface ManifestRepository {
+  readonly url: string;
+  readonly directory?: string | undefined;
+}
+/**
+ * `owner/repo` from any of the GitHub URL spellings a `repository.url` carries (https, `git+https`,
+ * `git@`, `ssh://`, `git://`, the `github:` shorthand), or `undefined` for anything else.
+ *
+ * @public
+ */
+declare function githubOwnerRepo(url: string): {
+  readonly owner: string;
+  readonly repo: string;
+} | undefined;
+/**
+ * Derive the registries block from the build's targets. Only for a public
+ * package: a private one is published nowhere.
+ *
+ * @public
+ */
+declare function registriesFromTargets(input: Pick<ComposeManifestInput, "targets" | "packageName" | "isPrivate" | "repository">): ReadonlyArray<RegistryRef>;
+/**
+ * Flatten the three authoring tiers into the emitted manifest. Pure.
+ *
+ * @remarks
+ * Config beats leaf beats project per FIELD; the project tier is emitted
+ * nested, never flattened, because the consumer's provenance ranking depends
+ * on telling the tiers apart. Returns `undefined` when there is nothing to
+ * say, so a package with no metadata emits no file. An `sbom` pointer is
+ * never written here — the release action upserts it at publish.
+ *
+ * @public
+ */
+declare function composeTsdoctorManifest(input: ComposeManifestInput): BundleManifest | undefined;
+/**
+ * What the generator sees. Built from the same tiers as the manifest.
+ *
+ * @public
+ */
+declare function ogImageInfoOf(input: ComposeManifestInput & {
+  readonly version: string;
+}): OgImageInfo;
+//#endregion
 //#region src/meta/generate.d.ts
 /** @public */
 interface GenerateMetaOptions {
@@ -1474,6 +1623,16 @@ interface GenerateMetaOptions {
   readonly ci?: boolean | undefined;
   /** When set, messages matched by `suppressWarnings` are routed here for accounting. */
   readonly onSuppressed?: ((entry: DiagnosticInput) => void) | undefined;
+  /**
+   * The `tsdoctor.json` sidecar inputs: the config tier, the two source tiers, and the targets bound
+   * to this group (registries derive from them). Omitted means no sidecar and no Open Graph image.
+   */
+  readonly tsdoctor?: {
+    readonly config: TsdoctorMetaOptions | undefined;
+    readonly leaf: ManifestSource | undefined;
+    readonly project: ManifestSource | undefined;
+    readonly targets: ReadonlyArray<ManifestTarget>;
+  } | undefined;
 }
 /** @public */
 interface MetaResult {
@@ -1490,6 +1649,42 @@ interface MetaResult {
  */
 declare function generateMeta(options: GenerateMetaOptions): Promise<MetaResult>;
 //#endregion
+//#region src/meta/og-image.d.ts
+declare const OgGenerateError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "OgGenerateError";
+} & Readonly<A>;
+/**
+ * A configured `openGraph.generate` renderer threw, returned no bytes, or returned bytes that are
+ * not an image. Fails the build: a half-written OG image is worse than none.
+ *
+ * @public
+ */
+declare class OgGenerateError extends OgGenerateError_base<{
+  readonly packageName: string;
+  readonly cause: unknown;
+}> {
+  get message(): string;
+}
+/**
+ * Options for {@link writeGeneratedOgImage}.
+ *
+ * @public
+ */
+interface WriteGeneratedOgImageOptions {
+  readonly generate: (info: OgImageInfo) => Promise<Uint8Array>;
+  readonly info: OgImageInfo;
+  /** The meta bundle dir; the image lands at `og/<unscopedName>.<ext>` beneath it. */
+  readonly outMetaDir: string;
+  readonly unscopedName: string;
+}
+/**
+ * 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).
+ *
+ * @public
+ */
+declare function writeGeneratedOgImage(options: WriteGeneratedOgImageOptions): Promise<OpenGraphImage>;
+//#endregion
 //#region src/meta/optimistic.d.ts
 /**
  * Rewrite a meta `package.json` so the package's own `version` and any workspace-sibling
@@ -1500,6 +1695,46 @@ declare function generateMeta(options: GenerateMetaOptions): Promise<MetaResult>
  */
 declare function rewriteMetaVersions(pkg: Record<string, unknown>, versions: ReadonlyMap<string, string>, selfName: string): Record<string, unknown>;
 //#endregion
+//#region src/meta/tsdoctor-source.d.ts
+declare const TsdoctorSourceError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "TsdoctorSourceError";
+} & Readonly<A>;
+/**
+ * A present `tsdoctor.json` source file that could not be parsed or decoded. Absence is never
+ * this error — a missing source tier is the normal case.
+ *
+ * @public
+ */
+declare class TsdoctorSourceError extends TsdoctorSourceError_base<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {
+  get message(): string;
+}
+/**
+ * The two source tiers a build reads: the package's own file and the workspace root's.
+ *
+ * @public
+ */
+interface TsdoctorSources {
+  readonly leaf: ManifestSource | undefined;
+  readonly project: ManifestSource | undefined;
+  /**
+   * Why workspace discovery failed, when it did. The project tier is then unknown rather than
+   * absent; `runMetaPass` records it as a `meta` warning so the degradation is visible in `issues.json`.
+   */
+  readonly discoveryFailure?: string | undefined;
+}
+/**
+ * Read the leaf (`<cwd>/tsdoctor.json`) and project (`<workspaceRoot>/tsdoctor.json`)
+ * source tiers. Absence is normal; a present file that does not decode throws
+ * {@link TsdoctorSourceError}. A package that IS the workspace root reads its file once, as the
+ * leaf, and has no project tier.
+ *
+ * @public
+ */
+declare function loadTsdoctorSources(cwd: string): Promise<TsdoctorSources>;
+//#endregion
 //#region src/meta/run-pass.d.ts
 /**
  * Options for the meta-pass orchestrator.
@@ -1529,6 +1764,17 @@ interface RunMetaPassOptions {
   readonly resolveNextVersions?: (cwd: string) => Promise<{
     versions: ReadonlyMap<string, string>;
   }>;
+  /**
+   * The resolved `targets.json` targets; each group's `tsdoctor.json` derives its registries from the
+   * targets bound to that group. Omitted (an escape-hatch build with no resolution) means none.
+   */
+  readonly targets?: ReadonlyArray<{
+    group: string;
+    id: string;
+    registry: string;
+  }> | undefined;
+  /** Injectable for tests; defaults to the real loadTsdoctorSources. */
+  readonly loadTsdoctorSources?: (cwd: string) => Promise<TsdoctorSources>;
 }
 /**
  * Meta-pass orchestrator: derives export paths, filters bin/ entries, resolves optimistic
@@ -1865,5 +2111,5 @@ declare function resolveTargets(options: {
   baseName: string;
 }): TargetResolution;
 //#endregion
-export { type AmbientDtsEntry, BuildCollector, BuildCollectorTag, type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildIssues, type BuildPlatform, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, type CopyAmbientDtsOptions, type CssOptions, DEFAULT_EXE_NODE_VERSION, DependencyResolutionError, type DeriveOptions, type DerivedTsdownOptions, type DiagnosticEntry, type DiagnosticInput, type DtsExportClass, type DualExports, type EmitManifestOptions, type EmittedFile, type EntryOverride, type Environment, EnvironmentDetector, type ExeBuild, type ExeConfig, type ExeRewrite, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, ExecutorResolver, type ExtractAmbientOptions, type ExtractOptions, type ExtractResult, FormatSelector, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, JsonFormatter, type JsxConfig, type LooseFileSpec, type LooseFiles, ManifestDecodeError, type ManifestLike, MarkdownFormatter, MetaGenerationError, type MetaOptions, type MetaResult, type ModuleExportNames, type NextVersions, type NormalizedExe, type NormalizedLooseFile, type NormalizedMeta, type OutputFormat, OutputRenderer, 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, ReportPipeline, ReportTimings, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, type RunMetaPassOptions, SilentFormatter, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, TerminalFormatter, type Timer, type TransformManifestOptions, type TsconfigJsx, type TsdocOptions, type TsdocTagDefinition, type TsdownBuild, type TsdownLogger, UnresolvedDependencyError, type ValidationInput, type WarningSuppressionRule, ambientOutName, analyzeReexportBarrel, applySubdirMetaEntries, assertNoEntryCollisions, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, classifyDtsExport, collectExportNames, computeExeFileName, copyAmbientDts, copyPublicDir, createEntryName, createTimer, createTsdownLogger, declarationExt, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractAmbientDts, extractEntries, findRelativeSpecifiers, flattenIssues, formatTime, generateMeta, isTargetObject, mixedDtsExportError, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };
+export { type AmbientDtsEntry, BuildCollector, BuildCollectorTag, type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildIssues, type BuildPlatform, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, CiAnnotationsFormatter, type ComposeManifestInput, ConfigValidationError, ConfigValidator, type CopyAmbientDtsOptions, type CssOptions, DEFAULT_EXE_NODE_VERSION, DependencyResolutionError, type DeriveOptions, type DerivedTsdownOptions, type DiagnosticEntry, type DiagnosticInput, type DtsExportClass, type DualExports, type EmitManifestOptions, type EmittedFile, type EntryOverride, type Environment, EnvironmentDetector, type ExeBuild, type ExeConfig, type ExeRewrite, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, ExecutorResolver, type ExtractAmbientOptions, type ExtractOptions, type ExtractResult, FormatSelector, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, JsonFormatter, type JsxConfig, type LooseFileSpec, type LooseFiles, ManifestDecodeError, type ManifestLike, type ManifestRepository, type ManifestTarget, MarkdownFormatter, MetaGenerationError, type MetaOptions, type MetaResult, type ModuleExportNames, type NextVersions, type NormalizedExe, type NormalizedLooseFile, type NormalizedMeta, OgGenerateError, type OgImageInfo, type OutputFormat, OutputRenderer, 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, ReportPipeline, ReportTimings, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, type RunMetaPassOptions, SilentFormatter, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, TerminalFormatter, type Timer, type TransformManifestOptions, type TsconfigJsx, type TsdocOptions, type TsdocTagDefinition, TsdoctorEmitError, type TsdoctorMetaOptions, TsdoctorSourceError, type TsdoctorSources, type TsdownBuild, type TsdownLogger, UnresolvedDependencyError, type ValidationInput, type WarningSuppressionRule, type WriteGeneratedOgImageOptions, 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 };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,6 +1,6 @@
 import { analyzeReexportBarrel, collectExportNames, renderReexportStub } from "./dts/reexport-stub.js";
 import { buildResolvedTsconfig, writeDtsEmitTsconfig, writeResolvedTsconfig } from "./dts/resolved-tsconfig.js";
-import { ConfigValidationError, MetaGenerationError } from "./errors.js";
+import { ConfigValidationError, MetaGenerationError, TsdoctorEmitError } from "./errors.js";
 import { createEntryName, extractEntries } from "./entry/extract.js";
 import { ambientOutName, assertNoEntryCollisions, classifyDtsExport, declarationExt, extractAmbientDts, mixedDtsExportError } from "./entry/ambient-dts.js";
 import { resolveManifest } from "./catalog/resolve-catalogs.js";
@@ -27,9 +27,12 @@ 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 { resolvePortableTsconfig } from "./meta/tsconfig-resolver.js";
+import { composeTsdoctorManifest, githubOwnerRepo, ogImageInfoOf, registriesFromTargets } from "./meta/tsdoctor-manifest.js";
 import { generateMeta } from "./meta/generate.js";
 import { rewriteMetaVersions } from "./meta/optimistic.js";
+import { TsdoctorSourceError, loadTsdoctorSources } from "./meta/tsdoctor-source.js";
 import { applySubdirMetaEntries, deriveExportPaths, runMetaPass } from "./meta/run-pass.js";
 import { BuildReport, ReportTimings, TargetGroupReport } from "./report/schema.js";
 import { BuildCollector, BuildCollectorTag } from "./report/collector.js";
@@ -47,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, OutputRenderer, ReportPipeline, ReportTimings, SilentFormatter, TargetGroupReport as TargetGroupReportSchema, TerminalFormatter, UnresolvedDependencyError, ambientOutName, analyzeReexportBarrel, applySubdirMetaEntries, assertNoEntryCollisions, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, classifyDtsExport, collectExportNames, computeExeFileName, copyAmbientDts, copyPublicDir, createEntryName, createTimer, createTsdownLogger, declarationExt, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractAmbientDts, extractEntries, findRelativeSpecifiers, flattenIssues, formatTime, generateMeta, isTargetObject, mixedDtsExportError, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, 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, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, writeGeneratedOgImage, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };

package/meta/config.js

@@ -16,7 +16,8 @@ function normalizeMetaOptions(meta, env = process.env) {
 		tsdoc: {
 			suppressWarnings: meta.tsdoc?.suppressWarnings ?? [],
 			tagDefinitions: meta.tsdoc?.tagDefinitions ?? []
-		}
+		},
+		tsdoctor: meta.tsdoctor
 	};
 }
 

package/meta/generate.js

@@ -1,15 +1,31 @@
+import { TsdoctorEmitError } from "../errors.js";
 import { runApiExtractor } from "./api-extractor.js";
 import { mergeApiModels } from "./merge-models.js";
+import { writeGeneratedOgImage } from "./og-image.js";
 import { resolvePortableTsconfig } from "./tsconfig-resolver.js";
 import { writeTsdocConfig } from "./tsdoc-config.js";
+import { composeTsdoctorManifest, ogImageInfoOf } from "./tsdoctor-manifest.js";
 import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { Effect } from "effect";
+import { TSDOCTOR_MANIFEST_FILENAME, encodeBundleManifest } from "@tsdoctor/manifest";
 
 //#region src/meta/generate.ts
 function unscopedName(name) {
 	const slash = name.lastIndexOf("/");
 	return slash >= 0 ? name.slice(slash + 1) : name;
 }
+/** Normalize the manifest's `repository` (string shorthand or object) to the composer's shape. */
+function manifestRepositoryOf(value) {
+	if (typeof value === "string") return value.length > 0 ? { url: value } : void 0;
+	if (typeof value === "object" && value !== null && "url" in value && typeof value.url === "string") {
+		const directory = "directory" in value && typeof value.directory === "string" ? value.directory : void 0;
+		return {
+			url: value.url,
+			...directory !== void 0 ? { directory } : {}
+		};
+	}
+}
 /**
 * Generate the api-model meta bundle from already-emitted .d.ts. Writes tsdoc.json (idempotent),
 * runs the extractor per entry, merges if needed, and writes the "virtual TS env" trio to
@@ -116,12 +132,70 @@ async function generateMeta(options) {
 	const bundleTsconfig = join(outMetaDir, "tsconfig.json");
 	const portableTsconfig = resolvePortableTsconfig(cwd, tsconfigPath);
 	writeFileSync(bundleTsconfig, `${JSON.stringify(portableTsconfig, null, 2)}\n`, "utf-8");
+	rmSync(join(outMetaDir, TSDOCTOR_MANIFEST_FILENAME), { force: true });
+	rmSync(join(outMetaDir, "og"), {
+		recursive: true,
+		force: true
+	});
+	let manifestPath;
+	let generatedImageRelative;
+	if (options.tsdoctor !== void 0) {
+		const composeInput = {
+			config: options.tsdoctor.config,
+			leaf: options.tsdoctor.leaf,
+			project: options.tsdoctor.project,
+			packageName,
+			isPrivate: finalPkg.private === true,
+			targets: options.tsdoctor.targets,
+			generatedImage: void 0,
+			repository: manifestRepositoryOf(finalPkg.repository)
+		};
+		const generate = options.tsdoctor.config?.openGraph?.generate;
+		if (generate !== void 0) {
+			const generated = await writeGeneratedOgImage({
+				generate,
+				info: ogImageInfoOf({
+					...composeInput,
+					version: String(finalPkg.version ?? "0.0.0")
+				}),
+				outMetaDir,
+				unscopedName: unscopedName(packageName)
+			});
+			composeInput.generatedImage = generated;
+			generatedImageRelative = generated.path;
+		}
+		const manifest = composeTsdoctorManifest(composeInput);
+		if (manifest !== void 0) {
+			const path = join(outMetaDir, TSDOCTOR_MANIFEST_FILENAME);
+			try {
+				const encoded = await Effect.runPromise(encodeBundleManifest(manifest));
+				writeFileSync(path, `${JSON.stringify(encoded, null, 2)}\n`, "utf-8");
+			} catch (cause) {
+				throw new TsdoctorEmitError({
+					packageName,
+					path,
+					cause
+				});
+			}
+			manifestPath = path;
+		}
+	}
 	for (const localPath of localPaths) {
 		const dest = join(cwd, localPath);
 		mkdirSync(dest, { recursive: true });
 		copyFileSync(apiJsonPath, join(dest, apiJsonFilename));
 		copyFileSync(bundlePackageJson, join(dest, "package.json"));
 		copyFileSync(bundleTsconfig, join(dest, "tsconfig.json"));
+		if (manifestPath !== void 0) copyFileSync(manifestPath, join(dest, TSDOCTOR_MANIFEST_FILENAME));
+		else rmSync(join(dest, TSDOCTOR_MANIFEST_FILENAME), { force: true });
+		rmSync(join(dest, "og"), {
+			recursive: true,
+			force: true
+		});
+		if (generatedImageRelative !== void 0) {
+			mkdirSync(join(dest, "og"), { recursive: true });
+			copyFileSync(join(outMetaDir, generatedImageRelative), join(dest, generatedImageRelative));
+		}
 	}
 	return {
 		apiJsonPath,

package/meta/og-image.js

@@ -0,0 +1,79 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Data } from "effect";
+import { imageSize } from "image-size";
+
+//#region src/meta/og-image.ts
+/**
+* A configured `openGraph.generate` renderer threw, returned no bytes, or returned bytes that are
+* not an image. Fails the build: a half-written OG image is worse than none.
+*
+* @public
+*/
+var OgGenerateError = class extends Data.TaggedError("OgGenerateError") {
+	get message() {
+		const reason = this.cause instanceof Error ? this.cause.message : String(this.cause);
+		return `Open Graph image generation failed for ${this.packageName}: ${reason}`;
+	}
+};
+/** 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"
+};
+/**
+* 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).
+*
+* @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 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`)
+	});
+	const relative = `og/${options.unscopedName}.${ext}`;
+	try {
+		mkdirSync(join(options.outMetaDir, "og"), { recursive: true });
+		writeFileSync(join(options.outMetaDir, relative), bytes);
+	} catch (cause) {
+		throw new OgGenerateError({
+			packageName: options.info.packageName,
+			cause
+		});
+	}
+	return {
+		path: relative,
+		type,
+		width: size.width,
+		height: size.height
+	};
+}
+
+//#endregion
+export { OgGenerateError, writeGeneratedOgImage };

package/meta/run-pass.js

@@ -1,9 +1,12 @@
+import { TsdoctorEmitError } from "../errors.js";
 import { createEntryName } from "../entry/extract.js";
 import { declarationsDirFor } from "../build/target-groups.js";
 import { resolveNextVersions } from "../changesets/next-versions.js";
 import { normalizeMetaOptions } from "./config.js";
+import { OgGenerateError } from "./og-image.js";
 import { generateMeta } from "./generate.js";
 import { rewriteMetaVersions } from "./optimistic.js";
+import { TsdoctorSourceError, loadTsdoctorSources } from "./tsdoctor-source.js";
 import { join } from "node:path";
 
 //#region src/meta/run-pass.ts
@@ -27,22 +30,71 @@ async function runMetaPass(o) {
 	const resolveNext = o.resolveNextVersions ?? resolveNextVersions;
 	const nextVersions = norm.optimistic ? await resolveNext(o.cwd) : void 0;
 	const manifestTransform = nextVersions ? (m) => rewriteMetaVersions(m, nextVersions.versions, o.packageName) : void 0;
-	for (const g of o.groups) await gen({
-		cwd: o.cwd,
-		packageName: o.packageName,
-		tsconfigPath: o.tsconfigPath,
-		dtsDir: join(o.cwd, "dist", "prod", g.id, "pkg"),
-		aeInputDir: declarationsDirFor(o.cwd, g.id),
-		entries: dtsBasenames,
-		exportPaths,
-		outMetaDir: join(o.cwd, "dist", "prod", g.id, "meta"),
-		localPaths: g.id === canonicalId ? norm.localPaths : [],
-		tsdoc: norm.tsdoc,
-		...manifestTransform !== void 0 ? { manifestTransform } : {},
-		ci: o.ci,
-		onMessage: (e) => e.level === "error" ? o.collector.recordError(g.id, e) : o.collector.recordWarning(g.id, e),
-		onSuppressed: (e) => o.collector.recordSuppressed(g.id, e)
+	const loadSources = o.loadTsdoctorSources ?? loadTsdoctorSources;
+	let sources;
+	try {
+		sources = await loadSources(o.cwd);
+	} catch (err) {
+		if (err instanceof TsdoctorSourceError) for (const g of o.groups) o.collector.recordError(g.id, {
+			source: "meta",
+			level: "error",
+			code: "tsdoctor-source-invalid",
+			text: err.message,
+			file: err.path
+		});
+		throw err;
+	}
+	if (sources.discoveryFailure !== void 0) for (const g of o.groups) o.collector.recordWarning(g.id, {
+		source: "meta",
+		level: "warn",
+		code: "tsdoctor-workspace-discovery-failed",
+		text: `Workspace discovery failed, so tsdoctor.json has no project tier: ${sources.discoveryFailure}`
 	});
+	for (const g of o.groups) {
+		const targets = (o.targets ?? []).filter((t) => t.group === g.id).map((t) => ({
+			name: t.id,
+			registry: t.registry
+		}));
+		try {
+			await gen({
+				cwd: o.cwd,
+				packageName: o.packageName,
+				tsconfigPath: o.tsconfigPath,
+				dtsDir: join(o.cwd, "dist", "prod", g.id, "pkg"),
+				aeInputDir: declarationsDirFor(o.cwd, g.id),
+				entries: dtsBasenames,
+				exportPaths,
+				outMetaDir: join(o.cwd, "dist", "prod", g.id, "meta"),
+				localPaths: g.id === canonicalId ? norm.localPaths : [],
+				tsdoc: norm.tsdoc,
+				...manifestTransform !== void 0 ? { manifestTransform } : {},
+				ci: o.ci,
+				tsdoctor: {
+					config: norm.tsdoctor,
+					leaf: sources.leaf,
+					project: sources.project,
+					targets
+				},
+				onMessage: (e) => e.level === "error" ? o.collector.recordError(g.id, e) : o.collector.recordWarning(g.id, e),
+				onSuppressed: (e) => o.collector.recordSuppressed(g.id, e)
+			});
+		} catch (err) {
+			if (err instanceof OgGenerateError) o.collector.recordError(g.id, {
+				source: "meta",
+				level: "error",
+				code: "og-generate-failed",
+				text: err.message
+			});
+			else if (err instanceof TsdoctorEmitError) o.collector.recordError(g.id, {
+				source: "meta",
+				level: "error",
+				code: "tsdoctor-emit-failed",
+				text: err.message,
+				file: err.path
+			});
+			throw err;
+		}
+	}
 }
 /**
 * Map entry names to export paths using the package exports map. index maps to ".".

package/meta/tsdoctor-manifest.js

@@ -0,0 +1,135 @@
+import { MANIFEST_SPEC } from "@tsdoctor/manifest";
+
+//#region src/meta/tsdoctor-manifest.ts
+const first = (...values) => values.find((v) => v !== void 0);
+/**
+* `owner/repo` from any of the GitHub URL spellings a `repository.url` carries (https, `git+https`,
+* `git@`, `ssh://`, `git://`, the `github:` shorthand), or `undefined` for anything else.
+*
+* @public
+*/
+function githubOwnerRepo(url) {
+	const match = /^(?:git\+)?(?:https?:\/\/|git:\/\/|ssh:\/\/(?:git@)?|git@)?(?:www\.)?github\.com[/:]([^/]{1,214})\/([^/]{1,214}?)(?:\.git)?\/?$/i.exec(url.trim()) ?? /^github:([^/]{1,214})\/([^/]{1,214}?)(?:\.git)?$/i.exec(url.trim());
+	if (match === null) return void 0;
+	const owner = match[1];
+	const repo = match[2];
+	if (owner === void 0 || repo === void 0 || owner.length === 0 || repo.length === 0) return void 0;
+	return {
+		owner,
+		repo
+	};
+}
+function unscopedName(name) {
+	const slash = name.lastIndexOf("/");
+	return slash >= 0 ? name.slice(slash + 1) : name;
+}
+/**
+* The package's human page on a registry, or `undefined` when no real page can be derived. npmjs
+* has a well-known page; GitHub Packages pages hang off the repository, so they need a parseable
+* `repository.url` and are omitted rather than emitted as a dead link when it is missing.
+*/
+/** Strip trailing slashes without a `/\/+$/` regex, which backtracks polynomially on slash runs (CodeQL js/polynomial-redos). */
+function stripTrailingSlashes(value) {
+	let end = value.length;
+	while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+	return value.slice(0, end);
+}
+function packagePageUrl(registry, packageName, repository) {
+	const host = stripTrailingSlashes(registry);
+	if (host === "https://registry.npmjs.org") return `https://www.npmjs.com/package/${packageName}`;
+	if (/^https?:\/\/npm\.pkg\.github\.com$/i.test(host)) {
+		const gh = repository !== void 0 ? githubOwnerRepo(repository.url) : void 0;
+		return gh === void 0 ? void 0 : `https://github.com/${gh.owner}/${gh.repo}/pkgs/npm/${unscopedName(packageName)}`;
+	}
+	return `${host}/package/${packageName}`;
+}
+function projectIdentityOf(project) {
+	if (project === void 0) return void 0;
+	if (project.name === void 0 && project.tagline === void 0) return void 0;
+	return {
+		...project.name !== void 0 ? { name: project.name } : {},
+		...project.tagline !== void 0 ? { tagline: project.tagline } : {}
+	};
+}
+/**
+* Derive the registries block from the build's targets. Only for a public
+* package: a private one is published nowhere.
+*
+* @public
+*/
+function registriesFromTargets(input) {
+	if (input.isPrivate) return [];
+	const out = [];
+	for (const t of input.targets) {
+		const url = packagePageUrl(t.registry, input.packageName, input.repository);
+		if (url !== void 0) out.push({
+			type: "npm",
+			name: t.name,
+			url
+		});
+	}
+	return out;
+}
+/**
+* Flatten the three authoring tiers into the emitted manifest. Pure.
+*
+* @remarks
+* Config beats leaf beats project per FIELD; the project tier is emitted
+* nested, never flattened, because the consumer's provenance ranking depends
+* on telling the tiers apart. Returns `undefined` when there is nothing to
+* say, so a package with no metadata emits no file. An `sbom` pointer is
+* never written here — the release action upserts it at publish.
+*
+* @public
+*/
+function composeTsdoctorManifest(input) {
+	const { config, leaf, project } = input;
+	const images = [
+		...input.generatedImage !== void 0 ? [input.generatedImage] : [],
+		...config?.openGraph?.images ?? [],
+		...leaf?.openGraph?.images ?? [],
+		...project?.openGraph?.images ?? []
+	];
+	const themeColor = first(config?.openGraph?.themeColor, leaf?.openGraph?.themeColor, project?.openGraph?.themeColor);
+	const openGraph = images.length > 0 || themeColor !== void 0 ? {
+		...images.length > 0 ? { images } : {},
+		...themeColor !== void 0 ? { themeColor } : {}
+	} : void 0;
+	const registries = config?.registries === false ? void 0 : first(config?.registries, leaf?.registries) ?? registriesFromTargets(input);
+	const name = first(config?.name, leaf?.name);
+	const tagline = first(config?.tagline, leaf?.tagline);
+	const description = first(config?.description, leaf?.description);
+	const projectIdentity = projectIdentityOf(project);
+	const manifest = {
+		spec: MANIFEST_SPEC,
+		...name !== void 0 ? { name } : {},
+		...tagline !== void 0 ? { tagline } : {},
+		...description !== void 0 ? { description } : {},
+		...projectIdentity !== void 0 ? { project: projectIdentity } : {},
+		...openGraph !== void 0 ? { openGraph } : {},
+		...registries !== void 0 && registries.length > 0 ? { registries } : {}
+	};
+	return Object.keys(manifest).length > 1 ? manifest : void 0;
+}
+/**
+* What the generator sees. Built from the same tiers as the manifest.
+*
+* @public
+*/
+function ogImageInfoOf(input) {
+	const { config, leaf, project } = input;
+	const tagline = first(config?.tagline, leaf?.tagline, project?.tagline);
+	const description = first(config?.description, leaf?.description);
+	const projectIdentity = projectIdentityOf(project);
+	return {
+		name: first(config?.name, leaf?.name) ?? input.packageName,
+		packageName: input.packageName,
+		version: input.version,
+		...tagline !== void 0 ? { tagline } : {},
+		...description !== void 0 ? { description } : {},
+		...projectIdentity !== void 0 ? { project: projectIdentity } : {}
+	};
+}
+
+//#endregion
+export { composeTsdoctorManifest, githubOwnerRepo, ogImageInfoOf, registriesFromTargets };

package/meta/tsdoctor-source.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Data, Effect, Layer } from "effect";
+import { NodeFileSystem, NodePath } from "@effect/platform-node";
+import { WorkspaceDiscovery, WorkspaceRootNotFoundError, Workspaces } from "@effected/workspaces";
+import { TSDOCTOR_MANIFEST_FILENAME, decodeManifestSource } from "@tsdoctor/manifest";
+
+//#region src/meta/tsdoctor-source.ts
+/**
+* A present `tsdoctor.json` source file that could not be parsed or decoded. Absence is never
+* this error — a missing source tier is the normal case.
+*
+* @public
+*/
+var TsdoctorSourceError = class extends Data.TaggedError("TsdoctorSourceError") {
+	get message() {
+		return `Invalid ${TSDOCTOR_MANIFEST_FILENAME} at ${this.path}`;
+	}
+};
+/** Bound once: the platform layer is stateless and layers memoize by reference. */
+const platform = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);
+/** The canonical absolute form of a directory, so a relative or symlinked `cwd` compares equal to the discovered root. */
+function canonical(dir) {
+	const absolute = resolve(dir);
+	try {
+		return realpathSync(absolute);
+	} catch {
+		return absolute;
+	}
+}
+/** `Effect.runPromise` rejects with the failure itself or with a `FiberFailure` wrapping it; check both. */
+function isRootNotFound(cause) {
+	if (cause instanceof WorkspaceRootNotFoundError) return true;
+	return typeof cause === "object" && cause !== null && "_tag" in cause && cause._tag === "WorkspaceRootNotFoundError";
+}
+/**
+* The workspace root containing `cwd`, or the reason discovery failed. A package outside any
+* workspace is the `root: undefined` case with no failure. Mirrors the `WorkspaceDiscovery`
+* invocation in `changesets/next-versions.ts`.
+*/
+async function findWorkspaceRoot(cwd) {
+	try {
+		const packages = await Effect.runPromise(Effect.gen(function* () {
+			return yield* (yield* WorkspaceDiscovery).listPackages();
+		}).pipe(Effect.provide(Workspaces.layer({ cwd }).pipe(Layer.provide(platform)))));
+		return { root: packages[0]?.isRootWorkspace ? packages[0].path : void 0 };
+	} catch (cause) {
+		if (isRootNotFound(cause)) return { root: void 0 };
+		return {
+			root: void 0,
+			failure: cause instanceof Error ? cause.message : String(cause)
+		};
+	}
+}
+async function readSource(path) {
+	if (!existsSync(path)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf-8"));
+	} catch (cause) {
+		throw new TsdoctorSourceError({
+			path,
+			cause
+		});
+	}
+	const result = await Effect.runPromise(Effect.result(decodeManifestSource(parsed, path)));
+	if (result._tag === "Failure") throw new TsdoctorSourceError({
+		path,
+		cause: result.failure
+	});
+	return result.success;
+}
+/**
+* Read the leaf (`<cwd>/tsdoctor.json`) and project (`<workspaceRoot>/tsdoctor.json`)
+* source tiers. Absence is normal; a present file that does not decode throws
+* {@link TsdoctorSourceError}. A package that IS the workspace root reads its file once, as the
+* leaf, and has no project tier.
+*
+* @public
+*/
+async function loadTsdoctorSources(cwd) {
+	const leafDir = canonical(cwd);
+	const leaf = await readSource(join(leafDir, TSDOCTOR_MANIFEST_FILENAME));
+	const { root, failure } = await findWorkspaceRoot(leafDir);
+	return {
+		leaf,
+		project: root !== void 0 && canonical(root) !== leafDir ? await readSource(join(root, TSDOCTOR_MANIFEST_FILENAME)) : void 0,
+		...failure !== void 0 ? { discoveryFailure: failure } : {}
+	};
+}
+
+//#endregion
+export { TsdoctorSourceError, loadTsdoctorSources };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/tsdown-plugins",
-	"version": "2.5.10",
+	"version": "2.6.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",
@@ -33,12 +33,14 @@
 		"@effect/platform-node": "4.0.0-rc.109",
 		"@effected/npm": "^0.12.1",
 		"@effected/package-json": "^0.13.0",
-		"@effected/tsconfig-json": "^0.6.1",
+		"@effected/tsconfig-json": "^0.7.0",
 		"@effected/workspaces": "^0.18.3",
 		"@microsoft/api-extractor": "^7.59.0",
 		"@microsoft/tsdoc": "^0.16.0",
 		"@microsoft/tsdoc-config": "^0.18.1",
+		"@tsdoctor/manifest": "^0.1.0",
 		"effect": "4.0.0-rc.109",
+		"image-size": "^2.0.2",
 		"picocolors": "^1.1.1",
 		"std-env": "^4.2.0",
 		"tsdown": "^0.22.14",

package/report/schema.js

@@ -4,7 +4,8 @@ import { Schema } from "effect";
 /** @public */
 var ReportTimings = class extends Schema.Class("ReportTimings")({ totalMs: Schema.Number }) {};
 /**
-* A captured warning or error, from tsdown's logger, rolldown's onLog, or API Extractor.
+* A captured warning or error, from tsdown's logger, rolldown's onLog, API Extractor, or the meta
+* pass's own sidecar work (`tsdoctor.json` sources, Open Graph generation).
 *
 * @public
 */
@@ -12,7 +13,8 @@ var DiagnosticEntry = class extends Schema.Class("DiagnosticEntry")({
 	source: Schema.Literals([
 		"tsdown",
 		"rolldown",
-		"api-extractor"
+		"api-extractor",
+		"meta"
 	]),
 	level: Schema.Literals(["warn", "error"]),
 	text: Schema.String,