@real-router/validation-plugin 0.0.1

package/src/validationPlugin.ts

@@ -0,0 +1,330 @@
+// packages/validation-plugin/src/validationPlugin.ts
+
+import { RouterError } from "@real-router/core";
+import { getInternals } from "@real-router/core/validation";
+import {
+  validateRouteName,
+  isState,
+  isBoolean,
+  getTypeDescription,
+} from "type-guards";
+
+import {
+  validateDependencyName,
+  validateSetDependencyArgs as validateSetDependencyArgsRaw,
+  validateDependenciesObject,
+  validateDependencyExists as validateDependencyExistsRaw,
+  validateDependencyCount,
+  validateCloneArgs,
+  warnOverwrite as warnDepsOverwrite,
+  warnBatchOverwrite,
+  warnRemoveNonExistent,
+} from "./validators/dependencies";
+import { validateEventName, validateListenerArgs } from "./validators/eventBus";
+import {
+  validateHandler,
+  validateNotRegistering,
+  validateHandlerLimit,
+  validateLifecycleCountThresholds,
+  warnOverwrite as warnLifecycleOverwrite,
+  warnAsyncGuardSync,
+} from "./validators/lifecycle";
+import {
+  validateNavigateArgs,
+  validateNavigateToDefaultArgs,
+  validateNavigationOptions,
+  validateNavigateParams,
+  validateStartArgs,
+} from "./validators/navigation";
+import {
+  validateLimitValue,
+  validateLimits,
+  validateOptions,
+} from "./validators/options";
+import {
+  validatePluginLimit,
+  validatePluginKeys,
+  validateCountThresholds as validatePluginCountThresholds,
+  warnBatchDuplicates,
+  warnPluginMethodType,
+  warnPluginAfterStart,
+  validateAddInterceptorArgs,
+} from "./validators/plugins";
+import {
+  validateExistingRoutes,
+  validateForwardToConsistency,
+  validateRoutePropertiesStore,
+  validateForwardToTargetsStore,
+  validateDependenciesStructure,
+  validateLimitsConsistency,
+} from "./validators/retrospective";
+import {
+  validateBuildPathArgs,
+  validateMatchPathArgs,
+  validateIsActiveRouteArgs,
+  validateShouldUpdateNodeArgs,
+  validateStateBuilderArgs,
+  validateAddRouteArgs,
+  validateRoutes,
+  validateRemoveRouteArgs,
+  validateUpdateRouteBasicArgs,
+  validateUpdateRoutePropertyTypes,
+  validateUpdateRoute,
+  validateParentOption as validateParentOptionRaw,
+  throwIfInternalRoute,
+  throwIfInternalRouteInArray,
+  validateSetRootPathArgs,
+  guardRouteCallbacks,
+  guardNoAsyncCallbacks,
+} from "./validators/routes";
+import { validateMakeStateArgs } from "./validators/state";
+
+import type { PluginFactory, RouterValidator } from "@real-router/core";
+import type { RouterInternals } from "@real-router/core/validation";
+
+function buildValidatorObject(ctx: RouterInternals): RouterValidator {
+  return {
+    routes: {
+      validateBuildPathArgs,
+      validateMatchPathArgs,
+      validateIsActiveRouteArgs,
+      validateShouldUpdateNodeArgs,
+      validateStateBuilderArgs,
+
+      validateAddRouteArgs(routes) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+        validateAddRouteArgs(routes as any);
+      },
+
+      validateRoutes(routes, store) {
+        const typedStore = store as {
+          tree?: unknown;
+          config?: { forwardMap?: Record<string, string> };
+        };
+
+        validateRoutes(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+          routes as any,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+          typedStore.tree as any,
+          typedStore.config?.forwardMap,
+        );
+      },
+      validateRemoveRouteArgs,
+      validateUpdateRouteBasicArgs,
+      validateUpdateRoutePropertyTypes(_name, updates) {
+        const upd = updates as Record<string, unknown>;
+
+        validateUpdateRoutePropertyTypes(
+          upd.forwardTo,
+          upd.defaultParams,
+          upd.decodeParams,
+          upd.encodeParams,
+        );
+      },
+      validateUpdateRoute(name, updates, store) {
+        const typedStore = store as {
+          matcher: {
+            hasRoute: (routeName: string) => boolean;
+            getSegmentsByName: (routeName: string) => unknown;
+          };
+          config: { forwardMap: Record<string, string> };
+        };
+        const forwardTo = (updates as Record<string, unknown>).forwardTo;
+
+        validateUpdateRoute(
+          name,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+          forwardTo as any,
+          (routeName: string) => typedStore.matcher.hasRoute(routeName),
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+          typedStore.matcher as any,
+          typedStore.config,
+        );
+      },
+      validateParentOption(parent, tree) {
+        validateParentOptionRaw(parent as string);
+        let node = tree as { children: Map<string, unknown> };
+
+        for (const segment of (parent as string).split(".")) {
+          const child = node.children.get(segment) as
+            | { children: Map<string, unknown> }
+            | undefined;
+
+          if (!child) {
+            throw new ReferenceError(
+              `[router.addRoute] Parent route "${parent as string}" does not exist`,
+            );
+          }
+
+          node = child;
+        }
+      },
+      validateRouteName(name, caller) {
+        validateRouteName(name, caller);
+      },
+      throwIfInternalRoute(name, caller) {
+        throwIfInternalRoute(name as string, caller);
+      },
+
+      throwIfInternalRouteInArray(routes, caller) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+        throwIfInternalRouteInArray(routes as any, caller);
+      },
+      validateExistingRoutes,
+      validateForwardToConsistency,
+      validateSetRootPathArgs,
+      guardRouteCallbacks,
+      guardNoAsyncCallbacks,
+    },
+    options: {
+      validateLimitValue(name, value) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+        validateLimitValue(name as any, value, "validate");
+      },
+      validateLimits(limits) {
+        validateLimits(limits, "validate");
+      },
+      validateOptions,
+    },
+    dependencies: {
+      validateDependencyName,
+      validateSetDependencyArgs(_name, _value, _caller) {
+        validateSetDependencyArgsRaw(_name);
+      },
+      validateDependenciesObject,
+      validateDependencyExists(name, store) {
+        const typedStore = store as { dependencies?: Record<string, unknown> };
+        const value = typedStore.dependencies?.[name];
+
+        validateDependencyExistsRaw(value, name);
+      },
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      validateDependencyLimit(_store, _limits) {},
+      validateDependenciesStructure,
+      validateDependencyCount,
+      validateCloneArgs,
+      warnOverwrite: warnDepsOverwrite,
+      warnBatchOverwrite,
+      warnRemoveNonExistent,
+    },
+    plugins: {
+      validatePluginLimit(count, limits) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access
+        validatePluginLimit(count, 1, (limits as any)?.maxPlugins);
+      },
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      validateNoDuplicatePlugins(_factory, _factories) {},
+      validatePluginKeys,
+      validateCountThresholds(count) {
+        const maxPlugins = ctx.getOptions().limits?.maxPlugins ?? 50;
+
+        validatePluginCountThresholds(count, maxPlugins);
+      },
+      warnBatchDuplicates,
+      warnPluginMethodType,
+      warnPluginAfterStart,
+      validateAddInterceptorArgs,
+    },
+    lifecycle: {
+      validateHandler,
+      validateNotRegistering(name, _guards, caller) {
+        validateNotRegistering(false, name, caller);
+      },
+      validateHandlerLimit(count, limits, caller) {
+        validateHandlerLimit(
+          count,
+          caller,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access
+          (limits as any)?.maxLifecycleHandlers,
+        );
+      },
+      validateCountThresholds(count, methodName) {
+        const maxHandlers =
+          ctx.getOptions().limits?.maxLifecycleHandlers ?? 200;
+
+        validateLifecycleCountThresholds(count, methodName, maxHandlers);
+      },
+      warnOverwrite: warnLifecycleOverwrite,
+      warnAsyncGuardSync,
+    },
+    navigation: {
+      validateNavigateArgs,
+      validateNavigateToDefaultArgs,
+      validateNavigationOptions,
+      validateParams: validateNavigateParams,
+      validateStartArgs,
+    },
+    state: {
+      validateMakeStateArgs,
+      validateAreStatesEqualArgs(s1, s2, ignoreQP) {
+        if (!isState(s1)) {
+          throw new TypeError(
+            `[router.areStatesEqual] Invalid state1: ${getTypeDescription(s1)}. Expected State object.`,
+          );
+        }
+        if (!isState(s2)) {
+          throw new TypeError(
+            `[router.areStatesEqual] Invalid state2: ${getTypeDescription(s2)}. Expected State object.`,
+          );
+        }
+        if (ignoreQP !== undefined && !isBoolean(ignoreQP)) {
+          throw new TypeError(
+            `[router.areStatesEqual] Invalid ignoreQueryParams: ${getTypeDescription(ignoreQP)}. Expected boolean.`,
+          );
+        }
+      },
+    },
+    eventBus: {
+      validateEventName,
+
+      validateListenerArgs(name, cb) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        validateListenerArgs(name as any, cb as any);
+      },
+    },
+  };
+}
+
+export function validationPlugin(): PluginFactory {
+  // eslint-disable-next-line unicorn/consistent-function-scoping
+  return (router) => {
+    const ctx = getInternals(router);
+
+    if (router.isActive()) {
+      throw new RouterError("VALIDATION_PLUGIN_AFTER_START", {
+        message: "validation-plugin must be registered before router.start()",
+      });
+    }
+
+    // RouterInternals.validator is now mutable — direct assignment works
+    ctx.validator = buildValidatorObject(ctx);
+
+    try {
+      const store = ctx.routeGetStore();
+      const deps = ctx.dependenciesGetStore();
+      const options = ctx.getOptions();
+
+      validateExistingRoutes(store);
+      validateForwardToConsistency(store);
+      validateRoutePropertiesStore(store);
+      validateForwardToTargetsStore(store);
+      validateDependenciesStructure(deps);
+      validateLimitsConsistency(options, store, deps);
+      ctx.validator.options.validateOptions(
+        options as unknown,
+        "constructor (retrospective)",
+      );
+    } catch (error) {
+      ctx.validator = null;
+
+      throw error;
+    }
+
+    return {
+      teardown() {
+        ctx.validator = null;
+      },
+    };
+  };
+}

