@ttsc/lint 0.12.3 → 0.13.0

package/linthost/print_nodes_imports.go

@@ -20,56 +20,70 @@ import (
 // mode, matching Prettier's `bracketSpacing: true` default for import
 // declarations (which is hard-coded; Prettier ignores `bracketSpacing`
 // for imports). Empty named imports `{}` collapse cleanly.
-func printNamedImports(ctx *PrintContext, node *shimast.Node) Doc {
+//
+// The second return value is the `covered` flag: see PrintNode.
+func printNamedImports(ctx *PrintContext, node *shimast.Node) (Doc, bool) {
   if node == nil {
-    return Doc{}
+    return Doc{}, true
   }
   ni := node.AsNamedImports()
   if ni == nil || ni.Elements == nil {
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
   items := make([]Doc, 0, len(ni.Elements.Nodes))
+  covered := true
   for _, spec := range ni.Elements.Nodes {
     if spec == nil {
-      return verbatim(ctx, node)
+      return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
     }
-    doc, _ := PrintNode(ctx, spec)
+    doc, childCovered := PrintNode(ctx, spec)
+    covered = covered && childCovered
     items = append(items, doc)
   }
+  // AddComma honors `format.trailingComma`: named imports are an
+  // ES5-permitted comma position, so "all" and "es5" both keep the
+  // trailing comma; only "none" drops it.
   return printList(ctx, listShape{
     OpenTok:  "{",
     CloseTok: "}",
     Items:    items,
     Space:    true,
-    AddComma: true,
-  })
+    AddComma: ctx.allowsEs5TrailingComma(),
+  }), covered
 }
 
 // printNamedExports renders `export { a, b }`. The shape is identical
 // to NamedImports; only the surrounding declaration differs.
-func printNamedExports(ctx *PrintContext, node *shimast.Node) Doc {
+//
+// The second return value is the `covered` flag: see PrintNode.
+func printNamedExports(ctx *PrintContext, node *shimast.Node) (Doc, bool) {
   if node == nil {
-    return Doc{}
+    return Doc{}, true
   }
   ne := node.AsNamedExports()
   if ne == nil || ne.Elements == nil {
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
   items := make([]Doc, 0, len(ne.Elements.Nodes))
+  covered := true
   for _, spec := range ne.Elements.Nodes {
     if spec == nil {
-      return verbatim(ctx, node)
+      return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
     }
-    doc, _ := PrintNode(ctx, spec)
+    doc, childCovered := PrintNode(ctx, spec)
+    covered = covered && childCovered
     items = append(items, doc)
   }
+  // AddComma honors `format.trailingComma`: named exports are an
+  // ES5-permitted comma position, so "all" and "es5" both keep the
+  // trailing comma; only "none" drops it.
   return printList(ctx, listShape{
     OpenTok:  "{",
     CloseTok: "}",
     Items:    items,
     Space:    true,
-    AddComma: true,
-  })
+    AddComma: ctx.allowsEs5TrailingComma(),
+  }), covered
 }
 
 // printImportDeclaration renders the surrounding `import … from "x";`.
@@ -79,13 +93,15 @@ func printNamedExports(ctx *PrintContext, node *shimast.Node) Doc {
 //
 // The dispatcher hands off to the per-clause printers; the top-level
 // frame stitches them together with the keywords and `from` token.
-func printImportDeclaration(ctx *PrintContext, node *shimast.Node) Doc {
+//
+// The second return value is the `covered` flag: see PrintNode.
+func printImportDeclaration(ctx *PrintContext, node *shimast.Node) (Doc, bool) {
   if node == nil {
-    return Doc{}
+    return Doc{}, true
   }
   imp := node.AsImportDeclaration()
   if imp == nil {
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
   // If the declaration uses anything other than a vanilla
   // `import { ... } from "x"` shape (default specifier, namespace
@@ -93,20 +109,26 @@ func printImportDeclaration(ctx *PrintContext, node *shimast.Node) Doc {
   // canonical reflow target is the named-import body.
   clause := imp.ImportClause
   if clause == nil {
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
   clauseData := clause.AsImportClause()
   if clauseData == nil || clauseData.NamedBindings == nil {
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
   if clauseData.NamedBindings.Kind != shimast.KindNamedImports {
     // Namespace imports (`import * as ns from "x"`) have no
     // reflow surface; leave them alone.
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
   if clause.Name() != nil {
     // `import Default, { … } from "x"` — keep verbatim for v1.
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
+  }
+  // AttributeClause (`with { ... }` / `assert { ... }`) lives after
+  // the module specifier. Fall back to verbatim when present so we
+  // don't drop attributes silently.
+  if imp.Attributes != nil {
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
 
   // Bracketed clause prefix: `import ` (and optional `type `).
@@ -114,8 +136,9 @@ func printImportDeclaration(ctx *PrintContext, node *shimast.Node) Doc {
   if clause.IsTypeOnly() {
     prefix = "import type "
   }
-  named, _ := PrintNode(ctx, clauseData.NamedBindings)
+  named, covered := PrintNode(ctx, clauseData.NamedBindings)
   moduleSpec := verbatim(ctx, imp.ModuleSpecifier)
+  covered = covered && !nodeSpansMultipleLines(ctx, imp.ModuleSpecifier)
   parts := []Doc{Text(prefix), named, Text(" from "), moduleSpec}
   if sourceHasStatementTerminator(ctx.Source, node.End()) {
     // Preserve the user's terminator decision. Emitting `;`
@@ -124,13 +147,7 @@ func printImportDeclaration(ctx *PrintContext, node *shimast.Node) Doc {
     // `;;` — `format/semi` owns terminator placement.
     parts = append(parts, Text(";"))
   }
-  // AttributeClause (`with { ... }` / `assert { ... }`) lives after
-  // the module specifier. Fall back to verbatim when present so we
-  // don't drop attributes silently.
-  if imp.Attributes != nil {
-    return verbatim(ctx, node)
-  }
-  return Concat(parts...)
+  return Concat(parts...), covered
 }
 
 // sourceHasStatementTerminator reports whether the last non-trivia

package/linthost/print_nodes_list.go

@@ -27,15 +27,53 @@ type listShape struct {
   Items    []Doc
   Space    bool // emit a space after OPEN / before CLOSE in flat mode
   AddComma bool // emit a trailing comma in broken mode
+  // HugLast keeps the final item attached to the parens instead of
+  // exploding the whole list. It is set by the call/new argument
+  // printer when the last argument is a callback or object literal —
+  // see printArgList. When true, the last item is emitted directly
+  // against OPEN…CLOSE with no leading/trailing soft break, so a
+  // multi-line callback body does not force every preceding argument
+  // onto its own line.
+  HugLast bool
+  // ForceBreak commits the list to its broken, one-item-per-line shape
+  // even when it would fit flat. The object-literal printer sets it to
+  // mirror Prettier's objectWrap:"preserve" — an object the source
+  // wrote with a newline after `{` stays expanded.
+  ForceBreak bool
 }
 
 // printList renders the list shape as a Doc tree. Empty lists collapse
-// to `OPENCLOSE`. Single-element lists still wrap so trailing-comma
-// logic stays uniform.
+// to `OPENCLOSE`. A HugLast list becomes a ConditionalGroup of up to
+// three shapes; every other list is the plain fit-or-break Group.
 func printList(ctx *PrintContext, shape listShape) Doc {
   if len(shape.Items) == 0 {
     return Text(shape.OpenTok + shape.CloseTok)
   }
+  plain := printListPlain(ctx, shape)
+  if !shape.HugLast {
+    return plain
+  }
+  // A HugLast list offers the engine up to three shapes, in preference
+  // order:
+  //   1. allFlat — every item on one line, chosen when it fits;
+  //   2. hugged  — leading items inline, the final callback or object
+  //      committed to its multi-line shape, chosen when its opening
+  //      line fits but the all-flat form does not;
+  //   3. plain   — every item exploded onto its own indented line.
+  // The all-flat option is dropped when the list cannot render flat
+  // (a block-bodied callback argument carries hard line breaks).
+  hugged := printListHuggingLast(ctx, shape)
+  if allFlat, ok := flatten(plain); ok {
+    return ConditionalGroup(allFlat, hugged, plain)
+  }
+  return ConditionalGroup(hugged, plain)
+}
+
+// printListPlain renders the open-comma-close list as a single
+// fit-or-break Group: flat (`OPEN a, b CLOSE`) when it fits the width
+// budget, one item per indented line — with an optional trailing
+// comma — when it does not.
+func printListPlain(ctx *PrintContext, shape listShape) Doc {
   sep := Concat(Text(","), Line())
   body := Join(sep, shape.Items)
 
@@ -53,12 +91,55 @@ func printList(ctx *PrintContext, shape listShape) Doc {
   closeTok := Text(shape.CloseTok)
 
   // In flat mode: OPEN [pad] body [pad] CLOSE
-  // In broken mode: OPEN \n body, \n CLOSE — using Softline so the
-  // flat form collapses cleanly.
+  // In broken mode: OPEN \n body, \n CLOSE.
   leadingSep := IfBreak(Hardline(), flatPad)
   trailingSep := IfBreak(Hardline(), flatPad)
 
   bodyBlock := Indent(ctx.indentUnit(), leadingSep, body, trailing)
   doc := Concat(openTok, bodyBlock, trailingSep, closeTok)
-  return Group(doc)
+  group := Group(doc)
+  // ForceBreak (object-literal newline preservation) commits the group
+  // to its broken shape regardless of fit.
+  group.Break = shape.ForceBreak
+  return group
+}
+
+// printListHuggingLast renders the "last-argument hugging" shape that
+// Prettier uses for `foo(a, b, () => { … })`: the leading items flow
+// comma-separated and the final item stays attached to the closing
+// paren instead of being pushed onto its own indented line.
+//
+//  hugged: OPEN a, b, OPEN-of-last … CLOSE-of-last CLOSE
+//
+// The result is a plain Concat, not a Group: the hugged last argument
+// is a callback or object literal whose own printer carries the
+// fit-or-break decision for its body, so wrapping here would let a
+// multi-line body force the `a, b,` prefix to break. printList offers
+// this Concat as a ConditionalGroup option; when its opening line would
+// overflow printWidth the engine falls back to the plain exploded list.
+//
+// The hugged final item is forced broken — via forceBreakFirstGroup —
+// so the hugged option is genuinely multi-line and distinct from the
+// all-flat option. A flat hugged object would otherwise be
+// byte-identical to all-flat yet escape its width check. The break
+// reaches the first Group in the item's subtree, so an object or array
+// nested inside an arrow body (`(x) => ({ … })`) breaks too.
+func printListHuggingLast(ctx *PrintContext, shape listShape) Doc {
+  last := shape.Items[len(shape.Items)-1]
+  lead := shape.Items[:len(shape.Items)-1]
+  // Force the hugged item's first Group broken only when the item has
+  // no hard line breaks of its own. A block-bodied callback already
+  // renders multi-line through its block's hard breaks; descending into
+  // it with forceBreakFirstGroup would instead force some unrelated
+  // nested Group — a plain statement's call-argument list — broken.
+  if _, flat := flatten(last); flat {
+    last, _ = forceBreakFirstGroup(last)
+  }
+
+  parts := []Doc{Text(shape.OpenTok)}
+  for _, item := range lead {
+    parts = append(parts, item, Text(", "))
+  }
+  parts = append(parts, last, Text(shape.CloseTok))
+  return Concat(parts...)
 }

package/linthost/print_nodes_object.go

@@ -2,6 +2,7 @@ package linthost
 
 import (
   shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
 )
 
 // printObjectLiteral renders an ObjectLiteralExpression with width-aware
@@ -22,30 +23,74 @@ import (
 // The flat form uses a single space inside the braces, matching
 // Prettier's `bracketSpacing: true` default. Empty object literals
 // collapse to `{}` with no inner space, matching every formatter.
-func printObjectLiteral(ctx *PrintContext, node *shimast.Node) Doc {
+//
+// The second return value is the `covered` flag: see PrintNode. It is
+// the AND of every property's coverage — one multi-line verbatim
+// member taints the whole literal.
+func printObjectLiteral(ctx *PrintContext, node *shimast.Node) (Doc, bool) {
   if node == nil {
-    return Doc{}
+    return Doc{}, true
   }
   obj := node.AsObjectLiteralExpression()
   if obj == nil || obj.Properties == nil {
-    return verbatim(ctx, node)
+    return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
   }
   items := make([]Doc, 0, len(obj.Properties.Nodes))
+  covered := true
   for _, prop := range obj.Properties.Nodes {
     if prop == nil {
       // A nil child entry would render as an empty Doc and surface
       // as `a, , b` in the output. Bail to verbatim so the source
       // bytes round-trip unchanged.
-      return verbatim(ctx, node)
+      return verbatim(ctx, node), !nodeSpansMultipleLines(ctx, node)
     }
-    doc, _ := PrintNode(ctx, prop)
+    doc, childCovered := PrintNode(ctx, prop)
+    covered = covered && childCovered
     items = append(items, doc)
   }
+  // objectWrap:"preserve" — keep a non-empty object expanded when the
+  // source wrote a newline after `{`. An empty literal has no first
+  // property to anchor the check and never preserves.
+  forceBreak := false
+  if len(obj.Properties.Nodes) > 0 {
+    forceBreak = objectHasNewlineAfterBrace(ctx.Source, node, obj.Properties.Nodes[0])
+  }
+  // AddComma honors `format.trailingComma`: object literals accept
+  // trailing commas in ES5 so both "all" and "es5" keep them; only
+  // "none" suppresses. Pairs with the call/array branches so the printer
+  // never disagrees with the trailing-comma rule on the same setting.
   return printList(ctx, listShape{
-    OpenTok:  "{",
-    CloseTok: "}",
-    Items:    items,
-    Space:    true,
-    AddComma: true,
-  })
+    OpenTok:    "{",
+    CloseTok:   "}",
+    Items:      items,
+    Space:      true,
+    AddComma:   ctx.allowsEs5TrailingComma(),
+    ForceBreak: forceBreak,
+  }), covered
+}
+
+// objectHasNewlineAfterBrace reports whether the source places a
+// newline between the object literal's `{` and its first property.
+//
+// Prettier's objectWrap:"preserve" default keeps such an object
+// expanded even when it would fit flat, treating the author's line
+// break as intentional structure. format/print-width mirrors that:
+// without it a deliberately multi-line object that happens to fit
+// would be silently collapsed onto one line, which Prettier never
+// does.
+func objectHasNewlineAfterBrace(src string, node *shimast.Node, firstProp *shimast.Node) bool {
+  if node == nil || firstProp == nil {
+    return false
+  }
+  brace := shimscanner.SkipTrivia(src, node.Pos())
+  propStart := shimscanner.SkipTrivia(src, firstProp.Pos())
+  if brace < 0 || propStart <= brace || propStart > len(src) {
+    return false
+  }
+  for i := brace; i < propStart; i++ {
+    if src[i] == '\n' {
+      return true
+    }
+  }
+  return false
 }

package/linthost/rules_arrays.go

@@ -25,8 +25,11 @@ func (noSparseArrays) Check(ctx *Context, node *shimast.Node) {
 }
 
 // no-array-constructor: forbid `new Array(0)` / `Array(1, 2, 3)` (use
-// array literals). The 1-arg numeric form is also banned because its
-// behavior depends on the runtime — see ESLint defaults.
+// array literals). The single-argument form is intentionally excluded from
+// the ban: `Array(n)` is commonly used to pre-allocate a sparse array by
+// length, and banning it would generate noise on existing idiomatic code.
+// The typed form `new Array<string>()` is also excluded — a type argument
+// signals intentional use and the caller takes responsibility.
 // https://eslint.org/docs/latest/rules/no-array-constructor
 type noArrayConstructor struct{}
 

package/linthost/rules_debugger.go

@@ -12,8 +12,9 @@ func (noDebugger) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(node, "Unexpected `debugger` statement.")
 }
 
-// no-with: forbid `with` statements (already disallowed in strict mode,
-// but lint catches it before the parse error).
+// no-with: forbid `with` statements. `with` is disallowed in strict mode
+// at the parser level, but TypeScript source files may not use strict mode
+// explicitly; the lint rule catches it uniformly regardless of mode.
 // https://eslint.org/docs/latest/rules/no-with
 type noWith struct{}
 

package/linthost/rules_dupes.go

@@ -49,18 +49,17 @@ func (noDupeKeys) Check(ctx *Context, node *shimast.Node) {
   if obj == nil || obj.Properties == nil {
     return
   }
-  seen := make(map[string]*shimast.Node, len(obj.Properties.Nodes))
+  seen := make(map[string]bool, len(obj.Properties.Nodes))
   for _, prop := range obj.Properties.Nodes {
     key := propertyKey(ctx.File, prop)
     if key == "" {
       continue
     }
-    if first, ok := seen[key]; ok {
+    if seen[key] {
       ctx.Report(prop, "Duplicate key '"+key+"'.")
-      _ = first
       continue
     }
-    seen[key] = prop
+    seen[key] = true
   }
 }
 
@@ -153,6 +152,10 @@ func propertyKey(file *shimast.SourceFile, prop *shimast.Node) string {
   return ""
 }
 
+// staticPropertyKey extracts a comparable string key from a property name node.
+// Identifiers, string/numeric literals, and computed names with a literal
+// payload all produce a stable string. Other computed names (dynamic
+// expressions) return "" so the caller skips them without false positives.
 func staticPropertyKey(file *shimast.SourceFile, name *shimast.Node) string {
   if name == nil {
     return ""

package/linthost/rules_empty.go

@@ -83,8 +83,9 @@ func (noEmptyPattern) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
-// isFunctionLikeKind reports whether the node represents a function-like
-// host whose body is the relevant scope for the empty check.
+// isFunctionLikeKind reports whether n represents a function-like AST node
+// (declaration, expression, arrow, method, accessor, or constructor). Used
+// to detect scope boundaries by rules_empty, rules_finally, and others.
 func isFunctionLikeKind(n *shimast.Node) bool {
   if n == nil {
     return false

package/linthost/rules_escape.go

@@ -52,12 +52,12 @@ func (noUselessEscape) Check(ctx *Context, node *shimast.Node) {
   // single-char escape whitelist matches ESLint per-context.
   switch node.Kind {
   case shimast.KindStringLiteral:
-    reportStringEscapes(ctx, raw, pos, stringValidEscapes)
+    reportStringEscapes(ctx, raw, pos, stringValidEscapes, false)
   case shimast.KindNoSubstitutionTemplateLiteral,
     shimast.KindTemplateHead,
     shimast.KindTemplateMiddle,
     shimast.KindTemplateTail:
-    reportStringEscapes(ctx, raw, pos, templateValidEscapes)
+    reportStringEscapes(ctx, raw, pos, templateValidEscapes, true)
   case shimast.KindRegularExpressionLiteral:
     reportRegexEscapes(ctx, raw, pos)
   }
@@ -73,7 +73,22 @@ const templateValidEscapes = "`'\"\\bfnrtv0xuU$\n\r"
 // — it never deletes a backslash whose meaning could be context-sensitive).
 const regexValidEscapes = "^$\\.*+?()[]{}|/-\n\r"
 
-func reportStringEscapes(ctx *Context, raw string, base int, whitelist string) {
+// reportStringEscapes walks the raw source bytes of a string or template
+// literal and reports each backslash whose following character is not in
+// `whitelist`. `base` is the source offset of `raw[0]` so reported ranges
+// translate to absolute file positions. The function issues an autofix
+// (delete the backslash) for ASCII escapes; multi-byte sequences are
+// reported without a fix to avoid corrupting UTF-8.
+//
+// `isTemplate` is true for `NoSubstitutionTemplateLiteral` and
+// `TemplateHead`/`Middle`/`Tail` payloads. Inside a template, `\${` escapes
+// the interpolation opener: stripping the backslash from `\${expr}` would
+// either turn the literal text into an interpolation (corrupting the
+// program) or — when the surrounding template already contains a real
+// `${expr}` — produce TS syntax that no longer parses. The explicit guard
+// here pins that exception so future tightening of `templateValidEscapes`
+// cannot regress the corruption.
+func reportStringEscapes(ctx *Context, raw string, base int, whitelist string, isTemplate bool) {
   if len(raw) < 2 {
     return
   }
@@ -95,6 +110,14 @@ func reportStringEscapes(ctx *Context, raw string, base int, whitelist string) {
       return
     }
     next := raw[i+1]
+    // Template-literal exception: `\${` escapes the interpolation
+    // opener. Without the backslash the next two bytes would either
+    // start an interpolation or trigger a parse error, so the escape is
+    // load-bearing even though `\$` looks redundant in isolation.
+    if isTemplate && next == '$' && i+2 < len(raw) && raw[i+2] == '{' {
+      i++ // consume the `$` so the `{` is not re-examined as a fresh char.
+      continue
+    }
     if isUselessStringEscape(next, whitelist) {
       // Only emit a fix when both surrounding bytes are plain ASCII so
       // deleting one byte cannot corrupt a multi-byte sequence.
@@ -117,6 +140,9 @@ func reportStringEscapes(ctx *Context, raw string, base int, whitelist string) {
   }
 }
 
+// reportRegexEscapes walks the pattern body of a regex literal and reports
+// backslashes that escape non-special characters. `base` is the source offset
+// of `raw[0]`. Character-class context (`[…]`) widens the legal set slightly.
 func reportRegexEscapes(ctx *Context, raw string, base int) {
   if len(raw) < 3 || raw[0] != '/' {
     return
@@ -166,6 +192,9 @@ func reportRegexEscapes(ctx *Context, raw string, base int) {
   }
 }
 
+// isUselessStringEscape reports whether a backslash before `ch` is redundant
+// inside a string or template literal. The `whitelist` contains the characters
+// that are valid escape targets for the specific literal kind (string vs template).
 func isUselessStringEscape(ch byte, whitelist string) bool {
   // Whitespace + control chars are escape sequences too.
   if ch < 0x20 {
@@ -181,6 +210,9 @@ func isUselessStringEscape(ch byte, whitelist string) bool {
   return true
 }
 
+// isUselessRegexEscape reports whether a backslash before `ch` is redundant
+// in a regex pattern. `inClass` is true when the escape occurs inside a `[…]`
+// character class, which widens the set of meaningful escapes.
 func isUselessRegexEscape(ch byte, inClass bool) bool {
   if ch < 0x20 {
     return false

package/linthost/rules_eval.go

@@ -36,6 +36,9 @@ func (noScriptURL) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isJavaScriptURL reports whether text starts with the "javascript:" scheme
+// (case-insensitively, ASCII only). The manual loop avoids importing strings
+// just for strings.ToLower and keeps the hot path allocation-free.
 func isJavaScriptURL(text string) bool {
   const prefix = "javascript:"
   if len(text) < len(prefix) {

package/linthost/rules_finally.go

@@ -25,6 +25,15 @@ func (noUnsafeFinally) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(node, "Unsafe usage of "+keyword+".")
 }
 
+// walkToFinally walks the parent chain from node upward looking for a
+// `finally` block. It returns the Block node that IS the finally clause when
+// found, or nil when the search exits through a function boundary (making any
+// control-flow transfer target something outside the finally block) or when no
+// finally block is found at all.
+//
+// A `break` or `continue` that targets an inner loop or switch INSIDE the
+// finally block is safe — it does not escape the finally — so the walk stops
+// early and returns nil in that case.
 func walkToFinally(node *shimast.Node) *shimast.Node {
   cur := node.Parent
   for cur != nil {
@@ -58,6 +67,8 @@ func walkToFinally(node *shimast.Node) *shimast.Node {
   return nil
 }
 
+// keywordOfControl returns the control-flow keyword string for the given
+// statement node, used to build the diagnostic message text.
 func keywordOfControl(node *shimast.Node) string {
   switch node.Kind {
   case shimast.KindReturnStatement:

package/linthost/rules_format_jsdoc.go

@@ -136,6 +136,10 @@ func findJSDocBlocks(src string) []jsdocBlock {
   return out
 }
 
+// rewriteJSDocTags scans one JSDoc block and emits a fix for each tag that has
+// a canonical synonym. Tags preceded by a byte other than `*`, whitespace, or a
+// newline are treated as inline `@foo` references (not top-level tags) and are
+// left alone. Tags inside `@example` bodies are also skipped.
 func rewriteJSDocTags(ctx *Context, src string, block jsdocBlock, synonyms map[string]string) {
   for i := block.bodyStart; i < block.bodyEnd; i++ {
     if src[i] != '@' {
@@ -205,6 +209,9 @@ func endOfJSDocExampleBody(src string, block jsdocBlock, start int) int {
   return block.bodyEnd
 }
 
+// isJSDocTagByte reports whether `b` is an ASCII letter that may appear in a
+// JSDoc tag name. Tags are purely alphabetic: digits, hyphens, and underscores
+// terminate a tag name.
 func isJSDocTagByte(b byte) bool {
   return (b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z')
 }