@ttsc/lint 0.12.3 → 0.12.4

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

@@ -73,6 +73,12 @@ const templateValidEscapes = "`'\"\\bfnrtv0xuU$\n\r"
 // — it never deletes a backslash whose meaning could be context-sensitive).
 const regexValidEscapes = "^$\\.*+?()[]{}|/-\n\r"
 
+// 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.
 func reportStringEscapes(ctx *Context, raw string, base int, whitelist string) {
   if len(raw) < 2 {
     return
@@ -117,6 +123,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 +175,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 +193,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')
 }

package/linthost/rules_format_print_width.go

@@ -256,6 +256,9 @@ func hasReflowAncestor(node *shimast.Node) bool {
   return false
 }
 
+// isReflowKind reports whether `k` is one of the node kinds the
+// format/print-width rule visits. Kept in sync with Visits() so
+// hasReflowAncestor does not need to call Visits() at runtime.
 func isReflowKind(k shimast.Kind) bool {
   switch k {
   case shimast.KindObjectLiteralExpression,

package/linthost/rules_format_quotes.go

@@ -25,6 +25,9 @@ import (
 // also intentionally out of scope.
 type formatQuotes struct{}
 
+// formatQuotesOptions mirrors `TtscLintRuleOptions.Quotes`. Prefer accepts
+// `"double"` (the default, enforces double quotes) or `"single"` (enforces
+// single quotes). Any other value is treated as the default.
 type formatQuotesOptions struct {
   Prefer string `json:"prefer"`
 }

package/linthost/rules_format_sort_imports.go

@@ -173,6 +173,8 @@ func loadSortImportsOptions(ctx *Context) resolvedSortImportsOptions {
   }
 }
 
+// hasThirdPartyGroup reports whether at least one group in the list is the
+// third-party catchall. Used to decide whether a sentinel needs to be appended.
 func hasThirdPartyGroup(groups []sortImportsGroup) bool {
   for _, g := range groups {
     if g.thirdParty {
@@ -449,6 +451,8 @@ func reportNamedSpecifierSort(ctx *Context, decl *shimast.Node, caseInsensitive
   )
 }
 
+// joinSortedSpecifiers returns the specifier texts joined with ", " in their
+// already-sorted order. The caller owns the sort; this is a formatting step only.
 func joinSortedSpecifiers(entries []specifierEntry) string {
   texts := make([]string, len(entries))
   for i, e := range entries {

package/linthost/rules_gap.go

@@ -1,3 +1,11 @@
+// Miscellaneous AST-only rules that cover the gap between the core ESLint
+// "Possible Problems" list and the @typescript-eslint strict/stylistic
+// presets: empty static blocks, setter returns, unused labels, dynamic
+// delete, nullish-coalescing with non-null assertions, unnecessary type
+// constraints, unsafe built-in types, wrapper object types, useless
+// constructors, non-literal enum members, type-assertion style, type
+// definition style, dot notation, and unsafe declaration merging.
+// Each rule is registered in init() at the bottom of the file.
 package linthost
 
 import shimast "github.com/microsoft/typescript-go/shim/ast"
@@ -35,6 +43,9 @@ func (noSetterReturn) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(node, "Setter should not return a value.")
 }
 
+// isInsideDirectSetter reports whether node is lexically nested inside a
+// SetAccessor without an intervening function boundary. "Direct" means the
+// return value would actually be a setter return, not a nested callback's.
 func isInsideDirectSetter(node *shimast.Node) bool {
   for p := node.Parent; p != nil; p = p.Parent {
     if p.Kind == shimast.KindSetAccessor {
@@ -99,6 +110,9 @@ func (noDynamicDelete) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(node, "Do not delete dynamically computed property keys.")
 }
 
+// isStaticPropertyKey reports whether node is a literal key that can
+// appear in a delete expression without triggering no-dynamic-delete:
+// string literals, no-substitution template literals, and numeric literals.
 func isStaticPropertyKey(node *shimast.Node) bool {
   node = stripParens(node)
   if node == nil {
@@ -263,6 +277,9 @@ func fileShadowsWrapperName(file *shimast.SourceFile, name string) bool {
   return false
 }
 
+// wrapperPrimitive maps a boxed object type name (e.g. "String") to its
+// primitive keyword equivalent (e.g. "string"). Returns ("", false) for
+// names that are not recognized wrapper types.
 func wrapperPrimitive(name string) (string, bool) {
   switch name {
   case "String":
@@ -365,6 +382,9 @@ func (dotNotation) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(node, "Use dot notation instead of a string literal property access.")
 }
 
+// isSimpleIdentifierName reports whether value is a valid bare identifier
+// (ASCII letters, digits, underscore, dollar sign; digits not first). Used
+// by dot-notation to decide whether bracket access can become dot access.
 func isSimpleIdentifierName(value string) bool {
   if value == "" {
     return false

package/linthost/rules_imports.go

@@ -67,13 +67,11 @@ func (noImportTypeSideEffects) Check(ctx *Context, node *shimast.Node) {
   }
   src := ctx.File.Text()
   for _, spec := range named.Elements.Nodes {
-    // Locate the `type` keyword token at the head of the specifier by
-    // first skipping leading trivia (whitespace + comments). A naive
-    // `findKeyword` would search the byte range linearly and could
-    // match `type` *inside* a leading block comment such as
-    // `/* type alias */`, deleting the comment text and corrupting
-    // the source. SkipTrivia honors the lexer's notion of trivia, so
-    // the post-skip position is the actual first token byte.
+    // Locate the `type` keyword token at the head of each specifier by
+    // skipping leading trivia (whitespace + comments). A naive
+    // findKeyword scan would risk matching `type` inside a block comment
+    // such as `/* type alias */`, corrupting the source. SkipTrivia
+    // anchors the scan at the actual first token byte.
     typePos := shimscanner.SkipTrivia(src, spec.Pos())
     if typePos < 0 || typePos+len("type") > len(src) {
       continue

package/linthost/rules_logic.go

@@ -1,3 +1,8 @@
+// Correctness and equality rules — a focused set from ESLint's "Possible
+// Problems" and "Suggestions" categories that catch logic errors rather than
+// style issues: redundant boolean casts, unsafe negations, loose equality,
+// NaN comparisons, constant conditions, and assignment-in-condition.
+// AST-only, no scope analysis.
 package linthost
 
 import shimast "github.com/microsoft/typescript-go/shim/ast"
@@ -71,6 +76,12 @@ func isInBooleanContext(node *shimast.Node) bool {
   return false
 }
 
+// skipParents walks up through any wrapping ParenthesizedExpression nodes and
+// returns the outermost parenthesized wrapper. This is the inverse of
+// stripParens: where stripParens descends into the canonical inner expression,
+// skipParents climbs up to the outermost paren so that structural parent
+// comparisons (e.g. "is this expression the test of an if?") resolve against
+// the node the parser actually attached as a child, not the inner form.
 func skipParents(node *shimast.Node) *shimast.Node {
   for node != nil && node.Parent != nil && node.Parent.Kind == shimast.KindParenthesizedExpression {
     node = node.Parent

package/linthost/rules_loops.go

@@ -57,6 +57,10 @@ func (forDirection) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// updateDirection returns the direction (+1 for incrementing, -1 for
+// decrementing, 0 for unknown) that the incrementor expression moves the
+// named counter variable. Only simple patterns are recognised: i++, i--,
+// ++i, --i, i += N, and i -= N. Compound or computed expressions return 0.
 func updateDirection(node *shimast.Node, counter string) int {
   if node == nil || counter == "" {
     return 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

@@ -110,6 +110,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 +145,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 +194,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 +214,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
@@ -351,6 +362,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 +396,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 +428,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 +478,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

@@ -64,6 +64,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 +100,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

@@ -253,10 +253,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
   }
@@ -783,8 +788,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()

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