@avytheone/efmesh 0.2.0 → 0.2.1

package/src/config.ts

@@ -1,43 +1,43 @@
 import type { AnyModel } from "./core/model.ts"
 
 /**
- * Конфиг проекта — `efmesh.config.ts` (SPEC §11): типизированный TS-модуль,
- * никакого YAML. CLI импортирует его и собирает слои движка и состояния.
+ * Project config — `efmesh.config.ts` (SPEC §11): a typed TS module, no
+ * YAML. The CLI imports it and assembles the engine and state layers.
  */
 export interface EfmeshConfig {
-  /** Модели значениями; можно вместе с discovery — дубликат имени = ошибка. */
+  /** Models by value; can be combined with discovery — a duplicate name is an error. */
   readonly models?: ReadonlyArray<AnyModel>
   /**
-   * Glob-маски файлов моделей относительно конфига (SPEC §12):
-   * все экспорты-модели найденных файлов попадают в проект.
+   * Glob masks for model files, relative to the config (SPEC §12):
+   * every model export found in matched files joins the project.
    */
   readonly discovery?: string | ReadonlyArray<string>
   readonly engine?: {
-    /** Путь к файлу DuckDB; по умолчанию `efmesh.duckdb` рядом с конфигом. */
+    /** Path to the DuckDB file; defaults to `efmesh.duckdb` next to the config. */
     readonly path?: string
-    /** postgres://… — движком становится Postgres (F3); path игнорируется. */
+    /** postgres://… — switches the engine to Postgres (F3); path is ignored. */
     readonly url?: string
-    /** Размер пула соединений Postgres — параллелизм бэкфилла (SPEC §5.3). */
+    /** Postgres connection pool size — backfill parallelism (SPEC §5.3). */
     readonly max?: number
   }
   readonly state?: {
-    /** Путь к SQLite-файлу состояния; по умолчанию `efmesh.state.sqlite`. */
+    /** Path to the SQLite state file; defaults to `efmesh.state.sqlite`. */
     readonly path?: string
-    /** postgres://… — состояние в Postgres (схема efmesh_state, SPEC §6). */
+    /** postgres://… — state lives in Postgres (schema efmesh_state, SPEC §6). */
     readonly url?: string
   }
   readonly lake?: {
-    /** Корень parquet-озера (SPEC §3.3) — локальная директория или s3://…. */
+    /** Root of the parquet lake (SPEC §3.3) — a local directory or s3://…. */
     readonly path: string
   }
-  /** DuckLake-каталог для target: "ducklake" (SPEC §14.5). DuckDB-only. */
+  /** DuckLake catalog for target: "ducklake" (SPEC §14.5). DuckDB-only. */
   readonly ducklake?: {
-    /** Путь к SQLite-файлу каталога DuckLake. */
+    /** Path to the DuckLake catalog's SQLite file. */
     readonly catalog: string
-    /** Куда DuckLake кладёт parquet-данные; по умолчанию — рядом с каталогом. */
+    /** Where DuckLake writes parquet data; defaults to next to the catalog. */
     readonly dataPath?: string
   }
-  /** ATTACH-базы по алиасам (SPEC §9.3): url + опции (`TYPE postgres` и т.п.). */
+  /** ATTACH databases by alias (SPEC §9.3): url + options (`TYPE postgres` etc.). */
   readonly attach?: Readonly<Record<string, { readonly url: string; readonly options?: string }>>
 }
 

package/src/core/audit.ts

@@ -2,26 +2,30 @@ import { Data, type Schema } from "effect"
 import type { SelfValue, SqlFragment, SqlLiteral } from "./sql.ts"
 import { quoteIdent, sql } from "./sql.ts"
 
-/** Blocking-аудит нашёл нарушения: снапшот/интервал не считается годным. */
+/** A blocking audit found violations: the snapshot/interval is considered unfit. */
 export class AuditFailure extends Data.TaggedError("AuditFailure")<{
   readonly model: string
   readonly audit: string
   readonly violations: number
-}> {}
+}> {
+  override get message(): string {
+    return `audit ${this.audit} on model «${this.model}»: ${this.violations} violating row(s)`
+  }
+}
 
 /**
- * Аудит (SPEC §8) — SQL-предикат над результатом модели: запрос возвращает
- * НАРУШАЮЩИЕ строки, непустой результат = провал. `ctx.self` рендерится
- * в физику снапшота (у incremental — в подзапрос обработанного интервала,
- * аудит проверяет то, что только что загрузили, а не всю историю).
+ * Audit (SPEC §8) — a SQL predicate over a model's result: the query returns
+ * the VIOLATING rows, a non-empty result means failure. `ctx.self` renders
+ * to the snapshot's physical table (for incremental, to a subquery of the
+ * processed interval — the audit checks what was just loaded, not the whole history).
  *
- * blocking-аудит (по умолчанию) роняет apply: интервал помечается failed,
- * view не промоутится. warn — лог + конвейер едет дальше.
+ * A blocking audit (the default) fails apply: the interval is marked failed,
+ * the view is not promoted. warn — logs and lets the pipeline continue.
  */
 export interface Audit {
   readonly name: string
   readonly blocking: boolean
-  /** Запрос нарушений; содержит узел Self. */
+  /** The violations query; contains a Self node. */
   readonly fragment: SqlFragment
 }
 
