@tsdoctor/bundle 0.2.3 → 0.2.4

package/Bundle.js

@@ -1,15 +1,9 @@
-import { BundleManifestError, decodeBundleManifest } from "./BundleManifest.js";
+import { BundleManifestError, TSDOCTOR_MANIFEST_FILENAME, decodeBundleManifest } from "@tsdoctor/manifest";
 import { PackageJsonFile } from "@effected/package-json";
 import { TsconfigLoader } from "@effected/tsconfig-json";
 import { Effect, FileSystem, Option, Schema } from "effect";
 
 //#region src/Bundle.ts
-/**
-* The sidecar manifest's file name inside a bundle folder.
-*
-* @public
-*/
-const TSDOCTOR_MANIFEST_FILENAME = "tsdoctor.json";
 /** The minimal api.json shape the layer-0 reader validates. */
 const ApiModelHeader = Schema.Struct({ name: Schema.String });
 /**

package/PlatformOverrides.js

@@ -1,4 +1,4 @@
-import { BundleManifestError, OpenGraphConfig, RegistryRef, SbomRef } from "./BundleManifest.js";
+import { BundleManifestError, OpenGraphConfig, RegistryRef, SbomRef } from "@tsdoctor/manifest";
 import { Effect, Schema } from "effect";
 
 //#region src/PlatformOverrides.ts

package/index.d.ts

@@ -1,11 +1,12 @@
+import { Crypto, Effect, FileSystem, Option, Path, PlatformError, Schema } from "effect";
 import { PackageManifest } from "@effected/package-json";
 import { CompilerOptions, ResolvedTsconfig } from "@effected/tsconfig-json";
-import { Crypto, Effect, FileSystem, Option, Path, PlatformError, 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";
 import { JsoncCanonicalizeError } from "@effected/jsonc";
+//#region ../manifest/dist/dev/pkg/index.d.ts
 //#region src/BundleManifest.d.ts
 /**
  * The registry protocol families this reader knows how to do more than link
@@ -266,14 +267,83 @@ declare class BundleManifestError extends BundleManifestError_base {
  * @public
  */
 declare function decodeBundleManifest(input: unknown, path?: string): Effect.Effect<BundleManifest, BundleManifestError>;
-//#endregion
-//#region src/Bundle.d.ts
+/**
+ * The manifest spec version this package reads and writes.
+ *
+ * @public
+ */
+declare const MANIFEST_SPEC: 1;
 /**
  * The sidecar manifest's file name inside a bundle folder.
  *
  * @public
  */
 declare const TSDOCTOR_MANIFEST_FILENAME = "tsdoctor.json";
+/**
+ * Encode a {@link (BundleManifest:type)} into the JSON-ready value a writer
+ * serializes as `tsdoctor.json`.
+ *
+ * @remarks
+ * The writer's boundary. Going through the schema rather than
+ * `JSON.stringify` means an emitted file is by construction what
+ * {@link decodeBundleManifest} accepts.
+ *
+ * @public
+ */
+declare function encodeBundleManifest(manifest: BundleManifest): Effect.Effect<unknown, BundleManifestError>;
+//#endregion
+//#region src/ManifestSource.d.ts
+/**
+ * The shape an author checks in as a `tsdoctor.json` SOURCE file, at a
+ * package root (the leaf tier) or a workspace root (the project tier).
+ *
+ * @remarks
+ * `BundleManifest` minus `spec` and `project`: a source file never declares
+ * its own spec version, and it never declares its inherited tier — the
+ * bundler supplies both when it flattens the hierarchy at emit time. Decoded
+ * only by writers; readers never see this shape.
+ *
+ * @public
+ */
+declare const ManifestSource: Schema.Struct<{
+  readonly name: Schema.optionalKey<Schema.String>;
+  readonly tagline: Schema.optionalKey<Schema.String>;
+  readonly description: Schema.optionalKey<Schema.String>;
+  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>;
+  }>>;
+  readonly sbom: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.String;
+    readonly format: Schema.optionalKey<Schema.String>;
+  }>>;
+  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 (ManifestSource:variable)}.
+ *
+ * @public
+ */
+type ManifestSource = typeof ManifestSource.Type;
+/**
+ * Decode an unknown value into a {@link (ManifestSource:type)}.
+ *
+ * @public
+ */
+declare function decodeManifestSource(input: unknown, path?: string): Effect.Effect<ManifestSource, BundleManifestError>;
+//#endregion
+//#region src/Bundle.d.ts
 /**
  * The subset of a `<name>.api.json` model this package reads: the package
  * name from the model's own metadata.
@@ -885,5 +955,5 @@ declare function hashLayerText(text: string): Effect.Effect<string, PlatformErro
  */
 declare function fingerprintResolvedBundle(resolved: ResolvedBundle): Effect.Effect<Readonly<Record<string, string>>, PlatformError.PlatformError, Crypto.Crypto>;
 //#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, decodeBundleManifest, decodePlatformOverrides, discoverBundle, discoverBundles, fetchGitHubReleaseBundle, fetchNpmBundle, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, isKnownRegistryType, loadBundle, loadBundles, normalizeText, readApiModelInfo, readBundle, resolveBundle, resolveBundleFrom };
