@endge/core 4.0.3 → 6.0.0

package/dist/features/core/modules/diagnostics/domain/types/diagnostics.types.d.ts

@@ -0,0 +1,315 @@
+/** Сигналы, которые поддерживает первая версия модуля диагностики. */
+export type DiagnosticsSignal = 'log' | 'span';
+/** Фаза жизненного цикла, в которой создана диагностическая запись. */
+export type DiagnosticsPhase = 'authoring' | 'build' | 'runtime';
+/** Базовые значения OpenTelemetry SeverityNumber, используемые публичным API. */
+export type DiagnosticsSeverityNumber = 1 | 5 | 9 | 13 | 17 | 21;
+/** Скалярное значение диагностического атрибута. */
+export type DiagnosticsAttributeScalar = string | number | boolean;
+/** Допустимое значение диагностического атрибута. */
+export type DiagnosticsAttributeValue = DiagnosticsAttributeScalar | DiagnosticsAttributeScalar[];
+/** Плоские структурированные атрибуты записи. */
+export type DiagnosticsAttributes = Record<string, DiagnosticsAttributeValue>;
+/** Синхронный provider общих attributes, актуальных в момент создания record. */
+export type DiagnosticsContextProvider = () => DiagnosticsAttributes;
+/** Фаза, в которой обнаружена актуальная проблема системы. */
+export type DiagnosticsProblemPhase = DiagnosticsPhase;
+/** Уровень актуальной проблемы, независимый от OTel SeverityNumber. */
+export type DiagnosticsProblemSeverity = 'info' | 'warning' | 'error' | 'fatal';
+/** Стабильная ссылка на доменную сущность без ограничения compiled ProgramEntityType. */
+export interface DiagnosticsEntityRef {
+    entityType: string;
+    id: string | number;
+    identity: string;
+}
+/** Владелец replaceable-набора проблем. */
+export interface DiagnosticsProblemOwner {
+    /** Уникальный ключ владельца внутри problem registry. */
+    key: string;
+    /** Фаза жизненного цикла, к которой относится набор. */
+    phase: DiagnosticsProblemPhase;
+    /** Доменная сущность, если проблема связана с persisted document. */
+    entityRef?: DiagnosticsEntityRef;
+    /** Runtime instance, если проблема относится к живому host. */
+    runtimeId?: string;
+}
+/** Вход одной проблемы до добавления owner и временных метаданных registry. */
+export interface DiagnosticsProblemInput {
+    /** Стабильный ключ проблемы внутри одного owner; при отсутствии выводится из содержимого. */
+    key?: string;
+    severity: DiagnosticsProblemSeverity;
+    code: string;
+    message: string;
+    sourcePath?: string;
+    start?: number;
+    end?: number;
+    attributes?: DiagnosticsAttributes;
+    traceId?: string;
+    recordId?: number;
+}
+/** Актуальная проблема, нормализованная problem registry. */
+export interface DiagnosticsProblem extends Omit<DiagnosticsProblemInput, 'key'> {
+    /** Стабильный id в формате `<owner.key>:<problem.key>`. */
+    id: string;
+    /** Ключ проблемы внутри owner. */
+    key: string;
+    owner: DiagnosticsProblemOwner;
+    updatedAt: number;
+}
+/** Условия выбора актуальных проблем. */
+export interface DiagnosticsProblemFilter {
+    ownerKeys?: string[];
+    phases?: DiagnosticsProblemPhase[];
+    severities?: DiagnosticsProblemSeverity[];
+    entityTypes?: string[];
+    entityId?: string | number;
+    entityIdentity?: string;
+    runtimeId?: string;
+    codes?: string[];
+}
+/** Реестр проблем, заменяемый целиком через snapshot. */
+export interface DiagnosticsProblemsSnapshot {
+    revision: number;
+    total: number;
+    problems: readonly DiagnosticsProblem[];
+}
+/** Модуль или библиотека, создавшая запись. */
+export interface DiagnosticsInstrumentationScope {
+    name: string;
+    version?: string;
+}
+/** Общие атрибуты текущего запуска Endge. */
+export interface DiagnosticsResource {
+    attributes: DiagnosticsAttributes;
+}
+/** Статус завершённого span. */
+export interface DiagnosticsSpanStatus {
+    code: 'unset' | 'ok' | 'error';
+    message?: string;
+}
+/** Общие поля любой записи локального diagnostics store. */
+export interface DiagnosticsRecordBase {
+    id: number;
+    signal: DiagnosticsSignal;
+    scope: DiagnosticsInstrumentationScope;
+    attributes: DiagnosticsAttributes;
+    traceId?: string;
+    spanId?: string;
+    traceFlags?: number;
+    phase?: DiagnosticsPhase;
+}
+/** Структурированный log record в формате, близком к OpenTelemetry. */
+export interface DiagnosticsLogRecord extends DiagnosticsRecordBase {
+    signal: 'log';
+    timestamp: number;
+    observedTimestamp?: number;
+    severityNumber: DiagnosticsSeverityNumber;
+    severityText: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+    body: string;
+    eventName?: string;
+}
+/** Один завершённый span; start/end records отдельно не сохраняются. */
+export interface DiagnosticsSpanRecord extends DiagnosticsRecordBase {
+    signal: 'span';
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimestamp: number;
+    endTimestamp: number;
+    durationMs: number;
+    status: DiagnosticsSpanStatus;
+}
+/** Объединённый тип записей модуля диагностики. */
+export type DiagnosticsRecord = DiagnosticsLogRecord | DiagnosticsSpanRecord;
+/** Настройки локального сбора и bounded storage. */
+export interface EndgeDiagnosticsCollectionConfiguration {
+    enabled: boolean;
+    signals: DiagnosticsSignal[];
+    minSeverity: DiagnosticsSeverityNumber;
+    maxRecords: number;
+}
+/** JSON-safe значение persisted options конкретного adapter. */
+export type DiagnosticsAdapterOptionValue = string | number | boolean | null | DiagnosticsAdapterOptionValue[] | {
+    [key: string]: DiagnosticsAdapterOptionValue;
+};
+/** Именованный канал вывода, создаваемый через adapter registry. */
+export interface EndgeDiagnosticsOutputConfiguration {
+    id: string;
+    name: string;
+    enabled: boolean;
+    adapterType: string;
+    options: Record<string, DiagnosticsAdapterOptionValue>;
+}
+/** Условия выбора records для подписки или route. */
+export interface DiagnosticsFilter {
+    signals?: DiagnosticsSignal[];
+    phases?: DiagnosticsPhase[];
+    minSeverity?: DiagnosticsSeverityNumber;
+    spanStatuses?: DiagnosticsSpanStatus['code'][];
+    minDurationMs?: number;
+    scopes?: string[];
+    eventNames?: string[];
+    traceId?: string;
+    spanId?: string;
+    attributes?: DiagnosticsAttributes;
+    limit?: number;
+}
+/** Декларативное правило доставки records в adapter. */
+export interface EndgeDiagnosticsRoute {
+    id: string;
+    name: string;
+    enabled: boolean;
+    match: DiagnosticsFilter;
+    outputId: string;
+}
+/** Effective configuration сбора и внешней доставки telemetry. */
+export interface EndgeDiagnosticsTelemetryConfiguration {
+    collection: EndgeDiagnosticsCollectionConfiguration;
+    outputs: EndgeDiagnosticsOutputConfiguration[];
+    routes: EndgeDiagnosticsRoute[];
+}
+/** Состав JSON snapshot по умолчанию. */
+export interface EndgeDiagnosticsSnapshotContentConfiguration {
+    telemetry: boolean;
+    problems: boolean;
+    configuration: boolean;
+}
+/** Условия автоматического snapshot по ERROR/FATAL records. */
+export interface EndgeDiagnosticsAutomaticSnapshotConfiguration {
+    enabled: boolean;
+    errorCount: number;
+    windowSeconds: number;
+    cooldownSeconds: number;
+    outputIds: string[];
+}
+/** Effective configuration ручных и автоматических snapshots. */
+export interface EndgeDiagnosticsSnapshotsConfiguration {
+    content: EndgeDiagnosticsSnapshotContentConfiguration;
+    automatic: EndgeDiagnosticsAutomaticSnapshotConfiguration;
+}
+/** Полная effective configuration модуля диагностики. */
+export interface EndgeDiagnosticsConfiguration {
+    telemetry: EndgeDiagnosticsTelemetryConfiguration;
+    snapshots: EndgeDiagnosticsSnapshotsConfiguration;
+}
+/** Параметры записи log без выбранного уровня severity. */
+export interface DiagnosticsLogOptions {
+    timestamp?: number;
+    observedTimestamp?: number;
+    scope?: DiagnosticsInstrumentationScope;
+    eventName?: string;
+    attributes?: DiagnosticsAttributes;
+    traceId?: string;
+    spanId?: string;
+    traceFlags?: number;
+    phase?: DiagnosticsPhase;
+}
+/** Полный input универсального метода log(). */
+export interface DiagnosticsLogInput extends DiagnosticsLogOptions {
+    body: string;
+    severityNumber: DiagnosticsSeverityNumber;
+}
+/** Параметры структурированной записи исключения. */
+export interface DiagnosticsExceptionOptions extends DiagnosticsLogOptions {
+    severityNumber?: 17 | 21;
+}
+/** Параметры создания root или child span. */
+export interface DiagnosticsSpanOptions {
+    scope?: DiagnosticsInstrumentationScope;
+    attributes?: DiagnosticsAttributes;
+    traceId?: string;
+    parentSpanId?: string;
+    traceFlags?: number;
+    startTimestamp?: number;
+    phase?: DiagnosticsPhase;
+}
+/** Параметры завершения span. */
+export interface DiagnosticsSpanEndOptions {
+    status?: DiagnosticsSpanStatus['code'];
+    message?: string;
+    attributes?: DiagnosticsAttributes;
+    endTimestamp?: number;
+}
+/** Публичный handle активного span. */
+export interface DiagnosticsSpanHandle {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly isEnded: boolean;
+    /** Добавляет или переопределяет структурированные атрибуты активного span. */
+    setAttributes: (attributes: DiagnosticsAttributes) => void;
+    /** Создаёт child span с унаследованными trace id и parent span id. */
+    startChild: (name: string, options?: Omit<DiagnosticsSpanOptions, 'traceId' | 'parentSpanId'>) => DiagnosticsSpanHandle;
+    /** Записывает log, автоматически связанный с текущим span. */
+    log: (input: Omit<DiagnosticsLogInput, 'traceId' | 'spanId'>) => DiagnosticsLogRecord | null;
+    /** Записывает exception log, автоматически связанный с текущим span. */
+    recordException: (error: unknown, options?: DiagnosticsExceptionOptions) => DiagnosticsLogRecord | null;
+    /** Завершает span и сохраняет единственный итоговый span record. */
+    end: (options?: DiagnosticsSpanEndOptions) => DiagnosticsSpanRecord | null;
+}
+/** Счётчики текущей diagnostics session. */
+export interface DiagnosticsCounters {
+    totalRecords: number;
+    droppedByPolicy: number;
+    droppedByCapacity: number;
+    adapterFailures: number;
+    listenerFailures: number;
+    contextProviderFailures: number;
+    activeAdapters: number;
+    activeContextProviders: number;
+    activeSpans: number;
+    recordsBySignal: Partial<Record<DiagnosticsSignal, number>>;
+    recordsByScope: Record<string, number>;
+}
+/** Параметры создания JSON-safe snapshot. */
+export interface DiagnosticsSnapshotOptions {
+    trigger?: 'manual' | 'automatic';
+    includeTelemetry?: boolean;
+    includeProblems?: boolean;
+    includeConfiguration?: boolean;
+    filter?: DiagnosticsFilter;
+}
+/** Telemetry-часть диагностического snapshot. */
+export interface DiagnosticsTelemetrySnapshot {
+    sessionId: string;
+    resource: DiagnosticsResource;
+    counters: DiagnosticsCounters;
+    records: readonly DiagnosticsRecord[];
+}
+/** JSON-safe snapshot текущего состояния diagnostics-модуля. */
+export interface DiagnosticsSnapshot {
+    generatedAt: number;
+    trigger: 'manual' | 'automatic';
+    telemetry?: DiagnosticsTelemetrySnapshot;
+    problems?: DiagnosticsProblemsSnapshot;
+    configuration?: EndgeDiagnosticsConfiguration;
+}
+/** Обработчик одной принятой диагностической записи. */
+export type DiagnosticsListener = (record: DiagnosticsRecord) => void;
+/** Параметры подписки на diagnostics stream. */
+export interface DiagnosticsSubscribeOptions {
+    replayStored?: boolean;
+}
+/** Внутренний port, через который span пишет records в модуль. */
+export interface DiagnosticsSpanOwner {
+    /** Создаёт root или child span от имени handle. */
+    startSpan: (name: string, options?: DiagnosticsSpanOptions) => DiagnosticsSpanHandle;
+    /** Записывает нормализованный log от имени handle. */
+    log: (input: DiagnosticsLogInput) => DiagnosticsLogRecord | null;
+    /** Записывает нормализованное исключение от имени handle. */
+    recordException: (error: unknown, options?: DiagnosticsExceptionOptions) => DiagnosticsLogRecord | null;
+    /** Финализирует активный span и создаёт итоговый record. */
+    finishSpan: (input: {
+        traceId: string;
+        spanId: string;
+        parentSpanId?: string;
+        traceFlags?: number;
+        phase?: DiagnosticsPhase;
+        name: string;
+        scope: DiagnosticsInstrumentationScope;
+        startTimestamp: number;
+        attributes: DiagnosticsAttributes;
+        options?: DiagnosticsSpanEndOptions;
+    }) => DiagnosticsSpanRecord | null;
+}

