docs(formatter): document True/None deferral and add None regression tests

- Expand normalize_functions docstrings in FormatConfig and
  format_model_expressions to explicitly document True and None as
  aliases that defer to SQLGlot's default (uppercase custom functions),
  contrasting them with False (preserve) and the string modes.
- Add None regression assertions to the existing normalize_functions test:
  one for the multi-expression path and one for the single-meta-expression
  path, both proving that lowercase audit names are uppercased when
  normalize_functions=None is passed explicitly.
- Update docs/reference/configuration.md to mention 'true' alongside
  'null' as a valid value that defers to the SQLGlot default.

mypy skipped: errors are pre-existing in unrelated files (cache.py,
macros.py, state_sync/base.py) and were present before this branch.

Signed-off-by: Alberto Suman <alberto.suman@1komma5grad.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: albertosuman-1k5

docs/reference/configuration.md

@@ -114,7 +114,7 @@ Formatting settings for the `sqlmesh format` command and UI.
 | `normalize`           | Whether to normalize SQL (Default: False)                                                      | boolean |    N     |
 | `pad`                 | The number of spaces to use for padding (Default: 2)                                           |   int   |    N     |
 | `indent`              | The number of spaces to use for indentation (Default: 2)                                       |   int   |    N     |
-| `normalize_functions` | How to normalize function name casing. `False` (default) preserves the casing of custom and audit function names as written; `"upper"` uppercases all function names; `"lower"` lowercases all function names; `null` defers to SQLGlot's generator default, which uppercases all function names including custom ones. Note: SQLGlot built-in function names may still be canonicalized by the parser regardless of this setting. | string \| boolean \| null |    N     |
+| `normalize_functions` | How to normalize function name casing. `False` (default) preserves the casing of custom and audit function names as written; `"upper"` uppercases all function names; `"lower"` lowercases all function names; `true` or `null` defers to SQLGlot's generator default, which uppercases all function names including custom ones. Note: SQLGlot built-in function names may still be canonicalized by the parser regardless of this setting. | string \| boolean \| null |    N     |
 | `leading_comma`       | Whether to use leading commas (Default: False)                                                 | boolean |    N     |
 | `max_text_width`      | The maximum text width in a segment before creating new lines (Default: 80)                    |   int   |    N     |
 | `append_newline`      | Whether to append a newline to the end of the file (Default: False)                            | boolean |    N     |

sqlmesh/core/config/format.py

@@ -12,9 +12,18 @@ class FormatConfig(BaseConfig):
         normalize: Whether to normalize the SQL code or not.
         pad: The number of spaces to use for padding.
         indent: The number of spaces to use for indentation.
-        normalize_functions: How to normalize function name casing. Use ``False`` (default) to
-            preserve the original casing, ``"upper"`` to uppercase all function names, or
-            ``"lower"`` to lowercase all function names.
+        normalize_functions: How to normalize function name casing.
+
+            * ``False`` (default) — preserves the original spelling of custom and audit
+              function names.  SQLGlot built-in functions (e.g. ``COUNT``, ``SUM``) may
+              still be uppercased because the parser discards the original token.
+            * ``"upper"`` — uppercases all function names, including custom audit
+              references.
+            * ``"lower"`` — lowercases all function names, including built-in ones.
+            * ``True`` or ``None`` — defers to SQLGlot's generator default, which
+              uppercases all function names including custom ones.  These two values are
+              equivalent; ``None`` passes the deferral explicitly rather than relying on
+              the SQLGlot default.
         leading_comma: Whether to use leading commas or not.
         max_text_width: The maximum text width in a segment before creating new lines.
         append_newline: Whether to append a newline to the end of the file or not.

sqlmesh/core/dialect.py

@@ -799,8 +799,17 @@ def format_model_expressions(
         expressions: The model's expressions, must be at least model def + query.
         dialect: The dialect to render the expressions as.
         rewrite_casts: Whether to rewrite all casts to use the :: syntax.
-        normalize_functions: How to normalize function name casing. ``False`` (default)
-            preserves original casing; ``"upper"`` uppercases; ``"lower"`` lowercases.
+        normalize_functions: How to normalize function name casing.
+
+            * ``False`` (default) — preserves the original spelling of custom and audit
+              function names.  SQLGlot built-in functions may still canonicalize because
+              the parser discards the original token.
+            * ``"upper"`` — uppercases all function names including custom audit
+              references.
+            * ``"lower"`` — lowercases all function names including built-ins.
+            * ``True`` or ``None`` — defers to SQLGlot's generator default, which
+              uppercases all function names including custom ones.  Passing ``None``
+              makes the deferral explicit rather than relying on the SQLGlot default.
         **kwargs: Additional keyword arguments to pass to the sql generator.
 
     Returns:

tests/core/test_dialect.py

@@ -436,6 +436,29 @@ def test_format_model_expressions_normalize_functions():
 FROM foo"""
     )
 
+    # None: explicit deferral to SQLGlot default → custom/audit names uppercased,
+    # just like "upper".  This is distinct from False (preserve) and must be tested
+    # explicitly because None used to be indistinguishable from the missing kwarg.
+    assert (
+        format_model_expressions(expressions, normalize_functions=None)
+        == """MODEL (
+  name x,
+  audits (
+    UNIQUE_COMBINATION_OF_COLUMNS(columns := (
+      id
+    )),
+    NOT_NULL(columns := (
+      id
+    ))
+  )
+);
+
+SELECT
+  SUM(id),
+  COUNT(id)
+FROM foo"""
+    )
+
     # Single-meta-expression path: normalize_functions must be forwarded.
     # Without the fix, this path ignored normalize_functions entirely.
     single_model = parse(
@@ -480,6 +503,22 @@ def test_format_model_expressions_normalize_functions():
 )"""
     )
 
+    # Single-meta path, None: custom audit names are uppercased (explicit SQLGlot default deferral).
+    assert (
+        format_model_expressions(single_model, normalize_functions=None)
+        == """MODEL (
+  name x,
+  audits (
+    UNIQUE_COMBINATION_OF_COLUMNS(columns := (
+      id
+    )),
+    NOT_NULL(columns := (
+      id
+    ))
+  )
+)"""
+    )
+
 
 def test_format_config_normalize_functions_false():
     config = FormatConfig(normalize_functions=False)