@ttsc/lint 0.14.0-dev.20260529.2 → 0.14.1

package/linthost/format.go

@@ -5,6 +5,7 @@ import (
   "fmt"
   "os"
   "sort"
+  "sync"
 )
 
 // maxFormatPasses bounds the format cascade for the same reason
@@ -36,12 +37,16 @@ func RunFormat(args []string) int {
 // runFormat is the internal implementation of RunFormat. It drives the
 // cascade loop and applies format-rule edits until convergence.
 func runFormat(opts *subcommandOpts) int {
-  rules, err := loadRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
+  rules, err := loadFormatRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
+  if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return 2
+  }
+  resolver, err := newFormatCommandResolver(rules, opts.cwd, "")
   if err != nil {
     fmt.Fprintln(os.Stderr, err)
     return 2
   }
-  resolver := formatCommandResolver{inner: rules}
   engine := NewEngineWithResolver(resolver)
   engine.SetSerial(opts.singleThreaded)
   needsRuleChecker := engine.NeedsTypeChecker()
@@ -100,6 +105,110 @@ func runFormat(opts *subcommandOpts) int {
 // without requiring explicit rule declarations in the project config.
 type formatCommandResolver struct {
   inner RuleResolver
+  // ruleNames memoizes formatOptionRuleNames. The resolver's option set is
+  // immutable for the whole run, so the sorted format-rule slice is computed
+  // once and reused across ResolveRules (per file per pass), ActiveRuleNames,
+  // and EnabledRuleConfig. The field is a pointer so a nil zero value stays
+  // valid: callers that build formatCommandResolver{inner: ...} without it
+  // (tests, lsp) fall back to direct computation, and copying the struct by
+  // value (it is stored in the engine's RuleResolver interface and passed
+  // around as a value) shares the same underlying cache rather than copying a
+  // sync.Once lock.
+  ruleNames *formatRuleNamesCache
+  // entryDecisions memoizes the per-fileName ignored/matches decision that
+  // ResolveRules derives from fileIsIgnoredByEntry and fileMatchesAnyEntry.
+  // Both walk store.entries with glob matching and are recomputed identically
+  // for the same fileName on every format pass, so the result is cached once
+  // per file and reused. The field is a pointer (a *sync.Map) so the nil zero
+  // value stays valid for construction sites that omit it, and copying the
+  // resolver by value shares the same underlying map. sync.Map handles the
+  // engine's concurrent per-file ResolveRules calls without an extra lock.
+  entryDecisions *sync.Map
+  // defaultOptions holds the always-on format rules' options (from
+  // expandFormatBlock) to apply when the project config declares no `format`
+  // block — no block in lint.config.*, or no config file at all. nil when a
+  // format block is configured, so that block wins entirely. Keys are canonical
+  // format rule names; values are the marshaled options blob each rule decodes,
+  // exactly as a configured block would supply them.
+  defaultOptions RuleOptionsMap
+}
+
+// newFormatCommandResolver wraps inner for the format command / LSP buffer path.
+// When inner declares no `format` rules (no `format` block in lint.config.*, or
+// no config file at all) it loads the documented default format rules, letting
+// the nearest .vscode/settings.json under startDir override the indentation/eol
+// keys. language scopes the settings.json language section ("" skips sections,
+// e.g. the project-wide CLI path). A configured `format` block leaves
+// defaultOptions nil so the block stays authoritative.
+func newFormatCommandResolver(inner RuleResolver, startDir string, language string) (formatCommandResolver, error) {
+  r := formatCommandResolver{
+    inner:          inner,
+    ruleNames:      &formatRuleNamesCache{},
+    entryDecisions: &sync.Map{},
+  }
+  if !hasInnerFormatRules(inner) {
+    opts, err := defaultFormatOptions(editorFormatOverrides(startDir, language))
+    if err != nil {
+      return formatCommandResolver{}, err
+    }
+    r.defaultOptions = opts
+  }
+  return r, nil
+}
+
+// hasInnerFormatRules reports whether inner already carries format-rule options,
+// i.e. the project configured a `format` block (format/* options only ever come
+// from a block). When true the block is authoritative and defaults are skipped.
+func hasInnerFormatRules(inner RuleResolver) bool {
+  for name := range resolverOptions(inner) {
+    if isRegisteredFormatRule(name) {
+      return true
+    }
+  }
+  return false
+}
+
+// defaultFormatOptions expands the always-on default format ruleset (optionally
+// overridden by editor settings) into the per-rule options map the resolver
+// returns through RuleOptions. It reuses expandFormatBlock so the defaults are
+// produced by exactly the same code path as a user-authored format block.
+func defaultFormatOptions(overrides map[string]any) (RuleOptionsMap, error) {
+  expanded, err := expandFormatBlock(overrides)
+  if err != nil {
+    return nil, err
+  }
+  out := make(RuleOptionsMap, len(expanded))
+  for name, entry := range expanded {
+    tuple, ok := entry.([]any)
+    if !ok || len(tuple) < 2 {
+      continue
+    }
+    options, ok := tuple[1].(map[string]any)
+    if !ok {
+      continue
+    }
+    raw, err := json.Marshal(options)
+    if err != nil {
+      return nil, err
+    }
+    out[name] = raw
+  }
+  return out, nil
+}
+
+// formatRuleNamesCache lazily computes and stores the sorted format-rule name
+// slice for a resolver. sync.Once guarantees a single computation even when
+// ResolveRules runs concurrently across files in the engine's parallel walk.
+type formatRuleNamesCache struct {
+  once  sync.Once
+  names []string
+}
+
+// formatEntryDecision is the cached per-fileName outcome of the two entry-scope
+// checks ResolveRules runs before applying its format-rule upgrade.
+type formatEntryDecision struct {
+  ignoredByEntry bool
+  matchesEntry   bool
 }
 
 // ResolveRules implements RuleResolver. It delegates to the inner resolver
@@ -127,10 +236,11 @@ func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig
   if resolved.Ignored {
     return resolved
   }
-  if r.fileIsIgnoredByEntry(fileName) {
+  decision := r.entryDecision(fileName)
+  if decision.ignoredByEntry {
     return resolved
   }
-  if !r.fileMatchesAnyEntry(fileName) {
+  if !decision.matchesEntry {
     return resolved
   }
   if resolved.Rules == nil {
@@ -144,6 +254,36 @@ func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig
   return resolved
 }
 
+// entryDecision returns the per-fileName ignored/matches outcome that
+// ResolveRules needs, computing it from fileIsIgnoredByEntry and
+// fileMatchesAnyEntry on first use and reusing it on later passes. When the
+// memo is absent (a resolver built without entryDecisions, e.g. in tests or
+// lsp) it computes the decision directly so behavior is identical, just
+// uncached.
+func (r formatCommandResolver) entryDecision(fileName string) formatEntryDecision {
+  if r.entryDecisions == nil {
+    return r.computeEntryDecision(fileName)
+  }
+  if cached, ok := r.entryDecisions.Load(fileName); ok {
+    return cached.(formatEntryDecision)
+  }
+  decision := r.computeEntryDecision(fileName)
+  // LoadOrStore keeps the first writer's value so concurrent passes over the
+  // same file agree; the decision is a pure function of fileName, so either
+  // value is correct.
+  actual, _ := r.entryDecisions.LoadOrStore(fileName, decision)
+  return actual.(formatEntryDecision)
+}
+
+// computeEntryDecision runs the two uncached entry-scope checks behind
+// entryDecision.
+func (r formatCommandResolver) computeEntryDecision(fileName string) formatEntryDecision {
+  return formatEntryDecision{
+    ignoredByEntry: r.fileIsIgnoredByEntry(fileName),
+    matchesEntry:   r.fileMatchesAnyEntry(fileName),
+  }
+}
+
 // 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
@@ -154,19 +294,34 @@ func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig
 // 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 {
+  matched, _ := r.anyNonIgnoreEntry(func(entry *ConfigEntry) bool {
+    return entry.matchesIgnores(fileName)
+  })
+  return matched
+}
+
+// anyNonIgnoreEntry resolves the inner resolver to its concrete *ConfigStore
+// once and reports whether any non-IgnoreOnly entry satisfies `pred`. The
+// second return value is false when the inner resolver is not a *ConfigStore
+// (or is a nil one), letting each caller pick its own non-store default. This
+// collapses the shared store-resolution and entry-walk that fileIsIgnoredByEntry
+// and fileMatchesAnyEntry would otherwise duplicate; the per-caller default and
+// the empty-entries base case stay in the callers where they differ.
+func (r formatCommandResolver) anyNonIgnoreEntry(pred func(*ConfigEntry) bool) (matched bool, hasStore bool) {
   store, ok := r.inner.(*ConfigStore)
   if !ok || store == nil {
-    return false
+    return false, false
   }
-  for _, entry := range store.entries {
+  for i := range store.entries {
+    entry := &store.entries[i]
     if entry.IgnoreOnly {
       continue
     }
-    if entry.matchesIgnores(fileName) {
-      return true
+    if pred(entry) {
+      return true, true
     }
   }
-  return false
+  return false, true
 }
 
 // fileMatchesAnyEntry reports whether `fileName` falls inside the `files`
@@ -193,22 +348,32 @@ func (r formatCommandResolver) fileIsIgnoredByEntry(fileName string) bool {
 //     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 {
+  matched, hasStore := r.anyNonIgnoreEntry(func(entry *ConfigEntry) bool {
+    return entry.matchesFile(fileName)
+  })
+  if !hasStore {
+    // Not a *ConfigStore: conservative default, see the doc comment above.
     return true
   }
-  if len(store.entries) == 0 {
+  // A store with no entries (or only IgnoreOnly ones that the walk skipped)
+  // produces matched == false; an empty entries slice must still return true
+  // so format mode applies its default upgrade, matching ConfigStore behavior.
+  // The all-IgnoreOnly case is distinguished by a non-empty entries slice.
+  if !matched && len(r.storeEntries()) == 0 {
     return true
   }
-  for _, entry := range store.entries {
-    if entry.IgnoreOnly {
-      continue
-    }
-    if entry.matchesFile(fileName) {
-      return true
-    }
+  return matched
+}
+
+// storeEntries returns the inner resolver's config entries, or nil when the
+// inner resolver is not a *ConfigStore. Used by fileMatchesAnyEntry to tell the
+// empty-entries base case (return true) apart from the all-IgnoreOnly case
+// (return false) after anyNonIgnoreEntry reports no match.
+func (r formatCommandResolver) storeEntries() []ConfigEntry {
+  if store, ok := r.inner.(*ConfigStore); ok && store != nil {
+    return store.entries
   }
-  return false
+  return nil
 }
 
 // ActiveRuleNames implements RuleResolver. Returns the union of the inner
@@ -239,25 +404,57 @@ func (r formatCommandResolver) EnabledRuleConfig() RuleConfig {
   return enabled
 }
 
-// RuleOptions implements RuleResolver by delegating directly to the inner resolver.
+// RuleOptions implements RuleResolver. It prefers the inner resolver's options
+// and falls back to the default format options for rules the project did not
+// configure, so the default always-on rules receive their (possibly
+// settings.json-overridden) options.
 func (r formatCommandResolver) RuleOptions(name string) json.RawMessage {
-  return r.inner.RuleOptions(name)
+  if raw := r.inner.RuleOptions(name); len(raw) > 0 {
+    return raw
+  }
+  if r.defaultOptions != nil {
+    if raw, ok := r.defaultOptions[name]; ok {
+      return raw
+    }
+  }
+  return nil
 }
 
 // formatOptionRuleNames returns the sorted list of rule names from the inner
 // resolver's options that are registered as format rules. These are the rules
 // that formatCommandResolver promotes from off to warn.
 func (r formatCommandResolver) formatOptionRuleNames() []string {
-  options := resolverOptions(r.inner)
-  if len(options) == 0 {
-    return nil
+  if r.ruleNames == nil {
+    // Nil cache (a resolver built without the memo, e.g. in tests or lsp):
+    // compute directly. Construction sites that want the memo set ruleNames.
+    return r.computeFormatOptionRuleNames()
   }
+  r.ruleNames.once.Do(func() {
+    r.ruleNames.names = r.computeFormatOptionRuleNames()
+  })
+  return r.ruleNames.names
+}
+
+// computeFormatOptionRuleNames does the uncached work behind
+// formatOptionRuleNames: collect the inner resolver's option names that are
+// registered format rules, sorted. The result order is stable (sorted) so
+// memoizing it does not change any caller's observed ordering.
+func (r formatCommandResolver) computeFormatOptionRuleNames() []string {
+  options := resolverOptions(r.inner)
   names := make([]string, 0, len(options))
   for name := range options {
     if isRegisteredFormatRule(name) {
       names = append(names, name)
     }
   }
+  if len(names) == 0 {
+    // No `format` block configured: fall back to the default always-on set so
+    // the formatter still runs, with documented defaults plus any
+    // .vscode/settings.json overrides folded into defaultOptions.
+    for name := range r.defaultOptions {
+      names = append(names, name)
+    }
+  }
   sort.Strings(names)
   return names
 }

package/linthost/format_editor_settings.go

@@ -0,0 +1,262 @@
+package linthost
+
+import (
+  "encoding/json"
+  "errors"
+  "os"
+  "path/filepath"
+  "strings"
+)
+
+// errNoLintConfigFile is the sentinel LoadConfigResolver wraps when no
+// lint.config.*/ttsc-lint.config.* file is found. The format paths
+// (loadFormatRules) treat it as "use defaults" rather than a hard error, so
+// formatOnSave / `ttsc format` work even when a project ships no lint config.
+var errNoLintConfigFile = errors.New("@ttsc/lint: no lint.config.* or ttsc-lint.config.* file found")
+
+// loadFormatRules loads the rule resolver for the format paths, tolerating a
+// missing lint config. The lint check/build path requires a config and surfaces
+// the error, but formatting falls back to the documented defaults: a project
+// with no lint.config.* still formats on save. Any other load error (a broken
+// or malformed config) is propagated unchanged.
+func loadFormatRules(pluginsJSON, cwd, tsconfigPath string) (RuleResolver, error) {
+  rules, err := loadRules(pluginsJSON, cwd, tsconfigPath)
+  if err != nil {
+    if errors.Is(err, errNoLintConfigFile) {
+      return RuleConfig{}, nil
+    }
+    return nil, err
+  }
+  return rules, nil
+}
+
+// editorFormatOverrides reads the nearest ancestor `.vscode/settings.json`
+// relative to startDir and maps the editor's formatting settings onto the
+// `format` block keys the default formatter understands. Only keys the user
+// explicitly set are returned, so any setting that is absent falls through to
+// the documented format defaults.
+//
+// This is consulted only when lint.config.* configures no `format` block: a
+// configured format block always wins and never reaches this path. Within
+// settings.json a language-specific section matching `language` (e.g.
+// "[typescript]" or a combined "[javascript][typescript][json]") wins over the
+// top-level keys, mirroring VS Code's own resolution. Pass language="" to skip
+// language sections (e.g. the project-wide `ttsc format` CLI path).
+//
+// Mapping (values use JSON types so they parse identically to a real `format`
+// block, where numbers decode as float64):
+//
+//   - editor.tabSize      -> tabWidth   (number)
+//   - editor.insertSpaces -> useTabs    (bool, inverted)
+//   - files.eol           -> endOfLine  ("\n" -> "lf", "\r\n" -> "crlf")
+//
+// editor.detectIndentation auto-detection is intentionally not emulated; the
+// explicit tabSize/insertSpaces are honored as written. A relative startDir is
+// ignored (returns no overrides) so unit tests that format from a bare cwd stay
+// hermetic and never walk up into a real workspace's .vscode directory.
+func editorFormatOverrides(startDir string, language string) map[string]any {
+  out := map[string]any{}
+  if !filepath.IsAbs(startDir) {
+    return out
+  }
+  settings, ok := loadNearestVSCodeSettings(startDir)
+  if !ok {
+    return out
+  }
+  // Top-level keys first, then language-specific sections override them.
+  applyEditorSettings(out, settings)
+  if language != "" {
+    for key, value := range settings {
+      if !sectionMatchesLanguage(key, language) {
+        continue
+      }
+      if section, ok := value.(map[string]any); ok {
+        applyEditorSettings(out, section)
+      }
+    }
+  }
+  return out
+}
+
+// applyEditorSettings reads the recognized editor keys from a settings object
+// (either the top-level document or a language-specific section) and writes the
+// corresponding format-block overrides into out, overwriting earlier values so
+// callers can layer language sections over the top-level defaults.
+func applyEditorSettings(out map[string]any, settings map[string]any) {
+  if v, ok := settings["editor.tabSize"]; ok {
+    if f, ok := v.(float64); ok {
+      out["tabWidth"] = f
+    }
+  }
+  if v, ok := settings["editor.insertSpaces"]; ok {
+    if b, ok := v.(bool); ok {
+      out["useTabs"] = !b
+    }
+  }
+  if v, ok := settings["files.eol"]; ok {
+    if s, ok := v.(string); ok {
+      switch s {
+      case "\n":
+        out["endOfLine"] = "lf"
+      case "\r\n":
+        out["endOfLine"] = "crlf"
+      }
+    }
+  }
+}
+
+// sectionMatchesLanguage reports whether a settings.json key is a
+// language-specific section header (e.g. "[typescript]" or the combined
+// "[javascript][typescript][json]") that applies to language. An empty
+// language never matches.
+func sectionMatchesLanguage(key string, language string) bool {
+  if language == "" {
+    return false
+  }
+  if !strings.HasPrefix(key, "[") || !strings.HasSuffix(key, "]") {
+    return false
+  }
+  inner := strings.TrimSuffix(strings.TrimPrefix(key, "["), "]")
+  for _, lang := range strings.Split(inner, "][") {
+    if lang == language {
+      return true
+    }
+  }
+  return false
+}
+
+// vscodeLanguageID maps a file extension to the VS Code language identifier
+// used in settings.json language sections. Extensions outside the formatter's
+// supported set return "" so no language section matches.
+func vscodeLanguageID(filePath string) string {
+  switch strings.ToLower(filepath.Ext(filePath)) {
+  case ".ts", ".mts", ".cts":
+    return "typescript"
+  case ".tsx":
+    return "typescriptreact"
+  case ".js", ".mjs", ".cjs":
+    return "javascript"
+  case ".jsx":
+    return "javascriptreact"
+  default:
+    return ""
+  }
+}
+
+// loadNearestVSCodeSettings walks up from startDir looking for a
+// `.vscode/settings.json`, returning the first one found decoded as a JSONC
+// document. It returns ok=false when none exists or the file cannot be parsed,
+// so a broken settings file degrades to the format defaults instead of breaking
+// the formatter.
+func loadNearestVSCodeSettings(startDir string) (map[string]any, bool) {
+  dir := startDir
+  for {
+    candidate := filepath.Join(dir, ".vscode", "settings.json")
+    if data, err := os.ReadFile(candidate); err == nil {
+      var parsed map[string]any
+      if json.Unmarshal(stripJSONC(data), &parsed) == nil {
+        return parsed, true
+      }
+      return nil, false
+    }
+    parent := filepath.Dir(dir)
+    if parent == dir {
+      return nil, false
+    }
+    dir = parent
+  }
+}
+
+// stripJSONC removes `//` line comments, `/* */` block comments, and trailing
+// commas from a JSONC byte slice so encoding/json can parse VS Code's
+// settings.json. It is string-literal aware: comment markers and commas inside
+// string values are preserved.
+func stripJSONC(data []byte) []byte {
+  out := make([]byte, 0, len(data))
+  inString := false
+  escaped := false
+  for i := 0; i < len(data); i++ {
+    c := data[i]
+    if inString {
+      out = append(out, c)
+      if escaped {
+        escaped = false
+        continue
+      }
+      switch c {
+      case '\\':
+        escaped = true
+      case '"':
+        inString = false
+      }
+      continue
+    }
+    switch {
+    case c == '"':
+      inString = true
+      out = append(out, c)
+    case c == '/' && i+1 < len(data) && data[i+1] == '/':
+      for i < len(data) && data[i] != '\n' {
+        i++
+      }
+      if i < len(data) {
+        out = append(out, data[i])
+      }
+    case c == '/' && i+1 < len(data) && data[i+1] == '*':
+      i += 2
+      for i+1 < len(data) && !(data[i] == '*' && data[i+1] == '/') {
+        i++
+      }
+      i++
+    default:
+      out = append(out, c)
+    }
+  }
+  return dropTrailingCommas(out)
+}
+
+// dropTrailingCommas removes a comma that is followed (after optional
+// whitespace) by a closing `}` or `]`, the one JSONC affordance encoding/json
+// rejects. It is string-literal aware so commas inside strings survive.
+func dropTrailingCommas(data []byte) []byte {
+  out := make([]byte, 0, len(data))
+  inString := false
+  escaped := false
+  for i := 0; i < len(data); i++ {
+    c := data[i]
+    if inString {
+      out = append(out, c)
+      if escaped {
+        escaped = false
+        continue
+      }
+      switch c {
+      case '\\':
+        escaped = true
+      case '"':
+        inString = false
+      }
+      continue
+    }
+    if c == '"' {
+      inString = true
+      out = append(out, c)
+      continue
+    }
+    if c == ',' {
+      j := i + 1
+      for j < len(data) && isJSONSpace(data[j]) {
+        j++
+      }
+      if j < len(data) && (data[j] == '}' || data[j] == ']') {
+        continue
+      }
+    }
+    out = append(out, c)
+  }
+  return out
+}
+
+func isJSONSpace(c byte) bool {
+  return c == ' ' || c == '\t' || c == '\n' || c == '\r'
+}

package/linthost/lsp.go

@@ -302,7 +302,7 @@ func findingToLSPDiagnostic(finding *Finding) lspDiagnostic {
     Range:    lspRangeForFinding(finding),
     Severity: lspSeverity(finding.Severity),
     Code:     finding.Rule,
-    Source:   "ttsc/lint",
+    Source:   "@ttsc/lint",
     Message:  finding.Message,
   }
 }
@@ -479,13 +479,17 @@ func lspFormatBuffer(content string, opts *lspCommandOptions) (*lspWorkspaceEdit
     return nil, 0
   }
 
-  rules, err := loadRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
+  rules, err := loadFormatRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
   if err != nil {
     fmt.Fprintln(os.Stderr, err)
     return nil, 2
   }
-  rules = formatCommandResolver{inner: rules}
-  engine := NewEngineWithResolver(rules)
+  resolver, err := newFormatCommandResolver(rules, filepath.Dir(target), vscodeLanguageID(target))
+  if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return nil, 2
+  }
+  engine := NewEngineWithResolver(resolver)
   if engine.NeedsTypeChecker() {
     // A format-class contributor rule (formatContributorAdapter) needs the type
     // checker, which the single-file in-memory parse can't supply. Fall back to

package/linthost/print_dispatch.go

@@ -118,6 +118,9 @@ func dispatchNode(ctx *PrintContext, node *shimast.Node) (Doc, bool, bool) {
   case shimast.KindReturnStatement:
     doc, covered := printReturnStatement(ctx, node)
     return doc, covered, true
+  case shimast.KindConditionalExpression:
+    doc, covered := printConditionalExpression(ctx, node)
+    return doc, covered, true
   }
   return Doc{}, false, false
 }

package/linthost/print_doc.go

@@ -79,6 +79,7 @@ const (
   docConcat
   docLineSuffix
   docConditionalGroup
+  docFill
 )
 
 // Doc is one node in the layout tree. Only the fields relevant to the
@@ -135,6 +136,15 @@ func ConditionalGroup(options ...Doc) Doc {
   return Doc{Kind: docConditionalGroup, Children: options}
 }
 
+// Fill renders an alternating [content, separator, content, separator, …,
+// content] sequence with Wadler/Prettier "fill" semantics: it places as many
+// contents on a line as fit, breaking a separator to a new line only when the
+// next content (with its separator) would overflow. Used for concisely-printed
+// numeric arrays (`[1, 2, 3, … ]` packed several per line), where a plain
+// one-item-per-line break would waste space. `parts` must have odd length
+// (content at even indices, separators at odd).
+func Fill(parts ...Doc) Doc { return Doc{Kind: docFill, Children: parts} }
+
 // Indent adds `width` columns of indentation to every newline emitted by
 // the child doc. Nesting composes.
 func Indent(width int, parts ...Doc) Doc {
@@ -162,6 +172,9 @@ func Concat(parts ...Doc) Doc {
 
 // LineSuffix queues output until the next line break. Used for trailing
 // line comments that must appear after the current source line ends.
+//
+// The payload is expected to be single-line: it is emitted verbatim at the
+// line break and is NOT re-indented across any embedded newlines.
 func LineSuffix(parts ...Doc) Doc {
   return Doc{Kind: docLineSuffix, Children: parts}
 }