feat(playground): explain each refused known difference once

A refused known difference is now worded from its plain-English entry,
as `sqlquack convert` words it: SQ0008 gives its title, what differs,
when relying on it is fine and when it is wrong, and the one fix that
works under the page's policy and mode. The banner gives the same title.
The example caption that repeated the HASH explanation beside the editor
is gone, and conversion notes say "known difference".

Author: kvlonge

website/public/playground/examples.js

@@ -144,9 +144,3 @@ export const STOP_LABELS = {
 	run: 'stops at Run',
 };
 export const stopLabel = (stops) => (stops ? STOP_LABELS[stops] : 'all four pass');
-
-// Shown under the editor while an example is loaded and unedited.
-export const CAPTIONS = {
-	refused:
-		'Valid Snowflake SQL that SQLQuack will not translate. DuckDB computes HASH differently, so translated SQL would run and return other values. SQLQuack refuses and says why rather than guess; a policy file can allow a known divergence explicitly.',
-};

website/public/playground/index.html

@@ -75,7 +75,6 @@ <h1>Playground</h1>
 						<textarea id="pg-sql" spellcheck="false" autocomplete="off" autocapitalize="off"></textarea>
 					</div>
 					<p class="pg-note">Hover an underline for its diagnostic.</p>
-					<p class="pg-note pg-caption" id="pg-caption" hidden></p>
 					<details open>
 						<summary>Sources: the tables your SQL reads</summary>
 						<textarea class="pg-small" id="pg-sources" spellcheck="false" aria-label="Source file (YAML)"></textarea>
@@ -88,7 +87,7 @@ <h1>Playground</h1>
 					</details>
 					<details>
 						<summary>Policy and session</summary>
-						<textarea class="pg-small" id="pg-policy" spellcheck="false" aria-label="Policy file (TOML)" placeholder="Empty: the built-in default, which refuses every known divergence but the clock and checks that only raise"></textarea>
+						<textarea class="pg-small" id="pg-policy" spellcheck="false" aria-label="Policy file (TOML)" placeholder="Empty: the built-in default, which refuses every known difference but the clock and checks that only raise"></textarea>
 						<p class="pg-note">A policy file, as for <code>--policy</code>. <button class="pg-link" type="button" id="pg-load-policy">Load the repository's sqlquack.toml</button></p>
 						<textarea class="pg-small pg-short" id="pg-session" spellcheck="false" aria-label="Session parameters" placeholder="TIMEZONE=UTC"></textarea>
 						<p class="pg-note">Snowflake session parameters, one <code>NAME=VALUE</code> per line, as for <code>--session</code>.</p>

website/public/playground/playground.js

@@ -4,7 +4,7 @@
 
 import { DUCKDB_DIR, DUCKDB_EXTENSIONS, DUCKDB_WASM_BYTES } from './duckdb-version.js';
 import { ENGINE_DIR, ENGINE_WASM_BYTES } from './engine-version.js';
-import { CAPTIONS, EXAMPLE_GROUPS, EXAMPLES, ROWS, SOURCES, stopLabel } from './examples.js';
+import { EXAMPLE_GROUPS, EXAMPLES, ROWS, SOURCES, stopLabel } from './examples.js';
 import { escape, previewLimit, rendered, resultTable, underlined } from './spans.js';
 
 const here = (path) => new URL(path, import.meta.url).href;
@@ -100,7 +100,6 @@ const strictBox = $('#pg-strict');
 const utcBox = $('#pg-utc');
 const settings = () =>
 	JSON.stringify({ policy: policyBox.value, session: sessionBox.value, strict: strictBox.checked, utc_session: utcBox.checked });
-const caption = $('#pg-caption');
 const verdict = $('#pg-verdict');
 const marks = $('#pg-marks');
 const tip = $('#pg-tip');
@@ -125,11 +124,6 @@ function underline(chars, items) {
 	marks.scrollTop = sqlBox.scrollTop;
 }
 
-function showCaption(example) {
-	caption.textContent = CAPTIONS[example] ?? '';
-	caption.hidden = !CAPTIONS[example];
-}
-
 let latest = null;
 // The helper macros the translated statement calls, created before it runs.
 let latestSetup = [];
