@ttsc/lint 0.12.3 → 0.13.0

package/linthost/rules_ts_extra.go

@@ -1,8 +1,8 @@
-// Bulk implementation of @typescript-eslint rules that work off the
-// AST alone (no checker, no scope analysis). The set is curated to
-// match the rules `eslint-plugin-typescript`'s recommended preset relies
-// on most heavily — the rest of that plugin's catalog is type-aware and
-// out of scope for v0.
+// Extended @typescript-eslint rules that work off the AST alone (no
+// checker, no scope analysis). Rules here complement the core set in
+// rules_ts.go; the split is by recommendation tier — this file covers
+// rules that appear in typescript-eslint strict, stylistic, or as
+// commonly-requested extras. Each rule is registered in init() below.
 package linthost
 
 import (
@@ -187,6 +187,10 @@ func (noNonNullAssertedOptionalChain) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// containsOptionalChain reports whether node or any of its left-hand
+// sub-expressions uses the optional-chaining operator (?.). Only descends
+// into PropertyAccessExpression, ElementAccessExpression, and
+// CallExpression chains — stops at any other node kind.
 func containsOptionalChain(node *shimast.Node) bool {
   if node == nil {
     return false
@@ -333,6 +337,8 @@ func (preferForOf) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(node, "Prefer a 'for-of' loop instead of a 'for' loop with this simple iteration.")
 }
 
+// isCounterIncrement reports whether node is a prefix or postfix `++`
+// applied to the identifier named counter. Used by prefer-for-of.
 func isCounterIncrement(node *shimast.Node, counter string) bool {
   switch node.Kind {
   case shimast.KindPostfixUnaryExpression:
@@ -501,6 +507,11 @@ func (consistentTypeImports) Check(ctx *Context, node *shimast.Node) {
   ctx.Report(node, "All imports in the declaration are only used as types. Use `import type`.")
 }
 
+// allUsesAreTypeOnly reports whether every reference to any of the given
+// names in the subtree rooted at root occurs inside a type-only position
+// (TypeReferenceNode, TypeAliasDeclaration, InterfaceDeclaration, etc.).
+// A reference inside another ImportDeclaration is skipped entirely.
+// Returns false as soon as a value-position reference is found.
 func allUsesAreTypeOnly(root *shimast.Node, names []string) bool {
   want := map[string]bool{}
   for _, n := range names {
@@ -675,6 +686,9 @@ func (adjacentOverloadSignatures) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// containerMembers returns the direct child member/statement list of a
+// container node (interface, type literal, class, module block, or source
+// file). Returns nil for node kinds that don't have member lists.
 func containerMembers(node *shimast.Node) []*shimast.Node {
   switch node.Kind {
   case shimast.KindInterfaceDeclaration:
@@ -711,6 +725,12 @@ func containerMembers(node *shimast.Node) []*shimast.Node {
   return nil
 }
 
+// overloadName extracts the canonical name and kind of an overloadable
+// member node. Returns (name, kind, true) for method signatures, method
+// declarations, function declarations, call signatures, and construct
+// signatures; otherwise returns ("", 0, false). Call and construct
+// signatures use a synthesized name that includes the kind string so
+// they compare equal only to other signatures of the same shape.
 func overloadName(m *shimast.Node) (string, shimast.Kind, bool) {
   if m == nil {
     return "", 0, false
@@ -737,9 +757,6 @@ func overloadName(m *shimast.Node) (string, shimast.Kind, bool) {
   return "", 0, false
 }
 
-// no-this-alias-helper: shared helpers for ts rules above.
-var _ = struct{}{}
-
 func init() {
   Register(noConfusingNonNullAssertion{})
   Register(noDuplicateEnumValues{})

package/linthost/rules_var.go

@@ -31,7 +31,8 @@ func (noVar) Check(ctx *Context, node *shimast.Node) {
 // prefer-const: flag `let` declarations whose binding is never reassigned.
 // This follows ESLint's core rule for the common AST-local cases. It is
 // intentionally conservative: destructuring and declaration-only `let`
-// variables are skipped until the lint host grows full scope/data-flow state.
+// variables (those without an initializer and not in a for-of/for-in
+// header) are skipped until the lint host grows full scope/data-flow state.
 // ESLint canonical: https://eslint.org/docs/latest/rules/prefer-const
 type preferConst struct{}
 
@@ -70,7 +71,7 @@ func (preferConst) Check(ctx *Context, node *shimast.Node) {
       if expr == nil || expr.OperatorToken == nil || !isAssignmentOperator(expr.OperatorToken.Kind) {
         return
       }
-      for _, name := range bindingIdentifierNames(expr.Left) {
+      for _, name := range assignmentTargetNames(expr.Left) {
         assigned[name] = true
       }
     case shimast.KindPrefixUnaryExpression:
@@ -115,6 +116,10 @@ func (preferConst) Check(ctx *Context, node *shimast.Node) {
   }
 }
 
+// isSingleDeclarationList reports whether the VariableDeclarationList node
+// declares exactly one binding, which is required before the `let` keyword
+// can safely be rewritten to `const` (a multi-binding list shares a single
+// keyword, so replacing just one binding's keyword is not valid).
 func isSingleDeclarationList(node *shimast.Node) bool {
   if node == nil {
     return false
@@ -123,6 +128,14 @@ func isSingleDeclarationList(node *shimast.Node) bool {
   return list != nil && list.Declarations != nil && len(list.Declarations.Nodes) == 1
 }
 
+// isConstEligibleLetDeclaration reports whether a `let` VariableDeclaration
+// node is eligible for prefer-const analysis. A declaration is eligible when:
+//   - it has an initializer (the value is set immediately), or
+//   - it is the loop variable of a for-in or for-of statement (e.g. `for (let k of m)`).
+//
+// For-statement initializers (`for (let i = 0; …)`) are eligible only when
+// the declaration list is a single binding; the loop index is a well-known
+// reassignment target so multi-binding for-statement lists are excluded.
 func isConstEligibleLetDeclaration(node *shimast.Node, decl *shimast.VariableDeclaration) bool {
   if decl.Initializer != nil {
     if node.Parent != nil && node.Parent.Parent != nil && node.Parent.Parent.Kind == shimast.KindForStatement {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/lint",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Reference ttsc plugin: ESLint-style lint rules hosted in the same Program/Checker as the type-check pass.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -33,10 +33,10 @@
     "src"
   ],
   "devDependencies": {
-    "@typescript/native-preview": "7.0.0-dev.20260518.1",
+    "@typescript/native-preview": "7.0.0-dev.20260522.1",
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
-    "ttsc": "0.12.3"
+    "ttsc": "0.13.0"
   },
   "repository": {
     "type": "git",

package/plugin/main.go

@@ -1,6 +1,6 @@
 // Command @ttsc/lint is the native backend for the `@ttsc/lint` plugin.
 //
-// The plugin host (ttsc / ttsx) spawns this binary with one of five
+// The plugin host (ttsc / ttsx) spawns this binary with one of six
 // subcommands:
 //
 //   - `version` / `-v` / `--version` — print the binary banner.
@@ -25,11 +25,11 @@
 package main
 
 import (
-	"os"
+  "os"
 
-	"github.com/samchon/ttsc/packages/lint/linthost"
+  "github.com/samchon/ttsc/packages/lint/linthost"
 )
 
 func main() {
-	os.Exit(linthost.Main(os.Args[1:]))
+  os.Exit(linthost.Main(os.Args[1:]))
 }

package/rule/astutil/astutil.go

@@ -68,6 +68,9 @@ func KeywordStart(file *shimast.SourceFile, node *shimast.Node, keyword string)
   if limit > len(src) {
     limit = len(src)
   }
+  // Scan at most 32 bytes past the trivia-adjusted start. Declaration keywords
+  // ("var", "let", "const", etc.) always appear within the first few bytes of
+  // a node's token range; the cap avoids runaway scanning on malformed nodes.
   for i := pos; i+len(keyword) <= limit && i < pos+32; i++ {
     end = i + len(keyword)
     if strings.HasPrefix(src[i:], keyword) &&
@@ -139,6 +142,15 @@ func TokenRange(file *shimast.SourceFile, node *shimast.Node) (int, int) {
   return pos, end
 }
 
+// isIdentifierPart reports whether the ASCII byte ch can appear inside a
+// JavaScript/TypeScript identifier (letters, digits, underscore, dollar sign).
+// Used to detect word boundaries when searching for keyword tokens so that
+// a search for "let" does not match "letters".
+// Note: this is a byte-level check; non-ASCII identifier characters (e.g.
+// Unicode letters) are treated as non-identifier bytes, which is conservative
+// — the keyword boundary check may produce a false positive only for source
+// files that use non-ASCII characters immediately adjacent to a keyword,
+// an extremely rare pattern in practice.
 func isIdentifierPart(ch byte) bool {
   return (ch >= 'a' && ch <= 'z') ||
     (ch >= 'A' && ch <= 'Z') ||

package/rule/rule.go

@@ -21,30 +21,30 @@
 //
 // Example contributor:
 //
-//	package myrules
+//  package myrules
 //
-//	import (
-//	    shimast "github.com/microsoft/typescript-go/shim/ast"
-//	    "github.com/samchon/ttsc/packages/lint/rule"
-//	)
+//  import (
+//      shimast "github.com/microsoft/typescript-go/shim/ast"
+//      "github.com/samchon/ttsc/packages/lint/rule"
+//  )
 //
-//	func init() { rule.Register(noTodoComment{}) }
+//  func init() { rule.Register(noTodoComment{}) }
 //
-//	type noTodoComment struct{}
+//  type noTodoComment struct{}
 //
-//	func (noTodoComment) Name() string             { return "demo/no-todo-comment" }
-//	func (noTodoComment) Visits() []shimast.Kind   { return []shimast.Kind{shimast.KindSourceFile} }
-//	func (noTodoComment) Check(ctx *rule.Context, node *shimast.Node) {
-//	    // ctx.File, ctx.Checker, ctx.Severity available; ctx.Report(node, msg)
-//	    // or ctx.ReportRange(pos, end, msg) push a finding through the engine.
-//	}
+//  func (noTodoComment) Name() string             { return "demo/no-todo-comment" }
+//  func (noTodoComment) Visits() []shimast.Kind   { return []shimast.Kind{shimast.KindSourceFile} }
+//  func (noTodoComment) Check(ctx *rule.Context, node *shimast.Node) {
+//      // ctx.File, ctx.Checker, ctx.Severity available; ctx.Report(node, msg)
+//      // or ctx.ReportRange(pos, end, msg) push a finding through the engine.
+//  }
 package rule
 
 import (
-	"encoding/json"
+  "encoding/json"
 
-	shimast "github.com/microsoft/typescript-go/shim/ast"
-	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimchecker "github.com/microsoft/typescript-go/shim/checker"
 )
 
 // Severity mirrors the engine's three-level severity ladder. The
@@ -53,31 +53,31 @@ import (
 type Severity int
 
 const (
-	// SeverityOff means the rule is disabled. Engine skips dispatch.
-	SeverityOff Severity = iota
-	// SeverityWarn produces a warning diagnostic (does not change exit
-	// code).
-	SeverityWarn
-	// SeverityError produces an error diagnostic and fails the command.
-	SeverityError
+  // SeverityOff means the rule is disabled. Engine skips dispatch.
+  SeverityOff Severity = iota
+  // SeverityWarn produces a warning diagnostic (does not change exit
+  // code).
+  SeverityWarn
+  // SeverityError produces an error diagnostic and fails the command.
+  SeverityError
 )
 
 // Rule is the contract every contributor rule satisfies. Mirrors the
 // internal host interface so the host can dispatch via a thin adapter
 // without re-implementing the engine.
 type Rule interface {
-	// Name is the identifier users put in their `rules` map.
-	// Conventionally namespaced as "<plugin-namespace>/<rule-name>" to
-	// avoid colliding with built-in rule names.
-	Name() string
+  // Name is the identifier users put in their `rules` map.
+  // Conventionally namespaced as "<plugin-namespace>/<rule-name>" to
+  // avoid colliding with built-in rule names.
+  Name() string
 
-	// Visits returns the AST kinds the rule cares about. The engine only
-	// dispatches to rules that registered for the visited node's kind.
-	Visits() []shimast.Kind
+  // Visits returns the AST kinds the rule cares about. The engine only
+  // dispatches to rules that registered for the visited node's kind.
+  Visits() []shimast.Kind
 
-	// Check is invoked once per relevant node. Use `ctx.Report` /
-	// `ctx.ReportRange` to emit findings.
-	Check(ctx *Context, node *shimast.Node)
+  // Check is invoked once per relevant node. Use `ctx.Report` /
+  // `ctx.ReportRange` to emit findings.
+  Check(ctx *Context, node *shimast.Node)
 }
 
 // FormatRule is an optional marker contributors implement when a rule
@@ -93,20 +93,20 @@ type Rule interface {
 // returning `false` is equivalent to not implementing the interface at
 // all, and the host treats either form the same way.
 type FormatRule interface {
-	Rule
-	IsFormat() bool
+  Rule
+  IsFormat() bool
 }
 
 // Reporter is the engine-supplied callback that records a finding. The
 // host implements this and passes it to `NewContext` when invoking a
 // contributor rule.
 type Reporter interface {
-	// Report records a finding at the given node's source range.
-	Report(node *shimast.Node, message string)
-	// ReportRange records a finding at an explicit byte range inside the
-	// current file. Use this when the rule wants to highlight a
-	// sub-token.
-	ReportRange(pos, end int, message string)
+  // Report records a finding at the given node's source range.
+  Report(node *shimast.Node, message string)
+  // ReportRange records a finding at an explicit byte range inside the
+  // current file. Use this when the rule wants to highlight a
+  // sub-token.
+  ReportRange(pos, end int, message string)
 }
 
 // FixReporter is the optional extension a host implements to receive
@@ -122,8 +122,8 @@ type Reporter interface {
 // a fake that wants the fix path must implement BOTH `ReportFix` and
 // `ReportRangeFix`.
 type FixReporter interface {
-	ReportFix(node *shimast.Node, message string, edits ...TextEdit)
-	ReportRangeFix(pos, end int, message string, edits ...TextEdit)
+  ReportFix(node *shimast.Node, message string, edits ...TextEdit)
+  ReportRangeFix(pos, end int, message string, edits ...TextEdit)
 }
 
 // TextEdit is one byte-range replacement offered by an autofixable finding.
@@ -143,9 +143,9 @@ type FixReporter interface {
 // falls inside a deletion range. Design fixes so each finding emits one
 // contiguous TextEdit covering the entire replacement region.
 type TextEdit struct {
-	Pos  int
-	End  int
-	Text string
+  Pos  int
+  End  int
+  Text string
 }
 
 // Context is the per-(file, rule) handle the engine passes to `Check`.
@@ -153,70 +153,70 @@ type TextEdit struct {
 // contributors call `ctx.Report` / `ctx.ReportRange` directly through
 // this Context rather than touching the reporter.
 type Context struct {
-	// File is the source file currently being walked. Always non-nil
-	// when `Check` is invoked.
-	File *shimast.SourceFile
+  // File is the source file currently being walked. Always non-nil
+  // when `Check` is invoked.
+  File *shimast.SourceFile
 
-	// Checker is the host's tsgo type checker. Available for type-aware
-	// rules; nil-safe enough that AST-only rules can ignore it.
-	Checker *shimchecker.Checker
+  // Checker is the host's tsgo type checker. Available for type-aware
+  // rules; nil-safe enough that AST-only rules can ignore it.
+  Checker *shimchecker.Checker
 
-	// Severity is the rule's resolved severity for this file. Already
-	// filtered by the engine — rules do not need to check for
-	// SeverityOff.
-	Severity Severity
+  // Severity is the rule's resolved severity for this file. Already
+  // filtered by the engine — rules do not need to check for
+  // SeverityOff.
+  Severity Severity
 
-	// Options is the raw JSON blob the user wrote in the second slot of
-	// their `[severity, options]` rule configuration tuple. Nil when the
-	// rule was configured with a bare severity literal. Contributors that
-	// accept options decode the blob into their own struct via
-	// `(*Context).DecodeOptions`.
-	Options json.RawMessage
+  // Options is the raw JSON blob the user wrote in the second slot of
+  // their `[severity, options]` rule configuration tuple. Nil when the
+  // rule was configured with a bare severity literal. Contributors that
+  // accept options decode the blob into their own struct via
+  // `(*Context).DecodeOptions`.
+  Options json.RawMessage
 
-	reporter Reporter
+  reporter Reporter
 }
 
 // NewContext constructs a Context for the engine to pass into a
 // contributor rule's `Check`. Reserved for host code; contributors
 // should not need to call this.
 func NewContext(
-	file *shimast.SourceFile,
-	checker *shimchecker.Checker,
-	severity Severity,
-	options json.RawMessage,
-	reporter Reporter,
+  file *shimast.SourceFile,
+  checker *shimchecker.Checker,
+  severity Severity,
+  options json.RawMessage,
+  reporter Reporter,
 ) *Context {
-	return &Context{
-		File:     file,
-		Checker:  checker,
-		Severity: severity,
-		Options:  options,
-		reporter: reporter,
-	}
+  return &Context{
+    File:     file,
+    Checker:  checker,
+    Severity: severity,
+    Options:  options,
+    reporter: reporter,
+  }
 }
 
 // DecodeOptions unmarshals the rule's options blob into `out`. Returns
 // nil with no side effect when the rule was configured with severity
 // alone, so contributors can write:
 //
-//	var opts myRuleOptions
-//	_ = ctx.DecodeOptions(&opts)
-//	// opts now holds either the user's settings or the zero value.
+//  var opts myRuleOptions
+//  _ = ctx.DecodeOptions(&opts)
+//  // opts now holds either the user's settings or the zero value.
 func (c *Context) DecodeOptions(out interface{}) error {
-	if c == nil || len(c.Options) == 0 {
-		return nil
-	}
-	return json.Unmarshal(c.Options, out)
+  if c == nil || len(c.Options) == 0 {
+    return nil
+  }
+  return json.Unmarshal(c.Options, out)
 }
 
 // Report records a finding at the given node's source range. Silently
 // ignored when severity is `off` (defensive — the engine already filters
 // by severity before invoking Check) or when no reporter is attached.
 func (c *Context) Report(node *shimast.Node, message string) {
-	if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
-		return
-	}
-	c.reporter.Report(node, message)
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
+    return
+  }
+  c.reporter.Report(node, message)
 }
 
 // ReportFix records a finding at the given node's source range with optional
@@ -224,28 +224,28 @@ func (c *Context) Report(node *shimast.Node, message string) {
 // diagnostic without edits.
 // Treat edits as best-effort: design the rule so the diagnostic alone is useful.
 func (c *Context) ReportFix(node *shimast.Node, message string, edits ...TextEdit) {
-	if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
-		return
-	}
-	if len(edits) == 0 {
-		c.reporter.Report(node, message)
-		return
-	}
-	fixer, ok := c.reporter.(FixReporter)
-	if !ok {
-		c.reporter.Report(node, message)
-		return
-	}
-	fixer.ReportFix(node, message, edits...)
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
+    return
+  }
+  if len(edits) == 0 {
+    c.reporter.Report(node, message)
+    return
+  }
+  fixer, ok := c.reporter.(FixReporter)
+  if !ok {
+    c.reporter.Report(node, message)
+    return
+  }
+  fixer.ReportFix(node, message, edits...)
 }
 
 // ReportRange records a finding at an explicit byte range inside the
 // current file.
 func (c *Context) ReportRange(pos, end int, message string) {
-	if c == nil || c.reporter == nil || c.Severity == SeverityOff {
-		return
-	}
-	c.reporter.ReportRange(pos, end, message)
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff {
+    return
+  }
+  c.reporter.ReportRange(pos, end, message)
 }
 
 // ReportRangeFix records a finding at an explicit byte range with optional
@@ -253,19 +253,19 @@ func (c *Context) ReportRange(pos, end int, message string) {
 // diagnostic without edits.
 // Treat edits as best-effort: design the rule so the diagnostic alone is useful.
 func (c *Context) ReportRangeFix(pos, end int, message string, edits ...TextEdit) {
-	if c == nil || c.reporter == nil || c.Severity == SeverityOff {
-		return
-	}
-	if len(edits) == 0 {
-		c.reporter.ReportRange(pos, end, message)
-		return
-	}
-	fixer, ok := c.reporter.(FixReporter)
-	if !ok {
-		c.reporter.ReportRange(pos, end, message)
-		return
-	}
-	fixer.ReportRangeFix(pos, end, message, edits...)
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff {
+    return
+  }
+  if len(edits) == 0 {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  fixer, ok := c.reporter.(FixReporter)
+  if !ok {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  fixer.ReportRangeFix(pos, end, message, edits...)
 }
 
 var registry []Rule
@@ -275,17 +275,17 @@ var registry []Rule
 // — the host's adapter layer surfaces collisions with a clearer error
 // than a raw panic.
 func Register(r Rule) {
-	if r == nil {
-		panic("rule: Register called with nil rule")
-	}
-	registry = append(registry, r)
+  if r == nil {
+    panic("rule: Register called with nil rule")
+  }
+  registry = append(registry, r)
 }
 
 // Registered returns every contributor rule registered via `Register`.
 // Called once by the host during engine bootstrap. The returned slice is
 // a defensive copy so the host cannot mutate the registry.
 func Registered() []Rule {
-	out := make([]Rule, len(registry))
-	copy(out, registry)
-	return out
+  out := make([]Rule, len(registry))
+  copy(out, registry)
+  return out
 }

package/src/defaultFormat.ts

@@ -1,25 +1,24 @@
 import type { ITtscLintFormatConfig } from "./structures/ITtscLintFormatConfig";
 
 /**
- * Documented defaults for the `format` block's *always-on* rules
+ * Documented defaults for the `format` block's _always-on_ rules
  * (`format/semi`, `format/quotes`, `format/trailing-comma`,
  * `format/print-width`).
  *
  * Exported so users can spread defaults next to overrides:
  *
- *   import { defaultFormat, type ITtscLintConfig } from "@ttsc/lint";
+ * Import { defaultFormat, type ITtscLintConfig } from "@ttsc/lint";
  *
- *   export default {
- *     format: { ...defaultFormat, printWidth: 100 },
- *   } satisfies ITtscLintConfig;
+ * Export default { format: { ...defaultFormat, printWidth: 100 }, } satisfies
+ * ITtscLintConfig;
  *
- * The values mirror Prettier 1:1 except for the documented
- * `endOfLine` narrowing (no `"cr"` / `"auto"`).
+ * The values mirror Prettier 1:1 except for the documented `endOfLine`
+ * narrowing (no `"cr"` / `"auto"`).
  *
- * Notably absent: `importOrder` and `jsdoc`. `format/sort-imports`
- * and `format/jsdoc` are opt-in by setting their corresponding
- * fields; the defaults const only seeds the rules that turn on
- * unconditionally with a non-empty `format` block.
+ * Notably absent: `importOrder` and `jsdoc`. `format/sort-imports` and
+ * `format/jsdoc` are opt-in by setting their corresponding fields; the defaults
+ * const only seeds the rules that turn on unconditionally with a non-empty
+ * `format` block.
  */
 export const defaultFormat = Object.freeze({
   severity: "off",