letopis 0.20.3 → 1.0.0

package/dist/errors.js

@@ -0,0 +1,70 @@
+/**
+ * Ошибки letopis 1.0 (план, §7.1, этап 2, п. 10). Текст — «letopis: <код>: <сообщение>», как у ошибок
+ * базы; код — имя из каталога (`error_catalog()` в lib/sql/15-errors.sql) или код самой библиотеки.
+ */
+export class LetopisError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(`letopis: ${code}: ${message}`);
+        this.name = 'LetopisError';
+        this.code = code;
+        this.detail = detail;
+    }
+}
+/** Охранник снесённого API (план, этап 3, п. 11): понятная ошибка с версией и заменой. */
+export function removed(name, replacement) {
+    return new LetopisError('removed', `${name} снят в 1.0.0 — ${replacement}`);
+}
+/** Метод зарезервирован, но появится на следующем этапе плана. */
+export function notYet(name, stage) {
+    return new LetopisError('not_implemented', `${name} появится на этапе ${stage} плана 1.0`);
+}
+/** Данные не проходят описание класса (`invalid_data`). */
+export class ValidationError extends LetopisError {
+    issues;
+    constructor(cls, issues) {
+        super('invalid_data', `данные не проходят описание класса ${cls}`, { issues });
+        this.name = 'ValidationError';
+        this.issues = issues;
+    }
+}
+/** Код SQLSTATE класса LT → имя ошибки letopis (каталог error_catalog() в базе). */
+const LT_NAMES = {
+    LT001: 'no_session', LT002: 'target_not_found', LT003: 'invalid_data', LT004: 'undeclared_end', LT005: 'tenant_denied',
+    LT006: 'acl_denied', LT007: 'id_mismatch', LT008: 'id_from_db', LT009: 'immutable_key', LT010: 'invalid_class',
+    LT011: 'use_reclass', LT012: 'reclass_denied', LT013: 'tightening_conflict', LT014: 'isolation_level',
+    LT015: 'recreated_in_statement', LT016: 'cursor_expired', LT017: 'delete_restricted', LT018: 'not_deleted',
+    LT019: 'reset_disabled', LT020: 'confirm_mismatch',
+};
+/**
+ * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL
+ * (JSON) переносятся в detail; прочие ошибки возвращаются как есть.
+ */
+export function fromDbError(e) {
+    const err = e;
+    // новые значения строки не проходят условие ACL (политика RLS WITH CHECK) — отказ по правам; upsert,
+    // которому существующую строку менять нельзя («USING expression»), остаётся 42501 (§2.5). Признак —
+    // функция сервера, а не текст: текст зависит от языка сервера
+    if (err.code === '42501' && err.routine === 'ExecWithCheckOptions' && !/USING/.test(err.message ?? '')) {
+        return Object.assign(new LetopisError('acl_denied', 'новые значения строки запрещают правила доступа'), { cause: e });
+    }
+    const name = err.code ? LT_NAMES[err.code] : undefined;
+    if (!name)
+        return e;
+    let detail;
+    try {
+        detail = err.detail ? JSON.parse(err.detail) : undefined;
+    }
+    catch {
+        detail = err.detail;
+    }
+    const text = (err.message ?? '').replace(/^letopis: [a-z_]+: /, '');
+    const issues = detail?.issues;
+    if (name === 'invalid_data' && Array.isArray(issues)) {
+        const cls = /класса (\S+)/.exec(text)?.[1] ?? '?';
+        const v = new ValidationError(cls, issues);
+        return Object.assign(v, { cause: e });
+    }
+    return Object.assign(new LetopisError(name, text, detail), { cause: e });
+}

