@ttsc/lint 0.13.1 → 0.14.0-dev.20260528

package/linthost/rules_ts_no_deprecated.go

@@ -0,0 +1,195 @@
+// typescript/no-deprecated: flag references to declarations annotated
+// `@deprecated` in their JSDoc. The deprecation marker is the API
+// owner's signal that a binding is on its way out; callers that keep
+// reaching for it accumulate work to undo later, and the rule surfaces
+// the dependency at the reference site. typescript-eslint:
+// https://typescript-eslint.io/rules/no-deprecated/
+//
+// Type-aware. The rule visits the AST kinds that name a symbol —
+// bare identifiers, property-access expressions, call / new
+// expressions, and JSX opening / self-closing tag names — and asks the
+// Checker for the symbol at the reference location. When any of the
+// symbol's declarations carries a `@deprecated` JSDoc tag (attached
+// either to the declaration itself or to its declaration block — e.g.
+// JSDoc on a VariableStatement covers the inner VariableDeclaration),
+// the rule reports at the reference with the deprecation comment when
+// one is present.
+//
+// To avoid double-firing and silencing the deprecation site itself:
+//
+//   - identifiers at a declaration-name position (`function foo`,
+//     `const foo`, `class Foo`, …) are skipped — they are the marker,
+//     not a reference;
+//   - the bare-identifier arm reports the canonical reference position
+//     for property-access tails, JSX tag names, and call / new callees,
+//     so the CallExpression, NewExpression, PropertyAccessExpression,
+//     and JSX-element arms register only to keep the rule honest about
+//     what it inspects — they don't report a second time.
+package linthost
+
+import (
+	"strings"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type noDeprecated struct{}
+
+func (noDeprecated) Name() string { return "typescript/no-deprecated" }
+func (noDeprecated) NeedsTypeChecker() bool {
+	return true
+}
+func (noDeprecated) Visits() []shimast.Kind {
+	return []shimast.Kind{
+		shimast.KindIdentifier,
+		shimast.KindPropertyAccessExpression,
+		shimast.KindCallExpression,
+		shimast.KindNewExpression,
+		shimast.KindJsxOpeningElement,
+		shimast.KindJsxSelfClosingElement,
+	}
+}
+func (noDeprecated) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	// All non-identifier kinds delegate to the identifier walk for
+	// reporting — they're listed in Visits() to keep the contract
+	// explicit about which structural shapes carry symbol references,
+	// but the actual diagnostic is emitted once per identifier so a
+	// chain like `obj.method()` reports the `method` identifier, not
+	// the surrounding PropertyAccess and CallExpression as well.
+	if node.Kind != shimast.KindIdentifier {
+		return
+	}
+	if noDeprecatedSkipIdentifier(node) {
+		return
+	}
+	symbol := ctx.Checker.GetSymbolAtLocation(node)
+	if symbol == nil {
+		return
+	}
+	tag := findDeprecatedJSDocTag(symbol)
+	if tag == nil {
+		return
+	}
+	// Don't report when this identifier IS the name of one of the
+	// symbol's declarations — that's the deprecation marker itself.
+	if noDeprecatedLocationIsDeclarationName(node, symbol) {
+		return
+	}
+	name := identifierText(node)
+	if name == "" {
+		name = symbol.Name
+	}
+	message := "`" + name + "` is deprecated."
+	if comment := jsdocDeprecatedComment(tag); comment != "" {
+		message = message + " " + comment
+	}
+	ctx.Report(node, message)
+}
+
+// noDeprecatedSkipIdentifier reports whether an identifier visit
+// should be skipped. The skipped positions are:
+//
+//   - the LHS of a QualifiedName (`A.B` — only `B` resolves to the
+//     referenced symbol).
+//
+// The general "is this identifier the declaration name?" gate is
+// applied later against the resolved symbol's declarations — see
+// `noDeprecatedLocationIsDeclarationName` — which handles every
+// declaration kind without enumerating each one here.
+func noDeprecatedSkipIdentifier(node *shimast.Node) bool {
+	parent := node.Parent
+	if parent == nil {
+		return false
+	}
+	if parent.Kind == shimast.KindQualifiedName {
+		qn := parent.AsQualifiedName()
+		if qn != nil && qn.Left == node {
+			return true
+		}
+	}
+	return false
+}
+
+// noDeprecatedLocationIsDeclarationName reports whether `loc` is the
+// name node of one of `symbol`'s declarations — i.e. the deprecation
+// marker itself rather than a reference site.
+func noDeprecatedLocationIsDeclarationName(loc *shimast.Node, symbol *shimast.Symbol) bool {
+	if loc == nil || symbol == nil {
+		return false
+	}
+	for _, decl := range symbol.Declarations {
+		if decl == nil {
+			continue
+		}
+		if decl.Name() == loc {
+			return true
+		}
+	}
+	return false
+}
+
+// findDeprecatedJSDocTag walks the symbol's declarations for a
+// `@deprecated` JSDoc tag and returns the first one found. The walk
+// climbs each declaration's ancestors up to the SourceFile because
+// JSDoc on a VariableDeclaration is attached to the enclosing
+// VariableStatement, and JSDoc on an ExportSpecifier may be on the
+// outer ExportDeclaration.
+func findDeprecatedJSDocTag(symbol *shimast.Symbol) *shimast.Node {
+	if symbol == nil {
+		return nil
+	}
+	for _, decl := range symbol.Declarations {
+		if tag := deprecatedJSDocTagOnNodeOrAncestors(decl); tag != nil {
+			return tag
+		}
+	}
+	return nil
+}
+
+// deprecatedJSDocTagOnNodeOrAncestors walks up from `node` looking for
+// a `@deprecated` JSDoc tag attached to any ancestor. Returns the
+// first matching tag, or nil.
+func deprecatedJSDocTagOnNodeOrAncestors(node *shimast.Node) *shimast.Node {
+	for n := node; n != nil; n = n.Parent {
+		for _, jsdoc := range n.JSDoc(nil) {
+			data := jsdoc.AsJSDoc()
+			if data == nil || data.Tags == nil {
+				continue
+			}
+			for _, tag := range data.Tags.Nodes {
+				if tag.Kind == shimast.KindJSDocDeprecatedTag {
+					return tag
+				}
+			}
+		}
+		if n.Kind == shimast.KindSourceFile {
+			return nil
+		}
+	}
+	return nil
+}
+
+// jsdocDeprecatedComment returns the textual comment that follows the
+// `@deprecated` token in `tag`'s source range, trimmed of surrounding
+// whitespace. Empty when the tag has no comment.
+func jsdocDeprecatedComment(tag *shimast.Node) string {
+	if tag == nil {
+		return ""
+	}
+	src := strings.TrimSpace(shimast.NodeText(tag))
+	if src == "" {
+		return ""
+	}
+	const prefix = "@deprecated"
+	if strings.HasPrefix(src, prefix) {
+		src = src[len(prefix):]
+	}
+	return strings.TrimSpace(src)
+}
+
+func init() {
+	Register(noDeprecated{})
+}

