@ttsc/lint 0.12.3 → 0.13.0

package/linthost/rules_misc.go

@@ -2,8 +2,10 @@ package linthost
 
 import shimast "github.com/microsoft/typescript-go/shim/ast"
 
-// radix: `parseInt(x)` without an explicit radix can hit the legacy
-// "leading 0 means octal" trap. ESLint default mode requires the radix.
+// radix: `parseInt(x)` without an explicit radix argument can trigger
+// implementation-defined octal parsing in older environments. ESLint's
+// default "always" mode requires the second argument and rejects values
+// outside the valid bases {2, 8, 10, 16}.
 // https://eslint.org/docs/latest/rules/radix
 type radix struct{}
 

package/linthost/rules_params.go

@@ -24,9 +24,12 @@ func (defaultParamLast) Check(ctx *Context, node *shimast.Node) {
   if len(params) == 0 {
     return
   }
-  // Walk right-to-left; once we see a parameter without an Initializer
-  // (and not a rest parameter), every earlier parameter that DOES have
-  // an Initializer is misordered.
+  // Walk right-to-left: the first non-default-like parameter sets the
+  // boundary; any default-like parameter to its LEFT is mis-ordered.
+  // "Default-like" includes both initializer-bearing params (`a = 1`)
+  // and optional params (`a?: T`): both let callers elide the argument,
+  // so placing them before a required param forces callers to write
+  // `undefined` explicitly — which defeats the point of both forms.
   sawNonDefaultAfter := false
   for i := len(params) - 1; i >= 0; i-- {
     p := params[i]
@@ -38,16 +41,9 @@ func (defaultParamLast) Check(ctx *Context, node *shimast.Node) {
       continue
     }
     if decl.DotDotDotToken != nil {
-      // Rest parameters are always last by grammar; they don't
-      // participate in the default-position check.
+      // Rest parameters must be last by grammar; skip them.
       continue
     }
-    // typescript-eslint canonical treats both default-initialized and
-    // optional (`a?: T`) parameters as default-like for ordering: both
-    // permit callers to elide the argument, so a non-optional / non-
-    // default parameter after either one forces the caller to spell
-    // `undefined`. The round-1 implementation only checked Initializer;
-    // round 2 adds the QuestionToken branch.
     isDefaultLike := decl.Initializer != nil || decl.QuestionToken != nil
     if !isDefaultLike {
       sawNonDefaultAfter = true

package/linthost/rules_problems.go

@@ -74,7 +74,9 @@ func (noExAssign) Check(ctx *Context, node *shimast.Node) {
 }
 
 // walkAssignments invokes `report` on every `<name> = ...` shape inside
-// `root`. Used by no-ex-assign and friends.
+// `root`. Used by no-ex-assign to scan a single catch block; the
+// file-wide no-func-assign / no-class-assign scans go through
+// reportAssignmentsToDeclarations instead.
 func walkAssignments(root *shimast.Node, name string, report func(*shimast.Node)) {
   if root == nil {
     return
@@ -110,6 +112,8 @@ func (noEmptyCharacterClass) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// hasEmptyCharClass reports whether the regex source text src contains an
+// empty character class (`[]` or `[^]`). Respects backslash escapes.
 func hasEmptyCharClass(src string) bool {
   // Walk the regex literal source manually, respecting escapes.
   for i := 0; i < len(src); i++ {
@@ -143,6 +147,10 @@ func (noMisleadingCharacterClass) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// regexHasSurrogatePair reports whether the regex source text src contains
+// a non-BMP character (code point >= U+10000) inside a character class
+// without the `u` flag. Such characters are stored as surrogate pairs in
+// the source and the class will only match one half of the pair.
 func regexHasSurrogatePair(src string) bool {
   // Strip the trailing flags so we don't misread the `u` flag — it
   // suppresses this rule.
@@ -188,6 +196,10 @@ func (noLossOfPrecision) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// numericLiteralLosesPrecision reports whether the decimal integer literal
+// text exceeds Number.MAX_SAFE_INTEGER (2^53 - 1). Non-decimal literals
+// (hex, octal, binary) and literals with exponents or decimal points are
+// exempt because their precision loss is caller-visible and intentional.
 func numericLiteralLosesPrecision(text string) bool {
   // Strip underscore separators, exponents, decimal/hex/oct/binary
   // markers — for the simple-base-10 integer case the round-trip
@@ -204,7 +216,8 @@ func numericLiteralLosesPrecision(text string) bool {
   if trimmed == "" {
     return false
   }
-  // 2^53 = 9007199254740992; anything larger as an integer literal loses precision.
+  // Number.MAX_SAFE_INTEGER is 2^53-1 = 9007199254740991; 2^53 itself
+  // (9007199254740992) is the first integer that float64 cannot round-trip.
   const maxSafe = "9007199254740992"
   if len(trimmed) < len(maxSafe) {
     return false
@@ -219,38 +232,80 @@ func numericLiteralLosesPrecision(text string) bool {
 type noClassAssign struct{}
 
 func (noClassAssign) Name() string           { return "no-class-assign" }
-func (noClassAssign) Visits() []shimast.Kind { return []shimast.Kind{shimast.KindClassDeclaration} }
+func (noClassAssign) Visits() []shimast.Kind { return []shimast.Kind{shimast.KindSourceFile} }
 func (noClassAssign) Check(ctx *Context, node *shimast.Node) {
-  decl := node.AsClassDeclaration()
-  if decl == nil || decl.Name() == nil {
-    return
-  }
-  name := identifierText(decl.Name())
-  if name == "" {
-    return
-  }
-  walkAssignments(ctx.File.AsNode(), name, func(target *shimast.Node) {
-    ctx.Report(target, "'"+name+"' is a class.")
-  })
+  reportAssignmentsToDeclarations(ctx, node, shimast.KindClassDeclaration, "is a class.")
 }
 
 // no-func-assign: same idea, but for function declarations.
 type noFuncAssign struct{}
 
 func (noFuncAssign) Name() string           { return "no-func-assign" }
-func (noFuncAssign) Visits() []shimast.Kind { return []shimast.Kind{shimast.KindFunctionDeclaration} }
+func (noFuncAssign) Visits() []shimast.Kind { return []shimast.Kind{shimast.KindSourceFile} }
 func (noFuncAssign) Check(ctx *Context, node *shimast.Node) {
-  decl := node.AsFunctionDeclaration()
-  if decl == nil || decl.Name() == nil {
+  reportAssignmentsToDeclarations(ctx, node, shimast.KindFunctionDeclaration, "is a function.")
+}
+
+// reportAssignmentsToDeclarations flags every `<name> = …` assignment whose
+// target identifier names a `declKind` declaration found anywhere in the
+// file. It walks the file exactly once — gathering declared names and
+// assignment targets in the same pass — so the cost is linear in file size.
+//
+// The earlier shape registered for `declKind` directly and, on every
+// declaration, re-scanned the whole file for assignments: O(declarations ×
+// file size), which blows up quadratically on a file with many top-level
+// functions. Visiting `KindSourceFile` once and cross-referencing afterward
+// keeps the same findings without the repeated scans.
+func reportAssignmentsToDeclarations(
+  ctx *Context,
+  file *shimast.Node,
+  declKind shimast.Kind,
+  noun string,
+) {
+  if ctx == nil || file == nil {
     return
   }
-  name := identifierText(decl.Name())
-  if name == "" {
+  declared := map[string]struct{}{}
+  var targets []*shimast.Node
+  walkDescendants(file, func(n *shimast.Node) {
+    switch n.Kind {
+    case declKind:
+      if name := declarationName(n); name != "" {
+        declared[name] = struct{}{}
+      }
+    case shimast.KindBinaryExpression:
+      if expr := n.AsBinaryExpression(); expr != nil &&
+        expr.OperatorToken != nil && isAssignmentOperator(expr.OperatorToken.Kind) &&
+        expr.Left != nil && expr.Left.Kind == shimast.KindIdentifier {
+        targets = append(targets, expr.Left)
+      }
+    }
+  })
+  if len(declared) == 0 || len(targets) == 0 {
     return
   }
-  walkAssignments(ctx.File.AsNode(), name, func(target *shimast.Node) {
-    ctx.Report(target, "'"+name+"' is a function.")
-  })
+  for _, target := range targets {
+    name := identifierText(target)
+    if _, ok := declared[name]; ok {
+      ctx.Report(target, "'"+name+"' "+noun)
+    }
+  }
+}
+
+// declarationName returns the bound name of a class or function declaration
+// node, or "" when the node is neither (or is anonymous).
+func declarationName(n *shimast.Node) string {
+  switch n.Kind {
+  case shimast.KindFunctionDeclaration:
+    if d := n.AsFunctionDeclaration(); d != nil {
+      return identifierText(d.Name())
+    }
+  case shimast.KindClassDeclaration:
+    if d := n.AsClassDeclaration(); d != nil {
+      return identifierText(d.Name())
+    }
+  }
+  return ""
 }
 
 // no-prototype-builtins: `obj.hasOwnProperty(x)` — should be
@@ -351,6 +406,9 @@ func (noControlRegex) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// regexContainsControl reports whether the regex source text src contains a
+// literal control character (U+0000–U+001F, excluding \t, \n, \r) or a
+// \xNN / \uNNNN escape that resolves to a control character.
 func regexContainsControl(src string) bool {
   for i := 0; i < len(src); i++ {
     c := src[i]
@@ -382,6 +440,8 @@ func regexContainsControl(src string) bool {
   return false
 }
 
+// hexDigit converts an ASCII hex byte ('0'-'9', 'a'-'f', 'A'-'F') to its
+// integer value. Returns -1 for non-hex bytes.
 func hexDigit(b byte) int {
   switch {
   case b >= '0' && b <= '9':
@@ -412,6 +472,10 @@ func (noIrregularWhitespace) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isIrregularWhitespace reports whether rune r is a non-standard whitespace
+// character that the TypeScript parser accepts but is almost certainly a
+// copy-paste artifact: vertical tab, form feed, non-breaking space, and the
+// various Unicode space and line separator code points.
 func isIrregularWhitespace(r rune) bool {
   switch r {
   case '\v', '\f',
@@ -458,6 +522,9 @@ func (noFallthrough) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isTerminating reports whether stmt is a statement that unconditionally
+// transfers control out of the current block: break, continue, return,
+// throw, or a block whose last statement is terminating.
 func isTerminating(stmt *shimast.Node) bool {
   if stmt == nil {
     return false

package/linthost/rules_promise.go

@@ -19,6 +19,9 @@ import (
 type awaitThenable struct{}
 
 func (awaitThenable) Name() string { return "await-thenable" }
+func (awaitThenable) NeedsTypeChecker() bool {
+  return true
+}
 func (awaitThenable) Visits() []shimast.Kind {
   return []shimast.Kind{shimast.KindAwaitExpression}
 }
@@ -64,6 +67,15 @@ func (awaitThenable) Check(ctx *Context, node *shimast.Node) {
 // reference to globalPromise, and `GetPropertyOfType` filters `then` as
 // a partial member, so without iterating constituents the rule would
 // fire on legitimate code.
+// isAwaitable reports whether t is safe to await. A type is awaitable when:
+//   - its flags include Any, Unknown, or Never (these escape static strictness);
+//   - it is a Promise (GetPromisedTypeOfPromise returns non-nil); or
+//   - it is thenable (has a callable `then` property).
+//
+// For union and intersection types the function recurses into constituents: if
+// ANY constituent is awaitable the whole type is considered awaitable. This is
+// necessary because GetPromisedTypeOfPromise returns nil on composite types
+// like `Promise<X> | number` even though the expression can legally be awaited.
 func isAwaitable(checker *shimchecker.Checker, t *shimchecker.Type) bool {
   if checker == nil || t == nil {
     return false
@@ -91,6 +103,9 @@ func isAwaitable(checker *shimchecker.Checker, t *shimchecker.Type) bool {
   return isThenableType(checker, t)
 }
 
+// isThenableType reports whether t has a callable `then` property, which is
+// the runtime-observable contract for "thenable" in the ES spec. The check
+// intentionally mirrors what the JS engine uses at await-time.
 func isThenableType(checker *shimchecker.Checker, t *shimchecker.Type) bool {
   if checker == nil || t == nil {
     return false

package/linthost/rules_protos.go

@@ -2,8 +2,9 @@ package linthost
 
 import shimast "github.com/microsoft/typescript-go/shim/ast"
 
-// no-iterator: `obj.__iterator__` is a non-standard SpiderMonkey-era
-// access. Use `Symbol.iterator` instead.
+// no-iterator: accessing `obj.__iterator__` is a non-standard SpiderMonkey-era
+// extension that predates `Symbol.iterator`. Modern code should use
+// `Symbol.iterator` and the iterable protocol instead.
 // https://eslint.org/docs/latest/rules/no-iterator
 type noIterator struct{}
 

package/linthost/rules_self.go

@@ -31,6 +31,10 @@ func (noSelfAssign) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isAssignableLeftHand reports whether node can appear as the left-hand side
+// of a plain assignment expression. Only simple identifier and member-access
+// shapes are checked here; complex destructuring patterns are excluded because
+// a textual equality test would produce too many false negatives.
 func isAssignableLeftHand(node *shimast.Node) bool {
   if node == nil {
     return false
@@ -67,6 +71,8 @@ func (noSelfCompare) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isComparisonOperator reports whether kind is one of the eight standard
+// comparison operators: ==, ===, !=, !==, <, >, <=, >=.
 func isComparisonOperator(kind shimast.Kind) bool {
   switch kind {
   case

package/linthost/rules_strings.go

@@ -22,6 +22,9 @@ func (noTemplateCurlyInString) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// hasTemplatePlaceholder reports whether `text` contains a `${...}`
+// sequence — i.e. at least one `${` followed by a closing `}`. A lone
+// `${` with no matching brace is not flagged.
 func hasTemplatePlaceholder(text string) bool {
   if !strings.Contains(text, "${") {
     return false
@@ -57,6 +60,9 @@ func (noMultiStr) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// hasBackslashLineContinuation reports whether `src` contains a backslash
+// immediately followed by a newline (`\n` or `\r`), which is the raw-source
+// signature of a backslash line-continuation inside a string literal.
 func hasBackslashLineContinuation(src string) bool {
   for i := 0; i < len(src)-1; i++ {
     if src[i] == '\\' {
@@ -89,6 +95,9 @@ func (noUselessConcat) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isStringLikeLiteral reports whether `node` is a string literal or a
+// no-substitution template literal — the two kinds that can be trivially
+// concatenated with `+`.
 func isStringLikeLiteral(node *shimast.Node) bool {
   if node == nil {
     return false
@@ -115,6 +124,7 @@ func (noOctal) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isAsciiDigit reports whether b is an ASCII decimal digit (0–9).
 func isAsciiDigit(b byte) bool { return b >= '0' && b <= '9' }
 
 func init() {

package/linthost/rules_suggestions.go

@@ -7,6 +7,7 @@ import (
   "strings"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
 )
 
 // no-alert: `alert()` / `confirm()` / `prompt()`. Rarely the right
@@ -253,10 +254,15 @@ func (noLoneBlocks) Check(ctx *Context, node *shimast.Node) {
   switch parent.Kind {
   case shimast.KindBlock, shimast.KindSourceFile, shimast.KindModuleBlock:
   default:
+    // Block is the body of a control-flow statement (if/for/while/…) —
+    // those braces are not lone; only report blocks nested inside another
+    // statement list (another Block, SourceFile, or ModuleBlock).
     return
   }
-  // Skip blocks that are themselves a function/method body — those
-  // are tracked by isFunctionLikeKind on the parent.
+  // isFunctionLikeKind returns false for all three parent kinds above
+  // (Block/SourceFile/ModuleBlock are never function-like), so this guard
+  // is a no-op. It is left in place to document intent: if the switch were
+  // ever widened to admit function-body containers, this guard would fire.
   if isFunctionLikeKind(parent) {
     return
   }
@@ -737,16 +743,72 @@ func (noUnneededTernary) Visits() []shimast.Kind {
 }
 func (noUnneededTernary) Check(ctx *Context, node *shimast.Node) {
   cond := node.AsConditionalExpression()
-  if cond == nil {
+  if cond == nil || cond.Condition == nil {
     return
   }
   t := stripParens(cond.WhenTrue)
   f := stripParens(cond.WhenFalse)
   tBool, tOk := isLiteralBoolean(t)
   fBool, fOk := isLiteralBoolean(f)
-  if tOk && fOk && tBool != fBool {
-    ctx.Report(node, "Unnecessary use of conditional expression for boolean.")
+  if !(tOk && fOk && tBool != fBool) {
+    return
+  }
+  message := "Unnecessary use of conditional expression for boolean."
+  src := ctx.File.Text()
+  condStart := shimscanner.SkipTrivia(src, cond.Condition.Pos())
+  if condStart < 0 || condStart >= cond.Condition.End() {
+    ctx.Report(node, message)
+    return
+  }
+  condText := src[condStart:cond.Condition.End()]
+  var replacement string
+  if tBool {
+    // `cond ? true : false` → `Boolean(cond)`
+    replacement = "Boolean(" + condText + ")"
+  } else {
+    // `cond ? false : true` → `!cond`. Wrap the condition in parentheses
+    // when it is not already a primary expression so operator precedence
+    // does not flip the meaning (e.g. `a || b` must become `!(a || b)`).
+    if needsParensForUnaryNegation(cond.Condition) {
+      replacement = "!(" + condText + ")"
+    } else {
+      replacement = "!" + condText
+    }
+  }
+  editPos := shimscanner.SkipTrivia(src, node.Pos())
+  if editPos < 0 || editPos >= node.End() {
+    ctx.Report(node, message)
+    return
+  }
+  ctx.ReportFix(
+    node,
+    message,
+    TextEdit{Pos: editPos, End: node.End(), Text: replacement},
+  )
+}
+
+// needsParensForUnaryNegation reports whether `cond` must be wrapped in
+// parentheses before prefixing with `!`. Anything looser than a unary /
+// member / primary expression flips precedence when negated. Mirrors
+// ESLint's `no-unneeded-ternary` autofix safety check.
+func needsParensForUnaryNegation(node *shimast.Node) bool {
+  inner := stripParens(node)
+  if inner == nil {
+    return false
+  }
+  switch inner.Kind {
+  case shimast.KindBinaryExpression,
+    shimast.KindConditionalExpression,
+    shimast.KindYieldExpression,
+    shimast.KindAwaitExpression,
+    shimast.KindArrowFunction,
+    shimast.KindFunctionExpression,
+    shimast.KindAsExpression,
+    shimast.KindSatisfiesExpression,
+    shimast.KindTypeAssertionExpression:
+    return true
   }
+  return false
 }
 
 // no-unused-expressions: an expression statement whose value isn't used.
@@ -783,8 +845,13 @@ func isProductiveExpression(node *shimast.Node) bool {
     shimast.KindPrefixUnaryExpression,
     shimast.KindPostfixUnaryExpression,
     shimast.KindTaggedTemplateExpression:
-    // These can have side effects. The narrower checks
-    // (no-cond-assign, no-bitwise) handle the suspicious shapes.
+    // Most of these kinds are unconditionally productive (call, new, await,
+    // yield, delete, tagged template). The inner switch narrows the two kinds
+    // that can be non-productive: a BinaryExpression is only productive when
+    // it is an assignment, and a PrefixUnaryExpression is only productive when
+    // it is ++ or --. KindPostfixUnaryExpression is always productive (++ and
+    // -- are the only postfix operators). All un-matched cases reach the
+    // outer `return true` below.
     switch expr.Kind {
     case shimast.KindBinaryExpression:
       bin := expr.AsBinaryExpression()
@@ -1089,9 +1156,27 @@ func (preferTemplate) Check(ctx *Context, node *shimast.Node) {
     }
   }
   hasString, hasOther := concatChainShape(node)
-  if hasString && hasOther {
-    ctx.Report(node, "Unexpected string concatenation.")
+  if !(hasString && hasOther) {
+    return
+  }
+  message := "Unexpected string concatenation."
+  src := ctx.File.Text()
+  operands := flattenConcatOperands(node)
+  template, ok := renderConcatAsTemplate(src, operands)
+  if !ok {
+    ctx.Report(node, message)
+    return
   }
+  editPos := shimscanner.SkipTrivia(src, node.Pos())
+  if editPos < 0 || editPos >= node.End() {
+    ctx.Report(node, message)
+    return
+  }
+  ctx.ReportFix(
+    node,
+    message,
+    TextEdit{Pos: editPos, End: node.End(), Text: template},
+  )
 }
 
 func concatChainShape(node *shimast.Node) (hasString bool, hasOther bool) {
@@ -1112,6 +1197,86 @@ func concatChainShape(node *shimast.Node) (hasString bool, hasOther bool) {
   return false, true
 }
 
+// flattenConcatOperands walks a `+` chain left-to-right and returns each
+// leaf operand in source order. Parenthesized sub-expressions are kept as
+// a single operand so the rendered template literal does not lose their
+// grouping. Mirrors ESLint's behavior of treating `("a" + b)` as one
+// expression slot when it appears inside a larger chain.
+func flattenConcatOperands(node *shimast.Node) []*shimast.Node {
+  if node == nil {
+    return nil
+  }
+  if node.Kind == shimast.KindBinaryExpression {
+    bin := node.AsBinaryExpression()
+    if bin != nil && bin.OperatorToken != nil && bin.OperatorToken.Kind == shimast.KindPlusToken {
+      out := flattenConcatOperands(bin.Left)
+      out = append(out, flattenConcatOperands(bin.Right)...)
+      return out
+    }
+  }
+  return []*shimast.Node{node}
+}
+
+// renderConcatAsTemplate renders the flattened concat operands as a single
+// backtick template literal. String-like literals contribute their value
+// directly (with template-specific escaping); any other expression becomes
+// a `${…}` placeholder copied verbatim from the source text. Returns ok=false
+// when an operand cannot be rendered (typically because its source range is
+// unavailable), so the caller falls back to detection-only.
+func renderConcatAsTemplate(src string, operands []*shimast.Node) (string, bool) {
+  if len(operands) == 0 {
+    return "", false
+  }
+  var sb strings.Builder
+  sb.WriteByte('`')
+  for _, operand := range operands {
+    if operand == nil {
+      return "", false
+    }
+    inner := stripParens(operand)
+    if isStringLikeLiteral(inner) {
+      sb.WriteString(escapeTemplateLiteralBody(stringLiteralText(inner)))
+      continue
+    }
+    pos := shimscanner.SkipTrivia(src, operand.Pos())
+    end := operand.End()
+    if pos < 0 || pos >= end || end > len(src) {
+      return "", false
+    }
+    sb.WriteString("${")
+    sb.WriteString(src[pos:end])
+    sb.WriteByte('}')
+  }
+  sb.WriteByte('`')
+  return sb.String(), true
+}
+
+// escapeTemplateLiteralBody escapes the characters that would otherwise
+// terminate or interpolate a template literal body: backslash, backtick,
+// and the `${` sequence. Matches the canonical ESLint `prefer-template`
+// fixer escape set.
+func escapeTemplateLiteralBody(text string) string {
+  var sb strings.Builder
+  sb.Grow(len(text))
+  for i := 0; i < len(text); i++ {
+    ch := text[i]
+    switch ch {
+    case '\\', '`':
+      sb.WriteByte('\\')
+      sb.WriteByte(ch)
+    case '$':
+      if i+1 < len(text) && text[i+1] == '{' {
+        sb.WriteString("\\$")
+      } else {
+        sb.WriteByte('$')
+      }
+    default:
+      sb.WriteByte(ch)
+    }
+  }
+  return sb.String()
+}
+
 // require-yield: `function* gen() { return 1; }` — generators that
 // never yield are usually unintended.
 type requireYield struct{}

package/linthost/rules_throw.go

@@ -21,6 +21,8 @@ func (noThrowLiteral) Check(ctx *Context, node *shimast.Node) {
     ctx.Report(throw.Expression, "Expected an error object to be thrown.")
     return
   }
+  // `undefined` can appear as either KindUndefinedKeyword (handled above) or
+  // as a plain KindIdentifier whose text is "undefined" — check both forms.
   if id := identifierText(expr); id == "undefined" {
     ctx.Report(throw.Expression, "Expected an error object to be thrown.")
   }

package/linthost/rules_ts.go

@@ -1,3 +1,7 @@
+// Core TypeScript-specific lint rules: direct ports of the most commonly
+// enabled @typescript-eslint/recommended and @typescript-eslint/stylistic
+// rules that require only AST inspection (no checker or scope analysis).
+// Each rule is registered in the package init function at the bottom.
 package linthost
 
 import shimast "github.com/microsoft/typescript-go/shim/ast"
@@ -83,6 +87,10 @@ func (noInferrableTypes) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(typeNode, "Type annotation here is unnecessary.")
 }
 
+// isInferrablePair reports whether typeNode is a type annotation that
+// TypeScript would have inferred automatically from the initializer init.
+// Only covers the scalar literal kinds: string, number, boolean, bigint,
+// null, and undefined.
 func isInferrablePair(typeNode, init *shimast.Node) bool {
   switch typeNode.Kind {
   case shimast.KindStringKeyword:
@@ -101,6 +109,8 @@ func isInferrablePair(typeNode, init *shimast.Node) bool {
   return false
 }
 
+// isUnaryNumeric reports whether node is a unary +/- applied to a numeric
+// literal (e.g. `-1`, `+0`). Used by isInferrablePair for the number case.
 func isUnaryNumeric(node *shimast.Node) bool {
   if node == nil || node.Kind != shimast.KindPrefixUnaryExpression {
     return false
@@ -202,6 +212,9 @@ func (preferAsConst) Check(ctx *Context, node *shimast.Node) {
   )
 }
 
+// literalsMatchSourceText reports whether lhs and rhs are both literal
+// expressions whose source text is identical. Used by prefer-as-const to
+// detect `x as "foo"` where "foo" matches x's literal value.
 func literalsMatchSourceText(file *shimast.SourceFile, lhs, rhs *shimast.Node) bool {
   if lhs == nil || rhs == nil {
     return false