@ttsc/lint 0.18.3 → 0.19.0

package/linthost/contrib_adapter.go

@@ -10,21 +10,32 @@
 // `package main` init functions and the relative order across files in
 // the same package is alphabetical — so we cannot blindly run the
 // contributor wiring from a file-level `init()` and expect built-in
-// registration to have already completed. Instead, `registerContributors`
-// is invoked explicitly from `main.run` after all built-in `init` calls
-// have settled, which makes the collision check meaningful.
+// registration to have already completed. Instead, `registerContributorsOnce`
+// is invoked explicitly from `run` after all built-in `init` calls have
+// settled, which makes the collision check meaningful.
 package linthost
 
 import (
   "fmt"
   "os"
   "sort"
+  "sync"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
 
   "github.com/samchon/ttsc/packages/lint/rule"
 )
 
+var contributorBootstrap sync.Once
+
+// registerContributorsOnce installs the immutable init-time contributor
+// registries exactly once. Main is a reusable library entry and may be called
+// concurrently, so every caller must wait for the same completed bootstrap
+// before constructing an Engine that reads the global rule maps.
+func registerContributorsOnce() {
+  contributorBootstrap.Do(registerContributors)
+}
+
 // registerContributors wraps every contributor rule registered through
 // the public `rule` package into the engine's internal `Rule` interface
 // and pushes it onto the same dispatch table the built-in rules use.