@@ -32,7 +36,7 @@ export interface AuditCtx {
 
 const SELF: SelfValue = { _tag: "SelfValue" }
 
-/** Билдеры типизированы колонками модели через параметр Fields. */
+/** Builders are typed by the model's columns via the Fields type parameter. */
 export const audit = {
   notNull: <Fields extends Schema.Struct.Fields>(
     column: Extract<keyof Fields, string>,
@@ -72,7 +76,7 @@ export const audit = {
     fragment: body({ sql, self: SELF }),
   }),
 
-  /** Понизить аудит до предупреждения: лог вместо провала. */
+  /** Downgrade an audit to a warning: log instead of failing. */
   warn: (base: Audit): Audit => ({ ...base, blocking: false }),
 } as const
 

package/src/core/errors.ts

@@ -1,27 +1,57 @@
 import { Data } from "effect"
+import { causeText } from "../error-text.ts"
 
-/** Некорректная конфигурация модели: битое имя, self-ref и т.п. Бросается на этапе загрузки модуля. */
+/** Invalid model configuration: a malformed name, a self-ref, etc. Thrown at module load time. */
 export class ModelDefinitionError extends Data.TaggedError("ModelDefinitionError")<{
   readonly model: string
   readonly reason: string
-}> {}
+}> {
+  override get message(): string {
+    return `model «${this.model}»: ${this.reason}`
+  }
+}
 
 export class DuplicateModelError extends Data.TaggedError("DuplicateModelError")<{
   readonly name: string
-}> {}
+}> {
+  override get message(): string {
+    return `model «${this.name}» is defined twice — names must be unique across the project`
+  }
+}
 
 export class UnknownDependencyError extends Data.TaggedError("UnknownDependencyError")<{
   readonly model: string
   readonly dependency: string
-}> {}
+}> {
+  override get message(): string {
+    return `model «${this.model}» depends on «${this.dependency}», which is not in the project`
+  }
+}
 
 export class DagCycleError extends Data.TaggedError("DagCycleError")<{
   readonly cycle: ReadonlyArray<string>
-}> {}
+}> {
+  override get message(): string {
+    return `dependency cycle: ${this.cycle.join(" → ")}`
+  }
+}
 
-/** Файл seed-модели не читается — fingerprint и сборка невозможны. */
+/** A seed model's file can't be read — fingerprint and assembly are impossible. */
 export class SeedReadError extends Data.TaggedError("SeedReadError")<{
   readonly model: string
   readonly file: string
   readonly cause: unknown
-}> {}
+}> {
+  override get message(): string {
+    return `seed «${this.model}»: cannot read ${this.file} — ${causeText(this.cause)}`
+  }
+}
+
+/** A model name handed to the facade/CLI (render, lineage) is not in the project. */
+export class UnknownModelError extends Data.TaggedError("UnknownModelError")<{
+  readonly model: string
+}> {
+  override get message(): string {
+    return `model «${this.model}» is not in the project`
+  }
+}

package/src/core/graph.ts

@@ -4,15 +4,15 @@ import type { AnyModel } from "./model.ts"
 
 export interface ModelGraph {
   readonly models: ReadonlyMap<string, AnyModel>
-  /** Топологический порядок: родители раньше детей. */
+  /** Topological order: parents before children. */
   readonly order: ReadonlyArray<string>
-  /** Прямые потомки: кто ссылается на данную модель. */
+  /** Direct dependents: who references this model. */
   readonly dependents: ReadonlyMap<string, ReadonlySet<string>>
 }
 
 export type GraphError = DuplicateModelError | UnknownDependencyError | DagCycleError
 
-/** Собирает DAG из набора моделей: дубликаты, неизвестные зависимости, циклы — типизированные ошибки. */
+/** Builds a DAG from a set of models: duplicates, unknown dependencies, cycles — typed errors. */
 export const buildGraph = (
   input: Iterable<AnyModel>,
 ): Effect.Effect<ModelGraph, GraphError> =>
@@ -36,10 +36,10 @@ export const buildGraph = (
       }
     }
 
-    // Кан: считаем входящие степени (число зависимостей), снимаем нулевые.
+    // Kahn's algorithm: count in-degrees (number of dependencies), drain the zeros.
     const inDegree = new Map<string, number>()
     for (const [name, model] of models) inDegree.set(name, model.deps.size)
-    // сортировка очереди — чтобы порядок был детерминированным между запусками
+    // sort the queue so the order is deterministic across runs
     const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([n]) => n).sort()
     const order: Array<string> = []
     while (queue.length > 0) {
@@ -60,7 +60,7 @@ export const buildGraph = (
     return { models, order, dependents }
   })
 
