@avytheone/efmesh 0.2.0 → 0.2.1

package/src/plan/categorize.ts

@@ -1,14 +1,14 @@
 /**
- * Категоризация изменения по каноническим AST (SPEC §5.2): non-breaking —
- * это добавление колонок В КОНЕЦ верхнего SELECT при полностью неизменном
- * остальном дереве (потребители выбирают по именам, INSERT потомков — по
- * позициям, поэтому только суффикс безопасен). Всё прочее — breaking.
- * При любой неожиданной структуре — консервативно breaking.
+ * Change categorization by canonical ASTs (SPEC §5.2): non-breaking is adding
+ * columns TO THE END of the top SELECT with the rest of the tree entirely
+ * unchanged (consumers select by name, descendants' INSERT is by position, so
+ * only a suffix is safe). Everything else is breaking. On any unexpected
+ * structure — conservatively breaking.
  */
 
 type AstNode = Record<string, unknown>
 
-/** Верхний SELECT канона: список колонок + остальное дерево (для explain.ts). */
+/** The canon's top SELECT: the column list + the rest of the tree (for explain.ts). */
 export const topSelect = (
   astJson: string,
 ): { list: ReadonlyArray<string>; rest: string } | null => {
@@ -37,7 +37,7 @@ export const categorizeAstChange = (
   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 — точный префикс нового
+  // the old select_list is an exact prefix of the new one
   return before.list.every((item, index) => item === after.list[index])
     ? "non-breaking"
     : "breaking"

package/src/plan/contract.ts

@@ -3,24 +3,28 @@ import type { AnyModel } from "../core/model.ts"
 import type { Engine, EngineError } from "../engine/adapter.ts"
 
 /**
- * Контракт схемы (SPEC §3.2): объявленная Schema — не документация.
- * Перед сборкой снапшота efmesh делает DESCRIBE запроса (движок отдаёт
- * имена и типы, не выполняя его) и сверяет с объявлением. Дрейф типов
- * ловится до бэкфилла, а не после.
+ * Schema contract (SPEC §3.2): the declared Schema is not documentation.
+ * Before building a snapshot efmesh runs a DESCRIBE of the query (the engine
+ * returns names and types without executing it) and checks it against the
+ * declaration. Type drift is caught before the backfill, not after.
  *
- * Сверка по семействам типов: точное соответствие TS-типов типам движка
- * невозможно (Number — это и INTEGER, и DOUBLE), а имена проверяются
- * строго. Nullability DESCRIBE не отдаёт — это территория аудитов (§14.2).
+ * Checked by type families: an exact match of TS types to engine types is
+ * impossible (Number is both INTEGER and DOUBLE), while names are checked
+ * strictly. DESCRIBE does not report nullability — that is audit territory (§14.2).
  */
 
 export class SchemaMismatchError extends Data.TaggedError("SchemaMismatchError")<{
   readonly model: string
   readonly problems: ReadonlyArray<string>
-}> {}
+}> {
+  override get message(): string {
+    return `schema contract of model «${this.model}»: ${this.problems.join("; ")}`
+  }
+}
 
 export type TypeFamily = "text" | "numeric" | "boolean" | "temporal" | "any"
 
-/** Семейство, ожидаемое от поля Effect Schema (по AST). Реюз: testModel рендерит фикстуры по нему. */
+/** Family expected from an Effect Schema field (by AST). Reuse: testModel renders fixtures from it. */
 export const familyOfAst = (ast: unknown): TypeFamily => {
   const node = ast as {
     readonly _tag: string
@@ -40,7 +44,7 @@ export const familyOfAst = (ast: unknown): TypeFamily => {
       return constructorTag.startsWith("effect/DateTime") ? "temporal" : "any"
     }
     case "Union": {
-      // NullOr(X) и подобные: единственное распознанное семейство среди членов
+      // NullOr(X) and the like: the single recognized family among the members
       const families = new Set(
         (node.types ?? [])
           .map(familyOfAst)
@@ -53,7 +57,7 @@ export const familyOfAst = (ast: unknown): TypeFamily => {
   }
 }
 
-/** Семейство фактического типа DuckDB из DESCRIBE. */
+/** Family of an actual DuckDB type from DESCRIBE. */
 const familyOfEngineType = (engineType: string): TypeFamily => {
   const base = engineType.toUpperCase()
   if (base === "VARCHAR" || base.startsWith("VARCHAR(")) return "text"
@@ -69,11 +73,11 @@ const familyOfEngineType = (engineType: string): TypeFamily => {
 }
 
 /**
- * Сверяет объявленную схему модели с фактическим результатом запроса.
- * `renderedSql` — исполнимый рендер тела (ссылки уже в физике/источниках).
- * `managed` — колонки, которые efmesh ведёт сам (scdType2: valid_from/
- * valid_to): в схеме объявлены — потребители их видят, — но запрос
- * их не возвращает.
+ * Checks the model's declared schema against the query's actual result.
+ * `renderedSql` — the executable render of the body (references already point
+ * at physical storage/sources). `managed` — columns efmesh maintains itself
+ * (scdType2: valid_from/valid_to): declared in the schema — consumers see
+ * them — but the query does not return them.
  */
 export const checkContract = (
   engine: Engine,
@@ -92,19 +96,19 @@ export const checkContract = (
     for (const [name, field] of declared) {
       const engineType = actualByName.get(name)
       if (engineType === undefined) {
-        problems.push(`колонка «${name}» объявлена в схеме, но запрос её не возвращает`)
+        problems.push(`column «${name}» is declared in the schema but the query does not return it`)
         continue
       }
       const expected = familyOfAst(field.ast)
       const got = familyOfEngineType(engineType)
       if (expected !== "any" && got !== "any" && expected !== got) {
-        problems.push(`колонка «${name}»: схема ждёт ${expected}, запрос отдаёт ${engineType}`)
+        problems.push(`column «${name}»: schema expects ${expected}, query returns ${engineType}`)
       }
     }
     const declaredNames = new Set(declared.map(([name]) => name))
     for (const column of actual) {
       if (!declaredNames.has(column.name)) {
-        problems.push(`запрос возвращает колонку «${column.name}», которой нет в схеме`)
+        problems.push(`query returns column «${column.name}» which is not in the schema`)
       }
     }
 

package/src/plan/diff.ts

@@ -9,12 +9,12 @@ import { viewRef } from "./naming.ts"
 import { StateStore } from "../state/store.ts"
 import type { StateError } from "../state/store.ts"
 
-/** Чем окружения отличаются (SPEC §11: `efmesh diff <envA> <envB>`). */
+/** How two environments differ (SPEC §11: `efmesh diff <envA> <envB>`). */
 export interface EnvDiff {
-  /** Модель есть только в A. */
+  /** Model present only in A. */
   readonly onlyInA: ReadonlyArray<string>
   readonly onlyInB: ReadonlyArray<string>
-  /** Разные версии: имя + fp8 обеих сторон. */
+  /** Differing versions: name + fp8 of both sides. */
   readonly different: ReadonlyArray<{ readonly name: string; readonly a: string; readonly b: string }>
   readonly same: ReadonlyArray<string>
 }
@@ -43,38 +43,38 @@ export const diffEnvironments = (
   })
 
 /**
- * Сравнение ДАННЫХ двух окружений (#6, класс table_diff sqlmesh): счётчики
- * строк, пересечение по ключу, помодельные доли расхождений по колонкам —
- * между view-слоями A и B одной базы. На DuckDB-классе данных это дёшево;
- * для больших таблиц — детерминированная выборка по md5 ключа: обе стороны
- * фильтруются одинаковыми бакетами, поэтому выборка выровнена и пары
- * ключей не теряются.
+ * DATA comparison of two environments (#6, sqlmesh's table_diff class): row
+ * counts, intersection by key, per-model column-mismatch rates — between the
+ * A and B view-layers of one database. On DuckDB-class data this is cheap;
+ * for large tables — a deterministic sample by md5 of the key: both sides are
+ * filtered by the same buckets, so the sample is aligned and key pairs are
+ * not lost.
  */
 
 export interface ColumnDrift {
   readonly column: string
-  /** Сколько сопоставленных ключей разошлись в этой колонке. */
+  /** How many matched keys diverged in this column. */
   readonly mismatches: number
-  /** Доля от matched, 0..1. */
+  /** Fraction of matched, 0..1. */
   readonly rate: number
 }
 
 export interface ModelDataDiff {
   readonly model: string
-  /** Полные счётчики строк (не задеты выборкой). */
+  /** Full row counts (not affected by sampling). */
   readonly rowsA: number
   readonly rowsB: number
-  /** Ключ сопоставления: grain или ключ вида (uniqueKey/scdType2). */
+  /** Matching key: grain or a kind's key (uniqueKey/scdType2). */
   readonly key?: ReadonlyArray<string>
-  /** Дальше — только при ключе; при выборке счётчики по выбранным бакетам. */
+  /** Below — only when there is a key; under sampling, counts over selected buckets. */
   readonly onlyInA?: number
   readonly onlyInB?: number
   readonly matched?: number
   readonly columns?: ReadonlyArray<ColumnDrift>
-  /** Колонки только одной стороны — дрейф схемы между окружениями. */
+  /** Columns present on only one side — schema drift between environments. */
   readonly columnsOnlyInA?: ReadonlyArray<string>
   readonly columnsOnlyInB?: ReadonlyArray<string>
-  /** Процент md5-бакетов ключа в сравнении; нет поля — сравнение полное. */
+  /** Percentage of the key's md5 buckets compared; no field — full comparison. */
   readonly sampledPercent?: number
 }
 
@@ -85,18 +85,22 @@ export interface DataDiffReport {
 }
 
 export interface DataDiffOptions {
-  /** Только эти модели; по умолчанию — все материализуемые из обоих окружений. */
+  /** Only these models; by default — all materializable ones from both environments. */
   readonly models?: ReadonlyArray<string>
-  /** 1–99: сравнивать долю ключей (md5-бакеты, выровнено между сторонами). */
+  /** 1–99: compare a fraction of keys (md5 buckets, aligned across sides). */
   readonly samplePercent?: number
 }
 
 export class DataDiffError extends Data.TaggedError("DataDiffError")<{
   readonly model: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `data diff of model «${this.model}»: ${this.reason}`
+  }
+}
 
-/** Виды с view-слоем в окружении — их данные есть с чем сравнивать. */
+/** Kinds with a view-layer in the environment — their data is comparable. */
 const COMPARABLE_KINDS: ReadonlySet<string> = new Set([
   "full",
   "view",
@@ -115,9 +119,9 @@ const keyOf = (model: AnyModel): ReadonlyArray<string> | undefined => {
 }
 
 /**
- * Детерминированный фильтр выборки: md5 от склейки ключа, первые два
- * hex-символа = 256 бакетов. Работает и на DuckDB, и на Postgres,
- * одинаково на обеих сторонах diff'а.
+ * Deterministic sampling filter: md5 of the concatenated key, first two
+ * hex chars = 256 buckets. Works on both DuckDB and Postgres, identically
+ * on both sides of the diff.
  */
 const samplePredicate = (key: ReadonlyArray<string>, percent: number): string => {
   const buckets = Math.max(1, Math.min(255, Math.floor((256 * percent) / 100)))
@@ -145,12 +149,12 @@ export const dataDiffEnvironments = (
     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: "модели нет в проекте" })
+        return yield* new DataDiffError({ model: name, reason: "model is not in the project" })
       }
       if (!inA.has(name) || !inB.has(name)) {
         return yield* new DataDiffError({
           model: name,
-          reason: `модели нет в окружении ${inA.has(name) ? envB : envA}`,
+          reason: `model is not in environment "${inA.has(name) ? envB : envA}"`,
         })
       }
     }
@@ -173,8 +177,8 @@ export const dataDiffEnvironments = (
         (yield* engine.query(`SELECT count(*) AS n FROM ${refB}`))[0]?.["n"],
       )
 
-      // реальные колонки обеих сторон: окружения могут указывать на разные
-      // версии модели — сравниваются только общие, дрейф схемы фиксируется
+      // actual columns of both sides: environments may point at different
+      // model versions — only common ones are compared, schema drift is recorded
       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)
@@ -186,8 +190,8 @@ export const dataDiffEnvironments = (
       const key = keyOf(model)
       const commonSet = new Set(common)
       if (key === undefined || !key.every((column) => commonSet.has(column))) {
-        // сопоставлять нечем (нет grain/ключа или ключ не на обеих сторонах) —
-        // честные счётчики строк без пары
+        // nothing to match on (no grain/key, or the key is not on both sides) —
+        // honest row counts without pairing
         reports.push({
           model: name,
           rowsA,