package/dist/features/core/modules/document-import/EndgeDocumentImport_Module.d.ts

@@ -0,0 +1,33 @@
+import { DocumentImportApplyRequest, DocumentImportApplyResult, DocumentImportPlan, DocumentImportPrepareRequest } from './domain/types/document-import.type';
+import { EndgeModule } from '../../../federation/EndgeModule';
+/** Владеет подготовкой и применением внешних схем как Domain-документов Endge. */
+export declare class EndgeDocumentImport_Module extends EndgeModule {
+    /** Format-specific parsers и единственный активный подтверждаемый plan. */
+    private readonly _graphQLParser;
+    private readonly _openAPIParser;
+    private _activePlan;
+    private _planSequence;
+    private _applying;
+    /**
+     * ----------------------------------------
+     * PUBLIC
+     * ----------------------------------------
+     */
+    /** Разбирает внешний документ и создаёт renderer-neutral plan без изменения Domain. */
+    prepare(request: DocumentImportPrepareRequest): DocumentImportPlan;
+    /** Создаёт только подтверждённых кандидатов из ранее подготовленного plan. */
+    apply(request: DocumentImportApplyRequest): Promise<DocumentImportApplyResult>;
+    /** Сбрасывает неподтверждённый import plan при reset Core context. */
+    reset(): void;
+    /**
+     * ----------------------------------------
+     * PRIVATE
+     * ----------------------------------------
+     */
+    /** Выбирает внутренний parser без публичного registry до появления extension use case. */
+    private _resolveParser;
+    /** Проверяет сгенерированный Type Source через публичный Source owner. */
+    private _validateTypeSource;
+    /** Запрещает помещение Type в папку другого Domain section. */
+    private _assertDestination;
+}

