@unieojs/unio-evjs-adapter 0.1.0

package/src/types.ts

@@ -0,0 +1,208 @@
+import type {
+  EvBuildResult,
+  EvPlugin,
+  EvPluginContext,
+  EvPluginHooks,
+} from "@evjs/ev";
+
+export type ClientManifest = EvBuildResult["clientManifest"];
+export type ServerManifest = NonNullable<EvBuildResult["serverManifest"]>;
+export type PageManifestEntry = NonNullable<ClientManifest["pages"]>[string];
+export type RouteEntry = NonNullable<ClientManifest["routes"]>[number];
+export type ServerFnEntry = ServerManifest["fns"][string];
+
+export type {
+  EvBuildResult,
+  EvPlugin,
+  EvPluginContext,
+  EvPluginHooks,
+};
+
+export type CapabilityStatus =
+  | "supported"
+  | "partial"
+  | "degraded"
+  | "unsupported";
+
+export interface UboaCapabilities {
+  static: CapabilityStatus;
+  routes: CapabilityStatus;
+  serverlessFunction: CapabilityStatus;
+  serverFunctionIntrospection: CapabilityStatus;
+  restRouteIntrospection: CapabilityStatus;
+  edgeMiddleware: CapabilityStatus;
+  rsc: CapabilityStatus;
+  imageOptimization: CapabilityStatus;
+}
+
+export interface UboaServerFunctionDescriptor {
+  name: string;
+  runtime: string;
+  entry: string;
+  handler: string;
+  handlerProtocol: string;
+  memory: number;
+  maxDuration: number;
+  environment: Record<string, unknown>;
+  bindings: Record<string, unknown>;
+  framework: Record<string, unknown>;
+  source: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ExtendServerFunctionDescriptorContext {
+  descriptor: UboaServerFunctionDescriptor;
+  serverFunctionName: string;
+}
+
+export interface ExtendArtifactsContext {
+  artifacts: UboaArtifact[];
+  serverFunctionName: string;
+}
+
+export interface AfterEmitContext {
+  outputDir: string;
+  serverFunctionName: string;
+}
+
+export interface UnioEvjsAdapterOptions {
+  cwd?: string;
+  outputDir?: string;
+  serverFunctionName?: string;
+  serverFunctionEndpoint?: string;
+  extendServerFunctionDescriptor?: (
+    context: ExtendServerFunctionDescriptorContext,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  extendArtifacts?: (
+    context: ExtendArtifactsContext,
+  ) => UboaArtifact[] | Promise<UboaArtifact[]>;
+  afterEmit?: (context: AfterEmitContext) => void | Promise<void>;
+}
+
+export interface DetectResult {
+  detected: boolean;
+  signals: string[];
+  configFiles: string[];
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+interface UboaRouteBase {
+  id: string;
+  match: string;
+}
+
+export interface UboaStaticRoute extends UboaRouteBase {
+  type: "static";
+  entry: string;
+  serverFunction?: never;
+  edgeFunction?: never;
+  methods?: never;
+}
+
+export interface UboaServerFunctionRoute extends UboaRouteBase {
+  type: "serverFunction";
+  serverFunction: string;
+  methods?: string[];
+  entry?: never;
+  edgeFunction?: never;
+}
+
+export interface UboaEdgeFunctionRoute extends UboaRouteBase {
+  type: "edgeFunction";
+  edgeFunction: string;
+  entry?: never;
+  serverFunction?: never;
+  methods?: never;
+}
+
+export type UboaRoute =
+  | UboaStaticRoute
+  | UboaServerFunctionRoute
+  | UboaEdgeFunctionRoute;
+
+interface UboaMiddlewareBase {
+  name: string;
+  match: string[];
+}
+
+export interface UboaEdgeMiddleware extends UboaMiddlewareBase {
+  runtime: "edge";
+  entry: string;
+  serverFunction?: never;
+}
+
+export interface UboaServerlessMiddleware extends UboaMiddlewareBase {
+  runtime: "serverless";
+  serverFunction: string;
+  entry?: never;
+}
+
+export type UboaMiddleware =
+  | UboaEdgeMiddleware
+  | UboaServerlessMiddleware;
+
+export type UboaArtifactResourceKind =
+  | "assets"
+  | "serverFunction"
+  | "edgeBundle"
+  | "apiSchema";
+
+export interface UboaAssetsArtifact {
+  id: string;
+  resourceKind: "assets";
+  path: string;
+}
+
+export interface UboaServerFunctionArtifact {
+  id: string;
+  resourceKind: "serverFunction";
+  path: string;
+}
+
+export interface UboaEdgeBundleArtifact {
+  id: string;
+  resourceKind: "edgeBundle";
+  path: string;
+}
+
+export interface UboaArtifactReference {
+  id: string;
+  resourceKind: UboaArtifactResourceKind;
+}
+
+export type UboaApiSchemaFormat = "oneapi";
+
+export interface UboaApiSchemaArtifact {
+  id: string;
+  resourceKind: "apiSchema";
+  path: string;
+  schemaFormat: UboaApiSchemaFormat;
+  describes?: UboaArtifactReference;
+}
+
+export type UboaArtifact =
+  | UboaAssetsArtifact
+  | UboaServerFunctionArtifact
+  | UboaEdgeBundleArtifact
+  | UboaApiSchemaArtifact;
+
+export interface AdapterBuildResult {
+  outputDir: string;
+  routes: UboaRoute[];
+  middleware: UboaMiddleware[];
+  artifacts: UboaArtifact[];
+  capabilities: UboaCapabilities;
+  warnings: string[];
+}
+
+export interface EmitUboaOptions extends UnioEvjsAdapterOptions {
+  clientManifest: ClientManifest;
+  serverManifest?: ServerManifest;
+}
+
+export type BuildOptions = EmitUboaOptions;

package/src/utils.ts

@@ -0,0 +1,61 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export async function pathExists(filePath: string): Promise<boolean> {
+  return fs.access(filePath).then(
+    () => true,
+    () => false,
+  );
+}
+
+export async function readJson(filePath: string): Promise<unknown> {
+  return JSON.parse(await fs.readFile(filePath, "utf8"));
+}
+
+export async function writeJson(filePath: string, value: unknown): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+export function toPosix(filePath: string): string {
+  return filePath.split(path.sep).join("/");
+}
+
+export function normalizeRoutePath(routePath: string): string {
+  if (!routePath || routePath === "/") return "/";
+  if (routePath === "*") return "/:path*";
+
+  const withLeadingSlash = routePath.startsWith("/")
+    ? routePath
+    : `/${routePath}`;
+
+  return withLeadingSlash
+    .split("/")
+    .map((segment) => {
+      if (segment === "*") return ":path*";
+      if (segment.startsWith("$") && segment.length > 1) {
+        return `:${segment.slice(1)}`;
+      }
+      return segment;
+    })
+    .join("/")
+    .replace(/\/+/g, "/");
+}
+
+export function routeId(prefix: string, routePath: string): string {
+  const slug = routePath
+    .replace(/^\/+/, "")
+    .replace(/[:*$]+/g, "")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+  return slug ? `${prefix}-${slug}` : `${prefix}-index`;
+}

package/src/validate.ts

@@ -0,0 +1,250 @@
+import path from "node:path";
+
+import type {
+  UboaArtifactReference,
+  UboaArtifactResourceKind,
+  UboaRoute,
+  ValidationResult,
+} from "./types.js";
+import { isRecord, pathExists, readJson } from "./utils.js";
+
+const ARTIFACT_RESOURCE_KINDS: UboaArtifactResourceKind[] = [
+  "assets",
+  "serverFunction",
+  "edgeBundle",
+  "apiSchema",
+];
+
+interface ValidArtifact {
+  id: string;
+  resourceKind: UboaArtifactResourceKind;
+  path: string;
+  absolutePath: string;
+  value: Record<string, unknown>;
+}
+
+function artifactKey(resourceKind: string, id: string): string {
+  return `${resourceKind}:${id}`;
+}
+
+function isArtifactResourceKind(
+  value: unknown,
+): value is UboaArtifactResourceKind {
+  return (
+    typeof value === "string" &&
+    ARTIFACT_RESOURCE_KINDS.includes(value as UboaArtifactResourceKind)
+  );
+}
+
+function isSafeRelativePath(value: string): boolean {
+  if (!value) return false;
+  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return false;
+  return !value.split(/[\\/]+/).includes("..");
+}
+
+function resolveArtifactPath(
+  root: string,
+  artifactPath: string,
+  artifactId: string,
+  errors: string[],
+): string | undefined {
+  if (!isSafeRelativePath(artifactPath)) {
+    errors.push(
+      `Artifact ${artifactId} path must stay within .unio/output: ${artifactPath}`,
+    );
+    return undefined;
+  }
+
+  return path.resolve(root, artifactPath);
+}
+
+function validateArtifactReference(
+  value: unknown,
+  label: string,
+  errors: string[],
+): UboaArtifactReference | undefined {
+  if (!isRecord(value)) {
+    errors.push(`${label} must be an object`);
+    return undefined;
+  }
+
+  const { id, resourceKind } = value;
+  if (typeof id !== "string" || id.length === 0) {
+    errors.push(`${label}.id must be a non-empty string`);
+    return undefined;
+  }
+  if (!isArtifactResourceKind(resourceKind)) {
+    errors.push(
+      `${label}.resourceKind must be one of ${ARTIFACT_RESOURCE_KINDS.join(", ")}`,
+    );
+    return undefined;
+  }
+
+  return { id, resourceKind };
+}
+
+function validateArtifactBase(
+  root: string,
+  value: unknown,
+  index: number,
+  errors: string[],
+): ValidArtifact | undefined {
+  const label = `artifacts[${index}]`;
+
+  if (!isRecord(value)) {
+    errors.push(`${label} must be an object`);
+    return undefined;
+  }
+
+  const { id, resourceKind, path: artifactPath } = value;
+  if (typeof id !== "string" || id.length === 0) {
+    errors.push(`${label}.id must be a non-empty string`);
+    return undefined;
+  }
+  if (!isArtifactResourceKind(resourceKind)) {
+    errors.push(
+      `${label}.resourceKind must be one of ${ARTIFACT_RESOURCE_KINDS.join(", ")}`,
+    );
+    return undefined;
+  }
+  if (typeof artifactPath !== "string" || artifactPath.length === 0) {
+    errors.push(`${label}.path must be a non-empty string`);
+    return undefined;
+  }
+
+  const absolutePath = resolveArtifactPath(root, artifactPath, id, errors);
+  if (!absolutePath) return undefined;
+
+  return {
+    id,
+    resourceKind,
+    path: artifactPath,
+    absolutePath,
+    value,
+  };
+}
+
+async function readRequiredJson<T>(
+  root: string,
+  file: string,
+  errors: string[],
+): Promise<T | undefined> {
+  const filePath = path.join(root, file);
+  if (!(await pathExists(filePath))) {
+    errors.push(`Missing ${file}`);
+    return undefined;
+  }
+
+  try {
+    return await readJson(filePath) as T;
+  } catch (error) {
+    errors.push(`Invalid JSON in ${file}: ${(error as Error).message}`);
+    return undefined;
+  }
+}
+
+export async function validate(options: {
+  cwd: string;
+  outputDir?: string;
+}): Promise<ValidationResult> {
+  const root = path.resolve(options.cwd, options.outputDir ?? ".unio/output");
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!(await pathExists(root))) {
+    return {
+      valid: false,
+      errors: [`Missing output directory: ${root}`],
+      warnings,
+    };
+  }
+
+  await readRequiredJson(root, "unio.json", errors);
+  const routes = await readRequiredJson<UboaRoute[]>(root, "routes.json", errors);
+  await readRequiredJson(root, "middleware.json", errors);
+  const artifactsManifest = await readRequiredJson<{ artifacts?: unknown }>(
+    root,
+    "artifacts.json",
+    errors,
+  );
+
+  if (routes && !Array.isArray(routes)) {
+    errors.push("routes.json must be an array");
+  }
+
+  const artifacts = artifactsManifest?.artifacts;
+  if (artifactsManifest && !Array.isArray(artifacts)) {
+    errors.push("artifacts.json artifacts must be an array");
+  }
+
+  const validArtifacts = Array.isArray(artifacts)
+    ? artifacts
+        .map((artifact, index) =>
+          validateArtifactBase(root, artifact, index, errors)
+        )
+        .filter((artifact): artifact is ValidArtifact => Boolean(artifact))
+    : [];
+  const artifactKeys = new Set(
+    validArtifacts.map((artifact) =>
+      artifactKey(artifact.resourceKind, artifact.id)
+    ),
+  );
+
+  for (const artifact of validArtifacts) {
+    if (!(await pathExists(artifact.absolutePath))) {
+      errors.push(`Artifact path does not exist: ${artifact.path}`);
+      continue;
+    }
+
+    if (artifact.resourceKind === "serverFunction") {
+      const serverFunctionJson = await readRequiredJson<{ entry?: string }>(
+        artifact.absolutePath,
+        "serverFunction.json",
+        errors,
+      );
+      if (serverFunctionJson?.entry) {
+        const entryPath = path.join(
+          artifact.absolutePath,
+          serverFunctionJson.entry,
+        );
+        if (!(await pathExists(entryPath))) {
+          errors.push(
+            `serverFunction ${artifact.id} entry does not exist: ${serverFunctionJson.entry}`,
+          );
+        }
+      }
+    }
+
+    if (artifact.resourceKind === "apiSchema") {
+      if (artifact.value.schemaFormat !== "oneapi") {
+        errors.push(`apiSchema ${artifact.id} schemaFormat must be "oneapi"`);
+      }
+
+      if (artifact.value.describes !== undefined) {
+        const reference = validateArtifactReference(
+          artifact.value.describes,
+          `apiSchema ${artifact.id} describes`,
+          errors,
+        );
+        if (
+          reference &&
+          !artifactKeys.has(artifactKey(reference.resourceKind, reference.id))
+        ) {
+          const missingArtifact = artifactKey(
+            reference.resourceKind,
+            reference.id,
+          );
+          errors.push(
+            `apiSchema ${artifact.id} describes missing artifact: ${missingArtifact}`,
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}