@ttsc/lint 0.18.4 → 0.19.1

package/linthost/rules_ban_ts_comment.go

@@ -0,0 +1,312 @@
+// typescript/ban-ts-comment: a faithful port of typescript-eslint's
+// ban-ts-comment rule, including its recommended defaults, per-directive
+// options, description thresholds, and description-format matching.
+//
+// The rule scans every parser-classified comment token (via
+// forEachCommentToken)
+// instead of reading `SourceFile.CommentDirectives`: the compiler-side
+// list only carries the error-suppression directives (`@ts-expect-error`,
+// `@ts-ignore`) and would miss `@ts-nocheck` / `@ts-check` entirely.
+//
+// Directive recognition mirrors the upstream rule (which in turn mirrors
+// the TypeScript compiler's own regexes):
+//
+//   - `@ts-check` / `@ts-nocheck` are pragmas: line comments with two or
+//     three leading slashes only. Block comments never activate them.
+//   - `@ts-expect-error` / `@ts-ignore` match line comments (any number
+//     of leading slashes) and the LAST line of a block comment — the only
+//     line the compiler honors.
+//   - `@ts-nocheck` is skipped when it appears at or after the first
+//     statement's line, because the compiler ignores it there.
+//
+// Reference: https://typescript-eslint.io/rules/ban-ts-comment
+package linthost
+
+import (
+  "bytes"
+  "encoding/json"
+  "fmt"
+  "regexp"
+  "strings"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
+)
+
+// tsCommentJSWhitespace is the ECMAScript `\s` character class. The
+// upstream regexes run under JavaScript semantics where `\s` covers the
+// Unicode space separators and the BOM; Go's `\s` is ASCII-only, so the
+// class is spelled out to keep the port byte-faithful.
+const tsCommentJSWhitespace = `[\t\n\v\f\r \x{00A0}\x{1680}\x{2000}-\x{200A}\x{2028}\x{2029}\x{202F}\x{205F}\x{3000}\x{FEFF}]`
+
+var (
+  // tsPragmaLineRegex matches the `@ts-check` / `@ts-nocheck` pragma form
+  // against the FULL line-comment text (`//...`): two or three leading
+  // slashes, optional whitespace, then the directive. Mirrors upstream's
+  // singleLinePragmaRegEx applied to `'//' + comment.value`.
+  tsPragmaLineRegex = regexp.MustCompile(`^///?` + tsCommentJSWhitespace + `*@ts-(?P<directive>check|nocheck)(?P<description>.*)$`)
+
+  // tsDirectiveLineRegex matches `@ts-expect-error` / `@ts-ignore` against
+  // a line comment's value (text after the opening `//`): any number of
+  // extra slashes, optional whitespace, then the directive.
+  tsDirectiveLineRegex = regexp.MustCompile(`^/*` + tsCommentJSWhitespace + `*@ts-(?P<directive>expect-error|ignore)(?P<description>.*)`)
+
+  // tsDirectiveBlockRegex matches `@ts-expect-error` / `@ts-ignore`
+  // against the last line of a block comment's value.
+  tsDirectiveBlockRegex = regexp.MustCompile(`^` + tsCommentJSWhitespace + `*(?:/|\*)*` + tsCommentJSWhitespace + `*@ts-(?P<directive>expect-error|ignore)(?P<description>.*)`)
+
+  // tsCommentLineBreakRegex splits block-comment values on the ECMAScript
+  // line terminators (upstream LINEBREAK_MATCHER).
+  tsCommentLineBreakRegex = regexp.MustCompile(`\r\n|[\r\n\x{2028}\x{2029}]`)
+)
+
+// tsCommentDirective is one recognized directive with the raw description
+// text that follows it (untrimmed, exactly as the upstream regex captures
+// it — descriptionFormat patterns match against this raw text).
+type tsCommentDirective struct {
+  directive   string // "check" | "nocheck" | "expect-error" | "ignore"
+  description string
+}
+
+// findTsDirectiveInComment classifies one comment token. `raw` is the full
+// comment text including delimiters. Returns nil when the comment carries
+// no supported directive.
+func findTsDirectiveInComment(kind shimast.Kind, raw string) *tsCommentDirective {
+  if kind == shimast.KindSingleLineCommentTrivia {
+    if match := tsPragmaLineRegex.FindStringSubmatch(raw); match != nil {
+      return &tsCommentDirective{directive: match[1], description: match[2]}
+    }
+    if match := tsDirectiveLineRegex.FindStringSubmatch(raw[2:]); match != nil {
+      return &tsCommentDirective{directive: match[1], description: match[2]}
+    }
+    return nil
+  }
+  // Block comment: only the last line can carry an effective directive,
+  // matching the compiler's scanner (and the upstream rule).
+  value := strings.TrimSuffix(raw[2:], "*/")
+  lines := tsCommentLineBreakRegex.Split(value, -1)
+  if match := tsDirectiveBlockRegex.FindStringSubmatch(lines[len(lines)-1]); match != nil {
+    return &tsCommentDirective{directive: match[1], description: match[2]}
+  }
+  return nil
+}
+
+// tsDirectivePolicy is the normalized evaluation mode for one directive.
+// At most one of `ban` and `requireDescription` is set; `format` is only
+// non-nil when `requireDescription` is set.
+type tsDirectivePolicy struct {
+  ban                bool
+  requireDescription bool
+  format             *regexp.Regexp
+}
+
+// banTsCommentOptions is the raw wire shape of the rule's options object.
+// Directive values stay as raw JSON because each accepts a boolean,
+// the string "allow-with-description", or `{ descriptionFormat }` — the
+// upstream DirectiveConfig union.
+type banTsCommentOptions struct {
+  MinimumDescriptionLength *int            `json:"minimumDescriptionLength"`
+  TsCheck                  json.RawMessage `json:"ts-check"`
+  TsExpectError            json.RawMessage `json:"ts-expect-error"`
+  TsIgnore                 json.RawMessage `json:"ts-ignore"`
+  TsNocheck                json.RawMessage `json:"ts-nocheck"`
+}
+
+// resolvedBanTsCommentOptions is the per-run policy table after merging
+// user options over the upstream recommended defaults.
+type resolvedBanTsCommentOptions struct {
+  minimumDescriptionLength int
+  check                    tsDirectivePolicy
+  expectError              tsDirectivePolicy
+  ignore                   tsDirectivePolicy
+  nocheck                  tsDirectivePolicy
+}
+
+func (o resolvedBanTsCommentOptions) policy(directive string) tsDirectivePolicy {
+  switch directive {
+  case "check":
+    return o.check
+  case "expect-error":
+    return o.expectError
+  case "ignore":
+    return o.ignore
+  case "nocheck":
+    return o.nocheck
+  }
+  return tsDirectivePolicy{}
+}
+
+// resolveBanTsCommentOptions merges the decoded options over the upstream
+// recommended defaults:
+//
+//  {
+//    minimumDescriptionLength: 3,
+//    "ts-check": false,
+//    "ts-expect-error": "allow-with-description",
+//    "ts-ignore": true,
+//    "ts-nocheck": true,
+//  }
+//
+// Absent keys keep their default; present keys replace it wholesale, the
+// same per-key merge ESLint applies to defaultOptions.
+func resolveBanTsCommentOptions(raw banTsCommentOptions) resolvedBanTsCommentOptions {
+  resolved := resolvedBanTsCommentOptions{
+    minimumDescriptionLength: 3,
+    check:                    tsDirectivePolicy{},
+    expectError:              tsDirectivePolicy{requireDescription: true},
+    ignore:                   tsDirectivePolicy{ban: true},
+    nocheck:                  tsDirectivePolicy{ban: true},
+  }
+  if raw.MinimumDescriptionLength != nil {
+    resolved.minimumDescriptionLength = *raw.MinimumDescriptionLength
+  }
+  resolved.check = normalizeTsDirectiveConfig(raw.TsCheck, resolved.check)
+  resolved.expectError = normalizeTsDirectiveConfig(raw.TsExpectError, resolved.expectError)
+  resolved.ignore = normalizeTsDirectiveConfig(raw.TsIgnore, resolved.ignore)
+  resolved.nocheck = normalizeTsDirectiveConfig(raw.TsNocheck, resolved.nocheck)
+  return resolved
+}
+
+// normalizeTsDirectiveConfig turns one raw DirectiveConfig value into a
+// policy. Upstream validates the shape through its JSON schema and rejects
+// the whole config on mismatch; this host has no schema layer, so a value
+// outside the documented union quietly keeps the directive's documented
+// default rather than inventing a stricter policy.
+func normalizeTsDirectiveConfig(raw json.RawMessage, def tsDirectivePolicy) tsDirectivePolicy {
+  if len(raw) == 0 || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
+    return def
+  }
+  var flag bool
+  if json.Unmarshal(raw, &flag) == nil {
+    return tsDirectivePolicy{ban: flag}
+  }
+  var literal string
+  if json.Unmarshal(raw, &literal) == nil {
+    if literal == "allow-with-description" {
+      return tsDirectivePolicy{requireDescription: true}
+    }
+    return def
+  }
+  var object struct {
+    DescriptionFormat *string `json:"descriptionFormat"`
+  }
+  if json.Unmarshal(raw, &object) == nil {
+    // Upstream treats an object without a truthy descriptionFormat as
+    // plain allowance: it neither bans nor demands a description.
+    if object.DescriptionFormat == nil || *object.DescriptionFormat == "" {
+      return tsDirectivePolicy{}
+    }
+    format, err := regexp.Compile(*object.DescriptionFormat)
+    if err != nil {
+      // The format cannot be enforced (upstream would have thrown while
+      // constructing the RegExp). Keep the description-length gate the
+      // object form implies instead of silently allowing everything.
+      return tsDirectivePolicy{requireDescription: true}
+    }
+    return tsDirectivePolicy{requireDescription: true, format: format}
+  }
+  return def
+}
+
+// banTsComment implements typescript/ban-ts-comment.
+type banTsComment struct{ optionsRule }
+
+func (banTsComment) Name() string           { return "typescript/ban-ts-comment" }
+func (banTsComment) Visits() []shimast.Kind { return []shimast.Kind{shimast.KindSourceFile} }
+
+func (banTsComment) Check(ctx *Context, node *shimast.Node) {
+  if ctx.File == nil {
+    return
+  }
+  text := ctx.File.Text()
+  // Cheap short-circuit: every supported directive contains this
+  // substring, so directive-free files skip the comment re-scan entirely
+  // (same strategy as parseLintInlineDirectives).
+  if !strings.Contains(text, "@ts-") {
+    return
+  }
+
+  var raw banTsCommentOptions
+  if err := ctx.DecodeOptions(&raw); err != nil {
+    return
+  }
+  options := resolveBanTsCommentOptions(raw)
+
+  // The compiler only honors `@ts-nocheck` before the first statement;
+  // upstream compares source lines, so a directive on the same line as
+  // the first statement is inert too and stays unreported.
+  firstStatementLine := -1
+  if statements := ctx.File.Statements; statements != nil && len(statements.Nodes) > 0 && statements.Nodes[0] != nil {
+    pos := shimscanner.SkipTrivia(text, statements.Nodes[0].Pos())
+    firstStatementLine = shimscanner.GetECMALineOfPosition(ctx.File, pos)
+  }
+
+  forEachCommentToken(ctx.File, func(kind shimast.Kind, pos, end int) {
+    matched := findTsDirectiveInComment(kind, text[pos:end])
+    if matched == nil {
+      return
+    }
+    if matched.directive == "nocheck" && firstStatementLine >= 0 &&
+      firstStatementLine <= shimscanner.GetECMALineOfPosition(ctx.File, pos) {
+      return
+    }
+
+    policy := options.policy(matched.directive)
+    if policy.ban {
+      if matched.directive == "ignore" {
+        reportTsIgnoreInsteadOfExpectError(ctx, text, pos, end)
+      } else {
+        ctx.ReportRange(pos, end, fmt.Sprintf(
+          "Do not use `@ts-%s` because it alters compilation errors.",
+          matched.directive,
+        ))
+      }
+    }
+    if policy.requireDescription {
+      if stringLength(strings.TrimSpace(matched.description)) < options.minimumDescriptionLength {
+        ctx.ReportRange(pos, end, fmt.Sprintf(
+          "Include a description after the `@ts-%[1]s` directive to explain why the @ts-%[1]s is necessary. The description must be %[2]d characters or longer.",
+          matched.directive, options.minimumDescriptionLength,
+        ))
+      } else if policy.format != nil && !policy.format.MatchString(matched.description) {
+        ctx.ReportRange(pos, end, fmt.Sprintf(
+          "The description for the `@ts-%s` directive must match the %s format.",
+          matched.directive, policy.format.String(),
+        ))
+      }
+    }
+  })
+}
+
+// reportTsIgnoreInsteadOfExpectError reports a banned `@ts-ignore` with the
+// upstream opt-in suggestion: rewrite the first `@ts-ignore` occurrence in
+// the comment body to `@ts-expect-error`. This must not be an autofix because
+// an error-free following line turns the rewrite into compiler error TS2578.
+func reportTsIgnoreInsteadOfExpectError(ctx *Context, text string, pos, end int) {
+  const message = "Use `@ts-expect-error` instead of `@ts-ignore`, as `@ts-ignore` will do nothing if the following line is error-free."
+  // Search the comment body (both `//` and `/*` delimiters are two bytes),
+  // mirroring upstream's comment.value.replace(/@ts-ignore/, ...) which
+  // rewrites the first occurrence in the delimiter-free value.
+  body := text[pos:end]
+  index := strings.Index(body[2:], "@ts-ignore")
+  if index < 0 {
+    ctx.ReportRange(pos, end, message)
+    return
+  }
+  editPos := pos + 2 + index
+  ctx.ReportRangeSuggestion(
+    pos,
+    end,
+    message,
+    "Replace \"@ts-ignore\" with \"@ts-expect-error\".",
+    TextEdit{
+      Pos:  editPos,
+      End:  editPos + len("@ts-ignore"),
+      Text: "@ts-expect-error",
+    },
+  )
+}
+
+func init() {
+  Register(banTsComment{})
+}

