RFC: Add context-sensitive string_continuation_style lint

[leynos]

RFC: string_continuation_style

Preamble

• Status: Proposed
• Repository: leynos/whitaker
• Created: 2026-07-26
• Proposed lint: string_continuation_style
• Default level: Warn
• Suite status: Stable, enabled in the standard suite

Summary

Add an opinionated, context-sensitive Dylint rule that treats a cooked string literal's escaped newline as one of two things:

1. a source-line join, for which concat!() is the required spelling when replacing the literal with a macro expression is proven safe; or
2. a required continuation, retained when concat!() would change the grammar, type, format-argument semantics, or layout intent.

The rule is deliberately asymmetric. It emits a diagnostic only for proven concat!() candidates, but its pure classifier also records why other continuations are required. Tests pin both sides so later broadening cannot quietly turn safe exceptions into false positives.

The central invariant is:

Replace an interior continuation escape with concat!() only when Whitaker can prove that the replacement preserves compilation, type, evaluated string contents, format-argument binding, and macro grammar.

Immediate finding on the motivating example

The CodeRabbit suggestion, as written, does not compile.

This source uses implicit named capture:

let header = format!(
    "HTTP/1.1 {status_line}\r\nContent-Length: {}\r\n\
     Content-Type: application/octet-stream\r\nConnection: close\r\n\r\n",
    body.len(),
);

A direct string literal lets format! capture status_line from the surrounding scope. A format string produced by concat!() does not. Rust deliberately forbids implicit capture when the format string comes from macro expansion.

Accordingly, the exact example is a required continuation and must pass this lint unchanged.

A concat!() rewrite becomes valid only after making the captured argument explicit:

let header = format!(
    concat!(
        "HTTP/1.1 {status_line}\r\nContent-Length: {}\r\n",
        "Content-Type: application/octet-stream\r\nConnection: close\r\n\r\n",
    ),
    body.len(),
    status_line = status_line,
);

The lint will not manufacture redundant explicit format arguments merely to unlock a cosmetic rewrite. That edit broadens the rule from literal spelling into macro argument surgery, behaves differently across formatting facade macros, and sacrifices the useful direct-literal capture idiom.

Motivation

Whitaker already states the house rule in AGENTS.md: use concat!() for long string literals rather than escaped newlines. Review findings have repeatedly applied that guidance to logging and formatting literals.

A naive textual rule would be wrong in several important cases:

• format! and related macros lose implicit named capture when the format string is generated by concat!();
• b"..." and c"..." literals have different types, and stable concat!() produces only &'static str;
• patterns, attributes, and macros with a $literal:literal contract require a literal token rather than a general expression;
• a leading continuation immediately after the opening quote commonly trims the source layout's initial newline and indentation rather than joining two semantic fragments;
• macro-generated or span-mangled literals may not have a trustworthy user-editable replacement range.

The lint therefore needs semantic context, not a regular expression wearing a compiler badge.

Goals

• Enforce concat!() for interior source-line joins in ordinary cooked string expressions.
• Enforce the same rule in source-authored format strings when no argument is implicitly captured and the originating macro accepts an expression in the format-string position.
• Retain escaped-newline continuations when direct-literal status, literal type, literal-token grammar, or layout trimming requires them.
• Provide a whole-literal, machine-applicable suggestion whenever the proof succeeds.
• Preserve the evaluated string byte for byte.
• Catch multiple join continuations with one diagnostic and one replacement.
• Work in the standalone lint crate and the aggregated Whitaker suite.
• Localize the primary message, note, and help in en-GB, cy, and gd.

Non-goals

• Choosing where a long single-line string should wrap.
• Rewriting actual newline characters embedded in a string.
• Rewriting raw strings, which do not interpret continuation escapes.
• Adding explicit format arguments to replace implicit captures.
• Inspecting arbitrary macro token trees whose grammar Whitaker cannot prove.
• Reversing already-valid concat!() expressions into continuation escapes.
• Acting as a general-purpose formatter.

Terminology

Continuation escape

A backslash followed by a physical source newline and the whitespace consumed after that newline. Its evaluated value is empty.

Source-line join

A continuation escape that appears after content on a physical line and before further non-delimiter content. Its sole purpose is to wrap one logical string across source lines.

