bazis 0.96.1

package/library/ui/compiler/contracts-v1.ts

@@ -0,0 +1,25 @@
+import type { OpenApiSchema } from "../../openapi";
+import type { CompiledUiSurfaceV1 } from "../compiled-v1";
+import type { UiDiagnosticV1 } from "../diagnostics-v1";
+import type { UiProfileV1 } from "../profile-v1";
+
+export interface CompileUiSurfaceV1Options {
+  readonly surface: string;
+  readonly profiles: readonly UiProfileV1[];
+  readonly openApi: OpenApiSchema;
+  readonly links: {
+    readonly openapi: string;
+    readonly session?: string;
+  };
+}
+
+export type CompileUiSurfaceV1Result =
+  | {
+      readonly ok: true;
+      readonly document: CompiledUiSurfaceV1;
+      readonly diagnostics: readonly UiDiagnosticV1[];
+    }
+  | {
+      readonly ok: false;
+      readonly diagnostics: readonly UiDiagnosticV1[];
+    };

package/library/ui/compiler/index.ts

@@ -0,0 +1,12 @@
+export { compileUiSurfaceV1 } from "./compileUiSurfaceV1";
+export { indexOpenApiV1 } from "./openApiIndex";
+export type {
+  CompileUiSurfaceV1Options,
+  CompileUiSurfaceV1Result,
+} from "./contracts-v1";
+export type {
+  UiOpenApiHttpMethodV1,
+  UiOpenApiIndexResultV1,
+  UiOpenApiIndexV1,
+  UiOpenApiOperationV1,
+} from "./openApiIndex";

package/library/ui/compiler/openApiIndex.ts