package/linthost/rules_ts_no_for_in_array.go

@@ -0,0 +1,84 @@
+// typescript/no-for-in-array: `for (const k in arr)` iterates the
+// enumerable property NAMES of `arr` — including inherited members and any
+// custom properties someone has attached to `Array.prototype` — and yields
+// them as strings, not as numeric indices. The author almost always meant
+// `for...of` (values) or a plain index loop (numeric keys). typescript-eslint:
+// https://typescript-eslint.io/rules/no-for-in-array/
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+// noForInArray fires on `for (... in <expr>)` when the Checker reports that
+// `<expr>` is an array or tuple type. Type-aware: without a Checker the rule
+// cannot tell an array from a plain record-shaped object, so it bails to
+// avoid false positives. The constituent-recursion shape mirrors
+// `requireArraySortCompareIsArrayLike` — a union like `number[] | string[]`
+// is still array-like because every constituent is.
+type noForInArray struct{}
+
+func (noForInArray) Name() string { return "typescript/no-for-in-array" }
+func (noForInArray) NeedsTypeChecker() bool {
+	return true
+}
+func (noForInArray) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindForInStatement}
+}
+func (noForInArray) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	stmt := node.AsForInOrOfStatement()
+	if stmt == nil || stmt.Expression == nil {
+		return
+	}
+	t := ctx.Checker.GetTypeAtLocation(stmt.Expression)
+	if t == nil {
+		return
+	}
+	if !noForInArrayIsArrayLike(ctx.Checker, t) {
+		return
+	}
+	ctx.Report(node, "Iterating an array with `for...in` yields enumerable property names (as strings), including inherited members. Use `for...of`, `forEach`, or an indexed `for` loop instead.")
+}
+
+// noForInArrayIsArrayLike reports whether t is provably an array or tuple.
+// Mirrors `requireArraySortCompareIsArrayLike`: recurse into union /
+// intersection constituents and consider the whole type array-like only when
+// every constituent is. `any` / `unknown` / `never` are intentionally NOT
+// treated as array-like — they leak from generic helpers and would explode
+// the false-positive volume on otherwise legitimate `for...in` over a
+// genuinely-keyed object.
+func noForInArrayIsArrayLike(checker *shimchecker.Checker, t *shimchecker.Type) bool {
+	if checker == nil || t == nil {
+		return false
+	}
+	flags := t.Flags()
+	if flags&(shimchecker.TypeFlagsAny|shimchecker.TypeFlagsUnknown|shimchecker.TypeFlagsNever) != 0 {
+		return false
+	}
+	if flags&(shimchecker.TypeFlagsUnion|shimchecker.TypeFlagsIntersection) != 0 {
+		for _, part := range t.Types() {
+			if part == nil {
+				continue
+			}
+			if !noForInArrayIsArrayLike(checker, part) {
+				return false
+			}
+		}
+		return true
+	}
+	if shimchecker.Checker_isArrayType(checker, t) {
+		return true
+	}
+	if shimchecker.IsTupleType(t) {
+		return true
+	}
+	return false
+}
+
+func init() {
+	Register(noForInArray{})
+}

