@ankhorage/data-sources 1.0.0 → 2.0.0

package/src/openapi/operation.ts

@@ -0,0 +1,231 @@
+import type {
+  DataOperationConfig,
+  DataOperationIntent,
+  DataOperationParameter,
+  DataOperationParameterLocation,
+  DataOperationRequest,
+  DataOperationResponse,
+  DataSourceDiagnostic,
+  EndpointId,
+  OperationId,
+} from '@ankhorage/contracts/data';
+
+import { normalizeOpenApiSchema } from './schema';
+import type {
+  OpenApiHttpMethod,
+  OpenApiImportInput,
+  OpenApiMediaTypeObject,
+  OpenApiOperationObject,
+  OpenApiParameterObject,
+  OpenApiPathItemObject,
+  OpenApiRequestBodyObject,
+  OpenApiResponseObject,
+  OpenApiSchemaObject,
+} from './types';
+
+export function normalizeOpenApiOperationId(
+  method: OpenApiHttpMethod,
+  path: string,
+  operationId?: string,
+): OperationId {
+  const rawId = operationId ?? `${method}-${path}`;
+  const normalized = rawId
+    .replace(/\{([^}]+)\}/g, '$1')
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+  return normalized.length > 0 ? normalized : `${method}-root`;
+}
+
+export function normalizeOpenApiOperation(
+  input: OpenApiImportInput,
+  endpointId: EndpointId,
+  path: string,
+  method: OpenApiHttpMethod,
+  operation: OpenApiOperationObject,
+  pathItem: OpenApiPathItemObject,
+  operationIds: Set<OperationId>,
+  diagnostics: DataSourceDiagnostic[],
+): DataOperationConfig {
+  const operationId = resolveUniqueOperationId(
+    input.id,
+    endpointId,
+    method,
+    path,
+    operation.operationId,
+    operationIds,
+    diagnostics,
+  );
+  const parameters = normalizeOpenApiParameters(
+    [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])],
+    input.id,
+    endpointId,
+    operationId,
+    diagnostics,
+  );
+  return {
+    id: operationId,
+    endpointId,
+    name: operation.summary,
+    description: operation.description,
+    protocol: 'http',
+    intent: mapOpenApiMethodToIntent(method),
+    method: method.toUpperCase(),
+    path,
+    request: normalizeOpenApiRequest(operation.requestBody, parameters),
+    response: normalizeOpenApiResponse(operation.responses),
+    metadata: { deprecated: operation.deprecated ?? false, source: 'openapi' },
+  };
+}
+
+function resolveUniqueOperationId(
+  apiId: string,
+  endpointId: EndpointId,
+  method: OpenApiHttpMethod,
+  path: string,
+  operationId: string | undefined,
+  operationIds: Set<OperationId>,
+  diagnostics: DataSourceDiagnostic[],
+): OperationId {
+  const normalized = normalizeOpenApiOperationId(method, path, operationId);
+  if (!operationIds.has(normalized)) {
+    operationIds.add(normalized);
+    return normalized;
+  }
+
+  const uniqueId = findUniqueOperationId(normalized, operationIds);
+  operationIds.add(uniqueId);
+  diagnostics.push({
+    code: 'duplicate-operation-id',
+    apiId,
+    endpointId,
+    operationId: uniqueId,
+    message: `OpenAPI operation id '${normalized}' is duplicated. Normalized to '${uniqueId}'.`,
+    path: `paths.${path}.${method}.operationId`,
+    severity: 'warning',
+  });
+  return uniqueId;
+}
+
+function findUniqueOperationId(
+  normalized: OperationId,
+  operationIds: Set<OperationId>,
+): OperationId {
+  let suffix = 2;
+  let candidate: OperationId = `${normalized}-${suffix}`;
+  while (operationIds.has(candidate)) {
+    suffix += 1;
+    candidate = `${normalized}-${suffix}`;
+  }
+  return candidate;
+}
+
+function normalizeOpenApiParameters(
+  parameters: readonly OpenApiParameterObject[],
+  apiId: string,
+  endpointId: EndpointId,
+  operationId: OperationId,
+  diagnostics: DataSourceDiagnostic[],
+): readonly DataOperationParameter[] | undefined {
+  if (parameters.length === 0) return undefined;
+  return parameters.flatMap((parameter) =>
+    normalizeOpenApiParameter(parameter, apiId, endpointId, operationId, diagnostics),
+  );
+}
+
+function normalizeOpenApiParameter(
+  parameter: OpenApiParameterObject,
+  apiId: string,
+  endpointId: EndpointId,
+  operationId: OperationId,
+  diagnostics: DataSourceDiagnostic[],
+): readonly DataOperationParameter[] {
+  const location = normalizeParameterLocation(parameter.in);
+  if (location !== undefined) {
+    return [
+      {
+        name: parameter.name,
+        location,
+        required: parameter.required,
+        description: parameter.description,
+        schema:
+          parameter.schema === undefined ? undefined : normalizeOpenApiSchema(parameter.schema),
+      },
+    ];
+  }
+  diagnostics.push({
+    code: 'invalid-config',
+    apiId,
+    endpointId,
+    operationId,
+    message: `OpenAPI parameter '${parameter.name}' uses unsupported location '${parameter.in}'.`,
+    path: `paths.${endpointId}.parameters.${parameter.name}`,
+    severity: 'warning',
+  });
+  return [];
+}
+
+function normalizeParameterLocation(location: string): DataOperationParameterLocation | undefined {
+  if (
+    location === 'cookie' ||
+    location === 'header' ||
+    location === 'path' ||
+    location === 'query'
+  ) {
+    return location;
+  }
+  return undefined;
+}
+
+function normalizeOpenApiRequest(
+  requestBody: OpenApiRequestBodyObject | undefined,
+  parameters: readonly DataOperationParameter[] | undefined,
+): DataOperationRequest | undefined {
+  const content = firstContentEntry(requestBody?.content);
+  if (requestBody === undefined && parameters === undefined) return undefined;
+  return {
+    contentType: content?.contentType,
+    parameters,
+    schema: content?.schema === undefined ? undefined : normalizeOpenApiSchema(content.schema),
+  };
+}
+
+function normalizeOpenApiResponse(
+  responses: Readonly<Record<string, OpenApiResponseObject>> | undefined,
+): DataOperationResponse | undefined {
+  const selected = chooseResponseEntry(responses);
+  if (selected === undefined) return undefined;
+  const [status, response] = selected;
+  const content = firstContentEntry(response.content);
+  return {
+    status,
+    contentType: content?.contentType,
+    description: response.description,
+    schema: content?.schema === undefined ? undefined : normalizeOpenApiSchema(content.schema),
+  };
+}
+
+function chooseResponseEntry(
+  responses: Readonly<Record<string, OpenApiResponseObject>> | undefined,
+): readonly [string, OpenApiResponseObject] | undefined {
+  if (responses === undefined) return undefined;
+  const entries = Object.entries(responses);
+  return entries.find(([status]) => status.startsWith('2')) ?? entries[0];
+}
+
+function firstContentEntry(
+  content: Readonly<Record<string, OpenApiMediaTypeObject>> | undefined,
+): { readonly contentType: string; readonly schema?: OpenApiSchemaObject } | undefined {
+  const entry = content === undefined ? undefined : Object.entries(content)[0];
+  if (entry === undefined) return undefined;
+  const [contentType, media] = entry;
+  return { contentType, schema: media.schema };
+}
+
+function mapOpenApiMethodToIntent(method: OpenApiHttpMethod): DataOperationIntent {
+  if (method === 'get' || method === 'head') return 'read';
+  if (method === 'post') return 'create';
+  if (method === 'delete') return 'delete';
+  if (method === 'patch' || method === 'put') return 'update';
+  return 'action';
+}