package/dist/features/core/modules/document-import/domain/types/document-import.type.d.ts

@@ -0,0 +1,76 @@
+/** Внешние форматы, из которых Core умеет подготовить Domain-документы. */
+export type DocumentImportFormat = 'graphql' | 'openapi';
+/** Состояние кандидата относительно текущего Domain. */
+export type DocumentImportCandidateStatus = 'ready' | 'conflict' | 'invalid';
+/** Нормализованная диагностика импорта без привязки к конкретному UI. */
+export interface DocumentImportDiagnostic {
+    severity: 'info' | 'warning' | 'error';
+    code: string;
+    message: string;
+    candidateId?: string;
+    line?: number;
+    column?: number;
+}
+/** Неподдержанная конструкция исходного документа. */
+export interface DocumentImportSkippedItem {
+    kind: string;
+    identity?: string;
+    reason: string;
+}
+/** Renderer-neutral описание одного документа, доступного для выбора. */
+export interface DocumentImportCandidate {
+    id: string;
+    documentType: 'type';
+    identity: string;
+    displayName: string;
+    description?: string;
+    status: DocumentImportCandidateStatus;
+    sourcePreview: string;
+    summary: {
+        fields: number;
+        requiredFields: number;
+    };
+    diagnostics: DocumentImportDiagnostic[];
+}
+/** Публичное представление подготовленного, но ещё не применённого импорта. */
+export interface DocumentImportPlan {
+    id: string;
+    format: DocumentImportFormat;
+    sourceName?: string;
+    createdAt: string;
+    candidates: DocumentImportCandidate[];
+    diagnostics: DocumentImportDiagnostic[];
+    skipped: DocumentImportSkippedItem[];
+}
+/** Вход подготовки import plan. Source передаётся как обычный текст. */
+export interface DocumentImportPrepareRequest {
+    format: DocumentImportFormat;
+    source: string;
+    sourceName?: string;
+}
+/** Папка назначения для создаваемых документов. */
+export interface DocumentImportDestination {
+    folderId: string | number | null;
+}
+/** Подтверждённый пользователем набор кандидатов. */
+export interface DocumentImportApplyRequest {
+    planId: string;
+    selectedCandidateIds: readonly string[];
+    destination: DocumentImportDestination;
+    conflictPolicy?: 'skip';
+}
+/** Результат применения одного кандидата. */
+export interface DocumentImportApplyItemResult {
+    candidateId: string;
+    identity: string;
+    status: 'imported' | 'skipped' | 'failed';
+    message?: string;
+}
+/** Результат одной подтверждённой операции импорта. */
+export interface DocumentImportApplyResult {
+    planId: string;
+    imported: number;
+    skipped: number;
+    failed: number;
+    items: DocumentImportApplyItemResult[];
+}