package/linthost/rules_ts_no_magic_numbers.go

@@ -0,0 +1,124 @@
+// typescript/no-magic-numbers: TS-aware extension of the core
+// `no-magic-numbers` rule. Numeric literals that appear inline in
+// expressions tend to be unexplained constants — `if (count > 86400)`
+// is opaque, `if (count > SECONDS_PER_DAY)` is not. The rule asks the
+// author to lift those values into a named constant or enum.
+// typescript-eslint:
+// https://typescript-eslint.io/rules/no-magic-numbers/
+//
+// AST-only. The trigger is a `KindNumericLiteral` (or a numeric literal
+// wrapped in a unary `+` / `-`). The TS variant differs from the core
+// rule in one detail that this implementation enforces: numeric
+// literals used as enum member initializers are NOT magic — an
+// `enum Status { OK = 200 }` declaration IS the lifting step the rule
+// pushes authors toward, so flagging the `200` would be backwards.
+//
+// Type-position numeric literals are also skipped: a literal that
+// appears inside a `KindLiteralType` (e.g. `type N = 5`) is a type, not
+// a runtime constant, and the rule's concern is runtime magic numbers.
+// The well-known unit values `-1`, `0`, and `1` pass through because
+// they almost always carry intrinsic meaning (sentinel, identity,
+// step) and treating them as magic produces only noise.
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type tsNoMagicNumbers struct{}
+
+func (tsNoMagicNumbers) Name() string { return "typescript/no-magic-numbers" }
+func (tsNoMagicNumbers) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindNumericLiteral}
+}
+func (tsNoMagicNumbers) Check(ctx *Context, node *shimast.Node) {
+	if node == nil {
+		return
+	}
+	// Identify the surface node that represents the numeric value:
+	// either the literal itself or the wrapping `+lit` / `-lit` unary.
+	surface := node
+	if parent := node.Parent; parent != nil && parent.Kind == shimast.KindPrefixUnaryExpression {
+		prefix := parent.AsPrefixUnaryExpression()
+		if prefix != nil && (prefix.Operator == shimast.KindMinusToken || prefix.Operator == shimast.KindPlusToken) && prefix.Operand == node {
+			surface = parent
+		}
+	}
+	// Skip when the literal lives inside a type position. A literal type
+	// (`type N = 5`, `Array<10>`) is not a runtime constant — the
+	// rule's concern is unexplained runtime values.
+	if isInsideTypePosition(surface) {
+		return
+	}
+	// TS extension: enum member initializers are themselves the named
+	// constant the rule is asking for. `enum S { OK = 200 }` lifts the
+	// value into `S.OK`; flagging the `200` would push authors to
+	// double-wrap an already-named constant.
+	if isEnumMemberInitializer(surface) {
+		return
+	}
+	// Whitelisted unit values: -1 / 0 / 1 carry intrinsic meaning (not
+	// found, identity, step) in almost every codebase. Treating them as
+	// magic produces only noise.
+	if isWellKnownUnitNumber(ctx.File, surface) {
+		return
+	}
+	ctx.Report(surface, "No magic number: extract into a named constant or enum member.")
+}
+
+// isEnumMemberInitializer reports whether surface is the initializer
+// expression of an enum member (`enum X { A = 1 }`). The literal node
+// itself (or its unary wrapper) is the EnumMember.Initializer in that
+// case, which is exactly the position the TS extension whitelists.
+func isEnumMemberInitializer(surface *shimast.Node) bool {
+	parent := surface.Parent
+	if parent == nil || parent.Kind != shimast.KindEnumMember {
+		return false
+	}
+	member := parent.AsEnumMember()
+	return member != nil && member.Initializer == surface
+}
+
+// isInsideTypePosition reports whether `surface` is reached only
+// through type-syntax ancestors before hitting a value-bearing node.
+// Literal types, type arguments, and type aliases are type positions;
+// the rule has nothing to say about literals that never reach runtime.
+func isInsideTypePosition(surface *shimast.Node) bool {
+	for p := surface.Parent; p != nil; p = p.Parent {
+		switch p.Kind {
+		case shimast.KindLiteralType,
+			shimast.KindTypeReference,
+			shimast.KindTypeAliasDeclaration,
+			shimast.KindUnionType,
+			shimast.KindIntersectionType,
+			shimast.KindTypeOperator,
+			shimast.KindIndexedAccessType,
+			shimast.KindMappedType,
+			shimast.KindConditionalType,
+			shimast.KindTypeParameter:
+			return true
+		case shimast.KindPrefixUnaryExpression,
+			shimast.KindParenthesizedExpression:
+			continue
+		}
+		return false
+	}
+	return false
+}
+
+// isWellKnownUnitNumber reports whether `surface` is the literal `0`,
+// `1`, or `-1`. The match is on source text to keep handling of `0.0`
+// vs `0` and `1e0` vs `1` consistent with what the author actually
+// wrote — only the bare textual form is whitelisted.
+func isWellKnownUnitNumber(file *shimast.SourceFile, surface *shimast.Node) bool {
+	text := nodeText(file, surface)
+	switch text {
+	case "0", "1", "-1":
+		return true
+	}
+	return false
+}
+
+func init() {
+	Register(tsNoMagicNumbers{})
+}

