@tsdoctor/manifest 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,63 @@
+# @tsdoctor/manifest
+
+[![npm](https://img.shields.io/npm/v/@tsdoctor%2Fmanifest?label=npm&color=cb3837)](https://www.npmjs.com/package/@tsdoctor/manifest)
+[![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.json` sidecar manifest: the spec-1 schema for a documented package's display identity, Open Graph images, SBOM pointer and registries, plus the encode/decode boundaries a writer and a reader each need. It depends on `effect` alone, so a bundler can emit `tsdoctor.json` through this package without pulling in `@tsdoctor/bundle`'s fetch, cache and discovery stack.
+
+## What you get
+
+- **`BundleManifest`** — the manifest schema. `spec` is `1` and the only required field; every other field (`name`, `tagline`, `description`, a nested `project` identity, `openGraph`, `sbom`, `registries`) is additive. Unknown enum-ish values (`registries[].type`, `sbom.format`) degrade to a plain value rather than being rejected, so a reader that does not know a registry type still renders it as a link.
+- **`decodeBundleManifest(input, path?)`** — the reader's boundary: `Schema.decodeUnknownEffect` over `BundleManifest`, failing typed `BundleManifestError` on a malformed file.
+- **`encodeBundleManifest(manifest)`** — the writer's boundary: `Schema.encodeEffect` over `BundleManifest`, so an emitted file is by construction what `decodeBundleManifest` accepts.
+- **`ManifestSource`** and **`decodeManifestSource(input, path?)`** — the shape an author checks in as a `tsdoctor.json` source file: `BundleManifest` minus `spec` and `project`, since a source file never declares its own spec version or the tier a monorepo project inherits.
+- **`OpenGraphImage`, `OpenGraphConfig`, `SbomRef`, `RegistryRef`, `ProjectIdentity`, `KNOWN_REGISTRY_TYPES`, `isKnownRegistryType`** — the field-level schemas and helpers `BundleManifest` composes.
+- **`MANIFEST_SPEC`, `TSDOCTOR_MANIFEST_FILENAME`** — the spec version this package reads and writes, and the sidecar's file name inside a bundle folder.
+
+## Install
+
+```bash
+npm install @tsdoctor/manifest
+# or
+pnpm add @tsdoctor/manifest
+```
+
+This is an ESM-only package. `effect` is a peer dependency.
+
+## Quick start
+
+```ts
+import { Effect } from "effect";
+import { decodeBundleManifest, encodeBundleManifest } from "@tsdoctor/manifest";
+
+const program = Effect.gen(function* () {
+  const manifest = yield* decodeBundleManifest({
+    spec: 1,
+    name: "Kitchen Sink",
+    tagline: "Every API Extractor feature, one fixture",
+    openGraph: { images: [{ path: "og/kitchensink.png" }] },
+  });
+
+  // Round-trips: what encodeBundleManifest writes, decodeBundleManifest reads back.
+  const encoded = yield* encodeBundleManifest(manifest);
+  return encoded;
+});
+```
+
+## Three boundaries, one file
+
+`tsdoctor.json` has three readers, and each gets its own function rather than sharing one loosely-typed parser:
+
+- **`decodeBundleManifest`** is what `@tsdoctor/bundle`'s layer-3 reader calls on a bundle's own `tsdoctor.json` — the fully resolved shape, `spec` and `project` included.
+- **`encodeBundleManifest`** is what a bundler's meta pass calls to emit the file — going through the schema rather than `JSON.stringify` is what guarantees the two boundaries agree on shape.
+- **`decodeManifestSource`** is what a bundler calls on an *authored* `tsdoctor.json` beside a package's `package.json`, or at a monorepo root — a source file never declares its own `spec` or `project`, because both are supplied by whichever tier assembles the final manifest.
+
+## Provenance
+
+Moved out of `@tsdoctor/bundle` so `@savvy-web/bundler`'s meta pass — the one implementation of this file's authoring-time resolution — can depend on the writer boundary without dragging in the bundle package's `@effected/github`, `npm`, `store`, `xdg`, `glob` and `walker` peers. `@tsdoctor/bundle` re-exports every name here; consumers inside the tsdoctor monorepo import from `@tsdoctor/bundle`, and only writers import this package directly.
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -12,7 +12,7 @@ import { Effect, Schema } from "effect";
  *
  * @public
  */
-declare const KNOWN_REGISTRY_TYPES: readonly ["npm", "jsr"];
+export declare const KNOWN_REGISTRY_TYPES: readonly ["npm", "jsr"];
 /**
  * A registry protocol family this reader recognizes.
  *
@@ -26,7 +26,7 @@ type KnownRegistryType = (typeof KNOWN_REGISTRY_TYPES)[number];
  *
  * @public
  */
-declare function isKnownRegistryType(type: string): type is KnownRegistryType;
+export declare function isKnownRegistryType(type: string): type is KnownRegistryType;
 /**
  * One registry the documented package is published to.
  *
@@ -38,7 +38,7 @@ declare function isKnownRegistryType(type: string): type is KnownRegistryType;
  *
  * @public
  */
-declare const RegistryRef: Schema.Struct<{
+export 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"`. */
@@ -51,7 +51,7 @@ declare const RegistryRef: Schema.Struct<{
  *
  * @public
  */
-type RegistryRef = typeof RegistryRef.Type;
+export type RegistryRef = typeof RegistryRef.Type;
 /**
  * One Open Graph image declared by the manifest.
  *
@@ -65,7 +65,7 @@ type RegistryRef = typeof RegistryRef.Type;
  *
  * @public
  */
-declare const OpenGraphImage: Schema.Struct<{
+export 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`. */
@@ -84,7 +84,7 @@ declare const OpenGraphImage: Schema.Struct<{
  *
  * @public
  */
-type OpenGraphImage = typeof OpenGraphImage.Type;
+export 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.
@@ -95,7 +95,7 @@ type OpenGraphImage = typeof OpenGraphImage.Type;
  *
  * @public
  */
-declare const OpenGraphConfig: Schema.Struct<{
+export 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`. */
@@ -119,14 +119,14 @@ declare const OpenGraphConfig: Schema.Struct<{
  *
  * @public
  */
-type OpenGraphConfig = typeof OpenGraphConfig.Type;
+export 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<{
+export 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. */
@@ -137,7 +137,7 @@ declare const SbomRef: Schema.Struct<{
  *
  * @public
  */
-type SbomRef = typeof SbomRef.Type;
+export 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 —
@@ -146,7 +146,7 @@ type SbomRef = typeof SbomRef.Type;
  *
  * @public
  */
-declare const ProjectIdentity: Schema.Struct<{
+export 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. */
@@ -157,7 +157,7 @@ declare const ProjectIdentity: Schema.Struct<{
  *
  * @public
  */
-type ProjectIdentity = typeof ProjectIdentity.Type;
+export type ProjectIdentity = typeof ProjectIdentity.Type;
 /**
  * The versioned `tsdoctor.json` sidecar manifest — bundle layer 3.
  *
@@ -170,7 +170,7 @@ type ProjectIdentity = typeof ProjectIdentity.Type;
  *
  * @public
  */
-declare const BundleManifest: Schema.Struct<{
+export 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). */
@@ -228,7 +228,7 @@ declare const BundleManifest: Schema.Struct<{
  *
  * @public
  */
-type BundleManifest = typeof BundleManifest.Type;
+export 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>;
@@ -245,7 +245,7 @@ declare const BundleManifestError_base: Schema.Class<BundleManifestError, Schema
  *
  * @public
  */
-declare class BundleManifestError extends BundleManifestError_base {
+export declare class BundleManifestError extends BundleManifestError_base {
   get message(): string;
 }
 /**
@@ -258,19 +258,19 @@ declare class BundleManifestError extends BundleManifestError_base {
  *
  * @public
  */
-declare function decodeBundleManifest(input: unknown, path?: string): Effect.Effect<BundleManifest, BundleManifestError>;
+export declare function decodeBundleManifest(input: unknown, path?: string): Effect.Effect<BundleManifest, BundleManifestError>;
 /**
  * The manifest spec version this package reads and writes.
  *
  * @public
  */
-declare const MANIFEST_SPEC: 1;
+export declare const MANIFEST_SPEC: 1;
 /**
  * The sidecar manifest's file name inside a bundle folder.
  *
  * @public
  */
-declare const TSDOCTOR_MANIFEST_FILENAME = "tsdoctor.json";
+export declare const TSDOCTOR_MANIFEST_FILENAME = "tsdoctor.json";
 /**
  * Encode a {@link (BundleManifest:type)} into the JSON-ready value a writer
  * serializes as `tsdoctor.json`.
@@ -282,7 +282,7 @@ declare const TSDOCTOR_MANIFEST_FILENAME = "tsdoctor.json";
  *
  * @public
  */
-declare function encodeBundleManifest(manifest: BundleManifest): Effect.Effect<unknown, BundleManifestError>;
+export declare function encodeBundleManifest(manifest: BundleManifest): Effect.Effect<unknown, BundleManifestError>;
 //#endregion
 //#region src/ManifestSource.d.ts
 /**
@@ -297,7 +297,7 @@ declare function encodeBundleManifest(manifest: BundleManifest): Effect.Effect<u
  *
  * @public
  */
-declare const ManifestSource: Schema.Struct<{
+export declare const ManifestSource: Schema.Struct<{
   readonly name: Schema.optionalKey<Schema.String>;
   readonly tagline: Schema.optionalKey<Schema.String>;
   readonly description: Schema.optionalKey<Schema.String>;
@@ -327,13 +327,13 @@ declare const ManifestSource: Schema.Struct<{
  *
  * @public
  */
-type ManifestSource = typeof ManifestSource.Type;
+export 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>;
+export declare function decodeManifestSource(input: unknown, path?: string): Effect.Effect<ManifestSource, BundleManifestError>;
 //#endregion
-export { BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, type KnownRegistryType, MANIFEST_SPEC, ManifestSource, OpenGraphConfig, OpenGraphImage, ProjectIdentity, RegistryRef, SbomRef, TSDOCTOR_MANIFEST_FILENAME, decodeBundleManifest, decodeManifestSource, encodeBundleManifest, isKnownRegistryType };
+export type { KnownRegistryType };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/manifest",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"private": false,
 	"description": "The tsdoctor.json bundle manifest: the spec-1 schema, encode/decode boundaries and the authoring-file shape shared by bundlers that write it and readers that consume it.",
 	"keywords": [
@@ -35,7 +35,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.109"
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"