docs(website): generate the policy page's count and list of refused defaults

The choices table's count and the list of known differences the defaults refuse come
from the policy, as the quickstart's do, so no count or name of a default is written by
hand.

Author: kvlonge

website/scripts/generate_known_differences.py

@@ -6,9 +6,9 @@
 between the generated markers of `website/src/content/docs/docs/known-differences.mdx`: first the
 ones that can return a different value, then the ones that raise an error instead, by area. It also
 writes the `[allow]` example on `website/src/content/docs/docs/policy.mdx` that refuses each one the
-defaults allow that can return a different value, and the sentence on
-`website/src/content/docs/docs/quickstart.mdx` naming the ones the defaults refuse. With `--check`
-it writes nothing and exits 1 when a page differs from what the entries give.
+defaults allow that can return a different value, that page's count and list of the ones the
+defaults refuse, and the sentence on `website/src/content/docs/docs/quickstart.mdx` naming them.
+With `--check` it writes nothing and exits 1 when a page differs from what the entries give.
 
 Usage: python3 scripts/generate_known_differences.py [--check]   (from website/)
 """
@@ -46,7 +46,21 @@
     "    defaults refuse. */}"
 )
 REFUSED_END = "{/* End of the generated defaults. */}"
+COUNT_BEGIN = "{/* Generated: how many the defaults refuse. */}"
+COUNT_END = "{/* End of the generated count. */}"
+DEFAULTS_BEGIN = (
+    "{/* Generated by website/scripts/generate_known_differences.py: the known differences the\n"
+    "    defaults refuse, and why. */}"
+)
+DEFAULTS_END = "{/* End of the generated list of refused defaults. */}"
 NUMBERS = "no one two three four five six seven eight nine ten eleven twelve".split()
+# Why the defaults refuse a known difference, where it isn't that its values can differ.
+REFUSED_UNTIL = {
+    "project_udf": (
+        "until `python_runtime = true` under `[project]` says a Python runtime registers\n"
+        "  the project's functions."
+    ),
+}
 
 CONSTANT = re.compile(r"pub const (\w+): &str =\s*" + STRING + r";", re.S)
 ENTRY = re.compile(r"KnownDifference \{(.*?)\}", re.S)
@@ -195,16 +209,64 @@ def refuse_allowed(known: list[dict[str, str]], default: dict[str, str]) -> list
     return [ALLOW_BEGIN, "", "```toml", "[allow]", *refusals, "```", "", ALLOW_END]
 
 
+def refused(known: list[dict[str, str]], default: dict[str, str]) -> list[dict[str, str]]:
+    """The entries the defaults refuse, in table order."""
+    return [entry for entry in known if default[entry["name"]] == "refused"]
+
+
+def number(count: int) -> str:
+    """A count in words, as the pages write it."""
+    return NUMBERS[count] if count < len(NUMBERS) else str(count)
+
+
+def listed(names: list[str]) -> str:
+    """Names in code, as `a`, `b` and `c`."""
+    names = [f"`{name}`" for name in names]
+    return ", ".join(names[:-1]) + f" and {names[-1]}" if len(names) > 1 else "".join(names)
+
+
+def refused_count(known: list[dict[str, str]], default: dict[str, str]) -> list[str]:
+    """How many the defaults refuse, in words, inline in the policy page's choices table."""
+    return [COUNT_BEGIN + number(len(refused(known, default))) + COUNT_END]
+
+
+def refused_list(known: list[dict[str, str]], default: dict[str, str]) -> list[str]:
+    """The policy page's list of the known differences the defaults refuse, and why."""
+    names = [entry["name"] for entry in refused(known, default)]
+    stray = sorted(set(REFUSED_UNTIL) - set(names))
+    if stray:
+        raise SystemExit(f"REFUSED_UNTIL in {__file__} names ones the defaults allow: {stray}")
+    by_value = sorted(name for name in names if name not in REFUSED_UNTIL)
+    loud = [
+        e["name"] for e in known if e["name"] in by_value and e["failure"] != FAILS_WITH["Value"]
+    ]
+    if loud:
+        raise SystemExit(f"{loud} are refused but only raise an error; give each a REFUSED_UNTIL")
+    lines = [
+        DEFAULTS_BEGIN,
+        "",
+        f"The defaults allow every known difference except these {number(len(names))}, which they"
+        " refuse:",
+        "",
+    ]
+    if by_value:
+        lines += [
+            f"- {listed(by_value)}, whose values can differ",
+            "  from Snowflake's with no error.",
+        ]
+    lines += [f"- `{name}`, {REFUSED_UNTIL[name]}" for name in names if name in REFUSED_UNTIL]
+    return lines + ["", DEFAULTS_END]
+
+
 def refused_by_default(known: list[dict[str, str]], default: dict[str, str]) -> list[str]:
     """A paragraph naming the known differences the defaults refuse."""
