@duckcodeailabs/dql-cli 1.6.18 → 1.6.20

package/dist/block-studio-import.js

@@ -142,11 +142,55 @@ export function updateBlockStudioImportCandidate(projectRoot, importId, candidat
         next.owner = patch.owner;
     if (patch.tags !== undefined)
         next.tags = normalizeTags(patch.tags);
+    if (patch.terms !== undefined)
+        next.terms = normalizeStringList(patch.terms);
+    if (patch.pattern !== undefined)
+        next.pattern = normalizePattern(patch.pattern);
+    if (patch.grain !== undefined)
+        next.grain = patch.grain;
+    if (patch.entities !== undefined)
+        next.entities = normalizeStringList(patch.entities);
+    if (patch.outputs !== undefined)
+        next.outputs = normalizeStringList(patch.outputs);
+    if (patch.dimensions !== undefined)
+        next.dimensions = normalizeStringList(patch.dimensions);
+    if (patch.allowedFilters !== undefined)
+        next.allowedFilters = normalizeStringList(patch.allowedFilters);
+    if (patch.parameterPolicy !== undefined)
+        next.parameterPolicy = normalizeParameterPolicy(patch.parameterPolicy);
+    if (patch.filterBindings !== undefined)
+        next.filterBindings = normalizeFilterBindings(patch.filterBindings);
+    if (patch.sourceSystems !== undefined)
+        next.sourceSystems = normalizeStringList(patch.sourceSystems);
+    if (patch.replacementFor !== undefined)
+        next.replacementFor = normalizeStringList(patch.replacementFor);
+    if (patch.reviewCadence !== undefined)
+        next.reviewCadence = normalizeReviewCadence(patch.reviewCadence) || 'monthly';
+    if (patch.parameterDecisions !== undefined)
+        next.parameterDecisions = patch.parameterDecisions;
+    if (patch.similarityMatches !== undefined)
+        next.similarityMatches = patch.similarityMatches;
+    if (patch.recommendedAction !== undefined)
+        next.recommendedAction = patch.recommendedAction;
     if (patch.sql !== undefined)
         next.sql = patch.sql;
     if (patch.reviewStatus !== undefined)
         next.reviewStatus = patch.reviewStatus;
-    if (patch.name || patch.domain || patch.description || patch.owner || patch.tags || patch.sql) {
+    if (patch.llmContext !== undefined)
+        next.llmContext = patch.llmContext;
+    if (patch.evidence !== undefined)
+        next.evidence = patch.evidence;
+    if (patch.draftSave !== undefined)
+        next.draftSave = patch.draftSave;
+    if (patch.generationMode !== undefined)
+        next.generationMode = patch.generationMode;
+    if (patch.generationProvider !== undefined)
+        next.generationProvider = patch.generationProvider;
+    if (patch.savedPath !== undefined)
+        next.savedPath = patch.savedPath;
+    if (patch.conversionNotes !== undefined)
+        next.conversionNotes = patch.conversionNotes;
+    if (patch.name || patch.domain || patch.description || patch.owner || patch.tags || patch.terms || patch.pattern || patch.grain || patch.entities || patch.outputs || patch.dimensions || patch.allowedFilters || patch.parameterPolicy || patch.filterBindings || patch.sourceSystems || patch.replacementFor || patch.reviewCadence || patch.parameterDecisions || patch.sql || patch.llmContext) {
         next.dqlSource = candidateToDqlSource(next);
         next.lineage = {
             ...next.lineage,
@@ -162,28 +206,561 @@ export function updateBlockStudioImportCandidate(projectRoot, importId, candidat
 }
 export function candidateToDqlSource(candidate) {
     const tags = normalizeTags(candidate.tags).map((tag) => dqlString(tag)).join(', ');
+    const terms = normalizeStringList(candidate.terms ?? []).slice(0, 16);
     const sql = candidate.sql.trim().replace(/"""/g, '\\"\\"\\"');
-    return `block ${dqlString(candidate.name)} {
-    status = "draft"
-    domain = ${dqlString(sanitizeDomain(candidate.domain))}
-    type = "custom"
-    description = ${dqlString(candidate.description)}
-    tags = [${tags}]
-    owner = ${dqlString(candidate.owner)}
-
-    query = """
-${sql}
-    """
-
-    visualization {
-        chart = "table"
-    }
-
-    tests {
-        assert row_count > 0
-    }
-}
-`;
+    const llmContext = candidate.llmContext?.trim();
+    const pattern = normalizePattern(candidate.pattern || inferSqlPattern(candidate.sql));
+    const grain = candidate.grain?.trim() || inferSqlGrain(candidate.sql);
+    const outputs = normalizeStringList(candidate.outputs?.length ? candidate.outputs : inferSqlOutputs(candidate.sql)).slice(0, 24);
+    const dimensions = normalizeStringList(candidate.dimensions?.length ? candidate.dimensions : inferSqlDimensions(candidate.sql, grain, outputs)).slice(0, 16);
+    const sourceSystems = normalizeStringList(candidate.sourceSystems?.length ? candidate.sourceSystems : inferSqlSourceSystems(candidate.sql)).slice(0, 12);
+    const entities = normalizeStringList(candidate.entities?.length ? candidate.entities : inferSqlEntities(grain, sourceSystems)).slice(0, 12);
+    const allowedFilters = normalizeStringList(candidate.allowedFilters?.length ? candidate.allowedFilters : inferSqlFilters(candidate.sql)).slice(0, 16);
+    const parameterDecisions = normalizeParameterDecisions(candidate.parameterDecisions ?? []);
+    const parameterPolicy = normalizeParameterPolicy(candidate.parameterPolicy?.length
+        ? candidate.parameterPolicy
+        : parameterDecisions.map((decision) => ({ name: decision.name, policy: decision.policy })));
+    const filterBindings = normalizeFilterBindings(candidate.filterBindings ?? []);
+    const reviewCadence = normalizeReviewCadence(candidate.reviewCadence || 'monthly');
+    const params = parameterDecisions.filter((decision) => decision.policy !== 'static');
+    const lines = [
+        `block ${dqlString(candidate.name)} {`,
+        '    status = "draft"',
+        `    domain = ${dqlString(sanitizeDomain(candidate.domain))}`,
+        '    type = "custom"',
+        `    description = ${dqlString(candidate.description)}`,
+        `    tags = [${tags}]`,
+        `    owner = ${dqlString(candidate.owner)}`,
+    ];
+    if (pattern)
+        lines.push(`    pattern = ${dqlString(pattern)}`);
+    if (grain)
+        lines.push(`    grain = ${dqlString(grain)}`);
+    if (entities.length > 0)
+        lines.push(`    entities = [${entities.map(dqlString).join(', ')}]`);
+    if (outputs.length > 0)
+        lines.push(`    outputs = [${outputs.map(dqlString).join(', ')}]`);
+    if (terms.length > 0)
+        lines.push(`    terms = [${terms.map(dqlString).join(', ')}]`);
+    if (dimensions.length > 0)
+        lines.push(`    dimensions = [${dimensions.map(dqlString).join(', ')}]`);
+    if (allowedFilters.length > 0)
+        lines.push(`    allowedFilters = [${allowedFilters.map(dqlString).join(', ')}]`);
+    if (parameterPolicy.length > 0) {
+        lines.push('    parameterPolicy {');
+        lines.push(...parameterPolicy.map((entry) => `        ${entry.name} = ${dqlString(entry.policy)}`));
+        lines.push('    }');
+    }
+    if (filterBindings.length > 0) {
+        lines.push('    filterBindings {');
+        lines.push(...filterBindings.map((entry) => `        ${entry.filter} = ${dqlString(entry.binding)}`));
+        lines.push('    }');
+    }
+    if (sourceSystems.length > 0)
+        lines.push(`    sourceSystems = [${sourceSystems.map(dqlString).join(', ')}]`);
+    if (candidate.replacementFor?.length)
+        lines.push(`    replacementFor = [${candidate.replacementFor.map(dqlString).join(', ')}]`);
+    if (reviewCadence)
+        lines.push(`    reviewCadence = ${dqlString(reviewCadence)}`);
+    if (llmContext)
+        lines.push(`    llmContext = ${dqlString(llmContext)}`);
+    if (params.length > 0) {
+        lines.push('', '    params {');
+        lines.push(...params.map((param) => `        ${param.name} = ${formatDqlLiteral(param.value)}`));
+        lines.push('    }');
+    }
+    lines.push('', '    query = """', sql, '    """');
+    lines.push('', '    visualization {', '        chart = "table"', '    }');
+    lines.push('', '    tests {', '        assert row_count > 0', '    }', '}');
+    return `${lines.join('\n')}\n`;
+}
+function normalizeParameterPolicy(value) {
+    const seen = new Set();
+    const result = [];
+    for (const item of value) {
+        const name = normalizeIdentifier(item.name);
+        const policy = String(item.policy ?? '').trim().toLowerCase().replace(/[^a-z0-9_]+/g, '_');
+        if (!name || !policy || seen.has(name))
+            continue;
+        seen.add(name);
+        result.push({ name, policy });
+    }
+    return result.slice(0, 24);
+}
+function normalizeFilterBindings(value) {
+    const seen = new Set();
+    const result = [];
+    for (const item of value) {
+        const filter = normalizeIdentifier(item.filter);
+        const binding = String(item.binding ?? '').trim();
+        if (!filter || !binding || seen.has(filter))
+            continue;
+        seen.add(filter);
+        result.push({ filter, binding });
+    }
+    return result.slice(0, 24);
+}
+function normalizeReviewCadence(value) {
+    const normalized = String(value ?? '').trim().toLowerCase().replace(/[^a-z0-9_ -]+/g, '').replace(/\s+/g, '_');
+    const allowed = new Set(['daily', 'weekly', 'biweekly', 'monthly', 'quarterly', 'semiannual', 'annual']);
+    return allowed.has(normalized) ? normalized : '';
+}
+function normalizeParameterDecisions(value) {
+    const seen = new Set();
+    const result = [];
+    for (const item of value) {
+        const name = normalizeIdentifier(item.name);
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        result.push({
+            ...item,
+            name,
+            policy: normalizeParameterPolicyKind(item.policy),
+            reason: item.reason || 'Detected from imported SQL literal.',
+            confidence: Math.max(0, Math.min(1, Number(item.confidence) || 0.5)),
+        });
+    }
+    return result.slice(0, 24);
+}
+function normalizeParameterPolicyKind(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'dynamic'
+        || normalized === 'static'
+        || normalized === 'business'
+        || normalized === 'derived'
+        || normalized === 'optional'
+        || normalized === 'ambiguous_review_required')
+        return normalized;
+    return 'ambiguous_review_required';
+}
+function normalizeIdentifier(value) {
+    return String(value || '').trim().replace(/[^A-Za-z0-9_]+/g, '_').replace(/^_+|_+$/g, '').replace(/^([0-9])/, '_$1');
+}
+function formatDqlLiteral(value) {
+    if (Array.isArray(value))
+        return `[${value.map(formatDqlLiteral).join(', ')}]`;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    return dqlString(String(value));
+}
+export function parameterizeSqlForDqlImport(sql) {
+    let nextSql = sql;
+    const decisions = new Map();
+    const bindings = new Map();
+    const warnings = [];
+    const addDecision = (decision) => {
+        const name = normalizeIdentifier(decision.name);
+        if (!name || decisions.has(name))
+            return name;
+        decisions.set(name, { ...decision, name });
+        return name;
+    };
+    const addBinding = (filter, binding) => {
+        const normalized = normalizeIdentifier(filter);
+        if (!normalized || bindings.has(normalized))
+            return;
+        bindings.set(normalized, { filter: normalized, binding: binding.trim() });
+    };
+    const availableParamName = (preferred, fallback) => {
+        const normalized = normalizeIdentifier(preferred);
+        return normalized && !decisions.has(normalized) ? normalized : normalizeIdentifier(fallback);
+    };
+    const availableFilterName = (preferred, fallback) => {
+        const normalized = normalizeIdentifier(preferred);
+        return normalized && !bindings.has(normalized) ? normalized : normalizeIdentifier(fallback);
+    };
+    const placeholder = (name) => '${' + name + '}';
+    const yearLiterals = extractYearLiterals(nextSql);
+    const yearParamName = (year) => {
+        if (yearLiterals.length <= 1)
+            return 'season_year';
+        if (year === yearLiterals[0])
+            return 'season_start';
+        if (year === yearLiterals[yearLiterals.length - 1])
+            return 'season_end';
+        return `season_year_${year}`;
+    };
+    if (yearLiterals.length > 0) {
+        nextSql = nextSql.replace(/(extract\s*\(\s*year\s+from\s+([^)]+?)\s*\)\s*(?:>=|<=|<>|!=|=|>|<)\s*)([12][0-9]{3})/gi, (match, prefix, column, yearValue) => {
+            if (match.includes('${'))
+                return match;
+            const year = Number(yearValue);
+            const name = addDecision({
+                name: yearParamName(year),
+                policy: 'dynamic',
+                value: year,
+                valueType: 'year',
+                sourceExpression: `EXTRACT(YEAR FROM ${column.trim()})`,
+                reason: 'Year literal is user scope and should be reusable across seasons.',
+                confidence: 0.94,
+            });
+            addBinding(yearLiterals.length > 1 ? 'season_range' : 'season', `${column.trim()}.year`);
+            return `${prefix}${placeholder(name)}`;
+        });
+        nextSql = nextSql.replace(/(extract\s*\(\s*year\s+from\s+([^)]+?)\s*\)\s+in\s*\()([^)]+)(\))/gi, (match, prefix, column, list, suffix) => {
+            if (match.includes('${'))
+                return match;
+            const listYears = extractYearValuesFromList(list);
+            const normalizedColumn = column.trim();
+            if (listYears.length === 1) {
+                const name = addDecision({
+                    name: 'season_year',
+                    policy: 'dynamic',
+                    value: listYears[0],
+                    valueType: 'year',
+                    sourceExpression: `EXTRACT(YEAR FROM ${normalizedColumn})`,
+                    reason: 'Single-year list literal is user scope and should be reusable across seasons.',
+                    confidence: 0.94,
+                });
+                addBinding('season', `${normalizedColumn}.year`);
+                return `EXTRACT(YEAR FROM ${normalizedColumn}) = ${placeholder(name)}`;
+            }
+            if (listYears.length > 1 && isContiguousYearRange(listYears)) {
+                const firstYear = listYears[0];
+                const lastYear = listYears[listYears.length - 1];
+                const startName = addDecision({
+                    name: 'season_start',
+                    policy: 'dynamic',
+                    value: firstYear,
+                    valueType: 'year',
+                    sourceExpression: `EXTRACT(YEAR FROM ${normalizedColumn})`,
+                    reason: 'Contiguous year list is treated as a reusable season range.',
+                    confidence: 0.95,
+                });
+                const endName = addDecision({
+                    name: 'season_end',
+                    policy: 'dynamic',
+                    value: lastYear,
+                    valueType: 'year',
+                    sourceExpression: `EXTRACT(YEAR FROM ${normalizedColumn})`,
+                    reason: 'Contiguous year list is treated as a reusable season range.',
+                    confidence: 0.95,
+                });
+                addBinding('season_range', `${normalizedColumn}.year`);
+                return `EXTRACT(YEAR FROM ${normalizedColumn}) BETWEEN ${placeholder(startName)} AND ${placeholder(endName)}`;
+            }
+            const replaced = list.replace(/\b([12][0-9]{3})\b/g, (_yearMatch, yearValue) => {
+                const year = Number(yearValue);
+                const name = addDecision({
+                    name: `season_year_${year}`,
+                    policy: 'dynamic',
+                    value: year,
+                    valueType: 'year',
+                    sourceExpression: `EXTRACT(YEAR FROM ${normalizedColumn})`,
+                    reason: 'Non-contiguous year list is user scope and should remain an explicit selected set.',
+                    confidence: 0.94,
+                });
+                return placeholder(name);
+            });
+            addBinding('season_set', `${normalizedColumn}.year`);
+            return `${prefix}${replaced}${suffix}`;
+        });
+    }
+    nextSql = nextSql.replace(/\blimit\s+([0-9]+)\b/gi, (match, value) => {
+        if (match.includes('${'))
+            return match;
+        const topN = Number(value);
+        if (!Number.isFinite(topN) || topN <= 0 || topN > 10000)
+            return match;
+        const name = addDecision({
+            name: 'top_n',
+            policy: 'dynamic',
+            value: topN,
+            valueType: 'number',
+            sourceExpression: 'LIMIT',
+            reason: 'Top/bottom row count is presentation scope and should be reusable.',
+            confidence: 0.9,
+        });
+        return match.replace(value, placeholder(name));
+    });
+    nextSql = nextSql.replace(/\b([A-Za-z_][A-Za-z0-9_.]*)\s+between\s+(?:date\s+)?'([12][0-9]{3}-[01][0-9]-[0-3][0-9])'\s+and\s+(?:date\s+)?'([12][0-9]{3}-[01][0-9]-[0-3][0-9])'/gi, (match, column, startValue, endValue) => {
+        if (match.includes('${') || !isDateScopeColumn(column))
+            return match;
+        const columnName = lastIdentifierPart(column);
+        const startName = addDecision({
+            name: availableParamName('start_date', `${columnName}_start_date`),
+            policy: 'dynamic',
+            value: startValue,
+            valueType: 'date',
+            sourceExpression: column,
+            reason: 'Date range literal is runtime scope and should be controlled by app filters.',
+            confidence: 0.9,
+        });
+        const endName = addDecision({
+            name: availableParamName('end_date', `${columnName}_end_date`),
+            policy: 'dynamic',
+            value: endValue,
+            valueType: 'date',
+            sourceExpression: column,
+            reason: 'Date range literal is runtime scope and should be controlled by app filters.',
+            confidence: 0.9,
+        });
+        addBinding(availableFilterName('date_range', `${columnName}_range`), column);
+        return `${column} BETWEEN ${placeholder(startName)} AND ${placeholder(endName)}`;
+    });
+    nextSql = nextSql.replace(/\b([A-Za-z_][A-Za-z0-9_.]*)\s*(>=|<=|=|>|<)\s*'([12][0-9]{3}-[01][0-9]-[0-3][0-9])'/gi, (match, column, operator, value) => {
+        if (match.includes('${') || !isDateScopeColumn(column))
+            return match;
+        const name = operator === '>=' || operator === '>' ? 'start_date' : operator === '<=' || operator === '<' ? 'end_date' : `${lastIdentifierPart(column)}_date`;
+        const paramName = addDecision({
+            name,
+            policy: 'dynamic',
+            value,
+            valueType: 'date',
+            sourceExpression: column,
+            reason: 'Date literal is runtime scope and should be controlled by app filters.',
+            confidence: 0.88,
+        });
+        addBinding(name === 'start_date' || name === 'end_date' ? 'date_range' : name, column);
+        return `${column} ${operator} ${placeholder(paramName)}`;
+    });
+    nextSql = nextSql.replace(/\b([A-Za-z_][A-Za-z0-9_.]*)\s+in\s*\(([^)]*)\)/gi, (match, column, rawList) => {
+        if (match.includes('${') || /\bextract\s*\(/i.test(match))
+            return match;
+        const columnName = lastIdentifierPart(column);
+        if (!isRuntimeScopeColumn(columnName))
+            return match;
+        const values = parseSqlLiteralList(rawList);
+        if (!values || values.length === 0)
+            return match;
+        const name = addDecision({
+            name: `${columnName}_set`,
+            policy: 'dynamic',
+            value: values,
+            valueType: 'set',
+            sourceExpression: column,
+            reason: 'Selected-set literal is user scope and should stay reusable for one or many values.',
+            confidence: 0.86,
+        });
+        addBinding(`${columnName}_set`, column);
+        return `${column} IN (${placeholder(name)})`;
+    });
+    nextSql = nextSql.replace(/\b([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*('(?:''|[^'])*'|[0-9]+(?:\.[0-9]+)?)/gi, (match, column, rawValue) => {
+        if (match.includes('${') || /extract\s*\(/i.test(match))
+            return match;
+        const columnName = lastIdentifierPart(column);
+        if (!isRuntimeScopeColumn(columnName)) {
+            const literal = parseSqlLiteral(rawValue);
+            if (isBusinessRuleLiteral(columnName, literal)) {
+                const name = addDecision({
+                    name: `${columnName}_rule`,
+                    policy: 'static',
+                    value: literal,
+                    valueType: typeof literal === 'number' ? 'number' : 'string',
+                    sourceExpression: column,
+                    reason: 'Literal appears to define a fixed business rule, not runtime scope.',
+                    confidence: 0.72,
+                });
+                warnings.push(`Kept ${columnName} as static business logic (${name}).`);
+            }
+            return match;
+        }
+        const literal = parseSqlLiteral(rawValue);
+        const name = addDecision({
+            name: columnName,
+            policy: 'dynamic',
+            value: literal,
+            valueType: typeof literal === 'number' ? 'number' : 'string',
+            sourceExpression: column,
+            reason: 'Filter literal is user scope and should be reusable.',
+            confidence: 0.82,
+        });
+        addBinding(columnName, column);
+        return `${column} = ${placeholder(name)}`;
+    });
+    const parameterDecisions = Array.from(decisions.values());
+    const parameterPolicy = parameterDecisions.map((decision) => ({ name: decision.name, policy: decision.policy }));
+    const filterBindings = Array.from(bindings.values());
+    const allowedFilters = Array.from(new Set([
+        ...filterBindings.map((binding) => binding.filter),
+        ...parameterDecisions.filter((decision) => decision.policy === 'dynamic').map((decision) => decision.name),
+    ])).slice(0, 16);
+    return { sql: nextSql, parameterDecisions, parameterPolicy, filterBindings, allowedFilters, warnings };
+}
+function extractYearLiterals(sql) {
+    const years = new Set();
+    const cleaned = stripSqlComments(sql);
+    const extractRegex = /extract\s*\(\s*year\s+from\s+[^)]+\)\s*(?:(?:>=|<=|<>|!=|=|>|<)\s*([12][0-9]{3})|\s+in\s*\(([^)]*)\))/gi;
+    let match;
+    while ((match = extractRegex.exec(cleaned))) {
+        for (const value of [match[1], ...(match[2]?.match(/[12][0-9]{3}/g) ?? [])]) {
+            if (value)
+                years.add(Number(value));
+        }
+    }
+    return Array.from(years).sort((a, b) => a - b);
+}
+function extractYearValuesFromList(list) {
+    const years = new Set();
+    for (const value of list.match(/\b[12][0-9]{3}\b/g) ?? []) {
+        years.add(Number(value));
+    }
+    return Array.from(years).sort((a, b) => a - b);
+}
+function isContiguousYearRange(years) {
+    if (years.length < 2)
+        return false;
+    for (let index = 1; index < years.length; index += 1) {
+        if (years[index] !== years[index - 1] + 1)
+            return false;
+    }
+    return true;
+}
+function lastIdentifierPart(column) {
+    return normalizeIdentifier(column.split('.').pop() ?? column).toLowerCase();
+}
+function stripSqlIdentifierQuotes(value) {
+    return value.replace(/["\[\]]/g, '').replaceAll('`', '');
+}
+function parseSqlLiteral(raw) {
+    if (/^'/.test(raw))
+        return raw.slice(1, -1).replace(/''/g, "'");
+    const numeric = Number(raw);
+    return Number.isFinite(numeric) ? numeric : raw;
+}
+function parseSqlLiteralList(rawList) {
+    const parts = splitSqlList(rawList).map((part) => part.trim()).filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    const values = [];
+    for (const part of parts) {
+        if (!/^(?:'(?:''|[^'])*'|[0-9]+(?:\.[0-9]+)?)$/i.test(part))
+            return null;
+        values.push(parseSqlLiteral(part));
+    }
+    return values;
+}
+function isDateScopeColumn(column) {
+    return /(date|day|time|period|month|week)/i.test(column);
+}
+function isRuntimeScopeColumn(column) {
+    const normalized = normalizeIdentifier(column).toLowerCase();
+    return /(?:^|_)(player|team|customer|account|user|segment|region|product|position|market|channel|country|state|city|league|season|year)(?:_|$)/i.test(normalized)
+        || /(?:^|_)(id|key|name|code)$/i.test(normalized);
+}
+function isBusinessRuleLiteral(column, value) {
+    const text = String(value).toLowerCase();
+    return /(status|state|type|flag|is_|mode|category)/i.test(column)
+        && /^(active|approved|complete|completed|valid|regular|true|1|yes|current)$/i.test(text);
+}
+function inferSqlGrain(sql) {
+    const groupFields = extractGroupByFields(sql);
+    return groupFields[0] ?? '';
+}
+function inferSqlPattern(sql) {
+    const lower = stripSqlComments(sql).toLowerCase();
+    const groupFields = extractGroupByFields(sql);
+    if (/@metric\s*\(/i.test(sql))
+        return 'metric_wrapper';
+    if (/\bjoin\b/i.test(sql)) {
+        const systems = new Set(inferSqlSourceSystems(sql));
+        if (systems.size > 1)
+            return 'bridge';
+    }
+    if (hasRankingLimit(sql))
+        return 'ranking';
+    if (groupFields.some((field) => /\b(date|day|week|month|quarter|year|period|time)\b/i.test(field)))
+        return 'trend';
+    if (groupFields.length === 1 && /_id$|_key$/i.test(groupFields[0]))
+        return 'entity_rollup';
+    if (!/\b(sum|count|avg|min|max|median|percentile|rank)\s*\(/i.test(lower) && /\b(dim|profile|customer|account|player|product|user|entity)\b/i.test(lower)) {
+        return 'entity_profile';
+    }
+    return 'custom';
+}
+function hasRankingLimit(sql) {
+    return /\border\s+by\b[\s\S]*\blimit\s+(?:\d+|\$\{\s*[A-Za-z_][A-Za-z0-9_]*\s*\}|[:?][A-Za-z_][A-Za-z0-9_]*)/i.test(sql);
+}
+function inferSqlOutputs(sql) {
+    const selectMatch = sql.match(/\bselect\b([\s\S]+?)\bfrom\b/i);
+    if (!selectMatch)
+        return [];
+    return splitSqlList(selectMatch[1])
+        .map((expr) => {
+        const alias = expr.match(/\bas\s+([A-Za-z_][A-Za-z0-9_]*)\b/i)?.[1]
+            ?? expr.match(/([A-Za-z_][A-Za-z0-9_]*)\s*$/)?.[1]
+            ?? '';
+        return stripSqlIdentifierQuotes(alias);
+    })
+        .filter(Boolean)
+        .filter((name) => !/^(from|where|group|order|limit)$/i.test(name));
+}
+function inferSqlFilters(sql) {
+    const filters = new Set();
+    const where = sql.match(/\bwhere\b([\s\S]+?)(?:\bgroup\s+by\b|\border\s+by\b|\blimit\b|$)/i)?.[1] ?? '';
+    const addFilter = (value) => {
+        const name = stripSqlIdentifierQuotes(value?.split('.').pop() ?? '');
+        if (name && !/^(and|or|not|null|year|month|day)$/i.test(name))
+            filters.add(name);
+    };
+    const extractRegex = /\bextract\s*\([^)]*\bfrom\s+([A-Za-z_][A-Za-z0-9_.]*)\s*\)\s*(?:=|<>|!=|>|<|>=|<=|\bin\b|\blike\b)/gi;
+    const isNullRegex = /\b([A-Za-z_][A-Za-z0-9_.]*)\s+is\s+(?:not\s+)?null\b/gi;
+    const regex = /\b([A-Za-z_][A-Za-z0-9_.]*)\s*(?:=|<>|!=|>|<|>=|<=|\bin\b|\blike\b)/gi;
+    let match;
+    while ((match = extractRegex.exec(where)))
+        addFilter(match[1]);
+    while ((match = isNullRegex.exec(where)))
+        addFilter(match[1]);
+    while ((match = regex.exec(where))) {
+        addFilter(match[1]);
+    }
+    return [...filters];
+}
+function inferSqlSourceSystems(sql) {
+    return extractSourceTables(sql)
+        .map((table) => table.split('.').filter(Boolean).slice(-2, -1)[0] ?? table.split('.').filter(Boolean)[0])
+        .filter(Boolean)
+        .map((value) => businessToken(value))
+        .filter(Boolean);
+}
+function inferSqlEntities(grain, sourceSystems) {
+    const entity = grain && /_id$|_key$/i.test(grain) ? businessEntityFromIdentifier(grain) : '';
+    return Array.from(new Set([entity, ...sourceSystems.map(businessEntityFromIdentifier)].filter(Boolean)));
+}
+function inferSqlDimensions(sql, grain, outputs) {
+    const outputSet = new Set(outputs.map((output) => output.toLowerCase()));
+    return extractGroupByFields(sql)
+        .filter((field) => field !== grain)
+        .filter((field) => !outputSet.has(field.toLowerCase()))
+        .filter((field) => !/\b(total|count|sum|avg|average|min|max|rate|pct|percent|amount|revenue|points?|score)\b/i.test(field))
+        .slice(0, 16);
+}
+function extractGroupByFields(sql) {
+    const match = sql.match(/\bgroup\s+by\b([\s\S]+?)(?:\border\s+by\b|\blimit\b|\bqualify\b|\bhaving\b|$)/i);
+    if (!match)
+        return [];
+    return splitSqlList(match[1])
+        .map((item) => stripSqlIdentifierQuotes(item).trim())
+        .filter((item) => item && !/^\d+$/.test(item))
+        .map((item) => item.split('.').pop() ?? item)
+        .slice(0, 4);
+}
+function splitSqlList(value) {
+    const parts = [];
+    let start = 0;
+    let depth = 0;
+    let single = false;
+    let double = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const char = value[i];
+        if (!double && char === "'" && value[i - 1] !== '\\')
+            single = !single;
+        else if (!single && char === '"' && value[i - 1] !== '\\')
+            double = !double;
+        else if (!single && !double && char === '(')
+            depth += 1;
+        else if (!single && !double && char === ')' && depth > 0)
+            depth -= 1;
+        else if (!single && !double && depth === 0 && char === ',') {
+            parts.push(value.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(value.slice(start));
+    return parts.map((part) => part.trim()).filter(Boolean);
 }
 function collectSqlStatements(sources) {
     const statements = [];
@@ -210,11 +787,12 @@ function buildSqlCandidate(options) {
     const statement = options.statement;
     const sourcePath = displayPath(options.projectRoot, statement.sourcePath);
     const metadata = extractStatementMetadata(statement.sql);
-    const baseName = metadata.name || basename(statement.sourcePath, extname(statement.sourcePath));
+    const sourceTables = extractSourceTables(statement.sql);
+    const inferred = metadata.name ? null : inferStatementBusinessMetadata(statement.sql, sourcePath, sourceTables);
+    const baseName = metadata.name || inferred?.name || basename(statement.sourcePath, extname(statement.sourcePath));
     const name = statement.totalStatements > 1 && !metadata.name
         ? `${baseName} ${statement.statementIndex}`
         : baseName;
-    const sourceTables = extractSourceTables(statement.sql);
     const parameters = extractSqlParameters(statement.sql);
     const warnings = [
         ...(parameters.length > 0 ? [`Contains parameters: ${parameters.join(', ')}`] : []),
@@ -234,9 +812,9 @@ function buildSqlCandidate(options) {
         sourcePath,
         name: titleizeName(name),
         domain: metadata.domain ? sanitizeDomain(metadata.domain) : options.defaults.domain,
-        description: metadata.description || `Imported from ${sourcePath}`,
+        description: metadata.description || inferred?.description || `Imported from ${sourcePath}`,
         owner: options.defaults.owner,
-        tags: normalizeTags([...options.defaults.tags, ...metadata.tags]),
+        tags: normalizeTags([...options.defaults.tags, ...metadata.tags, ...(inferred?.tags ?? [])]),
         sql: statement.sql.trim(),
         dqlSource: '',
         validation: null,
@@ -255,6 +833,7 @@ function buildSqlCandidate(options) {
             'Optional AI assist is review-gated and only receives this candidate context.',
         ],
         aiAssistance: [],
+        reviewCadence: 'monthly',
         reviewStatus: 'draft',
     };
     candidate.dqlSource = candidateToDqlSource(candidate);
@@ -407,9 +986,154 @@ function extractStatementMetadata(sql) {
     const firstComment = leading.match(/^\s*--\s*(?!name\s*:|block\s*:)(.+)$/im)?.[1]?.trim() ?? '';
     return { name, description: firstComment, domain, tags };
 }
+function inferStatementBusinessMetadata(sql, sourcePath, sourceTables) {
+    const expressions = extractSelectExpressions(sql);
+    const aggregateAliases = expressions.filter(isAggregateExpression).map(extractExpressionAlias).filter(Boolean);
+    const dimensionAliases = expressions.filter((expression) => !isAggregateExpression(expression)).map(extractExpressionAlias).filter(Boolean);
+    const orderByAliases = extractOrderByAliases(sql);
+    const metric = aggregateAliases[0] || orderByAliases.find((alias) => /total|sum|count|avg|score|point|revenue|amount|sales|games?/i.test(alias)) || aggregateAliases[0] || '';
+    const dimension = dimensionAliases.find((alias) => !/^row_?number$/i.test(alias)) || '';
+    const years = extractYearFilters(sql);
+    const tableLabel = sourceTables[0] || sourcePath;
+    const tableEntity = businessEntityFromIdentifier(tableLabel.split('.').pop() || tableLabel);
+    const metricLabel = metric ? titleizeName(metric) : '';
+    const pluralDimension = dimension ? pluralizeBusinessEntity(businessEntityFromIdentifier(dimension)) : pluralizeBusinessEntity(tableEntity);
+    const yearLabel = years.length === 1 ? years[0] : years.length > 1 ? years.join(' ') : '';
+    const yearClause = years.length === 1 ? ` for ${years[0]}` : years.length > 1 ? ` for ${years.join(' and ')}` : '';
+    let name = '';
+    if (metricLabel && dimension) {
+        name = `Top ${pluralDimension} By ${metricLabel}${yearLabel ? ` ${yearLabel}` : ''}`;
+    }
+    else if (metricLabel) {
+        name = `${metricLabel}${yearLabel ? ` ${yearLabel}` : ''}`;
+    }
+    else if (dimension) {
+        name = `${pluralDimension} Detail${yearLabel ? ` ${yearLabel}` : ''}`;
+    }
+    const selectedMeasures = aggregateAliases.map(titleizeName).filter((label) => label && label !== metricLabel);
+    let description = '';
+    if (metricLabel && dimension) {
+        description = `Ranks ${pluralDimension.toLowerCase()} by ${metricLabel.toLowerCase()}${yearClause} using ${sourceTables.join(', ') || sourcePath}.`;
+    }
+    else if (metricLabel) {
+        description = `Calculates ${metricLabel.toLowerCase()}${yearClause} using ${sourceTables.join(', ') || sourcePath}.`;
+    }
+    else if (dimension) {
+        description = `Lists ${pluralDimension.toLowerCase()}${yearClause} from ${sourceTables.join(', ') || sourcePath}.`;
+    }
+    if (description && selectedMeasures.length > 0) {
+        description = `${description.replace(/\.$/, '')}, including ${selectedMeasures.map((item) => item.toLowerCase()).join(', ')}.`;
+    }
+    const tags = [
+        ...sourceTables.flatMap((table) => table.split('.').slice(-2).map(businessToken)),
+        metric,
+        dimension,
+        ...years,
+    ].flatMap((item) => item.split(/[_\s.-]+/)).map(businessToken).filter(Boolean);
+    return {
+        name: name || '',
+        description,
+        tags,
+    };
+}
+function extractSelectExpressions(sql) {
+    const cleaned = stripSqlComments(sql);
+    const match = cleaned.match(/\bselect\b([\s\S]+?)\bfrom\b/i);
+    if (!match)
+        return [];
+    return splitTopLevelCommas(match[1])
+        .map((expression) => expression.trim())
+        .filter((expression) => expression && expression !== '*');
+}
+function splitTopLevelCommas(value) {
+    const parts = [];
+    let start = 0;
+    let depth = 0;
+    let single = false;
+    let double = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const char = value[i];
+        if (!double && char === "'" && value[i - 1] !== '\\')
+            single = !single;
+        else if (!single && char === '"' && value[i - 1] !== '\\')
+            double = !double;
+        else if (!single && !double && char === '(')
+            depth += 1;
+        else if (!single && !double && char === ')' && depth > 0)
+            depth -= 1;
+        else if (!single && !double && depth === 0 && char === ',') {
+            parts.push(value.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(value.slice(start));
+    return parts;
+}
+function isAggregateExpression(expression) {
+    return /\b(sum|count|avg|min|max|median|percentile_cont|percentile_disc)\s*\(/i.test(expression);
+}
+function extractExpressionAlias(expression) {
+    const asMatch = expression.match(/\bas\s+[`"[]?([A-Za-z_][A-Za-z0-9_$]*)[`"\]]?\s*$/i);
+    if (asMatch)
+        return asMatch[1];
+    const trailing = expression.match(/\s+[`"[]?([A-Za-z_][A-Za-z0-9_$]*)[`"\]]?\s*$/);
+    if (trailing && !/[).]$/.test(trailing[1]))
+        return trailing[1];
+    const simple = expression.match(/(?:^|\.)[`"[]?([A-Za-z_][A-Za-z0-9_$]*)[`"\]]?\s*$/);
+    return simple?.[1] ?? '';
+}
+function extractOrderByAliases(sql) {
+    const cleaned = stripSqlComments(sql);
+    const match = cleaned.match(/\border\s+by\b([\s\S]+?)(?:\blimit\b|\bfetch\b|\boffset\b|$)/i);
+    if (!match)
+        return [];
+    return splitTopLevelCommas(match[1])
+        .map((item) => item.replace(/\b(asc|desc|nulls\s+first|nulls\s+last)\b/gi, '').trim())
+        .map(extractExpressionAlias)
+        .filter(Boolean);
+}
+function extractYearFilters(sql) {
+    const years = new Set();
+    const cleaned = stripSqlComments(sql);
+    let match;
+    const extractYear = /extract\s*\(\s*year\s+from\s+[^)]+\)\s*(?:=\s*([12][0-9]{3})|in\s*\(([^)]*)\))/gi;
+    while ((match = extractYear.exec(cleaned))) {
+        const raw = match[1] || match[2] || '';
+        for (const year of raw.match(/[12][0-9]{3}/g) ?? [])
+            years.add(year);
+    }
+    const namedYear = /\b(?:year|season)\b\s*(?:=|in\s*\()\s*([^)\s]+(?:\s*,\s*[^)\s]+)*)/gi;
+    while ((match = namedYear.exec(cleaned))) {
+        for (const year of match[1].match(/[12][0-9]{3}/g) ?? [])
+            years.add(year);
+    }
+    return Array.from(years).sort();
+}
+function businessEntityFromIdentifier(identifier) {
+    const clean = identifier
+        .replace(/^(dim|fact|fct|stg|src|int)_/i, '')
+        .replace(/_(id|key|name|code)$/i, '')
+        .replace(/s$/i, '');
+    return titleizeName(clean) || 'Records';
+}
+function pluralizeBusinessEntity(entity) {
+    if (/s$/i.test(entity))
+        return entity;
+    if (/y$/i.test(entity))
+        return `${entity.slice(0, -1)}ies`;
+    return `${entity}s`;
+}
+function businessToken(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/^(dim|fact|fct|stg|src|int)_/, '')
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
 function extractSourceTables(sql) {
     const tables = new Set();
-    const cleaned = stripSqlComments(sql);
+    const cleaned = stripSqlComments(sql).replace(/extract\s*\(\s*\w+\s+from\s+[^)]+\)/gi, 'EXTRACT_VALUE');
     const cteNames = extractCteNames(cleaned);
     const regex = /\b(?:from|join|update|into)\s+([`"[]?[A-Za-z0-9_./:-]+(?:\.[A-Za-z0-9_./:-]+)*[`"\]]?)/gi;
     let match;
@@ -447,6 +1171,9 @@ function extractSqlParameters(sql) {
     const handlebars = /\{\{\s*([A-Za-z_][A-Za-z0-9_.-]*)\s*\}\}/g;
     while ((match = handlebars.exec(cleaned)))
         params.add(match[1]);
+    const dqlTemplate = /\$\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}/g;
+    while ((match = dqlTemplate.exec(cleaned)))
+        params.add(match[1]);
     const colon = /(^|[^:]):([A-Za-z_][A-Za-z0-9_]*)\b/g;
     while ((match = colon.exec(cleaned)))
         params.add(match[2]);
@@ -575,6 +1302,24 @@ function sanitizeDomain(domain) {
 function normalizeTags(tags) {
     return Array.from(new Set(tags.map((tag) => tag.trim().toLowerCase()).filter(Boolean)));
 }
+function normalizePattern(value) {
+    const normalized = (value ?? '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    const allowed = new Set([
+        'metric_wrapper',
+        'entity_profile',
+        'entity_rollup',
+        'ranking',
+        'trend',
+        'bridge',
+        'drilldown',
+        'replacement',
+        'custom',
+    ]);
+    return allowed.has(normalized) ? normalized : '';
+}
+function normalizeStringList(values) {
+    return Array.from(new Set((values ?? []).map((value) => value.trim()).filter(Boolean)));
+}
 function titleizeName(name) {
     return name
         .replace(/\.[^.]+$/, '')