@primafuture/contrib-kit-react 1.0.0

package/src/react-adapter-diagnostics.ts

@@ -0,0 +1,457 @@
+import * as contribKitCore from "@primafuture/contrib-kit-core";
+
+import * as adapterConfiguration from "./internal/adapter-configuration.js";
+import * as reactAdapterError from "./react-adapter-error.js";
+import type * as reactExtensionPoint from "./react-extension-point.js";
+
+/** Přesné Core kódy, které smí adapter zveřejnit jako bezpečný string. */
+const coreErrorCodes = new Set<contribKitCore.ContribKitErrorCode>([
+	"INVALID_ARGUMENT",
+	"INVALID_POINT_ID",
+	"INVALID_CONTRIBUTION_ID",
+	"INVALID_CONTRACT_VERSION",
+	"INVALID_CARDINALITY",
+	"INVALID_POLICY",
+	"FORGED_EXTENSION_POINT",
+	"FOREIGN_CORE_RUNTIME_POINT",
+	"POINT_ALREADY_REGISTERED",
+	"POINT_ID_COLLISION",
+	"POINT_NOT_REGISTERED",
+	"POINT_CLOSING",
+	"POINT_CLOSED",
+	"POINT_CONTRACT_VERSION_MISMATCH",
+	"REGISTRY_DISPOSING",
+	"REGISTRY_DISPOSED",
+	"OWNER_SCOPE_DISPOSING",
+	"OWNER_SCOPE_DISPOSED",
+	"CONTRIBUTION_ID_COLLISION",
+	"POINT_CARDINALITY_EXCEEDED",
+	"CONTRIBUTION_DATA_INVALID",
+	"CONTRIBUTION_IMPLEMENTATION_INVALID",
+	"CONTEXT_INVALID",
+	"REGISTRATION_CANCELLED",
+	"REGISTRATION_PREPARE_FAILED",
+	"REGISTRATION_PREPARE_TIMEOUT",
+	"REPLACEMENT_TARGET_NOT_FOUND",
+	"REPLACEMENT_TARGET_STALE",
+	"ORDERING_POLICY_FAILED",
+	"ORDERING_RESULT_INVALID",
+	"FILTER_POLICY_FAILED",
+	"SELECTION_POLICY_FAILED",
+	"SELECTION_RESULT_INVALID",
+	"CLEANUP_FAILED",
+	"CLEANUP_TIMEOUT",
+	"HOT_KEY_COLLISION",
+	"INCOMPATIBLE_HOT_UPDATE",
+]);
+
+/** Stabilní seznam adapter fází přijímaných z vlastní bezpečné chyby. */
+const reactAdapterErrorPhases = new Set<reactAdapterError.ReactAdapterErrorPhase>([
+	"configuration",
+	"resolve",
+	"load",
+	"render",
+	"customRender",
+	"fallback",
+	"policy",
+	"projection",
+	"callback",
+	"lifecycle",
+]);
+
+/**
+ * Bezpečná metadata jedné aktivní Core registrace bez business hodnot.
+ *
+ * @public
+ */
+export interface ReadonlyContributionMetadata {
+	/** Stabilní contribution identita uvnitř pointu. */
+	readonly contributionId: string;
+	/** Volitelná identita přispívajícího modulu. */
+	readonly contributorId?: string;
+	/** Volitelný lidsky čitelný label. */
+	readonly label?: string;
+	/** Volitelný lokální název pro diagnostiku. */
+	readonly localName?: string;
+	/** Opaque identita konkrétní Core activation. */
+	readonly registrationId: string;
+}
+
+/**
+ * Bezpečná public metadata extension pointu bez runtime capabilities.
+ *
+ * @public
+ */
+export interface ReadonlyPointMetadata {
+	/** Cardinalita katalogu daného pointu. */
+	readonly cardinality: "single" | "many";
+	/** Contract verze diagnostikované generation. */
+	readonly contractVersion: number;
+	/** Volitelný lidsky čitelný label. */
+	readonly label?: string;
+	/** Volitelný lokální název pro diagnostiku. */
+	readonly localName?: string;
+	/** Volitelná stabilní identita vlastníka pointu. */
+	readonly ownerId?: string;
+	/** Veřejná logická identita pointu. */
+	readonly pointId: string;
+}
+
+/**
+ * Frozen strukturovaná chyba určená host sinku a budoucí outlet policy.
+ *
+ * @public
+ */
+export interface ReactAdapterErrorEvent {
+	/** Opaque identita budoucí contribution boundary. */
+	readonly boundaryId?: string;
+	/** Přesný zachycený throwable nebo bezpečná syntetická chyba. */
+	readonly cause: unknown;
+	/** Stabilní adapterová klasifikace. */
+	readonly code: import("./react-adapter-error.js").ReactAdapterErrorCode;
+	/** Hostem výslovně projektovaný bezpečný context fragment. */
+	readonly contextProjection?: unknown;
+	/** Volitelná bezpečná metadata příslušné contribution. */
+	readonly contribution?: ReadonlyContributionMetadata;
+	/** Volitelný původní Core code bez přenosu Core error objektu. */
+	readonly coreCode?: string;
+	/** Opaque identita budoucí outlet instance. */
+	readonly outletId?: string;
+	/** Fáze adapter pipeline, ve které chyba vznikla. */
+	readonly phase: import("./react-adapter-error.js").ReactAdapterErrorPhase;
+	/** Volitelná bezpečná metadata příslušného pointu. */
+	readonly point?: ReadonlyPointMetadata;
+	/** Normalizovaný React component stack budoucí boundary. */
+	readonly reactComponentStack?: string;
+	/** Retry generation budoucí contribution boundary. */
+	readonly retryGeneration?: number;
+}
+
+/**
+ * Command-free event doručovaný best-effort diagnostickému sinku.
+ *
+ * @public
+ */
+export type ReactAdapterDiagnosticEvent =
+	| {
+		/** Rozlišuje strukturovanou chybu od late loader výsledku. */
+		readonly kind: "error";
+		/** Stejný frozen error event, který nese veřejný failed state. */
+		readonly error: ReactAdapterErrorEvent;
+	}
+	| {
+		/** Rozlišuje pozdní settlement budoucí managed-lazy generace. */
+		readonly kind: "lateLazyResult";
+		/** Opaque identita ukončené boundary. */
+		readonly boundaryId: string;
+		/** Bezpečná metadata contribution vlastnící loader. */
+		readonly contribution: ReadonlyContributionMetadata;
+		/** Druh pozdního settlementu. */
+		readonly outcome: "resolved" | "rejected";
+		/** Opaque identita outletu vlastnícího boundary. */
+		readonly outletId: string;
+		/** Volitelná bezpečná metadata pointu. */
+		readonly point?: ReadonlyPointMetadata;
+		/** Generation, které settlement původně patřil. */
+		readonly retryGeneration: number;
+	};
+
+/** Interní bezpečný vstup jednoho managed-lazy late-result eventu. */
+export interface ReactLateLazyResultDiagnosticInput {
+	/** Opaque committed boundary identita původního attemptu. */
+	readonly boundaryId: string;
+	/** Již projektovaná metadata bez contribution dat nebo implementation. */
+	readonly contribution: ReadonlyContributionMetadata;
+	/** Rozlišuje fulfillment od rejection bez přenosu business hodnoty či cause. */
+	readonly outcome: "resolved" | "rejected";
+	/** Opaque committed outlet identita původního attemptu. */
+	readonly outletId: string;
+	/** Volitelná bezpečná point metadata bez runtime capability. */
+	readonly point?: ReadonlyPointMetadata;
+	/** Retry generation, ve které loader skutečně začal. */
+	readonly retryGeneration: number;
+}
+
+/**
+ * Non-blocking best-effort cíl adapter diagnostiky.
+ *
+ * @public
+ */
+export interface ReactAdapterSink {
+	/** Přijme jeden frozen event; adapter návrat nikdy neawaituje. */
+	readonly report: (event: ReactAdapterDiagnosticEvent) => void | Promise<void>;
+}
+
+/**
+ * Výsledek synchronní budoucí contribution error policy.
+ *
+ * @public
+ */
+export type ReactErrorAction = "hide" | "renderFallback" | "escalate";
+
+/**
+ * Host policy rozhodující o budoucí izolaci contribution render chyby.
+ *
+ * @public
+ */
+export type ReactErrorPolicy = (error: ReactAdapterErrorEvent) => ReactErrorAction;
+
+/** Vstup bezpečného public error eventu bez raw registry nebo business hodnot. */
+export interface ReactAdapterErrorEventInput {
+	/** Opaque identita contribution boundary. */
+	readonly boundaryId?: string;
+	/** Stabilní adapterový code. */
+	readonly code: reactAdapterError.ReactAdapterErrorCode;
+	/** Přesný zachycený nebo syntetický cause. */
+	readonly cause: unknown;
+	/** Bezpečná metadata contribution bez business dat. */
+	readonly contribution?: ReadonlyContributionMetadata;
+	/** Fáze adapter pipeline. */
+	readonly phase: reactAdapterError.ReactAdapterErrorPhase;
+	/** Bezpečný původní Core code. */
+	readonly coreCode?: string;
+	/** Opaque identita outlet instance. */
+	readonly outletId?: string;
+	/** Bezpečná metadata pointu. */
+	readonly point?: ReadonlyPointMetadata;
+	/** Normalizovaný React component stack. */
+	readonly reactComponentStack?: string;
+	/** Monotonická retry generation contribution boundary. */
+	readonly retryGeneration?: number;
+	/** Hostem projektovaný context. */
+	readonly contextProjection?: unknown;
+	/** Rozlišuje projekci hodnoty undefined od absence projekce. */
+	readonly hasContextProjection?: boolean;
+}
+
+/**
+ * Přečte bezpečný Core code i z cizí fyzické Core runtime bez úniku accessor chyby.
+ */
+export function readCoreErrorCode(cause: unknown): contribKitCore.ContribKitErrorCode | undefined {
+	if (cause instanceof contribKitCore.ContribKitError) {
+		return cause.code;
+	}
+	if (typeof cause !== "object" || cause === null) {
+		return undefined;
+	}
+
+	try {
+		const code = Reflect.get(cause, "code", cause) as unknown;
+		return typeof code === "string" && coreErrorCodes.has(code as contribKitCore.ContribKitErrorCode)
+			? code as contribKitCore.ContribKitErrorCode
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Odvodí závazný React code z adapter chyby nebo bezpečné Core klasifikace.
+ */
+export function resolveReactErrorCode(
+	cause: unknown,
+	coreCode: contribKitCore.ContribKitErrorCode | undefined,
+): reactAdapterError.ReactAdapterErrorCode {
+	if (cause instanceof reactAdapterError.ReactAdapterError) {
+		return cause.code;
+	}
+	if (coreCode === "POINT_NOT_REGISTERED"
+		|| coreCode === "POINT_CLOSING"
+		|| coreCode === "POINT_CLOSED") {
+		return "REACT_POINT_UNAVAILABLE";
+	}
+	if (coreCode === "REGISTRY_DISPOSING" || coreCode === "REGISTRY_DISPOSED") {
+		return "REACT_REGISTRY_UNAVAILABLE";
+	}
+
+	return "REACT_RESOLVE_FAILED";
+}
+
+/**
+ * Zachová bezpečnou adapter phase, ostatní query failures zařadí do resolve.
+ */
+export function resolveReactErrorPhase(
+	cause: unknown,
+): reactAdapterError.ReactAdapterErrorPhase {
+	if (cause instanceof reactAdapterError.ReactAdapterError) {
+		const phase = cause.details.phase;
+		if (typeof phase === "string"
+			&& reactAdapterErrorPhases.has(phase as reactAdapterError.ReactAdapterErrorPhase)) {
+			return phase as reactAdapterError.ReactAdapterErrorPhase;
+		}
+	}
+
+	return "resolve";
+}
+
+/**
+ * Projektuje pouze známá scalar point metadata a při getter failure raději nic.
+ */
+export function createPointMetadata(
+	point: reactExtensionPoint.AnyReactExtensionPoint | undefined,
+): ReadonlyPointMetadata | undefined {
+	if (point === undefined) {
+		return undefined;
+	}
+
+	try {
+		const pointId = point.pointId;
+		const contractVersion = point.contractVersion;
+		const cardinality = point.cardinality;
+		const ownerId = point.ownerId;
+		const localName = point.localName;
+		const label = point.label;
+		if (typeof pointId !== "string"
+			|| pointId.length === 0
+			|| typeof contractVersion !== "number"
+			|| !Number.isSafeInteger(contractVersion)
+			|| contractVersion < 1
+			|| (cardinality !== "single" && cardinality !== "many")
+			|| (ownerId !== undefined && typeof ownerId !== "string")
+			|| (localName !== undefined && typeof localName !== "string")
+			|| (label !== undefined && typeof label !== "string")) {
+			return undefined;
+		}
+		return Object.freeze({
+			pointId,
+			contractVersion,
+			cardinality,
+			...(ownerId === undefined ? {} : { ownerId }),
+			...(localName === undefined ? {} : { localName }),
+			...(label === undefined ? {} : { label }),
+		});
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Projektuje contribution metadata bez jediného čtení dat nebo implementation.
+ */
+export function createContributionMetadata<Point extends contribKitCore.AnyExtensionPoint>(
+	contribution: contribKitCore.RegisteredContribution<Point> | undefined,
+): ReadonlyContributionMetadata | undefined {
+	if (contribution === undefined) {
+		return undefined;
+	}
+
+	try {
+		const registrationId = contribution.registrationId;
+		const contributionId = contribution.contributionId;
+		const contributorId = contribution.contributorId;
+		const localName = contribution.localName;
+		const label = contribution.label;
+		return Object.freeze({
+			registrationId,
+			contributionId,
+			...(contributorId === undefined ? {} : { contributorId }),
+			...(localName === undefined ? {} : { localName }),
+			...(label === undefined ? {} : { label }),
+		});
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Vytvoří shallow-frozen veřejný event bez raw contextu nebo registry capability.
+ */
+export function createReactAdapterErrorEvent(
+	input: ReactAdapterErrorEventInput,
+): ReactAdapterErrorEvent {
+	return Object.freeze({
+		code: input.code,
+		phase: input.phase,
+		cause: input.cause,
+		...(input.boundaryId === undefined ? {} : { boundaryId: input.boundaryId }),
+		...(input.contribution === undefined ? {} : { contribution: input.contribution }),
+		...(input.coreCode === undefined ? {} : { coreCode: input.coreCode }),
+		...(input.outletId === undefined ? {} : { outletId: input.outletId }),
+		...(input.point === undefined ? {} : { point: input.point }),
+		...(input.reactComponentStack === undefined
+			? {}
+			: { reactComponentStack: input.reactComponentStack }),
+		...(input.retryGeneration === undefined
+			? {}
+			: { retryGeneration: input.retryGeneration }),
+		...(input.hasContextProjection === true
+			? { contextProjection: input.contextProjection }
+			: {}),
+	});
+}
+
+/**
+ * Zabalí veřejnou chybu do frozen diagnostic union větve.
+ */
+export function createErrorDiagnostic(
+	error: ReactAdapterErrorEvent,
+): ReactAdapterDiagnosticEvent {
+	return Object.freeze({ kind: "error", error });
+}
+
+/**
+ * Vytvoří frozen late-result event bez raw settlement hodnoty, cause nebo contextu.
+ */
+export function createLateLazyResultDiagnostic(
+	input: ReactLateLazyResultDiagnosticInput,
+): ReactAdapterDiagnosticEvent {
+	return Object.freeze({
+		kind: "lateLazyResult",
+		boundaryId: input.boundaryId,
+		contribution: input.contribution,
+		outcome: input.outcome,
+		outletId: input.outletId,
+		...(input.point === undefined ? {} : { point: input.point }),
+		retryGeneration: input.retryGeneration,
+	});
+}
+
+/**
+ * Pohltí Promise, cizí thenable i jejich pozdní rejection bez diagnostické rekurze.
+ */
+export function normalizeSinkResult(result: unknown): void {
+	try {
+		/** Sink rejection nemá business ani další diagnostickou autoritu. */
+		function ignoreSinkRejection(): void {
+			// Best-effort sink záměrně končí bez dalšího eventu.
+		}
+		void Promise.resolve(result).catch(ignoreSinkRejection);
+	} catch {
+		// Throwing then getter nesmí opustit diagnostickou hranici.
+	}
+}
+
+/**
+ * Doručí command-free diagnostiku custom sinku nebo bezpečnému console fallbacku.
+ */
+export function reportReactAdapterDiagnostic(
+	event: ReactAdapterDiagnosticEvent,
+	configuration: adapterConfiguration.AdapterScopeConfiguration,
+	development = true,
+): void {
+	if (configuration.sink !== undefined) {
+		try {
+			normalizeSinkResult(adapterConfiguration.callCapturedReactAdapterSink(
+				configuration.sink,
+				event,
+			));
+		} catch {
+			// Sync sink throw nesmí změnit committed React stav.
+		}
+		return;
+	}
+	if (event.kind !== "error" && !development) {
+		return;
+	}
+
+	try {
+		const consoleReceiver = globalThis.console;
+		const method = event.kind === "error" ? "error" : "warn";
+		const report = Reflect.get(consoleReceiver, method, consoleReceiver) as unknown;
+		if (typeof report === "function") {
+			normalizeSinkResult(Reflect.apply(report, consoleReceiver, [event]));
+		}
+	} catch {
+		// Chybějící nebo rozbitý console fallback je bezpečný no-op.
+	}
+}

package/src/react-adapter-error.ts

@@ -0,0 +1,88 @@
+/**
+ * Stable public code for expected React adapter errors.
+ *
+ * @public
+ */
+export type ReactAdapterErrorCode =
+	| "REACT_INVALID_ARGUMENT"
+	| "REACT_REGISTRY_NOT_PROVIDED"
+	| "REACT_REGISTRY_INVALID"
+	| "REACT_REGISTRY_UNAVAILABLE"
+	| "REACT_ADAPTER_DISPOSED"
+	| "REACT_POINT_IMPLEMENTATION_INVALID"
+	| "REACT_POINT_UNAVAILABLE"
+	| "REACT_RESOLVE_FAILED"
+	| "REACT_LAZY_LOAD_FAILED"
+	| "REACT_RENDER_FAILED"
+	| "REACT_ERROR_POLICY_FAILED"
+	| "REACT_CONTEXT_PROJECTION_FAILED"
+	| "REACT_CALLBACK_FAILED";
+
+/**
+ * Stable phase in which the React adapter captured an error.
+ *
+ * @public
+ */
+export type ReactAdapterErrorPhase =
+	| "configuration"
+	| "resolve"
+	| "load"
+	| "render"
+	| "customRender"
+	| "fallback"
+	| "policy"
+	| "projection"
+	| "callback"
+	| "lifecycle";
+
+/**
+ * Vytvoří vlastní shallow-frozen kopii bezpečných detailů chyby.
+ */
+function copyErrorDetails(
+	details: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> {
+	return Object.freeze(details === undefined ? {} : { ...details });
+}
+
+/**
+ * Stable public React adapter error with safe immutable details.
+ *
+ * @public
+ */
+export class ReactAdapterError extends Error {
+	/** Machine-readable classification of the adapter error. */
+	public readonly code: ReactAdapterErrorCode;
+
+	/** Shallow-frozen safe metadata without raw contribution values. */
+	public readonly details: Readonly<Record<string, unknown>>;
+
+	/** Original throwable preserved when wrapping a foreign error. */
+	public override readonly cause?: unknown;
+
+	/**
+	 * Creates a public error with a stable code and its own copy of details.
+	 */
+	public constructor(
+		code: ReactAdapterErrorCode,
+		message: string,
+		options?: {
+			/** Original throwable that caused the stable wrapper. */
+			readonly cause?: unknown;
+			/** Safe scalar metadata for the specific failure phase. */
+			readonly details?: Readonly<Record<string, unknown>>;
+		},
+	) {
+		super(message);
+		this.name = "ReactAdapterError";
+		this.code = code;
+		this.details = copyErrorDetails(options?.details);
+		if (options !== undefined && Object.hasOwn(options, "cause")) {
+			Object.defineProperty(this, "cause", {
+				configurable: true,
+				enumerable: false,
+				value: options.cause,
+				writable: false,
+			});
+		}
+	}
+}