@tsdoctor/bundle 0.1.0

package/index.d.ts

@@ -0,0 +1,885 @@
+import { PackageManifest } from "@effected/package-json";
+import { CompilerOptions, ResolvedTsconfig } from "@effected/tsconfig-json";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { GitHubRelease } from "@effected/github";
+import { NpmRegistry, PackageTarball, RegistryTarget } from "@effected/npm";
+import { Cache } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
+//#region src/BundleManifest.d.ts
+/**
+ * The registry protocol families this reader knows how to do more than link
+ * to. `"npm"` means an npm-compatible registry — install commands and tarball
+ * fetching work against any instance of it — and `"jsr"` the jsr protocol.
+ *
+ * @remarks
+ * The manifest's `type` field is deliberately NOT constrained to these
+ * values: unknown future types must degrade to link-only rendering, not
+ * reject the manifest. Use {@link isKnownRegistryType} to branch.
+ *
+ * @public
+ */
+declare const KNOWN_REGISTRY_TYPES: readonly ["npm", "jsr"];
+/**
+ * A registry protocol family this reader recognizes.
+ *
+ * @public
+ */
+type KnownRegistryType = (typeof KNOWN_REGISTRY_TYPES)[number];
+/**
+ * Whether a registry `type` value is a protocol family this reader
+ * recognizes. `false` means the registry entry should degrade to link-only
+ * rendering — it is never a validation failure.
+ *
+ * @public
+ */
+declare function isKnownRegistryType(type: string): type is KnownRegistryType;
+/**
+ * One registry the documented package is published to.
+ *
+ * @remarks
+ * `type` is the PROTOCOL FAMILY (`"npm"` covers every npm-compatible
+ * registry), `name` the human instance label, `url` the package's page on
+ * that instance. Unknown `type` values decode successfully and degrade to
+ * link-only rendering (see {@link isKnownRegistryType}).
+ *
+ * @public
+ */
+declare const RegistryRef: Schema.Struct<{
+  /** The protocol family, e.g. `"npm"` or `"jsr"`. Unknown values are accepted. */
+  readonly type: Schema.String;
+  /** The human instance label, e.g. `"npm"` or `"Savvy Web Registry"`. */
+  readonly name: Schema.String;
+  /** The package's URL on that registry instance. */
+  readonly url: Schema.String;
+}>;
+/**
+ * The decoded type of {@link (RegistryRef:variable)}.
+ *
+ * @public
+ */
+type RegistryRef = typeof RegistryRef.Type;
+/**
+ * One Open Graph image declared by the manifest.
+ *
+ * @remarks
+ * Exactly ONE of `path` (a bundle-relative asset the consuming platform
+ * publishes and resolves to a URL) or `url` (an absolute external URL used
+ * verbatim) must be present — the schema enforces the XOR. `type` is a MIME
+ * type, inferred from the file extension by the resolver when omitted; `alt`
+ * has a documented inference chain (tagline → description →
+ * `"<name> API documentation"`).
+ *
+ * @public
+ */
+declare const OpenGraphImage: Schema.Struct<{
+  /** Bundle-relative asset path. Mutually exclusive with `url`. */
+  readonly path: Schema.optionalKey<Schema.String>;
+  /** Absolute external URL, used verbatim. Mutually exclusive with `path`. */
+  readonly url: Schema.optionalKey<Schema.String>;
+  /** MIME type; inferred from the extension when omitted. */
+  readonly type: Schema.optionalKey<Schema.String>;
+  /** Pixel width; 1200×630 (1.91:1) is the cross-platform safe default. */
+  readonly width: Schema.optionalKey<Schema.Int>;
+  /** Pixel height. */
+  readonly height: Schema.optionalKey<Schema.Int>;
+  /** Alt text; inferred (tagline → description → fallback) when omitted. */
+  readonly alt: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * The decoded type of {@link (OpenGraphImage:variable)}.
+ *
+ * @public
+ */
+type OpenGraphImage = typeof OpenGraphImage.Type;
+/**
+ * The manifest's Open Graph block: the asset-ish pieces only — most OG tags
+ * are page-level and derive at render time in the consuming platform.
+ *
+ * @remarks
+ * Multiple images follow OG array semantics: the first declared wins, extras
+ * are alternates (e.g. a portrait 1000×1500 variant).
+ *
+ * @public
+ */
+declare const OpenGraphConfig: Schema.Struct<{
+  /** Declared images, first-wins per OG array semantics. */
+  readonly images: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    /** Bundle-relative asset path. Mutually exclusive with `url`. */
+    readonly path: Schema.optionalKey<Schema.String>;
+    /** Absolute external URL, used verbatim. Mutually exclusive with `path`. */
+    readonly url: Schema.optionalKey<Schema.String>;
+    /** MIME type; inferred from the extension when omitted. */
+    readonly type: Schema.optionalKey<Schema.String>;
+    /** Pixel width; 1200×630 (1.91:1) is the cross-platform safe default. */
+    readonly width: Schema.optionalKey<Schema.Int>;
+    /** Pixel height. */
+    readonly height: Schema.optionalKey<Schema.Int>;
+    /** Alt text; inferred (tagline → description → fallback) when omitted. */
+    readonly alt: Schema.optionalKey<Schema.String>;
+  }>>>;
+  /** Embed accent color (e.g. Discord), a CSS color string. */
+  readonly themeColor: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * The decoded type of {@link (OpenGraphConfig:variable)}.
+ *
+ * @public
+ */
+type OpenGraphConfig = typeof OpenGraphConfig.Type;
+/**
+ * A pointer to the bundle's SBOM, computed by the bundler at publish and
+ * served as a downloadable static asset.
+ *
+ * @public
+ */
+declare const SbomRef: Schema.Struct<{
+  /** Bundle-relative path to the SBOM file. */
+  readonly path: Schema.String;
+  /** SBOM format label, e.g. `"spdx-json"`. Unknown values are accepted. */
+  readonly format: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * The decoded type of {@link (SbomRef:variable)}.
+ *
+ * @public
+ */
+type SbomRef = typeof SbomRef.Type;
+/**
+ * The inherited project tier, flattened into the emitted manifest by the
+ * bundler (a fetched bundle has no parent directory to walk). Kept nested —
+ * structurally distinguishable from the leaf fields — because provenance is
+ * load-bearing for override detection.
+ *
+ * @public
+ */
+declare const ProjectIdentity: Schema.Struct<{
+  /** The project display name, e.g. `"Effected"` over leaf `@effected/store`. */
+  readonly name: Schema.optionalKey<Schema.String>;
+  /** The project tagline. */
+  readonly tagline: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * The decoded type of {@link (ProjectIdentity:variable)}.
+ *
+ * @public
+ */
+type ProjectIdentity = typeof ProjectIdentity.Type;
+/**
+ * The versioned `tsdoctor.json` sidecar manifest — bundle layer 3.
+ *
+ * @remarks
+ * `spec` is the only required field; every other field enriches. Unknown
+ * top-level fields are ignored on decode (additive fields are minor spec
+ * revisions) and unknown enum-ish values (registry `type`, sbom `format`)
+ * degrade gracefully instead of rejecting — an old reader must be able to
+ * consume a new bundle.
+ *
+ * @public
+ */
+declare const BundleManifest: Schema.Struct<{
+  /** The integer spec version. This reader understands spec 1. */
+  readonly spec: Schema.Literal<1>;
+  /** Human display name (the npm name is dry; this one is SEO-friendly). */
+  readonly name: Schema.optionalKey<Schema.String>;
+  /** Short tagline. */
+  readonly tagline: Schema.optionalKey<Schema.String>;
+  /** Long description; overrides the package.json description when present. */
+  readonly description: Schema.optionalKey<Schema.String>;
+  /** The inherited project tier, flattened in at emit time. */
+  readonly project: Schema.optionalKey<Schema.Struct<{
+    /** The project display name, e.g. `"Effected"` over leaf `@effected/store`. */
+    readonly name: Schema.optionalKey<Schema.String>;
+    /** The project tagline. */
+    readonly tagline: Schema.optionalKey<Schema.String>;
+  }>>;
+  /** Open Graph assets. */
+  readonly openGraph: Schema.optionalKey<Schema.Struct<{
+    /** Declared images, first-wins per OG array semantics. */
+    readonly images: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+      /** Bundle-relative asset path. Mutually exclusive with `url`. */
+      readonly path: Schema.optionalKey<Schema.String>;
+      /** Absolute external URL, used verbatim. Mutually exclusive with `path`. */
+      readonly url: Schema.optionalKey<Schema.String>;
+      /** MIME type; inferred from the extension when omitted. */
+      readonly type: Schema.optionalKey<Schema.String>;
+      /** Pixel width; 1200×630 (1.91:1) is the cross-platform safe default. */
+      readonly width: Schema.optionalKey<Schema.Int>;
+      /** Pixel height. */
+      readonly height: Schema.optionalKey<Schema.Int>;
+      /** Alt text; inferred (tagline → description → fallback) when omitted. */
+      readonly alt: Schema.optionalKey<Schema.String>;
+    }>>>;
+    /** Embed accent color (e.g. Discord), a CSS color string. */
+    readonly themeColor: Schema.optionalKey<Schema.String>;
+  }>>;
+  /** SBOM pointer. */
+  readonly sbom: Schema.optionalKey<Schema.Struct<{
+    /** Bundle-relative path to the SBOM file. */
+    readonly path: Schema.String;
+    /** SBOM format label, e.g. `"spdx-json"`. Unknown values are accepted. */
+    readonly format: Schema.optionalKey<Schema.String>;
+  }>>;
+  /** Registries the package is published to. */
+  readonly registries: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    /** The protocol family, e.g. `"npm"` or `"jsr"`. Unknown values are accepted. */
+    readonly type: Schema.String;
+    /** The human instance label, e.g. `"npm"` or `"Savvy Web Registry"`. */
+    readonly name: Schema.String;
+    /** The package's URL on that registry instance. */
+    readonly url: Schema.String;
+  }>>>;
+}>;
+/**
+ * The decoded type of {@link (BundleManifest:variable)}.
+ *
+ * @public
+ */
+type BundleManifest = typeof BundleManifest.Type;
+declare const BundleManifestError_base: Schema.Class<BundleManifestError, Schema.TaggedStruct<"BundleManifestError", {
+  /** The manifest file path, when the failure is tied to a file on disk. */
+  readonly path: Schema.optionalKey<Schema.String>;
+  /** The underlying failure (JSON syntax or schema decode), preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a present `tsdoctor.json` cannot be parsed or does not satisfy
+ * the {@link (BundleManifest:variable)} schema.
+ *
+ * @remarks
+ * Absence of the manifest is NEVER this error — layers enrich, never gate,
+ * so a missing sidecar is the normal case and reads as `Option.none()`.
+ *
+ * @public
+ */
+declare class BundleManifestError extends BundleManifestError_base {
+  get message(): string;
+}
+/**
+ * Decode an unknown value into a {@link (BundleManifest:type)}.
+ *
+ * @remarks
+ * The typed boundary for manifest input that has already been parsed from
+ * JSON (plugin options, fetched payloads). File-based reading lives in
+ * `readBundle`, which routes through this after parsing.
+ *
+ * @public
+ */
+declare function decodeBundleManifest(input: unknown, path?: string): Effect.Effect<BundleManifest, BundleManifestError>;
+//#endregion
+//#region src/Bundle.d.ts
+/**
+ * The sidecar manifest's file name inside a bundle folder.
+ *
+ * @public
+ */
+declare const TSDOCTOR_MANIFEST_FILENAME = "tsdoctor.json";
+/**
+ * The subset of a `<name>.api.json` model this package reads: the package
+ * name from the model's own metadata.
+ *
+ * @remarks
+ * Full model loading (entry points, members, TSDoc) is `@tsdoctor/model`'s
+ * job — this package deliberately stays free of
+ * `@microsoft/api-extractor-model` and reads only what discovery and
+ * resolution need.
+ *
+ * @public
+ */
+interface ApiModelInfo {
+  /** The documented package's npm name, from the model's `name` field. */
+  readonly name: string;
+}
+declare const BundleLayerError_base: Schema.Class<BundleLayerError, Schema.TaggedStruct<"BundleLayerError", {
+  /** Which bundle layer failed. */
+  readonly layer: Schema.Literals<readonly ["apiModel", "packageJson", "tsconfig"]>;
+  /** The file that failed. */
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a PRESENT bundle layer file cannot be read, parsed or decoded.
+ *
+ * @remarks
+ * Absence of layers 1–3 is the normal case (layers enrich, never gate) and
+ * reads as `Option.none()`, never as this error. A file that exists but is
+ * malformed is a real problem worth surfacing, not degrading past. Manifest
+ * (layer 3) failures use {@link BundleManifestError} instead, so manifest
+ * consumers handle one tag across the file and non-file boundaries.
+ *
+ * @public
+ */
+declare class BundleLayerError extends BundleLayerError_base {
+  get message(): string;
+}
+/**
+ * Where a bundle's layer files live: the output of discovery, the input of
+ * {@link readBundle}.
+ *
+ * @remarks
+ * `modelPath` is the one required layer; the optional path fields are present
+ * iff the corresponding file existed at discovery time. `name` and `version`
+ * are pre-parsed during discovery (name from package.json, falling back to
+ * the api.json model; version from package.json when present).
+ *
+ * @public
+ */
+interface BundleDescriptor {
+  /** Absolute path to the bundle folder. */
+  readonly dir: string;
+  /** Last path segment of `dir`, e.g. `"kitchensink"`. */
+  readonly dirname: string;
+  /** The documented package's npm name. */
+  readonly name: string;
+  /** The package version from package.json, when present. */
+  readonly version?: string;
+  /** Absolute path to the layer-0 `*.api.json` model. */
+  readonly modelPath: string;
+  /** Absolute path to the layer-1 package.json, when present. */
+  readonly packageJsonPath?: string;
+  /** Absolute path to the layer-2 tsconfig.json, when present. */
+  readonly tsconfigPath?: string;
+  /** Absolute path to the layer-3 tsdoctor.json manifest, when present. */
+  readonly manifestPath?: string;
+}
+/**
+ * A bundle with all four layers read into typed structures. Layers 1–3 are
+ * `Option`s because their absence is the normal case.
+ *
+ * @public
+ */
+interface Bundle {
+  /** The descriptor the bundle was read from. */
+  readonly descriptor: BundleDescriptor;
+  /** Layer 0: the api.json model header (always present). */
+  readonly apiModel: ApiModelInfo;
+  /** Layer 1: the package.json manifest, presence-lenient. */
+  readonly packageJson: Option.Option<PackageManifest>;
+  /** Layer 2: the tsconfig, extends-resolved. */
+  readonly tsconfig: Option.Option<ResolvedTsconfig>;
+  /** Layer 3: the tsdoctor.json sidecar manifest. */
+  readonly manifest: Option.Option<BundleManifest>;
+}
+/**
+ * Read the layer-0 model header — the package name — from a `*.api.json`
+ * file.
+ *
+ * @remarks
+ * Parses the whole file as JSON but validates only the `name` field; see
+ * {@link ApiModelInfo} for why nothing more is read here.
+ *
+ * @public
+ */
+declare function readApiModelInfo(modelPath: string): Effect.Effect<ApiModelInfo, BundleLayerError, FileSystem.FileSystem>;
+/**
+ * Read all four layers of a discovered bundle into a {@link Bundle}.
+ *
+ * @remarks
+ * Layer 0 is required; layers 1–3 read to `Option.none()` when the
+ * descriptor recorded no file for them. A layer file that is present but
+ * malformed fails typed ({@link BundleLayerError}, or
+ * {@link BundleManifestError} for the manifest) — lenient about absence,
+ * strict about shape. `FileSystem` and `Path` stay in the `R` channel;
+ * provide the platform layer once at the application boundary.
+ *
+ * @public
+ */
+declare function readBundle(descriptor: BundleDescriptor): Effect.Effect<Bundle, BundleLayerError | BundleManifestError, FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/BundleDiscovery.d.ts
+declare const BundleDiscoveryError_base: Schema.Class<BundleDiscoveryError, Schema.TaggedStruct<"BundleDiscoveryError", {
+  /** The directory (or file) the failure is about. */
+  readonly path: Schema.String;
+  /** What went wrong, structurally. */
+  readonly reason: Schema.Literals<readonly ["notFound", "notADirectory", "noApiModel", "ambiguousApiModel", "invalidPackageJson", "unreadableDirectory", "notABundleFolder", "emptyParent"]>;
+  /** Human context for the failure (candidate lists, offending names). */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, when one exists, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a directory cannot be resolved into a bundle descriptor.
+ *
+ * @remarks
+ * Discovery failures are USER-facing wiring problems — a missing folder, no
+ * model file, an ambiguous model set — so the `reason` is a typed literal a
+ * consumer can branch on for actionable messaging.
+ *
+ * @public
+ */
+declare class BundleDiscoveryError extends BundleDiscoveryError_base {
+  get message(): string;
+}
+/**
+ * Overrides for {@link discoverBundle}. Any supplied field wins over
+ * discovery.
+ *
+ * @public
+ */
+interface BundleOverrides {
+  /** The package name to use instead of the discovered one. */
+  readonly name?: string;
+  /** The version to use instead of the discovered one. */
+  readonly version?: string;
+  /** The model path to use instead of `*.api.json` discovery (resolved against the bundle dir when relative). */
+  readonly modelPath?: string;
+}
+/**
+ * Options for {@link discoverBundle}.
+ *
+ * @public
+ */
+interface DiscoverBundleOptions {
+  /** Base for resolving a relative `dir`. When omitted, a relative `dir` resolves per the injected `Path` service. */
+  readonly cwd?: string;
+  /** Caller-supplied fields that win over discovery. */
+  readonly overrides?: BundleOverrides;
+}
+/**
+ * Options for {@link discoverBundles}.
+ *
+ * @public
+ */
+interface DiscoverBundlesOptions {
+  /** Base for resolving a relative `parentDir`. */
+  readonly cwd?: string;
+}
+/**
+ * Discover a single bundle folder into a {@link BundleDescriptor}.
+ *
+ * @remarks
+ * Generalizes the RSPress plugin's `api.fromDir` helper, framework-neutral:
+ * no route derivation — that stays in the adapter. Layer 0 (`*.api.json`) is
+ * required; package.json, tsconfig.json and tsdoctor.json are recorded when
+ * present. The package name comes from package.json when it has one, falling
+ * back to the api.json model's own name; the version comes from package.json
+ * alone. Caller overrides win over discovery. `FileSystem` and `Path` stay
+ * in the `R` channel — provide the platform layer at the application
+ * boundary.
+ *
+ * @public
+ */
+declare function discoverBundle(dir: string, options?: DiscoverBundleOptions): Effect.Effect<BundleDescriptor, BundleDiscoveryError | BundleLayerError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Strictly scan a parent directory and discover one bundle per subfolder.
+ *
+ * @remarks
+ * Generalizes the RSPress plugin's `apis.fromDir`: every non-dotfile
+ * subdirectory MUST be a valid bundle folder (contain at least one
+ * `*.api.json`) — a stray subfolder fails discovery with guidance to use
+ * {@link discoverBundle} for selective inclusion — and an empty scan is a
+ * failure, not an empty array (the models have probably not been built).
+ * Subfolders are processed in sorted order.
+ *
+ * @public
+ */
+declare function discoverBundles(parentDir: string, options?: DiscoverBundlesOptions): Effect.Effect<ReadonlyArray<BundleDescriptor>, BundleDiscoveryError | BundleLayerError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Discover and read a single bundle in one call.
+ *
+ * @public
+ */
+declare function loadBundle(dir: string, options?: DiscoverBundleOptions): Effect.Effect<Bundle, BundleDiscoveryError | BundleLayerError | BundleManifestError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Discover and read every bundle under a parent directory in one call.
+ *
+ * @public
+ */
+declare function loadBundles(parentDir: string, options?: DiscoverBundlesOptions): Effect.Effect<ReadonlyArray<Bundle>, BundleDiscoveryError | BundleLayerError | BundleManifestError, FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/BundleFetch.d.ts
+declare const BundleFetchError_base: Schema.Class<BundleFetchError, Schema.TaggedStruct<"BundleFetchError", {
+  /** Which fetcher failed. */
+  readonly source: Schema.Literals<readonly ["npm", "github"]>;
+  /** What went wrong, structurally. */
+  readonly reason: Schema.Literals<readonly ["invalidRef", "versionNotFound", "releaseNotFound", "assetNotFound", "assetAmbiguous", "download", "notABundle", "cache"]>;
+  /** The remote coordinate: `name@version` or `owner/repo@tag#asset`. */
+  readonly ref: Schema.String;
+  /** Human context for the failure. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+  /** The underlying failure, when one exists, preserved structurally. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when a remote bundle cannot be fetched into the local cache.
+ *
+ * @remarks
+ * Fetch-plane failures speak in remote terms (`ref` names the coordinate the
+ * caller asked for, never a temp directory). Post-fetch READ failures — a
+ * fetched artifact whose layer files are malformed — surface as the same
+ * typed errors local reads produce (`BundleLayerError`,
+ * `BundleManifestError`), so a consumer handles one vocabulary for both.
+ *
+ * @public
+ */
+declare class BundleFetchError extends BundleFetchError_base {
+  get message(): string;
+}
+/**
+ * Options for {@link fetchNpmBundle}.
+ *
+ * @public
+ */
+interface FetchNpmBundleOptions {
+  /** The published package name. */
+  readonly name: string;
+  /**
+   * An exact version or a dist-tag (e.g. `"latest"`). Ranges are not
+   * resolved by this fetcher — resolve them upstream.
+   */
+  readonly version: string;
+  /**
+   * The registry to read — any `type: "npm"` (npm-protocol-family) registry,
+   * per the manifest's registries semantics. Defaults to the public npm
+   * registry.
+   */
+  readonly target?: RegistryTarget;
+  /** Bypass the cache and refetch. */
+  readonly refresh?: boolean;
+}
+/**
+ * Options for {@link fetchGitHubReleaseBundle}.
+ *
+ * @public
+ */
+interface FetchGitHubReleaseBundleOptions {
+  /** The repository owner. */
+  readonly owner: string;
+  /** The repository name. */
+  readonly repo: string;
+  /** The release tag. */
+  readonly tag: string;
+  /**
+   * The exact asset file name. When omitted, the release must carry exactly
+   * ONE `*.npm.meta.tgz` asset (the bundle release variant) and that asset
+   * is used.
+   */
+  readonly asset?: string;
+  /**
+   * Bypass the cache and refetch. Unlike npm versions, a git tag CAN move —
+   * the cache treats tags as immutable by default, and this is the escape
+   * hatch when one has.
+   */
+  readonly refresh?: boolean;
+}
+/**
+ * Fetch one published npm package version as a bundle, through the durable
+ * XDG cache.
+ *
+ * @remarks
+ * Works against any npm-protocol-family registry via `target` (the
+ * `type: "npm"` semantics of the manifest's registries block). The tarball is
+ * downloaded, integrity-verified and extracted by `@effected/npm`'s
+ * `PackageTarball`, its bundle layer files are copied into
+ * `<xdg-cache>/tsdoctor/bundles/npm/<name>/<version>/`, and the returned
+ * {@link Bundle}'s descriptor points at that durable directory. A published
+ * npm version is immutable, so a cache hit skips the network entirely;
+ * `refresh: true` forces a refetch.
+ *
+ * Provide the `NpmRegistry`, `PackageTarball`, `Cache` and `AppDirs`
+ * services (plus `FileSystem`/`Path`) at the application boundary.
+ *
+ * @public
+ */
+declare function fetchNpmBundle(options: FetchNpmBundleOptions): Effect.Effect<Bundle, BundleFetchError | BundleLayerError | BundleManifestError, NpmRegistry | PackageTarball | Cache | AppDirs | FileSystem.FileSystem | Path.Path>;
+/**
+ * Fetch a bundle attached to a GitHub release as a `*.npm.meta.tgz`-style
+ * asset, through the durable XDG cache.
+ *
+ * @remarks
+ * The release is looked up by tag via `@effected/github`'s `GitHubRelease`
+ * (the `Repo` context is provided internally from `owner`/`repo`), the chosen
+ * asset is downloaded and extracted through the same verified
+ * `PackageTarball` path the npm fetcher uses (no integrity is available for
+ * release assets, so the download is unverified — the extractor logs this),
+ * and the layer files land in
+ * `<xdg-cache>/tsdoctor/bundles/github/<owner>/<repo>/<tag>/<asset>/`.
+ *
+ * A tarball with an npm-style `package/` root and one with its files at the
+ * archive root are both accepted. Git tags CAN move; the cache treats them as
+ * immutable and `refresh: true` is the escape hatch. Private-repo assets are
+ * not supported yet: the asset's browser download URL is fetched directly,
+ * which works for public releases only.
+ *
+ * @public
+ */
+declare function fetchGitHubReleaseBundle(options: FetchGitHubReleaseBundleOptions): Effect.Effect<Bundle, BundleFetchError | BundleLayerError | BundleManifestError, GitHubRelease | PackageTarball | Cache | AppDirs | FileSystem.FileSystem | Path.Path>;
+//#endregion
+//#region src/PlatformOverrides.d.ts
+/**
+ * The `manifest.platform` tier: a data-override object a consumer passes
+ * through platform options (e.g. `ApiExtractorPlugin(options)`), sitting at
+ * the TOP of the tier ranking.
+ *
+ * @remarks
+ * Same field surface as the authored manifest tiers — name, tagline,
+ * description, openGraph, sbom, registries — with no `spec` field (it is not
+ * a file with an independent version) and no `project` block (it is a single
+ * tier, not a flattened hierarchy). Lets a user with ONLY an api.json declare
+ * identity/OG/registries declaratively; the resolver does the merging.
+ *
+ * @public
+ */
+declare const PlatformOverrides: Schema.Struct<{
+  /** Human display name override. */
+  readonly name: Schema.optionalKey<Schema.String>;
+  /** Tagline override. */
+  readonly tagline: Schema.optionalKey<Schema.String>;
+  /** Description override. */
+  readonly description: Schema.optionalKey<Schema.String>;
+  /** Open Graph override. */
+  readonly openGraph: Schema.optionalKey<Schema.Struct<{
+    readonly images: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+      readonly path: Schema.optionalKey<Schema.String>;
+      readonly url: Schema.optionalKey<Schema.String>;
+      readonly type: Schema.optionalKey<Schema.String>;
+      readonly width: Schema.optionalKey<Schema.Int>;
+      readonly height: Schema.optionalKey<Schema.Int>;
+      readonly alt: Schema.optionalKey<Schema.String>;
+    }>>>;
+    readonly themeColor: Schema.optionalKey<Schema.String>;
+  }>>;
+  /** SBOM pointer override. */
+  readonly sbom: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.String;
+    readonly format: Schema.optionalKey<Schema.String>;
+  }>>;
+  /** Registries override. */
+  readonly registries: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly type: Schema.String;
+    readonly name: Schema.String;
+    readonly url: Schema.String;
+  }>>>;
+}>;
+/**
+ * The decoded type of {@link (PlatformOverrides:variable)}.
+ *
+ * @public
+ */
+type PlatformOverrides = typeof PlatformOverrides.Type;
+/**
+ * Decode an unknown value into a {@link (PlatformOverrides:type)}.
+ *
+ * @remarks
+ * For adapters decoding raw platform options. Failures share
+ * {@link BundleManifestError} — the platform tier is manifest data by another
+ * route, and a caller handles both boundaries with one tag.
+ *
+ * @public
+ */
+declare function decodePlatformOverrides(input: unknown): Effect.Effect<PlatformOverrides, BundleManifestError>;
+//#endregion
+//#region src/BundleResolver.d.ts
+/**
+ * Where a resolved field's value came from, highest-ranked tier first.
+ *
+ * @remarks
+ * The first six values are the spec's tier ladder. `"tsconfig"` is this
+ * package's one addition: the spec passes tsconfig compiler options through
+ * as a resolved field but its ladder has no source that names the tsconfig
+ * layer, so the union carries one.
+ *
+ * @public
+ */
+type ProvenanceSource = "manifest.platform" | "manifest.leaf" | "manifest.project" | "packageJson" | "apiModel" | "tsconfig" | "inferred";
+/**
+ * A resolved value carrying its provenance.
+ *
+ * @remarks
+ * Provenance is load-bearing: a field is user-overridden iff its source
+ * outranks the derivation that would otherwise supply it, an `inferred`
+ * field tracks upstream changes while an authored field is pinned, and the
+ * change-detection fingerprints hash value AND source together so an
+ * override flip is a visible diff.
+ *
+ * @public
+ */
+interface Provenanced<A> {
+  /** The resolved value. */
+  readonly value: A;
+  /** The tier that supplied it. */
+  readonly source: ProvenanceSource;
+}
+/**
+ * One Open Graph image after resolution: authored fields passed through,
+ * `type` and `alt` filled by the documented inference rules when absent.
+ *
+ * @public
+ */
+interface ResolvedOpenGraphImage {
+  /** Bundle-relative asset path, when the image is bundle-supplied. */
+  readonly path?: string;
+  /** Absolute external URL, when the image is external. */
+  readonly url?: string;
+  /** MIME type — authored, or inferred from the file extension. */
+  readonly type?: Provenanced<string>;
+  /** Pixel width, as authored. */
+  readonly width?: number;
+  /** Pixel height, as authored. */
+  readonly height?: number;
+  /** Alt text — authored, or inferred (tagline → description → `"<name> API documentation"`); never empty. */
+  readonly alt: Provenanced<string>;
+}
+/**
+ * The Open Graph block after resolution.
+ *
+ * @public
+ */
+interface ResolvedOpenGraph {
+  /** Resolved images, first-declared-wins per OG array semantics. */
+  readonly images: ReadonlyArray<ResolvedOpenGraphImage>;
+  /** Embed accent color, when authored. */
+  readonly themeColor?: string;
+}
+/**
+ * A bundle's manifest data resolved across the six tiers, every field
+ * carrying value + provenance.
+ *
+ * @remarks
+ * Fields that no tier supplies are absent — with two floors: `name` always
+ * resolves (the api.json model always has one) and every resolved image's
+ * `alt` always resolves (the inference chain bottoms out on `name`).
+ *
+ * @public
+ */
+interface ResolvedBundle {
+  /** Display name: platform → leaf manifest → package.json → api.json model. */
+  readonly name: Provenanced<string>;
+  /** Package version, from package.json. */
+  readonly version?: Provenanced<string>;
+  /** Tagline: platform → leaf manifest → project tier. */
+  readonly tagline?: Provenanced<string>;
+  /** Description: platform → leaf manifest → package.json. */
+  readonly description?: Provenanced<string>;
+  /** The project identity block, when the manifest carries one. */
+  readonly project?: Provenanced<ProjectIdentity>;
+  /** Open Graph block: platform → leaf manifest, with per-image inference applied. */
+  readonly openGraph?: Provenanced<ResolvedOpenGraph>;
+  /** SBOM pointer: platform → leaf manifest. */
+  readonly sbom?: Provenanced<SbomRef>;
+  /** Registries: platform → leaf manifest. */
+  readonly registries?: Provenanced<ReadonlyArray<RegistryRef>>;
+  /** Runtime dependencies from package.json, key-sorted. Feeds the type registry's rendering scope. */
+  readonly dependencies?: Provenanced<Readonly<Record<string, string>>>;
+  /** Peer dependencies from package.json, key-sorted. Feeds the type registry's rendering scope. */
+  readonly peerDependencies?: Provenanced<Readonly<Record<string, string>>>;
+  /** Extends-resolved compiler options from tsconfig.json. Feeds the Twoslash environment. */
+  readonly compilerOptions?: Provenanced<CompilerOptions.Type>;
+}
+/**
+ * The parsed layers {@link resolveBundle} resolves — plain optional fields,
+ * so pure call sites (and tests) need no `Option` wrapping.
+ *
+ * @public
+ */
+interface ResolveBundleInput {
+  /** Layer 0: the model header (required — the one layer a bundle must have). */
+  readonly apiModel: ApiModelInfo;
+  /** Layer 1: the package.json manifest, when present. */
+  readonly packageJson?: PackageManifest;
+  /** Layer 2: the extends-resolved tsconfig, when present. */
+  readonly tsconfig?: ResolvedTsconfig;
+  /** Layer 3: the tsdoctor.json sidecar manifest, when present. */
+  readonly manifest?: BundleManifest;
+  /** The `manifest.platform` tier, from platform options. */
+  readonly platform?: PlatformOverrides;
+}
+/**
+ * Resolve a bundle's layers into a {@link ResolvedBundle}, pure.
+ *
+ * @remarks
+ * Highest tier wins per FIELD: `manifest.platform` → `manifest.leaf` →
+ * `manifest.project` → `packageJson` → `apiModel` → `inferred`. The project
+ * tier participates only in the fields it carries site/project identity for
+ * (tagline); the display `name` chain deliberately skips it — a project name
+ * outranking every leaf's own name would render each package in a monorepo
+ * under the same title, and the spec's `og:title` derivation reads
+ * `leaf name/tagline ← package name`. Inference (image `alt` and MIME
+ * `type`) runs on the RESOLVED tagline/description, so a tagline change at
+ * any tier propagates into inferred alt text.
+ *
+ * @public
+ */
+declare function resolveBundle(input: ResolveBundleInput): ResolvedBundle;
+/**
+ * Resolve a read {@link Bundle}, unwrapping its `Option` layers.
+ *
+ * @public
+ */
+declare function resolveBundleFrom(bundle: Bundle, platform?: PlatformOverrides): ResolvedBundle;
+//#endregion
+//#region src/BundleHash.d.ts
+/**
+ * Serialize a JSON-shaped value canonically: object keys sorted recursively,
+ * `undefined`-valued keys dropped, arrays in declared order, no whitespace.
+ *
+ * @remarks
+ * The normalization half of the change-detection discipline: two values that
+ * differ only in key order or optional-key presence-as-`undefined` serialize
+ * identically, so their hashes match. Non-JSON leaves (functions, symbols)
+ * serialize as `null`, matching `JSON.stringify` semantics inside arrays.
+ *
+ * @public
+ */
+declare function canonicalJson(value: unknown): string;
+/**
+ * Normalize text for hashing: CRLF/CR line endings become LF and trailing
+ * whitespace at the end of the content is trimmed.
+ *
+ * @remarks
+ * The same file checked out with different line-ending settings must hash
+ * identically — coarse layer-hash comparison otherwise reports every file
+ * changed on the first cross-platform build.
+ *
+ * @public
+ */
+declare function normalizeText(text: string): string;
+/**
+ * The lowercase hex SHA-256 of a string, UTF-8 encoded.
+ *
+ * @public
+ */
+declare function sha256Hex(text: string): string;
+/**
+ * Hash text content: {@link normalizeText} then {@link sha256Hex}.
+ *
+ * @public
+ */
+declare function hashText(text: string): string;
+/**
+ * Hash a JSON-shaped value: {@link canonicalJson} then {@link sha256Hex}.
+ *
+ * @public
+ */
+declare function hashJsonValue(value: unknown): string;
+/**
+ * Hash one bundle layer file's raw text — the COARSE half of change
+ * detection (all layer hashes match → skip resolution entirely).
+ *
+ * @remarks
+ * Total: text that parses as JSON hashes canonically (key order and
+ * formatting churn do not read as change); text that does not parse falls
+ * back to {@link hashText}, so a broken file still gets a stable hash
+ * rather than an error — hashing is bookkeeping, not validation.
+ *
+ * @public
+ */
+declare function hashLayerText(text: string): string;
+/**
+ * Fingerprint every present field of a {@link ResolvedBundle} — the FINE
+ * half of change detection, hashing each field's `{ value, source }` pair.
+ *
+ * @remarks
+ * The source participates deliberately: an override flip (a field moving
+ * from `inferred` to an authored tier without changing value) is a
+ * semantically meaningful change and must read as one. Absent fields carry
+ * no fingerprint — their appearance or disappearance is itself the diff.
+ * The consuming store maps each key to its invalidation scope (version →
+ * version-embedding surfaces, tsconfig → all code blocks, …).
+ *
+ * @public
+ */
+declare function fingerprintResolvedBundle(resolved: ResolvedBundle): Readonly<Record<string, string>>;
+//#endregion
+export { type ApiModelInfo, type Bundle, type BundleDescriptor, BundleDiscoveryError, BundleFetchError, BundleLayerError, BundleManifest, BundleManifestError, type BundleOverrides, type DiscoverBundleOptions, type DiscoverBundlesOptions, type FetchGitHubReleaseBundleOptions, type FetchNpmBundleOptions, KNOWN_REGISTRY_TYPES, type KnownRegistryType, OpenGraphConfig, OpenGraphImage, PlatformOverrides, ProjectIdentity, type ProvenanceSource, type Provenanced, RegistryRef, type ResolveBundleInput, type ResolvedBundle, type ResolvedOpenGraph, type ResolvedOpenGraphImage, SbomRef, TSDOCTOR_MANIFEST_FILENAME, canonicalJson, decodeBundleManifest, decodePlatformOverrides, discoverBundle, discoverBundles, fetchGitHubReleaseBundle, fetchNpmBundle, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, isKnownRegistryType, loadBundle, loadBundles, normalizeText, readApiModelInfo, readBundle, resolveBundle, resolveBundleFrom, sha256Hex };
+//# sourceMappingURL=index.d.ts.map