@maykonpaulo/maestro-core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1355,6 +1355,33 @@ declare function resolveConsumerProjections(consumers: ConsumerDeclaration[], me
 declare function validateEntityDeclaration(input: unknown): SchemaValidationResult;
 declare function validateConsumerDeclaration(input: unknown, entity?: EntityDeclaration): SchemaValidationResult;
 
+type DeclarativeFileFormat = 'yaml' | 'json';
+/**
+ * Canonical shape of a declarative config file — structurally identical to `DeclarativeConfig`,
+ * so it can be passed directly as `createMaestro({ declarations })`.
+ * `entities` defaults to `[]` when the file omits it.
+ */
+interface DeclarativeFileConfig {
+    entities: EntityDeclaration[];
+    consumers?: ConsumerDeclaration[];
+}
+interface LoadDeclarativeConfigFromStringOptions {
+    format: DeclarativeFileFormat;
+    /** Required for `format: 'yaml'`. The core has no YAML runtime dependency — pass a parser (e.g. `{ parse: YAML.parse }` from the `yaml` package). */
+    yamlParser?: YamlParser;
+    /** Optional label (e.g. a file path) included in error messages to help pinpoint the source. */
+    source?: string;
+}
+interface LoadDeclarativeConfigFromFileOptions {
+    /** Overrides the format that would otherwise be detected from the file extension. */
+    format?: DeclarativeFileFormat;
+    yamlParser?: YamlParser;
+}
+/** Parses and validates a declarative config from textual content. Does not perform I/O. */
+declare function loadDeclarativeConfigFromString(content: string, options: LoadDeclarativeConfigFromStringOptions): DeclarativeFileConfig;
+/** Reads, parses and validates a declarative config from a file path. Format is detected from the extension unless overridden. */
+declare function loadDeclarativeConfigFromFile(filePath: string, options?: LoadDeclarativeConfigFromFileOptions): Promise<DeclarativeFileConfig>;
+
 declare const GOVERNANCE_EVENT_TYPES: {
     readonly OPERATION_EXECUTED: "governance.operation.executed";
     readonly AUTHORIZATION_DENIED: "governance.authorization.denied";
@@ -1428,4 +1455,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, 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 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 SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, compileDeclarations, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, resolveConsumerProjections, 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, 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 SnapshotRepository, type SoftDeleteConfig, type SortDescriptor, type SortDirection, type StructuredLogEntry, type StructuredLogger, type YamlParser, compileDeclarations, createMaestro, createMaestroFromIntrospection, createMaestroHttpHandlers, detectDisplayField, generateAllConfigs, generateCorrelationId, generateEntityConfig, generateRelationConfig, humanizeFieldName, inferFieldType, isSearchCandidate, isSoftDeleteCandidate, isTimestampField, loadDeclarativeConfigFromFile, loadDeclarativeConfigFromString, loadMaestroConfig, mergeIntrospectionWithOverrides, parseQueryInput, resolveConsumerProjections, tableNameToEntityId, tableNameToLabel, validateConsumerDeclaration, validateEntityDeclaration, validateMaestroConfig };

package/dist/index.js

@@ -3292,6 +3292,125 @@ var InMemoryConfirmationRepository = class {
   }
 };
 