let text = "first fragment \
            second fragment";

Layout trim

A continuation used to suppress an initial or terminal source-layout newline or indentation, rather than to divide two logical fragments.

let text = "\
    first displayed line
    second displayed line";

Required continuation

A continuation for which replacing the literal expression with concat!() is not proven to preserve the relevant language or macro contract.

Rule semantics

The implementation centres on a pure classification result:

pub(crate) enum ContinuationDisposition {
    PreferConcat(ConcatRewrite),
    RequireContinuation(RequiredReason),
    Ignore,
}

pub(crate) enum RequiredReason {
    ImplicitFormatCapture,
    NonStringLiteralType,
    LeadingOrTrailingLayoutTrim,
    LiteralTokenContext,
    UnknownMacroContract,
    GeneratedFormatString,
    UnrecoverableSourceSpan,
}

Only PreferConcat emits a lint. The RequireContinuation variants exist to make the negative policy explicit and directly testable.

Decision matrix

Source situation	Decision	Rationale
Root-context cooked str expression with an interior join	Diagnose and suggest concat!()	A general expression is valid and type/value are preserved
Source-authored format string with positional or explicitly named arguments only	Diagnose and suggest concat!()	No implicit capture is lost
Source-authored format string containing any FormatArgumentKind::Captured argument	Require continuation	concat!() would turn the format string into macro output and disable capture
Cooked byte string or C string	Require continuation	concat!() changes the type or has no stable equivalent
Raw string, raw byte string, or raw C string	Ignore	Continuation escapes are not interpreted
Leading or trailing layout trim	Require continuation	It expresses source layout rather than a fragment boundary
String literal pattern or attribute/meta literal	Require continuation	concat!() is an expression, not a literal token or pattern
Literal passed through an unknown $literal macro contract	Require continuation	Replacement may stop the outer macro matching
Format string generated by concat!, include_str!, or another eager macro	Ignore	There is no direct source literal to rewrite safely
Literal whose editable source span cannot be recovered exactly	Ignore	No trustworthy suggestion range exists
Several interior joins in one eligible literal	One diagnostic, one whole-literal rewrite	Avoid cascaded diagnostics and conflicting fixes

Why the motivating example passes

Rust's parsed FormatArgs AST retains the complete argument classification. Captured arguments use FormatArgumentKind::Captured(Ident), distinct from positional Normal arguments and explicit Named(Ident) arguments.

The classifier therefore uses:

let has_implicit_capture = format_args
    .arguments
    .all_args()
    .iter()
    .any(|argument| matches!(argument.kind, FormatArgumentKind::Captured(_)));

When this is true, the result is:

ContinuationDisposition::RequireContinuation(
    RequiredReason::ImplicitFormatCapture,
)

This is more reliable than parsing braces manually because it also catches captured width and precision parameters such as {value:width$} and {value:.precision$}.

Detection architecture

Pass phase

Implement the rule as a post-expansion early lint.

This is the narrow sweet spot:

• rustc has expanded format-like macros into ExprKind::FormatArgs, resolved placeholders, and classified captured arguments;
• the AST still retains FormatArgs::uncooked_fmt_str, documented by rustc as useful for lints that care about the raw bytes written by the user;
• FormatArgs::is_source_literal tells the lint whether the format string was written directly rather than produced by concat!() or include_str!();
• ordinary source string expressions still appear as AST literal expressions;
• HIR lowering has not yet erased the source spelling that distinguishes a continuation from an ordinary evaluated string.

Use dylint_linting::impl_early_lint!, not a late HIR pass and not a blind pre-expansion token scan.

AST entry points

EarlyLintPass::check_expr handles two candidate shapes:

match &expr.kind {
    ExprKind::Lit(literal) => check_plain_literal(cx, expr.span, literal),
    ExprKind::FormatArgs(arguments) => check_format_args(cx, expr.span, arguments),
    _ => {}
}

Patterns and attribute/meta literals are intentionally not visited by this rule.

[leynos]

Format strings

For ExprKind::FormatArgs:

