@tsdoctor/bundle 0.1.0

package/BundleResolver.js

@@ -0,0 +1,167 @@
+import { HashMap, Option } from "effect";
+
+//#region src/BundleResolver.ts
+/** MIME types inferred from image file extensions. */
+const IMAGE_MIME_BY_EXTENSION = {
+	avif: "image/avif",
+	gif: "image/gif",
+	jpeg: "image/jpeg",
+	jpg: "image/jpeg",
+	png: "image/png",
+	svg: "image/svg+xml",
+	webp: "image/webp"
+};
+/** The lowercased file extension of an image path or URL, query/fragment stripped. */
+function imageExtension(pathOrUrl) {
+	const withoutQuery = pathOrUrl.split(/[?#]/, 1)[0];
+	const lastSegment = withoutQuery.slice(withoutQuery.lastIndexOf("/") + 1);
+	const dot = lastSegment.lastIndexOf(".");
+	if (dot <= 0) return;
+	return lastSegment.slice(dot + 1).toLowerCase();
+}
+/** A key-sorted plain record from a HashMap, for deterministic downstream hashing. */
+function sortedRecord(map) {
+	const entries = [...HashMap.entries(map)].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	return Object.fromEntries(entries);
+}
+/** The highest-ranked defined candidate, with its source. */
+function pick(candidates) {
+	for (const [value, source] of candidates) if (value !== void 0) return {
+		value,
+		source
+	};
+}
+/**
+* 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
+*/
+function resolveBundle(input) {
+	const platform = input.platform;
+	const leaf = input.manifest;
+	const project = leaf?.project;
+	const packageJson = input.packageJson;
+	const name = pick([
+		[platform?.name, "manifest.platform"],
+		[leaf?.name, "manifest.leaf"],
+		[packageJson?.name, "packageJson"],
+		[input.apiModel.name, "apiModel"]
+	]);
+	const tagline = pick([
+		[platform?.tagline, "manifest.platform"],
+		[leaf?.tagline, "manifest.leaf"],
+		[project?.tagline, "manifest.project"]
+	]);
+	const description = pick([
+		[platform?.description, "manifest.platform"],
+		[leaf?.description, "manifest.leaf"],
+		[packageJson?.description, "packageJson"]
+	]);
+	const version = packageJson?.version !== void 0 ? {
+		value: String(packageJson.version),
+		source: "packageJson"
+	} : void 0;
+	const projectIdentity = project !== void 0 ? {
+		value: project,
+		source: "manifest.project"
+	} : void 0;
+	const sbom = pick([[platform?.sbom, "manifest.platform"], [leaf?.sbom, "manifest.leaf"]]);
+	const registries = pick([[platform?.registries, "manifest.platform"], [leaf?.registries, "manifest.leaf"]]);
+	const openGraphRaw = pick([[platform?.openGraph, "manifest.platform"], [leaf?.openGraph, "manifest.leaf"]]);
+	const inferredAlt = () => {
+		if (tagline !== void 0) return {
+			value: tagline.value,
+			source: "inferred"
+		};
+		if (description !== void 0) return {
+			value: description.value,
+			source: "inferred"
+		};
+		return {
+			value: `${name.value} API documentation`,
+			source: "inferred"
+		};
+	};
+	const openGraph = openGraphRaw !== void 0 ? {
+		value: {
+			images: (openGraphRaw.value.images ?? []).map((image) => {
+				const extension = imageExtension(image.path ?? image.url ?? "");
+				const inferredType = extension !== void 0 ? IMAGE_MIME_BY_EXTENSION[extension] : void 0;
+				const type = image.type !== void 0 ? {
+					value: image.type,
+					source: openGraphRaw.source
+				} : inferredType !== void 0 ? {
+					value: inferredType,
+					source: "inferred"
+				} : void 0;
+				const alt = image.alt !== void 0 ? {
+					value: image.alt,
+					source: openGraphRaw.source
+				} : inferredAlt();
+				return {
+					...image.path !== void 0 ? { path: image.path } : {},
+					...image.url !== void 0 ? { url: image.url } : {},
+					...type !== void 0 ? { type } : {},
+					...image.width !== void 0 ? { width: image.width } : {},
+					...image.height !== void 0 ? { height: image.height } : {},
+					alt
+				};
+			}),
+			...openGraphRaw.value.themeColor !== void 0 ? { themeColor: openGraphRaw.value.themeColor } : {}
+		},
+		source: openGraphRaw.source
+	} : void 0;
+	const dependencies = packageJson !== void 0 ? {
+		value: sortedRecord(packageJson.dependencies),
+		source: "packageJson"
+	} : void 0;
+	const peerDependencies = packageJson !== void 0 ? {
+		value: sortedRecord(packageJson.peerDependencies),
+		source: "packageJson"
+	} : void 0;
+	const compilerOptions = input.tsconfig !== void 0 ? {
+		value: input.tsconfig.compilerOptions,
+		source: "tsconfig"
+	} : void 0;
+	return {
+		name,
+		...version !== void 0 ? { version } : {},
+		...tagline !== void 0 ? { tagline } : {},
+		...description !== void 0 ? { description } : {},
+		...projectIdentity !== void 0 ? { project: projectIdentity } : {},
+		...openGraph !== void 0 ? { openGraph } : {},
+		...sbom !== void 0 ? { sbom } : {},
+		...registries !== void 0 ? { registries } : {},
+		...dependencies !== void 0 ? { dependencies } : {},
+		...peerDependencies !== void 0 ? { peerDependencies } : {},
+		...compilerOptions !== void 0 ? { compilerOptions } : {}
+	};
+}
+/**
+* Resolve a read {@link Bundle}, unwrapping its `Option` layers.
+*
+* @public
+*/
+function resolveBundleFrom(bundle, platform) {
+	return resolveBundle({
+		apiModel: bundle.apiModel,
+		...Option.isSome(bundle.packageJson) ? { packageJson: bundle.packageJson.value } : {},
+		...Option.isSome(bundle.tsconfig) ? { tsconfig: bundle.tsconfig.value } : {},
+		...Option.isSome(bundle.manifest) ? { manifest: bundle.manifest.value } : {},
+		...platform !== void 0 ? { platform } : {}
+	});
+}
+
+//#endregion
+export { resolveBundle, resolveBundleFrom };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PlatformOverrides.js

@@ -0,0 +1,48 @@
+import { BundleManifestError, OpenGraphConfig, RegistryRef, SbomRef } from "./BundleManifest.js";
+import { Effect, Schema } from "effect";
+
+//#region src/PlatformOverrides.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
+*/
+const PlatformOverrides = Schema.Struct({
+	/** Human display name override. */
+	name: Schema.optionalKey(Schema.String),
+	/** Tagline override. */
+	tagline: Schema.optionalKey(Schema.String),
+	/** Description override. */
+	description: Schema.optionalKey(Schema.String),
+	/** Open Graph override. */
+	openGraph: Schema.optionalKey(OpenGraphConfig),
+	/** SBOM pointer override. */
+	sbom: Schema.optionalKey(SbomRef),
+	/** Registries override. */
+	registries: Schema.optionalKey(Schema.Array(RegistryRef))
+});
+/**
+* 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
+*/
+function decodePlatformOverrides(input) {
+	return Schema.decodeUnknownEffect(PlatformOverrides)(input).pipe(Effect.mapError((cause) => new BundleManifestError({ cause })));
+}
+
+//#endregion
+export { PlatformOverrides, decodePlatformOverrides };

package/README.md

@@ -0,0 +1,65 @@
+# @tsdoctor/bundle
+
+[![npm](https://img.shields.io/npm/v/@tsdoctor%2Fbundle?label=npm&color=cb3837)](https://www.npmjs.com/package/@tsdoctor/bundle)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+The tsdoctor bundle spec. A bundle is the folder of files that describes one documented package — an API Extractor `.api.json` model plus optional overlays — and this package owns everything about reading one: discovery on disk, the versioned `tsdoctor.json` sidecar manifest, resolution of manifest data across override tiers with per-field provenance, and canonical hashing of the inputs for change detection.
+
+## The layered bundle
+
+A bundle is one required file plus optional overlays. Each layer enriches the result; none of the optional layers gates it — a folder holding only an `.api.json` still resolves.
+
+| Layer | File | Required | Supplies |
+| --- | --- | --- | --- |
+| 0 | `<name>.api.json` | yes | package name, the API itself |
+| 1 | `package.json` | no | version, description, dependencies and peers |
+| 2 | `tsconfig.json` | no | compiler options for the rendering environment |
+| 3 | `tsdoctor.json` | no | display identity, Open Graph, SBOM pointer, registries |
+
+## Install
+
+```bash
+pnpm add @tsdoctor/bundle effect @effected/glob @effected/package-json @effected/tsconfig-json @effected/walker
+```
+
+This is an ESM-only package. `effect` and the `@effected/*` packages are peer dependencies.
+
+## Quick start
+
+```ts
+import { NodeFileSystem } from "@effect/platform-node";
+import { Effect, Layer, Path } from "effect";
+import { fingerprintResolvedBundle, loadBundle, resolveBundleFrom } from "@tsdoctor/bundle";
+
+const program = Effect.gen(function* () {
+  const bundle = yield* loadBundle("./lib/models/kitchensink");
+  const resolved = resolveBundleFrom(bundle, {
+    // The manifest.platform tier: declarative overrides that outrank every file.
+    tagline: "Every API Extractor feature in one module",
+  });
+  console.log(resolved.name); // { value: "...", source: "manifest.leaf" | "packageJson" | ... }
+  console.log(fingerprintResolvedBundle(resolved)); // per-field SHA-256 fingerprints
+});
+
+program.pipe(Effect.provide(Layer.mergeAll(NodeFileSystem.layer, Path.layer)), Effect.runPromise);
+```
+
+Every resolved field carries `{ value, source }`, so "did the user override this or did we derive it?" is a rank comparison, not a heuristic. The fingerprints feed a snapshot store: unchanged inputs mean generation can be skipped at the granularity of exactly the surfaces a changed field invalidates.
+
+## API surface
+
+- `discoverBundle(dir)` / `discoverBundles(parentDir)` — resolve folder(s) into `BundleDescriptor`s (model file selection, name/version parsing, overlay detection).
+- `fetchNpmBundle` / `fetchGitHubReleaseBundle` — fetch a published bundle from any npm-protocol registry (via `@effected/npm`'s verified tarball pipeline) or from a GitHub release's `*.npm.meta.tgz` asset (via `@effected/github`), through a durable XDG cache (`@effected/store` + `@effected/xdg`). npm versions are immutable, so cache hits skip the network; `refresh: true` refetches.
+- `readBundle(descriptor)` / `loadBundle(dir)` / `loadBundles(parentDir)` — read the four layers into typed structures.
+- `BundleManifest`, `decodeBundleManifest` — the `tsdoctor.json` spec-1 schema; unknown fields and unknown registry types degrade gracefully instead of rejecting.
+- `PlatformOverrides`, `decodePlatformOverrides` — the top-ranked data-override tier a consumer passes through platform options.
+- `resolveBundle` / `resolveBundleFrom` — the pure six-tier resolver producing a `ResolvedBundle` of `Provenanced` fields, with the documented inference rules (Open Graph alt-text chain, MIME from extension).
+- `hashLayerText`, `hashJsonValue`, `canonicalJson`, `fingerprintResolvedBundle` — canonical-normalization hashing for coarse (per-layer) and fine (per-field) change detection.
+
+All filesystem-touching functions keep `FileSystem` and `Path` in the Effect `R` channel; provide a platform layer (for example `@effect/platform-node`) once at the application boundary.
+
+## License
+
+[MIT](LICENSE)