@avytheone/efmesh 0.1.0-beta.1 → 0.2.0

package/src/plan/diff.ts

@@ -1,4 +1,11 @@
-import { Effect } from "effect"
+import { Data, Effect } from "effect"
+import type { GraphError } from "../core/graph.ts"
+import { buildGraph } from "../core/graph.ts"
+import type { AnyModel } from "../core/model.ts"
+import { quoteIdent } from "../core/sql.ts"
+import { EngineAdapter } from "../engine/adapter.ts"
+import type { EngineError } from "../engine/adapter.ts"
+import { viewRef } from "./naming.ts"
 import { StateStore } from "../state/store.ts"
 import type { StateError } from "../state/store.ts"
 
@@ -34,3 +41,216 @@ export const diffEnvironments = (
 
     return { onlyInA, onlyInB, different, same }
   })
+
+/**
+ * Сравнение ДАННЫХ двух окружений (#6, класс table_diff sqlmesh): счётчики
+ * строк, пересечение по ключу, помодельные доли расхождений по колонкам —
+ * между view-слоями A и B одной базы. На DuckDB-классе данных это дёшево;
+ * для больших таблиц — детерминированная выборка по md5 ключа: обе стороны
+ * фильтруются одинаковыми бакетами, поэтому выборка выровнена и пары
+ * ключей не теряются.
+ */
+
+export interface ColumnDrift {
+  readonly column: string
+  /** Сколько сопоставленных ключей разошлись в этой колонке. */
+  readonly mismatches: number
+  /** Доля от matched, 0..1. */
+  readonly rate: number
+}
+
+export interface ModelDataDiff {
+  readonly model: string
+  /** Полные счётчики строк (не задеты выборкой). */
+  readonly rowsA: number
+  readonly rowsB: number
+  /** Ключ сопоставления: grain или ключ вида (uniqueKey/scdType2). */
+  readonly key?: ReadonlyArray<string>
+  /** Дальше — только при ключе; при выборке счётчики по выбранным бакетам. */
+  readonly onlyInA?: number
+  readonly onlyInB?: number
+  readonly matched?: number
+  readonly columns?: ReadonlyArray<ColumnDrift>
+  /** Колонки только одной стороны — дрейф схемы между окружениями. */
+  readonly columnsOnlyInA?: ReadonlyArray<string>
+  readonly columnsOnlyInB?: ReadonlyArray<string>
+  /** Процент md5-бакетов ключа в сравнении; нет поля — сравнение полное. */
+  readonly sampledPercent?: number
+}
+
+export interface DataDiffReport {
+  readonly envA: string
+  readonly envB: string
+  readonly models: ReadonlyArray<ModelDataDiff>
+}
+
+export interface DataDiffOptions {
+  /** Только эти модели; по умолчанию — все материализуемые из обоих окружений. */
+  readonly models?: ReadonlyArray<string>
+  /** 1–99: сравнивать долю ключей (md5-бакеты, выровнено между сторонами). */
+  readonly samplePercent?: number
+}
+
+export class DataDiffError extends Data.TaggedError("DataDiffError")<{
+  readonly model: string
+  readonly reason: string
+}> {}
+
+/** Виды с view-слоем в окружении — их данные есть с чем сравнивать. */
+const COMPARABLE_KINDS: ReadonlySet<string> = new Set([
+  "full",
+  "view",
+  "incrementalByTimeRange",
+  "incrementalByUniqueKey",
+  "scdType2",
+  "seed",
+])
+
+const keyOf = (model: AnyModel): ReadonlyArray<string> | undefined => {
+  if (model.grain !== undefined && model.grain.length > 0) return model.grain
+  if (model.kind._tag === "incrementalByUniqueKey" || model.kind._tag === "scdType2") {
+    return model.kind.key
+  }
+  return undefined
+}
+
+/**
+ * Детерминированный фильтр выборки: md5 от склейки ключа, первые два
+ * hex-символа = 256 бакетов. Работает и на DuckDB, и на Postgres,
+ * одинаково на обеих сторонах diff'а.
+ */
+const samplePredicate = (key: ReadonlyArray<string>, percent: number): string => {
+  const buckets = Math.max(1, Math.min(255, Math.floor((256 * percent) / 100)))
+  const threshold = buckets.toString(16).padStart(2, "0")
+  return `substr(md5(concat_ws('|', ${key.map(quoteIdent).join(", ")})), 1, 2) < '${threshold}'`
+}
+
+const asCount = (value: unknown): number => Number(value ?? 0)
+
+export const dataDiffEnvironments = (
+  envA: string,
+  envB: string,
+  models: Iterable<AnyModel>,
+  options?: DataDiffOptions,
+): Effect.Effect<
+  DataDiffReport,
+  GraphError | StateError | EngineError | DataDiffError,
+  StateStore | EngineAdapter
+> =>
+  Effect.gen(function* () {
+    const store = yield* StateStore
+    const engine = yield* EngineAdapter
+    const graph = yield* buildGraph(models)
+    const inA = new Set((yield* store.getEnvironment(envA)).map((row) => row.name))
+    const inB = new Set((yield* store.getEnvironment(envB)).map((row) => row.name))
+    for (const name of options?.models ?? []) {
+      if (!graph.models.has(name)) {
+        return yield* new DataDiffError({ model: name, reason: "модели нет в проекте" })
+      }
+      if (!inA.has(name) || !inB.has(name)) {
+        return yield* new DataDiffError({
+          model: name,
+          reason: `модели нет в окружении ${inA.has(name) ? envB : envA}`,
+        })
+      }
+    }
+    const wanted = options?.models === undefined ? undefined : new Set(options.models)
+    const percent = options?.samplePercent
+
+    const reports: Array<ModelDataDiff> = []
+    for (const name of graph.order) {
+      if (wanted !== undefined && !wanted.has(name)) continue
+      if (!inA.has(name) || !inB.has(name)) continue
+      const model = graph.models.get(name)!
+      if (!COMPARABLE_KINDS.has(model.kind._tag)) continue
+      const refA = viewRef(envA, model.name)
+      const refB = viewRef(envB, model.name)
+
+      const rowsA = asCount(
+        (yield* engine.query(`SELECT count(*) AS n FROM ${refA}`))[0]?.["n"],
+      )
+      const rowsB = asCount(
+        (yield* engine.query(`SELECT count(*) AS n FROM ${refB}`))[0]?.["n"],
+      )
+
+      // реальные колонки обеих сторон: окружения могут указывать на разные
+      // версии модели — сравниваются только общие, дрейф схемы фиксируется
+      const colsA = (yield* engine.describe(`SELECT * FROM ${refA}`)).map((c) => c.name)
+      const colsB = (yield* engine.describe(`SELECT * FROM ${refB}`)).map((c) => c.name)
+      const setB = new Set(colsB)
+      const setA = new Set(colsA)
+      const common = colsA.filter((column) => setB.has(column))
+      const columnsOnlyInA = colsA.filter((column) => !setB.has(column))
+      const columnsOnlyInB = colsB.filter((column) => !setA.has(column))
+
+      const key = keyOf(model)
+      const commonSet = new Set(common)
+      if (key === undefined || !key.every((column) => commonSet.has(column))) {
+        // сопоставлять нечем (нет grain/ключа или ключ не на обеих сторонах) —
+        // честные счётчики строк без пары
+        reports.push({
+          model: name,
+          rowsA,
+          rowsB,
+          ...(columnsOnlyInA.length > 0 ? { columnsOnlyInA } : {}),
+          ...(columnsOnlyInB.length > 0 ? { columnsOnlyInB } : {}),
+        })
+        continue
+      }
+
+      const keySet = new Set(key)
+      const compared = common.filter((column) => !keySet.has(column))
+      const sample = percent === undefined ? "" : ` WHERE ${samplePredicate(key, percent)}`
+      const pairs = compared
+        .map(
+          (column, index) =>
+            `, a.${quoteIdent(column)} AS a_${index}, b.${quoteIdent(column)} AS b_${index}`,
+        )
+        .join("")
+      const mismatches = compared
+        .map(
+          (_, index) =>
+            `, count(*) FILTER (WHERE in_a AND in_b AND (a_${index} IS DISTINCT FROM b_${index})) AS mm_${index}`,
+        )
+        .join("")
+      const keyList = key.map(quoteIdent).join(", ")
+      const [row] = yield* engine.query(`
+        SELECT
+          count(*) FILTER (WHERE NOT in_b) AS only_a,
+          count(*) FILTER (WHERE NOT in_a) AS only_b,
+          count(*) FILTER (WHERE in_a AND in_b) AS matched
+          ${mismatches}
+        FROM (
+          SELECT coalesce(a.in_a, FALSE) AS in_a, coalesce(b.in_b, FALSE) AS in_b${pairs}
+          FROM (SELECT TRUE AS in_a, * FROM ${refA}${sample}) a
+          FULL OUTER JOIN (SELECT TRUE AS in_b, * FROM ${refB}${sample}) b
+          USING (${keyList})
+        ) j
+      `)
+      const matched = asCount(row?.["matched"])
+      const columns = compared
+        .map((column, index) => {
+          const drifted = asCount(row?.[`mm_${index}`])
+          return {
+            column,
+            mismatches: drifted,
+            rate: matched === 0 ? 0 : drifted / matched,
+          }
+        })
+        .filter((drift) => drift.mismatches > 0)
+      reports.push({
+        model: name,
+        rowsA,
+        rowsB,
+        key,
+        onlyInA: asCount(row?.["only_a"]),
+        onlyInB: asCount(row?.["only_b"]),
+        matched,
+        columns,
+        ...(columnsOnlyInA.length > 0 ? { columnsOnlyInA } : {}),
+        ...(columnsOnlyInB.length > 0 ? { columnsOnlyInB } : {}),
+        ...(percent !== undefined ? { sampledPercent: percent } : {}),
+      })
+    }
+    return { envA, envB, models: reports }
+  }).pipe(Effect.withSpan("efmesh.diff.data", { attributes: { envA, envB } }))