package/src/openapi/schema.ts

@@ -0,0 +1,127 @@
+import type {
+  DataSchema,
+  DataSchemaPrimitiveType,
+  DataSchemaRegistry,
+  DataSourceDiagnostic,
+} from '@ankhorage/contracts/data';
+
+import type { OpenApiSchemaObject } from './types';
+
+const DATA_SCHEMA_PRIMITIVES = [
+  'array',
+  'boolean',
+  'integer',
+  'null',
+  'number',
+  'object',
+  'string',
+] as const satisfies readonly DataSchemaPrimitiveType[];
+
+export function normalizeOpenApiSchema(schema: OpenApiSchemaObject): DataSchema {
+  return {
+    ref: normalizeOpenApiSchemaRef(schema.$ref),
+    type: normalizeSchemaType(schema.type),
+    title: schema.title,
+    description: schema.description,
+    enum: schema.enum,
+    const: schema.const,
+    default: schema.default,
+    format: schema.format,
+    nullable: schema.nullable,
+    required: schema.required,
+    properties: normalizeSchemaRecord(schema.properties),
+    additionalProperties: normalizeAdditionalProperties(schema.additionalProperties),
+    items: schema.items === undefined ? undefined : normalizeOpenApiSchema(schema.items),
+    allOf: normalizeSchemaList(schema.allOf),
+    anyOf: normalizeSchemaList(schema.anyOf),
+    oneOf: normalizeSchemaList(schema.oneOf),
+  };
+}
+
+export function normalizeOpenApiSchemas(
+  schemas: Readonly<Record<string, OpenApiSchemaObject>> | undefined,
+  apiId: string,
+  diagnostics: DataSourceDiagnostic[],
+): DataSchemaRegistry | undefined {
+  if (schemas === undefined) return undefined;
+  return Object.fromEntries(
+    Object.entries(schemas).map(([schemaId, schema]) => {
+      collectUnsupportedSchemaDiagnostics(
+        schema,
+        apiId,
+        `components.schemas.${schemaId}`,
+        diagnostics,
+      );
+      return [schemaId, normalizeOpenApiSchema(schema)];
+    }),
+  );
+}
+
+function normalizeOpenApiSchemaRef(ref: string | undefined): { readonly id: string } | undefined {
+  if (ref === undefined) return undefined;
+  const prefix = '#/components/schemas/';
+  return { id: ref.startsWith(prefix) ? ref.slice(prefix.length) : ref };
+}
+
+function normalizeSchemaRecord(
+  record: Readonly<Record<string, OpenApiSchemaObject>> | undefined,
+): Readonly<Record<string, DataSchema>> | undefined {
+  if (record === undefined) return undefined;
+  return Object.fromEntries(
+    Object.entries(record).map(([key, schema]) => [key, normalizeOpenApiSchema(schema)]),
+  );
+}
+
+function normalizeSchemaList(
+  list: readonly OpenApiSchemaObject[] | undefined,
+): readonly DataSchema[] | undefined {
+  return list?.map(normalizeOpenApiSchema);
+}
+
+function normalizeAdditionalProperties(
+  value: boolean | OpenApiSchemaObject | undefined,
+): boolean | DataSchema | undefined {
+  if (value === undefined || typeof value === 'boolean') return value;
+  return normalizeOpenApiSchema(value);
+}
+
+function normalizeSchemaType(
+  type: string | readonly string[] | undefined,
+): DataSchemaPrimitiveType | readonly DataSchemaPrimitiveType[] | undefined {
+  if (type === undefined) return undefined;
+  if (typeof type === 'string') return isDataSchemaPrimitive(type) ? type : undefined;
+  return type.filter(isDataSchemaPrimitive);
+}
+
+function isDataSchemaPrimitive(type: string): type is DataSchemaPrimitiveType {
+  return DATA_SCHEMA_PRIMITIVES.some((primitive) => primitive === type);
+}
+
+function collectUnsupportedSchemaDiagnostics(
+  schema: OpenApiSchemaObject,
+  apiId: string,
+  path: string,
+  diagnostics: DataSourceDiagnostic[],
+): void {
+  if (typeof schema.type === 'string' && !isDataSchemaPrimitive(schema.type)) {
+    diagnostics.push({
+      code: 'unsupported-schema',
+      apiId,
+      message: `OpenAPI schema type '${schema.type}' is not supported by the normalized schema model.`,
+      path: `${path}.type`,
+      severity: 'warning',
+    });
+  }
+
+  for (const [propertyName, propertySchema] of Object.entries(schema.properties ?? {})) {
+    collectUnsupportedSchemaDiagnostics(
+      propertySchema,
+      apiId,
+      `${path}.properties.${propertyName}`,
+      diagnostics,
+    );
+  }
+  if (schema.items !== undefined) {
+    collectUnsupportedSchemaDiagnostics(schema.items, apiId, `${path}.items`, diagnostics);
+  }
+}