1. Require is_source_literal.
2. Require a cooked LitKind::Str uncooked format string.
3. Recover an exact source literal span and verify that its snippet lexes as one cooked string token.
4. Reject spans attributable only to an external or proc-macro expansion.
5. Classify the originating root macro as a known expression-accepting formatting facade.
6. Scan the uncooked source for join continuations.
7. If any argument is Captured, return RequireContinuation(ImplicitFormatCapture).
8. Otherwise build and emit the concat!() rewrite.

The known safe root macros should initially include:

• format_args, format, print, println, eprint, eprintln, write, and writeln;
• panic, todo, unimplemented, and unreachable where their modern formatting form is used;
• assert, assert_eq, assert_ne, and the corresponding debug_assert forms for custom messages;
• the log and tracing formatting facades trace, debug, info, warn, and error.

Skip locally defined macros even when they reuse one of those short names. The expansion backtrace exposes the macro definition ID and name, allowing the lint to reject local lookalikes.

Ordinary string expressions

For a direct cooked str expression:

1. Require a user-editable source span in root syntax context.
2. Require that the source snippet lexes as exactly one cooked string literal.
3. Scan for interior join continuations.
4. Ignore literals containing only leading or trailing layout trims.
5. Build a whole-literal concat!() rewrite.

Source literals that originated inside an unknown macro expansion are skipped because the source macro may have matched $literal:literal.

Continuation scanner

Implement the scanner as a pure byte-oriented module over the literal body.

A continuation begins at an unescaped backslash immediately followed by either \n or \r\n. Count the run of consecutive backslashes to distinguish a continuation from a literal escaped backslash. An odd run leaves one continuation backslash; an even run does not.

After the newline, consume exactly the whitespace rustc removes for string continuation. The scanner records:

pub(crate) struct Continuation {
    pub escape_range: Range<usize>,
    pub skipped_whitespace_range: Range<usize>,
    pub kind: ContinuationKind,
}

pub(crate) enum ContinuationKind {
    Join,
    LeadingLayoutTrim,
    TrailingLayoutTrim,
}

A continuation is a Join only when:

• some non-whitespace source content precedes the backslash on the same physical line; and
• some non-delimiter content follows the consumed whitespace.

This avoids converting the common opening "\ block-layout idiom into a ceremonial concat!("") contraption.

Rewrite construction

Split only at continuations classified as Join. Any retained layout continuation remains inside its fragment.

For:

"alpha \
 beta\
 gamma"

produce:

concat!(
    "alpha ",
    "beta",
    "gamma",
)

The rewriter copies the original source spelling of every fragment. It does not decode and re-encode the literal, so escape sequences, Unicode spelling, and brace escaping remain untouched.

The proof obligation is simple at source level:

concatenate(rewrite_fragments)
    == original_literal_body with each selected continuation range removed

Since a continuation contributes no evaluated character and split points never bisect another escape, separately decoding the copied fragments produces the same value as decoding the original literal.

Applicability

Use Applicability::MachineApplicable only when all of the following hold:

• the source span is exact and user-editable;
• the snippet is exactly one cooked string literal;
• every selected split is an interior join;
• the context accepts a general expression;
• a format string has no implicit captures;
• the root macro contract is known safe;
• the generated replacement re-lexes as one concat!() expression.

Otherwise suppress the lint rather than emit an unfixable style complaint. This rule should have near-zero false-positive tolerance.

Diagnostic

Declaration

dylint_linting::impl_early_lint! {
    pub STRING_CONTINUATION_STYLE,
    Warn,
    "source-line joins in cooked strings should use concat! unless literal context requires a continuation escape",
    StringContinuationStyle::default()
}

English diagnostic copy

Primary:

join these string fragments with concat!()

Note:

the continuation escape removes the physical newline and following indentation, hiding the fragment boundary inside one literal

Help:

split the cooked string into concat!() arguments at each source-line join

Label each selected backslash:

source-line join

For multiple joins, emit one primary diagnostic on the literal and secondary labels on each continuation.

Crate layout

Add:

