dbt-js 0.1.1 → 0.1.2

package/src/materialize.js

@@ -1,197 +1,197 @@
-import { quoteIdent, rel, relationKind, withTransaction } from './db.js';
-import { render } from './render.js';
-import { computeBatches } from './batches.js';
-
-export async function runModel(client, node, projectCfg, opts = {}) {
-  const { fullRefresh = false, vars } = opts;
-  const { name, config, rawSql } = node;
-  const schema = projectCfg.schema;
-  const target = rel(schema, name);
-  const kind = await relationKind(client, schema, name);
-  const isIncremental = config.materialized === 'incremental' && !fullRefresh && kind === 'r';
-
-  const ctx = {
-    name,
-    schema,
-    vars: vars ?? projectCfg.vars,
-    isIncremental,
-    sources: projectCfg.sources,
-    timezone: config.timezone,
-  };
-
-  // Hooks run outside the materialization transaction, one statement each, so
-  // they can use statements Postgres forbids inside a txn (VACUUM, CREATE
-  // INDEX CONCURRENTLY). Microbatch runs them once per model, not per batch.
-  await runHooks(client, config.pre_hook, 'pre_hook', ctx);
-
-  if (config.materialized === 'incremental' && config.strategy === 'microbatch') {
-    return runMicrobatch(client, node, projectCfg, { ...opts, kind, hookCtx: ctx });
-  }
-
-  const { sql } = render(rawSql, ctx);
-  const result = await materialize(client, { name, config, sql, target, kind, isIncremental });
-  await runHooks(client, config.post_hook, 'post_hook', ctx);
-  return result;
-}
-
-async function materialize(client, { name, config, sql, target, kind, isIncremental }) {
-  const sqlite = client.dialect === 'sqlite';
-  const cascade = sqlite ? '' : ' CASCADE'; // CASCADE is a SQLite syntax error
-
-  if (config.materialized === 'view') {
-    if (sqlite) {
-      // no CREATE OR REPLACE VIEW; SQLite DDL is transactional, so the wrap
-      // closes the window where the view would be absent
-      return withTransaction(client, async () => {
-        if (kind && kind !== 'v') await client.query(`DROP TABLE IF EXISTS ${target}`);
-        await client.query(`DROP VIEW IF EXISTS ${target}`);
-        await client.query(`CREATE VIEW ${target} AS\n${sql}`);
-        return { action: 'view' };
-      });
-    }
-    if (kind && kind !== 'v') await client.query(`DROP TABLE IF EXISTS ${target} CASCADE`);
-    await client.query(`CREATE OR REPLACE VIEW ${target} AS\n${sql}`);
-    return { action: 'view' };
-  }
-
-  if (!isIncremental) {
-    // table, or incremental first run / --full-refresh: transactional rebuild
-    return withTransaction(client, async () => {
-      if (kind === 'v') await client.query(`DROP VIEW IF EXISTS ${target}${cascade}`);
-      else await client.query(`DROP TABLE IF EXISTS ${target}${cascade}`);
-      const res = await client.query(`CREATE TABLE ${target} AS\n${sql}`);
-      const action = config.materialized === 'table' ? 'table' : 'incremental (full build)';
-      return { action, rowCount: res.rowCount };
-    });
-  }
-
-  if (config.strategy === 'append') {
-    const res = await client.query(`INSERT INTO ${target}\n${sql}`);
-    return { action: 'incremental append', rowCount: res.rowCount };
-  }
-
-  // delete+insert: compute the SELECT once into a temp table, swap within one txn
-  const keys = Array.isArray(config.unique_key) ? config.unique_key : [config.unique_key];
-  const temp = quoteIdent(`${name}__dbtjs_incr`);
-  const mysql = client.dialect === 'mysql';
-  return withTransaction(client, async () => {
-    // explicit DROP rather than ON COMMIT DROP — DuckDB silently ignores the latter
-    await client.query(`CREATE TEMPORARY TABLE ${temp} AS\n${sql}`);
-    const match = keys.map((k) => `t.${quoteIdent(k)} = i.${quoteIdent(k)}`).join(' AND ');
-    // MySQL has no Postgres-style DELETE ... USING ... WHERE; its multi-table
-    // form references the temp table once per statement, satisfying MySQL's
-    // single-reference rule for TEMPORARY tables. SQLite has neither form —
-    // correlated EXISTS against the aliased target instead.
-    await client.query(
-      sqlite
-        ? `DELETE FROM ${target} AS t WHERE EXISTS (SELECT 1 FROM ${temp} i WHERE ${match})`
-        : mysql
-          ? `DELETE t FROM ${target} t JOIN ${temp} i ON ${match}`
-          : `DELETE FROM ${target} t USING ${temp} i WHERE ${match}`
-    );
-    const res = await client.query(`INSERT INTO ${target} SELECT * FROM ${temp}`);
-    // TEMPORARY keyword on MySQL: plain DROP TABLE implicitly commits,
-    // which would break this transaction's atomicity
-    await client.query(`DROP ${mysql ? 'TEMPORARY ' : ''}TABLE ${temp}`);
-    return { action: 'incremental delete+insert', rowCount: res.rowCount };
-  });
-}
-
-async function runHooks(client, hooks, which, ctx) {
-  for (const [i, hook] of hooks.entries()) {
-    const { sql } = render(hook, ctx);
-    try {
-      await client.query(sql);
-    } catch (e) {
-      throw new Error(`${which}[${i}]: ${e.message}`);
-    }
-  }
-}
-
-// Microbatch: split the event-time range into aligned windows; each batch is its
-// own transaction that replaces the target rows inside its window. A failed
-// batch is recorded and the rest keep running (retry via --event-time-start/-end).
-async function runMicrobatch(client, node, projectCfg, opts) {
-  const { fullRefresh = false, vars, eventTimeStart, eventTimeEnd, onBatch, kind, hookCtx } = opts;
-  const { name, config, rawSql } = node;
-  const schema = projectCfg.schema;
-  const target = rel(schema, name);
-  const firstBuild = fullRefresh || kind !== 'r';
-
-  const batches = computeBatches({
-    begin: config.begin,
-    batchSize: config.batch_size,
-    lookback: config.lookback,
-    start: eventTimeStart,
-    end: eventTimeEnd,
-    firstBuild,
-    timezone: config.timezone,
-  });
-
-  const et = quoteIdent(config.event_time);
-  const sqlite = client.dialect === 'sqlite';
-  const cascade = sqlite ? '' : ' CASCADE';
-  const failed = [];
-  let total = 0;
-  let countUnknown = false;
-  let created = !firstBuild;
-
-  for (const b of batches) {
-    const { sql } = render(rawSql, {
-      name,
-      schema,
-      vars: vars ?? projectCfg.vars,
-      isIncremental: !firstBuild,
-      sources: projectCfg.sources,
-      batchStart: b.start,
-      batchEnd: b.end,
-      timezone: config.timezone,
-    });
-    try {
-      let rowCount;
-      if (!created) {
-        rowCount = await withTransaction(client, async () => {
-          if (kind === 'v') await client.query(`DROP VIEW IF EXISTS ${target}${cascade}`);
-          else await client.query(`DROP TABLE IF EXISTS ${target}${cascade}`);
-          const res = await client.query(`CREATE TABLE ${target} AS\n${sql}`);
-          return res.rowCount;
-        });
-        created = true;
-      } else {
-        rowCount = await withTransaction(client, async () => {
-          // SQLite compares timestamps as text, and a day-granularity event_time
-          // ('YYYY-MM-DD') sorts BELOW the batch boundary ('YYYY-MM-DD HH:MM:SS'
-          // from computeBatches) — datetime() normalizes both shapes
-          await client.query(
-            sqlite
-              ? `DELETE FROM ${target} WHERE datetime(${et}) >= datetime('${b.start}') AND datetime(${et}) < datetime('${b.end}')`
-              : `DELETE FROM ${target} WHERE ${et} >= '${b.start}' AND ${et} < '${b.end}'`
-          );
-          const res = await client.query(`INSERT INTO ${target}\n${sql}`);
-          return res.rowCount;
-        });
-      }
-      if (rowCount == null) countUnknown = true;
-      else total += rowCount;
-      onBatch?.({ ...b, ok: true, rowCount });
-    } catch (e) {
-      onBatch?.({ ...b, ok: false, message: e.message });
-      if (!created) {
-        // the target doesn't exist yet, so no later batch can insert into it
-        throw new Error(`first batch (${b.start}) failed: ${e.message}`);
-      }
-      failed.push({ ...b, message: e.message });
-    }
-  }
-
-  // skipped on partial failure: the model is already 'fail', don't stamp a
-  // success hook (grant, index, audit row) onto an incomplete build
-  if (!failed.length) await runHooks(client, config.post_hook, 'post_hook', hookCtx);
-
-  return {
-    action: 'incremental microbatch',
-    rowCount: countUnknown ? undefined : total,
-    batchCount: batches.length,
-    failedBatches: failed,
-  };
-}
+import { quoteIdent, rel, relationKind, withTransaction } from './db.js';
+import { render } from './render.js';
+import { computeBatches } from './batches.js';
+
+export async function runModel(client, node, projectCfg, opts = {}) {
+  const { fullRefresh = false, vars } = opts;
+  const { name, config, rawSql } = node;
+  const schema = projectCfg.schema;
+  const target = rel(schema, name);
+  const kind = await relationKind(client, schema, name);
+  const isIncremental = config.materialized === 'incremental' && !fullRefresh && kind === 'r';
+
+  const ctx = {
+    name,
+    schema,
+    vars: vars ?? projectCfg.vars,
+    isIncremental,
+    sources: projectCfg.sources,
+    timezone: config.timezone,
+  };
+
+  // Hooks run outside the materialization transaction, one statement each, so
+  // they can use statements Postgres forbids inside a txn (VACUUM, CREATE
+  // INDEX CONCURRENTLY). Microbatch runs them once per model, not per batch.
+  await runHooks(client, config.pre_hook, 'pre_hook', ctx);
+
+  if (config.materialized === 'incremental' && config.strategy === 'microbatch') {
+    return runMicrobatch(client, node, projectCfg, { ...opts, kind, hookCtx: ctx });
+  }
+
+  const { sql } = render(rawSql, ctx);
+  const result = await materialize(client, { name, config, sql, target, kind, isIncremental });
+  await runHooks(client, config.post_hook, 'post_hook', ctx);
+  return result;
+}
+
+async function materialize(client, { name, config, sql, target, kind, isIncremental }) {
+  const sqlite = client.dialect === 'sqlite';
+  const cascade = sqlite ? '' : ' CASCADE'; // CASCADE is a SQLite syntax error
+
+  if (config.materialized === 'view') {
+    if (sqlite) {
+      // no CREATE OR REPLACE VIEW; SQLite DDL is transactional, so the wrap
+      // closes the window where the view would be absent
+      return withTransaction(client, async () => {
+        if (kind && kind !== 'v') await client.query(`DROP TABLE IF EXISTS ${target}`);
+        await client.query(`DROP VIEW IF EXISTS ${target}`);
+        await client.query(`CREATE VIEW ${target} AS\n${sql}`);
+        return { action: 'view' };
+      });
+    }
+    if (kind && kind !== 'v') await client.query(`DROP TABLE IF EXISTS ${target} CASCADE`);
+    await client.query(`CREATE OR REPLACE VIEW ${target} AS\n${sql}`);
+    return { action: 'view' };
+  }
+
+  if (!isIncremental) {
+    // table, or incremental first run / --full-refresh: transactional rebuild
+    return withTransaction(client, async () => {
+      if (kind === 'v') await client.query(`DROP VIEW IF EXISTS ${target}${cascade}`);
+      else await client.query(`DROP TABLE IF EXISTS ${target}${cascade}`);
+      const res = await client.query(`CREATE TABLE ${target} AS\n${sql}`);
+      const action = config.materialized === 'table' ? 'table' : 'incremental (full build)';
+      return { action, rowCount: res.rowCount };
+    });
+  }
+
+  if (config.strategy === 'append') {
+    const res = await client.query(`INSERT INTO ${target}\n${sql}`);
+    return { action: 'incremental append', rowCount: res.rowCount };
+  }
+
+  // delete+insert: compute the SELECT once into a temp table, swap within one txn
+  const keys = Array.isArray(config.unique_key) ? config.unique_key : [config.unique_key];
+  const temp = quoteIdent(`${name}__dbtjs_incr`);
+  const mysql = client.dialect === 'mysql';
+  return withTransaction(client, async () => {
+    // explicit DROP rather than ON COMMIT DROP — DuckDB silently ignores the latter
+    await client.query(`CREATE TEMPORARY TABLE ${temp} AS\n${sql}`);
+    const match = keys.map((k) => `t.${quoteIdent(k)} = i.${quoteIdent(k)}`).join(' AND ');
+    // MySQL has no Postgres-style DELETE ... USING ... WHERE; its multi-table
+    // form references the temp table once per statement, satisfying MySQL's
+    // single-reference rule for TEMPORARY tables. SQLite has neither form —
+    // correlated EXISTS against the aliased target instead.
+    await client.query(
+      sqlite
+        ? `DELETE FROM ${target} AS t WHERE EXISTS (SELECT 1 FROM ${temp} i WHERE ${match})`
+        : mysql
+          ? `DELETE t FROM ${target} t JOIN ${temp} i ON ${match}`
+          : `DELETE FROM ${target} t USING ${temp} i WHERE ${match}`
+    );
+    const res = await client.query(`INSERT INTO ${target} SELECT * FROM ${temp}`);
+    // TEMPORARY keyword on MySQL: plain DROP TABLE implicitly commits,
+    // which would break this transaction's atomicity
+    await client.query(`DROP ${mysql ? 'TEMPORARY ' : ''}TABLE ${temp}`);
+    return { action: 'incremental delete+insert', rowCount: res.rowCount };
+  });
+}
+
+async function runHooks(client, hooks, which, ctx) {
+  for (const [i, hook] of hooks.entries()) {
+    const { sql } = render(hook, ctx);
+    try {
+      await client.query(sql);
+    } catch (e) {
+      throw new Error(`${which}[${i}]: ${e.message}`);
+    }
+  }
+}
+
+// Microbatch: split the event-time range into aligned windows; each batch is its
+// own transaction that replaces the target rows inside its window. A failed
+// batch is recorded and the rest keep running (retry via --event-time-start/-end).
+async function runMicrobatch(client, node, projectCfg, opts) {
+  const { fullRefresh = false, vars, eventTimeStart, eventTimeEnd, onBatch, kind, hookCtx } = opts;
+  const { name, config, rawSql } = node;
+  const schema = projectCfg.schema;
+  const target = rel(schema, name);
+  const firstBuild = fullRefresh || kind !== 'r';
+
+  const batches = computeBatches({
+    begin: config.begin,
+    batchSize: config.batch_size,
+    lookback: config.lookback,
+    start: eventTimeStart,
+    end: eventTimeEnd,
+    firstBuild,
+    timezone: config.timezone,
+  });
+
+  const et = quoteIdent(config.event_time);
+  const sqlite = client.dialect === 'sqlite';
+  const cascade = sqlite ? '' : ' CASCADE';
+  const failed = [];
+  let total = 0;
+  let countUnknown = false;
+  let created = !firstBuild;
+
+  for (const b of batches) {
+    const { sql } = render(rawSql, {
+      name,
+      schema,
+      vars: vars ?? projectCfg.vars,
+      isIncremental: !firstBuild,
+      sources: projectCfg.sources,
+      batchStart: b.start,
+      batchEnd: b.end,
+      timezone: config.timezone,
+    });
+    try {
+      let rowCount;
+      if (!created) {
+        rowCount = await withTransaction(client, async () => {
+          if (kind === 'v') await client.query(`DROP VIEW IF EXISTS ${target}${cascade}`);
+          else await client.query(`DROP TABLE IF EXISTS ${target}${cascade}`);
+          const res = await client.query(`CREATE TABLE ${target} AS\n${sql}`);
+          return res.rowCount;
+        });
+        created = true;
+      } else {
+        rowCount = await withTransaction(client, async () => {
+          // SQLite compares timestamps as text, and a day-granularity event_time
+          // ('YYYY-MM-DD') sorts BELOW the batch boundary ('YYYY-MM-DD HH:MM:SS'
+          // from computeBatches) — datetime() normalizes both shapes
+          await client.query(
+            sqlite
+              ? `DELETE FROM ${target} WHERE datetime(${et}) >= datetime('${b.start}') AND datetime(${et}) < datetime('${b.end}')`
+              : `DELETE FROM ${target} WHERE ${et} >= '${b.start}' AND ${et} < '${b.end}'`
+          );
+          const res = await client.query(`INSERT INTO ${target}\n${sql}`);
+          return res.rowCount;
+        });
+      }
+      if (rowCount == null) countUnknown = true;
+      else total += rowCount;
+      onBatch?.({ ...b, ok: true, rowCount });
+    } catch (e) {
+      onBatch?.({ ...b, ok: false, message: e.message });
+      if (!created) {
+        // the target doesn't exist yet, so no later batch can insert into it
+        throw new Error(`first batch (${b.start}) failed: ${e.message}`);
+      }
+      failed.push({ ...b, message: e.message });
+    }
+  }
+
+  // skipped on partial failure: the model is already 'fail', don't stamp a
+  // success hook (grant, index, audit row) onto an incomplete build
+  if (!failed.length) await runHooks(client, config.post_hook, 'post_hook', hookCtx);
+
+  return {
+    action: 'incremental microbatch',
+    rowCount: countUnknown ? undefined : total,
+    batchCount: batches.length,
+    failedBatches: failed,
+  };
+}