package/src/openapi/types.ts

@@ -0,0 +1,93 @@
+import type { CredentialRef, DataContractValue } from '@ankhorage/contracts/data';
+
+export type OpenApiHttpMethod = 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put';
+
+export interface OpenApiServerObject {
+  readonly url: string;
+  readonly description?: string;
+}
+
+export interface OpenApiSchemaObject {
+  readonly $ref?: string;
+  readonly type?: string | readonly string[];
+  readonly title?: string;
+  readonly description?: string;
+  readonly enum?: readonly DataContractValue[];
+  readonly const?: DataContractValue;
+  readonly default?: DataContractValue;
+  readonly format?: string;
+  readonly nullable?: boolean;
+  readonly required?: readonly string[];
+  readonly properties?: Readonly<Record<string, OpenApiSchemaObject>>;
+  readonly additionalProperties?: boolean | OpenApiSchemaObject;
+  readonly items?: OpenApiSchemaObject;
+  readonly allOf?: readonly OpenApiSchemaObject[];
+  readonly anyOf?: readonly OpenApiSchemaObject[];
+  readonly oneOf?: readonly OpenApiSchemaObject[];
+}
+
+export interface OpenApiMediaTypeObject {
+  readonly schema?: OpenApiSchemaObject;
+}
+
+export interface OpenApiRequestBodyObject {
+  readonly description?: string;
+  readonly required?: boolean;
+  readonly content?: Readonly<Record<string, OpenApiMediaTypeObject>>;
+}
+
+export interface OpenApiResponseObject {
+  readonly description?: string;
+  readonly content?: Readonly<Record<string, OpenApiMediaTypeObject>>;
+}
+
+export interface OpenApiParameterObject {
+  readonly name: string;
+  readonly in: string;
+  readonly required?: boolean;
+  readonly description?: string;
+  readonly schema?: OpenApiSchemaObject;
+}
+
+export interface OpenApiOperationObject {
+  readonly operationId?: string;
+  readonly summary?: string;
+  readonly description?: string;
+  readonly deprecated?: boolean;
+  readonly parameters?: readonly OpenApiParameterObject[];
+  readonly requestBody?: OpenApiRequestBodyObject;
+  readonly responses?: Readonly<Record<string, OpenApiResponseObject>>;
+}
+
+export type OpenApiPathItemObject = Partial<Record<OpenApiHttpMethod, OpenApiOperationObject>> & {
+  readonly parameters?: readonly OpenApiParameterObject[];
+};
+
+export interface OpenApiComponentsObject {
+  readonly schemas?: Readonly<Record<string, OpenApiSchemaObject>>;
+  readonly securitySchemes?: Readonly<Record<string, DataContractValue>>;
+}
+
+export interface OpenApiDocumentObject {
+  readonly openapi?: string;
+  readonly info?: {
+    readonly title?: string;
+    readonly version?: string;
+    readonly description?: string;
+  };
+  readonly servers?: readonly OpenApiServerObject[];
+  readonly paths?: Readonly<Record<string, OpenApiPathItemObject>>;
+  readonly components?: OpenApiComponentsObject;
+}
+
+export interface OpenApiImportInput {
+  readonly id: string;
+  readonly document: OpenApiDocumentObject;
+  readonly baseUrl?: string;
+  readonly credential?: CredentialRef;
+  readonly documentId?: string;
+  readonly documentUrl?: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly metadata?: DataContractValue;
+}

