@sqlanvil/cli 1.8.3 → 1.10.0

package/bundle.js

@@ -42996,6 +42996,24 @@ from (${query}) as insertions`;
             `) AS\n${exp.query}`;
         return [sqlanvil.ExecutionTask.create({ type: "statement", statement })];
     }
+    validationStubSql(table) {
+        const target = this.resolveTarget(table.target);
+        if (table.enumType === sqlanvil.TableType.VIEW) {
+            return `create view ${target} as ${table.query}`;
+        }
+        return `create table ${target} as select * from (${table.query}) limit 0`;
+    }
+    createSchemaSql(schema) {
+        return `create schema if not exists ${this.qualifiedSchema(schema)}`;
+    }
+    dropSchemaCascadeSql(schema) {
+        return `drop schema if exists ${this.qualifiedSchema(schema)} cascade`;
+    }
+    qualifiedSchema(schema) {
+        return this.project.defaultDatabase
+            ? `\`${this.project.defaultDatabase}.${schema}\``
+            : `\`${schema}\``;
+    }
     buildIncrementalSchemaChangeTasks(tasks, table) {
         const uniqueId = this.uniqueIdGenerator();
         const emptyTempTableTarget = Object.assign(Object.assign({}, table.target), { name: `${table.target.name}_sa_temp_${uniqueId}_empty` });
@@ -43206,6 +43224,19 @@ class MysqlExecutionSql {
     createExportTasks(exp) {
         throw new Error("type: \"export\" is not supported on MySQL/MariaDB yet.");
     }
+    validationStubSql(table) {
+        const target = this.resolveTarget(table.target);
+        if (table.enumType === sqlanvil.TableType.VIEW) {
+            return `create or replace view ${target} as ${table.query}`;
+        }
+        return `create table ${target} as select * from (${table.query}) as _sa_stub limit 0`;
+    }
+    createSchemaSql(schema) {
+        return `create database if not exists \`${schema}\``;
+    }
+    dropSchemaCascadeSql(schema) {
+        return `drop database if exists \`${schema}\``;
+    }
     publishTasks(table, runConfig, tableMetadata) {
         const tasks = new Tasks();
         const target = this.resolveTarget(table.target);
@@ -43370,6 +43401,19 @@ class PostgresExecutionSql {
         const kind = type === sqlanvil.TableMetadata.Type.VIEW ? "view" : "table";
         return `drop ${kind} if exists ${this.resolveTarget(target)} cascade`;
     }
+    validationStubSql(table) {
+        const target = this.resolveTarget(table.target);
+        if (table.enumType === sqlanvil.TableType.VIEW) {
+            return `create view ${target} as ${table.query}`;
+        }
+        return `create table ${target} as ${table.query} with no data`;
+    }
+    createSchemaSql(schema) {
+        return `create schema if not exists "${schema}"`;
+    }
+    dropSchemaCascadeSql(schema) {
+        return `drop schema if exists "${schema}" cascade`;
+    }
     createExportTasks(exp) {
         return [sqlanvil.ExecutionTask.create({ type: "export", statement: exp.query })];
     }
@@ -43682,6 +43726,15 @@ class ExecutionSql {
     dropIfExists(target, type) {
         return this.delegate.dropIfExists(target, type);
     }
+    validationStubSql(table) {
+        return this.delegate.validationStubSql(table);
+    }
+    createSchemaSql(schema) {
+        return this.delegate.createSchemaSql(schema);
+    }
+    dropSchemaCascadeSql(schema) {
+        return this.delegate.dropSchemaCascadeSql(schema);
+    }
 }
 function collectEvaluationQueries(queryOrAction, concatenate, queryModifier = (q) => q) {
     const validationQueries = new Array();
@@ -43739,7 +43792,7 @@ function collectEvaluationQueries(queryOrAction, concatenate, queryModifier = (q
         .filter(validationQuery => !!validationQuery.query);
 }
 
-const version = "1.8.3";
+const version = "1.10.0";
 const dataformVersion = "3.0.60";
 
 async function build(compiledGraph, runConfig, dbadapter) {
@@ -44406,6 +44459,53 @@ function assertConnectionCredentialsAvailable(graph, connections) {
     }));
 }
 
+function loadDuckdb() {
+    try {
+        return nativeRequire("@duckdb/node-api");
+    }
+    catch (e) {
+        throw new Error(`This feature requires the optional "@duckdb/node-api" dependency, which failed to load: ` +
+            `${e.message}`);
+    }
+}
+async function runAsync(conn, sql) {
+    await conn.run(sql);
+}
+async function allAsync(conn, sql) {
+    const reader = await conn.runAndReadAll(sql);
+    return reader.getRowObjects();
+}
+async function withDuckdb(fn, dbPath = ":memory:") {
+    const { DuckDBInstance } = loadDuckdb();
+    const instance = await DuckDBInstance.create(dbPath);
+    const conn = await instance.connect();
+    const done = () => {
+        var _a, _b;
+        try {
+            (_a = conn.closeSync) === null || _a === void 0 ? void 0 : _a.call(conn);
+        }
+        catch (e) {
+        }
+        try {
+            (_b = instance.closeSync) === null || _b === void 0 ? void 0 : _b.call(instance);
+        }
+        catch (e) {
+        }
+    };
+    try {
+        if (!process.env.HOME) {
+            await runAsync(conn, `SET home_directory='${os__namespace.tmpdir()}'`);
+        }
+        const result = await fn(conn);
+        done();
+        return result;
+    }
+    catch (e) {
+        done();
+        throw e;
+    }
+}
+
 const PG_ATTACH_ALIAS = "pg";
 const SECRET_NAME = "sa_export";
 function buildAttachSql(pg) {
@@ -44469,48 +44569,6 @@ function buildCopySql(selectSql, uri, format, options = {}) {
     const optionList = [`FORMAT ${fmt}`, ...extraOptions].join(", ");
     return `COPY (SELECT * FROM postgres_query('${PG_ATTACH_ALIAS}', $sa$${selectSql}$sa$)) TO '${target}' (${optionList})`;
 }
-function loadDuckdb() {
-    try {
-        return nativeRequire("@duckdb/node-api");
-    }
-    catch (e) {
-        throw new Error(`Exporting on Postgres/Supabase requires the optional "@duckdb/node-api" dependency, which ` +
-            `failed to load: ${e.message}`);
-    }
-}
-async function runAsync(conn, sql) {
-    await conn.run(sql);
-}
-async function withConnection(fn) {
-    const { DuckDBInstance } = loadDuckdb();
-    const instance = await DuckDBInstance.create(":memory:");
-    const conn = await instance.connect();
-    const done = () => {
-        var _a, _b;
-        try {
-            (_a = conn.closeSync) === null || _a === void 0 ? void 0 : _a.call(conn);
-        }
-        catch (e) {
-        }
-        try {
-            (_b = instance.closeSync) === null || _b === void 0 ? void 0 : _b.call(instance);
-        }
-        catch (e) {
-        }
-    };
-    try {
-        if (!process.env.HOME) {
-            await runAsync(conn, `SET home_directory='${os__namespace.tmpdir()}'`);
-        }
-        const result = await fn(conn);
-        done();
-        return result;
-    }
-    catch (e) {
-        done();
-        throw e;
-    }
-}
 async function runDuckdbExport(args) {
     const { spec, selectSql, pg, storage, actionName } = args;
     const uri = resolveExportUri(spec, actionName, { wildcard: false });
@@ -44519,7 +44577,7 @@ async function runDuckdbExport(args) {
         throw new Error(`No "${scheme}" storage credentials found in .df-credentials.json (storage.${scheme}) for ` +
             `export to ${uri}.`);
     }
-    return withConnection(async (conn) => {
+    return withDuckdb(async (conn) => {
         await runAsync(conn, "INSTALL postgres; LOAD postgres; INSTALL httpfs; LOAD httpfs;");
         await runAsync(conn, buildAttachSql(pg));
         if (scheme !== "local") {
@@ -45151,6 +45209,520 @@ function resolveCredentials(envCredentials, cliCredentials, defaultFilename) {
     return envCredentials || defaultFilename;
 }
 
+function key(target) {
+    return targetStringifier.stringify(target);
+}
+function enumName(enumObject, value) {
+    if (value === undefined || value === null) {
+        return "UNKNOWN";
+    }
+    const match = Object.keys(enumObject).find(k => enumObject[k] === value);
+    return match || String(value);
+}
+function tableType$1(enumType) {
+    switch (enumType) {
+        case sqlanvil.TableType.VIEW:
+            return "view";
+        case sqlanvil.TableType.INCREMENTAL:
+            return "incremental";
+        default:
+            return "table";
+    }
+}
+function toMillis(value) {
+    if (value === undefined || value === null) {
+        return 0;
+    }
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value.toNumber === "function") {
+        return value.toNumber();
+    }
+    return Number(value) || 0;
+}
+function actionRow(action, type) {
+    const descriptor = action.actionDescriptor || {};
+    return {
+        target_key: key(action.target),
+        database: action.target.database || "",
+        schema: action.target.schema || "",
+        name: action.target.name || "",
+        readable_name: targetAsReadableString(action.target),
+        type,
+        tags: JSON.stringify(action.tags || []),
+        disabled: !!action.disabled,
+        file_name: action.fileName || "",
+        description: descriptor.description || ""
+    };
+}
+function pushDeps(action, out) {
+    for (const dep of action.dependencyTargets || []) {
+        out.push({
+            from_target_key: key(action.target),
+            to_target_key: key(dep),
+            from_readable: targetAsReadableString(action.target),
+            to_readable: targetAsReadableString(dep)
+        });
+    }
+}
+function pushColumns(action, out) {
+    const columns = (action.actionDescriptor && action.actionDescriptor.columns) || [];
+    for (const column of columns) {
+        out.push({
+            target_key: key(action.target),
+            readable_name: targetAsReadableString(action.target),
+            column_name: (column.path || []).join("."),
+            description: column.description || ""
+        });
+    }
+}
+function catalogRows(compiledGraph) {
+    const actions = [];
+    const dependencies = [];
+    const columns = [];
+    const add = (action, type) => {
+        actions.push(actionRow(action, type));
+        pushDeps(action, dependencies);
+        pushColumns(action, columns);
+    };
+    for (const table of compiledGraph.tables || []) {
+        add(table, tableType$1(table.enumType));
+    }
+    for (const operation of compiledGraph.operations || []) {
+        add(operation, "operation");
+    }
+    for (const assertion of compiledGraph.assertions || []) {
+        add(assertion, "assertion");
+    }
+    for (const exp of compiledGraph.exports || []) {
+        add(exp, "export");
+    }
+    for (const declaration of compiledGraph.declarations || []) {
+        add(declaration, "declaration");
+    }
+    return { actions, dependencies, columns };
+}
+function runRows(runResult, runId) {
+    const runStatus = enumName(sqlanvil.RunResult.ExecutionStatus, runResult.status);
+    return (runResult.actions || []).map(action => {
+        const start = toMillis(action.timing && action.timing.startTimeMillis);
+        const end = toMillis(action.timing && action.timing.endTimeMillis);
+        const failedTask = (action.tasks || []).find(t => !!t.errorMessage);
+        return {
+            run_id: runId,
+            run_status: runStatus,
+            target_key: key(action.target),
+            readable_name: targetAsReadableString(action.target),
+            status: enumName(sqlanvil.ActionResult.ExecutionStatus, action.status),
+            start_millis: start,
+            end_millis: end,
+            duration_millis: start && end ? end - start : 0,
+            error_message: (failedTask && failedTask.errorMessage) || ""
+        };
+    });
+}
+
+let tmpCounter = 0;
+async function writeParquet(rows, outPath, columns) {
+    await fs__namespace.ensureDir(path__namespace.dirname(outPath));
+    const tmp = path__namespace.join(os__namespace.tmpdir(), `sa_artifact_${process.pid}_${Date.now()}_${tmpCounter++}.json`);
+    const payload = rows.length > 0 ? rows : [columns.reduce((o, c) => ((o[c] = null), o), {})];
+    const whereFalse = rows.length > 0 ? "" : " WHERE false";
+    await fs__namespace.writeFile(tmp, JSON.stringify(payload));
+    try {
+        await withDuckdb(async (conn) => {
+            await runAsync(conn, `COPY (SELECT * FROM read_json_auto('${tmp}')${whereFalse}) TO '${outPath}' (FORMAT parquet)`);
+        });
+    }
+    finally {
+        await fs__namespace.remove(tmp).catch(() => undefined);
+    }
+}
+async function queryParquet(sql, views) {
+    return withDuckdb(async (conn) => {
+        for (const view of views) {
+            await runAsync(conn, `create view ${view.name} as select * from read_parquet('${view.glob}')`);
+        }
+        return allAsync(conn, sql);
+    });
+}
+
+const TARGET_DIR = "target";
+const ACTION_COLUMNS = [
+    "target_key",
+    "database",
+    "schema",
+    "name",
+    "readable_name",
+    "type",
+    "tags",
+    "disabled",
+    "file_name",
+    "description"
+];
+const DEPENDENCY_COLUMNS = ["from_target_key", "to_target_key", "from_readable", "to_readable"];
+const COLUMN_COLUMNS = ["target_key", "readable_name", "column_name", "description"];
+const RUN_COLUMNS = [
+    "run_id",
+    "run_status",
+    "target_key",
+    "readable_name",
+    "status",
+    "start_millis",
+    "end_millis",
+    "duration_millis",
+    "error_message"
+];
+async function writeArtifacts(compiledGraph, projectDir, options = {}) {
+    const targetDir = path__namespace.join(projectDir, TARGET_DIR);
+    const catalogDir = path__namespace.join(targetDir, "catalog");
+    const { actions, dependencies, columns } = catalogRows(compiledGraph);
+    await writeParquet(actions, path__namespace.join(catalogDir, "actions.parquet"), ACTION_COLUMNS);
+    await writeParquet(dependencies, path__namespace.join(catalogDir, "dependencies.parquet"), DEPENDENCY_COLUMNS);
+    await writeParquet(columns, path__namespace.join(catalogDir, "columns.parquet"), COLUMN_COLUMNS);
+    if (options.runResult) {
+        const runId = options.runId !== undefined ? options.runId : Date.now();
+        await writeParquet(runRows(options.runResult, runId), path__namespace.join(targetDir, "runs", `run_${runId}.parquet`), RUN_COLUMNS);
+    }
+    return { targetDir };
+}
+async function safeWriteArtifacts(compiledGraph, projectDir, options = {}) {
+    try {
+        await writeArtifacts(compiledGraph, projectDir, options);
+    }
+    catch (e) {
+        if (options.warn) {
+            options.warn(`Artifacts skipped: ${e.message}`);
+        }
+    }
+}
+
+function escapeHtml(value) {
+    return String(value === null || value === undefined ? "" : value)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+async function buildDocsModel(views, generatedAt) {
+    const hasRuns = views.some(v => v.name === "runs");
+    const actions = await queryParquet("select readable_name, type, tags, description from actions order by type, readable_name", views);
+    const dependencies = await queryParquet("select from_readable, to_readable from dependencies", views);
+    const columns = await queryParquet("select readable_name, column_name, description from columns order by readable_name, column_name", views);
+    let latestRun;
+    const statusByModel = new Map();
+    if (hasRuns) {
+        const head = await queryParquet("select max(run_id) as run_id from runs", views);
+        const runId = head[0] && head[0].run_id !== null ? Number(head[0].run_id) : undefined;
+        if (runId !== undefined) {
+            const overall = await queryParquet(`select run_status from runs where run_id = ${runId} limit 1`, views);
+            latestRun = { runId, status: overall[0] ? overall[0].run_status : "UNKNOWN" };
+            const statuses = await queryParquet(`select readable_name, status from runs where run_id = ${runId}`, views);
+            for (const row of statuses) {
+                statusByModel.set(row.readable_name, row.status);
+            }
+        }
+    }
+    const dependsOn = new Map();
+    for (const dep of dependencies) {
+        dependsOn.set(dep.from_readable, (dependsOn.get(dep.from_readable) || []).concat(dep.to_readable));
+    }
+    const byTypeMap = new Map();
+    const models = actions.map(a => {
+        byTypeMap.set(a.type, (byTypeMap.get(a.type) || 0) + 1);
+        let tags = [];
+        try {
+            tags = JSON.parse(a.tags || "[]");
+        }
+        catch (e) {
+            tags = [];
+        }
+        return {
+            readable: a.readable_name,
+            type: a.type,
+            tags,
+            description: a.description || "",
+            status: statusByModel.get(a.readable_name),
+            dependsOn: dependsOn.get(a.readable_name) || []
+        };
+    });
+    return {
+        generatedAt,
+        summary: {
+            total: models.length,
+            byType: Array.from(byTypeMap.entries())
+                .map(([type, n]) => ({ type, n }))
+                .sort((x, y) => x.type.localeCompare(y.type))
+        },
+        latestRun,
+        models,
+        columns: columns.map(c => ({
+            readable: c.readable_name,
+            column: c.column_name,
+            description: c.description || ""
+        }))
+    };
+}
+function renderDocsHtml(model) {
+    const summaryLine = `${model.summary.total} models — ` +
+        model.summary.byType.map(t => `${t.n} ${t.type}`).join(", ");
+    const runLine = model.latestRun
+        ? `Last run: <strong>${escapeHtml(model.latestRun.status)}</strong> (run ${model.latestRun.runId})`
+        : "No runs recorded yet.";
+    const statusBadge = (status) => {
+        if (!status) {
+            return "";
+        }
+        const cls = status === "SUCCESSFUL" ? "ok" : status === "FAILED" ? "fail" : "muted";
+        return `<span class="badge ${cls}">${escapeHtml(status)}</span>`;
+    };
+    const modelRows = model.models
+        .map(m => `<tr data-search="${escapeHtml((m.readable + " " + m.type + " " + m.tags.join(" ")).toLowerCase())}">
+      <td><code>${escapeHtml(m.readable)}</code></td>
+      <td>${escapeHtml(m.type)}</td>
+      <td>${m.tags.map(t => `<span class="tag">${escapeHtml(t)}</span>`).join(" ")}</td>
+      <td>${statusBadge(m.status)}</td>
+      <td>${m.dependsOn.map(d => `<code>${escapeHtml(d)}</code>`).join("<br>")}</td>
+      <td>${escapeHtml(m.description)}</td>
+    </tr>`)
+        .join("\n");
+    const columnRows = model.columns
+        .map(c => `<tr><td><code>${escapeHtml(c.readable)}</code></td><td><code>${escapeHtml(c.column)}</code></td><td>${escapeHtml(c.description)}</td></tr>`)
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SQLAnvil catalog</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 -apple-system, system-ui, sans-serif; margin: 2rem; max-width: 1100px; }
+  h1 { margin: 0 0 .25rem; }
+  .meta { color: #888; margin-bottom: 1.5rem; }
+  table { border-collapse: collapse; width: 100%; margin: 1rem 0 2rem; }
+  th, td { text-align: left; padding: .4rem .6rem; border-bottom: 1px solid #8884; vertical-align: top; }
+  th { font-weight: 600; }
+  code { font-size: 12px; }
+  .tag { background: #8883; border-radius: 4px; padding: 0 .35rem; font-size: 12px; }
+  .badge { border-radius: 4px; padding: 0 .4rem; font-size: 12px; font-weight: 600; }
+  .badge.ok { background: #1a7f37; color: #fff; }
+  .badge.fail { background: #b62324; color: #fff; }
+  .badge.muted { background: #8884; }
+  #q { padding: .4rem .6rem; width: 320px; max-width: 100%; margin-bottom: .5rem; }
+</style>
+</head>
+<body>
+  <h1>SQLAnvil catalog</h1>
+  <div class="meta">${escapeHtml(summaryLine)} &middot; ${runLine} &middot; generated ${escapeHtml(model.generatedAt)}</div>
+
+  <input id="q" type="search" placeholder="Filter models…" oninput="filterModels(this.value)">
+  <table id="models">
+    <thead><tr><th>Model</th><th>Type</th><th>Tags</th><th>Last run</th><th>Depends on</th><th>Description</th></tr></thead>
+    <tbody>
+${modelRows}
+    </tbody>
+  </table>
+
+  <h2>Columns</h2>
+  <table>
+    <thead><tr><th>Model</th><th>Column</th><th>Description</th></tr></thead>
+    <tbody>
+${columnRows || '<tr><td colspan="3" class="meta">No documented columns.</td></tr>'}
+    </tbody>
+  </table>
+
+<script>
+  function filterModels(q) {
+    q = q.toLowerCase();
+    for (const tr of document.querySelectorAll('#models tbody tr')) {
+      tr.style.display = tr.getAttribute('data-search').includes(q) ? '' : 'none';
+    }
+  }
+</script>
+</body>
+</html>
+`;
+}
+
+function targetKey(target) {
+    return [target.database, target.schema, target.name].filter(Boolean).join(".");
+}
+function topoOrder(nodes) {
+    const byKey = new Map(nodes.map(n => [n.key, n]));
+    const indegree = new Map();
+    const dependents = new Map();
+    for (const n of nodes) {
+        const inGraphDeps = Array.from(new Set(n.dependencyKeys.filter(d => byKey.has(d) && d !== n.key)));
+        indegree.set(n.key, inGraphDeps.length);
+        for (const dep of inGraphDeps) {
+            dependents.set(dep, (dependents.get(dep) || []).concat(n.key));
+        }
+    }
+    const ready = nodes
+        .filter(n => (indegree.get(n.key) || 0) === 0)
+        .map(n => n.key)
+        .sort();
+    const ordered = [];
+    const emitted = new Set();
+    while (ready.length) {
+        const key = ready.shift();
+        if (emitted.has(key)) {
+            continue;
+        }
+        emitted.add(key);
+        ordered.push(byKey.get(key));
+        for (const dep of (dependents.get(key) || []).slice().sort()) {
+            indegree.set(dep, (indegree.get(dep) || 0) - 1);
+            if ((indegree.get(dep) || 0) <= 0 && !emitted.has(dep)) {
+                ready.push(dep);
+                ready.sort();
+            }
+        }
+    }
+    if (ordered.length < nodes.length) {
+        for (const n of nodes.slice().sort((a, b) => a.key.localeCompare(b.key))) {
+            if (!emitted.has(n.key)) {
+                emitted.add(n.key);
+                ordered.push(n);
+            }
+        }
+    }
+    return ordered;
+}
+function dependencyBlocked(dependencyKeys, statusByKey) {
+    return dependencyKeys.some(dep => {
+        const status = statusByKey.get(dep);
+        return status !== undefined && status !== "PASS";
+    });
+}
+const VALIDATE_SHADOW_PREFIX = "sqlanvil_validate_";
+function validateShadowSuffix(nowMs) {
+    return `${VALIDATE_SHADOW_PREFIX}${nowMs}`;
+}
+function parseShadowTimestamp(schemaName) {
+    const match = schemaName.match(/sqlanvil_validate_(\d+)/);
+    return match ? Number(match[1]) : null;
+}
+function shadowSchemasToSweep(schemaNames, nowMs, maxAgeMs) {
+    return schemaNames.filter(name => {
+        const ts = parseShadowTimestamp(name);
+        return ts !== null && nowMs - ts > maxAgeMs;
+    });
+}
+
+const SHADOW_MAX_AGE_MS = 60 * 60 * 1000;
+async function sweepOrphanShadows(deps, nowMs, maxAgeMs = SHADOW_MAX_AGE_MS) {
+    try {
+        const schemas = await deps.listSchemas();
+        for (const schema of shadowSchemasToSweep(schemas, nowMs, maxAgeMs)) {
+            try {
+                await deps.execute(deps.dropSchemaCascadeSql(schema));
+            }
+            catch (e) {
+            }
+        }
+    }
+    catch (e) {
+    }
+}
+function tableType(enumType) {
+    switch (enumType) {
+        case sqlanvil.TableType.VIEW:
+            return "view";
+        case sqlanvil.TableType.INCREMENTAL:
+            return "incremental";
+        default:
+            return "table";
+    }
+}
+function depKeys(deps) {
+    return (deps || []).map(targetKey);
+}
+async function validate(compiledGraph, deps, options = {}) {
+    const nodes = [];
+    for (const table of compiledGraph.tables || []) {
+        nodes.push({
+            key: targetKey(table.target),
+            dependencyKeys: depKeys(table.dependencyTargets),
+            kind: "table",
+            type: tableType(table.enumType),
+            target: table.target,
+            table,
+            action: table
+        });
+    }
+    for (const assertion of compiledGraph.assertions || []) {
+        nodes.push({
+            key: targetKey(assertion.target),
+            dependencyKeys: depKeys(assertion.dependencyTargets),
+            kind: "assertion",
+            type: "assertion",
+            target: assertion.target,
+            action: assertion
+        });
+    }
+    for (const operation of compiledGraph.operations || []) {
+        if (!operation.target) {
+            continue;
+        }
+        nodes.push({
+            key: targetKey(operation.target),
+            dependencyKeys: depKeys(operation.dependencyTargets),
+            kind: "operation",
+            type: "operation",
+            target: operation.target,
+            action: undefined
+        });
+    }
+    const ordered = topoOrder(nodes);
+    const shadowSchemas = Array.from(new Set(nodes.filter(n => n.kind === "table").map(n => n.target.schema)));
+    const statusByKey = new Map();
+    const results = [];
+    try {
+        for (const schema of shadowSchemas) {
+            await deps.execute(deps.createSchemaSql(schema));
+        }
+        for (const node of ordered) {
+            if (node.kind === "operation") {
+                statusByKey.set(node.key, "SKIPPED");
+                results.push({ target: node.target, type: node.type, status: "SKIPPED", errors: [] });
+                continue;
+            }
+            if (dependencyBlocked(node.dependencyKeys, statusByKey)) {
+                statusByKey.set(node.key, "BLOCKED");
+                results.push({ target: node.target, type: node.type, status: "BLOCKED", errors: [] });
+                continue;
+            }
+            const evaluations = await deps.evaluate(node.action);
+            const failed = evaluations.some(e => e.status === sqlanvil.QueryEvaluation.QueryEvaluationStatus.FAILURE);
+            const status = failed ? "FAILURE" : "PASS";
+            statusByKey.set(node.key, status);
+            results.push({ target: node.target, type: node.type, status, errors: evaluations });
+            if (status === "PASS" && node.kind === "table") {
+                try {
+                    await deps.execute(deps.validationStubSql(node.table));
+                }
+                catch (e) {
+                }
+            }
+        }
+    }
+    finally {
+        if (!options.keepShadow) {
+            for (const schema of shadowSchemas.slice().reverse()) {
+                try {
+                    await deps.execute(deps.dropSchemaCascadeSql(schema));
+                }
+                catch (e) {
+                }
+            }
+        }
+    }
+    return results;
+}
+
 function parsePostgresEvalError(_query, error) {
     return sqlanvil.QueryEvaluationError.create({
         message: (error === null || error === void 0 ? void 0 : error.message) ? String(error.message) : String(error)
@@ -47734,6 +48306,16 @@ const timeoutOption = option("timeout", {
     default: null,
     coerce: (rawTimeoutString) => rawTimeoutString ? parseDuration__default["default"](rawTimeoutString) : null
 });
+const noArtifactsOption = option("no-artifacts", {
+    describe: "Skip writing the queryable Parquet artifacts under target/ (catalog on compile; run history " +
+        "on run).",
+    type: "boolean"
+});
+const keepShadowOption = option("keep-shadow", {
+    describe: "If set, `validate` leaves its temporary shadow schema(s) in place instead of dropping them " +
+        "(debugging aid).",
+    type: "boolean"
+});
 const jobPrefixOption = option("job-prefix", {
     describe: "Adds an additional prefix in the form of `sqlanvil-${jobPrefix}-`.",
     type: "string",
@@ -47795,6 +48377,208 @@ function credentialsPathWithEnvironment(projectDir, argv) {
     const chosen = resolveCredentials(envCredentials, argv[credentialsOption.name], CREDENTIALS_FILENAME);
     return getCredentialsPath(projectDir, chosen);
 }
+function printValidationResults(results, json) {
+    const failures = results.filter(r => r.status === "FAILURE");
+    const blocked = results.filter(r => r.status === "BLOCKED");
+    const passed = results.filter(r => r.status === "PASS");
+    const skipped = results.filter(r => r.status === "SKIPPED");
+    if (json) {
+        print(prettyJsonStringify(results));
+    }
+    else {
+        for (const result of results) {
+            const label = targetAsReadableString(result.target);
+            if (result.status === "PASS") {
+                printSuccess(`  PASS   ${label}`);
+            }
+            else if (result.status === "SKIPPED") {
+                print(`  SKIP   ${label} (${result.type} — not validated)`);
+            }
+            else if (result.status === "BLOCKED") {
+                printError(`  BLOCK  ${label} — blocked by an upstream failure`);
+            }
+            else {
+                printError(`  FAIL   ${label}`);
+                result.errors
+                    .filter(e => e.status === sqlanvil.QueryEvaluation.QueryEvaluationStatus.FAILURE)
+                    .forEach(e => {
+                    var _a;
+                    const loc = ((_a = e.error) === null || _a === void 0 ? void 0 : _a.errorLocation) ? ` (line ${e.error.errorLocation.line}, col ${e.error.errorLocation.column})`
+                        : "";
+                    printError(`           ${(e.error && e.error.message) || "validation failed"}${loc}`);
+                });
+            }
+        }
+        print(`\n${passed.length} passed, ${failures.length} failed, ${blocked.length} blocked` +
+            (skipped.length ? `, ${skipped.length} skipped` : ""));
+    }
+    return failures.length > 0 || blocked.length > 0 ? 1 : 0;
+}
+async function runValidate(argv) {
+    const projectDir = argv[projectDirOption.name];
+    if (!argv[jsonOutputOption.name]) {
+        print("Compiling...\n");
+    }
+    const baseOverride = projectConfigOverrideWithEnvironment(projectDir, argv);
+    const shadowSuffix = validateShadowSuffix(Date.now());
+    const compiledGraph = await compile({
+        projectDir,
+        projectConfigOverride: Object.assign(Object.assign({}, baseOverride), { schemaSuffix: [baseOverride.schemaSuffix, shadowSuffix].filter(Boolean).join("_") }),
+        timeoutMillis: argv[timeoutOption.name] || undefined
+    });
+    if (compiledGraphHasErrors(compiledGraph)) {
+        printCompiledGraphErrors(compiledGraph.graphErrors, argv[quietCompileOption.name]);
+        return 1;
+    }
+    if (!argv[jsonOutputOption.name]) {
+        printSuccess("Compiled successfully.\n");
+    }
+    const warehouse = (compiledGraph.projectConfig.warehouse || "bigquery").toLowerCase();
+    const readCredentials = read(credentialsPathWithEnvironment(projectDir, argv), warehouse);
+    let dbadapter;
+    if (warehouse === "supabase") {
+        dbadapter = await SupabaseDbAdapter.create(readCredentials);
+    }
+    else if (warehouse === "mysql") {
+        dbadapter = await MySqlDbAdapter.create(readCredentials);
+    }
+    else if (warehouse === "bigquery") {
+        dbadapter = new BigQueryDbAdapter(readCredentials);
+    }
+    else {
+        dbadapter = await PostgresDbAdapter.create(readCredentials);
+    }
+    const prunedGraph = prune(compiledGraph, {
+        actions: argv[actionsOption.name],
+        includeDependencies: argv[includeDepsOption.name],
+        includeDependents: argv[includeDependentsOption.name],
+        tags: argv[tagsOption.name]
+    });
+    const executionSql = new ExecutionSql(compiledGraph.projectConfig, dataformVersion);
+    const shadowSchemas = Array.from(new Set((prunedGraph.tables || []).map(table => table.target.schema)));
+    process.on("SIGINT", () => {
+        Promise.all(shadowSchemas.map(schema => dbadapter.execute(executionSql.dropSchemaCascadeSql(schema)).catch(() => undefined))).then(() => process.exit(1));
+    });
+    const deps = {
+        evaluate: action => dbadapter.evaluate(action.enumType !== undefined
+            ? sqlanvil.Table.create(action)
+            : sqlanvil.Assertion.create(action)),
+        execute: sql => dbadapter.execute(sql).then(() => undefined),
+        validationStubSql: table => executionSql.validationStubSql(table),
+        createSchemaSql: schema => executionSql.createSchemaSql(schema),
+        dropSchemaCascadeSql: schema => executionSql.dropSchemaCascadeSql(schema),
+        listSchemas: async () => {
+            const result = await dbadapter.execute("select schema_name as name from information_schema.schemata");
+            return ((result && result.rows) || []).map((row) => row.name);
+        }
+    };
+    await sweepOrphanShadows(deps, Date.now());
+    if (!argv[jsonOutputOption.name]) {
+        print("Validating...\n");
+    }
+    const results = await validate(prunedGraph, deps, { keepShadow: argv[keepShadowOption.name] });
+    return printValidationResults(results, argv[jsonOutputOption.name]);
+}
+function resolveArtifactViews(projectDir) {
+    const catalogDir = path__namespace.join(projectDir, TARGET_DIR, "catalog");
+    const runsDir = path__namespace.join(projectDir, TARGET_DIR, "runs");
+    const views = [];
+    for (const name of ["actions", "dependencies", "columns"]) {
+        const file = path__namespace.join(catalogDir, `${name}.parquet`);
+        if (fs__namespace$1.existsSync(file)) {
+            views.push({ name, glob: file });
+        }
+    }
+    const hasRuns = fs__namespace$1.existsSync(runsDir) && fs__namespace$1.readdirSync(runsDir).some(f => f.endsWith(".parquet"));
+    if (hasRuns) {
+        views.push({ name: "runs", glob: path__namespace.join(runsDir, "*.parquet") });
+    }
+    return { views, hasCatalog: views.some(v => v.name === "actions"), hasRuns };
+}
+function printArtifactRows(rows) {
+    if (!rows || rows.length === 0) {
+        print("(0 rows)");
+        return;
+    }
+    const cols = Object.keys(rows[0]);
+    const widths = cols.map(c => Math.max(c.length, ...rows.map(r => String(r[c] === null || r[c] === undefined ? "" : r[c]).length)));
+    const fmtRow = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join("  ");
+    print(fmtRow(cols));
+    print(fmtRow(widths.map(w => "-".repeat(w))));
+    for (const row of rows) {
+        print(fmtRow(cols.map(c => String(row[c] === null || row[c] === undefined ? "" : row[c]))));
+    }
+    print(`\n(${rows.length} row${rows.length === 1 ? "" : "s"})`);
+}
+const NO_ARTIFACTS = "No artifacts found under target/. Run `sqlanvil compile` (or `run`) first.";
+async function runQuery(projectDir, sql, json) {
+    const { views, hasCatalog } = resolveArtifactViews(projectDir);
+    if (!hasCatalog) {
+        printError(NO_ARTIFACTS);
+        return 1;
+    }
+    const rows = await queryParquet(sql, views);
+    if (json) {
+        print(prettyJsonStringify(rows));
+    }
+    else {
+        printArtifactRows(rows);
+    }
+    return 0;
+}
+async function runInspect(projectDir, json) {
+    const { views, hasCatalog, hasRuns } = resolveArtifactViews(projectDir);
+    if (!hasCatalog) {
+        printError(NO_ARTIFACTS);
+        return 1;
+    }
+    const actionsByType = await queryParquet("select type, count(*) as n from actions group by type order by type", views);
+    let latestRun = null;
+    let failures = [];
+    if (hasRuns) {
+        const latest = await queryParquet("select run_id, run_status, " +
+            "count(*) filter (where status = 'SUCCESSFUL') as succeeded, " +
+            "count(*) filter (where status = 'FAILED') as failed, " +
+            "max(end_millis) - min(start_millis) as wall_ms " +
+            "from runs where run_id = (select max(run_id) from runs) group by run_id, run_status", views);
+        latestRun = latest[0] || null;
+        failures = await queryParquet("select readable_name, error_message from runs " +
+            "where run_id = (select max(run_id) from runs) and status = 'FAILED' limit 20", views);
+    }
+    if (json) {
+        print(prettyJsonStringify({ actionsByType, latestRun, failures }));
+        return 0;
+    }
+    print("Actions by type:");
+    printArtifactRows(actionsByType);
+    if (!hasRuns || !latestRun) {
+        print("\nNo runs recorded yet.");
+    }
+    else {
+        print(`\nLatest run (${latestRun.run_status}): ${latestRun.succeeded} succeeded, ` +
+            `${latestRun.failed} failed, ${latestRun.wall_ms}ms`);
+        if (failures.length > 0) {
+            print("\nFailures:");
+            printArtifactRows(failures);
+        }
+    }
+    return 0;
+}
+async function runDocs(projectDir) {
+    const { views, hasCatalog } = resolveArtifactViews(projectDir);
+    if (!hasCatalog) {
+        printError(NO_ARTIFACTS);
+        return 1;
+    }
+    const model = await buildDocsModel(views, new Date().toISOString());
+    const html = renderDocsHtml(model);
+    const outDir = path__namespace.join(projectDir, TARGET_DIR, "docs");
+    fs__namespace$1.mkdirSync(outDir, { recursive: true });
+    const outFile = path__namespace.join(outDir, "index.html");
+    fs__namespace$1.writeFileSync(outFile, html);
+    printSuccess(`Wrote catalog to ${outFile}`);
+    return 0;
+}
 function runCli() {
     const builtYargs = createYargsCli({
         commands: [
@@ -47925,6 +48709,7 @@ function runCli() {
                     compileTagsOption,
                     compileIncludeDepsOption,
                     compileIncludeDependentsOption,
+                    noArtifactsOption,
                     option(verboseOptionName, {
                         describe: "Enable verbose compilation output. Example usage: 'sqlanvil compile --verbose'",
                         type: "boolean",
@@ -47971,6 +48756,9 @@ function runCli() {
                             printCompiledGraphErrors(compiledGraph.graphErrors, argv[quietCompileOption.name]);
                             return true;
                         }
+                        if (!argv[noArtifactsOption.name]) {
+                            await safeWriteArtifacts(compiledGraph, projectDir, { warn: print });
+                        }
                         return false;
                     }
                     const graphHasErrors = await compileAndPrint();
@@ -48075,6 +48863,24 @@ function runCli() {
                     return testResults.every(testResult => testResult.successful) ? 0 : 1;
                 }
             },
+            {
+                format: `validate [${projectDirMustExistOption.name}]`,
+                description: "Validate the project's SQL against the warehouse planner (EXPLAIN/dry-run) without " +
+                    "executing. Postgres/Supabase/MySQL only.",
+                positionalOptions: [projectDirMustExistOption],
+                options: [
+                    actionsOption,
+                    tagsOption,
+                    includeDepsOption,
+                    includeDependentsOption,
+                    credentialsOption,
+                    jsonOutputOption,
+                    timeoutOption,
+                    keepShadowOption,
+                    ...ProjectConfigOptions.allYargsOptions
+                ],
+                processFn: async (argv) => runValidate(argv)
+            },
             {
                 format: `run [${projectDirMustExistOption.name}]`,
                 description: "Run the sqlanvil project.",
@@ -48103,6 +48909,7 @@ function runCli() {
                     timeoutOption,
                     tagsOption,
                     bigqueryJobLabelsOption,
+                    noArtifactsOption,
                     ...ProjectConfigOptions.allYargsOptions
                 ],
                 processFn: async (argv) => {
@@ -48127,6 +48934,9 @@ function runCli() {
                         printSuccess("Compiled successfully.\n");
                     }
                     const warehouse = compiledGraph.projectConfig.warehouse || "bigquery";
+                    if (argv[dryRunOptionName] && warehouse.toLowerCase() !== "bigquery") {
+                        return runValidate(argv);
+                    }
                     const readCredentials = read(credentialsPathWithEnvironment(argv[projectDirOption.name], argv), warehouse);
                     let dbadapter;
                     if (warehouse.toLowerCase() === "supabase") {
@@ -48214,9 +49024,47 @@ function runCli() {
                     runner.onChange(printExecutedGraph);
                     const runResult = await runner.result();
                     printExecutedGraph(runResult);
+                    if (!argv[noArtifactsOption.name]) {
+                        await safeWriteArtifacts(compiledGraph, argv[projectDirOption.name], {
+                            runResult,
+                            runId: Date.now(),
+                            warn: print
+                        });
+                    }
                     return runResult.status === sqlanvil.RunResult.ExecutionStatus.SUCCESSFUL ? 0 : 1;
                 }
             },
+            {
+                format: `query [sql] [${projectDirOption.name}]`,
+                description: "Run SQL over the project's queryable artifacts in target/ (views: actions, " +
+                    "dependencies, columns, runs), via the bundled DuckDB.",
+                positionalOptions: [
+                    positionalOption("sql", { describe: 'SQL to run, e.g. "select type, count(*) from actions group by 1".' }, (argv) => {
+                        if (!argv.sql) {
+                            throw new Error('Provide a SQL query, e.g. sqlanvil query "select * from actions".');
+                        }
+                    }),
+                    projectDirOption
+                ],
+                options: [jsonOutputOption],
+                processFn: async (argv) => runQuery(argv[projectDirOption.name], argv.sql, argv[jsonOutputOption.name])
+            },
+            {
+                format: `inspect [${projectDirOption.name}]`,
+                description: "Summarize the project's artifacts: action counts by type, the latest run's status/" +
+                    "timing, and recent failures.",
+                positionalOptions: [projectDirOption],
+                options: [jsonOutputOption],
+                processFn: async (argv) => runInspect(argv[projectDirOption.name], argv[jsonOutputOption.name])
+            },
+            {
+                format: `docs [${projectDirOption.name}]`,
+                description: "Generate a self-contained HTML catalog of the project (models, columns, dependencies, " +
+                    "last-run status) at target/docs/index.html, from the artifacts.",
+                positionalOptions: [projectDirOption],
+                options: [],
+                processFn: async (argv) => runDocs(argv[projectDirOption.name])
+            },
             {
                 format: `format [${projectDirMustExistOption.name}]`,
                 description: "Format the sqlanvil project's files.",

package/package.json

@@ -63,7 +63,7 @@
     "bin": {
         "sqlanvil": "bundle.js"
     },
-    "version": "1.8.3",
+    "version": "1.10.0",
     "name": "@sqlanvil/cli",
     "description": "sqlanvil command line interface.",
     "main": "bundle.js"