@maykonpaulo/maestro-core 0.6.0 → 0.7.0-next.1

package/dist/index.d.ts

@@ -909,8 +909,29 @@ interface IntrospectionResult {
     relations: RelationIntrospectionSchema[];
 }
 
+/**
+ * Execution context passed to an `IntrospectionProvider`. Intentionally generic and provider-agnostic:
+ * it carries cross-cutting concerns (who triggered the run, how to log, how to cancel) but never
+ * datasource-specific detail. Connection strings, hosts, ports, schemas, credentials and ORM/driver
+ * clients belong to the concrete provider's own constructor/options, not to this shared contract.
+ */
+interface IntrospectionContext {
+    correlationId?: string;
+    actor?: Actor;
+    metadata?: Metadata;
+    logger?: Logger;
+    signal?: AbortSignal;
+}
+
+/**
+ * Contract implemented by external adapters that discover the structure of a system or data source
+ * and report it back as an `IntrospectionResult`. The core only defines and executes this contract —
+ * it never implements a concrete provider (no database connection, driver or ORM).
+ */
 interface IntrospectionProvider {
-    introspect(): Promise<IntrospectionResult>;
+    /** Identifies the provider in logs and error messages, e.g. "postgres", "fake-in-memory". */
+    readonly name?: string;
+    introspect(context?: IntrospectionContext): Promise<IntrospectionResult> | IntrospectionResult;
 }
 
 interface YamlParser {
@@ -1040,6 +1061,51 @@ declare function detectDisplayField(fields: Array<{
     isPrimaryKey: boolean;
 }>): string | undefined;
 
+/**
+ * Public structural validator for the `IntrospectionResult` contract. Accepts unknown/untrusted input
+ * (e.g. a parsed JSON file) and checks it against the required (non-optional) fields of
+ * `IntrospectionResult`/`EntityIntrospectionSchema`/`FieldIntrospectionSchema`/`RelationIntrospectionSchema`.
+ * Optional derived fields (`isUnique`, `candidateForSearch`, `isTimestamp`, …) are not validated —
+ * they pass through untouched when present.
+ */
+interface IntrospectionValidationIssue {
+    /** Logical path of the offending field, e.g. `entities[0].fields[1].nullable`. */
+    path: string;
+    /** Human-readable reason, including expected vs. received type when applicable. */
+    message: string;
+}
+interface IntrospectionValidationResult {
+    valid: boolean;
+    issues: IntrospectionValidationIssue[];
+}
+/**
+ * Validates that an unknown value matches the `IntrospectionResult` contract closely enough to be
+ * safely consumed downstream. Accumulates every issue found (rather than failing fast) so callers can
+ * surface a complete, readable list of problems in one pass.
+ */
+declare function validateIntrospectionResult(value: unknown): IntrospectionValidationResult;
+
+/**
+ * Normalizes a valid `IntrospectionResult` into a deterministic, canonical form: entities sorted by
+ * `table`, relations sorted by `id`. The internal order of `fields`/`indices` is preserved, since column
+ * order is operationally meaningful. Never adds volatile data (timestamps, absolute paths, hashes) —
+ * the same input always normalizes to the same output.
+ */
+declare function normalizeIntrospectionResult(result: IntrospectionResult): IntrospectionResult;
+
+interface RunIntrospectionResult {
+    /** The provider's `name`, or `"unknown"` when the provider does not declare one. */
+    provider: string;
+    result: IntrospectionResult;
+}
+/**
+ * Runs an `IntrospectionProvider`, then validates and normalizes its output before returning it. This
+ * is the only sanctioned way to consume a provider's result: a provider can never hand back a
+ * structurally invalid `IntrospectionResult` silently — `validateIntrospectionResult` failures and
+ * provider exceptions both surface as a `MaestroError`.
+ */
+declare function runIntrospectionProvider(provider: IntrospectionProvider, context?: IntrospectionContext): Promise<RunIntrospectionResult>;
+
 interface GeneratedConfig {
     entities: Record<string, EntitySchema>;
     relations: Record<string, RelationSchema>;
@@ -1496,4 +1562,4 @@ declare class DefaultGovernanceApi implements GovernanceApi {
     getPolicyViolations(filter?: PolicyViolationFilter): Promise<PolicyViolation[]>;
 }
 
-export { type Actor, type ActorType, type AuditEvent, type AuditFilter, type AuditLevel, type AuditRecordedPayload, AuditRecorder, type AuditRepository, type AuditTimeline, type AuthorizationContext, type AuthorizationDecision, type AuthorizationDeniedPayload, type AuthorizationProvider, type AuthorizationResult, type CompileDeclarationsOptions, type ConfigProvider, type ConfirmationApproval, type ConfirmationApprovedPayload, type ConfirmationDeclaration, ConfirmationEngine, type ConfirmationRejectedPayload, type ConfirmationRepository, type ConfirmationRequest, type ConfirmationRequestedPayload, type ConfirmationStatus, ConsoleLogger, ConsoleStructuredLogger, type ConsumerActionsConfig, type ConsumerDeclaration, type ConsumerDetailConfig, type ConsumerFormConfig, type ConsumerFormsConfig, type ConsumerListConfig, type ConsumerProjectionFields, type ConsumerProjectionOperations, type ContextAction, type ContextActionCondition, type ContextActionStyle, ContextualAuthorizationEngine, type CorrelationContext, type CorrelationId, type CreateMaestroFromIntrospectionOptions, CsvExportProvider, type CursorPagination, DEFAULT_CAPABILITIES, type DatasourceDeleteContext, type DatasourceFindContext, type DatasourceProvider, type DatasourceQueryContext, DatasourceRegistry, type DatasourceUpdateContext, type DatasourceWriteContext, type DeclarativeCompilationResult, type DeclarativeConfig, type DeclarativeFileConfig, type DeclarativeFileFormat, type DeclarativeGeneratorMetadataInput, type DeclarativeGeneratorOptions, type DeclarativeGeneratorSchemaInput, type DeclarativeSerializationFormat, DefaultGovernanceApi, type DiffChange, type DiffChangeKind, DiffEngine, type DiffEngineOptions, type DiffSummary, type DomainEvent, type EntityCapabilities, type EntityDeclaration, type EntityDiffChange, type EntityDiffChangeKind, type EntityExportConfig, type EntityIntrospectionSchema, type EntityLabelConfig, type EntityMetadata, type EntitySchema, type EntitySourceConfig, type EnumOption, type EnumOptionDeclaration, ErrorCode, type EventBus, type EventHandler, type ExportConfig, type ExportFormat, type ExportOptions, type ExportProvider, type ExportResult, type FeatureFlag, type FeatureFlagProvider, type FieldDeclaration, type FieldDetailConfig, type FieldDiffChange, type FieldDiffChangeKind, type FieldFormConfig, type FieldIntrospectionSchema, type FieldListConfig, type FieldMetadata, type FieldSchema, type FieldSchemaDetailConfig, type FieldSchemaEnumOption, type FieldSchemaFormConfig, type FieldSchemaListConfig, type FieldType, type FileSystemReader, type FilterDescriptor, type FilterOperator, GOVERNANCE_EVENT_TYPES, type GeneratedConfig, type GovernanceApi, type GovernanceEventBus, type GovernanceEventType, type ImpactLevel, InMemoryAuditRepository, InMemoryConfigProvider, InMemoryConfirmationRepository, InMemoryDatasourceProvider, InMemoryEventBus, InMemoryFeatureFlagProvider, InMemoryGovernanceEventBus, InMemoryPolicyProvider, InMemorySnapshotRepository, type IndexIntrospectionSchema, type IntrospectionDiff, type IntrospectionProvider, type IntrospectionReport, type IntrospectionReportChange, type IntrospectionReportStats, type IntrospectionResult, IntrospectionRuntime, type IntrospectionRuntimeResult, type IntrospectionRuntimeRunOptions, type IntrospectionSnapshot, type ListResult, type LoadDeclarativeConfigFromFileOptions, type LoadDeclarativeConfigFromStringOptions, type LoadedConfig, type LogEntry, type LogLevel, type Logger, type MaestroActorResolver, type MaestroConfig, MaestroEngine, MaestroError, type MaestroFileLoaderOptions, type MaestroHttpHandler, type MaestroHttpHandlers, type MaestroHttpOptions, type MaestroHttpRequest, type MaestroHttpResponse, type MaestroMetadata, type MaestroRequestContext, type MergeIntrospectionOptions, type MergeStrategy, type Metadata, MetadataEngine, MetadataRiskClassifier, type MetadataValue, type OffsetPagination, type OperationContext, type OperationDeclaration, type OperationDef, type OperationExecutedPayload, type OperationLogStatus, type OperationMetadata, OperationRegistry, type OperationResult, type OperationScope, type OperationalRisk, type PagePagination, type PaginationInput, type Permission, type PolicyContext, type PolicyDecision, PolicyEngine, type PolicyEvaluationResult, type PolicyProvider, type PolicyRule, type PolicyRuleResult, type PolicyTriggeredPayload, type PolicyViolation, type PolicyViolationFilter, type QueryInput, RbacEngine, type RbacPolicy, type RecordAuditInput, type RelationDeclaration, type RelationDiffChange, type RelationDiffChangeKind, type RelationDisplayConfig, type RelationEndpoint, type RelationIntrospectionSchema, type RelationMetadata, type RelationSchema, type RelationType, ReportGenerator, type RequestConfirmationInput, type ResolvedConsumerProjection, type ResourceRef, type RiskClassificationInput, type RiskClassifier, type Role, type SchemaValidationError, type SchemaValidationResult, type SearchConfig, type SearchInput, type SerializeDeclarativeConfigOptions, type SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, type YamlSerializer, compileDeclarations, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateDeclarativeConfigFromMetadata, generateDeclarativeConfigFromSchema, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadDeclarativeConfigFromFile, loadDeclarativeConfigFromString, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, resolveConsumerProjections, serializeDeclarativeConfig, serializeDeclarativeConfigToJson, serializeDeclarativeConfigToYaml, tableNameToEntityId, tableNameToLabel, validateConsumerDeclaration, validateEntityDeclaration, validateMaestroConfig };
+export { type Actor, type ActorType, type AuditEvent, type AuditFilter, type AuditLevel, type AuditRecordedPayload, AuditRecorder, type AuditRepository, type AuditTimeline, type AuthorizationContext, type AuthorizationDecision, type AuthorizationDeniedPayload, type AuthorizationProvider, type AuthorizationResult, type CompileDeclarationsOptions, type ConfigProvider, type ConfirmationApproval, type ConfirmationApprovedPayload, type ConfirmationDeclaration, ConfirmationEngine, type ConfirmationRejectedPayload, type ConfirmationRepository, type ConfirmationRequest, type ConfirmationRequestedPayload, type ConfirmationStatus, ConsoleLogger, ConsoleStructuredLogger, type ConsumerActionsConfig, type ConsumerDeclaration, type ConsumerDetailConfig, type ConsumerFormConfig, type ConsumerFormsConfig, type ConsumerListConfig, type ConsumerProjectionFields, type ConsumerProjectionOperations, type ContextAction, type ContextActionCondition, type ContextActionStyle, ContextualAuthorizationEngine, type CorrelationContext, type CorrelationId, type CreateMaestroFromIntrospectionOptions, CsvExportProvider, type CursorPagination, DEFAULT_CAPABILITIES, type DatasourceDeleteContext, type DatasourceFindContext, type DatasourceProvider, type DatasourceQueryContext, DatasourceRegistry, type DatasourceUpdateContext, type DatasourceWriteContext, type DeclarativeCompilationResult, type DeclarativeConfig, type DeclarativeFileConfig, type DeclarativeFileFormat, type DeclarativeGeneratorMetadataInput, type DeclarativeGeneratorOptions, type DeclarativeGeneratorSchemaInput, type DeclarativeSerializationFormat, DefaultGovernanceApi, type DiffChange, type DiffChangeKind, DiffEngine, type DiffEngineOptions, type DiffSummary, type DomainEvent, type EntityCapabilities, type EntityDeclaration, type EntityDiffChange, type EntityDiffChangeKind, type EntityExportConfig, type EntityIntrospectionSchema, type EntityLabelConfig, type EntityMetadata, type EntitySchema, type EntitySourceConfig, type EnumOption, type EnumOptionDeclaration, ErrorCode, type EventBus, type EventHandler, type ExportConfig, type ExportFormat, type ExportOptions, type ExportProvider, type ExportResult, type FeatureFlag, type FeatureFlagProvider, type FieldDeclaration, type FieldDetailConfig, type FieldDiffChange, type FieldDiffChangeKind, type FieldFormConfig, type FieldIntrospectionSchema, type FieldListConfig, type FieldMetadata, type FieldSchema, type FieldSchemaDetailConfig, type FieldSchemaEnumOption, type FieldSchemaFormConfig, type FieldSchemaListConfig, type FieldType, type FileSystemReader, type FilterDescriptor, type FilterOperator, GOVERNANCE_EVENT_TYPES, type GeneratedConfig, type GovernanceApi, type GovernanceEventBus, type GovernanceEventType, type ImpactLevel, InMemoryAuditRepository, InMemoryConfigProvider, InMemoryConfirmationRepository, InMemoryDatasourceProvider, InMemoryEventBus, InMemoryFeatureFlagProvider, InMemoryGovernanceEventBus, InMemoryPolicyProvider, InMemorySnapshotRepository, type IndexIntrospectionSchema, type IntrospectionContext, type IntrospectionDiff, type IntrospectionProvider, type IntrospectionReport, type IntrospectionReportChange, type IntrospectionReportStats, type IntrospectionResult, IntrospectionRuntime, type IntrospectionRuntimeResult, type IntrospectionRuntimeRunOptions, type IntrospectionSnapshot, type IntrospectionValidationIssue, type IntrospectionValidationResult, type ListResult, type LoadDeclarativeConfigFromFileOptions, type LoadDeclarativeConfigFromStringOptions, type LoadedConfig, type LogEntry, type LogLevel, type Logger, type MaestroActorResolver, type MaestroConfig, MaestroEngine, MaestroError, type MaestroFileLoaderOptions, type MaestroHttpHandler, type MaestroHttpHandlers, type MaestroHttpOptions, type MaestroHttpRequest, type MaestroHttpResponse, type MaestroMetadata, type MaestroRequestContext, type MergeIntrospectionOptions, type MergeStrategy, type Metadata, MetadataEngine, MetadataRiskClassifier, type MetadataValue, type OffsetPagination, type OperationContext, type OperationDeclaration, type OperationDef, type OperationExecutedPayload, type OperationLogStatus, type OperationMetadata, OperationRegistry, type OperationResult, type OperationScope, type OperationalRisk, type PagePagination, type PaginationInput, type Permission, type PolicyContext, type PolicyDecision, PolicyEngine, type PolicyEvaluationResult, type PolicyProvider, type PolicyRule, type PolicyRuleResult, type PolicyTriggeredPayload, type PolicyViolation, type PolicyViolationFilter, type QueryInput, RbacEngine, type RbacPolicy, type RecordAuditInput, type RelationDeclaration, type RelationDiffChange, type RelationDiffChangeKind, type RelationDisplayConfig, type RelationEndpoint, type RelationIntrospectionSchema, type RelationMetadata, type RelationSchema, type RelationType, ReportGenerator, type RequestConfirmationInput, type ResolvedConsumerProjection, type ResourceRef, type RiskClassificationInput, type RiskClassifier, type Role, type RunIntrospectionResult, type SchemaValidationError, type SchemaValidationResult, type SearchConfig, type SearchInput, type SerializeDeclarativeConfigOptions, type SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, type YamlSerializer, compileDeclarations, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateDeclarativeConfigFromMetadata, generateDeclarativeConfigFromSchema, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadDeclarativeConfigFromFile, loadDeclarativeConfigFromString, loadMaestroConfig, mergeIntrospectionWithOverrides, normalizeIntrospectionResult, parseQueryInput, resolveConsumerProjections, runIntrospectionProvider, serializeDeclarativeConfig, serializeDeclarativeConfigToJson, serializeDeclarativeConfigToYaml, tableNameToEntityId, tableNameToLabel, validateConsumerDeclaration, validateEntityDeclaration, validateIntrospectionResult, validateMaestroConfig };

package/dist/index.js

@@ -2515,6 +2515,147 @@ async function loadMaestroConfig(options) {
   };
 }
 
+// src/introspection/IntrospectionValidator.ts
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function reject(issues, path, expected, received) {
+  issues.push({ path, message: `expected ${expected}, received ${typeOf(received)}.` });
+}
+function validateEndpoint(endpoint, path, issues) {
+  if (!isObject(endpoint)) {
+    reject(issues, path, 'an object with "table" and "field"', endpoint);
+    return;
+  }
+  if (!nonEmptyString(endpoint["table"])) {
+    reject(issues, `${path}.table`, "a non-empty string", endpoint["table"]);
+  }
+  if (!nonEmptyString(endpoint["field"])) {
+    reject(issues, `${path}.field`, "a non-empty string", endpoint["field"]);
+  }
+}
+function validateField(entityIndex, fieldIndex, field, issues) {
+  const path = `entities[${entityIndex}].fields[${fieldIndex}]`;
+  if (!isObject(field)) {
+    reject(issues, path, "an object", field);
+    return;
+  }
+  if (!nonEmptyString(field["name"])) reject(issues, `${path}.name`, "a non-empty string", field["name"]);
+  if (typeof field["nativeType"] !== "string") reject(issues, `${path}.nativeType`, "a string", field["nativeType"]);
+  if (typeof field["type"] !== "string") reject(issues, `${path}.type`, "a string", field["type"]);
+  if (typeof field["nullable"] !== "boolean") reject(issues, `${path}.nullable`, "a boolean", field["nullable"]);
+  if (typeof field["isPrimaryKey"] !== "boolean") {
+    reject(issues, `${path}.isPrimaryKey`, "a boolean", field["isPrimaryKey"]);
+  }
+}
+function validateEntity2(index, entity, issues) {
+  const path = `entities[${index}]`;
+  if (!isObject(entity)) {
+    reject(issues, path, "an object", entity);
+    return;
+  }
+  if (!nonEmptyString(entity["table"])) reject(issues, `${path}.table`, "a non-empty string", entity["table"]);
+  if (!Array.isArray(entity["fields"])) {
+    reject(issues, `${path}.fields`, "an array", entity["fields"]);
+    return;
+  }
+  const fields = entity["fields"];
+  for (let j = 0; j < fields.length; j++) {
+    validateField(index, j, fields[j], issues);
+  }
+}
+function validateRelation2(index, relation, issues) {
+  const path = `relations[${index}]`;
+  if (!isObject(relation)) {
+    reject(issues, path, "an object", relation);
+    return;
+  }
+  if (!nonEmptyString(relation["id"])) reject(issues, `${path}.id`, "a non-empty string", relation["id"]);
+  if (typeof relation["type"] !== "string") reject(issues, `${path}.type`, "a string", relation["type"]);
+  validateEndpoint(relation["from"], `${path}.from`, issues);
+  validateEndpoint(relation["to"], `${path}.to`, issues);
+  if (relation["confidence"] !== "definite" && relation["confidence"] !== "inferred") {
+    issues.push({
+      path: `${path}.confidence`,
+      message: `expected "definite" or "inferred", received ${JSON.stringify(relation["confidence"])}.`
+    });
+  }
+}
+function validateIntrospectionResult(value) {
+  const issues = [];
+  if (!isObject(value)) {
+    reject(issues, "", 'an object with "entities" and "relations" arrays', value);
+    return { valid: false, issues };
+  }
+  if (!Array.isArray(value["entities"])) {
+    reject(issues, "entities", "an array", value["entities"]);
+  } else {
+    const entities = value["entities"];
+    for (let i = 0; i < entities.length; i++) {
+      validateEntity2(i, entities[i], issues);
+    }
+  }
+  if (!Array.isArray(value["relations"])) {
+    reject(issues, "relations", "an array", value["relations"]);
+  } else {
+    const relations = value["relations"];
+    for (let i = 0; i < relations.length; i++) {
+      validateRelation2(i, relations[i], issues);
+    }
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+// src/introspection/IntrospectionNormalizer.ts
+function compareStrings(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function normalizeIntrospectionResult(result) {
+  const entities = [...result.entities].sort((a, b) => compareStrings(a.table, b.table));
+  const relations = [...result.relations].sort((a, b) => compareStrings(a.id, b.id));
+  return { entities, relations };
+}
+
+// src/introspection/runIntrospectionProvider.ts
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runIntrospectionProvider(provider, context) {
+  const providerName = provider.name ?? "unknown";
+  let raw;
+  try {
+    raw = await provider.introspect(context);
+  } catch (cause) {
+    throw new MaestroError(
+      "INTERNAL_ERROR" /* INTERNAL_ERROR */,
+      `Introspection provider "${providerName}" threw during introspect(): ${errorMessage(cause)}`,
+      { details: { provider: providerName }, cause }
+    );
+  }
+  const validation = validateIntrospectionResult(raw);
+  if (!validation.valid) {
+    const issueSummary = validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+    const details = {
+      provider: providerName,
+      issues: validation.issues.map((issue) => ({ path: issue.path, message: issue.message }))
+    };
+    throw new MaestroError(
+      "VALIDATION_ERROR" /* VALIDATION_ERROR */,
+      `Introspection provider "${providerName}" returned an invalid IntrospectionResult: ${issueSummary}`,
+      { details }
+    );
+  }
+  return { provider: providerName, result: normalizeIntrospectionResult(raw) };
+}
+
 // src/config-generator/ConfigGenerator.ts
 function detectSoftDelete2(fields) {
   const PRIORITY = [
@@ -3710,8 +3851,10 @@ export {
   loadDeclarativeConfigFromString,
   loadMaestroConfig,
   mergeIntrospectionWithOverrides,
+  normalizeIntrospectionResult,
   parseQueryInput,
   resolveConsumerProjections,
+  runIntrospectionProvider,
   serializeDeclarativeConfig,
   serializeDeclarativeConfigToJson,
   serializeDeclarativeConfigToYaml,
@@ -3719,6 +3862,7 @@ export {
   tableNameToLabel,
   validateConsumerDeclaration,
   validateEntityDeclaration,
+  validateIntrospectionResult,
   validateMaestroConfig
 };
 //# sourceMappingURL=index.js.map