-/** Все транзитивные потомки модели (для breaking-каскада в плане). */
+/** All transitive dependents of a model (for the breaking cascade in a plan). */
 export const transitiveDependents = (graph: ModelGraph, name: string): ReadonlySet<string> => {
   const out = new Set<string>()
   const stack = [name]

package/src/core/interval.ts

@@ -1,11 +1,11 @@
 /**
- * Интервальная арифметика (SPEC §2, §5.3): полуинтервалы `[start, end)`
- * времени UTC, выровненные по зерну модели. Учёт заполненных интервалов —
- * основа инкрементальности и бэкфилла; здесь только чистая математика,
- * состояние живёт в state store.
+ * Interval arithmetic (SPEC §2, §5.3): half-open `[start, end)` UTC time
+ * intervals, aligned to the model's grain. Tracking which intervals are
+ * filled is the basis of incrementality and backfill; this module is pure
+ * math only, state lives in the state store.
  *
- * Внутреннее представление — epoch millis: зёрна day/hour в UTC не зависят
- * от календаря, деление с округлением вниз даёт выравнивание.
+ * Internal representation is epoch millis: day/hour grains in UTC don't
+ * depend on the calendar, and floor division gives alignment.
  */
 
 export type IntervalUnit = "day" | "hour"
@@ -26,9 +26,9 @@ export const floorTo = (unit: IntervalUnit, ms: number): number => {
 }
 
 /**
- * Все завершённые интервалы зерна от `startMs` до `nowMs`:
- * начало выравнивается вниз, последний интервал — тот, что уже закончился
- * (`end <= floor(now)` — недописанное «сегодня» не считается).
+ * All completed grain intervals from `startMs` to `nowMs`:
+ * the start is floor-aligned, and the last interval is one that has
+ * already ended (`end <= floor(now)` — an unfinished "today" doesn't count).
  */
 export const enumerateIntervals = (
   unit: IntervalUnit,
@@ -45,7 +45,7 @@ export const enumerateIntervals = (
   return intervals
 }
 
-/** `wanted` минус `covered` (сравнение по `start`; интервалы одного зерна). */
+/** `wanted` minus `covered` (compared by `start`; intervals of the same grain). */
 export const missingIntervals = (
   wanted: ReadonlyArray<Interval>,
   covered: ReadonlyArray<Interval>,
@@ -54,7 +54,7 @@ export const missingIntervals = (
   return wanted.filter((i) => !done.has(i.start))
 }
 
-/** Смежные интервалы сливаются в непрерывные диапазоны (вход — отсортированный). */
+/** Adjacent intervals merge into contiguous ranges (input must be sorted). */
 export const mergeIntervals = (
   intervals: ReadonlyArray<Interval>,
 ): ReadonlyArray<Interval> => {
@@ -71,8 +71,8 @@ export const mergeIntervals = (
 }
 
 /**
- * Режет диапазон на батчи не длиннее `batchSize` интервалов зерна.
- * Батч — единица исполнения (один DELETE+INSERT), интервал — единица учёта.
+ * Slices a range into batches no longer than `batchSize` grain intervals.
+ * A batch is the unit of execution (one DELETE+INSERT); an interval is the unit of tracking.
  */
 export const splitIntoBatches = (
   range: Interval,
@@ -80,7 +80,7 @@ export const splitIntoBatches = (
   batchSize: number,
 ): ReadonlyArray<Interval> => {
   if (!Number.isInteger(batchSize) || batchSize < 1) {
-    throw new RangeError(`batchSize должен быть целым ≥ 1, получен ${batchSize}`)
+    throw new RangeError(`batchSize must be an integer ≥ 1, got ${batchSize}`)
   }
   const step = unitMillis[unit] * batchSize
   const batches: Array<Interval> = []
@@ -90,7 +90,7 @@ export const splitIntoBatches = (
   return batches
 }
 
-/** Интервалы зерна внутри диапазона (для поинтервальной отметки done после батча). */
+/** Grain intervals within a range (for marking each one done after a batch). */
 export const intervalsWithin = (
   range: Interval,
   unit: IntervalUnit,
@@ -103,16 +103,16 @@ export const intervalsWithin = (
   return intervals
 }
 
-/** ISO-8601 UTC — формат хранения границ в state store (сортируется лексикографически). */
+/** ISO-8601 UTC — the storage format for bounds in the state store (sorts lexicographically). */
 export const toIso = (ms: number): string => new Date(ms).toISOString()
 
 export const fromIso = (iso: string): number => {
   const ms = Date.parse(iso)
-  if (Number.isNaN(ms)) throw new RangeError(`не ISO-время: ${iso}`)
+  if (Number.isNaN(ms)) throw new RangeError(`not an ISO time: ${iso}`)
   return ms
 }
 
-/** Литерал для подстановки границы интервала в SQL DuckDB. */
+/** Literal for substituting an interval bound into DuckDB SQL. */
 export const sqlTimestamp = (ms: number): string => {
   const iso = new Date(ms).toISOString()
   return `TIMESTAMP '${iso.slice(0, 10)} ${iso.slice(11, 19)}'`