package/dist/import.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Импорт из letopis 0.21 (план, этап 7, п. 1): `letopis import --from <строка 0.21> --from-schema v1.x`.
+ *
+ * Читает таблицы 0.21 (Schema, Entity, Account, Credential, Resource, Rule) из её собственной базы —
+ * PostgreSQL 17 с TimescaleDB или обычный дамп таблиц — и пишет в установку 1.0:
+ *   - Schema → строки Class арендатора System (их видят все арендаторы): правила fastest-validator →
+ *     JSON Schema, концы — роли по имени класса цели, союз всех конкретных потомков класса —
+ *     полиморфный конец этого класса; корни без своих полей и концов (Entity, link) опускаются;
+ *     description, appearance, order → meta; ссылка на класс в данных, не объявленная концом, —
+ *     необязательный конец (в отчёте);
+ *   - Entity → загрузчиком в режиме истории (existing: 'skip', агент «letopis import»): версии по
+ *     порядку, надгробия — op delete, следующая за ним версия — create; id классов с ключом — v5 от
+ *     ключа (§2.3), без ключа — v5 от старого id ($ext); данные System — в арендатора --tenant;
+ *   - Account → строки Account (id — v5 от старого; System → System), Credential → secret (хэши scrypt
+ *     и ключей как есть, OTP — нет), Resource и Rule → строки Resource и rule в System.
+ * До первой записи импорт проверяет всё, что его остановит: два объекта с одним id 1.0 (нарушение
+ * ключа — опция keyless), ключ, менявшийся между версиями, ключ со ссылкой на отсутствующий объект.
+ * Висячие ссылки живых строк останавливает загрузчик (target_not_found) — отчёт называет строки 0.21.
+ * Шаги (классы, аккаунты, креды, права, данные арендатора) — отдельные транзакции; повтор дописывает
+ * недостающее и дублей не создаёт.
+ */
+import postgres from 'postgres';
+import { type JsonSchema } from './jsonschema.js';
+type Raw = Record<string, unknown>;
+type Sql = postgres.Sql<Record<string, unknown>>;
+export interface ImportOptions {
+    /** Строка подключения к базе 0.21 (или готовый пул). */
+    from: string | Sql;
+    /** Схема 0.21: v1.<имя>. */
+    fromSchema: string;
+    /** Партиция 0.21 (по умолчанию entity). */
+    partition?: string;
+    /** Администраторская строка подключения к установке 1.0. */
+    dsn: string;
+    /** Схема 1.0: v2.<имя>. */
+    schema: string;
+    /** Роль-владелец схемы 1.0 (по умолчанию letopis_owner). */
+    owner?: string;
+    /** Имя арендатора для данных аккаунта System (полигоны 0.21 записаны от его имени). */
+    tenant?: string;
+    /** Классы, которые импортируются без ключа: старый id — внешний ключ (объявленное расхождение). */
+    keyless?: string[];
+    /** Переименования классов: имена, занятые методами 1.0 и системными классами (иначе — имя + «_»). */
+    rename?: Record<string, string>;
+    /** Существующим объектам — новая версия из последней версии 0.21, если содержимое отличается. */
+    update?: boolean;
+    /** Порции загрузчика (§2.6, п. 8). */
+    commitEvery?: number;
+    /** Без сообщений в консоль. */
+    quiet?: boolean;
+}
+/** Непереведённое правило или иное расхождение описания класса. */
+export interface ImportNote {
+    class: string;
+    field?: string;
+    note: string;
+}
+export interface ClassCount {
+    objects: number;
+    versions: number;
+    live: number;
+}
+export interface ImportReport {
+    classes: {
+        created: string[];
+        existing: string[];
+        omitted: string[];
+        renamed: Record<string, string>;
+        keyless: string[];
+    };
+    /** Правила fastest-validator и концы, перенесённые не один к одному. */
+    notes: ImportNote[];
+    /** Число объектов, версий и живых строк по классам: в 0.21 и в 1.0 после импорта. */
+    source: Record<string, ClassCount>;
+    target: Record<string, ClassCount>;
+    tenants: {
+        old: string;
+        id: string;
+        name: string;
+    }[];
+    accounts: {
+        loaded: number;
+        skipped: number;
+    };
+    credentials: {
+        imported: number;
+        skipped: number;
+        otp: number;
+        conflicts: {
+            account: string;
+            kind: string;
+            ident: string;
+        }[];
+    };
+    resources: {
+        loaded: number;
+        skipped: number;
+    };
+    rules: {
+        loaded: number;
+        skipped: number;
+    };
+    objects: {
+        loaded: number;
+        skipped: number;
+        updated: number;
+    };
+    /** Поля data живых строк, в которых лежат uuid, совпадающие со старыми id (импорт их не переписывает). */
+    uuidFields: Record<string, number>;
+    /** Отброшенные поля данных, имя которых начинается с $ (метасхема 1.0 их не принимает). */
+    droppedFields: Record<string, number>;
+    /** Строк, у которых владелец не найден среди аккаунтов (владелец — арендатор). */
+    ownerLost: number;
+    verify: {
+        ok: boolean;
+        issues: number;
+        anchor: string;
+    };
+    ms: number;
+}
+/** Строка ошибки импорта: класс и id 0.21 и, для ошибок загрузчика, версия. */
+export interface ImportIssue {
+    code: string;
+    message: string;
+    class: string;
+    id: string;
+    rev?: number;
+}
+interface Conv {
+    s: JsonSchema;
+    optional: boolean;
+    dflt: boolean;
+}
+declare function conv(rule: unknown, cls: string, path: string, notes: ImportNote[]): Conv;
+interface SchemaRow {
+    id: string;
+    alias: string;
+    category: 'HUB' | 'LINK';
+    ancestor: string | null;
+    attributes: Raw;
+    links: unknown[];
+    meta: Raw;
+    order: number;
+    ancestors: string[];
+}
+/** Часть ключа 1.0: роль конца (классы 0.21) или поле данных. */
+type KeyPart = {
+    end: string;
+    classes: string[];
+} | {
+    field: string;
+};
+/** Класс 1.0 после перевода: описание и правила id для данных. */
+interface Cls {
+    old: string;
+    name: string;
+    desc: Raw;
+    /** Роль по классу цели 0.21 (конкретный класс → роль). */
+    roleOf: Map<string, string>;
+    /** Собственный ключ (undefined — наследуется). */
+    ownKey?: KeyPart[];
+    /** Поля на $ — отбрасываются из данных. */
+    dropped: string[];
+    history: boolean;
+}
+interface Built {
+    classes: Map<string, Cls>;
+    omitted: string[];
+    renamed: Record<string, string>;
+    keyless: string[];
+    notes: ImportNote[];
+    /** Эффективный ключ класса (собственный или унаследованный; [] — без ключа). */
+    keyOf(old: string): KeyPart[];
+    /** Конкретные (не абстрактные) классы, принимаемые концом из классов 0.21 (с потомками). */
+    family(old: string): string[];
+}
+declare function buildClasses(rows: SchemaRow[], observed: Map<string, Set<string>>, opts: ImportOptions): Built;
+export declare function import021(opts: ImportOptions): Promise<ImportReport>;
+export { buildClasses as _buildClasses, conv as _convRule };