@effected/workspaces 0.25.0 → 0.27.0

package/LayerPolicy.js

@@ -0,0 +1,133 @@
+import { ALL_DEPENDENCY_FIELDS } from "./internal/dependencyFields.js";
+import { Effect, FileSystem, Result, Schema } from "effect";
+import { GlobSet } from "@effected/glob";
+import { DependencyField } from "@effected/npm";
+
+//#region src/LayerPolicy.ts
+const REQUIRED_EDGE = /^\S+ -> \S+$/;
+/** `input` without `keys`, when it is a plain object; anything else passes through for the schema to reject. */
+const withoutKeys = (input, keys) => {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) return input;
+	return Object.fromEntries(Object.entries(input).filter(([key]) => !keys.includes(key)));
+};
+/**
+* Raised when a layer policy cannot be read, parsed or decoded.
+*
+* @public
+*/
+var LayerPolicyError = class extends Schema.TaggedError()("LayerPolicyError", {
+	/** `read`: the file could not be read. `json`: it is not JSON. `decode`: it is not a `LayerPolicy`. */
+	reason: Schema.Literals([
+		"read",
+		"json",
+		"decode"
+	]),
+	/** The file, when the policy came from one. */
+	path: Schema.optionalKey(Schema.String),
+	/** The originating failure. */
+	cause: Schema.Defect()
+}) {
+	/** Renders the failure kind and the file into one line. */
+	get message() {
+		const at = this.path === void 0 ? "" : ` at ${this.path}`;
+		switch (this.reason) {
+			case "read": return `Could not read the layer policy${at}`;
+			case "json": return `The layer policy${at} is not valid JSON`;
+			default: return `The layer policy${at} does not match the LayerPolicy shape${this.cause instanceof Error && this.cause.message !== "" ? `: ${this.cause.message}` : ""}`;
+		}
+	}
+};
+/**
+* A committed dependency-layering policy (`layers.json`).
+*
+* @remarks
+* `layers` is top-down: an edge may only point from a layer to one BELOW it
+* (a higher index), or into `tooling`. `tooling` packages may depend on each
+* other but never reach a layer. `unconstrained` holds globs (through
+* `@effected/glob`) for packages whose own edges are not checked (a test
+* harness, the private root). `fields` narrows which dependency maps count,
+* defaulting to all four. `requiredEdges` (`"a -> b"`) are edges that must
+* exist in a checked field: the non-vacuity guard against a discovery that
+* quietly drops real edges.
+*
+* Every entry matches a package's `name`, never its `relativePath`: `layers`
+* and `tooling` list exact names, and `unconstrained` globs match names. A
+* private root named `my-monorepo` at `relativePath` `"."` is classified as
+* `"my-monorepo"`; an entry of `"."` or `"packages/*"` classifies nothing.
+*
+* Decoding is strict: a key the policy does not model fails `decode`, and the
+* message names every such key. A typo on an optional key would otherwise be
+* silently dropped: `requiredEdge` would remove the non-vacuity guard and
+* leave the report green. `$schema` is always accepted. A file that carries
+* keys of its own, such as systems' `harness`, passes them in `allowKeys`.
+*
+* @example
+* ```ts
+* import { NodeServices } from "@effect/platform-node";
+* import { LayerPolicy } from "@effected/workspaces/testing";
+* import { Effect } from "effect";
+*
+* const policy = LayerPolicy.load("/repo/layers.json").pipe(Effect.provide(NodeServices.layer));
+* ```
+*
+* @public
+*/
+var LayerPolicy = class LayerPolicy extends Schema.Class("LayerPolicy")({
+	/** Exact package names (never relative paths) per layer, top layer first. */
+	layers: Schema.Array(Schema.Array(Schema.String)),
+	/** Exact package names (never relative paths) any layer may depend on that never depend on a layer. */
+	tooling: Schema.Array(Schema.String),
+	/** Globs matched against package names (never relative paths) for packages whose own edges are not checked. */
+	unconstrained: Schema.Array(Schema.String).check(Schema.makeFilter((patterns) => Result.isSuccess(GlobSet.compileResult(patterns)), { title: "compilable glob patterns" })),
+	/** The dependency maps to check. Absent means all four. */
+	fields: Schema.optionalKey(Schema.Array(DependencyField)),
+	/** Edges that must exist, written `"a -> b"`. */
+	requiredEdges: Schema.optionalKey(Schema.Array(Schema.String.check(Schema.isPattern(REQUIRED_EDGE))))
+}) {
+	/** The dependency maps a check reads: `fields`, or all four. */
+	get effectiveFields() {
+		return this.fields ?? ALL_DEPENDENCY_FIELDS;
+	}
+	/**
+	* Decode a policy from a parsed JSON value.
+	*
+	* @remarks
+	* Every key the policy does not model fails, except `$schema` and the
+	* keys named in `options.allowKeys`, which are dropped before decoding.
+	* `options.path` names the file in the error.
+	*/
+	static decode = Effect.fn("LayerPolicy.decode")((input, options) => {
+		const path = options?.path;
+		return Schema.decodeUnknownEffect(LayerPolicy)(withoutKeys(input, ["$schema", ...options?.allowKeys ?? []]), {
+			onExcessProperty: "error",
+			errors: "all"
+		}).pipe(Effect.mapError((cause) => new LayerPolicyError({
+			reason: "decode",
+			cause,
+			...path === void 0 ? {} : { path }
+		})));
+	});
+	/** Read, parse and decode the policy file at `path`; `options.allowKeys` is passed to `decode`. */
+	static load = Effect.fn("LayerPolicy.load")(function* (path, options) {
+		const text = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.mapError((cause) => new LayerPolicyError({
+			reason: "read",
+			path,
+			cause
+		})));
+		const json = yield* Effect.try({
+			try: () => JSON.parse(text),
+			catch: (cause) => new LayerPolicyError({
+				reason: "json",
+				path,
+				cause
+			})
+		});
+		return yield* LayerPolicy.decode(json, {
+			path,
+			allowKeys: options?.allowKeys
+		});
+	});
+};
+
+//#endregion
+export { LayerPolicy, LayerPolicyError };