+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, MANIFEST_SPEC, ManifestSource, OpenGraphConfig, OpenGraphImage, PlatformOverrides, ProjectIdentity, type ProvenanceSource, type Provenanced, RegistryRef, type ResolveBundleInput, type ResolvedBundle, type ResolvedOpenGraph, type ResolvedOpenGraphImage, SbomRef, TSDOCTOR_MANIFEST_FILENAME, decodeBundleManifest, decodeManifestSource, decodePlatformOverrides, discoverBundle, discoverBundles, encodeBundleManifest, fetchGitHubReleaseBundle, fetchNpmBundle, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, isKnownRegistryType, loadBundle, loadBundles, normalizeText, readApiModelInfo, readBundle, resolveBundle, resolveBundleFrom };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,9 +1,9 @@
-import { BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, OpenGraphConfig, OpenGraphImage, ProjectIdentity, RegistryRef, SbomRef, decodeBundleManifest, isKnownRegistryType } from "./BundleManifest.js";
-import { BundleLayerError, TSDOCTOR_MANIFEST_FILENAME, readApiModelInfo, readBundle } from "./Bundle.js";
+import { BundleLayerError, readApiModelInfo, readBundle } from "./Bundle.js";
 import { BundleDiscoveryError, discoverBundle, discoverBundles, loadBundle, loadBundles } from "./BundleDiscovery.js";
 import { BundleFetchError, fetchGitHubReleaseBundle, fetchNpmBundle } from "./BundleFetch.js";
 import { fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, normalizeText } from "./BundleHash.js";
 import { resolveBundle, resolveBundleFrom } from "./BundleResolver.js";
 import { PlatformOverrides, decodePlatformOverrides } from "./PlatformOverrides.js";
+import { BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, MANIFEST_SPEC, ManifestSource, OpenGraphConfig, OpenGraphImage, ProjectIdentity, RegistryRef, SbomRef, TSDOCTOR_MANIFEST_FILENAME, decodeBundleManifest, decodeManifestSource, encodeBundleManifest, isKnownRegistryType } from "@tsdoctor/manifest";
 
