letopis 0.21.0 → 1.0.0

package/scripts/gen-types.mjs

@@ -1,350 +0,0 @@
-#!/usr/bin/env node
-/**
- * Генерация TS-типов из таблицы Schema:
- *   npx tsx scripts/gen-types.mjs --dsn=postgres://… --schema=v1.booking [--out=entity-types.d.ts]
- *
- * Результат: интерфейсы data-полей каждого класса (с УЧЁТОМ наследования attributes),
- * типизированные цепочки на класс, слоты связей из Schema.links и два фасада:
- *
- *   import type { TypedDb, TypedFullDb } from './entity-types';
- *   const t = db as unknown as TypedDb;       // строго: только шаги по классам, опечатка = ошибка tsc
- *   const t = db as unknown as TypedFullDb;   // удобно: + begin/batch/auth/acl/tables (опечатки НЕ ловятся)
- *   await t.Мастер(и).навык().Услуга().rows()          // data типизирована по классу шага
- *   await t.Мастер(и).запись().create({ notes: 'x' }).Услуга.set(s).rows()
- */
-//
-// FILE: lib/scripts/gen-types.mjs
-// VERSION: 1.1.0
-// START_MODULE_CONTRACT
-//   PURPOSE: CLI-кодген — читает таблицу Schema и печатает типизированный .d.ts-фасад (Data-интерфейсы классов с наследованием + ChainOps/Steps/слоты + TypedDb/TypedFullDb).
-//   SCOPE: парсинг аргументов, чтение Schema, слияние attributes по ancestors, конвертация fastest-validator DSL → TS (ts), разбор Schema.links в слоты, эмиссия .d.ts.
-//   DEPENDS: none
-//   LINKS: M-GEN-TYPES, V-M-GEN-TYPES
-//   ROLE: SCRIPT
-//   MAP_MODE: LOCALS
-// END_MODULE_CONTRACT
-//
-// START_MODULE_MAP
-//   RESERVED - имена, которые chain/db-Proxy перехватывает ДО резолва класса (шаг недостижим под этим именем)
-//   ts - fastest-validator DSL → TS-тип ({ t, opt })
-//   ident - безопасный идентификатор либо строковый ключ
-//   typeName - имя генерируемого типа из id класса (без коллизий со служебными)
-//   mergedAttrs - attributes класса со слиянием по ancestors (предок → потомок поверх)
-//   endsOf - Schema.links → список концов { classes, optional }
-//   sql/rows - чтение классов из таблицы Schema
-//   lines/steps - аккумуляторы генерируемого .d.ts
-// END_MODULE_MAP
-//
-// START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.1.0 - Фасад приведён к текущему API: убраны снесённые execute()/set(data) и глушащая
-//     индекс-сигнатура; добавлены run/create/update/delete/purge/withDeleted/deep/агрегации и слоты
-//     .Класс.set()/.unset() из Schema.links; attributes теперь наследуются по ancestors; шаги по классам
-//     типизированы (опечатка = ошибка компиляции); зарезервированные имена исключены из шагов]
-// END_CHANGE_SUMMARY
-import { writeFile } from 'node:fs/promises';
-import postgres from 'postgres';
-
-// START_BLOCK_PARSE_ARGS
-const args = Object.fromEntries(process.argv.slice(2).map((a) => a.replace(/^--/, '').split('=')));
-const dsn = args.dsn ?? process.env.ENTITY_DSN;
-const schema = args.schema ?? 'booking';
-const out = args.out ?? 'entity-types.d.ts';
-if (!dsn) { console.error('usage: tsx scripts/gen-types.mjs --dsn=… --schema=v1.booking [--out=…]'); process.exit(1); }
-
-// END_BLOCK_PARSE_ARGS
-// START_BLOCK_RESERVED_NAMES
-/**
- * Proxy проверяет эти имена ДО ctx.registry.has(prop) (см. lib/src/chain.ts: switch в
- * makeChain-handler и в makeDb-handler), поэтому класс с таким id/alias недостижим как шаг
- * под этим именем. Здесь они ИСКЛЮЧАЮТСЯ из типизированных шагов — иначе типы обещали бы
- * вызов, который в рантайме уходит в модификатор/терминал или в migration-ошибку.
- * Список сверяется с case-метками chain.ts в scripts/check-docs.mjs.
- */
-const RESERVED = new Set([
-  // все три handler'а
-  'then',
-  // chain-уровень
-  'entity', 'run', 'execute', 'rows', 'first', 'ids', 'count', 'limit', 'offset', 'sort',
-  'asOf', 'withDeleted', 'deep', 'exact', 'sum', 'avg', 'min', 'max', 'countBy', 'after', 'versions',
-  'create', 'update', 'set', 'delete', 'anonymize', 'purge', 'alias', 'tags', 'account',
-  'owner',
-  // batch-уровень
-  'discard', 'size',
-  // db-уровень: switch + фасады, разбираемые if'ами до switch
-  'as', 'begin', 'commit', 'rollback', 'lock', 'batch', 'watch', 'close', 'reloadSchema',
-  'registry', 'sql', 'accounts', 'credentials', 'resources', 'rules', 'schema', 'auth', 'acl',
-]);
-
-// END_BLOCK_RESERVED_NAMES
-// START_CONTRACT: ts
-//   PURPOSE: Свести attribute-спеку fastest-validator (строка/массив/объект) к TS-типу и признаку optional.
-//   INPUTS: { attr: unknown - правило поля }
-//   OUTPUTS: { { t: string; opt: boolean } }
-//   SIDE_EFFECTS: none (рекурсивно по вложенным props/items)
-//   LINKS: M-GEN-TYPES, V-M-GEN-TYPES
-// END_CONTRACT: ts
-// fastest-validator DSL → TS-тип
-function ts(attr) {
-  if (typeof attr === 'string') {
-    const parts = attr.split('|').map((s) => s.trim());
-    const opt = parts.includes('optional');
-    const base = { number: 'number', boolean: 'boolean', date: 'string', string: 'string', uuid: 'string', email: 'string', url: 'string', any: 'unknown' }[parts[0]] ?? 'unknown';
-    return { t: base, opt };
-  }
-  if (Array.isArray(attr)) { const first = ts(attr[0] ?? 'any'); return { t: first.t, opt: true }; }
-  if (typeof attr === 'object' && attr !== null) {
-    const opt = attr.optional === true;
-    switch (attr.type) {
-      case 'enum': return { t: (attr.values ?? []).map((v) => JSON.stringify(v)).join(' | ') || 'string', opt };
-      case 'record': {
-        const key = attr.key?.type === 'enum' ? (attr.key.values ?? []).map((v) => JSON.stringify(v)).join(' | ') : 'string';
-        return { t: `Partial<Record<${key || 'string'}, number>>`, opt };
-      }
-      case 'array': {
-        const item = ts(attr.items ?? 'any');
-        return { t: `(${item.t})[]`, opt };
-      }
-      case 'number': return { t: 'number', opt };
-      case 'boolean': return { t: 'boolean', opt };
-      case 'date': return { t: 'string', opt };
-      case 'string': case 'uuid': case 'email': case 'url': return { t: 'string', opt };
-      case 'object': {
-        const props = attr.props ?? attr.properties;
-        if (props && typeof props === 'object') {
-          const fields = Object.entries(props)
-            .map(([k, v]) => { const f = ts(v); return `${ident(k)}${f.opt ? '?' : ''}: ${f.t}`; })
-            .join('; ');
-          return { t: `{ ${fields} }`, opt };
-        }
-        return { t: 'Record<string, unknown>', opt };
-      }
-      default: return { t: 'unknown', opt };
-    }
-  }
-  return { t: 'unknown', opt: true };
-}
-
-const ident = (s) => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s) ? s : JSON.stringify(s));
-
-// служебные имена генерируемого файла — класс с таким id получит суффикс, чтобы не затенять
-const OWN_TYPES = new Set(['TypedRow', 'ChainOps', 'Steps', 'AnyChain', 'TypedDb', 'TypedFullDb', 'SlotTarget']);
-// START_CONTRACT: typeName
-//   PURPOSE: Построить безопасное имя генерируемого типа из id класса.
-//   INPUTS: { id: string - id класса; suffix: string - 'Data' | 'Chain' | 'Slots' }
-//   OUTPUTS: { string - имя типа, не конфликтующее со служебными }
-//   SIDE_EFFECTS: none
-//   LINKS: M-GEN-TYPES, V-M-GEN-TYPES
-// END_CONTRACT: typeName
-function typeName(id, suffix) {
-  const base = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(id) ? id : id.replace(/[^A-Za-z0-9_$]/g, '_');
-  const name = `${base}${suffix}`;
-  return OWN_TYPES.has(name) ? `${name}_` : name;
-}
-
-// START_BLOCK_READ_SCHEMA
-const sql = postgres(dsn, { max: 1 });
-const rows = await sql.unsafe(
-  `SELECT id, alias, category, ancestor, ancestors, attributes, links, meta FROM "${schema.replaceAll('"', '""')}"."Schema" WHERE partition = 'entity' ORDER BY category, "order"`,
-);
-await sql.end();
-const byId = new Map(rows.map((r) => [r.id, r]));
-
-// END_BLOCK_READ_SCHEMA
-// START_CONTRACT: mergedAttrs
-//   PURPOSE: Слить attributes класса по цепочке ancestors (предок → потомок поверх), как это делает M-SCHEMA.buildDef.
-//   INPUTS: { r: object - строка Schema }
-//   OUTPUTS: { Record<string, unknown> - слитые attributes }
-//   SIDE_EFFECTS: none
-//   LINKS: M-GEN-TYPES, M-SCHEMA, V-M-GEN-TYPES
-// END_CONTRACT: mergedAttrs
-function mergedAttrs(r) {
-  // attributes НАСЛЕДУЮТСЯ (lib/src/schema.ts: buildDef); links — НЕТ
-  let chain = Array.isArray(r.ancestors) && r.ancestors.length ? r.ancestors : null;
-  if (!chain) {
-    chain = [r.id];
-    let cur = r.ancestor;
-    const seen = new Set([r.id]);
-    while (cur && !seen.has(cur)) { chain.push(cur); seen.add(cur); cur = byId.get(cur)?.ancestor ?? null; }
-  }
-  const merged = {};
-  for (let i = chain.length - 1; i >= 0; i--) Object.assign(merged, byId.get(chain[i])?.attributes ?? {});
-  return merged;
-}
-
-// START_CONTRACT: endsOf
-//   PURPOSE: Разобрать Schema.links класса в список концов (как M-SCHEMA.parseEnd, без валидации).
-//   INPUTS: { r: object - строка Schema }
-//   OUTPUTS: { { classes: string[]; optional: boolean }[] }
-//   SIDE_EFFECTS: none
-//   LINKS: M-GEN-TYPES, M-SCHEMA, V-M-GEN-TYPES
-// END_CONTRACT: endsOf
-function endsOf(r) {
-  let raw = r.links ?? [];
-  if (typeof raw === 'string') { try { raw = JSON.parse(raw); } catch { return []; } }
-  if (!Array.isArray(raw)) return [];
-  return raw.map((e) => {
-    if (typeof e === 'string') {
-      if (!e.trimStart().startsWith('{')) return { classes: [e], optional: false };
-      try { e = JSON.parse(e); } catch { return null; }
-    }
-    const classes = e.classes ?? (e.class ? [e.class] : []);
-    return classes.length ? { classes, optional: e.optional === true } : null;
-  }).filter(Boolean);
-}
-
-// START_BLOCK_EMIT_HEADER
-const lines = [
-  '/* Сгенерировано scripts/gen-types.mjs — не редактировать вручную. */',
-  `/* Схема: ${schema} · классов: ${rows.length} */`,
-  '',
-  `import type { Row, Path, Filter, Cursor, Chain, EntityDb } from 'letopis';`,
-  '',
-  'export interface TypedRow<D> extends Omit<Row, \'data\'> { data: D }',
-  '',
-  '/** Цель слота связи: id | Row/сущность с id | вложенная цепочка (та же транзакция). */',
-  'export type SlotTarget = string | { id: string } | Chain;',
-  '',
-  '/**',
-  ' * Терминалы, модификаторы и глаголы записи цепочки. Self — тип конкретной цепочки-класса,',
-  ' * поэтому модификаторы и глаголы записи сохраняют типизацию data.',
-  ' * ВНИМАНИЕ: create/update/delete/purge/anonymize возвращают ЦЕПОЧКУ (звено плана),',
-  ' * исполняет её терминал (.rows()/.run()/…), а не сам глагол.',
-  ' */',
-  'export interface ChainOps<D, Self> {',
-  '  /** Пути: [{шаг1: Row, шаг2: Row, …}, …]. */',
-  '  run(): Promise<Path[]>;',
-  '  /** Уникальные сущности последнего шага. */',
-  '  rows(): Promise<TypedRow<D>[]>;',
-  '  first(): Promise<TypedRow<D> | null>;',
-  '  ids(): Promise<string[]>;',
-  '  /** Число ПУТЕЙ. */',
-  '  count(): Promise<number>;',
-  '  /** ВСЕ версии сущностей последнего шага, по возрастанию updated. */',
-  '  versions(): Promise<TypedRow<D>[]>;',
-  '  sum(field: string): Promise<number | null>;',
-  '  avg(field: string): Promise<number | null>;',
-  '  min(field: string): Promise<unknown>;',
-  '  max(field: string): Promise<unknown>;',
-  '  countBy(field: string): Promise<Record<string, number>>;',
-  '  limit(n: number): Self;',
-  '  offset(n: number): Self;',
-  '  sort(field: string, dir?: \'asc\' | \'desc\' | boolean): Self;',
-  '  /** Чтение «как было на момент T». */',
-  '  asOf(t: string | Date): Self;',
-  '  /** Keyset-пагинация; требует .sort(). */',
-  '  after(cursor: Cursor): Self;',
-  '  /** Включить удалённые (tombstone) в выдачу последнего шага. */',
-  '  withDeleted(): Self;',
-  '  /** Рекурсивный self-обход: дети любой глубины (тот же класс). */',
-  '  deep(max?: number): Self;',
-  '  /** Снять полиморфизм шага: только свой класс, без классов-потомков. */',
-  '  exact(): Self;',
-  '  alias(name: string): Self;',
-  '  tags(v: string | string[] | object): Self;',
-  '  account(v: string | { id: string }): Self;',
-  '  owner(v: string | { id: string }): Self;',
-  '  /** Вклейка узла/паттерна — тип шага не выводится, отсюда AnyChain. */',
-  '  entity(x: Chain | Row): AnyChain;',
-  '  /** Звено: вставить сущность. id — по Schema (v4/v7/v5); фильтр-объект перед create() — ошибка. */',
-  '  create(data?: Partial<D> & { id?: string }): Self;',
-  '  /** Звено: новая версия каждой найденной путём (deep-merge листьев data). */',
-  '  update(data?: Partial<D>): Self;',
-  '  /** Звено: без confirm — превью (БД не тронута); { confirm: true } — tombstone + каскад. */',
-  '  delete(opts?: { confirm?: boolean }): Self;',
-  '  /** Звено: ФИЗИЧЕСКИЙ hard-erase уже удалённых (tombstone). Живую сущность не трогает — вернёт пусто. */',
-  '  purge(opts?: { confirm?: boolean }): Self;',
-  '  /** Звено: затереть string-поля + тег anonymized. */',
-  '  anonymize(fields: (keyof D & string)[]): Self;',
-  '}',
-  '',
-];
-
-// END_BLOCK_EMIT_HEADER
-// START_BLOCK_EMIT_CLASSES
-const steps = [];
-const skipped = [];
-for (const r of rows) {
-  if (r.meta?.abstract === true || r.meta?.abstract === 'true') continue;
-  const dataT = typeName(r.id, 'Data');
-  const chainT = typeName(r.id, 'Chain');
-  const slotsT = typeName(r.id, 'Slots');
-
-  lines.push(`/** ${r.category} ${r.id} · ${r.alias} */`, `export interface ${dataT} {`);
-  for (const [f, attr] of Object.entries(mergedAttrs(r))) {
-    if (f === 'id' || f.startsWith('$$')) continue;
-    const { t, opt } = ts(attr);
-    lines.push(`  ${ident(f)}${opt ? '?' : ''}: ${t};`);
-  }
-  lines.push('}', '');
-
-  // слоты: концы Schema.links владельца; союз задаётся ЛЮБЫМ своим классом; unset() — только optional
-  const ends = endsOf(r);
-  const slotKeys = [];
-  for (const end of ends) {
-    for (const c of end.classes) {
-      const target = byId.get(c);
-      for (const key of target ? [target.id, target.alias] : [c]) {
-        if (slotKeys.some((s) => s.key === key)) continue;
-        slotKeys.push({ key, optional: end.optional });
-      }
-    }
-  }
-  if (slotKeys.length) {
-    lines.push(`/** Концы связей ${r.id} (Schema.links): .Класс.set(target) / .unset(). */`, `export interface ${slotsT} {`);
-    for (const { key, optional } of slotKeys) {
-      const body = optional
-        ? `{ set(target: SlotTarget): ${chainT}; unset(): ${chainT} }`
-        : `{ set(target: SlotTarget): ${chainT} }`;
-      lines.push(`  ${ident(key)}: ${body};`);
-    }
-    lines.push('}', '');
-  }
-
-  lines.push(
-    `export type ${chainT} = ChainOps<${dataT}, ${chainT}> & Steps${slotKeys.length ? ` & ${slotsT}` : ''};`,
-    '',
-  );
-
-  const names = [r.id, r.alias].filter((n, i, a) => a.indexOf(n) === i);
-  const usable = names.filter((n) => !RESERVED.has(n));
-  if (!usable.length) { skipped.push(`${r.id}·${r.alias}`); continue; }
-  for (const n of names) {
-    if (RESERVED.has(n)) {
-      steps.push(`  /** ⚠ "${n}" зарезервировано цепочкой — шаг доступен как ${usable.map((u) => `\`${u}\``).join(' / ')}. */`);
-      continue;
-    }
-    steps.push(`  ${ident(n)}(filter?: Filter): ${chainT};`);
-  }
-}
-
-// END_BLOCK_EMIT_CLASSES
-// START_BLOCK_EMIT_FACADE
-lines.push(
-  '/**',
-  ' * Шаги по классам — доступны с любой цепочки и с корня db. ЗАКОННОСТЬ перехода',
-  ' * (HUB↔LINK, pivot, «no path X → Y») проверяет letopis синхронно при построении цепочки;',
-  ' * типы этого не гарантируют — они ловят опечатки в именах и типизируют data шага.',
-  ' */',
-  'export interface Steps {',
-  ...steps,
-  '}',
-  '',
-  '/** Цепочка с невыведенным классом шага (результат entity()). */',
-  'export type AnyChain = ChainOps<Record<string, unknown>, AnyChain> & Steps;',
-  '',
-  '/** Строгий фасад: только шаги по классам — опечатка в имени класса = ошибка компиляции. */',
-  'export type TypedDb = Steps;',
-  '',
-  '/** Полный фасад: шаги + begin/batch/watch/auth/acl/служебные таблицы.',
-  '  * Индекс-сигнатура EntityDb означает, что опечатки здесь НЕ ловятся. */',
-  'export type TypedFullDb = Steps & EntityDb;',
-  '',
-);
-if (skipped.length) {
-  lines.push(`/* Без типизированного шага (все имена зарезервированы цепочкой): ${skipped.join(', ')} */`, '');
-}
-
-// END_BLOCK_EMIT_FACADE
-await writeFile(out, lines.join('\n'), 'utf8');
-console.log(`written ${out}: ${rows.length} classes`);
-if (skipped.length) console.warn(`gen-types: пропущены шаги для ${skipped.join(', ')} — имена зарезервированы цепочкой`);

package/scripts/release-notes.mjs

@@ -1,76 +0,0 @@
-#!/usr/bin/env node
-/**
- * Печатает в stdout секцию CHANGELOG для ТЕКУЩЕЙ версии пакета — тело релизного PR.
- *
- *   cd lib && node scripts/release-notes.mjs                     # посмотреть
- *   gh pr create --base main --head dev --title "Release: …" \
- *     --body "$(cd lib && node scripts/release-notes.mjs)"        # так и создавать PR
- *
- * Зачем: описание PR было единственным местом контура, где текст писался заново, хотя тот же
- * текст уже есть в lib/CHANGELOG.md — источнике истины версии (его сверяет check-docs.mjs с
- * package.json). Цепочка становится без дублирования:
- *
- *   lib/CHANGELOG.md (руками) → описание PR → тело релиза (release.yml берёт из PR) → npm
- *
- * Версия НЕ передаётся аргументом намеренно: берётся из package.json, чтобы нельзя было
- * выпустить заметки одной версии под тегом другой.
- */
-//
-// FILE: lib/scripts/release-notes.mjs
-// VERSION: 1.0.0
-// START_MODULE_CONTRACT
-//   PURPOSE: Вырезать из lib/CHANGELOG.md секцию текущей версии пакета и напечатать её — тело релизного PR, из которого release.yml берёт заметки релиза.
-//   SCOPE: чтение package.json + CHANGELOG, извлечение секции, печать в stdout.
-//   DEPENDS: none
-//   LINKS: M-RELEASE-NOTES, V-M-RELEASE-NOTES
-//   ROLE: SCRIPT
-//   MAP_MODE: LOCALS
-// END_MODULE_CONTRACT
-//
-// START_MODULE_MAP
-//   section - (local) секция CHANGELOG по версии: от "## [x.y.z]" до следующей "## ["
-// END_MODULE_MAP
-//
-// START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Новый скрипт: тело релизного PR берётся из CHANGELOG, а не пишется заново]
-// END_CHANGE_SUMMARY
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-import { join } from 'node:path';
-
-const LIB = fileURLToPath(new URL('..', import.meta.url));
-
-// START_CONTRACT: section
-//   PURPOSE: Достать из текста CHANGELOG секцию конкретной версии (без её заголовка).
-//   INPUTS: { changelog: string - текст lib/CHANGELOG.md; version: string - x.y.z }
-//   OUTPUTS: { string - тело секции; пусто, если версии в файле нет }
-//   SIDE_EFFECTS: none
-//   LINKS: M-RELEASE-NOTES, V-M-RELEASE-NOTES
-// END_CONTRACT: section
-function section(changelog, version) {
-  const start = changelog.indexOf(`## [${version}]`);
-  if (start < 0) return '';
-  const after = changelog.indexOf('\n## [', start + 1);
-  const body = changelog.slice(changelog.indexOf('\n', start) + 1, after < 0 ? undefined : after);
-  return body.trim();
-}
-
-const [pkgRaw, changelog] = await Promise.all([
-  readFile(join(LIB, 'package.json'), 'utf8'),
-  readFile(join(LIB, 'CHANGELOG.md'), 'utf8'),
-]);
-const { version } = JSON.parse(pkgRaw);
-const body = section(changelog, version);
-
-if (!body) {
-  console.error(
-    `release-notes: в lib/CHANGELOG.md нет записи "## [${version}]" — подними версию в ` +
-      'package.json или добавь запись (то же самое проверяет npm run check:docs)',
-  );
-  process.exit(1);
-}
-
-// Ссылку на полный changelog добавляем всегда: релиз читают из GitHub, а не из репозитория.
-process.stdout.write(
-  `${body}\n\n---\n\nПолный changelog — [lib/CHANGELOG.md](https://github.com/alepri51/letopis/blob/main/lib/CHANGELOG.md).\n`,
-);

package/scripts/schema-sync.mjs

@@ -1,185 +0,0 @@
-#!/usr/bin/env node
-/**
- * Миграция классов: diff JSON-файла схемы и таблицы Schema + отчёт совместимости.
- * Ловит ломающие изменения ДО применения: новый валидатор прогоняется по живым
- * latest-строкам каждого изменённого класса (строгая валидация, как в рантайме).
- *
- *   node scripts/schema-sync.mjs --file=my-schema.json --dsn=… --schema=v1.booking
- *   node scripts/schema-sync.mjs --file=… --dsn=… --schema=v1.booking --apply
- *
- * Без --apply — только отчёт (exit 1, если есть несовместимые строки).
- * Классы, отсутствующие в файле, НЕ удаляются (append-only дух; удаление — вручную).
- * ancestors/descendants пересчитывает триггер schema_lineage.
- */
-//
-// FILE: lib/scripts/schema-sync.mjs
-// VERSION: 1.0.0
-// START_MODULE_CONTRACT
-//   PURPOSE: CLI-миграция схемы — diff JSON-файла и таблицы Schema, ревалидация выборки живых строк, upsert классов при --apply.
-//   SCOPE: парсинг аргументов, канон-сериализация (stable/linkEnd), diff added/changed/removed, проверка совместимости, apply.
-//   DEPENDS: none
-//   LINKS: M-SCHEMA-SYNC, V-M-SCHEMA-SYNC
-//   ROLE: SCRIPT
-//   MAP_MODE: LOCALS
-// END_MODULE_CONTRACT
-//
-// START_MODULE_MAP
-//   stable - стабильная сериализация для сравнения
-//   linkEnd/linksCanon - канон элементов Schema.links
-//   FIELDS - поля класса для diff/upsert
-//   added/changed/removed - результат diff файла и БД
-//   breakingRows - живые строки, ломающиеся о новую валидацию
-// END_MODULE_MAP
-//
-// START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
-// END_CHANGE_SUMMARY
-import { readFile } from 'node:fs/promises';
-import { createRequire } from 'node:module';
-import postgres from 'postgres';
-
-const Validator = createRequire(import.meta.url)('fastest-validator');
-const v = new Validator({ useNewCustomCheckerFunction: true });
-
-// START_BLOCK_PARSE_ARGS
-const args = Object.fromEntries(
-  process.argv.slice(2).map((a) => {
-    const m = a.match(/^--([^=]+)(?:=(.*))?$/);
-    return m ? [m[1], m[2] ?? true] : [a, true];
-  }),
-);
-const { file, schema } = args;
-const dsn = args.dsn ?? process.env.ENTITY_DSN;
-const partition = args.partition ?? 'entity';
-const sample = Number(args.sample ?? 200);
-if (!file || !dsn || !schema || typeof schema !== 'string') {
-  console.error('usage: node scripts/schema-sync.mjs --file=schema.json --dsn=… --schema=<pg_schema> [--partition=entity] [--sample=200] [--apply]');
-  process.exit(1);
-}
-
-// END_BLOCK_PARSE_ARGS
-const ident = `"${schema.replaceAll('"', '""')}"`;
-/** Поля класса, участвующие в diff и upsert (lineage-колонки считает триггер). */
-const FIELDS = ['alias', 'category', 'ancestor', 'attributes', 'links', 'meta', 'order'];
-
-// START_CONTRACT: stable
-//   PURPOSE: Стабильная сериализация значения (сортировка ключей на всех уровнях) для сравнения diff.
-//   INPUTS: { x: unknown }
-//   OUTPUTS: { string - канонический вид }
-//   SIDE_EFFECTS: none
-//   LINKS: M-SCHEMA-SYNC, V-M-SCHEMA-SYNC
-// END_CONTRACT: stable
-/** Стабильная сериализация для сравнения (сортировка ключей на всех уровнях). */
-function stable(x) {
-  if (Array.isArray(x)) return `[${x.map(stable).join(',')}]`;
-  if (typeof x === 'object' && x !== null)
-    return `{${Object.keys(x).sort().map((k) => `${JSON.stringify(k)}:${stable(x[k])}`).join(',')}}`;
-  return JSON.stringify(x ?? null);
-}
-
-// START_CONTRACT: linkEnd
-//   PURPOSE: Привести элемент links к канону (конец v2: в БД JSON-текст в text[], в файле — объект).
-//   INPUTS: { e: string|object }
-//   OUTPUTS: { string }
-//   SIDE_EFFECTS: none
-//   LINKS: M-SCHEMA-SYNC, V-M-SCHEMA-SYNC
-// END_CONTRACT: linkEnd
-/** Элемент links к канону: в БД конец v2 лежит JSON-текстом в text[], в файле — объектом. */
-function linkEnd(e) {
-  if (typeof e === 'string' && e.trimStart().startsWith('{')) return stable(JSON.parse(e));
-  return typeof e === 'string' ? JSON.stringify(e) : stable(e);
-}
-const linksCanon = (arr) => `[${(arr ?? []).map(linkEnd).join(',')}]`;
-
-const fileClasses = JSON.parse(await readFile(file, 'utf8'));
-const sql = postgres(dsn, { max: 1 });
-
-try {
-  // START_BLOCK_DIFF
-  const dbRows = await sql.unsafe(
-    `SELECT id, alias, category, ancestor, attributes, links, meta, "order" FROM ${ident}."Schema" WHERE partition = $1`,
-    [partition],
-  );
-  const inDb = new Map(dbRows.map((r) => [r.id, r]));
-  const inFile = new Map(fileClasses.map((c) => [c.id, c]));
-
-  const added = fileClasses.filter((c) => !inDb.has(c.id));
-  const removed = dbRows.filter((r) => !inFile.has(r.id));
-  const changed = [];
-  for (const c of fileClasses) {
-    const db = inDb.get(c.id);
-    if (!db) continue;
-    const diff = FIELDS.filter((f) =>
-      f === 'links'
-        ? linksCanon(c.links) !== linksCanon(db.links)
-        : stable(c[f] ?? (f === 'order' ? 0 : f === 'ancestor' ? null : {})) !== stable(db[f]));
-    if (diff.length) changed.push({ cls: c, fields: diff });
-  }
-
-  // END_BLOCK_DIFF
-  console.log(`schema-sync: ${file} ↔ ${schema}.Schema (partition ${partition})`);
-  for (const c of added) console.log(`  + ${c.id} (${c.category} · ${c.alias}) — новый класс`);
-  for (const { cls, fields } of changed) console.log(`  ~ ${cls.id} — изменены: ${fields.join(', ')}`);
-  for (const r of removed) console.log(`  - ${r.id} — в файле отсутствует (НЕ удаляется)`);
-  if (!added.length && !changed.length && !removed.length) console.log('  без изменений');
-
-  // совместимость: живые latest-строки изменённых классов против НОВОЙ строгой валидации
-  // START_BLOCK_COMPAT_CHECK
-  let breakingRows = 0;
-  for (const { cls, fields } of changed) {
-    if (!fields.includes('attributes')) continue;
-    const check = v.compile({ ...cls.attributes, $$strict: true });
-    const rows = await sql.unsafe(
-      `SELECT t.id, t.data FROM (
-         SELECT DISTINCT ON (e.id) e.id, e.data, e.deleted FROM ${ident}."Entity" e
-         WHERE e.partition = $1 AND e.class = $2
-         ORDER BY e.id, e.updated DESC
-       ) t WHERE t.deleted IS NULL LIMIT $3`,
-      [partition, cls.id, sample],
-    );
-    const bad = [];
-    for (const r of rows) {
-      const res = check({ ...r.data, id: r.id });
-      if (res !== true) bad.push({ id: r.id, issues: res });
-    }
-    if (bad.length) {
-      breakingRows += bad.length;
-      console.log(`  ! ${cls.id}: ${bad.length}/${rows.length} живых строк НЕ пройдут новую валидацию:`);
-      for (const b of bad.slice(0, 3)) {
-        console.log(`      id=${b.id} → ${b.issues.map((i) => `${i.field} — ${i.message ?? 'invalid'}`).join('; ')}`);
-      }
-      if (bad.length > 3) console.log(`      … и ещё ${bad.length - 3}`);
-    } else if (rows.length) {
-      console.log(`  ✓ ${cls.id}: ${rows.length} живых строк проходят новую валидацию`);
-    }
-  }
-
-  // END_BLOCK_COMPAT_CHECK
-  // START_BLOCK_APPLY
-  if (!args.apply) {
-    if (breakingRows) {
-      console.log(`ИТОГ: ломающие изменения (${breakingRows} строк). Применение (--apply) сломает запись этих сущностей.`);
-      process.exitCode = 1;
-    } else {
-      console.log(`ИТОГ: ${added.length} новых, ${changed.length} изменённых. Применить: --apply`);
-    }
-  } else {
-    if (breakingRows) console.warn(`ВНИМАНИЕ: применяю НЕсовместимую схему (${breakingRows} строк перестанут проходить валидацию при записи).`);
-    for (const c of [...added, ...changed.map((x) => x.cls)]) {
-      await sql.unsafe(
-        `INSERT INTO ${ident}."Schema" (partition, id, alias, category, ancestor, attributes, links, meta, "order")
-         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
-         ON CONFLICT (partition, id) DO UPDATE SET
-           alias = EXCLUDED.alias, category = EXCLUDED.category, ancestor = EXCLUDED.ancestor,
-           attributes = EXCLUDED.attributes, links = EXCLUDED.links, meta = EXCLUDED.meta, "order" = EXCLUDED."order"`,
-        // links — jsonb-массив (объекты-концы v2 / legacy-строки); postgres.js сериализует сам
-        [partition, c.id, c.alias, c.category, c.ancestor ?? null, c.attributes ?? {},
-         c.links ?? [], c.meta ?? {}, c.order ?? 0],
-      );
-    }
-    console.log(`применено: ${added.length} новых, ${changed.length} изменённых классов`);
-  }
-  // END_BLOCK_APPLY
-} finally {
-  await sql.end();
-}