@ttsc/lint 0.12.3 → 0.13.0

package/linthost/directives.go

@@ -1,3 +1,10 @@
+// Inline-disable directive parser and filter for the lint engine.
+//
+// Supports both `eslint-disable` and `lint-disable` comment families in
+// four forms: `disable`, `enable`, `disable-line`, and
+// `disable-next-line`. Rule lists are comma- or space-separated; an
+// empty list disables all rules. The `--` description separator (ESLint
+// convention) is also recognized and stripped before parsing rule names.
 package linthost
 
 import (
@@ -7,36 +14,61 @@ import (
   shimscanner "github.com/microsoft/typescript-go/shim/scanner"
 )
 
+// lintDirectiveKind classifies the four comment forms the parser recognizes.
 type lintDirectiveKind int
 
 const (
+  // lintDirectiveDisable activates suppression from the comment position until
+  // a matching `enable` is seen (or end of file).
   lintDirectiveDisable lintDirectiveKind = iota
+  // lintDirectiveEnable cancels a prior `disable` for the named rules (or all
+  // rules when no rule list is given).
   lintDirectiveEnable
+  // lintDirectiveDisableLine suppresses findings on the same source line as
+  // the directive comment.
   lintDirectiveDisableLine
+  // lintDirectiveDisableNextLine suppresses findings on the line immediately
+  // following the directive comment.
   lintDirectiveDisableNextLine
 )
 
+// lintDirective is the parsed representation of one directive comment.
 type lintDirective struct {
   kind  lintDirectiveKind
   rules lintDirectiveRules
 }
 
+// lintDirectiveRules holds the rule scope of a directive. When `all` is
+// true the directive applies to every rule; otherwise only the named rules
+// in `rules` are affected.
 type lintDirectiveRules struct {
   all   bool
   rules map[string]struct{}
 }
 
+// lintDirectiveEvent is one enable/disable transition recorded in source
+// order. `pos` is the byte offset of the comment. `on` is true for a
+// disable event and false for an enable event.
 type lintDirectiveEvent struct {
   pos   int
   rules lintDirectiveRules
   on    bool
 }
 
+// lintInlineDirectives accumulates the per-file directive information
+// extracted by parseLintInlineDirectives. `lines` maps a zero-based line
+// number to any disable-line / disable-next-line directives on that line.
+// `events` is the ordered list of range-style disable/enable transitions.
 type lintInlineDirectives struct {
   lines  map[int][]lintDirectiveRules
   events []lintDirectiveEvent
 }
 
+// lintDisableState tracks the cumulative suppress/allow state as
+// lintDirectiveEvents are replayed in order up to a finding's position.
+// `all` means every rule is suppressed. `rules` is the set of individually
+// suppressed rules. `enabledInAll` is the set of rules that were
+// re-enabled via `eslint-enable <rule>` while `all` was active.
 type lintDisableState struct {
   all          bool
   rules        map[string]struct{}
@@ -60,6 +92,21 @@ func filterInlineDisabledFindings(file *shimast.SourceFile, findings []*Finding)
   return filtered
 }
 
+// parseLintInlineDirectives scans all comment tokens in `file` for
+// recognized directive markers and returns a structured summary of the
+// per-line and range-style suppressions found.
+//
+// The raw scanner does not split `KindTemplateExpression` on its own:
+// after returning `KindTemplateHead`/`KindTemplateMiddle`, it resumes
+// lexing the substitution as ordinary code, and a later `}` is reported
+// as `KindCloseBraceToken` instead of re-entering the template body.
+// Without intervention the next backtick would open a fresh template
+// scan that swallows the rest of the file (including every disable
+// directive comment) as one runaway unterminated literal. The parser
+// avoids this by calling `ReScanTemplateToken` on the matching `}`;
+// this loop mirrors that behavior with a brace-depth stack so comment
+// positions stay aligned with the source bytes past any template
+// substitution.
 func parseLintInlineDirectives(file *shimast.SourceFile) *lintInlineDirectives {
   directives := &lintInlineDirectives{
     lines: make(map[int][]lintDirectiveRules),
@@ -68,12 +115,44 @@ func parseLintInlineDirectives(file *shimast.SourceFile) *lintInlineDirectives {
   scanner.SetText(file.Text())
   scanner.SetSkipTrivia(false)
 
+  // templateBraceDepth tracks `{` nesting inside each open template
+  // substitution. A zero on top means the next `}` matches the original
+  // `${` and must be re-scanned as a template middle/tail token.
+  var templateBraceDepth []int
+
 scan:
   for {
     kind := scanner.Scan()
     switch kind {
     case shimast.KindEndOfFile:
       break scan
+    case shimast.KindTemplateHead, shimast.KindTemplateMiddle:
+      // Entering a `${...}` substitution; account for its closing `}`.
+      templateBraceDepth = append(templateBraceDepth, 0)
+      continue
+    case shimast.KindOpenBraceToken:
+      if n := len(templateBraceDepth); n > 0 {
+        templateBraceDepth[n-1]++
+      }
+      continue
+    case shimast.KindCloseBraceToken:
+      n := len(templateBraceDepth)
+      if n == 0 {
+        continue
+      }
+      if templateBraceDepth[n-1] > 0 {
+        templateBraceDepth[n-1]--
+        continue
+      }
+      // Matching `}` for the original `${`. Pop the substitution and
+      // rescan as template; a `KindTemplateMiddle` reopens a new
+      // substitution, a `KindTemplateTail` closes the template literal.
+      templateBraceDepth = templateBraceDepth[:n-1]
+      rescanned := scanner.ReScanTemplateToken(false /*isTaggedTemplate*/)
+      if rescanned == shimast.KindTemplateMiddle {
+        templateBraceDepth = append(templateBraceDepth, 0)
+      }
+      continue
     case shimast.KindSingleLineCommentTrivia, shimast.KindMultiLineCommentTrivia:
     default:
       continue
@@ -111,10 +190,16 @@ scan:
   return directives
 }
 
+// empty reports whether no directives were found in the file, allowing the
+// caller to skip the filtering step entirely.
 func (d *lintInlineDirectives) empty() bool {
   return d == nil || (len(d.lines) == 0 && len(d.events) == 0)
 }
 
+// suppresses reports whether the directive set causes `finding` to be
+// suppressed. It checks the per-line map first (disable-line and
+// disable-next-line directives), then replays the ordered event list to
+// compute the range-style disable/enable state at the finding's position.
 func (d *lintInlineDirectives) suppresses(file *shimast.SourceFile, finding *Finding) bool {
   if d == nil || finding == nil || file == nil {
     return false
@@ -135,6 +220,10 @@ func (d *lintInlineDirectives) suppresses(file *shimast.SourceFile, finding *Fin
   return state.matches(finding.Rule)
 }
 
+// apply updates the disable state by folding in one directive event.
+// Disable events add rules; enable events remove them. When the event
+// targets all rules (`event.rules.all`), the entire state is replaced
+// rather than merged.
 func (s *lintDisableState) apply(event lintDirectiveEvent) {
   if event.on {
     if event.rules.all {
@@ -169,6 +258,9 @@ func (s *lintDisableState) apply(event lintDirectiveEvent) {
   }
 }
 
+// matches reports whether `rule` is currently suppressed given this state.
+// The name is normalized before lookup so that `@typescript-eslint/` prefixes
+// do not prevent a match.
 func (s lintDisableState) matches(rule string) bool {
   normalized := normalizeDirectiveRuleName(rule)
   if _, ok := s.rules[normalized]; ok {
@@ -181,6 +273,9 @@ func (s lintDisableState) matches(rule string) bool {
   return !enabled
 }
 
+// matches reports whether this rule-set covers `rule`. Returns true when the
+// directive targeted all rules or when `rule` (normalized) appears in the
+// named set.
 func (r lintDirectiveRules) matches(rule string) bool {
   if r.all {
     return true
@@ -189,6 +284,9 @@ func (r lintDirectiveRules) matches(rule string) bool {
   return ok
 }
 
+// parseLintDirectiveComment strips comment delimiters from `raw` and
+// delegates to parseLintDirectiveLine. Returns (zero, false) when the
+// comment does not contain a recognized directive marker.
 func parseLintDirectiveComment(raw string) (lintDirective, bool) {
   text := stripCommentDelimiters(raw)
   if directive, ok := parseLintDirectiveLine(text); ok {
@@ -197,6 +295,9 @@ func parseLintDirectiveComment(raw string) (lintDirective, bool) {
   return lintDirective{}, false
 }
 
+// stripCommentDelimiters removes `//` and `/* … */` syntax from `raw` and
+// returns the trimmed inner text. Handles JSDoc-style `* ` prefix on the
+// first content line.
 func stripCommentDelimiters(raw string) string {
   switch {
   case strings.HasPrefix(raw, "//"):
@@ -216,6 +317,9 @@ func stripCommentDelimiters(raw string) string {
   }
 }
 
+// parseLintDirectiveLine matches `text` against all recognized directive
+// markers in declaration order (longest suffix first to avoid prefix
+// ambiguity). Returns the first match found or (zero, false) if none match.
 func parseLintDirectiveLine(text string) (lintDirective, bool) {
   for _, prefix := range []string{"eslint", "lint"} {
     for _, form := range []struct {
@@ -241,6 +345,9 @@ func parseLintDirectiveLine(text string) (lintDirective, bool) {
   return lintDirective{}, false
 }
 
+// directivePayload returns the text after `marker` in `text` when `text`
+// starts with `marker` followed by whitespace or end of string. The
+// returned payload is trimmed of leading/trailing whitespace.
 func directivePayload(text, marker string) (string, bool) {
   if !strings.HasPrefix(text, marker) {
     return "", false
@@ -252,6 +359,9 @@ func directivePayload(text, marker string) (string, bool) {
   return strings.TrimSpace(rest), true
 }
 
+// parseDirectiveRules converts the payload (the text after the directive
+// marker) into a lintDirectiveRules value. The `--` separator strips an
+// optional human-readable description. An empty rule list means "all rules".
 func parseDirectiveRules(payload string) lintDirectiveRules {
   payload = stripDirectiveDescription(payload)
   payload = strings.ReplaceAll(payload, ",", " ")
@@ -272,6 +382,10 @@ func parseDirectiveRules(payload string) lintDirectiveRules {
   return lintDirectiveRules{rules: rules}
 }
 
+// stripDirectiveDescription returns the portion of `payload` before the
+// first ` -- ` token (ESLint's description separator). The separator must
+// be surrounded by whitespace or be at a string boundary to avoid
+// stripping `--` from rule names like `no--foo`.
 func stripDirectiveDescription(payload string) string {
   for i := 0; i < len(payload)-1; i++ {
     if payload[i] != '-' || payload[i+1] != '-' {
@@ -287,6 +401,8 @@ func stripDirectiveDescription(payload string) string {
   return payload
 }
 
+// normalizeDirectiveRuleName strips the common ESLint namespace prefixes so
+// both `@typescript-eslint/no-var` and `no-var` resolve to the same key.
 func normalizeDirectiveRuleName(name string) string {
   name = strings.TrimSpace(name)
   name = strings.TrimPrefix(name, "@typescript-eslint/")

package/linthost/dispatch.go

@@ -7,8 +7,8 @@
 package linthost
 
 import (
-	"fmt"
-	"os"
+  "fmt"
+  "os"
 )
 
 // Version is the build banner string the `version` subcommand prints.
@@ -25,41 +25,41 @@ var Version = "dev"
 // Recognized verbs: `version` / `-v` / `--version`, `check`, `fix`, `format`,
 // `build`, `transform`. Anything else is a usage error (exit code 2).
 func Main(args []string) int {
-	return run(args)
+  return run(args)
 }
 
 // run is the package-local dispatcher invoked by Main and by the in-tree
 // test/command corpus, which exercises end-to-end subcommand routing through
 // the same entry point the CLI uses.
 func run(args []string) int {
-	if len(args) == 0 {
-		fmt.Fprintln(os.Stderr, "@ttsc/lint: command required (expected check|fix|format|build|transform|version)")
-		return 2
-	}
-	switch args[0] {
-	case "-v", "--version", "version":
-		// Don't pay contributor-registration cost for the version banner.
-		fmt.Fprintf(os.Stdout, "@ttsc/lint %s\n", Version)
-		return 0
-	case "check", "fix", "format", "build", "transform":
-	default:
-		fmt.Fprintf(os.Stderr, "@ttsc/lint: unknown command %q\n", args[0])
-		return 2
-	}
-	// Wire contributor rules into the engine's dispatch table after every
-	// package init has settled. See contrib_adapter.go for the rationale.
-	registerContributors()
-	switch args[0] {
-	case "check":
-		return RunCheck(args[1:])
-	case "fix":
-		return RunFix(args[1:])
-	case "format":
-		return RunFormat(args[1:])
-	case "build":
-		return RunBuild(args[1:])
-	case "transform":
-		return RunTransform(args[1:])
-	}
-	return 2
+  if len(args) == 0 {
+    fmt.Fprintln(os.Stderr, "@ttsc/lint: command required (expected check|fix|format|build|transform|version)")
+    return 2
+  }
+  switch args[0] {
+  case "-v", "--version", "version":
+    // Don't pay contributor-registration cost for the version banner.
+    fmt.Fprintf(os.Stdout, "@ttsc/lint %s\n", Version)
+    return 0
+  case "check", "fix", "format", "build", "transform":
+  default:
+    fmt.Fprintf(os.Stderr, "@ttsc/lint: unknown command %q\n", args[0])
+    return 2
+  }
+  // Wire contributor rules into the engine's dispatch table after every
+  // package init has settled. See contrib_adapter.go for the rationale.
+  registerContributors()
+  switch args[0] {
+  case "check":
+    return RunCheck(args[1:])
+  case "fix":
+    return RunFix(args[1:])
+  case "format":
+    return RunFormat(args[1:])
+  case "build":
+    return RunBuild(args[1:])
+  case "transform":
+    return RunTransform(args[1:])
+  }
+  return 2
 }

package/linthost/engine.go

@@ -21,7 +21,9 @@ import (
   "encoding/json"
   "fmt"
   "os"
+  "runtime"
   "sort"
+  "sync"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
   shimchecker "github.com/microsoft/typescript-go/shim/checker"
@@ -62,12 +64,23 @@ type FormatRule interface {
   IsFormat() bool
 }
 
+// typeAwareRule marks rules that need a live TypeScript checker in Context.
+// Rules that do not implement it are assumed AST-only.
+type typeAwareRule interface {
+  NeedsTypeChecker() bool
+}
+
 // isFormatRule reports whether `r` opts into the format category.
 func isFormatRule(r Rule) bool {
   fr, ok := r.(FormatRule)
   return ok && fr.IsFormat()
 }
 
+func ruleNeedsTypeChecker(r Rule) bool {
+  tr, ok := r.(typeAwareRule)
+  return ok && tr.NeedsTypeChecker()
+}
+
 // Context is the per-(file, rule) handle the engine passes to `Check`.
 //
 // `Options` is the raw JSON blob the user wrote in their rule
@@ -184,6 +197,10 @@ func (c *Context) ReportRangeFix(pos, end int, message string, edits ...TextEdit
   })
 }
 
+// cloneTextEdits returns a shallow copy of `edits` so that the caller's
+// variadic slice cannot be mutated through the stored Finding. Returns nil
+// when the input is empty, keeping the Finding.Fix field nil rather than
+// a zero-length slice.
 func cloneTextEdits(edits []TextEdit) []TextEdit {
   if len(edits) == 0 {
     return nil
@@ -230,10 +247,32 @@ func AllRuleNames() []string {
 // Engine binds a rule configuration to a Program and walks the AST once
 // per source file, dispatching each visited node to its interested rules.
 type Engine struct {
-  config  RuleResolver
-  rules   map[shimast.Kind][]Rule
-  enabled map[string]Severity
-  unknown []string
+  config           RuleResolver
+  rules            map[shimast.Kind][]Rule
+  enabled          map[string]Severity
+  unknown          []string
+  needsTypeChecker bool
+  serial           bool
+}
+
+// SetSerial forces Engine.Run to walk files one at a time. The host calls
+// this when `--singleThreaded` reaches the lint sidecar so the benchmark
+// (and any caller that wants a deterministic, low-overhead pass) can opt
+// out of file-level parallelism. Type-aware rule sets always run serial
+// regardless of this flag — the single shared checker is not concurrent —
+// so callers do not need to clear it themselves.
+func (e *Engine) SetSerial(serial bool) {
+  if e == nil {
+    return
+  }
+  e.serial = serial
+}
+
+// runsSerial reports whether Run must walk files one at a time — either
+// because the caller asked for it or because a type-aware rule pins the
+// engine to the shared single checker.
+func (e *Engine) runsSerial() bool {
+  return e == nil || e.serial || e.needsTypeChecker
 }
 
 // NewEngine returns an engine configured for `config`. Rules whose
@@ -262,6 +301,9 @@ func NewEngineWithResolver(config RuleResolver) *Engine {
       eng.unknown = append(eng.unknown, name)
       continue
     }
+    if ruleNeedsTypeChecker(rule) {
+      eng.needsTypeChecker = true
+    }
     eng.enabled[name] = displaySeverities.Severity(name)
     // Dedup kinds per rule so a contributor that accidentally lists the
     // same Kind twice in `Visits()` doesn't end up firing twice per node.
@@ -282,23 +324,76 @@ func NewEngineWithResolver(config RuleResolver) *Engine {
 // have no registered implementation.
 func (e *Engine) UnknownRules() []string { return e.unknown }
 
+// NeedsTypeChecker reports whether any active rule requires Context.Checker.
+func (e *Engine) NeedsTypeChecker() bool {
+  return e != nil && e.needsTypeChecker
+}
+
 // EnabledRules returns the active rule set keyed by name. Mostly for
 // tests + introspection.
 func (e *Engine) EnabledRules() map[string]Severity { return e.enabled }
 
-// Run walks every non-declaration source file in the program and
-// returns the collected findings.
+// Run walks every non-declaration source file in the program and returns
+// the collected findings. By default files are processed in parallel,
+// bounded by `runtime.NumCPU()`; the engine falls back to a serial walk
+// when SetSerial(true) was called or when a type-aware rule is active.
+// Findings are merged in source-file order so the diagnostic stream is
+// deterministic across runs even when the per-file work happens out of
+// order.
 func (e *Engine) Run(files []*shimast.SourceFile, checker *shimchecker.Checker) []*Finding {
-  var findings []*Finding
-  for _, file := range files {
+  if e.runsSerial() {
+    var findings []*Finding
+    for _, file := range files {
+      if file == nil || file.IsDeclarationFile {
+        continue
+      }
+      findings = append(findings, e.runFile(file, checker)...)
+    }
+    return findings
+  }
+
+  perFile := make([][]*Finding, len(files))
+  var wg sync.WaitGroup
+  workers := runtime.NumCPU()
+  if workers < 1 {
+    workers = 1
+  }
+  sem := make(chan struct{}, workers)
+  for i, file := range files {
     if file == nil || file.IsDeclarationFile {
       continue
     }
-    findings = append(findings, e.runFile(file, checker)...)
+    wg.Add(1)
+    sem <- struct{}{}
+    go func(idx int, f *shimast.SourceFile) {
+      defer wg.Done()
+      defer func() { <-sem }()
+      perFile[idx] = e.runFile(f, checker)
+    }(i, file)
+  }
+  wg.Wait()
+
+  total := 0
+  for _, fs := range perFile {
+    total += len(fs)
+  }
+  if total == 0 {
+    return nil
+  }
+  findings := make([]*Finding, 0, total)
+  for _, fs := range perFile {
+    findings = append(findings, fs...)
   }
   return findings
 }
 
+// boundRule pairs an active rule with the Context the engine reuses for
+// every node it dispatches to that rule within one file. See runFile.
+type boundRule struct {
+  rule Rule
+  ctx  *Context
+}
+
 // runFile is the per-file driver. The visitor is allocated once per file
 // to keep the per-node hot path branch-free; it visits children
 // post-order so parents see their already-checked subtrees.
@@ -310,29 +405,53 @@ func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker)
     return collected
   }
   fileRules := resolved.Rules
+  if !hasEnabledFileRules(fileRules) {
+    return collected
+  }
+
+  // Bind every active rule to a Context once per file. A Context's fields
+  // — File, Checker, the file-resolved Severity, the rule's Options blob,
+  // and the format marker — are all invariant across the file's nodes, so
+  // the engine builds them here. The earlier shape allocated a fresh
+  // Context for every (node, rule) pair, which on a large program meant
+  // millions of short-lived heap allocations and the GC pressure they
+  // carry. Rules never mutate their Context, so reuse is safe.
+  byKind := make(map[shimast.Kind][]boundRule, len(e.rules))
+  ctxByRule := make(map[string]*Context, len(e.enabled))
+  for kind, rules := range e.rules {
+    for _, rule := range rules {
+      name := rule.Name()
+      ctx, built := ctxByRule[name]
+      if !built {
+        if severity := fileRules.Severity(name); severity != SeverityOff {
+          ctx = &Context{
+            File:     file,
+            Checker:  checker,
+            Severity: severity,
+            Options:  e.config.RuleOptions(name),
+            rule:     rule,
+            isFormat: isFormatRule(rule),
+            collect:  collect,
+          }
+        }
+        // A nil entry memoizes "off for this file" so a rule registered
+        // for several kinds resolves its severity only once.
+        ctxByRule[name] = ctx
+      }
+      if ctx == nil {
+        continue
+      }
+      byKind[kind] = append(byKind[kind], boundRule{rule: rule, ctx: ctx})
+    }
+  }
 
   var walk func(node *shimast.Node)
   walk = func(node *shimast.Node) {
     if node == nil {
       return
     }
-    if rules, ok := e.rules[node.Kind]; ok {
-      for _, rule := range rules {
-        severity := fileRules.Severity(rule.Name())
-        if severity == SeverityOff {
-          continue
-        }
-        ctx := &Context{
-          File:     file,
-          Checker:  checker,
-          Severity: severity,
-          Options:  e.config.RuleOptions(rule.Name()),
-          rule:     rule,
-          isFormat: isFormatRule(rule),
-          collect:  collect,
-        }
-        runRuleCheck(rule, ctx, node, collect)
-      }
+    for _, bound := range byKind[node.Kind] {
+      runRuleCheck(bound.rule, bound.ctx, node, collect)
     }
     node.ForEachChild(func(child *shimast.Node) bool {
       walk(child)
@@ -344,23 +463,8 @@ func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker)
   // statements explicitly so the file node itself can be inspected by
   // rules (e.g., `ban-ts-comment` reads CommentDirectives off the
   // SourceFile).
-  if rules, ok := e.rules[shimast.KindSourceFile]; ok {
-    for _, rule := range rules {
-      severity := fileRules.Severity(rule.Name())
-      if severity == SeverityOff {
-        continue
-      }
-      ctx := &Context{
-        File:     file,
-        Checker:  checker,
-        Severity: severity,
-        Options:  e.config.RuleOptions(rule.Name()),
-        rule:     rule,
-        isFormat: isFormatRule(rule),
-        collect:  collect,
-      }
-      runRuleCheck(rule, ctx, file.AsNode(), collect)
-    }
+  for _, bound := range byKind[shimast.KindSourceFile] {
+    runRuleCheck(bound.rule, bound.ctx, file.AsNode(), collect)
   }
 
   statements := file.Statements
@@ -377,6 +481,15 @@ func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker)
   return filterInlineDisabledFindings(file, collected)
 }
 
+func hasEnabledFileRules(rules RuleConfig) bool {
+  for _, severity := range rules {
+    if severity != SeverityOff {
+      return true
+    }
+  }
+  return false
+}
+
 // runRuleCheck invokes a rule's `Check` with a `recover()` barrier so a
 // panicking rule does not abort the entire `ttsc fix` / `ttsc check`
 // run. Built-in rules are not expected to panic, but contributor rules