@@ -0,0 +1,246 @@
+import type { OpenApiSchema } from "../../openapi";
+import { uiDiagnosticV1, type UiDiagnosticV1 } from "../diagnostics-v1";
+
+export type UiOpenApiHttpMethodV1 = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface UiOpenApiOperationV1 {
+  readonly operationId: string;
+  readonly method: UiOpenApiHttpMethodV1;
+  readonly path: string;
+  readonly operation: Readonly<Record<string, unknown>>;
+  readonly requestSchema?: OpenApiSchema;
+  readonly responseSchema?: OpenApiSchema;
+}
+
+export interface UiOpenApiIndexV1 {
+  readonly operations: ReadonlyMap<string, UiOpenApiOperationV1>;
+  readonly schemas: Readonly<Record<string, OpenApiSchema>>;
+}
+
+export interface UiOpenApiIndexResultV1 {
+  readonly index: UiOpenApiIndexV1;
+  readonly diagnostics: readonly UiDiagnosticV1[];
+}
+
+const METHODS: Readonly<Record<string, UiOpenApiHttpMethodV1>> = Object.freeze({
+  get: "GET",
+  post: "POST",
+  put: "PUT",
+  patch: "PATCH",
+  delete: "DELETE",
+});
+
+export function indexOpenApiV1(document: OpenApiSchema): UiOpenApiIndexResultV1 {
+  const diagnostics: UiDiagnosticV1[] = [];
+  const operations = new Map<string, UiOpenApiOperationV1>();
+  const paths = asRecord(document["paths"]);
+
+  for (const path of Object.keys(paths).sort()) {
+    const pathItem = asRecord(paths[path]);
+    for (const [methodName, method] of Object.entries(METHODS)) {
+      const operation = asRecord(pathItem[methodName]);
+      if (Object.keys(operation).length === 0) {
+        continue;
+      }
+      const operationId = operation["operationId"];
+      if (typeof operationId !== "string" || operationId.trim().length === 0) {
+        continue;
+      }
+      if (operations.has(operationId)) {
+        diagnostics.push(uiDiagnosticV1(
+          "error",
+          "UIV1_OPENAPI_DUPLICATE_OPERATION_ID",
+          "OpenAPI operationId " + operationId + " is declared more than once.",
+          { path: path + "." + methodName },
+        ));
+        continue;
+      }
+
+      operations.set(operationId, Object.freeze({
+        operationId,
+        method,
+        path,
+        operation,
+        requestSchema: requestSchemaOf(operation),
+        responseSchema: responseSchemaOf(operation),
+      }));
+    }
+  }
+
+  return {
+    index: Object.freeze({
+      operations,
+      schemas: schemasOf(document),
+    }),
+    diagnostics: Object.freeze(diagnostics),
+  };
+}
+
+export function resolveSchemaV1(
+  index: UiOpenApiIndexV1,
+  schema: OpenApiSchema | undefined,
+): OpenApiSchema | undefined {
+  if (schema === undefined) {
+    return undefined;
+  }
+  const ref = schema["$ref"];
+  if (typeof ref !== "string") {
+    return schema;
+  }
+  const prefix = "#/components/schemas/";
+  return ref.startsWith(prefix) ? index.schemas[ref.slice(prefix.length)] : undefined;
+}
+
+export function responseEntitySchemaV1(
+  index: UiOpenApiIndexV1,
+  operation: UiOpenApiOperationV1 | undefined,
+): OpenApiSchema | undefined {
+  const response = resolveSchemaV1(index, operation?.responseSchema);
+  if (response === undefined) {
+    return undefined;
+  }
+
+  if (response["type"] === "array") {
+    const items = asRecord(response["items"]);
+    return Object.keys(items).length > 0 ? resolveSchemaV1(index, items) : undefined;
+  }
+
+  const properties = asRecord(response["properties"]);
+  for (const collectionField of ["data", "items"] as const) {
+    const collection = asRecord(properties[collectionField]);
+    const items = asRecord(collection["items"]);
+    if (Object.keys(items).length > 0) {
+      return resolveSchemaV1(index, items);
+    }
+  }
+  return response;
+}
+
+export function requestEntitySchemaV1(
+  index: UiOpenApiIndexV1,
+  operation: UiOpenApiOperationV1 | undefined,
+): OpenApiSchema | undefined {
+  return resolveSchemaV1(index, operation?.requestSchema);
+}
+
+export function schemaPropertyNamesV1(schema: OpenApiSchema | undefined): ReadonlySet<string> {
+  return new Set(Object.keys(asRecord(schema?.["properties"])));
+}
+
+export function listFilterCapabilitiesV1(
+  operation: UiOpenApiOperationV1 | undefined,
+): ReadonlyMap<string, ReadonlySet<string>> {
+  const filters = new Map<string, Set<string>>();
+  for (const parameter of operationParameters(operation)) {
+    if (parameter["in"] !== "query" || typeof parameter["name"] !== "string") {
+      continue;
+    }
+    const match = /^filter\[([^\]]+)\]\[([^\]]+)\]$/.exec(parameter["name"]);
+    if (match === null) {
+      continue;
+    }
+    const field = match[1] as string;
+    const operator = match[2] as string;
+    const operators = filters.get(field) ?? new Set<string>();
+    operators.add(operator);
+    filters.set(field, operators);
+  }
+  const declared = hasQueryParameterV1(operation, "filter")
+    ? asRecord(operation?.operation["x-bazis-list-filters"])
+    : {};
+  for (const [field, value] of Object.entries(declared)) {
+    if (!Array.isArray(value)) {
+      continue;
+    }
+    const operators = filters.get(field) ?? new Set<string>();
+    for (const operator of value) {
+      if (typeof operator === "string" && operator.trim().length > 0) {
+        operators.add(operator.trim());
+      }
+    }
+    if (operators.size > 0) {
+      filters.set(field, operators);
+    }
+  }
+  return filters;
+}
+
+export function listMaxPageSizeV1(operation: UiOpenApiOperationV1 | undefined): number | undefined {
+  const maxima: number[] = [];
+  for (const parameter of operationParameters(operation)) {
+    if (
+      parameter["in"] !== "query"
+      || (parameter["name"] !== "page[size]" && parameter["name"] !== "limit")
+    ) {
+      continue;
+    }
+    const maximum = asRecord(parameter["schema"])["maximum"];
+    if (typeof maximum === "number" && Number.isFinite(maximum)) {
+      maxima.push(maximum);
+    }
+  }
+  return maxima.length === 0 ? undefined : Math.min(...maxima);
+}
+
+export function hasQueryParameterV1(
+  operation: UiOpenApiOperationV1 | undefined,
+  name: string,
+): boolean {
+  return operationParameters(operation).some(
+    (parameter) => parameter["in"] === "query" && parameter["name"] === name,
+  );
+}
+
+function requestSchemaOf(operation: Readonly<Record<string, unknown>>): OpenApiSchema | undefined {
+  const requestBody = asRecord(operation["requestBody"]);
+  return schemaFromContent(requestBody["content"]);
+}
+
+function responseSchemaOf(operation: Readonly<Record<string, unknown>>): OpenApiSchema | undefined {
+  const responses = asRecord(operation["responses"]);
+  const successCode = Object.keys(responses)
+    .filter((code) => /^2[0-9][0-9]$/.test(code))
+    .sort()[0];
+  if (successCode === undefined) {
+    return undefined;
+  }
+  const response = asRecord(responses[successCode]);
+  return schemaFromContent(response["content"]);
+}
+
+function schemaFromContent(contentValue: unknown): OpenApiSchema | undefined {
+  const content = asRecord(contentValue);
+  const mediaType = asRecord(content["application/json"]);
+  const schema = asRecord(mediaType["schema"]);
+  return Object.keys(schema).length === 0 ? undefined : schema;
+}
+
+function operationParameters(
+  operation: UiOpenApiOperationV1 | undefined,
+): readonly Readonly<Record<string, unknown>>[] {
+  const parameters = operation?.operation["parameters"];
+  if (!Array.isArray(parameters)) {
+    return [];
+  }
+  return parameters.map(asRecord).filter((parameter) => Object.keys(parameter).length > 0);
+}
+
+function schemasOf(document: OpenApiSchema): Readonly<Record<string, OpenApiSchema>> {
+  const components = asRecord(document["components"]);
+  const schemas = asRecord(components["schemas"]);
+  const out: Record<string, OpenApiSchema> = {};
+  for (const [name, schema] of Object.entries(schemas)) {
+    if (isRecord(schema)) {
+      out[name] = schema;
+    }
+  }
+  return Object.freeze(out);
+}
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> {
+  return isRecord(value) ? value : {};
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/library/ui/defineUiProfile.ts

@@ -0,0 +1,340 @@
+import {
+  UI_PROFILE_V1_API_VERSION,
+  UI_PROFILE_V1_KIND,
+  type UiActionProfileV1,
+  type UiCustomPageProfileV1,
+  type UiFieldProfileV1,
+  type UiOperationRefV1,
+  type UiProfileV1,
+  type UiResourceProfileV1,
+  type UiSchemaElementV1,
+} from "./profile-v1";
+import { normalizeUiJsonObject } from "./serialization";
+
+const ACTION_PLACEMENTS = new Set([
+  "list.header",
+  "list.row",
+  "detail.header",
+]);
+const ACTION_INTENTS = new Set(["primary", "secondary", "danger", "neutral"]);
+const ACTION_REFRESH_MODES = new Set(["none", "resource", "page", "all"]);
+
+export function defineUiProfile(profile: UiProfileV1): UiProfileV1 {
+  validateProfile(profile);
+  return normalizeUiJsonObject(profile, "uiProfile") as unknown as UiProfileV1;
+}
+
+function validateProfile(profile: UiProfileV1): void {
+  assertKnownKeys(profile, ["apiVersion", "kind", "metadata", "spec"], "uiProfile");
+  if (profile.apiVersion !== UI_PROFILE_V1_API_VERSION) {
+    throw new TypeError("uiProfile.apiVersion must be " + UI_PROFILE_V1_API_VERSION + ".");
+  }
+  if (profile.kind !== UI_PROFILE_V1_KIND) {
+    throw new TypeError("uiProfile.kind must be " + UI_PROFILE_V1_KIND + ".");
+  }
+
+  requiredText(profile.metadata.name, "uiProfile.metadata.name");
+  requiredText(profile.metadata.surface, "uiProfile.metadata.surface");
+  requiredText(profile.metadata.owner, "uiProfile.metadata.owner");
+  assertKnownKeys(profile.metadata, ["name", "surface", "owner", "extensions"], "uiProfile.metadata");
+  assertKnownKeys(
+    profile.spec,
+    ["resources", "customPages", "requiredRendererCapabilities", "extensions"],
+    "uiProfile.spec",
+  );
+
+  for (let index = 0; index < profile.spec.resources.length; index += 1) {
+    validateResource(profile.spec.resources[index] as UiResourceProfileV1, "uiProfile.spec.resources[" + index + "]");
+  }
+  for (let index = 0; index < (profile.spec.customPages?.length ?? 0); index += 1) {
+    validateCustomPage(
+      profile.spec.customPages?.[index] as UiCustomPageProfileV1,
+      "uiProfile.spec.customPages[" + index + "]",
+    );
+  }
+  for (let index = 0; index < (profile.spec.requiredRendererCapabilities?.length ?? 0); index += 1) {
+    requiredText(
+      profile.spec.requiredRendererCapabilities?.[index] as string,
+      "uiProfile.spec.requiredRendererCapabilities[" + index + "]",
+    );
+  }
+}
+
+function validateCustomPage(page: UiCustomPageProfileV1, path: string): void {
+  requiredText(page.id, path + ".id");
+  requiredText(page.title, path + ".title");
+  validateNavigation(page.navigation, path + ".navigation");
+  switch (page.kind) {
+    case "feature":
+      assertKnownKeys(page, ["kind", "id", "title", "navigation", "renderer"], path);
+      requiredText(page.renderer, path + ".renderer");
+      return;
+    case "settings":
+      assertKnownKeys(page, ["kind", "id", "title", "navigation", "operations", "form"], path);
+      assertKnownKeys(page.operations, ["read", "update"], path + ".operations");
+      validateOperation(page.operations.read, path + ".operations.read");
+      validateOperation(page.operations.update, path + ".operations.update");
+      if (page.form !== undefined) {
+        assertKnownKeys(page.form, ["title", "uiSchema"], path + ".form");
+        optionalText(page.form.title, path + ".form.title");
+        if (page.form.uiSchema !== undefined) {
+          validateUiSchema(page.form.uiSchema, path + ".form.uiSchema");
+        }
+      }
+      return;
+    case "document":
+      assertKnownKeys(page, ["kind", "id", "title", "navigation", "operation"], path);
+      validateOperation(page.operation, path + ".operation");
+      return;
+    case "dashboard": {
+      assertKnownKeys(page, ["kind", "id", "title", "navigation", "blocks"], path);
+      if (page.blocks.length === 0) {
+        throw new TypeError(path + ".blocks must contain at least one block.");
+      }
+      const ids = new Set<string>();
+      for (let index = 0; index < page.blocks.length; index += 1) {
+        const block = page.blocks[index] as (typeof page.blocks)[number];
+        const blockPath = path + ".blocks[" + index + "]";
+        assertKnownKeys(block, ["id", "kind", "title", "operation"], blockPath);
+        requiredText(block.id, blockPath + ".id");
+        if (ids.has(block.id)) {
+          throw new TypeError(path + ".blocks must not contain duplicate id " + block.id + ".");
+        }
+        ids.add(block.id);
+        if (block.kind !== "metric" && block.kind !== "document") {
+          throw new TypeError(blockPath + ".kind is not supported.");
+        }
+        requiredText(block.title, blockPath + ".title");
+        validateOperation(block.operation, blockPath + ".operation");
+      }
+      return;
+    }
+    default:
+      throw new TypeError(path + ".kind is not a supported custom page kind.");
+  }
+}
+
+function validateNavigation(navigation: UiCustomPageProfileV1["navigation"], path: string): void {
+  if (navigation === undefined) {
+    return;
+  }
+  assertKnownKeys(navigation, ["title", "group", "icon", "order", "hidden"], path);
+  optionalText(navigation.title, path + ".title");
+  optionalText(navigation.group, path + ".group");
+  optionalText(navigation.icon, path + ".icon");
+  optionalInteger(navigation.order, path + ".order");
+}
+
+function validateResource(resource: UiResourceProfileV1, path: string): void {
+  assertKnownKeys(
+    resource,
+    ["id", "title", "singularTitle", "keyField", "navigation", "operations", "list", "detail", "forms", "actions", "extensions"],
+    path,
+  );
+  requiredText(resource.id, path + ".id");
+  optionalText(resource.title, path + ".title");
+  optionalText(resource.singularTitle, path + ".singularTitle");
+  optionalText(resource.keyField, path + ".keyField");
+  optionalText(resource.navigation?.title, path + ".navigation.title");
+  optionalText(resource.navigation?.group, path + ".navigation.group");
+  optionalText(resource.navigation?.icon, path + ".navigation.icon");
+  if (resource.navigation !== undefined) {
+    assertKnownKeys(
+      resource.navigation,
+      ["title", "group", "icon", "order", "hidden"],
+      path + ".navigation",
+    );
+    optionalInteger(resource.navigation.order, path + ".navigation.order");
+  }
+
+  const operations = resource.operations;
+  if (operations !== undefined) {
+    assertKnownKeys(operations, ["list", "read", "create", "update", "delete"], path + ".operations");
+    validateOperation(operations.list, path + ".operations.list");
+    validateOperation(operations.read, path + ".operations.read");
+    validateOperation(operations.create, path + ".operations.create");
+    validateOperation(operations.update, path + ".operations.update");
+    validateOperation(operations.delete, path + ".operations.delete");
+  }
+
+  validateFields(resource.list?.columns, path + ".list.columns");
+  validateFields(resource.list?.selectionFields, path + ".list.selectionFields");
+  optionalText(resource.list?.defaultSort, path + ".list.defaultSort");
+  optionalPositiveInteger(resource.list?.pageSize, path + ".list.pageSize");
+  if (resource.list !== undefined) {
+    assertKnownKeys(
+      resource.list,
+      ["title", "columns", "selectionFields", "defaultSort", "pageSize"],
+      path + ".list",
+    );
+    optionalText(resource.list.title, path + ".list.title");
+  }
+
+  if (resource.detail !== undefined) {
+    assertKnownKeys(
+      resource.detail,
+      ["titleField", "subtitleField", "statusField", "sections"],
+      path + ".detail",
+    );
+    optionalText(resource.detail.titleField, path + ".detail.titleField");
+    optionalText(resource.detail.subtitleField, path + ".detail.subtitleField");
+    optionalText(resource.detail.statusField, path + ".detail.statusField");
+  }
+  for (let index = 0; index < (resource.detail?.sections?.length ?? 0); index += 1) {
+    const section = resource.detail?.sections?.[index];
+    if (section === undefined) {
+      continue;
+    }
+    assertKnownKeys(section, ["id", "title", "fields"], path + ".detail.sections[" + index + "]");
+    requiredText(section.id, path + ".detail.sections[" + index + "].id");
+    requiredText(section.title, path + ".detail.sections[" + index + "].title");
+    validateFields(section.fields, path + ".detail.sections[" + index + "].fields");
+  }
+
+  if (resource.forms?.create?.uiSchema !== undefined) {
+    validateUiSchema(resource.forms.create.uiSchema, path + ".forms.create.uiSchema");
+  }
+  if (resource.forms?.edit?.uiSchema !== undefined) {
+    validateUiSchema(resource.forms.edit.uiSchema, path + ".forms.edit.uiSchema");
+  }
+  if (resource.forms !== undefined) {
+    assertKnownKeys(resource.forms, ["create", "edit"], path + ".forms");
+  }
+  if (resource.forms?.create !== undefined) {
+    assertKnownKeys(resource.forms.create, ["title", "uiSchema"], path + ".forms.create");
+    optionalText(resource.forms.create.title, path + ".forms.create.title");
+  }
+  if (resource.forms?.edit !== undefined) {
+    assertKnownKeys(resource.forms.edit, ["title", "uiSchema"], path + ".forms.edit");
+    optionalText(resource.forms.edit.title, path + ".forms.edit.title");
+  }
+
+  for (let index = 0; index < (resource.actions?.length ?? 0); index += 1) {
+    validateAction(resource.actions?.[index] as UiActionProfileV1, path + ".actions[" + index + "]");
+  }
+}
+
+function validateOperation(operation: UiOperationRefV1 | undefined, path: string): void {
+  if (operation !== undefined) {
+    assertKnownKeys(operation, ["operationId"], path);
+    requiredText(operation.operationId, path + ".operationId");
+  }
+}
+
+function validateFields(fields: readonly UiFieldProfileV1[] | undefined, path: string): void {
+  for (let index = 0; index < (fields?.length ?? 0); index += 1) {
+    const field = fields?.[index] as UiFieldProfileV1;
+    requiredText(field, path + "[" + index + "]");
+  }
+}
+
+function validateAction(action: UiActionProfileV1, path: string): void {
+  assertKnownKeys(
+    action,
+    ["id", "title", "operation", "placements", "intent", "confirm", "refresh", "extensions"],
+    path,
+  );
+  requiredText(action.id, path + ".id");
+  requiredText(action.title, path + ".title");
+  validateOperation(action.operation, path + ".operation");
+  if (action.placements.length === 0) {
+    throw new TypeError(path + ".placements must contain at least one placement.");
+  }
+  const seenPlacements = new Set<string>();
+  for (const placement of action.placements) {
+    if (!ACTION_PLACEMENTS.has(placement)) {
+      throw new TypeError(path + ".placements contains unsupported placement " + placement + ".");
+    }
+    if (seenPlacements.has(placement)) {
+      throw new TypeError(path + ".placements must not contain duplicate placement " + placement + ".");
+    }
+    seenPlacements.add(placement);
+  }
+  if (action.intent !== undefined && !ACTION_INTENTS.has(action.intent)) {
+    throw new TypeError(path + ".intent contains unsupported intent " + action.intent + ".");
+  }
+  if (action.refresh !== undefined && !ACTION_REFRESH_MODES.has(action.refresh)) {
+    throw new TypeError(path + ".refresh contains unsupported mode " + action.refresh + ".");
+  }
+  optionalText(action.confirm, path + ".confirm");
+  if (action.intent === "danger" && action.confirm === undefined) {
+    throw new TypeError(path + ".confirm is required for a danger action.");
+  }
+}
+
+function validateUiSchema(element: UiSchemaElementV1, path: string): void {
+  switch (element.type) {
+    case "Control":
+      assertKnownKeys(element, ["type", "scope", "label", "options"], path);
+      requiredText(element.scope, path + ".scope");
+      return;
+    case "Label":
+      assertKnownKeys(element, ["type", "text"], path);
+      requiredText(element.text, path + ".text");
+      return;
+    case "VerticalLayout":
+    case "HorizontalLayout":
+    case "Group":
+    case "Category":
+      assertKnownKeys(
+        element,
+        element.type === "Category"
+          ? ["type", "label", "elements"]
+          : ["type", "label", "elements"],
+        path,
+      );
+      if (element.type === "Category") {
+        requiredText(element.label, path + ".label");
+      }
+      for (let index = 0; index < element.elements.length; index += 1) {
+        validateUiSchema(element.elements[index] as UiSchemaElementV1, path + ".elements[" + index + "]");
+      }
+      return;
+    case "Categorization":
+      assertKnownKeys(element, ["type", "elements"], path);
+      for (let index = 0; index < element.elements.length; index += 1) {
+        validateUiSchema(element.elements[index] as UiSchemaElementV1, path + ".elements[" + index + "]");
+      }
+      return;
+    default:
+      throw new TypeError(path + ".type is not a supported UI Schema element.");
+  }
+}
+
+function requiredText(value: string, path: string): string {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new TypeError(path + " must be a non-empty string.");
+  }
+  if (normalized !== value) {
+    throw new TypeError(path + " must not contain surrounding whitespace.");
+  }
+  return normalized;
+}
+
+function optionalText(value: string | undefined, path: string): void {
+  if (value !== undefined) {
+    requiredText(value, path);
+  }
+}
+
+function optionalPositiveInteger(value: number | undefined, path: string): void {
+  if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
+    throw new TypeError(path + " must be a positive integer.");
+  }
+}
+
+function optionalInteger(value: number | undefined, path: string): void {
+  if (value !== undefined && !Number.isInteger(value)) {
+    throw new TypeError(path + " must be an integer.");
+  }
+}
+
+function assertKnownKeys(value: object, allowed: readonly string[], path: string): void {
+  const known = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!known.has(key)) {
+      throw new TypeError(path + "." + key + " is not part of UiProfileV1.");
+    }
+  }
+}

package/library/ui/diagnostics-v1.ts

@@ -0,0 +1,33 @@
+export type UiDiagnosticSeverityV1 = "error" | "warning" | "info";
+
+export interface UiDiagnosticV1 {
+  readonly severity: UiDiagnosticSeverityV1;
+  readonly code: string;
+  readonly message: string;
+  readonly profile?: string;
+  readonly resource?: string;
+  readonly path?: string;
+  readonly source?: string;
+}
+
+export function uiDiagnosticV1(
+  severity: UiDiagnosticSeverityV1,
+  code: string,
+  message: string,
+  context: Omit<UiDiagnosticV1, "severity" | "code" | "message"> = {},
+): UiDiagnosticV1 {
+  return Object.freeze({
+    severity,
+    code: requiredText(code, "diagnostic.code"),
+    message: requiredText(message, "diagnostic.message"),
+    ...context,
+  });
+}
+
+function requiredText(value: string, field: string): string {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new TypeError(field + " must be a non-empty string.");
+  }
+  return normalized;
+}