@avytheone/efmesh 0.1.0-beta.1

package/src/core/model.ts

@@ -0,0 +1,475 @@
+import { readFileSync } from "node:fs"
+import type { Schema } from "effect"
+import type { Audit } from "./audit.ts"
+import type { IntervalUnit } from "./interval.ts"
+import { ModelDefinitionError } from "./errors.ts"
+import type { BoundValue, IdentsValue, RefValue, SqlFragment } from "./sql.ts"
+import { collectRefs, parseSqlText, sql, usesBounds } from "./sql.ts"
+
+/** Вид материализации (SPEC §3.1). */
+export type ModelKind =
+  | { readonly _tag: "full" }
+  | { readonly _tag: "view" }
+  | {
+      /** Подставляется в потребителей как подзапрос, без материализации (SPEC §3.1). */
+      readonly _tag: "embedded"
+    }
+  | {
+      readonly _tag: "incrementalByTimeRange"
+      /** Колонка времени, по которой режутся и перечитываются интервалы. */
+      readonly timeColumn: string
+      /** С какого момента бэкфиллить (ISO UTC). */
+      readonly start: string
+      /** Зерно интервала. */
+      readonly interval: IntervalUnit
+      /** Сколько интервалов зерна исполняется одним DELETE+INSERT. */
+      readonly batchSize: number
+      /** Сколько последних done-интервалов пересчитывать заново (поздние данные). */
+      readonly lookback: number
+    }
+  | { readonly _tag: "external"; readonly source: ExternalSource }
+  | {
+      readonly _tag: "seed"
+      /** CSV/JSON-файл с данными; содержимое входит в fingerprint. */
+      readonly file: string
+      readonly format: "csv" | "json"
+    }
+  | {
+      readonly _tag: "incrementalByUniqueKey"
+      /** Логический ключ upsert'а; каждый apply перегоняет запрос и заменяет строки по ключу. */
+      readonly key: ReadonlyArray<string>
+    }
+  | {
+      /**
+       * Медленно меняющееся измерение, тип 2 (SPEC §3.1): история версий
+       * строк. Каждый apply сверяет запрос с открытыми строками: изменившиеся
+       * и исчезнувшие закрываются (validTo = сейчас), новые версии
+       * вставляются открытыми (validTo IS NULL).
+       */
+      readonly _tag: "scdType2"
+      readonly key: ReadonlyArray<string>
+      /** Колонки версионирования — ведёт efmesh: в схеме объявлены, в запросе отсутствуют. */
+      readonly validFrom: string
+      readonly validTo: string
+    }
+
+/**
+ * Определение внешнего источника (SPEC §9.3): таблица движка/ATTACH-базы
+ * или файлы по пути/URL (`read_parquet`/`read_csv`/`read_json`, включая
+ * HTTPS — REST-JSON ложится сюда же).
+ */
+export type ExternalSource =
+  | { readonly _tag: "table"; readonly table: string }
+  | {
+      readonly _tag: "files"
+      readonly path: string
+      readonly format: "parquet" | "csv" | "json"
+    }
+
+export interface IncrementalByTimeRangeOptions {
+  readonly timeColumn: string
+  readonly start: string
+  readonly interval?: IntervalUnit
+  readonly batchSize?: number
+  readonly lookback?: number
+}
+
+export const kind = {
+  full: (): ModelKind => ({ _tag: "full" }),
+  view: (): ModelKind => ({ _tag: "view" }),
+  embedded: (): ModelKind => ({ _tag: "embedded" }),
+  incrementalByTimeRange: (options: IncrementalByTimeRangeOptions): ModelKind => ({
+    _tag: "incrementalByTimeRange",
+    timeColumn: options.timeColumn,
+    start: options.start,
+    interval: options.interval ?? "day",
+    batchSize: options.batchSize ?? 30,
+    lookback: options.lookback ?? 0,
+  }),
+  incrementalByUniqueKey: (options: {
+    readonly key: ReadonlyArray<string>
+  }): ModelKind => ({ _tag: "incrementalByUniqueKey", key: options.key }),
+  scdType2: (options: {
+    readonly key: ReadonlyArray<string>
+    readonly validFrom?: string
+    readonly validTo?: string
+  }): ModelKind => ({
+    _tag: "scdType2",
+    key: options.key,
+    validFrom: options.validFrom ?? "valid_from",
+    validTo: options.validTo ?? "valid_to",
+  }),
+} as const
+
+export const external = {
+  table: (table: string): ExternalSource => ({ _tag: "table", table }),
+  files: (path: string, format: "parquet" | "csv" | "json"): ExternalSource => ({
+    _tag: "files",
+    path,
+    format,
+  }),
+} as const
+
+/** Имя модели: `<схема>.<таблица>`. */
+const MODEL_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$/
+
+export interface ModelName {
+  readonly full: string
+  readonly schema: string
+  readonly table: string
+}
+
+export const parseModelName = (raw: string): ModelName => {
+  if (!MODEL_NAME.test(raw)) {
+    throw new ModelDefinitionError({
+      model: raw,
+      reason: "имя модели должно быть вида <схема>.<таблица> (латиница, цифры, _)",
+    })
+  }
+  const [schema, table] = raw.split(".") as [string, string]
+  return { full: raw, schema, table }
+}
+
+/**
+ * Куда складывать физический слой (SPEC §3.3): нативная таблица движка,
+ * parquet-файлы озера (интервал = партиция, view поверх read_parquet) или
+ * DuckLake-каталог (SPEC §14.5: таблица-на-fingerprint в ATTACH-каталоге —
+ * снапшоты и time travel самого DuckLake в довесок, версионность наша).
+ */
+export type MaterializationTarget = "table" | "parquet" | "ducklake"
+
+export interface ModelConfig<Fields extends Schema.Struct.Fields> {
+  readonly name: string
+  readonly kind: ModelKind
+  readonly schema: Schema.Struct<Fields>
+  readonly description?: string
+  /** Логический первичный ключ; пока метаданные (аудит unique — F2). */
+  readonly grain?: ReadonlyArray<Extract<keyof Fields, string>>
+  /** Цель материализации; по умолчанию — таблица движка. */
+  readonly target?: MaterializationTarget
+  /** Аудиты качества (SPEC §8); в fingerprint не входят. */
+  readonly audits?: ReadonlyArray<Audit>
+  /**
+   * Экспорт наружу (SPEC §9.3): после аудитов и промоушена готовый
+   * результат уезжает в ATTACH-базу (`attach` — алиас из конфига).
+   */
+  readonly export?: { readonly attach: string; readonly table: string }
+}
+
+/** Контекст рендера тела модели. Тело обязано быть чистым: всё изменчивое приходит отсюда. */
+export interface ModelCtx {
+  readonly sql: typeof sql
+  readonly ref: (model: AnyModel) => RefValue
+  readonly cols: <Fields extends Schema.Struct.Fields>(
+    model: Model<Fields>,
+    ...names: ReadonlyArray<Extract<keyof Fields, string>>
+  ) => IdentsValue
+  /**
+   * Границы обрабатываемого интервала `[start, end)` — только для
+   * incrementalByTimeRange. При исполнении подставляются литералами,
+   * в canonical-текст попадают плейсхолдерами (SPEC §3).
+   */
+  readonly start: BoundValue
+  readonly end: BoundValue
+}
+
+export interface Model<Fields extends Schema.Struct.Fields = Schema.Struct.Fields> {
+  readonly _tag: "Model"
+  readonly name: ModelName
+  readonly kind: ModelKind
+  readonly schema: Schema.Struct<Fields>
+  readonly description: string | undefined
+  readonly grain: ReadonlyArray<string>
+  readonly target: MaterializationTarget
+  readonly audits: ReadonlyArray<Audit>
+  /** Тело, отрендеренное в фрагмент один раз при определении. */
+  readonly fragment: SqlFragment
+  /** Имена моделей, на которые тело ссылается через `ctx.ref`. */
+  readonly deps: ReadonlySet<string>
+  /** Сами модели-источники по имени — схемы для валидации фикстур в testModel. */
+  readonly refs: ReadonlyMap<string, AnyModel>
+  readonly export?: { readonly attach: string; readonly table: string }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyModel = Model<any>
+
+export const columnNames = (model: AnyModel): ReadonlyArray<string> =>
+  Object.keys(model.schema.fields)
+
+/** Общие проверки конфигурации вида модели — для defineModel и defineSqlModel. */
+const validateKindConfig = <Fields extends Schema.Struct.Fields>(
+  name: ModelName,
+  config: ModelConfig<Fields>,
+): void => {
+  if (config.kind._tag === "external") {
+    throw new ModelDefinitionError({
+      model: name.full,
+      reason: "external-модель не имеет тела — используй defineExternal",
+    })
+  }
+  if (config.kind._tag === "seed") {
+    throw new ModelDefinitionError({
+      model: name.full,
+      reason: "seed-модель не имеет тела — используй defineSeed",
+    })
+  }
+  if (config.kind._tag === "incrementalByUniqueKey" || config.kind._tag === "scdType2") {
+    for (const keyColumn of config.kind.key) {
+      if (!(keyColumn in config.schema.fields)) {
+        throw new ModelDefinitionError({
+          model: name.full,
+          reason: `ключевой колонки «${keyColumn}» нет в схеме модели`,
+        })
+      }
+    }
+    if (config.kind.key.length === 0) {
+      throw new ModelDefinitionError({ model: name.full, reason: "key не может быть пустым" })
+    }
+  }
+  if (config.kind._tag === "scdType2") {
+    const { validFrom, validTo } = config.kind
+    if (validFrom === validTo) {
+      throw new ModelDefinitionError({
+        model: name.full,
+        reason: "validFrom и validTo не могут совпадать",
+      })
+    }
+    for (const column of [validFrom, validTo]) {
+      if (!(column in config.schema.fields)) {
+        throw new ModelDefinitionError({
+          model: name.full,
+          reason: `колонки версионирования «${column}» нет в схеме модели — потребители должны её видеть`,
+        })
+      }
+      if (config.kind.key.includes(column)) {
+        throw new ModelDefinitionError({
+          model: name.full,
+          reason: `колонка версионирования «${column}» не может входить в key`,
+        })
+      }
+    }
+    if (config.target === "parquet") {
+      throw new ModelDefinitionError({
+        model: name.full,
+        reason: "scdType2 закрывает строки на месте — parquet-цель неприменима",
+      })
+    }
+  }
+  if (
+    (config.kind._tag === "view" || config.kind._tag === "embedded") &&
+    config.target !== undefined &&
+    config.target !== "table"
+  ) {
+    throw new ModelDefinitionError({
+      model: name.full,
+      reason: `${config.kind._tag} не материализуется — цель «${config.target}» к нему неприменима`,
+    })
+  }
+  if (config.kind._tag === "incrementalByUniqueKey" && config.target === "parquet") {
+    throw new ModelDefinitionError({
+      model: name.full,
+      reason: "upsert по ключу в parquet-файлы невозможен — используй target: \"table\"",
+    })
+  }
+  if (config.kind._tag === "incrementalByTimeRange") {
+    if (!(config.kind.timeColumn in config.schema.fields)) {
+      throw new ModelDefinitionError({
+        model: name.full,
+        reason: `timeColumn «${config.kind.timeColumn}» нет в схеме модели`,
+      })
+    }
+    if (Number.isNaN(Date.parse(config.kind.start))) {
+      throw new ModelDefinitionError({
+        model: name.full,
+        reason: `start «${config.kind.start}» — не ISO-время`,
+      })
+    }
+  }
+}
+
+/** Финальная сборка модели из фрагмента — общие инварианты тела. */
+const assembleModel = <Fields extends Schema.Struct.Fields>(
+  name: ModelName,
+  config: ModelConfig<Fields>,
+  fragment: SqlFragment,
+  refs: ReadonlyMap<string, AnyModel>,
+): Model<Fields> => {
+  if (usesBounds(fragment) && config.kind._tag !== "incrementalByTimeRange") {
+    throw new ModelDefinitionError({
+      model: name.full,
+      reason: `ctx.start/ctx.end доступны только incrementalByTimeRange, вид модели — ${config.kind._tag}`,
+    })
+  }
+  const deps = collectRefs(fragment)
+  if (deps.has(name.full)) {
+    throw new ModelDefinitionError({ model: name.full, reason: "модель ссылается сама на себя" })
+  }
+  return {
+    _tag: "Model",
+    name,
+    kind: config.kind,
+    schema: config.schema,
+    description: config.description,
+    grain: config.grain ?? [],
+    target: config.target ?? "table",
+    audits: config.audits ?? [],
+    fragment,
+    deps,
+    refs,
+    ...(config.export !== undefined ? { export: config.export } : {}),
+  }
+}
+
+/**
+ * Определяет модель. Вызывается на верхнем уровне модуля; тело выполняется
+ * ровно один раз — сразу, поэтому ссылки (`ctx.ref`) известны статически
+ * и DAG строится без парсинга SQL.
+ */
+export const defineModel = <const Fields extends Schema.Struct.Fields>(
+  config: ModelConfig<Fields>,
+  body: (ctx: ModelCtx) => SqlFragment,
+): Model<Fields> => {
+  const name = parseModelName(config.name)
+  validateKindConfig(name, config)
+  const refs = new Map<string, AnyModel>()
+  const ctx: ModelCtx = {
+    sql,
+    ref: (model) => {
+      refs.set(model.name.full, model)
+      return { _tag: "RefValue", modelName: model.name.full }
+    },
+    cols: (model, ...names) => {
+      const known = new Set(Object.keys(model.schema.fields))
+      for (const column of names) {
+        if (!known.has(column)) {
+          // недостижимо при честной типизации; защита от `as any`
+          throw new ModelDefinitionError({
+            model: config.name,
+            reason: `колонки «${column}» нет в схеме модели ${model.name.full}`,
+          })
+        }
+      }
+      return { _tag: "IdentsValue", names }
+    },
+    start: { _tag: "BoundValue", which: "start" },
+    end: { _tag: "BoundValue", which: "end" },
+  }
+  return assembleModel(name, config, body(ctx), refs)
+}
+
+export interface SqlModelConfig<Fields extends Schema.Struct.Fields>
+  extends ModelConfig<Fields> {
+  /** Путь к .sql-файлу тела: `@ref(схема.таблица)`, `@start`, `@end`. */
+  readonly file: string
+  /**
+   * Модели, на которые SQL-текст ссылается через `@ref` — значениями,
+   * чтобы DAG и testModel работали как у обычных моделей.
+   */
+  readonly refs?: ReadonlyArray<AnyModel>
+}
+
+/**
+ * Модель из сырого .sql-файла (SPEC §14.1) — для миграции существующих
+ * dbt/sqlmesh-проектов. Типизация ссылок теряется (это честная цена):
+ * каждая `@ref` в тексте обязана быть объявлена в `refs`, лишние
+ * объявления — ошибка.
+ */
+export const defineSqlModel = <const Fields extends Schema.Struct.Fields>(
+  config: SqlModelConfig<Fields>,
+): Model<Fields> => {
+  const name = parseModelName(config.name)
+  validateKindConfig(name, config)
+  let text: string
+  try {
+    text = readFileSync(config.file, "utf8")
+  } catch (cause) {
+    throw new ModelDefinitionError({
+      model: name.full,
+      reason: `не удалось прочитать ${config.file}: ${String(cause)}`,
+    })
+  }
+  const fragment = parseSqlText(text)
+  const declared = new Map((config.refs ?? []).map((model) => [model.name.full, model]))
+  const used = collectRefs(fragment)
+  for (const ref of used) {
+    if (!declared.has(ref)) {
+      throw new ModelDefinitionError({
+        model: name.full,
+        reason: `@ref(${ref}) в ${config.file} не объявлен в refs`,
+      })
+    }
+  }
+  for (const declaredName of declared.keys()) {
+    if (!used.has(declaredName)) {
+      throw new ModelDefinitionError({
+        model: name.full,
+        reason: `модель ${declaredName} объявлена в refs, но @ref в ${config.file} её не использует`,
+      })
+    }
+  }
+  return assembleModel(name, config, fragment, declared)
+}
+
+export interface ExternalConfig<Fields extends Schema.Struct.Fields> {
+  readonly name: string
+  readonly source: ExternalSource
+  readonly schema: Schema.Struct<Fields>
+  readonly description?: string
+}
+
+/**
+ * Внешний источник (SPEC §3.1, §9.3): не материализуется, но участвует
+ * в DAG и lineage, схема объявляется. В fingerprint входит только
+ * *определение* источника — содержимое меняется между запусками, и это
+ * нормально для сырья.
+ */
+export const defineExternal = <const Fields extends Schema.Struct.Fields>(
+  config: ExternalConfig<Fields>,
+): Model<Fields> => ({
+  _tag: "Model",
+  name: parseModelName(config.name),
+  kind: { _tag: "external", source: config.source },
+  schema: config.schema,
+  description: config.description,
+  grain: [],
+  target: "table", // не материализуется — поле не используется
+  audits: [],
+  fragment: { _tag: "SqlFragment", nodes: [] },
+  deps: new Set(),
+  refs: new Map(),
+})
+
+export interface SeedConfig<Fields extends Schema.Struct.Fields> {
+  readonly name: string
+  /** Путь к CSV/JSON-файлу; формат — по расширению или явно. */
+  readonly file: string
+  readonly format?: "csv" | "json"
+  readonly schema: Schema.Struct<Fields>
+  readonly description?: string
+  readonly audits?: ReadonlyArray<Audit>
+}
+
+/**
+ * Seed (SPEC §3.1): справочник из файла. В отличие от external, содержимое
+ * файла входит в fingerprint — правка данных = новая версия и пересборка;
+ * форма проверяется контрактом схемы при сборке.
+ */
+export const defineSeed = <const Fields extends Schema.Struct.Fields>(
+  config: SeedConfig<Fields>,
+): Model<Fields> => {
+  const format = config.format ?? (config.file.endsWith(".json") ? "json" : "csv")
+  return {
+    _tag: "Model",
+    name: parseModelName(config.name),
+    kind: { _tag: "seed", file: config.file, format },
+    schema: config.schema,
+    description: config.description,
+    grain: [],
+    target: "table",
+    audits: config.audits ?? [],
+    fragment: { _tag: "SqlFragment", nodes: [] },
+    deps: new Set(),
+    refs: new Map(),
+  }
+}

package/src/core/sql.ts

@@ -0,0 +1,200 @@
+/**
+ * SQL-фрагменты: дерево из текста, ссылок на модели и идентификаторов.
+ *
+ * Тело модели рендерится в фрагмент один раз при определении; в текст SQL
+ * фрагмент превращается позже — резолвером ссылок (canonical-рендер для
+ * fingerprint, физический — для исполнения).
+ */
+
+export interface SqlFragment {
+  readonly _tag: "SqlFragment"
+  readonly nodes: ReadonlyArray<SqlNode>
+}
+
+export type SqlNode =
+  | { readonly _tag: "Text"; readonly text: string }
+  | { readonly _tag: "Ref"; readonly modelName: string }
+  | { readonly _tag: "Idents"; readonly names: ReadonlyArray<string> }
+  | { readonly _tag: "Bound"; readonly which: "start" | "end" }
+  | { readonly _tag: "Self" }
+
+/** Ссылка на модель, полученная из `ctx.ref(model)`. */
+export interface RefValue {
+  readonly _tag: "RefValue"
+  readonly modelName: string
+}
+
+/** Список колонок, полученный из `ctx.cols(model, ...)`. */
+export interface IdentsValue {
+  readonly _tag: "IdentsValue"
+  readonly names: ReadonlyArray<string>
+}
+
+/** Граница обрабатываемого интервала — `ctx.start` / `ctx.end` (SPEC §3). */
+export interface BoundValue {
+  readonly _tag: "BoundValue"
+  readonly which: "start" | "end"
+}
+
+/** Результат самой модели в запросе аудита — `ctx.self` (SPEC §8). */
+export interface SelfValue {
+  readonly _tag: "SelfValue"
+}
+
+/** Скалярные значения инлайнятся как SQL-литералы (детерминированно). */
+export type SqlLiteral = string | number | boolean | bigint | null
+
+export type Interpolation =
+  | SqlFragment
+  | RefValue
+  | IdentsValue
+  | BoundValue
+  | SelfValue
+  | SqlLiteral
+
+const isSqlFragment = (v: unknown): v is SqlFragment =>
+  typeof v === "object" && v !== null && (v as any)._tag === "SqlFragment"
+
+const isRefValue = (v: unknown): v is RefValue =>
+  typeof v === "object" && v !== null && (v as any)._tag === "RefValue"
+
+const isIdentsValue = (v: unknown): v is IdentsValue =>
+  typeof v === "object" && v !== null && (v as any)._tag === "IdentsValue"
+
+const isBoundValue = (v: unknown): v is BoundValue =>
+  typeof v === "object" && v !== null && (v as any)._tag === "BoundValue"
+
+const isSelfValue = (v: unknown): v is SelfValue =>
+  typeof v === "object" && v !== null && (v as any)._tag === "SelfValue"
+
+export const quoteIdent = (name: string): string => `"${name.replaceAll(`"`, `""`)}"`
+
+export const escapeLiteral = (value: SqlLiteral): string => {
+  if (value === null) return "NULL"
+  switch (typeof value) {
+    case "string":
+      return `'${value.replaceAll(`'`, `''`)}'`
+    case "number": {
+      if (!Number.isFinite(value)) throw new TypeError(`non-finite number in SQL literal: ${value}`)
+      return String(value)
+    }
+    case "bigint":
+      return value.toString()
+    case "boolean":
+      return value ? "TRUE" : "FALSE"
+  }
+}
+
+export const sql = (
+  strings: TemplateStringsArray,
+  ...values: ReadonlyArray<Interpolation>
+): SqlFragment => {
+  const nodes: Array<SqlNode> = []
+  const pushText = (text: string) => {
+    if (text === "") return
+    const last = nodes[nodes.length - 1]
+    if (last !== undefined && last._tag === "Text") {
+      nodes[nodes.length - 1] = { _tag: "Text", text: last.text + text }
+    } else {
+      nodes.push({ _tag: "Text", text })
+    }
+  }
+  for (let i = 0; i < strings.length; i++) {
+    pushText(strings[i]!)
+    if (i >= values.length) continue
+    const value = values[i]!
+    if (isSqlFragment(value)) {
+      for (const node of value.nodes) {
+        if (node._tag === "Text") pushText(node.text)
+        else nodes.push(node)
+      }
+    } else if (isRefValue(value)) {
+      nodes.push({ _tag: "Ref", modelName: value.modelName })
+    } else if (isIdentsValue(value)) {
+      nodes.push({ _tag: "Idents", names: value.names })
+    } else if (isBoundValue(value)) {
+      nodes.push({ _tag: "Bound", which: value.which })
+    } else if (isSelfValue(value)) {
+      nodes.push({ _tag: "Self" })
+    } else {
+      pushText(escapeLiteral(value))
+    }
+  }
+  return { _tag: "SqlFragment", nodes }
+}
+
+export interface RenderOptions {
+  /** Во что превращается ссылка на модель (physical-таблица, view окружения, логическое имя…). */
+  readonly resolveRef: (modelName: string) => string
+  /**
+   * Границы обрабатываемого интервала — готовые SQL-выражения
+   * (`TIMESTAMP '…'` при исполнении). Без них `ctx.start`/`ctx.end`
+   * рендерятся плейсхолдерами `$start`/`$end` — так канонический текст
+   * не зависит от конкретных дат и fingerprint стабилен (SPEC §3, §4).
+   */
+  readonly interval?: { readonly start: string; readonly end: string }
+  /** Во что рендерится `ctx.self` в запросе аудита (физика или подзапрос интервала). */
+  readonly self?: string
+}
+
+export const render = (fragment: SqlFragment, options: RenderOptions): string => {
+  let out = ""
+  for (const node of fragment.nodes) {
+    switch (node._tag) {
+      case "Text":
+        out += node.text
+        break
+      case "Ref":
+        out += options.resolveRef(node.modelName)
+        break
+      case "Idents":
+        out += node.names.map(quoteIdent).join(", ")
+        break
+      case "Bound":
+        out += options.interval === undefined ? `$${node.which}` : options.interval[node.which]
+        break
+      case "Self":
+        if (options.self === undefined) throw new Error("рендер ctx.self без options.self")
+        out += options.self
+        break
+    }
+  }
+  return out
+}
+
+/**
+ * Парсер сырого SQL-текста (SPEC §14.1): `@ref(схема.таблица)` — ссылка
+ * на модель, `@start`/`@end` — границы интервала. Всё остальное — текст
+ * как есть. Для миграции существующих dbt/sqlmesh-проектов: типизация
+ * ссылок теряется, зависимости объявляются рядом (defineSqlModel.refs).
+ */
+export const parseSqlText = (text: string): SqlFragment => {
+  const nodes: Array<SqlNode> = []
+  const pattern = /@ref\(\s*([^)\s]+)\s*\)|@start\b|@end\b/g
+  let cursor = 0
+  for (const match of text.matchAll(pattern)) {
+    const before = text.slice(cursor, match.index)
+    if (before !== "") nodes.push({ _tag: "Text", text: before })
+    if (match[0].startsWith("@ref")) {
+      nodes.push({ _tag: "Ref", modelName: match[1]! })
+    } else {
+      nodes.push({ _tag: "Bound", which: match[0] === "@start" ? "start" : "end" })
+    }
+    cursor = match.index + match[0].length
+  }
+  const tail = text.slice(cursor)
+  if (tail !== "") nodes.push({ _tag: "Text", text: tail })
+  return { _tag: "SqlFragment", nodes }
+}
+
+export const collectRefs = (fragment: SqlFragment): ReadonlySet<string> => {
+  const refs = new Set<string>()
+  for (const node of fragment.nodes) {
+    if (node._tag === "Ref") refs.add(node.modelName)
+  }
+  return refs
+}
+
+/** Использует ли фрагмент границы интервала (валидация вида модели). */
+export const usesBounds = (fragment: SqlFragment): boolean =>
+  fragment.nodes.some((node) => node._tag === "Bound")