package/src/packageInfo.ts

@@ -0,0 +1,50 @@
+import type {
+  ApiOrigin,
+  ApiProtocol,
+  DataSourceConfig,
+  DataSourceKind,
+} from '@ankhorage/contracts/data';
+
+export const DATA_SOURCES_PACKAGE_NAME = '@ankhorage/data-sources' as const;
+export const SUPPORTED_DATA_SOURCE_KINDS = [
+  'database',
+] as const satisfies readonly DataSourceKind[];
+export const SUPPORTED_API_ORIGINS = ['external'] as const satisfies readonly ApiOrigin[];
+export const SUPPORTED_API_PROTOCOLS = [
+  'graphql',
+  'rest',
+] as const satisfies readonly ApiProtocol[];
+
+export type SupportedApiOrigin = (typeof SUPPORTED_API_ORIGINS)[number];
+
+export interface DataSourcesPackageInfo {
+  readonly packageName: typeof DATA_SOURCES_PACKAGE_NAME;
+  readonly supportedKinds: typeof SUPPORTED_DATA_SOURCE_KINDS;
+  readonly supportedApiOrigins: typeof SUPPORTED_API_ORIGINS;
+  readonly supportedApiProtocols: typeof SUPPORTED_API_PROTOCOLS;
+}
+
+export function getDataSourcesPackageInfo(): DataSourcesPackageInfo {
+  return {
+    packageName: DATA_SOURCES_PACKAGE_NAME,
+    supportedKinds: SUPPORTED_DATA_SOURCE_KINDS,
+    supportedApiOrigins: SUPPORTED_API_ORIGINS,
+    supportedApiProtocols: SUPPORTED_API_PROTOCOLS,
+  };
+}
+
+export function isSupportedDataSourceKind(kind: string): kind is DataSourceKind {
+  return SUPPORTED_DATA_SOURCE_KINDS.some((supported) => supported === kind);
+}
+
+export function isSupportedApiOrigin(origin: string): origin is SupportedApiOrigin {
+  return SUPPORTED_API_ORIGINS.some((supported) => supported === origin);
+}
+
+export function isSupportedApiProtocol(protocol: string): protocol is ApiProtocol {
+  return SUPPORTED_API_PROTOCOLS.some((supported) => supported === protocol);
+}
+
+export function getDataSourceKind(source: DataSourceConfig): DataSourceKind {
+  return source.kind;
+}