-export { BundleDiscoveryError, BundleFetchError, BundleLayerError, BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, OpenGraphConfig, OpenGraphImage, PlatformOverrides, ProjectIdentity, RegistryRef, SbomRef, TSDOCTOR_MANIFEST_FILENAME, decodeBundleManifest, decodePlatformOverrides, discoverBundle, discoverBundles, fetchGitHubReleaseBundle, fetchNpmBundle, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, isKnownRegistryType, loadBundle, loadBundles, normalizeText, readApiModelInfo, readBundle, resolveBundle, resolveBundleFrom };
+export { BundleDiscoveryError, BundleFetchError, BundleLayerError, BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, MANIFEST_SPEC, ManifestSource, OpenGraphConfig, OpenGraphImage, PlatformOverrides, ProjectIdentity, RegistryRef, SbomRef, TSDOCTOR_MANIFEST_FILENAME, decodeBundleManifest, decodeManifestSource, decodePlatformOverrides, discoverBundle, discoverBundles, encodeBundleManifest, fetchGitHubReleaseBundle, fetchNpmBundle, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, isKnownRegistryType, loadBundle, loadBundles, normalizeText, readApiModelInfo, readBundle, resolveBundle, resolveBundleFrom };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/bundle",
-	"version": "0.2.3",
+	"version": "0.2.4",
 	"private": false,
 	"description": "The tsdoctor bundle spec: layered bundle discovery, the versioned tsdoctor.json sidecar manifest, provenance-carrying resolution and canonical input hashing for API documentation bundles.",
 	"keywords": [
@@ -48,6 +48,7 @@
 		"@effected/tsconfig-json": "^0.7.0",
 		"@effected/walker": "^0.5.0",
 		"@effected/xdg": "^0.3.0",
+		"@tsdoctor/manifest": "0.1.0",
 		"effect": "4.0.0-rc.109"
 	},
 	"engines": {

package/BundleManifest.js

@@ -1,183 +0,0 @@
-import { Effect, Schema } from "effect";
-
-//#region src/BundleManifest.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
-*/
-const KNOWN_REGISTRY_TYPES = ["npm", "jsr"];
-/**
-* 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
-*/
-function isKnownRegistryType(type) {
-	return KNOWN_REGISTRY_TYPES.includes(type);
-}
-/**
-* 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
-*/
-const RegistryRef = Schema.Struct({
-	/** The protocol family, e.g. `"npm"` or `"jsr"`. Unknown values are accepted. */
-	type: Schema.String,
-	/** The human instance label, e.g. `"npm"` or `"Savvy Web Registry"`. */
-	name: Schema.String,
-	/** The package's URL on that registry instance. */
-	url: Schema.String
-});
-/**
-* 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
-*/
-const OpenGraphImage = Schema.Struct({
-	/** Bundle-relative asset path. Mutually exclusive with `url`. */
-	path: Schema.optionalKey(Schema.String),
-	/** Absolute external URL, used verbatim. Mutually exclusive with `path`. */
-	url: Schema.optionalKey(Schema.String),
-	/** MIME type; inferred from the extension when omitted. */
-	type: Schema.optionalKey(Schema.String),
-	/** Pixel width; 1200×630 (1.91:1) is the cross-platform safe default. */
-	width: Schema.optionalKey(Schema.Int),
-	/** Pixel height. */
-	height: Schema.optionalKey(Schema.Int),
-	/** Alt text; inferred (tagline → description → fallback) when omitted. */
-	alt: Schema.optionalKey(Schema.String)
-}).check(Schema.makeFilter((image) => image.path === void 0 !== (image.url === void 0) ? void 0 : "exactly one of \"path\" or \"url\" must be present", { title: "openGraph image source" }));
-/**
-* 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
-*/
-const OpenGraphConfig = Schema.Struct({
-	/** Declared images, first-wins per OG array semantics. */
-	images: Schema.optionalKey(Schema.Array(OpenGraphImage)),
-	/** Embed accent color (e.g. Discord), a CSS color string. */
-	themeColor: Schema.optionalKey(Schema.String)
-});
-/**
-* A pointer to the bundle's SBOM, computed by the bundler at publish and
-* served as a downloadable static asset.
-*
-* @public
-*/
-const SbomRef = Schema.Struct({
-	/** Bundle-relative path to the SBOM file. */
-	path: Schema.String,
-	/** SBOM format label, e.g. `"spdx-json"`. Unknown values are accepted. */
-	format: Schema.optionalKey(Schema.String)
-});
-/**
-* 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
-*/
-const ProjectIdentity = Schema.Struct({
-	/** The project display name, e.g. `"Effected"` over leaf `@effected/store`. */
-	name: Schema.optionalKey(Schema.String),
-	/** The project tagline. */
-	tagline: Schema.optionalKey(Schema.String)
-});
-/**
-* 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
-*/
-const BundleManifest = Schema.Struct({
-	/** The integer spec version. This reader understands spec 1. */
-	spec: Schema.Literal(1),
-	/** Human display name (the npm name is dry; this one is SEO-friendly). */
-	name: Schema.optionalKey(Schema.String),
-	/** Short tagline. */
-	tagline: Schema.optionalKey(Schema.String),
-	/** Long description; overrides the package.json description when present. */
-	description: Schema.optionalKey(Schema.String),
-	/** The inherited project tier, flattened in at emit time. */
-	project: Schema.optionalKey(ProjectIdentity),
-	/** Open Graph assets. */
-	openGraph: Schema.optionalKey(OpenGraphConfig),
-	/** SBOM pointer. */
-	sbom: Schema.optionalKey(SbomRef),
-	/** Registries the package is published to. */
-	registries: Schema.optionalKey(Schema.Array(RegistryRef))
-});
-/**
-* 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
-*/
-var BundleManifestError = class extends Schema.TaggedError()("BundleManifestError", {
-	/** The manifest file path, when the failure is tied to a file on disk. */
-	path: Schema.optionalKey(Schema.String),
-	/** The underlying failure (JSON syntax or schema decode), preserved structurally. */
-	cause: Schema.Defect()
-}) {
-	get message() {
-		return `Invalid tsdoctor.json manifest${this.path !== void 0 ? ` at ${this.path}` : ""}`;
-	}
-};
-/**
-* 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
-*/
-function decodeBundleManifest(input, path) {
-	return Schema.decodeUnknownEffect(BundleManifest)(input).pipe(Effect.mapError((cause) => new BundleManifestError({
-		...path !== void 0 ? { path } : {},
-		cause
-	})));
-}
-
-//#endregion
-export { BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, OpenGraphConfig, OpenGraphImage, ProjectIdentity, RegistryRef, SbomRef, decodeBundleManifest, isKnownRegistryType };