@@ -218,7 +212,7 @@ async function run() {
 	const policy = translate.profile ? `policy: ${translate.profile}` : '';
 	if (refused) {
 		const reason = translate.diagnostics?.[0]?.message ?? 'no supported conversion';
-		verdict.innerHTML = `<strong>Valid Snowflake SQL.</strong> Not translated to DuckDB: ${escape(reason)}`;
+		verdict.innerHTML = `<strong>Valid Snowflake SQL, not translated:</strong> ${escape(reason)}`;
 		verdict.hidden = false;
 		setStage('translate', 'refused', body, policy, 'not translated');
 	} else setStage('translate', translate.status, body, policy);
@@ -238,14 +232,14 @@ async function run() {
 }
 
 // What the translation relies on that a reader should know, as `sqlquack convert` prints it:
-// each known divergence the policy allows, and each assumption, which gives a wrong value
+// each known difference the policy allows, and each assumption, which gives a wrong value
 // silently where it does not hold.
 function conversionNotes(translate) {
 	const notes = [];
 	for (const statement of translate.statements ?? [])
 		for (const d of statement.divergences ?? []) {
 			const at = d.constructs.map((construct) => `<code>${escape(construct)}</code>`).join(', ');
-			const kind = d.assumption ? 'assumption' : 'known divergence';
+			const kind = d.assumption ? 'assumption' : 'known difference';
 			notes.push(`Relies on ${kind} <code>${escape(d.id)}</code> at ${at}${d.reason ? `: ${escape(d.reason)}` : ''}`);
 		}
 	return [...new Set(notes)].map((note) => `<p class="pg-conversion-note"><strong>Note.</strong> ${note}</p>`).join('');
@@ -471,7 +465,6 @@ document.addEventListener('click', (event) => {
 	if (event.target.dataset.addRelation) addRelation(event.target.dataset.addRelation);
 });
 sqlBox.addEventListener('input', () => {
-	showCaption(null);
 	// Edited SQL is no longer the example, so neither the chip nor the link names it any more.
 	if (activeExample) {
 		setActiveExample(null);
@@ -516,7 +509,6 @@ function setActiveExample(key) {
 
 function loadExample(key) {
 	sqlBox.value = EXAMPLES[key];
-	showCaption(key);
 	setActiveExample(key);
 }
 

website/public/styles.css

@@ -1328,18 +1328,6 @@ footer a {
 	font-size: 12px;
 }
 
-.pg-caption {
-	padding: 8px 10px;
-	border-left: 2px solid var(--primary);
-	background: var(--accent-soft);
-	color: var(--muted-foreground);
-	font-size: 13px;
-}
-
-.pg-caption[hidden] {
-	display: none;
-}
-
 .pg-note label {
 	margin-right: 16px;
 	cursor: pointer;

website/tests/playground.test.mjs

@@ -108,7 +108,7 @@ test('the conversion budget is timed in the browser and refuses with SQ0006 when
 });
 
 test('every example chip stops at the stage its label names, the Run stage included', async () => {
-	const { EXAMPLE_GROUPS, EXAMPLES, CAPTIONS, SOURCES: PAGE_SOURCES } = await import('../public/playground/examples.js');
+	const { EXAMPLE_GROUPS, EXAMPLES, SOURCES: PAGE_SOURCES } = await import('../public/playground/examples.js');
 	const chips = EXAMPLE_GROUPS.flatMap((group) => group.examples);
 	assert.deepEqual(chips.map((chip) => chip.key).sort(), Object.keys(EXAMPLES).sort());
 	assert.equal(new Set(chips.map((chip) => chip.slug)).size, chips.length);
@@ -126,10 +126,26 @@ test('every example chip stops at the stage its label names, the Run stage inclu
 		}
 	};
 	for (const chip of chips) assert.equal(await stops(EXAMPLES[chip.key]), chip.stops, chip.name);
-	// The one deliberate refusal is a known divergence, explained by its caption.
+	// The one deliberate refusal is a known difference, explained once by its SQ0008.
 	const refused = JSON.parse(analyze(EXAMPLES.refused, PAGE_SOURCES)).translate;
 	assert.deepEqual(refused.diagnostics.map((d) => d.code), ['SQ0008']);
-	assert.ok(CAPTIONS.refused);
+});
+
+test('a refused known difference is worded from its entry, with the one fix that works here, as the CLI words it', () => {
+	const policy = readFileSync(new URL('../../sqlquack.toml', import.meta.url), 'utf8');
+	const refused = (settings) => JSON.parse(analyze('SELECT HASH(order_id) AS h FROM orders', SOURCES, JSON.stringify(settings))).translate.diagnostics[0];
+	const builtin = refused({});
+	assert.equal(builtin.message, 'HASH gives a different value in DuckDB');
+	assert.equal(builtin.label, "DuckDB computes its own hash, never Snowflake's");
+	assert.deepEqual(builtin.notes, [
+		'Equal inputs still get equal hashes within one run.',
+		'fine when: Joins, grouping, removing duplicates and spotting changed rows by hash.',
+		'wrong when: Storing, comparing or sorting by the hash value itself: it differs, with no error.',
+	]);
+	assert.match(builtin.help, /^allow it in a sqlquack\.toml with default = "warn" under \[divergences\.hash\]/);
+	// A policy file that refuses it gets the edit to that file; strict mode the strict setting.
+	assert.match(refused({ policy }).help, /^allow it with default = "warn" under \[divergences\.hash\] in the policy file/);
+	assert.match(refused({ policy, strict: true }).help, /^allow it in strict mode with default = "warn" and strict = "warn"/);
 });
 
 test('date arithmetic against CURRENT_DATE runs in the in-browser DuckDB, on its first statement', async () => {

website/wasm/src/lib.rs

@@ -13,6 +13,8 @@ use sqlquack_blocks::blocks::main::quoted_identifier::quoted_identifier;
 use sqlquack_blocks::checking::constants::SEMI_STRUCTURED_HOLDING_TYPE;
 use sqlquack_blocks::layout::main::layout_sql::layout_sql;
 use sqlquack_blocks::macros::main::helper_statements::helper_statements;
+use sqlquack_convert::snowflake::analysis::main::with_divergence_help::with_divergence_help;
+use sqlquack_convert::snowflake::analysis::models::ConversionChoices;
 use sqlquack_convert::snowflake::catalogue::main::builtin_catalogue::builtin_catalogue;
 use sqlquack_convert::snowflake::conversion::main::convert_statement::convert_statement;
 use sqlquack_convert::snowflake::conversion::main::quoted_exclusions::quoted_exclusions;
@@ -182,11 +184,10 @@ struct Settings {
     compact: bool,
 }
 
-/// Conversion options for `settings` as `sqlquack convert` chooses them, and the matched profile;
-/// a session no recorded profile covers is a refusal, as on the command line.
-fn chosen_options(
+/// The policy file and session parameters `settings` give, as `sqlquack convert` reads them.
+fn chosen_settings(
     settings: &Settings,
-) -> Result<Result<(ConversionOptions, String), String>, String> {
+) -> Result<(Option<Policy>, BTreeMap<String, String>), String> {
     let policy = match settings.policy.trim() {
         "" => None,
         text => Some(
@@ -201,12 +202,7 @@ fn chosen_options(
         .filter(|line| !line.is_empty())
         .map(str::to_owned)
         .collect();
-    let parameters = parse_session(&lines)?;
-    Ok(session_conversion_options(
-        policy.as_ref(),
-        (settings.strict, settings.utc_session),
-        &parameters,
-    ))
+    Ok((policy, parse_session(&lines)?))
 }
 
 /// A stage's verdict and what it found.
@@ -276,10 +272,17 @@ fn stages(sql: &str, catalog: &Catalog, settings: &str) -> Value {
             Err(error) => return json!({ "settings_error": error.to_string() }),
         },
     };
-    let session = match chosen_options(&settings) {
-        Ok(session) => session,
+    let (chosen_policy, parameters) = match chosen_settings(&settings) {
+        Ok(chosen) => chosen,
         Err(error) => return json!({ "settings_error": error }),
     };
+    // Conversion options and the matched profile; a session no recorded profile covers is a
+    // refusal, as on the command line.
+    let session = session_conversion_options(
+        chosen_policy.as_ref(),
+        (settings.strict, settings.utc_session),
+        &parameters,
+    );
     let lines = SourceLines::new(sql);
 
     // 1. Parse as Snowflake.
@@ -405,7 +408,24 @@ fn stages(sql: &str, catalog: &Catalog, settings: &str) -> Value {
             Err(refusal) => refusals.push(placed(refusal, statement, &lines)),
         }
     }
-    let mut translate = Stage::new(refusals.is_empty(), diagnostics(&refusals, sql));
+    // Each SQ0008 worded from its known difference, with the one fix that works here, as
+    // `sqlquack convert` words it.
+    let choices = ConversionChoices {
+        policy_file: "the policy file".to_owned(),
+        strict: settings.strict,
+        utc_session: settings.utc_session,
+        ..ConversionChoices::default()
+    };
+    let worded = with_divergence_help(
+        &refusals,
+        diagnose(&refusals, sql),
+        (chosen_policy.as_ref(), &choices, &parameters),
+    );
+    let worded = worded
+        .iter()
+        .filter_map(|diagnostic| serde_json::to_value(diagnostic).ok())
+        .collect();
+    let mut translate = Stage::new(refusals.is_empty(), worded);
     translate.extra.insert("statements", json!(converted));
     translate.extra.insert("profile", json!(profile));
     json!({ "parse": parse, "checks": checks, "translate": translate })