@ttsc/lint 0.12.4 → 0.13.1

package/linthost/format.go

@@ -41,8 +41,12 @@ func runFormat(opts *subcommandOpts) int {
     fmt.Fprintln(os.Stderr, err)
     return 2
   }
+  resolver := formatCommandResolver{inner: rules}
+  engine := NewEngineWithResolver(resolver)
+  engine.SetSerial(opts.singleThreaded)
+  needsRuleChecker := engine.NeedsTypeChecker()
 
-  prog, code := loadFixProgram(opts)
+  prog, code := loadFixProgram(opts, needsRuleChecker)
   if code != 0 {
     return code
   }
@@ -55,7 +59,6 @@ func runFormat(opts *subcommandOpts) int {
   totalFixes := 0
   cascadeConverged := false
   for pass := 0; pass < maxFormatPasses; pass++ {
-    engine := NewEngineWithResolver(formatCommandResolver{inner: rules})
     findings := engine.Run(prog.userSourceFiles(), prog.checker)
     fixed, err := applyFindingFixes(opts.cwd, filterFormatFindings(findings))
     if err != nil {
@@ -67,7 +70,7 @@ func runFormat(opts *subcommandOpts) int {
       break
     }
     totalFixes += fixed
-    prog, code = reloadFixProgram(prog, opts)
+    prog, code = reloadFixProgram(prog, opts, needsRuleChecker)
     if code != 0 {
       return code
     }
@@ -102,11 +105,34 @@ type formatCommandResolver struct {
 // ResolveRules implements RuleResolver. It delegates to the inner resolver
 // and then upgrades format-rule entries from off to warn so they are applied
 // even when the project config omits them.
+//
+// A user-authored entry whose `ignores` list matches `fileName` is honored
+// here even when the entry also carries a `rules` block: the engine already
+// skips that entry's rule contributions via `ConfigEntry.matchesFile`, so the
+// format command must skip its blanket format-rule upgrade as well. Without
+// this guard, `ttsc format` would rewrite files that the user explicitly
+// asked the lint config to ignore — the engine's lint walk would skip the
+// file but the formatter would still touch it.
+//
+// The symmetric guard applies to `files`: if every non-IgnoreOnly entry
+// carries a `files` filter and `fileName` matches none of them, the engine
+// would not run any rules on the file (`ConfigEntry.matchesFile` returns
+// false for every entry). The format command must skip its blanket
+// format-rule upgrade for the same reason — otherwise `ttsc format` would
+// rewrite files that fall outside every entry's scope, e.g. a `.json`
+// resolved into the program via `resolveJsonModule` when the only entry
+// targets `src/**/*.ts`.
 func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig {
   resolved := r.inner.ResolveRules(fileName)
   if resolved.Ignored {
     return resolved
   }
+  if r.fileIsIgnoredByEntry(fileName) {
+    return resolved
+  }
+  if !r.fileMatchesAnyEntry(fileName) {
+    return resolved
+  }
   if resolved.Rules == nil {
     resolved.Rules = RuleConfig{}
   }
@@ -118,6 +144,73 @@ func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig
   return resolved
 }
 
+// fileIsIgnoredByEntry reports whether any non-IgnoreOnly entry in the inner
+// ConfigStore has an `ignores` glob that matches `fileName`. IgnoreOnly
+// entries are already handled by ResolvedRuleConfig.Ignored — they are
+// checked first by ConfigStore.ResolveRules and short-circuit the walk. This
+// helper covers the complementary case: an entry that carries both `rules`
+// and `ignores`, where the engine skips the entry's rule contributions via
+// `ConfigEntry.matchesFile` but the format command must learn the same fact
+// independently because its job is to upgrade format rules to `warn`, not to
+// read the engine's resolved severity map.
+func (r formatCommandResolver) fileIsIgnoredByEntry(fileName string) bool {
+  store, ok := r.inner.(*ConfigStore)
+  if !ok || store == nil {
+    return false
+  }
+  for _, entry := range store.entries {
+    if entry.IgnoreOnly {
+      continue
+    }
+    if entry.matchesIgnores(fileName) {
+      return true
+    }
+  }
+  return false
+}
+
+// fileMatchesAnyEntry reports whether `fileName` falls inside the `files`
+// scope of at least one non-IgnoreOnly entry. An entry without an explicit
+// `files` list matches every file by definition (eslint flat-config
+// semantics), so a config with any unrestricted non-IgnoreOnly entry returns
+// true for every file. The format command treats a `false` result the same
+// way the engine does: no entry contributes rules, so the blanket
+// format-rule upgrade must be skipped.
+//
+// Base cases:
+//
+//   - Empty entries slice: returns `true`. A store with no entries cannot
+//     skip a file by scope (the engine has nothing to walk), so format
+//     mode must be allowed to apply its default upgrade. Matching engine
+//     behavior at `ConfigStore.ResolveRules` for the same input
+//     (`Ignored = false`, empty rule map).
+//   - All entries are IgnoreOnly: returns `false`. No non-IgnoreOnly
+//     entry contributes a `files` scope, so the file is out-of-scope by
+//     construction.
+//   - Inner resolver is not a *ConfigStore: returns `true` (conservative
+//     default). The `files` concept is store-specific; an in-process
+//     custom resolver that does not surface a scope cannot have its
+//     rule-eligibility reasoned about from the outside, so the format
+//     upgrade applies the same as it does for an entry without `files`.
+func (r formatCommandResolver) fileMatchesAnyEntry(fileName string) bool {
+  store, ok := r.inner.(*ConfigStore)
+  if !ok || store == nil {
+    return true
+  }
+  if len(store.entries) == 0 {
+    return true
+  }
+  for _, entry := range store.entries {
+    if entry.IgnoreOnly {
+      continue
+    }
+    if entry.matchesFile(fileName) {
+      return true
+    }
+  }
+  return false
+}
+
 // ActiveRuleNames implements RuleResolver. Returns the union of the inner
 // resolver's active rules and every format-option rule that is registered.
 func (r formatCommandResolver) ActiveRuleNames() []string {

package/linthost/host.go

@@ -14,6 +14,7 @@ import (
   "errors"
   "fmt"
   "path/filepath"
+  "strings"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
   "github.com/microsoft/typescript-go/shim/bundled"
@@ -39,10 +40,25 @@ type loadProgramOptions struct {
   forceEmit   bool
   forceNoEmit bool
   outDir      string
+  // needsRuleChecker asks loadProgram to pin the checker pool and acquire the
+  // checker that type-aware lint rules receive through Context.Checker.
+  needsRuleChecker bool
+  // singleThreaded mirrors `tsgo --singleThreaded`: one checker, serial
+  // parse/check/emit.
+  singleThreaded bool
+  // checkers mirrors `tsgo --checkers`: type-checker pool size. Zero leaves
+  // TypeScript-Go's default; ignored when singleThreaded is set.
+  checkers int
+  // tsgoArgs carries tsgo CLI flags the `ttsc` launcher forwarded (`--strict`,
+  // `--target es2020`, …). They are parsed through TypeScript-Go's own
+  // command-line parser into a CompilerOptions overlay that wins over the
+  // tsconfig, exactly as tsgo's CLI merges them.
+  tsgoArgs []string
 }
 
-// loadProgram parses the given tsconfig, builds a Program, and acquires a
-// type checker. Mirrors the canonical bootstrap pattern from
+// loadProgram parses the given tsconfig and builds a Program. When
+// needsRuleChecker is set, it also acquires a type checker for lint rules.
+// Mirrors the canonical bootstrap pattern from
 // `03-tsgo.md` — the only ttsc-specific bit is that `forceEmit`/
 // `forceNoEmit`/`outDir` overrides are merged into the parsed config
 // before the program is created so `--noEmit` and friends behave like
@@ -63,9 +79,14 @@ func loadProgram(cwd, tsconfigPath string, options loadProgramOptions) (*program
   fs := bundled.WrapFS(cachedvfs.From(osvfs.FS()))
   host := shimcompiler.NewCompilerHost(cwd, fs, bundled.LibPath(), nil, nil)
 
+  cliOptions, cliDiags := parseTsgoArgs(options.tsgoArgs, host)
+  if len(cliDiags) > 0 {
+    return nil, cliDiags, nil
+  }
+
   parsed, parseDiags := tsoptions.GetParsedCommandLineOfConfigFile(
     resolved,
-    &shimcore.CompilerOptions{},
+    cliOptions,
     nil,
     host,
     nil,
@@ -88,17 +109,34 @@ func loadProgram(cwd, tsconfigPath string, options loadProgramOptions) (*program
   if options.outDir != "" {
     overrideOutDir(cwd, parsed, options.outDir)
   }
+  applyThreading(parsed, options.singleThreaded, options.checkers)
+  if options.needsRuleChecker {
+    forceSingleChecker(parsed)
+  }
 
+  // SingleThreaded is left unset so the program keeps TypeScript-Go's parallel
+  // source parsing and parallel emit. For type-aware lint rules, the checker
+  // pool is pinned to a single checker (see forceSingleChecker): the lint
+  // engine walks files serially against the one checker GetTypeChecker hands
+  // back, and rules ask that checker to resolve types in nodes drawn from every
+  // source file. TypeScript-Go's multi-checker pool affinitizes each file to a
+  // different checker and forbids mixing types across them, so a type whose
+  // declarations span files on different checkers (e.g. a circular
+  // indexed-access alias) resolves to `any` on the borrowed checker. AST-only
+  // lint rules do not receive a checker, so they keep the user's checker pool.
   tsProgram := shimcompiler.NewProgram(shimcompiler.ProgramOptions{
     Config:                      parsed,
-    SingleThreaded:              shimcore.TSTrue,
     Host:                        host,
     UseSourceOfProjectReference: true,
   })
   if tsProgram == nil {
     return nil, nil, errors.New("compiler.NewProgram returned nil")
   }
-  checker, release := tsProgram.GetTypeChecker(context.Background())
+  var checker *shimchecker.Checker
+  var release func()
+  if options.needsRuleChecker {
+    checker, release = tsProgram.GetTypeChecker(context.Background())
+  }
   return &program{
     cwd:            cwd,
     tsProgram:      tsProgram,
@@ -120,12 +158,19 @@ func (p *program) close() {
   }
 }
 
-// userSourceFiles returns the program's user-authored source files
-// (declaration files filtered out — those belong to library typings).
+// userSourceFiles returns the tsconfig-selected source files the lint engine
+// owns. The tsconfig file list is the boundary: imported libraries, generated
+// output, and JSON modules may still appear in Program.SourceFiles(), but lint
+// and format should not walk them unless the project selected them as TS/JS
+// source roots.
 func (p *program) userSourceFiles() []*shimast.SourceFile {
+  roots := p.userSourceFileNames()
   out := make([]*shimast.SourceFile, 0)
   for _, f := range p.tsProgram.SourceFiles() {
-    if f == nil || f.IsDeclarationFile {
+    if f == nil {
+      continue
+    }
+    if _, ok := roots[canonicalProjectPath(p.cwd, f.FileName())]; !ok {
       continue
     }
     out = append(out, f)
@@ -133,6 +178,35 @@ func (p *program) userSourceFiles() []*shimast.SourceFile {
   return out
 }
 
+func (p *program) userSourceFileNames() map[string]struct{} {
+  out := make(map[string]struct{})
+  if p == nil || p.parsed == nil || p.parsed.ParsedConfig == nil {
+    return out
+  }
+  for _, fileName := range p.parsed.ParsedConfig.FileNames {
+    if isLintSourceFileName(fileName) {
+      out[canonicalProjectPath(p.cwd, fileName)] = struct{}{}
+    }
+  }
+  return out
+}
+
+func canonicalProjectPath(cwd, fileName string) string {
+  if !filepath.IsAbs(fileName) {
+    fileName = filepath.Join(cwd, fileName)
+  }
+  return filepath.ToSlash(filepath.Clean(fileName))
+}
+
+func isLintSourceFileName(fileName string) bool {
+  switch strings.ToLower(filepath.Ext(fileName)) {
+  case ".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs":
+    return true
+  default:
+    return false
+  }
+}
+
 // programDiagnostics returns the bind + semantic diagnostics for the
 // loaded program. Same surface tsgo's CLI prints when you run a regular
 // `tsgo --noEmit`.
@@ -185,6 +259,68 @@ func forceNoEmit(parsed *tsoptions.ParsedCommandLine) {
   parsed.ParsedConfig.CompilerOptions.NoEmit = shimcore.TSTrue
 }
 
+// parseTsgoArgs runs forwarded tsgo CLI flags through TypeScript-Go's own
+// command-line parser, yielding a CompilerOptions overlay loadProgram merges
+// over the tsconfig — so a flag like `ttsc --strict` reaches the in-process
+// lint program even though @ttsc/lint never shells out to `tsgo`. Returns an
+// empty (non-nil) options value when there are no forwarded flags.
+func parseTsgoArgs(args []string, host shimcompiler.CompilerHost) (*shimcore.CompilerOptions, []*shimast.Diagnostic) {
+  if len(args) == 0 {
+    return &shimcore.CompilerOptions{}, nil
+  }
+  cli := tsoptions.ParseCommandLine(args, host)
+  if cli == nil {
+    return &shimcore.CompilerOptions{}, nil
+  }
+  if len(cli.Errors) > 0 {
+    return nil, cli.Errors
+  }
+  return cli.CompilerOptions(), nil
+}
+
+// applyThreading forwards the --singleThreaded / --checkers knobs onto the
+// parsed compiler options. ttsc mirrors tsgo here: the values land in
+// CompilerOptions, and both Program.SingleThreaded() and the checker pool read
+// them from there. SingleThreaded wins over Checkers, matching the pool.
+//
+// When a type-aware lint rule is active, loadProgram calls forceSingleChecker
+// afterwards, so a `--checkers N` greater than 1 is recorded here and then
+// clamped back to a single checker. AST-only lint runs keep the recorded
+// checker count. `--singleThreaded` still takes full effect.
+func applyThreading(parsed *tsoptions.ParsedCommandLine, singleThreaded bool, checkers int) {
+  if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
+    return
+  }
+  options := parsed.ParsedConfig.CompilerOptions
+  if singleThreaded {
+    options.SingleThreaded = shimcore.TSTrue
+  }
+  if checkers > 0 {
+    n := checkers
+    options.Checkers = &n
+  }
+}
+
+// forceSingleChecker pins the TypeScript-Go checker pool to a single checker.
+//
+// The lint engine walks the program serially and obtains types through the
+// single checker GetTypeChecker hands back. Rules query types on nodes from
+// arbitrary source files, so the checker must be the same one that checked
+// every file. A pool of size > 1 affinitizes files to distinct checkers;
+// resolving a type whose declarations cross that boundary yields `any`.
+// Parallel parsing and emit are unaffected — they do not consult the count.
+func forceSingleChecker(parsed *tsoptions.ParsedCommandLine) {
+  if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
+    return
+  }
+  options := parsed.ParsedConfig.CompilerOptions
+  if options.SingleThreaded == shimcore.TSTrue {
+    return
+  }
+  one := 1
+  options.Checkers = &one
+}
+
 // overrideOutDir replaces the parsed config's OutDir with `outDir`.
 // Relative outDir values are resolved against `cwd`; absolute paths are
 // used as-is. Paths are converted to forward slashes for tsgo

package/linthost/print_dispatch.go

@@ -9,10 +9,10 @@ import (
 //
 // The dispatcher is the bridge between the TypeScript-Go AST and the
 // printer engine. It walks one node at a time and emits a Doc tree
-// shaped to that node's grammar. Coverage is intentionally partial in
-// v1; the verbatim fallback below guarantees that an un-handled node
-// kind contributes its original source bytes verbatim, so the printer
-// can be wired up to a rule without breaking files that happen to use
+// shaped to that node's grammar. Coverage is intentionally partial;
+// the verbatim fallback below guarantees that an un-handled node kind
+// contributes its original source bytes verbatim, so the printer can
+// be wired up to a rule without breaking files that happen to use
 // shapes the per-node printers don't yet understand.
 //
 // The price of verbatim fallback is that reflow stops at the boundary
@@ -20,6 +20,19 @@ import (
 // dispatcher doesn't recognize stays long. That trade-off is preferable
 // to corrupting unfamiliar shapes — extension over time turns each
 // verbatim hop into a real reflow.
+//
+// Coverage signal. A verbatim slice keeps its *original* source column.
+// When an un-handled node spans multiple lines, its interior lines are
+// frozen at the columns the user wrote while the enclosing reflow
+// re-indents everything around it — the result is inconsistently
+// indented, corrupt output. To prevent that, every printer reports a
+// `covered` boolean alongside its Doc: `true` means the whole printed
+// subtree is reflow-safe (no multi-line verbatim node), `false` means a
+// multi-line verbatim node is buried inside. The format/print-width
+// rule abstains entirely when `covered` is false, so `ttsc format`
+// either reflows correctly or leaves the bytes untouched — it never
+// emits the half-reflowed shape. Single-line verbatim is always safe:
+// a node confined to one source line has no interior column to freeze.
 
 // PrintContext bundles the per-file inputs every per-node printer
 // needs. The dispatcher constructs one per top-level reflow and threads
@@ -42,46 +55,96 @@ func NewPrintContext(file *shimast.SourceFile, opts PrintOptions) *PrintContext
 
 // PrintNode is the dispatcher entry. It picks a per-node printer based
 // on `node.Kind` and falls back to the verbatim source slice when no
-// printer is registered. Returns the printed Doc and a boolean
-// indicating whether the dispatch actually reformatted the node. The
-// boolean is currently only used by the format/print-width rule, which
-// skips edit emission when every printable child fell back to
-// verbatim (no behavior change, no diagnostic).
+// printer is registered. Returns the printed Doc and a `covered`
+// boolean: `true` when the whole printed subtree is reflow-safe,
+// `false` when a multi-line verbatim node is buried inside it.
+//
+// The format/print-width rule consults `covered` to decide whether to
+// emit an edit at all — see the coverage-signal note at the top of this
+// file. A `false` reading is a hard abstain, not a soft hint.
 func PrintNode(ctx *PrintContext, node *shimast.Node) (Doc, bool) {
   if node == nil {
-    return Doc{}, false
+    return Doc{}, true
   }
-  if doc, reformatted, ok := dispatchNode(ctx, node); ok {
-    return doc, reformatted
+  if doc, covered, ok := dispatchNode(ctx, node); ok {
+    return doc, covered
   }
-  return verbatim(ctx, node), false
+  return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
 }
 
 // dispatchNode is the per-kind switch. Each branch returns
-// (doc, reformatted, true) when it produces a structured Doc, or
+// (doc, covered, true) when it produces a structured Doc, or
 // (zero, false, false) to let the caller fall back to verbatim. The
-// reformatted flag is true when the per-node printer asserts the
-// result may differ from the original bytes.
+// `covered` flag is `true` only when the per-node printer guarantees
+// the whole subtree it produced is free of multi-line verbatim slices.
 func dispatchNode(ctx *PrintContext, node *shimast.Node) (Doc, bool, bool) {
   switch node.Kind {
   case shimast.KindObjectLiteralExpression:
-    return printObjectLiteral(ctx, node), true, true
+    doc, covered := printObjectLiteral(ctx, node)
+    return doc, covered, true
   case shimast.KindArrayLiteralExpression:
-    return printArrayLiteral(ctx, node), true, true
+    doc, covered := printArrayLiteral(ctx, node)
+    return doc, covered, true
   case shimast.KindCallExpression:
-    return printCallExpression(ctx, node), true, true
+    doc, covered := printCallExpression(ctx, node)
+    return doc, covered, true
   case shimast.KindNewExpression:
-    return printNewExpression(ctx, node), true, true
+    doc, covered := printNewExpression(ctx, node)
+    return doc, covered, true
   case shimast.KindNamedImports:
-    return printNamedImports(ctx, node), true, true
+    doc, covered := printNamedImports(ctx, node)
+    return doc, covered, true
   case shimast.KindNamedExports:
-    return printNamedExports(ctx, node), true, true
+    doc, covered := printNamedExports(ctx, node)
+    return doc, covered, true
   case shimast.KindImportDeclaration:
-    return printImportDeclaration(ctx, node), true, true
+    doc, covered := printImportDeclaration(ctx, node)
+    return doc, covered, true
+  case shimast.KindArrowFunction:
+    doc, covered := printArrowFunction(ctx, node)
+    return doc, covered, true
+  case shimast.KindFunctionExpression:
+    doc, covered := printFunctionExpression(ctx, node)
+    return doc, covered, true
+  case shimast.KindParenthesizedExpression:
+    doc, covered := printParenthesizedExpression(ctx, node)
+    return doc, covered, true
+  case shimast.KindBlock:
+    doc, covered := printBlock(ctx, node)
+    return doc, covered, true
+  case shimast.KindExpressionStatement:
+    doc, covered := printExpressionStatement(ctx, node)
+    return doc, covered, true
+  case shimast.KindReturnStatement:
+    doc, covered := printReturnStatement(ctx, node)
+    return doc, covered, true
   }
   return Doc{}, false, false
 }
 
+// nodeSpansMultipleLines reports whether `node`'s trivia-trimmed source
+// range crosses a newline. A verbatim slice that stays on one line is
+// always reflow-safe — there is no interior column for the enclosing
+// re-indent to leave stranded — so the dispatcher treats single-line
+// verbatim as `covered`. A multi-line verbatim node freezes its
+// interior columns and is reported uncovered.
+func nodeSpansMultipleLines(ctx *PrintContext, node *shimast.Node) bool {
+  if node == nil {
+    return false
+  }
+  start := shimscanner.SkipTrivia(ctx.Source, node.Pos())
+  end := node.End()
+  if start < 0 || end < start || end > len(ctx.Source) {
+    return false
+  }
+  for i := start; i < end; i++ {
+    if ctx.Source[i] == '\n' {
+      return true
+    }
+  }
+  return false
+}
+
 // verbatim returns the original source bytes for `node`, leading trivia
 // trimmed. Use this whenever a printer cannot fully cover a node — the
 // surrounding doc tree still flows, but the verbatim slice carries
@@ -118,3 +181,38 @@ func (ctx *PrintContext) indentUnit() int {
   }
   return 2
 }
+
+// trailingCommaMode normalizes ctx.Opts.TrailingComma to one of "all",
+// "es5", or "none". An empty value — the zero value for the field —
+// reads as "all" to keep pre-existing callers and tests that built a
+// PrintOptions{} without setting the field on Prettier's default
+// behavior. Any other value also reads as "all"; the config layer
+// rejects unknown strings before they reach the printer (see
+// `expandFormatBlock` in config_format.go), so a stray value here is a
+// programmer error and the safest fallback is the most-commas mode.
+func (ctx *PrintContext) trailingCommaMode() string {
+  switch ctx.Opts.TrailingComma {
+  case "es5", "none":
+    return ctx.Opts.TrailingComma
+  }
+  return "all"
+}
+
+// allowsCallArgumentTrailingComma reports whether a multi-line call /
+// new argument list should emit a trailing comma under the current
+// trailingComma setting. Trailing commas in call arguments arrived in
+// ES2017, so Prettier's "es5" mode excludes them just like "none" does;
+// only "all" keeps them. Parameter lists are not printed by the
+// dispatcher today, but the same rule applies to them when they are.
+func (ctx *PrintContext) allowsCallArgumentTrailingComma() bool {
+  return ctx.trailingCommaMode() == "all"
+}
+
+// allowsEs5TrailingComma reports whether a multi-line ES5-permitted
+// list — arrays, objects, named imports / exports — should emit a
+// trailing comma. Only "none" suppresses the comma here; "es5" and
+// "all" both keep it because ES5 has accepted trailing commas in these
+// positions since the language's inception.
+func (ctx *PrintContext) allowsEs5TrailingComma() bool {
+  return ctx.trailingCommaMode() != "none"
+}

package/linthost/print_doc.go

@@ -52,6 +52,9 @@ package linthost
 //   - DocLineSuffix queues output until the next hardline/softline that
 //     actually breaks; used for trailing line comments that must stick
 //     to their source line.
+//   - DocConditionalGroup offers an ordered list of layout options; the
+//     engine renders the first whose first line fits the width budget
+//     and uses the last option as the unconditional fallback.
 //
 // The doc tree is built by helper constructors (Text, Line, Group, …)
 // below. Constructors take their children as variadic or slice
@@ -75,6 +78,7 @@ const (
   docIfBreak
   docConcat
   docLineSuffix
+  docConditionalGroup
 )
 
 // Doc is one node in the layout tree. Only the fields relevant to the
@@ -93,6 +97,11 @@ type Doc struct {
   Text     string
   Children []Doc
   Width    int
+  // Break, meaningful only on a docGroup, forces the group to render
+  // broken regardless of whether its flat form would fit. A
+  // ConditionalGroup option uses it to commit its last argument — a
+  // hugged object literal — to the multi-line shape.
+  Break bool
   // IfBreak pairs: BreakChild stored in Children[0], FlatChild in Children[1].
 }
 
@@ -116,6 +125,16 @@ func Literalline() Doc { return Doc{Kind: docLiteralline} }
 // concatenated.
 func Group(parts ...Doc) Doc { return Doc{Kind: docGroup, Children: parts} }
 
+// ConditionalGroup picks the first option whose first line fits the
+// remaining width budget, falling back to the last option when none
+// fit. Where Group makes a single flat-or-break decision, a
+// ConditionalGroup lets a printer offer several distinct shapes — a
+// call's hugged vs. exploded argument list — and have the engine choose
+// between them. The last option must always be a safe fallback.
+func ConditionalGroup(options ...Doc) Doc {
+  return Doc{Kind: docConditionalGroup, Children: options}
+}
+
 // Indent adds `width` columns of indentation to every newline emitted by
 // the child doc. Nesting composes.
 func Indent(width int, parts ...Doc) Doc {