+// src/declarative/loader/DeclarativeFileLoader.ts
+import { readFile as readFile2 } from "fs/promises";
+import { extname as extname2 } from "path";
+var KNOWN_KEYS = /* @__PURE__ */ new Set(["entities", "consumers"]);
+function parseContent2(content, format, yamlParser, source) {
+  const origin = source ? ` (${source})` : "";
+  if (format === "yaml") {
+    if (!yamlParser) {
+      throw new MaestroError(
+        "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+        `Cannot parse YAML declarative config${origin}: a "yamlParser" must be provided. The core has no bundled YAML dependency \u2014 install a YAML library (e.g. "yaml") and pass { yamlParser: { parse: YAML.parse } }.`
+      );
+    }
+    try {
+      return yamlParser.parse(content);
+    } catch (cause) {
+      throw new MaestroError(
+        "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+        `Failed to parse YAML declarative config${origin}: ${cause.message}`,
+        { cause }
+      );
+    }
+  }
+  try {
+    return JSON.parse(content);
+  } catch (cause) {
+    throw new MaestroError(
+      "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+      `Failed to parse JSON declarative config${origin}: ${cause.message}`,
+      { cause }
+    );
+  }
+}
+function normalizeAndValidate(raw, source) {
+  const origin = source ? ` in ${source}` : "";
+  if (raw === null || raw === void 0) {
+    return { entities: [] };
+  }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new MaestroError(
+      "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+      `Declarative config${origin} must be an object with optional "entities" and "consumers" arrays.`
+    );
+  }
+  const obj = raw;
+  const errors = [];
+  for (const key of Object.keys(obj)) {
+    if (!KNOWN_KEYS.has(key)) {
+      errors.push({
+        path: key,
+        message: `Unknown declarative config key "${key}". Only "entities" and "consumers" are supported.`
+      });
+    }
+  }
+  let entities;
+  if (obj["entities"] !== void 0) {
+    if (!Array.isArray(obj["entities"])) {
+      errors.push({ path: "entities", message: '"entities" must be an array of entity declarations.' });
+    } else {
+      entities = obj["entities"];
+      entities.forEach((entity, index) => {
+        const result = validateEntityDeclaration(entity);
+        if (!result.valid) {
+          for (const err of result.errors) {
+            const path = err.path ? `entities[${index}].${err.path}` : `entities[${index}]`;
+            errors.push({ path, message: err.message });
+          }
+        }
+      });
+    }
+  }
+  let consumers;
+  if (obj["consumers"] !== void 0) {
+    if (!Array.isArray(obj["consumers"])) {
+      errors.push({ path: "consumers", message: '"consumers" must be an array of consumer declarations.' });
+    } else {
+      consumers = obj["consumers"];
+      const entityByName = new Map((entities ?? []).map((entity) => [entity.entity, entity]));
+      consumers.forEach((consumer, index) => {
+        const relatedEntity = consumer && typeof consumer === "object" ? entityByName.get(consumer["entity"]) : void 0;
+        const result = validateConsumerDeclaration(consumer, relatedEntity);
+        if (!result.valid) {
+          for (const err of result.errors) {
+            const path = err.path ? `consumers[${index}].${err.path}` : `consumers[${index}]`;
+            errors.push({ path, message: err.message });
+          }
+        }
+      });
+    }
+  }
+  if (errors.length > 0) {
+    const details = errors.map((err) => `${err.path}: ${err.message}`).join("; ");
+    throw new MaestroError(
+      "VALIDATION_ERROR" /* VALIDATION_ERROR */,
+      `Invalid declarative config${origin}: ${details}`,
+      { details: { errors } }
+    );
+  }
+  return { entities: entities ?? [], consumers };
+}
+function loadDeclarativeConfigFromString(content, options) {
+  const raw = parseContent2(content, options.format, options.yamlParser, options.source);
+  return normalizeAndValidate(raw, options.source);
+}
+function detectFormatFromExtension(filePath) {
+  const ext = extname2(filePath).toLowerCase();
+  if (ext === ".yaml" || ext === ".yml") return "yaml";
+  if (ext === ".json") return "json";
+  throw new MaestroError(
+    "CONFIGURATION_ERROR" /* CONFIGURATION_ERROR */,
+    `Cannot detect declarative config format from file extension "${ext}" (${filePath}). Supported extensions: .yaml, .yml, .json. Pass { format } explicitly to override.`
+  );
+}
+async function loadDeclarativeConfigFromFile(filePath, options = {}) {
+  const format = options.format ?? detectFormatFromExtension(filePath);
+  const content = await readFile2(filePath, "utf-8");
+  return loadDeclarativeConfigFromString(content, { format, yamlParser: options.yamlParser, source: filePath });
+}
+
 // src/governance/GovernanceEventType.ts
 var GOVERNANCE_EVENT_TYPES = {
   OPERATION_EXECUTED: "governance.operation.executed",
@@ -3402,6 +3521,8 @@ export {
   isSearchCandidate,
   isSoftDeleteCandidate,
   isTimestampField,
+  loadDeclarativeConfigFromFile,
+  loadDeclarativeConfigFromString,
   loadMaestroConfig,
   mergeIntrospectionWithOverrides,
   parseQueryInput,