package/src/validators/dependencies.ts

@@ -0,0 +1,159 @@
+// packages/validation-plugin/src/validators/dependencies.ts
+
+import { logger } from "@real-router/logger";
+import { getTypeDescription } from "type-guards";
+
+import { computeThresholds } from "../helpers";
+
+const DEFAULT_MAX_DEPENDENCIES = 100;
+
+export function validateDependencyName(
+  name: unknown,
+  methodName: string,
+): asserts name is string {
+  if (typeof name !== "string") {
+    throw new TypeError(
+      `[router.${methodName}] dependency name must be a string, got ${typeof name}`,
+    );
+  }
+}
+
+export function validateSetDependencyArgs(
+  name: unknown,
+): asserts name is string {
+  if (typeof name !== "string") {
+    throw new TypeError(
+      `[router.setDependency] dependency name must be a string, got ${typeof name}`,
+    );
+  }
+}
+
+export function validateDependenciesObject(
+  deps: unknown,
+  methodName: string,
+): asserts deps is Record<string, unknown> {
+  if (!(deps && typeof deps === "object" && deps.constructor === Object)) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid argument: expected plain object, received ${getTypeDescription(deps)}`,
+    );
+  }
+
+  for (const key in deps) {
+    if (Object.getOwnPropertyDescriptor(deps, key)?.get) {
+      throw new TypeError(
+        `[router.${methodName}] Getters not allowed: "${key}"`,
+      );
+    }
+  }
+}
+
+export function validateDependencyExists(
+  value: unknown,
+  dependencyName: string,
+): asserts value is NonNullable<unknown> {
+  if (value === undefined) {
+    throw new ReferenceError(
+      `[router.getDependency] dependency "${dependencyName}" not found`,
+    );
+  }
+}
+
+export function validateDependencyLimit(
+  currentCount: number,
+  newCount: number,
+  methodName: string,
+  maxDependencies: number = DEFAULT_MAX_DEPENDENCIES,
+): void {
+  if (maxDependencies === 0) {
+    return;
+  }
+
+  const totalCount = currentCount + newCount;
+
+  if (totalCount >= maxDependencies) {
+    throw new RangeError(
+      `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). ` +
+        `Current: ${totalCount}. This is likely a bug in your code.`,
+    );
+  }
+}
+
+export function validateDependencyCount(
+  store: unknown,
+  methodName: string,
+): void {
+  const typedStore = store as {
+    dependencies: Record<string, unknown>;
+    limits?: { maxDependencies?: number };
+  };
+  const maxDependencies =
+    typedStore.limits?.maxDependencies ?? DEFAULT_MAX_DEPENDENCIES;
+
+  if (maxDependencies === 0) {
+    return;
+  }
+
+  const currentCount = Object.keys(typedStore.dependencies).length;
+  const { warn, error } = computeThresholds(maxDependencies);
+
+  if (currentCount >= maxDependencies) {
+    throw new RangeError(
+      `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). Current: ${currentCount}.`,
+    );
+  } else if (currentCount === error) {
+    logger.error(
+      `router.${methodName}`,
+      `${currentCount} dependencies registered! This indicates architectural problems. Hard limit at ${maxDependencies}.`,
+    );
+  } else if (currentCount === warn) {
+    logger.warn(
+      `router.${methodName}`,
+      `${currentCount} dependencies registered. Consider if all are necessary.`,
+    );
+  }
+}
+
+export function validateCloneArgs(dependencies: unknown): void {
+  if (dependencies === undefined) {
+    return;
+  }
+
+  if (
+    !(
+      dependencies &&
+      typeof dependencies === "object" &&
+      dependencies.constructor === Object
+    )
+  ) {
+    throw new TypeError(
+      `[cloneRouter] Invalid dependencies: expected plain object or undefined, received ${typeof dependencies}`,
+    );
+  }
+
+  for (const key in dependencies as Record<string, unknown>) {
+    if (Object.getOwnPropertyDescriptor(dependencies, key)?.get) {
+      throw new TypeError(
+        `[cloneRouter] Getters not allowed in dependencies: "${key}"`,
+      );
+    }
+  }
+}
+
+export function warnOverwrite(name: string, methodName: string): void {
+  logger.warn(
+    `router.${methodName}`,
+    "Router dependency already exists and is being overwritten:",
+    name,
+  );
+}
+
+export function warnBatchOverwrite(keys: string[], methodName: string): void {
+  logger.warn(`router.${methodName}`, "Overwritten:", keys.join(", "));
+}
+
+export function warnRemoveNonExistent(name: unknown): void {
+  logger.warn(
+    "router.removeDependency",
+    `Attempted to remove non-existent dependency: "${typeof name === "string" ? name : String(name)}"`,
+  );
+}

package/src/validators/eventBus.ts

@@ -0,0 +1,48 @@
+// packages/validation-plugin/src/validators/eventBus.ts
+
+import type { Plugin } from "@real-router/core";
+
+// Local types — mirrors EventName and EventMethodMap from @real-router/types
+// (@real-router/types is not a direct dependency of this package)
+interface EventMethodMap {
+  $start: "onStart";
+  $stop: "onStop";
+  $$start: "onTransitionStart";
+  $$cancel: "onTransitionCancel";
+  $$success: "onTransitionSuccess";
+  $$error: "onTransitionError";
+}
+
+type EventName = keyof EventMethodMap;
+
+// Local set — mirrors validEventNames from @real-router/core/constants
+// (not exported from @real-router/core public API)
+const validEventNames = new Set<EventName>([
+  "$start",
+  "$stop",
+  "$$start",
+  "$$cancel",
+  "$$success",
+  "$$error",
+]);
+
+export function validateEventName(eventName: unknown): void {
+  if (!validEventNames.has(eventName as EventName)) {
+    throw new TypeError(
+      `[router.addEventListener] Invalid event name: ${String(eventName)}. Must be one of: $start, $stop, $$start, $$cancel, $$success, $$error`,
+    );
+  }
+}
+
+export function validateListenerArgs<E extends EventName>(
+  eventName: E,
+  cb: Plugin[EventMethodMap[E]],
+): void {
+  validateEventName(eventName);
+
+  if (typeof cb !== "function") {
+    throw new TypeError(
+      `[router.addEventListener] callback must be a function, got ${typeof cb}`,
+    );
+  }
+}