crates/string_continuation_style/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── classification.rs
│   ├── continuation.rs
│   ├── diagnostics.rs
│   ├── driver.rs
│   └── rewrite.rs
├── tests/
│   └── features/
│       └── string_continuation_style.feature
├── ui/
│   ├── fail_plain_join.rs
│   ├── fail_plain_join.stderr
│   ├── fail_explicit_format_arguments.rs
│   ├── fail_explicit_format_arguments.stderr
│   ├── fail_multiple_joins.rs
│   ├── fail_multiple_joins.stderr
│   ├── pass_implicit_format_capture.rs
│   ├── pass_implicit_width_capture.rs
│   ├── pass_leading_layout_trim.rs
│   ├── pass_byte_and_c_strings.rs
│   ├── pass_unknown_literal_macro.rs
│   └── pass_generated_format_string.rs
├── ui-cy/
│   └── locale_smoke.rs
└── ui-gd/
    └── locale_smoke.rs

Keep each source module below Whitaker's 400-line limit.

Dependencies

The lint crate needs only:

• dylint_linting;
• rustc_ast;
• rustc_lint;
• rustc_session;
• rustc_span;
• whitaker-common;
• whitaker for shared driver wiring;
• proptest, rstest, rstest-bdd, rstest-bdd-macros, and dylint_testing as development dependencies.

No configuration section is proposed. The proof predicate is the configuration.

Suite integration

Add string_continuation_style as a constituent dependency of whitaker_suite and include STRING_CONTINUATION_STYLE in SUITE_LINT_DECLS.

Because the existing suite combines late passes only, register this lint separately:

pub fn register_suite_lints(store: &mut LintStore) {
    store.register_lints(SUITE_LINT_DECLS);
    store.register_early_pass(|| Box::new(
        string_continuation_style::StringContinuationStyle::default(),
    ));
    store.register_late_pass(|_| Box::new(SuitePass::new()));
}

Do not force an early lint into the combined late-pass macro merely for visual uniformity.

Update:

• suite/Cargo.toml feature and dependency lists;
• suite/src/lints.rs descriptors and declarations;
• suite count and name tests;
• installer lint enumeration, if it is not derived from suite metadata;
• README.md and docs/users-guide.md;
• docs/roadmap.md, adding this as the next core lint item;
• Fluent resources under common/locales/{en-GB,cy,gd}.

[coderabbitai]

🔗 Related PRs

leynos/mdtablefix#304 - Fix cross-line inline code span reflow (#297) [closed]
leynos/mdtablefix#344 - Preserve inline code spans when wrapping prose (#326) (#323) (#327) (#310) [closed]
leynos/mdtablefix#356 - Keep escaped backtick code spans atomic (#354) [closed]
#263 - Propose lint candidates derived from CodeRabbit review findings [merged]
leynos/mdtablefix#394 - Protect literal ellipsis regions (#369) (#386) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

Test plan

UI failures

1. Plain string join

   let text = "alpha \
               beta";
   //~^ ERROR join these string fragments with `concat!()`

2. Format string with positional arguments only

   let text = format!(
       "value={} \
        units",
       3,
   );

3. Format string with explicitly named arguments

   let text = format!(
       "value={value} \
        units",
       value = value,
   );

4. Multiple joins produce one diagnostic and one replacement.

5. Join consuming blank source lines preserves the exact evaluated value.

6. Known standard formatting facade such as println! receives a valid suggestion.

UI passes

1. The exact PR Adopt sha2 0.11 with explicit lower-case hex encoding #296 example with implicit status_line capture.
2. Captured width and precision parameters.
3. Leading block-layout continuation.
4. Trailing layout trim.
5. Byte strings and C strings.
6. Raw strings.
7. String patterns and attribute/meta literals.
8. A local macro declared with $message:literal and forwarding to format_args!.
9. A format string generated by concat!() or include_str!().
10. Proc-macro-generated or unrecoverable spans.
11. An ordinary literal containing a real newline rather than a continuation.

Pure unit and property tests

• Classify odd and even runs of backslashes before LF and CRLF.
• Classify leading, interior, and trailing continuations.
• Assert that splitting and re-concatenating copied fragment source equals deleting the selected continuation ranges.
• Generate arbitrary safe fragment text and one to several continuation joins with proptest.
• Verify Unicode before and after split points.
• Verify escaped quotes, escaped braces, and ordinary Rust escapes remain unchanged.
• Verify one diagnostic is produced for any positive number of joins in one literal.