package/src/rest/index.test.ts

@@ -1,15 +1,15 @@
 import { describe, expect, it } from 'bun:test';
 
 import {
-  createManualRestDataSource,
+  createManualRestApi,
   extractRestPathParams,
   isManualRestMethod,
-  type ManualRestDataSourceDefinition,
-  normalizeManualRestDataSource,
+  type ManualRestApiDefinition,
+  normalizeManualRestApi,
   normalizeManualRestMethod,
 } from './index';
 
-function definition(): ManualRestDataSourceDefinition {
+function definition(): ManualRestApiDefinition {
   return {
     id: 'blog-api',
     baseUrl: 'https://api.example.com',
@@ -38,7 +38,7 @@ function definition(): ManualRestDataSourceDefinition {
   };
 }
 
-describe('manual REST normalization', () => {
+describe('manual REST API normalization', () => {
   it('normalizes methods and path parameters', () => {
     expect(normalizeManualRestMethod('get')).toBe('GET');
     expect(isManualRestMethod('GET')).toBe(true);
@@ -49,23 +49,26 @@ describe('manual REST normalization', () => {
     ]);
   });
 
-  it('creates an external REST API source', () => {
-    const source = normalizeManualRestDataSource(definition());
-    expect(source).toMatchObject({ kind: 'api', origin: 'external', protocol: 'rest' });
-    expect(source.endpoints.posts?.operations['posts.get']?.method).toBe('GET');
-    expect(source.endpoints.posts?.operations['posts.create']?.intent).toBe('create');
+  it('creates a canonical external REST API', () => {
+    const api = normalizeManualRestApi(definition());
+    expect(api).toMatchObject({ origin: 'external', protocol: 'rest' });
+    expect('kind' in api).toBe(false);
+    expect(api.endpoints.posts?.baseUrl).toBeUndefined();
+    expect(api.endpoints.posts?.operations['posts.get']?.method).toBe('GET');
+    expect(api.endpoints.posts?.operations['posts.create']?.intent).toBe('create');
   });
 
-  it('returns canonical diagnostic results', () => {
-    const valid = createManualRestDataSource(definition());
-    const invalid = createManualRestDataSource({ ...definition(), baseUrl: ' ' });
+  it('returns canonical diagnostics with API identity', () => {
+    const valid = createManualRestApi(definition());
+    const invalid = createManualRestApi({ ...definition(), baseUrl: ' ' });
     expect(valid.ok).toBe(true);
     expect(invalid.ok).toBe(false);
+    if (!invalid.ok) expect(invalid.diagnostics[0]?.apiId).toBe('blog-api');
   });
 
   it('reports unsupported methods and missing path parameters', () => {
     const broken = definition();
-    const result = createManualRestDataSource({
+    const result = createManualRestApi({
       ...broken,
       endpoints: [
         {