docs(website): generate the Allow example and name the policy page by its label

The Allow example refuses every known difference the defaults allow that can return a
different value, generated so it can't drift. The policy page is titled Refuse, allow or
replace, links that quoted the old title follow it, and project.mdx and the README say the
defaults. The intro to the ones that raise an error no longer claims Snowflake returns a
value.

Author: kvlonge

README.md

@@ -51,7 +51,7 @@ sqlquack convert query.sql
 
 Or **[try the playground](https://sqlquack.io/playground/)** - no installation needed.
 
-See the [supported dialects and coverage](https://sqlquack.io/docs/coverage/), [project guide](https://sqlquack.io/docs/project/) and [conversion policy](https://sqlquack.io/docs/policy/) for the details.
+See the [supported dialects and coverage](https://sqlquack.io/docs/coverage/), [project guide](https://sqlquack.io/docs/project/) and [defaults for known differences](https://sqlquack.io/docs/policy/) for the details.
 
 ## Use it from Python
 

website/scripts/generate_known_differences.py

@@ -4,8 +4,10 @@
 say for each known difference what differs, when relying on it is fine, when it is wrong and how
 it fails; `crates/sqlquack-policy/policy.toml` gives each one's default. This script writes them
 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. With
-`--check` it writes nothing and exits 1 when the page differs from what the entries give.
+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. With `--check` it writes nothing and exits 1 when
+either page differs from what the entries give.
 
 Usage: python3 scripts/generate_known_differences.py [--check]   (from website/)
 """
@@ -24,13 +26,19 @@
 ENTRIES = POLICY / "known_differences/constants.rs"
 DEFAULTS = POLICY.parent / "policy.toml"
 PAGE = WEBSITE / "src/content/docs/docs/known-differences.mdx"
+POLICY_PAGE = WEBSITE / "src/content/docs/docs/policy.mdx"
 
 BEGIN = (
     "{/* Generated by website/scripts/generate_known_differences.py from\n"
     "    crates/sqlquack-policy/src/known_differences/constants.rs. Edit the entries, then rerun"
     " it. */}"
 )
 END = "{/* End of the generated known differences. */}"
+ALLOW_BEGIN = (
+    "{/* Generated by website/scripts/generate_known_differences.py: each known difference that\n"
+    "    can return a different value and that the defaults allow. */}"
+)
+ALLOW_END = "{/* End of the generated [allow] example. */}"
 
 CONSTANT = re.compile(r"pub const (\w+): &str =\s*" + STRING + r";", re.S)
 ENTRY = re.compile(r"KnownDifference \{(.*?)\}", re.S)
@@ -158,7 +166,7 @@ def table(known: list[dict[str, str]], default: dict[str, str]) -> list[str]:
         "",
         "## Raise an error instead",
         "",
-        "Where one of these doesn't hold, DuckDB raises an error where Snowflake returns a value,"
+        "Where one of these doesn't hold, DuckDB raises an error instead of returning a value,"
         " never a different value.",
     ]
     for area, names in AREAS.items():
@@ -168,25 +176,42 @@ def table(known: list[dict[str, str]], default: dict[str, str]) -> list[str]:
     return lines + ["", END]
 
 
-def page(current: str, known: list[dict[str, str]], default: dict[str, str]) -> str:
-    """The page with its generated block replaced."""
-    start, end = current.index(BEGIN), current.index(END) + len(END)
-    return current[:start] + "\n".join(table(known, default)) + current[end:]
+def refuse_allowed(known: list[dict[str, str]], default: dict[str, str]) -> list[str]:
+    """An `[allow]` table refusing each one the defaults allow that can return a different value."""
+    names = [
+        entry["name"]
+        for entry in known
+        if entry["failure"] == FAILS_WITH["Value"] and default[entry["name"]] == "allowed"
+    ]
+    refusals = [f"{name} = false" for name in names]
+    return [ALLOW_BEGIN, "", "```toml", "[allow]", *refusals, "```", "", ALLOW_END]
+
+
+def replaced(current: str, begin: str, end: str, lines: list[str]) -> str:
+    """The page with the block between `begin` and `end` replaced by `lines`."""
+    start, stop = current.index(begin), current.index(end) + len(end)
+    return current[:start] + "\n".join(lines) + current[stop:]
 
 
 def main(argv: list[str]) -> int:
-    current = PAGE.read_text()
-    wanted = page(current, entries(ENTRIES.read_text(), constants()), defaults())
-    if "--check" in argv:
-        if current != wanted:
+    known, default = entries(ENTRIES.read_text(), constants()), defaults()
+    blocks = [
+        (PAGE, BEGIN, END, table(known, default)),
+        (POLICY_PAGE, ALLOW_BEGIN, ALLOW_END, refuse_allowed(known, default)),
+    ]
+    stale = 0
+    for path, begin, end, lines in blocks:
+        current = path.read_text()
+        wanted = replaced(current, begin, end, lines)
+        if "--check" not in argv:
+            path.write_text(wanted)
+        elif current != wanted:
             print(
-                f"{PAGE} is out of date; run python3 scripts/generate_known_differences.py",
+                f"{path} is out of date; run python3 scripts/generate_known_differences.py",
                 file=sys.stderr,
             )
-            return 1
-        return 0
-    PAGE.write_text(wanted)
-    return 0
+            stale = 1
+    return stale
 
 
 if __name__ == "__main__":

website/src/content/docs/docs/cli/convert.mdx

@@ -68,7 +68,7 @@ SQL that does not parse, or that Snowflake rejects, is refused with the same cod
 | `--color auto\|always\|never` | Highlight the SQL and colour diagnostics, as for [`check`](/docs/cli/check/#options). JSON is never coloured. |
 
 `convert` also takes the configuration flags: `--config`, `--no-config`, `--strict` and
-`--python-runtime`. See [When something can't convert exactly](/docs/policy/#flags).
+`--python-runtime`. See [Refuse, allow or replace](/docs/policy/#flags).
 
 ## JSON report
 

website/src/content/docs/docs/known-differences.mdx

@@ -122,7 +122,7 @@ Where one of these doesn't hold, the converted SQL returns a value that differs
 
 ## Raise an error instead
 
-Where one of these doesn't hold, DuckDB raises an error where Snowflake returns a value, never a different value.
+Where one of these doesn't hold, DuckDB raises an error instead of returning a value, never a different value.
 
 ### Numbers
 

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

@@ -1,8 +1,6 @@
 ---
-title: "When something can't convert exactly"
-description: "Refuse, allow or replace each known difference between Snowflake and DuckDB."
-sidebar:
-  label: "Refuse, allow or replace"
+title: "Refuse, allow or replace"
+description: "When something can't convert exactly: refuse, allow or replace each known difference between Snowflake and DuckDB."
 tableOfContents:
   maxHeadingLevel: 2
 ---
@@ -76,14 +74,24 @@ hash = true
 A name that isn't a known difference is an error that names the nearest one. Some known
 differences [can return a different value](/docs/known-differences/#can-return-a-different-value)
 with no error, and `sqlquack explain --differences` marks
-them `value`. To convert only what is exact or fails with an error, refuse each of those:
+them `value`. To convert only what is exact or fails with an error, refuse each of those that the
+defaults allow:
+
+{/* Generated by website/scripts/generate_known_differences.py: each known difference that
+    can return a different value and that the defaults allow. */}
 
 ```toml
 [allow]
-current_time = false
+user_override = false
+declared_offset = false
 session_timezone_utc = false
+random = false
+uuid = false
+current_time = false
 ```
 
+{/* End of the generated [allow] example. */}
+
 A conversion that relies on an allowed known difference names it in its last line on standard
 error, and `--verbose` adds a warning at each use:
 

website/src/content/docs/docs/project.mdx

@@ -126,8 +126,8 @@ sources = "warehouse/tables"
 Paths are relative to the project folder, and a folder you name must exist. `functions` and
 `overrides` work the same way.
 
-A `sqlquack.toml` holding only `[project]` keeps the built-in [policy](/docs/policy/). To use your
-own policy, keep the policy tables in the same file.
+A `sqlquack.toml` holding only `[project]` keeps [the defaults](/docs/policy/). To change them,
+add `[allow]` or `[replace]` to the same file.
 
 ## Functions
 

website/src/content/docs/docs/quickstart.mdx

@@ -109,7 +109,7 @@ differences you refuse it, allow it or replace it with your own SQL, in `sqlquac
 current directory or the file `--config` names. Without one, or with `--no-config`, `convert`
 uses the defaults: they allow every known difference, with a warning, except five whose values can
 differ from Snowflake's with no error, such as `HASH`. See
-[When something can't convert exactly](/docs/policy/).
+[Refuse, allow or replace](/docs/policy/).
 
 ## Next steps