@avytheone/efmesh 0.1.0-beta.1

package/src/plan/audit-run.ts

@@ -0,0 +1,101 @@
+import { Data, Effect } from "effect"
+import type { GraphError, ModelGraph } from "../core/graph.ts"
+import { buildGraph } from "../core/graph.ts"
+import type { AnyModel } from "../core/model.ts"
+import { render } from "../core/sql.ts"
+import { EngineAdapter } from "../engine/adapter.ts"
+import type { EngineError } from "../engine/adapter.ts"
+import { externalSourceRef, viewRef } from "./naming.ts"
+
+/**
+ * Автономный прогон аудитов (SPEC §8, F4): проверяет то, что окружение
+ * отдаёт потребителям СЕЙЧАС — view-слой целиком, не свежезагруженный
+ * интервал, как в apply. Ловит деградацию задним числом: поздние данные
+ * через lookback, руками поправленную физику, дрейф external-источников.
+ *
+ * Ничего не меняет и не помечает; отчёт целиком — упавший blocking-аудит
+ * не прячет следующие за ним.
+ */
+
+export interface AuditRunResult {
+  readonly model: string
+  readonly audit: string
+  readonly blocking: boolean
+  readonly violations: number
+}
+
+export interface AuditRunReport {
+  readonly results: ReadonlyArray<AuditRunResult>
+  /** Суммарные нарушения blocking-аудитов — не ноль ⇒ окружению нельзя верить. */
+  readonly blockingViolations: number
+}
+
+/** Запрошенной модели нет в проекте (или у неё нет аудитов — нечего гонять). */
+export class AuditTargetError extends Data.TaggedError("AuditTargetError")<{
+  readonly model: string
+  readonly reason: string
+}> {}
+
+/** Итог для CLI: blocking-аудиты окружения нарушены. */
+export class EnvironmentAuditError extends Data.TaggedError("EnvironmentAuditError")<{
+  readonly env: string
+  readonly blockingViolations: number
+}> {}
+
+const selfFor = (graph: ModelGraph, env: string, model: AnyModel): string => {
+  const resolve = (ref: string): string => {
+    const source = graph.models.get(ref)!
+    if (source.kind._tag === "external") return externalSourceRef(source.kind.source)
+    if (source.kind._tag === "embedded") {
+      return `(${render(source.fragment, { resolveRef: resolve })})`
+    }
+    return viewRef(env, source.name)
+  }
+  // embedded не материализуется — аудируется подзапрос против view окружения
+  if (model.kind._tag === "embedded") {
+    return `(${render(model.fragment, { resolveRef: resolve })})`
+  }
+  return viewRef(env, model.name)
+}
+
+export const auditEnvironment = (
+  env: string,
+  models: Iterable<AnyModel>,
+  only?: ReadonlyArray<string>,
+): Effect.Effect<AuditRunReport, GraphError | AuditTargetError | EngineError, EngineAdapter> =>
+  Effect.gen(function* () {
+    const engine = yield* EngineAdapter
+    const graph = yield* buildGraph(models)
+    for (const name of only ?? []) {
+      if (!graph.models.has(name)) {
+        return yield* new AuditTargetError({ model: name, reason: "модели нет в проекте" })
+      }
+    }
+    const wanted = only === undefined ? undefined : new Set(only)
+
+    const results: Array<AuditRunResult> = []
+    for (const name of graph.order) {
+      if (wanted !== undefined && !wanted.has(name)) continue
+      const model = graph.models.get(name)!
+      if (model.audits.length === 0) continue
+      const self = selfFor(graph, env, model)
+      for (const auditDef of model.audits) {
+        const violations = yield* engine.query(
+          render(auditDef.fragment, { resolveRef: (ref) => ref, self }),
+        )
+        results.push({
+          model: name,
+          audit: auditDef.name,
+          blocking: auditDef.blocking,
+          violations: violations.length,
+        })
+      }
+    }
+
+    return {
+      results,
+      blockingViolations: results
+        .filter((result) => result.blocking)
+        .reduce((sum, result) => sum + result.violations, 0),
+    }
+  }).pipe(Effect.withSpan("efmesh.audit", { attributes: { env } }))

package/src/plan/categorize.ts

