@tsdoctor/bundle 0.1.0 → 0.2.1

package/BundleDiscovery.js

@@ -1,4 +1,5 @@
 import { TSDOCTOR_MANIFEST_FILENAME, readApiModelInfo, readBundle } from "./Bundle.js";
+import { LenientManifest } from "@effected/package-json";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { GlobPatternOptions } from "@effected/glob";
 import { compileAndExpand } from "@effected/walker";
@@ -38,11 +39,6 @@ var BundleDiscoveryError = class extends Schema.TaggedError()("BundleDiscoveryEr
 		return `Bundle discovery failed (${this.reason}) at ${this.path}${detailPart}`;
 	}
 };
-/** The lenient package.json subset discovery needs: name and version only. */
-const DiscoveryPackageJson = Schema.Struct({
-	name: Schema.optionalKey(Schema.String),
-	version: Schema.optionalKey(Schema.String)
-});
 /** The unscoped tail of an npm package name (`@scope/pkg` → `pkg`). */
 function unscopedName(packageName) {
 	const slash = packageName.indexOf("/");
@@ -72,21 +68,35 @@ function listModelFiles(dir) {
 		cause
 	})));
 }
-/** Read the discovery-lenient name/version pair from a package.json, when present. */
+/**
+* Read the discovery-lenient name/version pair from a package.json, when
+* present.
+*
+* @remarks
+* Uses `@effected/package-json`'s `LenientManifest` — the shape-on-presence
+* degradable tier below `PackageManifest`. Malformed JSON text (or a
+* non-object document) fails typed as `invalidPackageJson`, matching the
+* previous two-field sniffer; a malformed individual field now degrades to
+* absence instead of failing, which is the ladder's enrich-never-gate rule
+* applied at field granularity (the model's own name covers a nameless
+* discovery).
+*/
 function readDiscoveryPackageJson(packageJsonPath) {
 	return Effect.gen(function* () {
 		const fs = yield* FileSystem.FileSystem;
 		if (!(yield* fs.exists(packageJsonPath).pipe(Effect.orElseSucceed(() => false)))) return Option.none();
 		const parsed = yield* Effect.gen(function* () {
 			const text = yield* fs.readFileString(packageJsonPath);
-			const json = yield* Effect.try(() => JSON.parse(text));
-			return yield* Schema.decodeUnknownEffect(DiscoveryPackageJson)(json);
+			return yield* LenientManifest.parse(text);
 		}).pipe(Effect.mapError((cause) => new BundleDiscoveryError({
 			path: packageJsonPath,
 			reason: "invalidPackageJson",
 			cause
 		})));
-		return Option.some(parsed);
+		return Option.some({
+			...parsed.name !== void 0 ? { name: parsed.name } : {},
+			...parsed.version !== void 0 ? { version: parsed.version } : {}
+		});
 	});
 }
 /**

package/BundleHash.js

@@ -1,83 +1,75 @@
-import { createHash } from "node:crypto";
+import { Effect } from "effect";
+import { JsoncFingerprint } from "@effected/jsonc";
 
 //#region src/BundleHash.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
-*/
-function canonicalJson(value) {
-	if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") return JSON.stringify(value);
-	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item === void 0 ? null : item)).join(",")}]`;
-	if (typeof value === "object") {
-		const record = value;
-		return `{${Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
-	}
-	return "null";
-}
-/**
 * 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.
+* changed on the first cross-platform build. Line-ending normalization is
+* `@effected/jsonc`'s `JsoncFingerprint.normalizeEol`; the trailing trim is
+* this package's own policy on top.
 *
 * @public
 */
 function normalizeText(text) {
-	return text.replace(/\r\n?/g, "\n").trimEnd();
+	return JsoncFingerprint.normalizeEol(text).trimEnd();
 }
 /**
-* The lowercase hex SHA-256 of a string, UTF-8 encoded.
+* Hash text content: {@link normalizeText} then SHA-256 (lowercase hex).
 *
-* @public
-*/
-function sha256Hex(text) {
-	return createHash("sha256").update(text, "utf8").digest("hex");
-}
-/**
-* Hash text content: {@link normalizeText} then {@link sha256Hex}.
+* @remarks
+* Digesting runs through core's `Crypto` service (`JsoncFingerprint`), so
+* consumers provide a backend — `@effect/platform-node`'s
+* `NodeCrypto.layer` — at the edge, the same posture as this package's
+* `FileSystem | Path` requirements.
 *
 * @public
 */
 function hashText(text) {
-	return sha256Hex(normalizeText(text));
+	return JsoncFingerprint.hashText(normalizeText(text));
 }
 /**
-* Hash a JSON-shaped value: {@link canonicalJson} then {@link sha256Hex}.
+* Hash a JSON-shaped value: RFC 8785 (JCS) canonicalization then SHA-256.
+*
+* @remarks
+* Delegates to `@effected/jsonc`'s `JsoncFingerprint.hash`. Canonicalization
+* is strict by design: an `undefined`-valued member, a `Date`, or any other
+* non-plain object fails typed (`JsoncCanonicalizeError`) rather than being
+* silently dropped or coerced — a fingerprint of a silently altered document
+* lies. Schema-encode class instances to plain JSON before hashing.
 *
 * @public
 */
 function hashJsonValue(value) {
-	return sha256Hex(canonicalJson(value));
+	return JsoncFingerprint.hash(value);
 }
 /**
 * 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.
+* Total in the error sense that matters here: 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. `JSON.parse` output is always plain
+* JSON-shaped, so a canonicalization failure on the parsed branch is a
+* defect, not a recoverable error.
 *
 * @public
 */
 function hashLayerText(text) {
+	let parsed;
 	try {
-		return hashJsonValue(JSON.parse(text));
+		parsed = JSON.parse(text);
 	} catch {
 		return hashText(text);
 	}
+	return JsoncFingerprint.hash(parsed).pipe(Effect.catchTag("JsoncCanonicalizeError", (error) => Effect.die(error)));
 }
 /**
 * Fingerprint every present field of a {@link ResolvedBundle} — the FINE
@@ -91,17 +83,17 @@ function hashLayerText(text) {
 * The consuming store maps each key to its invalidation scope (version →
 * version-embedding surfaces, tsconfig → all code blocks, …).
 *
+* Resolver output is plain JSON-shaped by construction (every value comes
+* from a `Schema.Struct` decode or a primitive derivation), so a
+* canonicalization failure here is a defect, not a recoverable error.
+*
 * @public
 */
 function fingerprintResolvedBundle(resolved) {
-	const fingerprints = {};
 	const fields = { ...resolved };
-	for (const key of Object.keys(fields).sort()) {
-		const field = fields[key];
-		if (field !== void 0) fingerprints[key] = hashJsonValue(field);
-	}
-	return fingerprints;
+	const present = Object.keys(fields).sort().filter((key) => fields[key] !== void 0);
+	return Effect.forEach(present, (key) => JsoncFingerprint.hash(fields[key]).pipe(Effect.catchTag("JsoncCanonicalizeError", (error) => Effect.die(error)), Effect.map((hash) => [key, hash])), { concurrency: 1 }).pipe(Effect.map((entries) => Object.fromEntries(entries)));
 }
 
 //#endregion