@@ -34,12 +45,23 @@ import (
 // with a stderr warning. The host prefers a deterministic, debuggable
 // outcome over panicking inside startup.
 func registerContributors() {
-  contributors := rule.Registered()
+  registered := rule.Registered()
+  contributors := make([]contributorMetadata, 0, len(registered))
+  for _, contributor := range registered {
+    metadata, err := inspectContributor(contributor)
+    if err != nil {
+      fmt.Fprintf(os.Stderr,
+        "@ttsc/lint: %v; dropping contributor entry\n",
+        err)
+      continue
+    }
+    contributors = append(contributors, metadata)
+  }
   sort.SliceStable(contributors, func(i, j int) bool {
-    return contributors[i].Name() < contributors[j].Name()
+    return contributors[i].name < contributors[j].name
   })
   for _, contributor := range contributors {
-    name := contributor.Name()
+    name := contributor.name
     if name == "" {
       fmt.Fprintln(os.Stderr, "@ttsc/lint: contributor rule with empty name ignored")
       continue
@@ -50,41 +72,122 @@ func registerContributors() {
         name)
       continue
     }
-    if fr, ok := contributor.(rule.FormatRule); ok && fr.IsFormat() {
-      Register(formatContributorAdapter{contributorAdapter{inner: contributor}})
+    adapter := newContributorAdapter(contributor)
+    if contributor.isFormat {
+      Register(formatContributorAdapter{adapter})
       continue
     }
-    Register(contributorAdapter{inner: contributor})
+    Register(adapter)
+  }
+  registerProjectContributors()
+}
+
+// contributorMetadata is the immutable host-side view of a public contributor
+// rule. Every contributor-defined metadata method is evaluated exactly once
+// behind inspectContributor's recover barrier so a broken declaration cannot
+// panic later during registry sorting or engine construction.
+type contributorMetadata struct {
+  inner                  rule.Rule
+  acceptsOptions         bool
+  isFormat               bool
+  name                   string
+  visits                 []shimast.Kind
+  visitsDeclarationFiles bool
+  needsTypeChecker       bool
+}
+
+// inspectContributor evaluates the public rule metadata behind a recover
+// barrier. Check itself is protected separately by runRuleCheck; this function
+// covers the startup methods the engine must call before it can dispatch a
+// node. A panicking contributor is rejected as one entry while the rest of the
+// lint registry remains usable.
+func inspectContributor(contributor rule.Rule) (metadata contributorMetadata, err error) {
+  defer func() {
+    if recovered := recover(); recovered != nil {
+      err = fmt.Errorf("contributor %T metadata panicked: %v", contributor, recovered)
+    }
+  }()
+  metadata = contributorMetadata{
+    inner:                  contributor,
+    acceptsOptions:         true,
+    name:                   contributor.Name(),
+    visits:                 append([]shimast.Kind(nil), contributor.Visits()...),
+    visitsDeclarationFiles: true,
+    needsTypeChecker:       true,
+  }
+  if formatRule, ok := contributor.(rule.FormatRule); ok {
+    metadata.isFormat = formatRule.IsFormat()
+  }
+  if declarationRule, ok := contributor.(rule.DeclarationFileRule); ok {
+    metadata.visitsDeclarationFiles = declarationRule.VisitsDeclarationFiles()
+  }
+  if typeAware, ok := contributor.(rule.TypeAwareRule); ok {
+    metadata.needsTypeChecker = typeAware.NeedsTypeChecker()
+  }
+  if optionsRule, ok := contributor.(rule.OptionsRule); ok {
+    metadata.acceptsOptions = optionsRule.AcceptsTtscLintOptions()
+  }
+  return metadata, nil
+}
+
+// newContributorAdapter builds the engine-facing adapter from metadata already
+// evaluated by inspectContributor, so no adapter method re-enters contributor
+// code after startup. This is the only construction path; a zero-value
+// contributorAdapter carries no usable metadata.
+func newContributorAdapter(metadata contributorMetadata) contributorAdapter {
+  return contributorAdapter{
+    inner:                  metadata.inner,
+    acceptsOptions:         metadata.acceptsOptions,
+    name:                   metadata.name,
+    visits:                 metadata.visits,
+    visitsDeclarationFiles: metadata.visitsDeclarationFiles,
+    needsTypeChecker:       metadata.needsTypeChecker,
   }
 }
 
 // contributorAdapter wraps a public `rule.Rule` so the engine's
-// `Register` accepts it. Forward `Name` and `Visits` directly; bridge
-// `Check` by constructing a `rule.Context` whose `Reporter` calls back
-// into the engine's existing `Context.Report` / `ReportRange`. The
+// `Register` accepts it. Name, Visits, and declaration-file policy are
+// cached by inspectContributor; Check bridges through a `rule.Context`
+// whose `Reporter` calls back into the engine's existing Context.Report /
+// ReportRange. The
 // public `rule.Context` and the engine's internal `Context` share the
 // same shim AST types, so no wrapping / unwrapping of nodes is needed.
 type contributorAdapter struct {
-  inner rule.Rule
+  inner                  rule.Rule
+  acceptsOptions         bool
+  name                   string
+  visits                 []shimast.Kind
+  visitsDeclarationFiles bool
+  needsTypeChecker       bool
 }
 
-// NeedsTypeChecker keeps contributor rules on the historical checker path.
-// The public rule.Context exposes Checker and has no mandatory marker, so the
-// host cannot safely infer that a third-party rule is AST-only.
+// AcceptsTtscLintOptions preserves the public contributor contract:
+// contributors have historically been allowed to decode an arbitrary options
+// blob, so the conservative default is true. A contributor can implement
+// rule.OptionsRule and return false to declare a genuinely optionless rule.
+func (a contributorAdapter) AcceptsTtscLintOptions() bool {
+  return a.acceptsOptions
+}
+
+// NeedsTypeChecker keeps contributor rules on the conservative checker path
+// unless the contributor opts out through the public `rule.TypeAwareRule`
+// marker. The public rule.Context exposes Checker, so the host cannot infer a
+// third-party rule is AST-only — the default is type-aware, and only a rule
+// that explicitly returns false skips the standalone checker and keeps the
+// parallel file walk. The default-true / marker-override policy is applied
+// once in inspectContributor.
 func (a contributorAdapter) NeedsTypeChecker() bool {
-  return true
+  return a.needsTypeChecker
 }
 
 // VisitsDeclarationFiles keeps contributor rules running on declaration
 // files unless the contributor opts out through the public
 // `rule.DeclarationFileRule` marker. Same conservative-default reasoning
 // as NeedsTypeChecker: the host cannot infer a third-party rule's grammar
-// shape, and a wrong skip silently loses findings.
+// shape, and a wrong skip silently loses findings. The default-true /
+// marker-override policy is applied once in inspectContributor.
 func (a contributorAdapter) VisitsDeclarationFiles() bool {
-  if dr, ok := a.inner.(rule.DeclarationFileRule); ok {
-    return dr.VisitsDeclarationFiles()
-  }
-  return true
+  return a.visitsDeclarationFiles
 }
 
 // formatContributorAdapter is the FormatRule-tagged variant of
@@ -98,18 +201,19 @@ type formatContributorAdapter struct {
 
 func (formatContributorAdapter) IsFormat() bool { return true }
 
-func (a contributorAdapter) Name() string           { return a.inner.Name() }
-func (a contributorAdapter) Visits() []shimast.Kind { return a.inner.Visits() }
+func (a contributorAdapter) Name() string           { return a.name }
+func (a contributorAdapter) Visits() []shimast.Kind { return a.visits }
 func (a contributorAdapter) Check(ctx *Context, node *shimast.Node) {
   if ctx == nil {
     return
   }
-  pubCtx := rule.NewContext(
+  pubCtx := rule.NewContextWithProjectResults(
     ctx.File,
     ctx.Checker,
     rule.Severity(ctx.Severity),
     ctx.Options,
     contextReporter{ctx: ctx},
+    ctx.projectResults,
   )
   a.inner.Check(pubCtx, node)
 }

package/linthost/declaration_rules.go

@@ -159,15 +159,16 @@ var declarationFileRuleNames = map[string]bool{
   "functional/type-declaration-immutability": true,
 
   // unicorn/* rules over file names, comments, identifier naming, and
-  // the numeric literals that appear in enum initializers and literal
-  // types.
-  "unicorn/empty-brace-spaces":        true,
-  "unicorn/expiring-todo-comments":    true,
-  "unicorn/filename-case":             true,
-  "unicorn/no-abusive-eslint-disable": true,
-  "unicorn/no-empty-file":             true,
-  "unicorn/no-keyword-prefix":         true,
-  "unicorn/number-literal-case":       true,
-  "unicorn/numeric-separators-style":  true,
-  "unicorn/prevent-abbreviations":     true,
+  // the literals that appear in enum initializers and literal types
+  // (numeric literals, template literal types).
+  "unicorn/consistent-template-literal-escape": true,
+  "unicorn/empty-brace-spaces":                 true,
+  "unicorn/expiring-todo-comments":             true,
+  "unicorn/filename-case":                      true,
+  "unicorn/no-abusive-eslint-disable":          true,
+  "unicorn/no-empty-file":                      true,
+  "unicorn/no-keyword-prefix":                  true,
+  "unicorn/number-literal-case":                true,
+  "unicorn/numeric-separators-style":           true,
+  "unicorn/prevent-abbreviations":              true,
 }

package/linthost/directives.go

@@ -98,28 +98,17 @@ func filterInlineDisabledFindingsWithDirectives(file *shimast.SourceFile, findin
   }
   filtered := findings[:0]
   for _, finding := range findings {
-    if finding == nil || !directives.suppresses(file, finding) {
+    if finding == nil || finding.engineFailure || !directives.suppresses(file, finding) {
       filtered = append(filtered, 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.
+// parseLintInlineDirectives scans all parser-classified comment tokens in
+// `file` (via the shared `forEachCommentToken` loop) for recognized directive
+// markers and returns a structured summary of the per-line and range-style
+// suppressions found.
 func parseLintInlineDirectives(file *shimast.SourceFile) *lintInlineDirectives {
   directives := &lintInlineDirectives{
     lines: make(map[int][]lintDirectiveRules),
@@ -135,58 +124,11 @@ func parseLintInlineDirectives(file *shimast.SourceFile) *lintInlineDirectives {
   if !strings.Contains(text, "-disable") && !strings.Contains(text, "-enable") {
     return directives
   }
-  scanner := shimscanner.NewScanner()
-  scanner.SetText(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
-    }
-    directive, ok := parseLintDirectiveComment(scanner.TokenText())
+  forEachCommentToken(file, func(_ shimast.Kind, start, end int) {
+    directive, ok := parseLintDirectiveComment(text[start:end])
     if !ok {
-      continue
+      return
     }
-    start := scanner.TokenStart()
-    end := scanner.TokenEnd()
     startLine := shimscanner.GetECMALineOfPosition(file, start)
     endLine := startLine
     if end > start {
@@ -217,7 +159,7 @@ scan:
     directives.records = append(directives.records, lintDirectiveRecord{
       ruleList: append([]string(nil), directive.ruleList...),
     })
-  }
+  })
   return directives
 }
 

package/linthost/dispatch.go

@@ -8,6 +8,7 @@ package linthost
 
 import (
   "fmt"
+  "io"
   "os"
 )
 
@@ -29,6 +30,39 @@ func Main(args []string) int {
   return run(args)
 }
 
+// MainWithIO dispatches the browser-owned project commands without consulting
+// process-global stdout or stderr. Native-only mutation and LSP commands retain
+// Main as their CLI entrypoint.
+func MainWithIO(args []string, stdout, stderr io.Writer) int {
+  if stdout == nil {
+    stdout = io.Discard
+  }
+  if stderr == nil {
+    stderr = io.Discard
+  }
+  if len(args) == 0 {
+    fmt.Fprintln(stderr, "@ttsc/lint: command required (expected check|build|transform|version)")
+    return 2
+  }
+  switch args[0] {
+  case "-v", "--version", "version":
+    fmt.Fprintf(stdout, "@ttsc/lint %s\n", Version)
+    return 0
+  case "check":
+    registerContributorsOnce()
+    return RunCheckWithIO(args[1:], stdout, stderr)
+  case "build":
+    registerContributorsOnce()
+    return RunBuildWithIO(args[1:], stdout, stderr)
+  case "transform":
+    registerContributorsOnce()
+    return RunTransformWithIO(args[1:], stdout, stderr)
+  default:
+    fmt.Fprintf(stderr, "@ttsc/lint: command %q is unavailable in the browser host\n", args[0])
+    return 2
+  }
+}
+
 // 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.
@@ -47,9 +81,9 @@ func run(args []string) int {
     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()
+  // Wire init-time contributor rules into the engine's dispatch table once,
+  // after every package init has settled. See contrib_adapter.go.
+  registerContributorsOnce()
   switch args[0] {
   case "check":
     return RunCheck(args[1:])