@sqlanvil/cli 1.21.0 → 1.22.0

package/bundle.js

@@ -50606,7 +50606,7 @@ function collectEvaluationQueries(queryOrAction, concatenate, queryModifier = (q
         .filter(validationQuery => !!validationQuery.query);
 }
 
-const version = "1.21.0";
+const version = "1.22.0";
 const dataformVersion = "3.0.61";
 
 async function build(compiledGraph, runConfig, dbadapter) {
@@ -53541,7 +53541,7 @@ class Runner {
         return actionResult;
     }
     async executeTask(client, task, parentAction, options, action) {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
         const timer = Timer.start();
         const taskResult = {
             status: sqlanvil.TaskResult.ExecutionStatus.RUNNING,
@@ -53613,7 +53613,14 @@ class Runner {
         }
         else if (task.type === "extract") {
             try {
-                const extractor = ((_d = action === null || action === void 0 ? void 0 : action.extract) === null || _d === void 0 ? void 0 : _d.platform) === "mysql"
+                if (Object.keys((_e = (_d = action === null || action === void 0 ? void 0 : action.extract) === null || _d === void 0 ? void 0 : _d.columnTypes) !== null && _e !== void 0 ? _e : {}).length === 0) {
+                    const ds = ((_f = action === null || action === void 0 ? void 0 : action.extract) === null || _f === void 0 ? void 0 : _f.platform) === "mysql"
+                        ? (_g = action === null || action === void 0 ? void 0 : action.extract) === null || _g === void 0 ? void 0 : _g.database : (_h = action === null || action === void 0 ? void 0 : action.extract) === null || _h === void 0 ? void 0 : _h.dataset;
+                    throw new Error(`declaration "${(_j = action === null || action === void 0 ? void 0 : action.target) === null || _j === void 0 ? void 0 : _j.name}" has no columnTypes — scaffold them with: ` +
+                        `sqlanvil introspect ${(_k = action === null || action === void 0 ? void 0 : action.extract) === null || _k === void 0 ? void 0 : _k.connectionName} ${ds}.${(_l = action === null || action === void 0 ? void 0 : action.extract) === null || _l === void 0 ? void 0 : _l.sourceName} ` +
+                        `--output <its .sqlx file>`);
+                }
+                const extractor = ((_m = action === null || action === void 0 ? void 0 : action.extract) === null || _m === void 0 ? void 0 : _m.platform) === "mysql"
                     ? this.executionOptions.mysqlExtract || runMysqlExtract
                     : this.executionOptions.bigQueryExtract || runBigQueryExtract;
                 await extractor({
@@ -53643,7 +53650,7 @@ class Runner {
                 }), task.type === "operation" ? 1 : options.bigquery.actionRetryLimit + 1 || 1);
                 taskResult.metadata = metadata;
                 if (task.type === "assertion") {
-                    const rowCount = (_e = rows[0]) === null || _e === void 0 ? void 0 : _e[Object.keys(rows[0])[0]];
+                    const rowCount = (_o = rows[0]) === null || _o === void 0 ? void 0 : _o[Object.keys(rows[0])[0]];
                     if (rowCount > 0) {
                         throw new Error(`Assertion failed: query returned ${rowCount} row(s).`);
                     }
@@ -53655,7 +53662,7 @@ class Runner {
                     ? sqlanvil.TaskResult.ExecutionStatus.CANCELLED
                     : sqlanvil.TaskResult.ExecutionStatus.FAILED;
                 taskResult.errorMessage = `${this.graph.projectConfig.warehouse} error: ${e.message}`;
-                if ((_g = (_f = e.metadata) === null || _f === void 0 ? void 0 : _f.bigquery) === null || _g === void 0 ? void 0 : _g.jobId) {
+                if ((_q = (_p = e.metadata) === null || _p === void 0 ? void 0 : _p.bigquery) === null || _q === void 0 ? void 0 : _q.jobId) {
                     taskResult.metadata = {
                         bigquery: {
                             jobId: e.metadata.bigquery.jobId
@@ -54175,6 +54182,596 @@ ${columnRows || '<tr><td colspan="3" class="meta">No documented columns.</td></t
 `;
 }
 
+function containsPath(parent, child) {
+    const rel = path__namespace.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path__namespace.isAbsolute(rel));
+}
+class OutWriter {
+    constructor(outDir) {
+        this.outDir = outDir;
+    }
+    write(relPath, contents) {
+        const full = path__namespace.resolve(this.outDir, relPath);
+        if (!containsPath(path__namespace.resolve(this.outDir), full)) {
+            throw new Error(`Refusing to write outside the output directory: ${relPath}`);
+        }
+        fs__namespace$1.mkdirSync(path__namespace.dirname(full), { recursive: true });
+        fs__namespace$1.writeFileSync(full, contents);
+    }
+}
+const SAFETY_SKIP = [
+    /^\.git(\/|$)/,
+    /(^|\/)node_modules(\/|$)/,
+    /(^|\/)\.df-credentials[^/]*\.json$/,
+    /service_account[^/]*\.json$/i,
+    /(^|\/)\.env([^/]*)$/,
+    /\.pem$/,
+    /(^|\/)compile_output\.json$/,
+    /(^|\/)\.DS_Store$/,
+    /(^|\/)target(\/|$)/,
+];
+function walkFiles(root) {
+    const out = [];
+    const walk = (rel) => {
+        for (const entry of fs__namespace$1.readdirSync(path__namespace.join(root, rel), { withFileTypes: true })) {
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            if (SAFETY_SKIP.some(re => re.test(relPath) || re.test(relPath + "/"))) {
+                skippedForSafety.add(relPath);
+                continue;
+            }
+            if (entry.isDirectory()) {
+                walk(relPath);
+            }
+            else if (entry.isFile()) {
+                out.push(relPath);
+            }
+        }
+    };
+    walk("");
+    return out;
+}
+let skippedForSafety;
+function findConfigBlock(source) {
+    const m = /(^|\n)\s*config\s*\{/.exec(source);
+    if (!m)
+        return null;
+    const open = source.indexOf("{", m.index + m[0].indexOf("config"));
+    let depth = 0;
+    let inString = null;
+    for (let i = open; i < source.length; i++) {
+        const ch = source[i];
+        const prev = source[i - 1];
+        if (inString) {
+            if (ch === inString && prev !== "\\")
+                inString = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            inString = ch;
+            continue;
+        }
+        if (ch === "{")
+            depth++;
+        if (ch === "}") {
+            depth--;
+            if (depth === 0) {
+                return {
+                    start: m.index + (m[1] ? m[1].length : 0),
+                    open,
+                    end: i + 1,
+                    body: source.slice(open + 1, i),
+                };
+            }
+        }
+    }
+    return null;
+}
+function jsBlockLines(source) {
+    const lines = new Set();
+    const re = /(^|\n)\s*js\s*\{/g;
+    let m;
+    while ((m = re.exec(source))) {
+        const open = source.indexOf("{", m.index + m[0].length - 1);
+        let depth = 0;
+        let end = -1;
+        for (let i = open; i < source.length; i++) {
+            if (source[i] === "{")
+                depth++;
+            if (source[i] === "}") {
+                depth--;
+                if (depth === 0) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        if (end < 0)
+            end = source.length - 1;
+        const startLine = source.slice(0, m.index + (m[1] ? m[1].length : 0)).split("\n").length - 1;
+        const endLine = source.slice(0, end).split("\n").length - 1;
+        for (let l = startLine; l <= endLine; l++)
+            lines.add(l);
+    }
+    return lines;
+}
+const str = (field, body) => {
+    const re = new RegExp(`${field}\\s*:\\s*["'\`]([^"'\`]+)["'\`]`);
+    const m = re.exec(body);
+    return m ? m[1] : null;
+};
+function parseSqlxConfig(body) {
+    let database = str("database", body);
+    if (!database && /database\s*:\s*(dataform|sqlanvil)\.projectConfig\.defaultDatabase/.test(body)) {
+        database = "<defaultDatabase>";
+    }
+    return {
+        type: str("type", body),
+        schema: str("schema", body),
+        database,
+        name: str("name", body),
+        description: str("description", body),
+    };
+}
+const GLOBAL_RULES = [
+    {
+        pattern: /\bdataform\.projectConfig\b/g,
+        replacement: "sqlanvil.projectConfig",
+        kind: "rewrite",
+        note: "dataform.projectConfig → sqlanvil.projectConfig (compile global renamed)",
+    },
+];
+const SQL_RULES = [
+    {
+        pattern: /\bSAFE_CAST\s*\(/g,
+        replacement: "CAST(",
+        kind: "rewrite",
+        note: "SAFE_CAST → CAST — Postgres CAST raises on bad input; verify the data or guard it",
+    },
+    {
+        pattern: /\bCURRENT_DATE\s*\(\s*\)/g,
+        replacement: "CURRENT_DATE",
+        kind: "rewrite",
+        note: "CURRENT_DATE() → CURRENT_DATE",
+    },
+    {
+        pattern: /\bCURRENT_DATE\s*\(\s*['"]/g,
+        kind: "flag",
+        note: "CURRENT_DATE('<tz>') — Postgres: (CURRENT_TIMESTAMP AT TIME ZONE '<tz>')::date",
+    },
+    {
+        pattern: /\bSAFE_DIVIDE\s*\(/g,
+        kind: "flag",
+        note: "SAFE_DIVIDE(a, b) — Postgres: a / NULLIF(b, 0)",
+    },
+    {
+        pattern: /\bSAFE_OFFSET\s*\(/g,
+        kind: "flag",
+        note: "array[SAFE_OFFSET(n)] — Postgres arrays are 1-based; use (split_part / arr[n+1])",
+    },
+    { pattern: /\bQUALIFY\b/gi, kind: "flag", note: "QUALIFY — rewrite as a subquery/CTE filter on the window function" },
+    { pattern: /\bUNNEST\s*\(/g, kind: "flag", note: "UNNEST — Postgres unnest() works on arrays only (no STRUCT arrays); verify semantics" },
+    { pattern: /\bSTRUCT\s*[(<]/g, kind: "flag", note: "STRUCT — no Postgres equivalent; consider jsonb or a composite type" },
+    { pattern: /\bARRAY\s*</g, kind: "flag", note: "ARRAY<T> type syntax — Postgres uses T[]" },
+    { pattern: /\bFORMAT_DATE\s*\(/g, kind: "flag", note: "FORMAT_DATE → TO_CHAR (different format tokens)" },
+    { pattern: /\bPARSE_DATE\s*\(/g, kind: "flag", note: "PARSE_DATE → TO_DATE (different format tokens)" },
+    { pattern: /\bFORMAT_TIMESTAMP\s*\(/g, kind: "flag", note: "FORMAT_TIMESTAMP → TO_CHAR (different format tokens)" },
+    {
+        pattern: /\b(DATE_ADD|DATE_SUB|TIMESTAMP_ADD|TIMESTAMP_SUB|DATETIME_ADD|DATETIME_SUB)\s*\(/g,
+        kind: "flag",
+        note: "BigQuery date arithmetic — Postgres uses interval arithmetic (x + INTERVAL '1 day')",
+    },
+    { pattern: /\bDATE_DIFF\s*\(/g, kind: "flag", note: "DATE_DIFF — Postgres: subtraction / EXTRACT(EPOCH FROM ...) depending on the part" },
+    { pattern: /_PARTITIONTIME|_PARTITIONDATE|_TABLE_SUFFIX/g, kind: "flag", note: "BigQuery pseudo-column has no Postgres equivalent" },
+    { pattern: /\bEXPORT\s+DATA\b/gi, kind: "flag", note: "EXPORT DATA — use a sqlanvil `type: \"export\"` action instead" },
+    { pattern: /\bEXECUTE\s+IMMEDIATE\b/gi, kind: "flag", note: "BigQuery scripting (EXECUTE IMMEDIATE) — rewrite as a PL/pgSQL DO block or operations" },
+    { pattern: /\bGENERATE_UUID\s*\(\s*\)/g, kind: "flag", note: "GENERATE_UUID() → gen_random_uuid()" },
+    {
+        pattern: /`[A-Za-z0-9_-]+\.[A-Za-z0-9_$]+\.[A-Za-z0-9_$]+`/g,
+        kind: "flag",
+        note: "backticked BigQuery FQN — use ${ref(...)} (declare it as a source) or a quoted Postgres name",
+    },
+];
+const CONFIG_BQ_KEYS = /^(\s*)(bigquery\s*:|partitionBy\s*:|clusterBy\s*:|requirePartitionFilter\s*:|partitionExpirationDays\s*:|database\s*:)/;
+const sanitize = (s) => s.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+const connectionNameFor = (project) => `bq_${sanitize(project)}`;
+function convertDeclaration(source, parsed, connection, sourceDataset, filePath) {
+    const span = findConfigBlock(source);
+    const description = parsed.description
+        ? `    description: ${JSON.stringify(parsed.description)},\n`
+        : "";
+    const newConfig = `config {
+    type: "declaration",
+    connection: ${JSON.stringify(connection)},
+    schema: ${JSON.stringify(sourceDataset)},
+    name: ${JSON.stringify(parsed.name)},
+${description}    columnTypes: {
+        // SQLANVIL-MIGRATE(TODO): scaffold the columns from the live source:
+        //   sqlanvil introspect ${connection} ${sourceDataset}.${parsed.name} --output ${filePath}
+    },
+}`;
+    const content = source.slice(0, span.start) + newConfig + source.slice(span.end);
+    return {
+        content,
+        findings: [
+            {
+                line: 1,
+                kind: "rewrite",
+                note: `declaration now reads BigQuery through connection "${connection}" (runner-extract); columnTypes need introspect`,
+            },
+        ],
+    };
+}
+function convertTarget(source, jsMode) {
+    const span = jsMode ? null : findConfigBlock(source);
+    const findings = [];
+    const lines = source.split("\n");
+    const jsLines = jsMode ? new Set() : jsBlockLines(source);
+    let configStartLine = -1;
+    let configEndLine = -1;
+    if (span) {
+        configStartLine = source.slice(0, span.start).split("\n").length - 1;
+        configEndLine = source.slice(0, span.end).split("\n").length - 1;
+    }
+    const out = [];
+    let commentingConfigBlockDepth = 0;
+    let swallowLeadingComma = false;
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i];
+        const inConfig = i >= configStartLine && i <= configEndLine && configStartLine >= 0;
+        const markersSafe = !jsMode && !jsLines.has(i);
+        const marker = (note) => inConfig ? `// SQLANVIL-MIGRATE: ${note}` : `-- SQLANVIL-MIGRATE: ${note}`;
+        const lineNo = i + 1;
+        const notesForLine = [];
+        for (const rule of GLOBAL_RULES) {
+            rule.pattern.lastIndex = 0;
+            if (rule.pattern.test(line)) {
+                line = line.replace(rule.pattern, rule.replacement);
+                findings.push({ line: lineNo, kind: "rewrite", note: rule.note });
+            }
+        }
+        if (swallowLeadingComma) {
+            swallowLeadingComma = false;
+            if (/^\s*,\s*$/.test(line)) {
+                out.push(`// ${line}`);
+                continue;
+            }
+            if (/^\s*,/.test(line)) {
+                line = line.replace(/,/, " ");
+            }
+        }
+        if (inConfig && commentingConfigBlockDepth === 0) {
+            const m = CONFIG_BQ_KEYS.exec(line);
+            if (m) {
+                const note = `BigQuery-only setting — not applicable on Postgres (partitioning/clustering → postgres: {}; project qualifiers drop)`;
+                findings.push({ line: lineNo, kind: "flag", note });
+                out.push(marker(note));
+                const opens = (line.match(/\{/g) || []).length;
+                const closes = (line.match(/\}/g) || []).length;
+                commentingConfigBlockDepth = Math.max(0, opens - closes);
+                if (commentingConfigBlockDepth === 0)
+                    swallowLeadingComma = !/,\s*$/.test(line) ? true : false;
+                out.push(`// ${line}`);
+                continue;
+            }
+        }
+        else if (commentingConfigBlockDepth > 0) {
+            const opens = (line.match(/\{/g) || []).length;
+            const closes = (line.match(/\}/g) || []).length;
+            commentingConfigBlockDepth = Math.max(0, commentingConfigBlockDepth + opens - closes);
+            if (commentingConfigBlockDepth === 0 && !/,\s*$/.test(line))
+                swallowLeadingComma = true;
+            out.push(`// ${line}`);
+            continue;
+        }
+        if (!inConfig || jsMode) {
+            for (const rule of SQL_RULES) {
+                rule.pattern.lastIndex = 0;
+                if (!rule.pattern.test(line))
+                    continue;
+                if (rule.replacement !== undefined) {
+                    rule.pattern.lastIndex = 0;
+                    line = line.replace(rule.pattern, rule.replacement);
+                    findings.push({ line: lineNo, kind: "rewrite", note: rule.note });
+                    if (markersSafe)
+                        notesForLine.push(rule.note);
+                }
+                else {
+                    findings.push({ line: lineNo, kind: "flag", note: rule.note });
+                    if (markersSafe)
+                        notesForLine.push(rule.note);
+                }
+            }
+        }
+        for (const note of notesForLine) {
+            out.push(marker(note));
+        }
+        out.push(line);
+    }
+    let content = out.join("\n");
+    if (jsMode && findings.length > 0) {
+        const noted = findings.slice(0, 12).map(f => ` *   L${f.line}: ${f.note}`);
+        const more = findings.length > 12 ? [` *   …and ${findings.length - 12} more (see migration-report.json)`] : [];
+        content =
+            ["/* SQLANVIL-MIGRATE — findings in this file (inline markers are unsafe in JS templates):", ...noted, ...more, " */"].join("\n") +
+                "\n" +
+                content;
+    }
+    return { content, findings };
+}
+function readSourceConfig(srcDir) {
+    var _a, _b, _c, _d, _e;
+    const wsPath = path__namespace.join(srcDir, "workflow_settings.yaml");
+    const djPath = path__namespace.join(srcDir, "dataform.json");
+    let raw;
+    if (fs__namespace$1.existsSync(wsPath)) {
+        raw = jsYaml.load(fs__namespace$1.readFileSync(wsPath, "utf8")) || {};
+    }
+    else if (fs__namespace$1.existsSync(djPath)) {
+        raw = JSON.parse(fs__namespace$1.readFileSync(djPath, "utf8"));
+    }
+    else {
+        throw new Error(`${srcDir} does not look like a Dataform project (no workflow_settings.yaml or dataform.json).`);
+    }
+    const s = (k) => (typeof raw[k] === "string" ? raw[k] : null);
+    return {
+        defaultProject: (_a = s("defaultProject")) !== null && _a !== void 0 ? _a : s("defaultDatabase"),
+        defaultDataset: (_c = (_b = s("defaultDataset")) !== null && _b !== void 0 ? _b : s("defaultSchema")) !== null && _c !== void 0 ? _c : "dataform",
+        defaultAssertionDataset: (_d = s("defaultAssertionDataset")) !== null && _d !== void 0 ? _d : s("assertionSchema"),
+        vars: (_e = raw.vars) !== null && _e !== void 0 ? _e : null,
+        raw,
+    };
+}
+async function migrateDataform(opts) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const srcDir = path__namespace.resolve(opts.srcDir);
+    const outDir = path__namespace.resolve(opts.outDir);
+    if (containsPath(srcDir, outDir)) {
+        throw new Error("The output directory must not be inside the source project.");
+    }
+    if (containsPath(outDir, srcDir)) {
+        throw new Error("The source project must not be inside the output directory.");
+    }
+    if (fs__namespace$1.existsSync(outDir) && fs__namespace$1.readdirSync(outDir).length > 0) {
+        throw new Error(`Output directory ${outDir} is not empty.`);
+    }
+    const sourceConfig = readSourceConfig(srcDir);
+    const writer = new OutWriter(outDir);
+    skippedForSafety = new Set();
+    const files = walkFiles(srcDir);
+    const report = {
+        generator: `sqlanvil migrate-dataform ${version}`,
+        sourceDir: srcDir,
+        sourceConfig: sourceConfig.raw,
+        inventory: { sqlxFiles: 0, jsFiles: 0, byType: {} },
+        connections: [],
+        overlappingSchemas: [],
+        files: [],
+        skippedForSafety: [],
+        warnings: [],
+    };
+    const sqlxFiles = [];
+    for (const rel of files) {
+        if (!rel.endsWith(".sqlx"))
+            continue;
+        const source = fs__namespace$1.readFileSync(path__namespace.join(srcDir, rel), "utf8");
+        const span = findConfigBlock(source);
+        const parsed = span
+            ? parseSqlxConfig(span.body)
+            : { type: null, schema: null, database: null, name: null, description: null };
+        sqlxFiles.push({ rel, source, parsed });
+        report.inventory.sqlxFiles++;
+        const t = (_a = parsed.type) !== null && _a !== void 0 ? _a : "(none)";
+        report.inventory.byType[t] = ((_b = report.inventory.byType[t]) !== null && _b !== void 0 ? _b : 0) + 1;
+    }
+    const resolveDatabase = (db) => { var _a; return !db || db === "<defaultDatabase>" ? (_a = sourceConfig.defaultProject) !== null && _a !== void 0 ? _a : "UNKNOWN_PROJECT" : db; };
+    const declarationSchemas = new Set();
+    const targetSchemas = new Set();
+    const connectionMap = new Map();
+    for (const f of sqlxFiles) {
+        if (f.parsed.type === "declaration") {
+            const dataset = (_c = f.parsed.schema) !== null && _c !== void 0 ? _c : sourceConfig.defaultDataset;
+            const project = resolveDatabase(f.parsed.database);
+            declarationSchemas.add(dataset);
+            const name = connectionNameFor(project);
+            const existing = connectionMap.get(name);
+            if (existing) {
+                existing.declarationCount++;
+                if (!existing.datasets.includes(dataset))
+                    existing.datasets.push(dataset);
+            }
+            else {
+                connectionMap.set(name, {
+                    name,
+                    project,
+                    datasets: [dataset],
+                    declarationCount: 1,
+                    introspectExample: `sqlanvil introspect ${name} <dataset>.<table> --output <declaration.sqlx>`,
+                });
+            }
+        }
+        else if (f.parsed.type) {
+            targetSchemas.add((_d = f.parsed.schema) !== null && _d !== void 0 ? _d : sourceConfig.defaultDataset);
+        }
+    }
+    report.connections = [...connectionMap.values()].sort((a, b) => a.name.localeCompare(b.name));
+    report.overlappingSchemas = [...declarationSchemas].filter(s => targetSchemas.has(s)).sort();
+    for (const rel of files) {
+        const abs = path__namespace.join(srcDir, rel);
+        if (rel === "workflow_settings.yaml" || rel === "dataform.json") {
+            continue;
+        }
+        if (rel.endsWith(".sqlx")) {
+            const info = sqlxFiles.find(f => f.rel === rel);
+            if (info.parsed.type === "declaration") {
+                const dataset = (_e = info.parsed.schema) !== null && _e !== void 0 ? _e : sourceConfig.defaultDataset;
+                const project = resolveDatabase(info.parsed.database);
+                const connection = connectionNameFor(project);
+                const { content, findings } = convertDeclaration(info.source, info.parsed, connection, dataset, rel);
+                writer.write(rel, content);
+                report.files.push({
+                    file: rel,
+                    action: "declaration",
+                    type: "declaration",
+                    status: "rewritten",
+                    findings,
+                    connection,
+                });
+            }
+            else {
+                const { content, findings } = convertTarget(info.source, false);
+                writer.write(rel, content);
+                report.files.push({
+                    file: rel,
+                    action: "target",
+                    type: (_f = info.parsed.type) !== null && _f !== void 0 ? _f : "(none)",
+                    status: findings.length === 0
+                        ? "clean"
+                        : findings.some(f => f.kind === "flag")
+                            ? "flagged"
+                            : "rewritten",
+                    findings,
+                });
+            }
+            continue;
+        }
+        if (rel.endsWith(".js") && (rel.startsWith("definitions/") || rel.startsWith("includes/"))) {
+            report.inventory.jsFiles++;
+            const source = fs__namespace$1.readFileSync(abs, "utf8");
+            const { content, findings } = convertTarget(source, true);
+            writer.write(rel, content);
+            const isIncludes = rel.startsWith("includes/");
+            if (isIncludes && findings.length > 0) {
+                report.warnings.push(`includes helper ${rel} emits BigQuery-flavored SQL — review its ${findings.length} finding(s)`);
+            }
+            report.files.push({
+                file: rel,
+                action: isIncludes ? "includes" : "target",
+                type: "js",
+                status: findings.length === 0
+                    ? "clean"
+                    : findings.some(f => f.kind === "flag")
+                        ? "flagged"
+                        : "rewritten",
+                findings,
+            });
+            continue;
+        }
+        writer.write(rel, fs__namespace$1.readFileSync(abs));
+        report.files.push({ file: rel, action: "copied", status: "clean", findings: [] });
+    }
+    const settings = {
+        warehouse: "supabase",
+        defaultDataset: sourceConfig.defaultDataset.toLowerCase(),
+        defaultAssertionDataset: ((_g = sourceConfig.defaultAssertionDataset) !== null && _g !== void 0 ? _g : "sqlanvil_assertions").toLowerCase(),
+        sqlanvilCoreVersion: (_h = opts.coreVersion) !== null && _h !== void 0 ? _h : version,
+    };
+    if (sourceConfig.vars)
+        settings.vars = sourceConfig.vars;
+    if (report.connections.length > 0) {
+        settings.connections = Object.fromEntries(report.connections.map(c => {
+            var _a;
+            return [
+                c.name,
+                {
+                    platform: "bigquery",
+                    project: c.project,
+                    billingProject: (_a = sourceConfig.defaultProject) !== null && _a !== void 0 ? _a : "REPLACE_WITH_YOUR_GCP_PROJECT",
+                    mode: "runner-extract",
+                },
+            ];
+        }));
+    }
+    writer.write("workflow_settings.yaml", jsYaml.dump(settings));
+    report.skippedForSafety = [...skippedForSafety].sort();
+    if (skippedForSafety.size > 0) {
+        report.warnings.push(`Skipped ${skippedForSafety.size} file(s)/dir(s) for safety (credentials, build artifacts, VCS) — see skippedForSafety`);
+    }
+    writer.write("migration-report.json", JSON.stringify(report, null, 2));
+    writer.write("migration-report.md", renderReportMd(report));
+    return report;
+}
+function renderReportMd(r) {
+    const targets = r.files.filter(f => f.action === "target");
+    const flagged = targets.filter(f => f.status === "flagged");
+    const rewritten = targets.filter(f => f.status === "rewritten");
+    const clean = targets.filter(f => f.status === "clean");
+    const declarations = r.files.filter(f => f.action === "declaration");
+    const lines = [];
+    lines.push(`# Dataform → SQLAnvil migration report`);
+    lines.push("");
+    lines.push(`Generated by ${r.generator} from \`${r.sourceDir}\` (source untouched).`);
+    lines.push("");
+    lines.push(`## Inventory`);
+    lines.push("");
+    lines.push(`- ${r.inventory.sqlxFiles} .sqlx, ${r.inventory.jsFiles} .js`);
+    for (const [t, n] of Object.entries(r.inventory.byType).sort((a, b) => b[1] - a[1])) {
+        lines.push(`  - ${t}: ${n}`);
+    }
+    lines.push("");
+    lines.push(`## Source connections (${r.connections.length})`);
+    lines.push("");
+    lines.push(`Declarations keep reading BigQuery through named \`connections:\` in workflow_settings.yaml ` +
+        `(mode: runner-extract — no Vault, no wrappers). Each declaration needs \`columnTypes\` ` +
+        `before it can extract; scaffold them with \`sqlanvil introspect\`:`);
+    lines.push("");
+    for (const c of r.connections) {
+        lines.push(`- **${c.name}** — project \`${c.project}\`, ${c.declarationCount} declaration(s) across ` +
+            `${c.datasets.length} dataset(s): ${c.datasets.slice(0, 8).map(d => `\`${d}\``).join(", ")}` +
+            (c.datasets.length > 8 ? ", …" : ""));
+        lines.push(`  - \`${c.introspectExample}\``);
+    }
+    if (r.overlappingSchemas.length > 0) {
+        lines.push("");
+        lines.push(`## ⚠ Schemas that are BOTH source and target`);
+        lines.push("");
+        lines.push(`These schemas have declarations AND materializing actions: ${r.overlappingSchemas
+            .map(s => `\`${s}\``)
+            .join(", ")}. ` +
+            `Their declared tables are probably produced by this pipeline (or a sibling) — once those ` +
+            `producers move to Postgres, convert the declarations to plain local declarations instead ` +
+            `of BigQuery connections.`);
+    }
+    lines.push("");
+    lines.push(`## Target files (${targets.length})`);
+    lines.push("");
+    lines.push(`- clean: ${clean.length}`);
+    lines.push(`- rewritten (safe lexical changes only): ${rewritten.length}`);
+    lines.push(`- **flagged (need dialect review): ${flagged.length}** — every location is marked ` +
+        `inline with \`SQLANVIL-MIGRATE:\``);
+    lines.push("");
+    for (const f of flagged) {
+        lines.push(`- \`${f.file}\` (${f.type})`);
+        for (const finding of f.findings.filter(x => x.kind === "flag").slice(0, 6)) {
+            lines.push(`  - L${finding.line}: ${finding.note}`);
+        }
+        const more = f.findings.filter(x => x.kind === "flag").length - 6;
+        if (more > 0)
+            lines.push(`  - …and ${more} more (see migration-report.json)`);
+    }
+    lines.push("");
+    lines.push(`## Declarations (${declarations.length})`);
+    lines.push("");
+    lines.push(`Every declaration was rewritten to ride its connection. The BigQuery data does not move.`);
+    if (r.warnings.length > 0) {
+        lines.push("");
+        lines.push(`## Warnings`);
+        lines.push("");
+        for (const w of r.warnings)
+            lines.push(`- ${w}`);
+    }
+    lines.push("");
+    lines.push(`## Finish the migration`);
+    lines.push("");
+    lines.push(`1. \`sqlanvil compile\` — should already succeed.`);
+    lines.push(`2. Scaffold \`columnTypes\` for the declarations you actually read (see connections above).`);
+    lines.push(`3. \`sqlanvil validate\` against your Postgres/Supabase warehouse — PASS/FAILURE/BLOCKED per ` +
+        `model is the migration to-do list. Work the flagged files until validate is green.`);
+    lines.push(`4. This report is machine-readable (migration-report.json) — pointing an AI agent at it plus ` +
+        `the \`SQLANVIL-MIGRATE:\` markers is the fastest path through the dialect work.`);
+    lines.push("");
+    return lines.join("\n");
+}
+
 const CHECKER_SOURCE = `
 import json, os, sys
 
@@ -56843,6 +57440,37 @@ function runCli() {
                     }
                     return 0;
                 }
+            },
+            {
+                format: "migrate-dataform <source-dir> <out-dir>",
+                description: "Convert a Dataform/BigQuery project into a sqlanvil-on-Postgres project. The source " +
+                    "directory is READ-ONLY; the converted project + migration-report.{md,json} land in " +
+                    "<out-dir> (must be empty). Sources stay in BigQuery as named connections; target SQL " +
+                    "gets safe rewrites + inline SQLANVIL-MIGRATE markers for dialect review.",
+                positionalOptions: [
+                    positionalOption("source-dir", {
+                        describe: "The Dataform project to convert (never modified)."
+                    }),
+                    positionalOption("out-dir", {
+                        describe: "Where the converted sqlanvil project is written (created; must be empty)."
+                    })
+                ],
+                options: [],
+                processFn: async (argv) => {
+                    const report = await migrateDataform({
+                        srcDir: argv["source-dir"],
+                        outDir: argv["out-dir"]
+                    });
+                    const targets = report.files.filter(f => f.action === "target");
+                    const flagged = targets.filter(f => f.status === "flagged").length;
+                    printSuccess(`Converted ${report.inventory.sqlxFiles} .sqlx file(s): ` +
+                        `${report.connections.length} source connection(s) over ` +
+                        `${report.files.filter(f => f.action === "declaration").length} declaration(s); ` +
+                        `${targets.length} target file(s), ${flagged} flagged for dialect review.`);
+                    print(`Report: ${path__namespace.join(argv["out-dir"], "migration-report.md")}`);
+                    print(`Next: sqlanvil compile ${argv["out-dir"]}`);
+                    return 0;
+                }
             }
         ]
     })

package/package.json

@@ -64,7 +64,7 @@
     "bin": {
         "sqlanvil": "bundle.js"
     },
-    "version": "1.21.0",
+    "version": "1.22.0",
     "name": "@sqlanvil/cli",
     "description": "sqlanvil command line interface.",
     "main": "bundle.js"