package/src/project.js

@@ -1,107 +1,139 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { basename, join } from 'node:path';
-
-const CONFIG_RE = /\/\*\s*config:\s*([\s\S]*?)\*\//;
-const MATERIALIZATIONS = new Set(['view', 'table', 'incremental']);
-const STRATEGIES = new Set(['append', 'delete+insert', 'microbatch']);
-const BATCH_SIZES = new Set(['hour', 'day', 'month', 'year']);
-
-// inlineModels: optional { name: rawSql } map (same format as a model file,
-// config comment included) — when given, models/ is not scanned.
-export function loadProject(cwd = process.cwd(), { models: inlineModels } = {}) {
-  const models = [];
-  if (inlineModels) {
-    for (const [name, rawSql] of Object.entries(inlineModels)) {
-      models.push({ name, rawSql, config: parseModelConfig(name, rawSql) });
-    }
-  } else {
-    const modelsDir = join(cwd, 'models');
-    if (existsSync(modelsDir)) {
-      for (const file of readdirSync(modelsDir).filter((f) => f.endsWith('.sql')).sort()) {
-        const path = join(modelsDir, file);
-        const rawSql = readFileSync(path, 'utf8');
-        const name = basename(file, '.sql');
-        models.push({ name, path, rawSql, config: parseModelConfig(name, rawSql) });
-      }
-    }
-  }
-
-  const seeds = [];
-  const seedsDir = join(cwd, 'seeds');
-  if (existsSync(seedsDir)) {
-    for (const file of readdirSync(seedsDir).filter((f) => f.endsWith('.csv')).sort()) {
-      seeds.push({ name: basename(file, '.csv'), path: join(seedsDir, file) });
-    }
-  }
-
-  const seen = new Set();
-  for (const { name } of [...models, ...seeds]) {
-    if (seen.has(name)) throw new Error(`Duplicate node name '${name}' across models/ and seeds/`);
-    seen.add(name);
-  }
-  if (!models.length && !seeds.length) {
-    throw new Error(`No models/*.sql or seeds/*.csv found in ${cwd} (and no inline models given)`);
-  }
-  return { models, seeds };
-}
-
-function parseModelConfig(name, rawSql) {
-  const match = rawSql.match(CONFIG_RE);
-  let config = {};
-  if (match) {
-    try {
-      config = JSON.parse(match[1]);
-    } catch (e) {
-      throw new Error(`Invalid JSON in config comment of model '${name}': ${e.message}`);
-    }
-  }
-  config.materialized ??= 'view';
-  if (!MATERIALIZATIONS.has(config.materialized)) {
-    throw new Error(`Model '${name}': unknown materialized '${config.materialized}' (use view|table|incremental)`);
-  }
-  config.timezone ??= 'UTC';
-  if (typeof config.timezone !== 'string') {
-    throw new Error(`Model '${name}': "timezone" must be a string (e.g. "UTC", "America/New_York")`);
-  }
-  try {
-    // RangeError on an unknown IANA zone; 'UTC' is always valid
-    new Intl.DateTimeFormat('en-US', { timeZone: config.timezone });
-  } catch {
-    throw new Error(`Model '${name}': unknown timezone '${config.timezone}' (use an IANA name like "America/New_York" or "UTC")`);
-  }
-  for (const key of ['pre_hook', 'post_hook']) {
-    if (typeof config[key] === 'string') config[key] = [config[key]];
-    config[key] ??= [];
-    if (!Array.isArray(config[key]) || config[key].some((h) => typeof h !== 'string' || !h.trim())) {
-      throw new Error(`Model '${name}': "${key}" must be a SQL string or array of SQL strings`);
-    }
-  }
-  if (config.materialized === 'incremental') {
-    config.strategy ??= 'append';
-    if (!STRATEGIES.has(config.strategy)) {
-      throw new Error(`Model '${name}': unknown strategy '${config.strategy}' (use append|delete+insert|microbatch)`);
-    }
-    if (config.strategy === 'delete+insert' && !config.unique_key) {
-      throw new Error(`Model '${name}': strategy delete+insert requires "unique_key"`);
-    }
-    if (config.strategy === 'microbatch') {
-      if (typeof config.event_time !== 'string' || !config.event_time) {
-        throw new Error(`Model '${name}': microbatch requires "event_time" (a column of this model)`);
-      }
-      if (!config.begin || Number.isNaN(Date.parse(String(config.begin).replace(' ', 'T')))) {
-        throw new Error(`Model '${name}': microbatch requires "begin" (start of history, e.g. "2026-01-01")`);
-      }
-      if (!BATCH_SIZES.has(config.batch_size)) {
-        throw new Error(`Model '${name}': microbatch requires "batch_size" (hour|day|month|year)`);
-      }
-      config.lookback ??= 1;
-      if (!Number.isInteger(config.lookback) || config.lookback < 0) {
-        throw new Error(`Model '${name}': "lookback" must be a non-negative integer`);
-      }
-      if (config.unique_key) {
-        throw new Error(`Model '${name}': "unique_key" is not used by microbatch (batches replace by event_time window)`);
-      }
-    }
-  }
-  return config;
-}
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const CONFIG_RE = /\/\*\s*config:\s*([\s\S]*?)\*\//;
+const MATERIALIZATIONS = new Set(['view', 'table', 'incremental']);
+const STRATEGIES = new Set(['append', 'delete+insert', 'microbatch']);
+const BATCH_SIZES = new Set(['hour', 'day', 'month', 'year']);
+
+// inlineModels: optional { name: rawSql } map (same format as a model file,
+// config comment included) — when given, models/ is not scanned.
+export function loadProject(cwd = process.cwd(), { models: inlineModels } = {}) {
+  const models = [];
+  if (inlineModels) {
+    for (const [name, rawSql] of Object.entries(inlineModels)) {
+      models.push({ name, rawSql, config: parseModelConfig(name, rawSql) });
+    }
+  } else {
+    const modelsDir = join(cwd, 'models');
+    if (existsSync(modelsDir)) {
+      for (const file of readdirSync(modelsDir).filter((f) => f.endsWith('.sql')).sort()) {
+        const path = join(modelsDir, file);
+        const rawSql = readFileSync(path, 'utf8');
+        const name = basename(file, '.sql');
+        models.push({ name, path, rawSql, config: parseModelConfig(name, rawSql) });
+      }
+    }
+  }
+
+  const seeds = [];
+  const seedsDir = join(cwd, 'seeds');
+  if (existsSync(seedsDir)) {
+    for (const file of readdirSync(seedsDir).filter((f) => f.endsWith('.csv')).sort()) {
+      seeds.push({ name: basename(file, '.csv'), path: join(seedsDir, file) });
+    }
+  }
+
+  const seen = new Set();
+  for (const { name } of [...models, ...seeds]) {
+    // ref()/source() in render.js only match \w+, so a name with other
+    // characters (e.g. "my-model") loads but is unreferenceable — reject it
+    // here with a clear message instead of a misleading template error later.
+    if (!/^\w+$/.test(name)) {
+      throw new Error(
+        `Invalid node name '${name}' — model and seed names must be word characters only ` +
+          `([A-Za-z0-9_]) so they can be used in ref()/source()`
+      );
+    }
+    if (seen.has(name)) throw new Error(`Duplicate node name '${name}' across models/ and seeds/`);
+    seen.add(name);
+  }
+  if (!models.length && !seeds.length) {
+    throw new Error(`No models/*.sql or seeds/*.csv found in ${cwd} (and no inline models given)`);
+  }
+  return { models, seeds };
+}
+
+function parseModelConfig(name, rawSql) {
+  const match = rawSql.match(CONFIG_RE);
+  let config = {};
+  if (match) {
+    try {
+      config = JSON.parse(match[1]);
+    } catch (e) {
+      throw new Error(`Invalid JSON in config comment of model '${name}': ${e.message}`);
+    }
+  }
+  config.materialized ??= 'view';
+  if (!MATERIALIZATIONS.has(config.materialized)) {
+    throw new Error(`Model '${name}': unknown materialized '${config.materialized}' (use view|table|incremental)`);
+  }
+  config.timezone ??= 'UTC';
+  if (typeof config.timezone !== 'string') {
+    throw new Error(`Model '${name}': "timezone" must be a string (e.g. "UTC", "America/New_York")`);
+  }
+  try {
+    // RangeError on an unknown IANA zone; 'UTC' is always valid
+    new Intl.DateTimeFormat('en-US', { timeZone: config.timezone });
+  } catch {
+    throw new Error(`Model '${name}': unknown timezone '${config.timezone}' (use an IANA name like "America/New_York" or "UTC")`);
+  }
+  for (const key of ['pre_hook', 'post_hook']) {
+    if (typeof config[key] === 'string') config[key] = [config[key]];
+    config[key] ??= [];
+    if (!Array.isArray(config[key]) || config[key].some((h) => typeof h !== 'string' || !h.trim())) {
+      throw new Error(`Model '${name}': "${key}" must be a SQL string or array of SQL strings`);
+    }
+  }
+  if (config.materialized === 'incremental') {
+    config.strategy ??= 'append';
+    if (!STRATEGIES.has(config.strategy)) {
+      throw new Error(`Model '${name}': unknown strategy '${config.strategy}' (use append|delete+insert|microbatch)`);
+    }
+    if (config.strategy === 'delete+insert' && !config.unique_key) {
+      throw new Error(`Model '${name}': strategy delete+insert requires "unique_key"`);
+    }
+    if (config.strategy === 'microbatch') {
+      if (typeof config.event_time !== 'string' || !config.event_time) {
+        throw new Error(`Model '${name}': microbatch requires "event_time" (a column of this model)`);
+      }
+      if (!config.begin || Number.isNaN(Date.parse(String(config.begin).replace(' ', 'T')))) {
+        throw new Error(`Model '${name}': microbatch requires "begin" (start of history, e.g. "2026-01-01")`);
+      }
+      if (!BATCH_SIZES.has(config.batch_size)) {
+        throw new Error(`Model '${name}': microbatch requires "batch_size" (hour|day|month|year)`);
+      }
+      config.lookback ??= 1;
+      if (!Number.isInteger(config.lookback) || config.lookback < 0) {
+        throw new Error(`Model '${name}': "lookback" must be a non-negative integer`);
+      }
+      if (config.unique_key) {
+        throw new Error(`Model '${name}': "unique_key" is not used by microbatch (batches replace by event_time window)`);
+      }
+    }
+  }
+  if (config.tests !== undefined) {
+    // Validate at load so compile/run/ls surface a bad spec, not just `test`.
+    if (typeof config.tests !== 'object' || Array.isArray(config.tests)) {
+      throw new Error(`Model '${name}': "tests" must be an object mapping column -> array of tests`);
+    }
+    for (const [column, specs] of Object.entries(config.tests)) {
+      if (!Array.isArray(specs)) {
+        throw new Error(`Model '${name}': tests for column '${column}' must be an array (e.g. ["not_null", "unique"])`);
+      }
+      for (const spec of specs) {
+        const ok =
+          spec === 'not_null' ||
+          spec === 'unique' ||
+          (spec && typeof spec === 'object' && Array.isArray(spec.accepted_values) && spec.accepted_values.length > 0);
+        if (!ok) {
+          throw new Error(
+            `Model '${name}': invalid test ${JSON.stringify(spec)} on column '${column}' ` +
+              `(use "not_null", "unique", or { "accepted_values": [...] } with a non-empty list)`
+          );
+        }
+      }
+    }
+  }
+  return config;
+}