@tsdoctor/bundle 0.1.0

package/Bundle.js

@@ -0,0 +1,127 @@
+import { BundleManifestError, decodeBundleManifest } from "./BundleManifest.js";
+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 });
+/**
+* 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
+*/
+var BundleLayerError = class extends Schema.TaggedError()("BundleLayerError", {
+	/** Which bundle layer failed. */
+	layer: Schema.Literals([
+		"apiModel",
+		"packageJson",
+		"tsconfig"
+	]),
+	/** The file that failed. */
+	path: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to read bundle layer "${this.layer}" at ${this.path}`;
+	}
+};
+/**
+* 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
+*/
+function readApiModelInfo(modelPath) {
+	return Effect.gen(function* () {
+		const text = yield* (yield* FileSystem.FileSystem).readFileString(modelPath);
+		const parsed = yield* Effect.try(() => JSON.parse(text));
+		return yield* Schema.decodeUnknownEffect(ApiModelHeader)(parsed);
+	}).pipe(Effect.mapError((cause) => new BundleLayerError({
+		layer: "apiModel",
+		path: modelPath,
+		cause
+	})));
+}
+/** Read layer 1 when the descriptor recorded a package.json. */
+function readPackageJsonLayer(packageJsonPath) {
+	if (packageJsonPath === void 0) return Effect.succeed(Option.none());
+	return Effect.gen(function* () {
+		const manifest = yield* (yield* PackageJsonFile.make).readManifest(packageJsonPath);
+		return Option.some(manifest);
+	}).pipe(Effect.mapError((cause) => new BundleLayerError({
+		layer: "packageJson",
+		path: packageJsonPath,
+		cause
+	})));
+}
+/** Read layer 2 when the descriptor recorded a tsconfig.json. */
+function readTsconfigLayer(tsconfigPath) {
+	if (tsconfigPath === void 0) return Effect.succeed(Option.none());
+	return TsconfigLoader.resolve(tsconfigPath).pipe(Effect.map(Option.some), Effect.mapError((cause) => new BundleLayerError({
+		layer: "tsconfig",
+		path: tsconfigPath,
+		cause
+	})));
+}
+/** Read layer 3 when the descriptor recorded a tsdoctor.json. */
+function readManifestLayer(manifestPath) {
+	if (manifestPath === void 0) return Effect.succeed(Option.none());
+	return Effect.gen(function* () {
+		const text = yield* (yield* FileSystem.FileSystem).readFileString(manifestPath).pipe(Effect.mapError((cause) => new BundleManifestError({
+			path: manifestPath,
+			cause
+		})));
+		const parsed = yield* Effect.try(() => JSON.parse(text)).pipe(Effect.mapError((cause) => new BundleManifestError({
+			path: manifestPath,
+			cause
+		})));
+		const manifest = yield* decodeBundleManifest(parsed, manifestPath);
+		return Option.some(manifest);
+	});
+}
+/**
+* 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
+*/
+function readBundle(descriptor) {
+	return Effect.gen(function* () {
+		return {
+			descriptor,
+			apiModel: yield* readApiModelInfo(descriptor.modelPath),
+			packageJson: yield* readPackageJsonLayer(descriptor.packageJsonPath),
+			tsconfig: yield* readTsconfigLayer(descriptor.tsconfigPath),
+			manifest: yield* readManifestLayer(descriptor.manifestPath)
+		};
+	});
+}
+
+//#endregion
+export { BundleLayerError, TSDOCTOR_MANIFEST_FILENAME, readApiModelInfo, readBundle };

package/BundleDiscovery.js

@@ -0,0 +1,233 @@
+import { TSDOCTOR_MANIFEST_FILENAME, readApiModelInfo, readBundle } from "./Bundle.js";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { GlobPatternOptions } from "@effected/glob";
+import { compileAndExpand } from "@effected/walker";
+
+//#region src/BundleDiscovery.ts
+/**
+* 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
+*/
+var BundleDiscoveryError = class extends Schema.TaggedError()("BundleDiscoveryError", {
+	/** The directory (or file) the failure is about. */
+	path: Schema.String,
+	/** What went wrong, structurally. */
+	reason: Schema.Literals([
+		"notFound",
+		"notADirectory",
+		"noApiModel",
+		"ambiguousApiModel",
+		"invalidPackageJson",
+		"unreadableDirectory",
+		"notABundleFolder",
+		"emptyParent"
+	]),
+	/** Human context for the failure (candidate lists, offending names). */
+	detail: Schema.optionalKey(Schema.String),
+	/** The underlying failure, when one exists, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		const detailPart = this.detail !== void 0 ? `: ${this.detail}` : "";
+		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("/");
+	return packageName.startsWith("@") && slash !== -1 ? packageName.slice(slash + 1) : packageName;
+}
+/** Assert `dir` exists and is a directory, or fail with a discovery error. */
+function assertDirectory(dir) {
+	return Effect.gen(function* () {
+		if ((yield* (yield* FileSystem.FileSystem).stat(dir).pipe(Effect.mapError((cause) => new BundleDiscoveryError({
+			path: dir,
+			reason: "notFound",
+			cause
+		})))).type !== "Directory") return yield* Effect.fail(new BundleDiscoveryError({
+			path: dir,
+			reason: "notADirectory"
+		}));
+	});
+}
+/** List the `*.api.json` files directly inside `dir`, sorted. */
+function listModelFiles(dir) {
+	return compileAndExpand("*.api.json", {
+		cwd: dir,
+		glob: GlobPatternOptions.make({})
+	}).pipe(Effect.mapError((cause) => new BundleDiscoveryError({
+		path: dir,
+		reason: "unreadableDirectory",
+		cause
+	})));
+}
+/** Read the discovery-lenient name/version pair from a package.json, when present. */
+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);
+		}).pipe(Effect.mapError((cause) => new BundleDiscoveryError({
+			path: packageJsonPath,
+			reason: "invalidPackageJson",
+			cause
+		})));
+		return Option.some(parsed);
+	});
+}
+/**
+* Pick the bundle's model file from the `*.api.json` candidates in its
+* folder.
+*
+* @remarks
+* One candidate wins outright. Zero is a discovery failure — layer 0 is the
+* one required layer. Among several, the file named `<unscoped>.api.json`
+* for the bundle's package name wins; with no such match the set is
+* ambiguous and discovery fails with guidance to pass an explicit
+* `overrides.modelPath`.
+*/
+function pickModelFile(dir, candidates, packageName) {
+	return Effect.gen(function* () {
+		const path = yield* Path.Path;
+		if (candidates.length === 1) return path.join(dir, candidates[0]);
+		if (candidates.length === 0) return yield* Effect.fail(new BundleDiscoveryError({
+			path: dir,
+			reason: "noApiModel",
+			detail: "no *.api.json model found; pass an explicit overrides.modelPath"
+		}));
+		const preferred = packageName !== void 0 ? `${unscopedName(packageName)}.api.json` : void 0;
+		const match = preferred !== void 0 ? candidates.find((candidate) => candidate === preferred) : void 0;
+		if (match !== void 0) return path.join(dir, match);
+		return yield* Effect.fail(new BundleDiscoveryError({
+			path: dir,
+			reason: "ambiguousApiModel",
+			detail: `multiple *.api.json files (${candidates.join(", ")}) and none match "${preferred ?? "<name>.api.json"}"; pass an explicit overrides.modelPath`
+		}));
+	});
+}
+/**
+* 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
+*/
+function discoverBundle(dir, options) {
+	return Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const abs = options?.cwd !== void 0 ? path.resolve(options.cwd, dir) : path.resolve(dir);
+		yield* assertDirectory(abs);
+		const packageJsonPath = path.join(abs, "package.json");
+		const packageJson = yield* readDiscoveryPackageJson(packageJsonPath);
+		const packageJsonName = Option.isSome(packageJson) ? packageJson.value.name : void 0;
+		const overriddenModel = options?.overrides?.modelPath;
+		const modelPath = overriddenModel !== void 0 ? path.resolve(abs, overriddenModel) : yield* Effect.flatMap(listModelFiles(abs), (candidates) => pickModelFile(abs, candidates, options?.overrides?.name ?? packageJsonName));
+		const name = options?.overrides?.name ?? packageJsonName ?? (yield* readApiModelInfo(modelPath)).name;
+		const version = options?.overrides?.version ?? (Option.isSome(packageJson) ? packageJson.value.version : void 0);
+		const tsconfigPath = path.join(abs, "tsconfig.json");
+		const manifestPath = path.join(abs, TSDOCTOR_MANIFEST_FILENAME);
+		const hasTsconfig = yield* fs.exists(tsconfigPath).pipe(Effect.orElseSucceed(() => false));
+		const hasManifest = yield* fs.exists(manifestPath).pipe(Effect.orElseSucceed(() => false));
+		return {
+			dir: abs,
+			dirname: path.basename(abs),
+			name,
+			...version !== void 0 ? { version } : {},
+			modelPath,
+			...Option.isSome(packageJson) ? { packageJsonPath } : {},
+			...hasTsconfig ? { tsconfigPath } : {},
+			...hasManifest ? { manifestPath } : {}
+		};
+	});
+}
+/**
+* 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
+*/
+function discoverBundles(parentDir, options) {
+	return Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const absParent = options?.cwd !== void 0 ? path.resolve(options.cwd, parentDir) : path.resolve(parentDir);
+		yield* assertDirectory(absParent);
+		const entries = yield* fs.readDirectory(absParent).pipe(Effect.mapError((cause) => new BundleDiscoveryError({
+			path: absParent,
+			reason: "unreadableDirectory",
+			cause
+		})));
+		const subdirs = [];
+		for (const entry of [...entries].sort()) {
+			if (entry.startsWith(".")) continue;
+			const entryPath = path.join(absParent, entry);
+			const info = yield* fs.stat(entryPath).pipe(Effect.option);
+			if (Option.isSome(info) && info.value.type === "Directory") subdirs.push(entry);
+		}
+		const descriptors = [];
+		for (const subdir of subdirs) {
+			const subdirPath = path.join(absParent, subdir);
+			if ((yield* listModelFiles(subdirPath)).length === 0) return yield* Effect.fail(new BundleDiscoveryError({
+				path: absParent,
+				reason: "notABundleFolder",
+				detail: `"${subdir}" has no *.api.json model; use discoverBundle for selective inclusion`
+			}));
+			descriptors.push(yield* discoverBundle(subdirPath));
+		}
+		if (descriptors.length === 0) return yield* Effect.fail(new BundleDiscoveryError({
+			path: absParent,
+			reason: "emptyParent",
+			detail: "no bundle folders found; have the package models been built?"
+		}));
+		return descriptors;
+	});
+}
+/**
+* Discover and read a single bundle in one call.
+*
+* @public
+*/
+function loadBundle(dir, options) {
+	return Effect.flatMap(discoverBundle(dir, options), readBundle);
+}
+/**
+* Discover and read every bundle under a parent directory in one call.
+*
+* @public
+*/
+function loadBundles(parentDir, options) {
+	return Effect.flatMap(discoverBundles(parentDir, options), (descriptors) => Effect.forEach(descriptors, readBundle));
+}
+
+//#endregion
+export { BundleDiscoveryError, discoverBundle, discoverBundles, loadBundle, loadBundles };