@@ -0,0 +1,41 @@
+/**
+ * Категоризация изменения по каноническим AST (SPEC §5.2): non-breaking —
+ * это добавление колонок В КОНЕЦ верхнего SELECT при полностью неизменном
+ * остальном дереве (потребители выбирают по именам, INSERT потомков — по
+ * позициям, поэтому только суффикс безопасен). Всё прочее — breaking.
+ * При любой неожиданной структуре — консервативно breaking.
+ */
+
+type AstNode = Record<string, unknown>
+
+const topSelect = (astJson: string): { list: ReadonlyArray<string>; rest: string } | null => {
+  try {
+    const ast = JSON.parse(astJson) as {
+      readonly statements?: ReadonlyArray<{ readonly node?: AstNode }>
+    }
+    const node = ast.statements?.[0]?.node
+    if (node === undefined || !Array.isArray(node["select_list"])) return null
+    const list = (node["select_list"] as ReadonlyArray<unknown>).map((item) =>
+      JSON.stringify(item),
+    )
+    const { select_list: _list, ...rest } = node
+    return { list, rest: JSON.stringify(rest) }
+  } catch {
+    return null
+  }
+}
+
+export const categorizeAstChange = (
+  oldAst: string,
+  newAst: string,
+): "breaking" | "non-breaking" => {
+  const before = topSelect(oldAst)
+  const after = topSelect(newAst)
+  if (before === null || after === null) return "breaking"
+  if (before.rest !== after.rest) return "breaking"
+  if (after.list.length <= before.list.length) return "breaking"
+  // старый select_list — точный префикс нового
+  return before.list.every((item, index) => item === after.list[index])
+    ? "non-breaking"
+    : "breaking"
+}

package/src/plan/contract.ts