-    names = [f"`{entry['name']}`" for entry in known if default[entry["name"]] == "refused"]
-    listed = ", ".join(names[:-1]) + f" and {names[-1]}" if len(names) > 1 else "".join(names)
-    count = NUMBERS[len(names)] if len(names) < len(NUMBERS) else str(len(names))
+    names = [entry["name"] for entry in refused(known, default)]
     return [
         REFUSED_BEGIN,
         "",
-        f"The defaults refuse {count} known difference{'' if len(names) == 1 else 's'},",
-        f"{listed},",
+        f"The defaults refuse {number(len(names))} known"
+        f" difference{'' if len(names) == 1 else 's'},",
+        f"{listed(names)},",
         "and allow the rest with a warning.",
         "[Can return a different value](/docs/known-differences/#can-return-a-different-value)",
         "lists the ones whose values can differ from Snowflake's with no error, and their",
@@ -225,6 +287,8 @@ def main(argv: list[str]) -> int:
     blocks = [
         (PAGE, BEGIN, END, table(known, default)),
         (POLICY_PAGE, ALLOW_BEGIN, ALLOW_END, refuse_allowed(known, default)),
+        (POLICY_PAGE, COUNT_BEGIN, COUNT_END, refused_count(known, default)),
+        (POLICY_PAGE, DEFAULTS_BEGIN, DEFAULTS_END, refused_list(known, default)),
         (QUICKSTART, REFUSED_BEGIN, REFUSED_END, refused_by_default(known, default)),
     ]
     stale = 0

website/src/content/docs/docs/policy.mdx

@@ -18,7 +18,7 @@ When a statement needs a known difference, you choose what happens:
 
 | Choice | What happens | How |
 |--------|--------------|-----|
-| [Refuse](#refuse) | The statement isn't converted. [`SQ0008`](/docs/diagnostics/reference/#sq0008) points at the construct. | `name = false` under `[allow]` in `sqlquack.toml`. The default for five. |
+| [Refuse](#refuse) | The statement isn't converted. [`SQ0008`](/docs/diagnostics/reference/#sq0008) points at the construct. | `name = false` under `[allow]` in `sqlquack.toml`. The default for {/* Generated: how many the defaults refuse. */}five{/* End of the generated count. */}. |
 | [Allow](#allow) | The statement converts. A warning names the known difference it relies on. | `name = true` under `[allow]`. The default for the rest. |
 | [Replace](#replace) | Calls to a Snowflake function use your own DuckDB SQL. | One file under `overrides/`. |
 
@@ -49,13 +49,18 @@ sqlquack convert: refused, 1 refusal
 [project](/docs/project/)'s `sqlquack.toml`, or from the file `--config` names, on top of the
 defaults. Without one, they use the defaults alone.
 
+{/* Generated by website/scripts/generate_known_differences.py: the known differences the
+    defaults refuse, and why. */}
+
 The defaults allow every known difference except these five, which they refuse:
 
 - `hash`, `sequences`, `source_variant_json` and `variant_chain_type`, whose values can differ
   from Snowflake's with no error.
 - `project_udf`, until `python_runtime = true` under `[project]` says a Python runtime registers
   the project's functions.
 
+{/* End of the generated list of refused defaults. */}
+
 `sqlquack explain --differences` lists how the defaults and your `sqlquack.toml` treat each one.
 
 `--no-config` uses the defaults alone even where a `sqlquack.toml` exists.