package/linthost/rules_boundaries.go

@@ -12,22 +12,11 @@ import (
   shimast "github.com/microsoft/typescript-go/shim/ast"
 )
 
-type boundariesElementTypes struct{}
-type boundariesExternal struct{}
-type boundariesEntryPoint struct{}
-type boundariesNoPrivate struct{}
-type boundariesNoUnknown struct{}
-
-// boundariesDependencies is a v1 stub for the upstream unified
-// `boundaries/dependencies` rule, which replaces the legacy
-// `element-types` / `entry-point` / `external` / `no-private` /
-// `no-unknown` rules with a single direction-aware policy block.
-//
-// The native engine accepts the same `elements` + `rules` config shape so
-// projects can claim the rule id today, but the full direction
-// validation is deferred. Until then this rule registers, decodes
-// options without crashing, and emits no diagnostics.
-type boundariesDependencies struct{}
+type boundariesElementTypes struct{ optionsRule }
+type boundariesExternal struct{ optionsRule }
+type boundariesEntryPoint struct{ optionsRule }
+type boundariesNoPrivate struct{ optionsRule }
+type boundariesNoUnknown struct{ optionsRule }
 
 func (boundariesElementTypes) Name() string { return "boundaries/element-types" }
 func (boundariesExternal) Name() string     { return "boundaries/external" }