-export { canonicalJson, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, normalizeText, sha256Hex };
+export { fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, normalizeText };

package/README.md

@@ -29,7 +29,7 @@ This is an ESM-only package. `effect` and the `@effected/*` packages are peer de
 ## Quick start
 
 ```ts
-import { NodeFileSystem } from "@effect/platform-node";
+import { NodeCrypto, NodeFileSystem } from "@effect/platform-node";
 import { Effect, Layer, Path } from "effect";
 import { fingerprintResolvedBundle, loadBundle, resolveBundleFrom } from "@tsdoctor/bundle";
 
@@ -40,10 +40,13 @@ const program = Effect.gen(function* () {
     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
+  console.log(yield* fingerprintResolvedBundle(resolved)); // per-field SHA-256 fingerprints
 });
 
-program.pipe(Effect.provide(Layer.mergeAll(NodeFileSystem.layer, Path.layer)), Effect.runPromise);
+program.pipe(
+  Effect.provide(Layer.mergeAll(NodeFileSystem.layer, Path.layer, NodeCrypto.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.
@@ -56,9 +59,9 @@ Every resolved field carries `{ value, source }`, so "did the user override this
 - `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.
+- `hashLayerText`, `hashJsonValue`, `fingerprintResolvedBundle` — RFC 8785 (JCS) canonicalization plus SHA-256 (via `@effected/jsonc`'s `JsoncFingerprint`) for coarse (per-layer) and fine (per-field) change detection. Canonicalization is strict: an `undefined`-valued member or non-plain object fails typed rather than being silently dropped.
 
-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.
+All filesystem-touching functions keep `FileSystem` and `Path` in the Effect `R` channel, and the hashing functions keep `Crypto` there too; provide platform layers (for example `@effect/platform-node`'s `NodeFileSystem.layer`, `Path.layer` and `NodeCrypto.layer`) once at the application boundary.
 
 ## License
 

package/index.d.ts

@@ -1,10 +1,11 @@
 import { PackageManifest } from "@effected/package-json";
 import { CompilerOptions, ResolvedTsconfig } from "@effected/tsconfig-json";
-import { Effect, FileSystem, Option, Path, Schema } from "effect";
+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 src/BundleManifest.d.ts
 /**
  * The registry protocol families this reader knows how to do more than link
@@ -809,19 +810,6 @@ declare function resolveBundle(input: ResolveBundleInput): ResolvedBundle;
 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.
@@ -829,42 +817,54 @@ declare function canonicalJson(value: unknown): string;
  * @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.
+ * changed on the first cross-platform build. Line-ending normalization is
+ * `@effected/jsonc`'s `JsoncFingerprint.normalizeEol`; the trailing trim is
+ * this package's own policy on top.
  *
  * @public
  */
 declare function normalizeText(text: string): string;
 /**
- * The lowercase hex SHA-256 of a string, UTF-8 encoded.
+ * Hash text content: {@link normalizeText} then SHA-256 (lowercase hex).
  *
- * @public
- */
-declare function sha256Hex(text: string): string;
-/**
- * Hash text content: {@link normalizeText} then {@link sha256Hex}.
+ * @remarks
+ * Digesting runs through core's `Crypto` service (`JsoncFingerprint`), so
+ * consumers provide a backend — `@effect/platform-node`'s
+ * `NodeCrypto.layer` — at the edge, the same posture as this package's
+ * `FileSystem | Path` requirements.
  *
  * @public
  */
-declare function hashText(text: string): string;
+declare function hashText(text: string): Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
 /**
- * Hash a JSON-shaped value: {@link canonicalJson} then {@link sha256Hex}.
+ * Hash a JSON-shaped value: RFC 8785 (JCS) canonicalization then SHA-256.
+ *
+ * @remarks
+ * Delegates to `@effected/jsonc`'s `JsoncFingerprint.hash`. Canonicalization
+ * is strict by design: an `undefined`-valued member, a `Date`, or any other
+ * non-plain object fails typed (`JsoncCanonicalizeError`) rather than being
+ * silently dropped or coerced — a fingerprint of a silently altered document
+ * lies. Schema-encode class instances to plain JSON before hashing.
  *
  * @public
  */
-declare function hashJsonValue(value: unknown): string;
+declare function hashJsonValue(value: unknown): Effect.Effect<string, JsoncCanonicalizeError | PlatformError.PlatformError, Crypto.Crypto>;
 /**
  * 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.
+ * Total in the error sense that matters here: 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. `JSON.parse` output is always plain
+ * JSON-shaped, so a canonicalization failure on the parsed branch is a
+ * defect, not a recoverable error.
  *
  * @public
  */
-declare function hashLayerText(text: string): string;
+declare function hashLayerText(text: string): Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
 /**
  * Fingerprint every present field of a {@link ResolvedBundle} — the FINE
  * half of change detection, hashing each field's `{ value, source }` pair.
@@ -877,9 +877,13 @@ declare function hashLayerText(text: string): string;
  * The consuming store maps each key to its invalidation scope (version →
  * version-embedding surfaces, tsconfig → all code blocks, …).
  *
+ * Resolver output is plain JSON-shaped by construction (every value comes
+ * from a `Schema.Struct` decode or a primitive derivation), so a
+ * canonicalization failure here is a defect, not a recoverable error.
+ *
  * @public
  */
-declare function fingerprintResolvedBundle(resolved: ResolvedBundle): Readonly<Record<string, string>>;
+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, canonicalJson, decodeBundleManifest, decodePlatformOverrides, discoverBundle, discoverBundles, fetchGitHubReleaseBundle, fetchNpmBundle, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, isKnownRegistryType, loadBundle, loadBundles, normalizeText, readApiModelInfo, readBundle, resolveBundle, resolveBundleFrom, sha256Hex };
+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 };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -2,8 +2,8 @@ import { BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, OpenGraphCon
 import { BundleLayerError, TSDOCTOR_MANIFEST_FILENAME, readApiModelInfo, readBundle } from "./Bundle.js";
 import { BundleDiscoveryError, discoverBundle, discoverBundles, loadBundle, loadBundles } from "./BundleDiscovery.js";
 import { BundleFetchError, fetchGitHubReleaseBundle, fetchNpmBundle } from "./BundleFetch.js";
-import { canonicalJson, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, normalizeText, sha256Hex } from "./BundleHash.js";
+import { fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, normalizeText } from "./BundleHash.js";
 import { resolveBundle, resolveBundleFrom } from "./BundleResolver.js";
 import { PlatformOverrides, decodePlatformOverrides } from "./PlatformOverrides.js";
 
-export { BundleDiscoveryError, BundleFetchError, BundleLayerError, BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, OpenGraphConfig, OpenGraphImage, PlatformOverrides, ProjectIdentity, RegistryRef, SbomRef, TSDOCTOR_MANIFEST_FILENAME, canonicalJson, decodeBundleManifest, decodePlatformOverrides, discoverBundle, discoverBundles, fetchGitHubReleaseBundle, fetchNpmBundle, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, isKnownRegistryType, loadBundle, loadBundles, normalizeText, readApiModelInfo, readBundle, resolveBundle, resolveBundleFrom, sha256Hex };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/bundle",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"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": [
@@ -41,10 +41,11 @@
 	"peerDependencies": {
 		"@effected/github": "^0.8.0",
 		"@effected/glob": "^0.4.0",
-		"@effected/npm": "^0.12.0",
-		"@effected/package-json": "^0.11.0",
-		"@effected/store": "^0.4.0",
-		"@effected/tsconfig-json": "^0.6.0",
+		"@effected/jsonc": "^0.8.0",
+		"@effected/npm": "^0.12.1",
+		"@effected/package-json": "^0.13.0",
+		"@effected/store": "^0.5.0",
+		"@effected/tsconfig-json": "^0.6.1",
 		"@effected/walker": "^0.5.0",
 		"@effected/xdg": "^0.3.0",
 		"effect": "4.0.0-rc.109"