Repository navigation
feat!: fold header descriptions and accept triple-quoted strings - #1242
Merged
Merged
Conversation
Descriptions in MODEL, SCENARIO, SCHEMA, FUNCTION, HOOK and MACRO headers, column descriptions, audit description options and Rule exception reasons are stored as folded prose: a line break and the spaces around it are one space, and a blank line is a paragraph break. Strings that are meaningful as written (SQL, regexes, literals, meta values) keep their exact text. Any header string may be written between triple quotes, where quotes need no escaping. A backslash-escaped double quote in a prose string, a quote that ends a string inside its text, and an unclosed or inner triple quote fail with their line and column. MACRO header strings no longer depend on quotes in the macro body.
A description that fits stays one line, written as "..." or, when it holds a double quote, as """...""". A longer one becomes an indented """ block wrapped at the line width, and a short wrapped one is joined onto one line. FUNCTION, HOOK, SCHEMA and MACRO descriptions are laid out too. Layout never changes the stored text: each rewrite is checked to fold back to the same description.
sqb format --fix rewrites a description that escapes double quotes with \" as a """...""" string holding real quotes, reported as an applied description-quotes fix. The rewrite is made only when the string's sole backslashes escape quotes and the new string stores exactly that text. When the project cannot compile until the rewrites are saved, Rule fixes are skipped with a warning to rerun.
A """ block indents its lines under the field, so counting its lines would make a description at the line limit fail description-length after formatting. Count the description wrapped from its field to the full width, as before, and update tests for folded descriptions.
A double-quoted description takes backslashes literally, so it may end in one; a single-quoted description reads \' and '' as a quote. MODEL and MACRO headers and every header scanner share this rule, and only prose descriptions reject a quote that runs straight on into more text, so other header strings tokenize as before.
The canonical description layout and the MACRO header layout now keep a change only when the macro parses to the same definition afterwards.
The AUDIT header scanner and the MODEL contract type scanner use the shared header string rules instead of their own quote handling.
A description that doubles its quotes as "" is rewritten as a triple-quoted string like one that escapes them as \", and the quote error's help names both.
A file whose headers, MACRO headers included, still fail once its descriptions are rewritten is left as written, and the fix is reported as refused.
kvlonge
enabled auto-merge (squash)
October 23, 2026 22:33
… fields A one-line header such as FUNCTION (description '...', arguments (...), returns ...) kept its short description as written before; the layout counted the fields after it and turned it into a block. Fields that follow on the line no longer count towards whether a description fits.
…le-quoted form The two cases put a description with an escaped quote and an apostrophe before a body reference error. Descriptions have no \" escape any more, so they now hold the same text as a triple-quoted string, and still check that the body error is located, typed and names the file.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Header descriptions had no reliable way to hold a double quote:
\"failed in short MACRO descriptions but passed by accident in long ones. Wrapped descriptions stored their line breaks, andsqb formatleft continuation lines at column 0.Changes
reasonare stored folded: a line break and its indentation is one space, a blank line a paragraph. Other strings keep their text."""..."""is accepted for any header string; quotes need no escaping."..."description a backslash is literal; in'...'one,\'and''are a quote. MODEL, MACRO and every header scanner share these rules.\","", an inner or unclosed""") fails with line, column and the fix.sqb format: a description that fits stays one line, a longer one becomes an indented"""block. Text never changes; MACRO layouts must parse to the same macro.sqb format --fixrewrites\"and""descriptions as"""strings, only when the whole file then parses; otherwise it reports the fix as refused.BREAKING CHANGE: descriptions written over several lines are stored folded; a description that escapes a double quote as
\"or doubles it as""no longer compiles (runsqb format --fix); and a backslash in a"..."description is literal, so"Path C:\\temp"stores both backslashes.Verification
sqb formatlayout and--fix(applied and refused).make test,make check-ci.make compiler-differential: existing goldens unchanged; two new failure-corpus goldens.