@@ -43,15 +32,6 @@ func (boundariesNoPrivate) Visits() []shimast.Kind    { return []shimast.Kind{sh
 func (boundariesNoUnknown) Visits() []shimast.Kind    { return []shimast.Kind{shimast.KindSourceFile} }
 func (boundariesDependencies) Visits() []shimast.Kind { return []shimast.Kind{shimast.KindSourceFile} }
 
-// Check is intentionally a no-op for the v1 stub. The rule accepts the
-// upstream config shape via the shared `boundariesOptions` decoder so
-// downstream configs type-check and load, then exits without reporting
-// findings. Replace this body when the unified direction validation
-// lands.
-func (boundariesDependencies) Check(ctx *Context, node *shimast.Node) {
-  _ = decodeBoundariesOptions(ctx)
-}
-
 func (boundariesElementTypes) Check(ctx *Context, node *shimast.Node) {
   opts := decodeBoundariesOptions(ctx)
   if len(opts.Elements) == 0 {
@@ -236,9 +216,12 @@ type boundaryFile struct {
 }
 
 type boundaryDependency struct {
-  node      *shimast.Node
-  specifier string
-  relative  bool
+  node       *shimast.Node
+  specifier  string
+  relative   bool
+  kind       string
+  nodeKind   string
+  specifiers []string
 }
 
 func decodeBoundariesOptions(ctx *Context) boundariesOptions {
@@ -250,7 +233,28 @@ func decodeBoundariesOptions(ctx *Context) boundariesOptions {
 }
 
 func collectBoundaryDependencies(node *shimast.Node) []boundaryDependency {
+  return collectBoundaryDependenciesWithSyntax(node, false)
+}
+
+func collectBoundaryPolicyDependencies(node *shimast.Node) []boundaryDependency {
+  return collectBoundaryDependenciesWithSyntax(node, true)
+}
+
+func collectBoundaryDependenciesWithSyntax(node *shimast.Node, extended bool) []boundaryDependency {
   out := []boundaryDependency{}
+  appendDependency := func(sourceNode *shimast.Node, specifier, kind, nodeKind string, specifiers []string) {
+    if sourceNode == nil || specifier == "" {
+      return
+    }
+    out = append(out, boundaryDependency{
+      node:       sourceNode,
+      specifier:  specifier,
+      relative:   isRelativeBoundarySpecifier(specifier),
+      kind:       kind,
+      nodeKind:   nodeKind,
+      specifiers: specifiers,
+    })
+  }
   var walk func(*shimast.Node)
   walk = func(n *shimast.Node) {
     if n == nil {
@@ -260,25 +264,85 @@ func collectBoundaryDependencies(node *shimast.Node) []boundaryDependency {
     case shimast.KindImportDeclaration:
       if imp := n.AsImportDeclaration(); imp != nil && imp.ModuleSpecifier != nil {
         specifier := stringLiteralText(imp.ModuleSpecifier)
-        if specifier != "" {
-          out = append(out, boundaryDependency{
-            node:      imp.ModuleSpecifier,
-            specifier: specifier,
-            relative:  isRelativeBoundarySpecifier(specifier),
-          })
-        }
+        names, typeOnly := noRestrictedImportsImportNames(imp)
+        appendDependency(
+          imp.ModuleSpecifier,
+          specifier,
+          boundaryDependencyKind(typeOnly, false),
+          "ImportDeclaration",
+          boundaryImportedNames(names),
+        )
       }
     case shimast.KindExportDeclaration:
       if exp := n.AsExportDeclaration(); exp != nil && exp.ModuleSpecifier != nil {
         specifier := stringLiteralText(exp.ModuleSpecifier)
-        if specifier != "" {
-          out = append(out, boundaryDependency{
-            node:      exp.ModuleSpecifier,
-            specifier: specifier,
-            relative:  isRelativeBoundarySpecifier(specifier),
-          })
+        names, typeOnly := noRestrictedImportsExportNames(nil, n, exp)
+        appendDependency(
+          exp.ModuleSpecifier,
+          specifier,
+          boundaryDependencyKind(typeOnly, false),
+          "ExportDeclaration",
+          boundaryImportedNames(names),
+        )
+      }
+    case shimast.KindImportEqualsDeclaration:
+      if !extended {
+        break
+      }
+      declaration := n.AsImportEqualsDeclaration()
+      if declaration != nil && declaration.ModuleReference != nil &&
+        declaration.ModuleReference.Kind == shimast.KindExternalModuleReference {
+        module := declaration.ModuleReference.AsExternalModuleReference()
+        if module != nil && module.Expression != nil {
+          appendDependency(
+            module.Expression,
+            stringLiteralText(module.Expression),
+            boundaryDependencyKind(declaration.IsTypeOnly, false),
+            "ImportEqualsDeclaration",
+            nil,
+          )
         }
       }
+    case shimast.KindCallExpression:
+      if !extended {
+        break
+      }
+      call := n.AsCallExpression()
+      if call == nil || call.Expression == nil || call.Arguments == nil || len(call.Arguments.Nodes) != 1 {
+        break
+      }
+      argument := call.Arguments.Nodes[0]
+      if argument == nil {
+        break
+      }
+      switch {
+      case call.Expression.Kind == shimast.KindImportKeyword:
+        appendDependency(argument, stringLiteralText(argument), "value", "ImportCall", nil)
+      case identifierText(call.Expression) == "require":
+        appendDependency(argument, stringLiteralText(argument), "value", "RequireCall", nil)
+      }
+    case shimast.KindImportType:
+      if !extended {
+        break
+      }
+      imported := n.AsImportTypeNode()
+      if imported == nil || imported.Argument == nil || imported.Argument.Kind != shimast.KindLiteralType {
+        break
+      }
+      literalType := imported.Argument.AsLiteralTypeNode()
+      if literalType == nil || literalType.Literal == nil {
+        break
+      }
+      appendDependency(
+        literalType.Literal,
+        stringLiteralText(literalType.Literal),
+        // An `import("m")` node in type position resolves types only, so it
+        // is a `type` dependency; the `typeof import("m")` flavor queries the
+        // module's value shape and keeps the dedicated `typeof` kind.
+        boundaryDependencyKind(true, imported.IsTypeOf),
+        "ImportType",
+        nil,
+      )
     }
     n.ForEachChild(func(child *shimast.Node) bool {
       walk(child)
@@ -289,6 +353,26 @@ func collectBoundaryDependencies(node *shimast.Node) []boundaryDependency {
   return out
 }
 
+func boundaryDependencyKind(typeOnly, typeOf bool) string {
+  if typeOf {
+    return "typeof"
+  }
+  if typeOnly {
+    return "type"
+  }
+  return "value"
+}
+
+func boundaryImportedNames(names []noRestrictedImportsImportedName) []string {
+  out := make([]string, 0, len(names))
+  for _, name := range names {
+    if name.name != "" {
+      out = append(out, name.name)
+    }
+  }
+  return uniqueBoundaryStrings(out)
+}
+
 func classifyBoundaryFile(fileName string, elements []boundaryElement) *boundaryFile {
   normalized := normalizeBoundaryPath(fileName)
   matches := []boundaryFile{}
@@ -357,10 +441,10 @@ func resolveBoundaryImport(sourceFileName, specifier string) (string, bool) {
   target := filepath.Clean(filepath.Join(base, filepath.FromSlash(specifier)))
   candidates := []string{target}
   if filepath.Ext(target) == "" {
-    for _, ext := range []string{".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"} {
+    for _, ext := range []string{".ts", ".tsx", ".mts", ".cts", ".d.ts", ".d.mts", ".d.cts", ".js", ".jsx", ".mjs", ".cjs"} {
       candidates = append(candidates, target+ext)
     }
-    for _, ext := range []string{".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"} {
+    for _, ext := range []string{".ts", ".tsx", ".mts", ".cts", ".d.ts", ".d.mts", ".d.cts", ".js", ".jsx", ".mjs", ".cjs"} {
       candidates = append(candidates, filepath.Join(target, "index"+ext))
     }
   }
@@ -499,6 +583,7 @@ func boundaryDisplayPath(path string) string {
 }
 
 func normalizeBoundaryPath(path string) string {
+  path = strings.ReplaceAll(path, `\`, "/")
   return filepath.ToSlash(filepath.Clean(path))
 }