package/src/plan/executor.ts

@@ -32,6 +32,7 @@ import {
 import type {
   FingerprintVersionError,
   ForwardOnlyError,
+  ReclassifyError,
   InvalidEnvironmentError,
   Plan,
   PlanAction,
@@ -66,6 +67,7 @@ export type ApplyError =
   | AuditFailure
   | InvalidEnvironmentError
   | ForwardOnlyError
+  | ReclassifyError
   | FingerprintVersionError
   | EngineFeatureError
 
@@ -546,6 +548,22 @@ export const applyPlan = (
           const body = render(model.fragment, { resolveRef })
           // контракт схемы (SPEC §3.2): дрейф типов ловится до сборки
           yield* checkContract(engine, model, body)
+          // indirect-реюз (#5): данные идентичны по построению (родители
+          // non-breaking/forward-only, своё тело не менялось) — пересборка
+          // пропускается, аудиты гоняются по унаследованной физике
+          if (model.kind._tag === "full" && action.reusedFrom !== undefined) {
+            yield* runAudits(engine, model, physicalFor(model, action.physicalFingerprint))
+            yield* store.upsertSnapshot({
+              name: action.name,
+              fingerprint: action.fingerprint,
+              physicalFp: action.physicalFingerprint,
+              canonicalAst: action.canonicalAst ?? "",
+              renderedSql: body,
+              kind: model.kind._tag,
+              fingerprintVersion: FINGERPRINT_VERSION,
+            })
+            break
+          }
           if (model.kind._tag === "full" && model.target === "parquet") {
             const prefix = parquetPrefix(lakePath!, model.name, action.physicalFingerprint)
             yield* ensureDir(prefix)
@@ -748,6 +766,8 @@ export const applyPlan = (
         actions: plan.actions.map((a) => ({
           name: a.name,
           change: a.change,
+          // override оператора (#5) в журнале: видно, кто и что заявил
+          ...(a.reclassifiedFrom !== undefined ? { reclassifiedFrom: a.reclassifiedFrom } : {}),
           fingerprint: a.fingerprint.slice(0, 8),
           build: a.build,
           backfill: a.backfill.map((r) => `[${toIso(r.start)}, ${toIso(r.end)})`),

package/src/plan/explain.ts

@@ -0,0 +1,114 @@
+/**
+ * Объяснение категоризации (#4, SPEC §5.2): `plan --explain` показывает,
+ * КАКИЕ узлы канонического AST разошлись и почему категория именно такая.
+ * Пути идут по дереву канона движка (json_serialize_sql у DuckDB,
+ * libpg_query у Postgres) — это отладочная подсказка, а не контракт:
+ * форма путей меняется вместе с каноном и semver-события не образует.
+ * Категорию считает categorize.ts; здесь — только её обоснование.
+ */
+
+import { topSelect } from "./categorize.ts"
+
+export interface ChangeExplanation {
+  /** Пути разошедшихся узлов канонического AST (не больше MAX_DIVERGED). */
+  readonly diverged: ReadonlyArray<string>
+  /** Почему категория именно такая. */
+  readonly reason: string
+  /** Изменившиеся прямые родители — источник каскада indirect/forward-only. */
+  readonly cascadeFrom?: ReadonlyArray<string>
+}
+
+/** Дальше точечные пути перестают помогать — лучше открыть render/diff. */
+const MAX_DIVERGED = 8
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const at = (path: string, segment: string): string =>
+  path === "" ? segment : `${path}.${segment}`
+
+const walk = (before: unknown, after: unknown, path: string, out: Array<string>): void => {
+  if (out.length >= MAX_DIVERGED) return
+  if (JSON.stringify(before) === JSON.stringify(after)) return
+  if (Array.isArray(before) && Array.isArray(after)) {
+    const shared = Math.min(before.length, after.length)
+    for (let i = 0; i < shared; i++) walk(before[i], after[i], `${path}[${i}]`, out)
+    for (let i = shared; i < after.length && out.length < MAX_DIVERGED; i++) {
+      out.push(`${path}[${i}] (добавлен)`)
+    }
+    for (let i = shared; i < before.length && out.length < MAX_DIVERGED; i++) {
+      out.push(`${path}[${i}] (удалён)`)
+    }
+    return
+  }
+  if (isRecord(before) && isRecord(after)) {
+    // узел заменён выражением другого типа — точечные пути внутри бессмысленны
+    if (before["type"] !== after["type"]) {
+      out.push(path === "" ? "(корень)" : path)
+      return
+    }
+    const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()
+    for (const key of keys) walk(before[key], after[key], at(path, key), out)
+    return
+  }
+  out.push(path === "" ? "(корень)" : path)
+}
+
+/** Служебная обёртка стейтмента в пути не интересна — режем до тела запроса. */
+const trimStatement = (path: string): string =>
+  path.replace(/^statements\[0\]\.node\.?/, "").replace(/^stmts\[0\]\.stmt\.?/, "") ||
+  "(корень)"
+
+/** Пути расхождения двух канонических AST (JSON-строки); мусор на входе — пусто. */
+export const divergedPaths = (oldAst: string, newAst: string): ReadonlyArray<string> => {
+  try {
+    const out: Array<string> = []
+    walk(JSON.parse(oldAst), JSON.parse(newAst), "", out)
+    return out.map(trimStatement)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Гвардрейл override'а (#5): в новом верхнем SELECT колонок меньше — они
+ * удалены, потомки читают их по именам, «non-breaking» очевидно противоречит
+ * AST. Непарсибельный канон противоречием не считается: решение — за
+ * оператором, override явный и журналируется.
+ */
+export const dropsColumns = (oldAst: string, newAst: string): boolean => {
+  const before = topSelect(oldAst)
+  const after = topSelect(newAst)
+  if (before === null || after === null) return false
+  return after.list.length < before.list.length
+}
+
+/**
+ * Обоснование вердикта categorizeAstChange теми же правилами, которыми он
+ * вынесен (SPEC §5.2): non-breaking — только суффикс верхнего SELECT.
+ */
+export const explainCategorized = (
+  oldAst: string,
+  newAst: string,
+  change: "breaking" | "non-breaking",
+): ChangeExplanation => {
+  const diverged = divergedPaths(oldAst, newAst)
+  if (change === "non-breaking") {
+    return {
+      diverged,
+      reason:
+        "колонки добавлены в конец верхнего SELECT, остальное дерево нетронуто — потребители читают по именам, пересборка не нужна",
+    }
+  }
+  const before = topSelect(oldAst)
+  const after = topSelect(newAst)
+  const reason =
+    before === null || after === null
+      ? "канонический AST неожиданной формы — консервативно breaking"
+      : before.rest !== after.rest
+        ? "дерево разошлось вне списка SELECT (FROM/WHERE/JOIN/GROUP BY/модификаторы)"
+        : after.list.length < before.list.length
+          ? "колонки удалены из SELECT — потомки вставляют по позициям, физику надо пересобирать"
+          : "список SELECT изменён не только хвостом — правка или перестановка колонок ломает позиции потомков"
+  return { diverged, reason }
+}

package/src/plan/fingerprint.ts

@@ -89,9 +89,57 @@ export interface ModelVersion {
   readonly ast: string | null
 }
 
+/**
+ * Кэш канонизации (#8): повторный plan почти целиком состоит из
+ * json_serialize_sql-раундтрипов по неизменённым моделям. Кэш — не
+ * данные: get/put обязаны быть безошибочными (промах/сбой = пересчёт).
+ */
+export interface CanonCache {
+  readonly get: (key: string) => Effect.Effect<string | undefined>
+  readonly put: (key: string, canonical: string) => Effect.Effect<void>
+}
+
+/** Ключ кэша: версия алгоритма + диалект + исходник — апгрейд канона не маскируется. */
+export const canonCacheKey = (dialect: string, source: string): string =>
+  sha256(`${FINGERPRINT_VERSION}:${dialect}:${source}`)
+
+/** Модель в объёме, нужном fingerprint'у: kind, метаданные формы данных, цель. */
+type FingerprintableModel = Parameters<typeof columnNames>[0] & {
+  readonly name: { readonly full: string }
+  readonly kind: ModelKind
+  readonly grain: ReadonlyArray<string> | undefined
+  readonly target: string | undefined
+}
+
+/**
+ * Fingerprint одной модели из готового AST и подписей родителей
+ * (`имя=fingerprint`, отсортированы). Нужен планировщику для проверки
+ * «версию сдвинули ТОЛЬКО родители» (#5): пересчёт со старыми подписями
+ * обязан дать старый fingerprint — иначе разошлись ещё и метаданные,
+ * и физику реюзать нельзя.
+ */
+export const modelFingerprint = (
+  model: FingerprintableModel,
+  ast: string | null,
+  parents: ReadonlyArray<string>,
+): Effect.Effect<string, SeedReadError> =>
+  Effect.gen(function* () {
+    const payload = JSON.stringify({
+      ast,
+      kind: yield* kindPayload(model, model.kind),
+      grain: model.grain,
+      columns: columnNames(model),
+      // смена цели материализации = новая физика, потребители перечитают её
+      target: model.target,
+      parents,
+    })
+    return sha256(payload)
+  })
+
 /** Fingerprint всех моделей графа; транзитивность — через хэши родителей. */
 export const fingerprintGraph = (
   graph: ModelGraph,
+  cache?: CanonCache,
 ): Effect.Effect<
   ReadonlyMap<string, ModelVersion>,
   EngineError | SqlParseError | SeedReadError,
@@ -99,6 +147,16 @@ export const fingerprintGraph = (
 > =>
   Effect.gen(function* () {
     const engine = yield* EngineAdapter
+    const canonicalize = (source: string): Effect.Effect<string, EngineError | SqlParseError> =>
+      Effect.gen(function* () {
+        if (cache === undefined) return yield* engine.canonicalize(source)
+        const key = canonCacheKey(engine.dialect, source)
+        const hit = yield* cache.get(key)
+        if (hit !== undefined) return hit
+        const canon = yield* engine.canonicalize(source)
+        yield* cache.put(key, canon)
+        return canon
+      })
     const versions = new Map<string, ModelVersion>()
     for (const name of graph.order) {
       const model = graph.models.get(name)!
@@ -106,20 +164,11 @@ export const fingerprintGraph = (
       const ast =
         model.kind._tag === "external" || model.kind._tag === "seed"
           ? null
-          : yield* engine.canonicalize(canonicalSql(graph, name))
+          : yield* canonicalize(canonicalSql(graph, name))
       const parents = [...model.deps]
         .sort()
         .map((dep) => `${dep}=${versions.get(dep)!.fingerprint}`)
-      const payload = JSON.stringify({
-        ast,
-        kind: yield* kindPayload(model, model.kind),
-        grain: model.grain,
-        columns: columnNames(model),
-        // смена цели материализации = новая физика, потребители перечитают её
-        target: model.target,
-        parents,
-      })
-      versions.set(name, { fingerprint: sha256(payload), ast })
+      versions.set(name, { fingerprint: yield* modelFingerprint(model, ast, parents), ast })
     }
     return versions
   })