@ttsc/lint 0.19.3 → 0.20.1

package/linthost/rules_storybook.go

@@ -12,6 +12,8 @@ import (
   "unicode"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
+  publicrule "github.com/samchon/ttsc/packages/lint/rule"
 )
 
 type storybookAwaitInteractions struct{}
@@ -89,6 +91,14 @@ func (storybookDefaultExports) Check(ctx *Context, node *shimast.Node) {
 type storybookHierarchySeparator struct{}
 
 func (storybookHierarchySeparator) Name() string { return "storybook/hierarchy-separator" }
+
+// DiagnosticTags strikes the separator through: `|` is Storybook's superseded
+// hierarchy separator, and a title that uses it still renders — Storybook
+// keeps reading it — so the finding is exactly "this still works, migrate off
+// it", never "delete this title property".
+func (storybookHierarchySeparator) DiagnosticTags() []publicrule.DiagnosticTag {
+  return []publicrule.DiagnosticTag{publicrule.DiagnosticTagDeprecated}
+}
 func (storybookHierarchySeparator) Visits() []shimast.Kind {
   return []shimast.Kind{shimast.KindSourceFile}
 }
@@ -101,7 +111,74 @@ func (storybookHierarchySeparator) Check(ctx *Context, node *shimast.Node) {
   if !ok || !strings.Contains(storybookLiteralString(value), "|") {
     return
   }
-  ctx.Report(prop, "Deprecated hierarchy separator in title property.")
+  const message = "Deprecated hierarchy separator in title property."
+  pos, end, located := storybookLiteralPipeRange(ctx.File, value)
+  if !located {
+    // The decoded title carries the separator, so the finding is real even when
+    // the raw spelling that produced it cannot be bounded. Report the property
+    // rather than dropping the diagnostic: a wider strikethrough is an
+    // imprecision, a missing diagnostic is a rule that stopped working.
+    ctx.Report(prop, message)
+    return
+  }
+  ctx.ReportRange(pos, end, message)
+}
+
+// storybookLiteralPipeRange returns the raw source range of one `|` that the
+// parser decoded from a title literal. The tagged diagnostic must cover the
+// deprecated separator itself, not the still-live title property around it.
+//
+// A pipe can be written directly or as an active `\\|`, `\\x7C`, `\\u007C`, or
+// `\\u{7C}` escape. Every spelling below evaluates to the same separator, and
+// reporting its complete raw escape keeps the editor range valid for each.
+func storybookLiteralPipeRange(file *shimast.SourceFile, node *shimast.Node) (int, int, bool) {
+  pos, end := tokenRange(file, node)
+  if pos < 0 {
+    return 0, 0, false
+  }
+  src := file.Text()
+  for index := pos; index < end; {
+    if src[index] == '|' {
+      return index, index + 1, true
+    }
+    if src[index] != '\\' {
+      index++
+      continue
+    }
+    start := index
+    for index < end && src[index] == '\\' {
+      index++
+    }
+    if (index-start)%2 == 0 || index >= end {
+      continue
+    }
+    active := index - 1
+    switch src[index] {
+    case '|':
+      return active, index + 1, true
+    case 'x':
+      if index+2 < end && hexDigit(src[index+1])*16+hexDigit(src[index+2]) == int('|') {
+        return active, index + 3, true
+      }
+    case 'u':
+      if index+1 < end && src[index+1] == '{' {
+        close := index + 2
+        value := 0
+        for close < end && hexDigit(src[close]) >= 0 {
+          value = value*16 + hexDigit(src[close])
+          close++
+        }
+        if close > index+2 && close < end && src[close] == '}' && value == int('|') {
+          return active, close + 1, true
+        }
+      } else if index+4 < end &&
+        hexDigit(src[index+1])*4096+hexDigit(src[index+2])*256+hexDigit(src[index+3])*16+hexDigit(src[index+4]) == int('|') {
+        return active, index + 5, true
+      }
+    }
+    index++
+  }
+  return 0, 0, false
 }
 
 type storybookMetaInlineProperties struct{}
@@ -140,18 +217,34 @@ func (storybookMetaSatisfiesType) Check(ctx *Context, node *shimast.Node) {
 type storybookNoRedundantStoryName struct{}
 
 func (storybookNoRedundantStoryName) Name() string { return "storybook/no-redundant-story-name" }
+
+// DiagnosticTags greys the redundant annotation out. Both arms of this rule
+// report an annotation that restates the name Storybook already derives from
+// the export identifier — the object property in one, the standalone
+// `Story.storyName =` assignment in the other — and each is reported at
+// exactly the range whose deletion is the whole resolution.
+func (storybookNoRedundantStoryName) DiagnosticTags() []publicrule.DiagnosticTag {
+  return []publicrule.DiagnosticTag{publicrule.DiagnosticTagUnnecessary}
+}
 func (storybookNoRedundantStoryName) Visits() []shimast.Kind {
   return []shimast.Kind{shimast.KindSourceFile}
 }
 func (storybookNoRedundantStoryName) Check(ctx *Context, node *shimast.Node) {
+  namedExports := map[string]bool{}
   for _, story := range storybookNamedExports(ctx.File) {
+    namedExports[story.Name] = true
     if story.Init == nil || story.Init.Kind != shimast.KindObjectLiteralExpression {
       continue
     }
     for _, propName := range []string{"name", "storyName"} {
       prop, value, ok := storybookObjectProperty(story.Init, propName)
       if ok && storybookLiteralString(value) == storybookNameFromExport(story.Name) {
-        ctx.Report(prop, "Named exports should not use a redundant story name annotation.")
+        pos, end, removable := storybookRemovablePropertyRange(ctx.File, prop)
+        if removable {
+          ctx.ReportRange(pos, end, "Named exports should not use a redundant story name annotation.")
+        } else {
+          ctx.Report(prop, "Named exports should not use a redundant story name annotation.")
+        }
       }
     }
   }
@@ -164,12 +257,47 @@ func (storybookNoRedundantStoryName) Check(ctx *Context, node *shimast.Node) {
       return
     }
     objectName, propName := storybookPropertyAccessParts(expr.Left)
-    if propName == "storyName" && storybookLiteralString(expr.Right) == storybookNameFromExport(objectName) {
-      ctx.Report(child, "Named exports should not use a redundant story name annotation.")
+    if namedExports[objectName] &&
+      propName == "storyName" &&
+      storybookLiteralString(expr.Right) == storybookNameFromExport(objectName) {
+      if child.Parent == nil ||
+        child.Parent.Kind != shimast.KindExpressionStatement ||
+        child.Parent.Parent == nil ||
+        child.Parent.Parent.Kind != shimast.KindSourceFile {
+        return
+      }
+      // The Unnecessary tag is rule-wide. Only a standalone assignment can be
+      // removed as a whole; an assignment nested in another expression still
+      // contributes its value, while one in a nested scope can refer to a
+      // same-named shadow instead of the exported story.
+      ctx.Report(child.Parent, "Named exports should not use a redundant story name annotation.")
     }
   })
 }
 
+// storybookRemovablePropertyRange returns the complete removable grain of an
+// object property. A PropertyAssignment node stops before its trailing comma;
+// when one is present, include it (and any trivia before it) so deleting
+// exactly the faded `Unnecessary` range leaves valid object syntax.
+//
+// A comment sitting between the property and its comma is therefore faded with
+// them. That is deliberate, not an oversight: the alternative — stopping at the
+// comment and leaving the comma behind — produces `{ /* note */, }`, which does
+// not parse. Only one of the two can hold, and a range whose deletion always
+// leaves valid syntax is the contract the Unnecessary tag makes.
+func storybookRemovablePropertyRange(file *shimast.SourceFile, property *shimast.Node) (int, int, bool) {
+  pos, end := tokenRange(file, property)
+  if pos < 0 {
+    return 0, 0, false
+  }
+  source := file.Text()
+  comma := shimscanner.SkipTrivia(source, end)
+  if comma < len(source) && source[comma] == ',' {
+    end = comma + 1
+  }
+  return pos, end, true
+}
+
 type storybookNoRendererPackages struct{}
 
 func (storybookNoRendererPackages) Name() string { return "storybook/no-renderer-packages" }
@@ -181,27 +309,106 @@ func (storybookNoRendererPackages) Check(ctx *Context, node *shimast.Node) {
   if decl == nil {
     return
   }
-  if _, ok := storybookRendererPackages[storybookLiteralString(decl.ModuleSpecifier)]; ok {
-    ctx.Report(node, "Do not import Storybook renderer packages directly. Use a framework package instead.")
+  frameworks, ok := storybookRendererPackages[storybookLiteralString(decl.ModuleSpecifier)]
+  if !ok || len(frameworks) == 0 {
+    return
+  }
+  message := "Do not import Storybook renderer packages directly. Use a framework package instead: " +
+    storybookDisjunction(frameworks) + "."
+  pos, end, quoted := storybookQuotedTextRange(ctx.File, decl.ModuleSpecifier)
+  if !quoted {
+    ctx.Report(node, message)
+    return
+  }
+  suggestions := make([]Suggestion, 0, len(frameworks))
+  for _, framework := range frameworks {
+    suggestions = append(suggestions, Suggestion{
+      Title: "Import from `" + framework + "`.",
+      Edits: []TextEdit{{Pos: pos, End: end, Text: framework}},
+    })
+  }
+  ctx.ReportFixSuggestions(node, message, nil, suggestions...)
+}
+
+// storybookDisjunction renders a package list the way upstream's
+// `Intl.ListFormat("en-US", {type: "disjunction"})` does: "a", "a or b",
+// "a, b, or c".
+func storybookDisjunction(items []string) string {
+  quoted := make([]string, 0, len(items))
+  for _, item := range items {
+    quoted = append(quoted, "`"+item+"`")
+  }
+  switch len(quoted) {
+  case 0:
+    return ""
+  case 1:
+    return quoted[0]
+  case 2:
+    return quoted[0] + " or " + quoted[1]
+  default:
+    return strings.Join(quoted[:len(quoted)-1], ", ") + ", or " + quoted[len(quoted)-1]
   }
 }
 
+// storybookQuotedTextRange returns the byte range of the text inside a string
+// literal's quotes, so a rewrite replaces the contents and leaves the
+// surrounding quote characters exactly as the author wrote them. Reports false
+// for anything that is not a plainly quoted literal, such as a
+// parse-recovered node with no closing quote.
+func storybookQuotedTextRange(file *shimast.SourceFile, node *shimast.Node) (int, int, bool) {
+  pos, end := tokenRange(file, node)
+  if pos < 0 || end-pos < 2 {
+    return 0, 0, false
+  }
+  src := file.Text()
+  quote := src[pos]
+  if quote != '"' && quote != '\'' {
+    return 0, 0, false
+  }
+  if src[end-1] != quote {
+    return 0, 0, false
+  }
+  return pos + 1, end - 1, true
+}
+
 type storybookNoStoriesOf struct{}
 
 func (storybookNoStoriesOf) Name() string { return "storybook/no-stories-of" }
+
+// DiagnosticTags strikes the `storiesOf` import specifier through. The builder
+// API is deprecated in favor of CSF but still runs, and the whole reported
+// range is the specifier that names it, so migration — not deletion — is the
+// instruction the editor should render.
+func (storybookNoStoriesOf) DiagnosticTags() []publicrule.DiagnosticTag {
+  return []publicrule.DiagnosticTag{publicrule.DiagnosticTagDeprecated}
+}
 func (storybookNoStoriesOf) Visits() []shimast.Kind {
   return []shimast.Kind{shimast.KindImportSpecifier}
 }
 func (storybookNoStoriesOf) Check(ctx *Context, node *shimast.Node) {
   spec := node.AsImportSpecifier()
-  if spec != nil && storybookImportSpecifierImportedName(spec) == "storiesOf" {
-    ctx.Report(node, "storiesOf is deprecated and should not be used.")
+  if spec != nil &&
+    storybookImportSpecifierImportedName(spec) == "storiesOf" &&
+    isStorybookStoriesOfModule(storybookImportSpecifierModule(node)) {
+    reported := spec.Name()
+    if spec.PropertyName != nil {
+      reported = spec.PropertyName
+    }
+    ctx.Report(reported, "storiesOf is deprecated and should not be used.")
   }
 }
 
 type storybookNoTitlePropertyInMeta struct{}
 
 func (storybookNoTitlePropertyInMeta) Name() string { return "storybook/no-title-property-in-meta" }
+
+// DiagnosticTags greys the `title` property out. CSF3 derives a story's title
+// from the file's location on disk, so the property is dead weight rather than
+// a wrong value, and the reported range is the property itself: removing
+// exactly what the editor fades is the resolution.
+func (storybookNoTitlePropertyInMeta) DiagnosticTags() []publicrule.DiagnosticTag {
+  return []publicrule.DiagnosticTag{publicrule.DiagnosticTagUnnecessary}
+}
 func (storybookNoTitlePropertyInMeta) Visits() []shimast.Kind {
   return []shimast.Kind{shimast.KindSourceFile}
 }
@@ -211,7 +418,12 @@ func (storybookNoTitlePropertyInMeta) Check(ctx *Context, node *shimast.Node) {
     return
   }
   if prop, _, ok := storybookObjectProperty(meta.Object, "title"); ok {
-    ctx.Report(prop, "CSF3 does not need a title in meta.")
+    pos, end, removable := storybookRemovablePropertyRange(ctx.File, prop)
+    if removable {
+      ctx.ReportRange(pos, end, "CSF3 does not need a title in meta.")
+    } else {
+      ctx.Report(prop, "CSF3 does not need a title in meta.")
+    }
   }
 }
 
@@ -370,6 +582,16 @@ var storybookRendererPackages = map[string][]string{
   "@storybook/web-components": {"@storybook/web-components-vite", "@storybook/web-components-webpack5"},
 }
 
+var storybookStoriesOfModules = []string{
+  "@storybook/react",
+  "@storybook/vue",
+  "@storybook/vue3",
+  "@storybook/angular",
+  "@storybook/svelte",
+  "@storybook/html",
+  "@storybook/web-components",
+}
+
 func storybookDefaultMeta(file *shimast.SourceFile) *storybookMetaInfo {
   if file == nil || file.Statements == nil {
     return nil
@@ -756,7 +978,30 @@ func storybookDescriptorsMatch(descriptors []storybookDescriptor, name string) b
 }
 
 func storybookHasStoriesOfImport(file *shimast.SourceFile) bool {
-  return storybookHasNamedImport(file, "storiesOf", "@storybook/react", "@storybook/vue", "@storybook/vue3", "@storybook/angular", "@storybook/svelte", "@storybook/html", "@storybook/web-components")
+  return storybookHasNamedImport(file, "storiesOf", storybookStoriesOfModules...)
+}
+
+func isStorybookStoriesOfModule(module string) bool {
+  for _, candidate := range storybookStoriesOfModules {
+    if module == candidate {
+      return true
+    }
+  }
+  return false
+}
+
+func storybookImportSpecifierModule(node *shimast.Node) string {
+  for current := node; current != nil; current = current.Parent {
+    if current.Kind != shimast.KindImportDeclaration {
+      continue
+    }
+    decl := current.AsImportDeclaration()
+    if decl == nil {
+      return ""
+    }
+    return storybookLiteralString(decl.ModuleSpecifier)
+  }
+  return ""
 }
 
 func storybookHasNamedImport(file *shimast.SourceFile, name string, modules ...string) bool {

package/linthost/rules_suggestions.go

@@ -185,11 +185,20 @@ func (noExtraBind) Check(ctx *Context, node *shimast.Node) {
     return
   }
 
-  edits := noExtraBindFixEdits(ctx, node, call, member, receiver)
-  if len(edits) == 0 {
-    ctx.Report(node, "The function binding is unnecessary.")
-  } else {
-    ctx.ReportFix(node, "The function binding is unnecessary.", edits...)
+  message := "The function binding is unnecessary."
+  edits, imposable := noExtraBindFixEdits(ctx, node, call, member, receiver)
+  switch {
+  case len(edits) == 0:
+    ctx.Report(node, message)
+  case imposable:
+    ctx.ReportFix(node, message, edits...)
+  default:
+    ctx.ReportSuggestion(
+      node,
+      message,
+      "Remove the unnecessary binding, discarding the comment inside it.",
+      edits...,
+    )
   }
 }
 
@@ -296,22 +305,28 @@ func noExtraBindThisBelongsToFunction(node, root *shimast.Node) bool {
 
 // noExtraBindFixEdits removes the member access and its one-argument call as
 // separate ranges. Parentheses and comments before the member operator remain
-// byte-for-byte intact. The fix is withheld when evaluating the receiver may
-// have effects or when any comment lies inside discarded syntax.
+// byte-for-byte intact.
+//
+// No edit exists at all when the removal would change what the program does —
+// evaluating the receiver may have effects — or when the ranges are degenerate;
+// both return `(nil, false)`. When the edit is well-formed but a comment lies
+// inside the discarded syntax, it returns `(edits, false)`: imposing silent
+// comment loss is unacceptable, yet the caller can still offer the removal as
+// an opt-in suggestion. Only `(edits, true)` may be applied automatically.
 func noExtraBindFixEdits(
   ctx *Context,
   callNode *shimast.Node,
   call *shimast.CallExpression,
   member *shimast.Node,
   receiver *shimast.Node,
-) []TextEdit {
+) (edits []TextEdit, imposable bool) {
   if ctx == nil || ctx.File == nil || callNode == nil || call == nil || call.Expression == nil || member == nil ||
     !noExtraBindReceiverIsSideEffectFree(receiver) {
-    return nil
+    return nil, false
   }
   parts, ok := referenceMemberParts(member)
   if !ok || parts.object == nil {
-    return nil
+    return nil, false
   }
 
   src := ctx.File.Text()
@@ -320,15 +335,12 @@ func noExtraBindFixEdits(
   callStart := shimscanner.SkipTrivia(src, call.Expression.End())
   callEnd := callNode.End()
   if memberStart < 0 || memberStart >= memberEnd || memberEnd > callStart || callStart >= callEnd || callEnd > len(src) {
-    return nil
-  }
-  if hasCommentBetween(src, memberStart, callEnd) {
-    return nil
+    return nil, false
   }
   return []TextEdit{
     {Pos: memberStart, End: memberEnd, Text: ""},
     {Pos: callStart, End: callEnd, Text: ""},
-  }
+  }, !hasCommentBetween(src, memberStart, callEnd)
 }
 
 func noExtraBindReceiverIsSideEffectFree(node *shimast.Node) bool {
@@ -1312,19 +1324,22 @@ func reportUselessRenameFix(ctx *Context, node, propertyName, name *shimast.Node
     ctx.Report(node, message)
     return
   }
+  edit := TextEdit{Pos: propertyName.End(), End: name.End(), Text: ""}
   // A comment between the two names (`{ a as /* c */ a }`) sits inside the
-  // deleted rename tail; dropping it would be silent data loss, so decline to
-  // a report-only diagnostic. Mirrors ESLint no-useless-rename's
-  // `commentsExistBetween` guard.
+  // deleted rename tail; imposing that loss is unacceptable, so the autofix
+  // declines. Mirrors ESLint no-useless-rename's `commentsExistBetween` guard.
+  // The collapse is still what the author wants, so the same edit is offered
+  // as an opt-in suggestion whose title states that the comment goes with it.
   if hasCommentBetween(ctx.File.Text(), propertyName.End(), name.End()) {
-    ctx.Report(node, message)
+    ctx.ReportSuggestion(
+      node,
+      message,
+      "Remove the redundant rename, discarding the comment inside it.",
+      edit,
+    )
     return
   }
-  ctx.ReportFix(
-    node,
-    message,
-    TextEdit{Pos: propertyName.End(), End: name.End(), Text: ""},
-  )
+  ctx.ReportFix(node, message, edit)
 }
 
 // objectShorthand: `{ x: x }` → `{ x }`.
@@ -1351,17 +1366,20 @@ func (objectShorthand) Check(ctx *Context, node *shimast.Node) {
   // that range.
   //
   // A comment inside that range (`{ x: /* c */ x }`) would be dropped by the
-  // deletion, so decline to a report-only diagnostic. Mirrors ESLint
-  // object-shorthand's `commentsExistBetween` guard.
+  // deletion, so the autofix declines. Mirrors ESLint object-shorthand's
+  // `commentsExistBetween` guard. The shorthand rewrite is still correct, so
+  // the same edit is offered as an opt-in suggestion that names the loss.
+  edit := TextEdit{Pos: prop.Name().End(), End: prop.Initializer.End(), Text: ""}
   if hasCommentBetween(ctx.File.Text(), prop.Name().End(), prop.Initializer.End()) {
-    ctx.Report(node, "Expected property shorthand.")
+    ctx.ReportSuggestion(
+      node,
+      "Expected property shorthand.",
+      "Use property shorthand, discarding the comment before the value.",
+      edit,
+    )
     return
   }
-  ctx.ReportFix(
-    node,
-    "Expected property shorthand.",
-    TextEdit{Pos: prop.Name().End(), End: prop.Initializer.End(), Text: ""},
-  )
+  ctx.ReportFix(node, "Expected property shorthand.", edit)
 }
 
 // operatorAssignment: `x = x + 1` → `x += 1`.
@@ -1494,21 +1512,24 @@ func (preferTemplate) Check(ctx *Context, node *shimast.Node) {
     ctx.Report(node, message)
     return
   }
+  edit := TextEdit{Pos: editPos, End: node.End(), Text: template}
   // A comment in an operator seam (`"a" + /* c */ b`) is dropped by the
-  // template rebuild, so decline to a report-only diagnostic. Mirrors ESLint
+  // template rebuild, so the autofix declines and the rendered literal is
+  // offered as an opt-in suggestion that names the loss. Mirrors ESLint
   // prefer-template's `commentsExistBetween` guard. Only the seams are scanned:
   // operand interiors are copied verbatim (their comments survive) and string
   // contents are cooked, so scanning the whole span would misread a `//` or
   // `/*` inside a string literal (`"https://" + host`) as a comment.
   if concatOperandSeamsHaveComment(src, operands) {
-    ctx.Report(node, message)
+    ctx.ReportSuggestion(
+      node,
+      message,
+      "Use a template literal, discarding the comments between the operands.",
+      edit,
+    )
     return
   }
-  ctx.ReportFix(
-    node,
-    message,
-    TextEdit{Pos: editPos, End: node.End(), Text: template},
-  )
+  ctx.ReportFix(node, message, edit)
 }
 
 // concatOperandSeamsHaveComment reports whether a comment sits in any seam

package/linthost/rules_ts.go

@@ -147,6 +147,13 @@ func (noNamespace) Check(ctx *Context, node *shimast.Node) {
   if decl.Name().Kind == shimast.KindStringLiteral {
     return
   }
+  // Skip `declare global { … }`. It is spelled with the `global` keyword
+  // rather than `namespace`/`module`, and it is the only way to augment a
+  // global interface — ES module syntax has no equivalent, so the advice this
+  // rule gives cannot be followed. Upstream exempts it for the same reason.
+  if decl.Keyword == shimast.KindGlobalKeyword {
+    return
+  }
   ctx.Report(node, "ES2015 module syntax is preferred over namespaces.")
 }
 

package/linthost/rules_ts_async.go

@@ -6,7 +6,7 @@
 //
 // Implemented here:
 //   - typescript/require-await
-//     (AST-only; async function with no `await` in its body)
+//     (type-aware; async function with no `await` that also returns no promise)
 //   - typescript/use-unknown-in-catch-callback-variable
 //     (type-aware; `.catch(err)` / `.then(_, err)` must annotate `unknown`)
 //   - typescript/only-throw-error
@@ -24,13 +24,20 @@ import (
 // refactor artifact. typescript-eslint:
 // https://typescript-eslint.io/rules/require-await/
 //
-// AST-only. The walker stops at nested function-like boundaries so an
+// The walker stops at nested function-like boundaries so an
 // `await` inside an inner non-async closure does not count toward the
 // outer function. Async generators are exempt — they satisfy the
 // async-keyword contract through `yield`.
 type requireAwait struct{}
 
 func (requireAwait) Name() string { return "typescript/require-await" }
+
+// NeedsTypeChecker: upstream states the rule as "async functions which do not
+// return promises and have no await expression", and that it "uses type
+// information to allow promise-returning functions to be marked as async
+// without containing an await expression". Whether a returned expression is
+// thenable is not visible in the syntax.
+func (requireAwait) NeedsTypeChecker() bool { return true }
 func (requireAwait) Visits() []shimast.Kind {
   return []shimast.Kind{
     shimast.KindFunctionDeclaration,
@@ -53,6 +60,9 @@ func (requireAwait) Check(ctx *Context, node *shimast.Node) {
   if requireAwaitBodyHasAwait(body) {
     return
   }
+  if requireAwaitReturnsThenable(ctx, body) {
+    return
+  }
   startPos := keywordStart(ctx.File, node, "async")
   if startPos < 0 {
     ctx.Report(node, "Async function has no `await` expression.")
@@ -99,6 +109,16 @@ func requireAwaitBodyHasAwait(body *shimast.Node) bool {
       found = true
       return
     }
+    // `for await (const x of source)` awaits every step of the iteration. It
+    // is spelled as a for-of carrying an await modifier rather than as an
+    // AwaitExpression, so a walker that looks only for the expression form
+    // reports a function whose sole suspend point is the loop.
+    if n.Kind == shimast.KindForOfStatement {
+      if stmt := n.AsForInOrOfStatement(); stmt != nil && stmt.AwaitModifier != nil {
+        found = true
+        return
+      }
+    }
     n.ForEachChild(func(child *shimast.Node) bool {
       walk(child)
       return false
@@ -266,3 +286,61 @@ func init() {
   Register(useUnknownInCatchCallbackVariable{})
   Register(onlyThrowError{})
 }
+
+// requireAwaitReturnsThenable reports whether the function body hands a
+// thenable back to its caller.
+//
+// Upstream exempts these deliberately: `async function f() { return g() }`
+// marks the async contract for callers and forwards the inner promise, which
+// is a use of `async` rather than a leftover from a refactor. The walk stops at
+// nested function-like scopes for the same reason the await walk does — an
+// inner closure's `return` belongs to that closure.
+//
+// A concise arrow body (`async () => g()`) is the returned expression itself
+// rather than a block, and is classified directly.
+func requireAwaitReturnsThenable(ctx *Context, body *shimast.Node) bool {
+  if ctx == nil || ctx.Checker == nil || body == nil {
+    return false
+  }
+  if body.Kind != shimast.KindBlock {
+    return requireAwaitExpressionIsThenable(ctx, body)
+  }
+  thenable := false
+  var walk func(*shimast.Node)
+  walk = func(n *shimast.Node) {
+    if thenable || n == nil {
+      return
+    }
+    if n != body && isFunctionLikeKind(n) {
+      return
+    }
+    if n.Kind == shimast.KindReturnStatement {
+      if stmt := n.AsReturnStatement(); stmt != nil && requireAwaitExpressionIsThenable(ctx, stmt.Expression) {
+        thenable = true
+        return
+      }
+    }
+    n.ForEachChild(func(child *shimast.Node) bool {
+      walk(child)
+      return false
+    })
+  }
+  walk(body)
+  return thenable
+}
+
+// requireAwaitExpressionIsThenable classifies one returned expression with the
+// same awaitability test `await-thenable` uses, so the two rules agree on what
+// counts as a promise. Anything the classifier does not rule out entirely is
+// treated as thenable: the exemption must not depend on proving a union is
+// thenable in every branch.
+func requireAwaitExpressionIsThenable(ctx *Context, expr *shimast.Node) bool {
+  if expr == nil {
+    return false
+  }
+  t := ctx.Checker.GetTypeAtLocation(expr)
+  if t == nil {
+    return false
+  }
+  return classifyPromiseAwaitability(ctx.Checker, expr, t) != promiseAwaitabilityNever
+}