package/linthost/rules_ts_no_meaningless_void_operator.go

@@ -0,0 +1,84 @@
+// typescript/no-meaningless-void-operator reports `void X` where the
+// operand `X` is already statically typed `void`. The `void` operator
+// always evaluates to `undefined`; if the operand was going to produce
+// `undefined` anyway, the operator adds nothing and obscures the
+// intent. The most common shape is `void someVoidReturningCall()`
+// somewhere a `void` discard would be useful for a non-void operand
+// (e.g. fire-and-forget Promise) — but a `void`-typed operand is
+// already discarded.
+// https://typescript-eslint.io/rules/no-meaningless-void-operator/
+//
+// Type-aware. Without a Checker the rule cannot tell `void` from any
+// other type, so Context.Checker == nil short-circuits the Check to a
+// no-op the way the other type-aware rules do. The upstream
+// `checkNever` option is left at its default of `false`: only the
+// `void` operand triggers, `never` does not.
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+type noMeaninglessVoidOperator struct{}
+
+func (noMeaninglessVoidOperator) Name() string {
+	return "typescript/no-meaningless-void-operator"
+}
+func (noMeaninglessVoidOperator) NeedsTypeChecker() bool { return true }
+func (noMeaninglessVoidOperator) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindVoidExpression}
+}
+func (noMeaninglessVoidOperator) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	expr := node.AsVoidExpression()
+	if expr == nil || expr.Expression == nil {
+		return
+	}
+	operand := stripParens(expr.Expression)
+	if operand == nil {
+		return
+	}
+	t := ctx.Checker.GetTypeAtLocation(operand)
+	if t == nil {
+		return
+	}
+	if !isVoidOnlyType(t) {
+		return
+	}
+	ctx.Report(node, "The `void` operator on a value already typed `void` adds nothing — drop the operator.")
+}
+
+// isVoidOnlyType reports whether t is the bare `void` type or a union
+// composed entirely of `void` constituents. The upstream rule fires
+// only when the operand carries no non-void member; a mixed `void |
+// number` operand still needs the operator to discard the runtime
+// value, so it is left alone.
+func isVoidOnlyType(t *shimchecker.Type) bool {
+	if t == nil {
+		return false
+	}
+	flags := t.Flags()
+	if flags&shimchecker.TypeFlagsVoid != 0 {
+		return true
+	}
+	if flags&shimchecker.TypeFlagsUnion != 0 {
+		parts := t.Types()
+		if len(parts) == 0 {
+			return false
+		}
+		for _, part := range parts {
+			if !isVoidOnlyType(part) {
+				return false
+			}
+		}
+		return true
+	}
+	return false
+}
+
+func init() {
+	Register(noMeaninglessVoidOperator{})
+}