Behaviour scenarios

Feature: Context-sensitive string continuation style

  Scenario: An ordinary source-line join prefers concat
    Given a cooked string expression with an interior continuation
    And the literal is in a general expression context
    When the continuation is classified
    Then the disposition is PreferConcat

  Scenario: An implicit format capture requires the direct literal
    Given a source-authored format string with an interior continuation
    And rustc classified one argument as Captured
    When the continuation is classified
    Then the disposition is RequireContinuation with reason ImplicitFormatCapture

  Scenario: A leading continuation expresses source layout
    Given a cooked string whose first token after the opening quote is a continuation
    When the continuation is classified
    Then the disposition is RequireContinuation with reason LeadingOrTrailingLayoutTrim

Acceptance fixtures

Must pass unchanged

fn header(status_line: &str, length: usize) -> String {
    format!(
        "HTTP/1.1 {status_line}\r\nContent-Length: {}\r\n\
         Content-Type: application/octet-stream\r\nConnection: close\r\n\r\n",
        length,
    )
}

Must fail with a machine-applicable rewrite

fn header(status_line: &str, length: usize) -> String {
    format!(
        "HTTP/1.1 {status_line}\r\nContent-Length: {}\r\n\
         Content-Type: application/octet-stream\r\nConnection: close\r\n\r\n",
        length,
        status_line = status_line,
    )
}

Expected replacement:

fn header(status_line: &str, length: usize) -> String {
    format!(
        concat!(
            "HTTP/1.1 {status_line}\r\nContent-Length: {}\r\n",
            "Content-Type: application/octet-stream\r\nConnection: close\r\n\r\n",
        ),
        length,
        status_line = status_line,
    )
}

Rollout

1. Land the lint with its classifier, UI matrix, localization, suite registration, and user documentation.

2. Dogfood it against Whitaker. The PR Adopt sha2 0.11 with explicit lower-case hex encoding #296 fixture must remain clean because of its capture.

3. Run it across df12 Rust repositories and apply machine fixes.

4. Replace CodeRabbit's unconditional prose guidance with the context-sensitive rule:

   Use concat!() for interior joins in cooked string expressions unless direct-literal status is required, including implicit format capture or a literal-only macro contract.

5. Promote no later than the next normal Whitaker release. The rule is deterministic and should not need an experimental incubation period.

Alternatives considered

Textual search for backslash-newline

Rejected. It cannot distinguish raw, byte, C, format-capture, macro-contract, pattern, or layout cases.

Pre-expansion macro-token lint

Rejected as the primary architecture. It preserves spelling but would have to reimplement format argument classification and macro grammar reasoning that rustc already performs.

Late HIR lint

Rejected. HIR no longer retains the exact source spelling that distinguishes an escaped newline from an equivalent evaluated string.

Always add explicit captured arguments and use concat!()

Rejected. It makes a style lint edit macro argument structure, introduces redundant bindings, varies across facade macro grammars, and converts a simple source-spelling rule into a larger semantic rewrite.

Exempt all format strings

Rejected. Format strings with positional or already-explicit named arguments can use concat!() safely, and they account for many of the repeated review findings.

Permit every continuation

Rejected. That merely restates the language grammar and does not enforce Whitaker's established style.

Review response for PR #296

A technically accurate response to the open review thread is:

The proposed replacement is not semantics-preserving as written. This format string implicitly captures status_line, while format!(concat!(...)) cannot capture surrounding identifiers because the format string comes from macro expansion. We must either retain the continuation escape or add status_line = status_line. The context-sensitive Whitaker rule treats this instance as a required continuation and uses concat!() only where no capture or literal-token contract is lost.

Source basis

• AGENTS.md requires concat!() for long string literals instead of escaped newlines.
• rustc_ast::FormatArgs retains uncooked_fmt_str specifically for raw-source-sensitive lints and records whether the format string was directly written in source.
• rustc_ast::FormatArgumentKind distinguishes Normal, Named, and Captured arguments.
• rustc_builtin_macros::format explicitly disables implicit capture when the first format argument is not a direct literal.
• Rust's own UI test verifies that format!(concat!("{a}")) fails with the diagnostic that format_args! cannot capture variables when its format string is expanded from a macro.