package/dist/features/core/modules/document-import/services/parsers/DocumentImportParser.d.ts

@@ -0,0 +1,23 @@
+import { DocumentImportDiagnostic, DocumentImportFormat, DocumentImportSkippedItem } from '../../domain/types/document-import.type';
+/** Внутренний черновик Type, который Configurator не может изменить. */
+export interface ParsedDocumentImportCandidate {
+    id: string;
+    identity: string;
+    displayName: string;
+    description?: string;
+    source: string;
+    fields: number;
+    requiredFields: number;
+    diagnostics: DocumentImportDiagnostic[];
+}
+/** Нормализованный результат одного format-specific parser. */
+export interface DocumentImportParserResult {
+    candidates: ParsedDocumentImportCandidate[];
+    diagnostics: DocumentImportDiagnostic[];
+    skipped: DocumentImportSkippedItem[];
+}
+/** Внутренний contract парсера внешнего документного формата. */
+export interface DocumentImportParser {
+    readonly format: DocumentImportFormat;
+    parse: (source: string) => DocumentImportParserResult;
+}

package/dist/features/core/modules/document-import/services/parsers/GraphQLDocumentImportParser.d.ts

@@ -0,0 +1,7 @@
+import { DocumentImportParser, DocumentImportParserResult } from './DocumentImportParser';
+/** Преобразует GraphQL SDL в черновики Type Source без изменения Domain. */
+export declare class GraphQLDocumentImportParser implements DocumentImportParser {
+    readonly format: "graphql";
+    /** Возвращает поддержанные object/enum types и нормализует scalar aliases. */
+    parse(source: string): DocumentImportParserResult;
+}

package/dist/features/core/modules/document-import/services/parsers/OpenAPIDocumentImportParser.d.ts

@@ -0,0 +1,7 @@
+import { DocumentImportParser, DocumentImportParserResult } from './DocumentImportParser';
+/** Преобразует OpenAPI YAML/JSON components.schemas в черновики Type Source. */
+export declare class OpenAPIDocumentImportParser implements DocumentImportParser {
+    readonly format: "openapi";
+    /** Возвращает object/enum schemas и диагностики неподдержанных OpenAPI constructs. */
+    parse(source: string): DocumentImportParserResult;
+}