@@ -0,0 +1,114 @@
+import { Data, Effect } from "effect"
+import type { AnyModel } from "../core/model.ts"
+import type { Engine, EngineError } from "../engine/adapter.ts"
+
+/**
+ * Контракт схемы (SPEC §3.2): объявленная Schema — не документация.
+ * Перед сборкой снапшота efmesh делает DESCRIBE запроса (движок отдаёт
+ * имена и типы, не выполняя его) и сверяет с объявлением. Дрейф типов
+ * ловится до бэкфилла, а не после.
+ *
+ * Сверка по семействам типов: точное соответствие TS-типов типам движка
+ * невозможно (Number — это и INTEGER, и DOUBLE), а имена проверяются
+ * строго. Nullability DESCRIBE не отдаёт — это территория аудитов (§14.2).
+ */
+
+export class SchemaMismatchError extends Data.TaggedError("SchemaMismatchError")<{
+  readonly model: string
+  readonly problems: ReadonlyArray<string>
+}> {}
+
+export type TypeFamily = "text" | "numeric" | "boolean" | "temporal" | "any"
+
+/** Семейство, ожидаемое от поля Effect Schema (по AST). Реюз: testModel рендерит фикстуры по нему. */
+export const familyOfAst = (ast: unknown): TypeFamily => {
+  const node = ast as {
+    readonly _tag: string
+    readonly types?: ReadonlyArray<unknown>
+    readonly annotations?: { readonly typeConstructor?: { readonly _tag?: string } }
+  }
+  switch (node._tag) {
+    case "String":
+      return "text"
+    case "Number":
+    case "BigInt":
+      return "numeric"
+    case "Boolean":
+      return "boolean"
+    case "Declaration": {
+      const constructorTag = node.annotations?.typeConstructor?._tag ?? ""
+      return constructorTag.startsWith("effect/DateTime") ? "temporal" : "any"
+    }
+    case "Union": {
+      // NullOr(X) и подобные: единственное распознанное семейство среди членов
+      const families = new Set(
+        (node.types ?? [])
+          .map(familyOfAst)
+          .filter((family) => family !== "any"),
+      )
+      return families.size === 1 ? [...families][0]! : "any"
+    }
+    default:
+      return "any"
+  }
+}
+
+/** Семейство фактического типа DuckDB из DESCRIBE. */
+const familyOfEngineType = (engineType: string): TypeFamily => {
+  const base = engineType.toUpperCase()
+  if (base === "VARCHAR" || base.startsWith("VARCHAR(")) return "text"
+  if (base === "BOOLEAN") return "boolean"
+  if (
+    /^(U?(TINY|SMALL|BIG|HUGE)INT|INTEGER|UINTEGER|FLOAT|DOUBLE|REAL)$/.test(base) ||
+    base.startsWith("DECIMAL")
+  ) {
+    return "numeric"
+  }
+  if (base === "DATE" || base === "TIME" || base.startsWith("TIMESTAMP")) return "temporal"
+  return "any"
+}
+
+/**
+ * Сверяет объявленную схему модели с фактическим результатом запроса.
+ * `renderedSql` — исполнимый рендер тела (ссылки уже в физике/источниках).
+ * `managed` — колонки, которые efmesh ведёт сам (scdType2: valid_from/
+ * valid_to): в схеме объявлены — потребители их видят, — но запрос
+ * их не возвращает.
+ */
+export const checkContract = (
+  engine: Engine,
+  model: AnyModel,
+  renderedSql: string,
+  managed?: ReadonlySet<string>,
+): Effect.Effect<void, EngineError | SchemaMismatchError> =>
+  Effect.gen(function* () {
+    const actual = yield* engine.describe(renderedSql)
+    const actualByName = new Map(actual.map((column) => [column.name, column.type]))
+    const declared = (
+      Object.entries(model.schema.fields) as ReadonlyArray<[string, { readonly ast: unknown }]>
+    ).filter(([name]) => !(managed?.has(name) ?? false))
+
+    const problems: Array<string> = []
+    for (const [name, field] of declared) {
+      const engineType = actualByName.get(name)
+      if (engineType === undefined) {
+        problems.push(`колонка «${name}» объявлена в схеме, но запрос её не возвращает`)
+        continue
+      }
+      const expected = familyOfAst(field.ast)
+      const got = familyOfEngineType(engineType)
+      if (expected !== "any" && got !== "any" && expected !== got) {
+        problems.push(`колонка «${name}»: схема ждёт ${expected}, запрос отдаёт ${engineType}`)
+      }
+    }
+    const declaredNames = new Set(declared.map(([name]) => name))
+    for (const column of actual) {
+      if (!declaredNames.has(column.name)) {
+        problems.push(`запрос возвращает колонку «${column.name}», которой нет в схеме`)
+      }
+    }
+
+    if (problems.length > 0) {
+      return yield* new SchemaMismatchError({ model: model.name.full, problems })
+    }
+  })

package/src/plan/diff.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect"
+import { StateStore } from "../state/store.ts"
+import type { StateError } from "../state/store.ts"
+
+/** Чем окружения отличаются (SPEC §11: `efmesh diff <envA> <envB>`). */
+export interface EnvDiff {
+  /** Модель есть только в A. */
+  readonly onlyInA: ReadonlyArray<string>
+  readonly onlyInB: ReadonlyArray<string>
+  /** Разные версии: имя + fp8 обеих сторон. */
+  readonly different: ReadonlyArray<{ readonly name: string; readonly a: string; readonly b: string }>
+  readonly same: ReadonlyArray<string>
+}
+
+export const diffEnvironments = (
+  envA: string,
+  envB: string,
+): Effect.Effect<EnvDiff, StateError, StateStore> =>
+  Effect.gen(function* () {
+    const store = yield* StateStore
+    const a = new Map((yield* store.getEnvironment(envA)).map((r) => [r.name, r.fingerprint]))
+    const b = new Map((yield* store.getEnvironment(envB)).map((r) => [r.name, r.fingerprint]))
+
+    const onlyInA: Array<string> = []
+    const different: Array<{ name: string; a: string; b: string }> = []
+    const same: Array<string> = []
+    for (const [name, fpA] of a) {
+      const fpB = b.get(name)
+      if (fpB === undefined) onlyInA.push(name)
+      else if (fpA === fpB) same.push(name)
+      else different.push({ name, a: fpA.slice(0, 8), b: fpB.slice(0, 8) })
+    }
+    const onlyInB = [...b.keys()].filter((name) => !a.has(name))
+
+    return { onlyInA, onlyInB, different, same }
+  })