package/linthost/rules_ts_no_misused_spread.go

@@ -0,0 +1,104 @@
+// AST-only subset of the upstream `typescript/no-misused-spread` rule.
+//
+// The full upstream rule needs the type checker to decide whether the
+// spread operand is actually iterable (or a plain object). This subset
+// catches the three syntactic shapes that are unambiguously wrong even
+// without type information:
+//
+//  1. Object literal spread inside an array literal — `[...{ a: 1 }]`.
+//     Object literals are not iterable, so this is always a TypeError
+//     at runtime.
+//  2. Object literal spread as a call/construct argument —
+//     `f(...{ a: 1 })`, `new Set(...{ a: 1 })`. Same reason: the
+//     callee receives the spread via iteration.
+//  3. Array literal spread inside an object literal — `{ ...[1, 2] }`.
+//     The array's numeric indices become string keys (`"0"`, `"1"`,
+//     …) which is almost never what the author intended.
+//
+// https://typescript-eslint.io/rules/no-misused-spread/
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type noMisusedSpread struct{}
+
+func (noMisusedSpread) Name() string { return "typescript/no-misused-spread" }
+func (noMisusedSpread) Visits() []shimast.Kind {
+	return []shimast.Kind{
+		shimast.KindArrayLiteralExpression,
+		shimast.KindObjectLiteralExpression,
+		shimast.KindCallExpression,
+		shimast.KindNewExpression,
+	}
+}
+func (noMisusedSpread) Check(ctx *Context, node *shimast.Node) {
+	switch node.Kind {
+	case shimast.KindArrayLiteralExpression:
+		arr := node.AsArrayLiteralExpression()
+		if arr == nil || arr.Elements == nil {
+			return
+		}
+		for _, elem := range arr.Elements.Nodes {
+			reportObjectSpreadInIterable(ctx, elem)
+		}
+	case shimast.KindCallExpression:
+		call := node.AsCallExpression()
+		if call == nil || call.Arguments == nil {
+			return
+		}
+		for _, arg := range call.Arguments.Nodes {
+			reportObjectSpreadInIterable(ctx, arg)
+		}
+	case shimast.KindNewExpression:
+		ne := node.AsNewExpression()
+		if ne == nil || ne.Arguments == nil {
+			return
+		}
+		for _, arg := range ne.Arguments.Nodes {
+			reportObjectSpreadInIterable(ctx, arg)
+		}
+	case shimast.KindObjectLiteralExpression:
+		obj := node.AsObjectLiteralExpression()
+		if obj == nil || obj.Properties == nil {
+			return
+		}
+		for _, prop := range obj.Properties.Nodes {
+			if prop == nil || prop.Kind != shimast.KindSpreadAssignment {
+				continue
+			}
+			spread := prop.AsSpreadAssignment()
+			if spread == nil {
+				continue
+			}
+			inner := stripParens(spread.Expression)
+			if inner != nil && inner.Kind == shimast.KindArrayLiteralExpression {
+				ctx.Report(prop, "Spreading an array literal into an object literal coerces numeric indices to string keys — likely a mistake.")
+			}
+		}
+	}
+}
+
+// reportObjectSpreadInIterable reports the spread element when its
+// operand is an object literal in a position that consumes the spread
+// via iteration (array literal element or function/constructor
+// argument).
+func reportObjectSpreadInIterable(ctx *Context, elem *shimast.Node) {
+	if elem == nil || elem.Kind != shimast.KindSpreadElement {
+		return
+	}
+	spread := elem.AsSpreadElement()
+	if spread == nil {
+		return
+	}
+	inner := stripParens(spread.Expression)
+	if inner == nil || inner.Kind != shimast.KindObjectLiteralExpression {
+		return
+	}
+	ctx.Report(elem, "Spread of an object literal into an iterable context is meaningless — object literals are not iterable.")
+}
+
+func init() {
+	Register(noMisusedSpread{})
+}