@ttsc/lint 0.13.1 → 0.14.0-dev.20260528.1

package/linthost/rules_ts_prefer_regexp_exec.go

@@ -0,0 +1,122 @@
+// typescript/prefer-regexp-exec: prefer `re.exec(str)` over
+// `str.match(re)` when the regex has no `g` flag. Both shapes return
+// the same `RegExpExecArray | null` for first-match queries, but
+// `String#match` silently switches to "every match" the moment the
+// regex gains the `g` flag — a typo at the regex literal can change
+// the call's return shape from `[fullMatch, ...captures]` to a flat
+// `string[]` of matches. `RegExp#exec` is the stable form.
+// typescript-eslint:
+// https://typescript-eslint.io/rules/prefer-regexp-exec/
+//
+// Type-aware. Without a Checker the rule cannot prove the receiver of
+// `match` is string-like, so Context.Checker == nil short-circuits each
+// Check to a no-op the way `prefer-includes` and
+// `prefer-string-starts-ends-with` do. The argument must be a regex
+// literal — the AST-only baseline reads the flag suffix directly off
+// the token text; non-literal regex arguments (a `new RegExp(...)`,
+// a `const re = /.../` aliased through a variable) are conservatively
+// skipped because static flag tracking would explode in scope.
+package linthost
+
+import (
+	"strings"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+type preferRegexpExec struct{}
+
+func (preferRegexpExec) Name() string { return "typescript/prefer-regexp-exec" }
+func (preferRegexpExec) NeedsTypeChecker() bool {
+	return true
+}
+func (preferRegexpExec) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindCallExpression}
+}
+func (preferRegexpExec) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	call := node.AsCallExpression()
+	if call == nil || call.Expression == nil {
+		return
+	}
+	receiver, method, ok := promisePropertyAccessParts(call.Expression)
+	if !ok || method != "match" {
+		return
+	}
+	if receiver == nil {
+		return
+	}
+	if call.Arguments == nil || len(call.Arguments.Nodes) != 1 {
+		return
+	}
+	arg := stripParens(call.Arguments.Nodes[0])
+	if arg == nil || arg.Kind != shimast.KindRegularExpressionLiteral {
+		return
+	}
+	// Skip when the regex literal carries the `g` flag — `String#match`
+	// returns every match in that mode, which `RegExp#exec` cannot
+	// replicate in a single call.
+	if preferRegexpExecHasGlobalFlag(ctx.File, arg) {
+		return
+	}
+	if !preferRegexpExecIsString(ctx.Checker.GetTypeAtLocation(receiver)) {
+		return
+	}
+	ctx.Report(node, preferRegexpExecMessage)
+}
+
+const preferRegexpExecMessage = "Prefer `RegExp#exec(str)` over `String#match(re)` when the regex has no `g` flag — `exec` returns the same first-match shape and avoids the `g`-flag fallthrough that silently changes the return type of `match`."
+
+// preferRegexpExecHasGlobalFlag reports whether the regex literal at
+// `node` carries the `g` flag. The flag string follows the closing `/`
+// of the literal (e.g. `/foo/gi` has flags `"gi"`); the scanner has
+// already validated the token, so a textual scan of the trailing
+// suffix is sufficient.
+func preferRegexpExecHasGlobalFlag(file *shimast.SourceFile, node *shimast.Node) bool {
+	raw := nodeText(file, node)
+	if len(raw) < 2 || raw[0] != '/' {
+		return false
+	}
+	closing := strings.LastIndexByte(raw, '/')
+	if closing <= 0 {
+		return false
+	}
+	flags := raw[closing+1:]
+	return strings.Contains(flags, "g")
+}
+
+// preferRegexpExecIsString reports whether t is provably string-like.
+// Mirrors `preferStringStartsEndsWithIsString`: `any` / `unknown` /
+// `never` are rejected so generic helpers don't fire. Union and
+// intersection types must have every constituent string-like.
+func preferRegexpExecIsString(t *shimchecker.Type) bool {
+	if t == nil {
+		return false
+	}
+	flags := t.Flags()
+	if flags&(shimchecker.TypeFlagsAny|shimchecker.TypeFlagsUnknown|shimchecker.TypeFlagsNever) != 0 {
+		return false
+	}
+	if flags&shimchecker.TypeFlagsStringLike != 0 {
+		return true
+	}
+	if flags&(shimchecker.TypeFlagsUnion|shimchecker.TypeFlagsIntersection) != 0 {
+		for _, part := range t.Types() {
+			if part == nil {
+				continue
+			}
+			if !preferRegexpExecIsString(part) {
+				return false
+			}
+		}
+		return true
+	}
+	return false
+}
+
+func init() {
+	Register(preferRegexpExec{})
+}

package/linthost/rules_ts_prefer_return_this_type.go

@@ -0,0 +1,135 @@
+// typescript/prefer-return-this-type: when an instance method always
+// `return this`, declare its return type as `this` instead of the
+// enclosing class name. The `this` polymorphic-receiver type keeps the
+// narrower subclass type at the call site so chained calls stay
+// polymorphic: `subclass.fluent().subclassOnly()` only type-checks if
+// `fluent()` is declared `: this` rather than `: Base`.
+// typescript-eslint:
+// https://typescript-eslint.io/rules/prefer-return-this-type/
+//
+// Type-aware. Without a Checker the rule cannot read the method's
+// declared return type or distinguish the class symbol, so
+// Context.Checker == nil short-circuits each Check to a no-op the way
+// other type-aware rules do.
+//
+// Skipped:
+//   - methods whose return type is already `this`;
+//   - methods without an explicit declared return type (the upstream
+//     rule only proposes a narrower annotation when one is already
+//     present — adding a brand-new annotation is the job of
+//     `explicit-function-return-type`);
+//   - constructors, accessors, generators, and `async` methods (each
+//     has return-shape semantics the `this` rewrite does not preserve);
+//   - methods with no body (overload signatures, abstract members);
+//   - methods that have at least one `return X;` where `X` is not the
+//     `this` keyword.
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type preferReturnThisType struct{}
+
+func (preferReturnThisType) Name() string { return "typescript/prefer-return-this-type" }
+func (preferReturnThisType) NeedsTypeChecker() bool {
+	return true
+}
+func (preferReturnThisType) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindMethodDeclaration}
+}
+func (preferReturnThisType) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	decl := node.AsMethodDeclaration()
+	if decl == nil || decl.Body == nil {
+		return
+	}
+	// Skip async / generator methods — their return shape is wrapped
+	// (`Promise<...>` / `Generator<...>`) and not directly `this`.
+	if hasAsyncModifier(node) {
+		return
+	}
+	if decl.AsteriskToken != nil {
+		return
+	}
+	// Skip static methods — the upstream rule targets instance-method
+	// chains where the receiver type is the subclass; static dispatch
+	// uses the class itself and `this` rewriting changes nothing.
+	if hasModifier(node, shimast.KindStaticKeyword) {
+		return
+	}
+	// The method must have an explicit return-type annotation that is
+	// NOT already `this`. The rewrite-target is the existing annotation;
+	// without one, adding `this` would force a new annotation that the
+	// upstream rule does not propose.
+	if decl.Type == nil {
+		return
+	}
+	if decl.Type.Kind == shimast.KindThisType {
+		return
+	}
+	// The enclosing class must exist — the rule applies to instance
+	// methods of class declarations / expressions only.
+	parent := node.Parent
+	if parent == nil {
+		return
+	}
+	if parent.Kind != shimast.KindClassDeclaration &&
+		parent.Kind != shimast.KindClassExpression {
+		return
+	}
+	// Walk the method body. Every value-returning `return` must
+	// return exactly `this`; we also require at least one return
+	// statement so we don't fire on methods that fall off the end.
+	hasValueReturn, allAreThis := preferReturnThisTypeAnalyzeBody(decl.Body)
+	if !hasValueReturn || !allAreThis {
+		return
+	}
+	ctx.Report(decl.Type, preferReturnThisTypeMessage)
+}
+
+const preferReturnThisTypeMessage = "Method always returns `this` — declare the return type as `this` so subclass call sites keep the narrower receiver type."
+
+// preferReturnThisTypeAnalyzeBody walks the method body (without
+// descending into nested function-like scopes) and reports:
+//   - hasValueReturn: at least one `return <expression>;` exists.
+//   - allAreThis: every value-returning `return` returns the bare
+//     `this` keyword (after stripping parens).
+//
+// A bare `return;` is ignored — it returns `undefined`, which the rule
+// cannot rewrite to `this` regardless. The conservative interpretation
+// matches the upstream rule's behavior.
+func preferReturnThisTypeAnalyzeBody(body *shimast.Node) (hasValueReturn, allAreThis bool) {
+	allAreThis = true
+	var walk func(*shimast.Node)
+	walk = func(n *shimast.Node) {
+		if n == nil {
+			return
+		}
+		if n != body && isFunctionLikeKind(n) {
+			return
+		}
+		if n.Kind == shimast.KindReturnStatement {
+			ret := n.AsReturnStatement()
+			if ret != nil && ret.Expression != nil {
+				hasValueReturn = true
+				inner := stripParens(ret.Expression)
+				if inner == nil || inner.Kind != shimast.KindThisKeyword {
+					allAreThis = false
+				}
+			}
+		}
+		n.ForEachChild(func(child *shimast.Node) bool {
+			walk(child)
+			return false
+		})
+	}
+	walk(body)
+	return hasValueReturn, allAreThis
+}
+
+func init() {
+	Register(preferReturnThisType{})
+}

package/linthost/rules_ts_prefer_string_starts_ends_with.go

@@ -0,0 +1,360 @@
+// typescript/prefer-string-starts-ends-with: prefer
+// `str.startsWith(prefix)` / `str.endsWith(suffix)` over the older
+// `indexOf` / `lastIndexOf` / anchored-regex shapes:
+//
+//   - `str.indexOf(p) === 0`                              → startsWith
+//   - `str.indexOf(p, str.length - p.length) !== -1`      → endsWith
+//   - `str.lastIndexOf(p) === str.length - p.length`      → endsWith
+//   - `/^prefix/.test(str)` (a static-prefix regex)       → startsWith
+//   - `/suffix$/.test(str)` (a static-suffix regex)       → endsWith
+//
+// The dedicated methods state the intent directly and avoid the
+// off-by-one arithmetic and regex-anchor pitfalls of the older shapes.
+// typescript-eslint:
+// https://typescript-eslint.io/rules/prefer-string-starts-ends-with/
+//
+// Type-aware. Without a Checker the rule cannot prove the receiver of
+// `indexOf` / `lastIndexOf` (or the argument of `.test(str)`) is a
+// `string`, so Context.Checker == nil short-circuits each Check to a
+// no-op the way `no-base-to-string` and `prefer-includes` do. `any` /
+// `unknown` / `never` are intentionally NOT treated as matching — they
+// leak from generic helpers and would explode the false-positive
+// volume on user-defined `indexOf` / `test` methods.
+package linthost
+
+import (
+	"strings"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+type preferStringStartsEndsWith struct{}
+
+func (preferStringStartsEndsWith) Name() string {
+	return "typescript/prefer-string-starts-ends-with"
+}
+func (preferStringStartsEndsWith) NeedsTypeChecker() bool {
+	return true
+}
+func (preferStringStartsEndsWith) Visits() []shimast.Kind {
+	return []shimast.Kind{
+		shimast.KindBinaryExpression,
+		shimast.KindCallExpression,
+	}
+}
+func (preferStringStartsEndsWith) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	switch node.Kind {
+	case shimast.KindBinaryExpression:
+		bin := node.AsBinaryExpression()
+		if bin == nil || bin.OperatorToken == nil {
+			return
+		}
+		if !preferStringStartsEndsWithIsEqualityOp(bin.OperatorToken.Kind) {
+			return
+		}
+		if preferStringStartsEndsWithBinary(ctx, bin.Left, bin.Right) {
+			ctx.Report(node, preferStringStartsEndsWithMessage)
+			return
+		}
+		if preferStringStartsEndsWithBinary(ctx, bin.Right, bin.Left) {
+			ctx.Report(node, preferStringStartsEndsWithMessage)
+		}
+	case shimast.KindCallExpression:
+		call := node.AsCallExpression()
+		if call == nil {
+			return
+		}
+		if preferStringStartsEndsWithRegexTest(ctx, call) {
+			ctx.Report(node, preferStringStartsEndsWithMessage)
+		}
+	}
+}
+
+const preferStringStartsEndsWithMessage = "Prefer `String#startsWith` / `String#endsWith` over the equivalent `indexOf` / `lastIndexOf` / anchored-regex idioms — clearer and avoids the off-by-one arithmetic."
+
+// preferStringStartsEndsWithIsEqualityOp reports whether `kind` is one
+// of the equality tokens the rule cares about. Only `==`, `===`,
+// `!=`, `!==` matter: every recognized shape compares two integers
+// for equality (or inequality with a sentinel) rather than ordering.
+func preferStringStartsEndsWithIsEqualityOp(kind shimast.Kind) bool {
+	switch kind {
+	case shimast.KindEqualsEqualsToken,
+		shimast.KindEqualsEqualsEqualsToken,
+		shimast.KindExclamationEqualsToken,
+		shimast.KindExclamationEqualsEqualsToken:
+		return true
+	}
+	return false
+}
+
+// preferStringStartsEndsWithBinary inspects `call op other` for the
+// `indexOf` / `lastIndexOf` shapes. Returns true when the receiver of
+// the call is provably string-typed AND the right-hand side matches
+// the sentinel of one of the recognized rewrites:
+//
+//	str.indexOf(p) === 0
+//	str.indexOf(p, str.length - p.length) !== -1
+//	str.lastIndexOf(p) === str.length - p.length
+func preferStringStartsEndsWithBinary(
+	ctx *Context,
+	callNode, otherNode *shimast.Node,
+) bool {
+	callNode = stripParens(callNode)
+	otherNode = stripParens(otherNode)
+	if callNode == nil || otherNode == nil {
+		return false
+	}
+	if callNode.Kind != shimast.KindCallExpression {
+		return false
+	}
+	call := callNode.AsCallExpression()
+	if call == nil || call.Expression == nil {
+		return false
+	}
+	receiver, method, ok := promisePropertyAccessParts(call.Expression)
+	if !ok {
+		return false
+	}
+	if method != "indexOf" && method != "lastIndexOf" {
+		return false
+	}
+	if receiver == nil {
+		return false
+	}
+	t := ctx.Checker.GetTypeAtLocation(receiver)
+	if !preferStringStartsEndsWithIsString(t) {
+		return false
+	}
+	args := call.Arguments
+	if args == nil || len(args.Nodes) == 0 {
+		return false
+	}
+	arg := stripParens(args.Nodes[0])
+	if arg == nil {
+		return false
+	}
+	receiverText := nodeText(ctx.File, receiver)
+	argText := nodeText(ctx.File, arg)
+	otherText := nodeText(ctx.File, otherNode)
+	if receiverText == "" || argText == "" {
+		return false
+	}
+	switch method {
+	case "indexOf":
+		// startsWith: `str.indexOf(p) === 0`
+		if len(args.Nodes) == 1 {
+			return otherText == "0"
+		}
+		// endsWith via positional indexOf: the second argument must
+		// equal `str.length - arg.length`, and the comparison must be
+		// against -1 (the sentinel for "not present at that
+		// position").
+		if len(args.Nodes) != 2 {
+			return false
+		}
+		second := stripParens(args.Nodes[1])
+		if !preferStringStartsEndsWithIsLengthMinusLength(ctx, second, receiverText, argText) {
+			return false
+		}
+		return preferStringStartsEndsWithIsMinusOne(otherText)
+	case "lastIndexOf":
+		// endsWith: `str.lastIndexOf(p) === str.length - p.length`
+		if len(args.Nodes) != 1 {
+			return false
+		}
+		return preferStringStartsEndsWithIsLengthMinusLengthText(otherText, receiverText, argText)
+	}
+	return false
+}
+
+// preferStringStartsEndsWithRegexTest reports whether `call` is a
+// `/^.../.test(str)` or `/...$/.test(str)` invocation on a regex
+// literal whose body is a static prefix or suffix — no metacharacters
+// other than the anchor and no flags that change the matching
+// semantics. The argument to `.test` must be a `string`-typed value;
+// without that the call is not equivalent to a startsWith/endsWith
+// rewrite (e.g. coercing a non-string regex argument).
+func preferStringStartsEndsWithRegexTest(
+	ctx *Context,
+	call *shimast.CallExpression,
+) bool {
+	if call == nil || call.Expression == nil || call.Arguments == nil || len(call.Arguments.Nodes) != 1 {
+		return false
+	}
+	receiver, method, ok := promisePropertyAccessParts(call.Expression)
+	if !ok || method != "test" {
+		return false
+	}
+	receiver = stripParens(receiver)
+	if receiver == nil || receiver.Kind != shimast.KindRegularExpressionLiteral {
+		return false
+	}
+	raw := nodeText(ctx.File, receiver)
+	if !preferStringStartsEndsWithIsAnchoredStaticRegex(raw) {
+		return false
+	}
+	arg := stripParens(call.Arguments.Nodes[0])
+	if arg == nil {
+		return false
+	}
+	return preferStringStartsEndsWithIsString(ctx.Checker.GetTypeAtLocation(arg))
+}
+
+// preferStringStartsEndsWithIsAnchoredStaticRegex reports whether
+// `raw` (the source text of a RegularExpressionLiteral, including the
+// surrounding `/`) encodes either `^prefix` or `suffix$` with no
+// metacharacters other than the anchor itself, and carries no flags
+// that change matching semantics (`i`, `m`, `s`, `u`, `v`). A flag
+// like `i` would lower-case both sides, which `startsWith` does not
+// do — so the rewrite would change meaning.
+func preferStringStartsEndsWithIsAnchoredStaticRegex(raw string) bool {
+	if len(raw) < 3 || raw[0] != '/' {
+		return false
+	}
+	closing := strings.LastIndexByte(raw, '/')
+	if closing <= 0 {
+		return false
+	}
+	pattern := raw[1:closing]
+	flags := raw[closing+1:]
+	if pattern == "" {
+		return false
+	}
+	for i := 0; i < len(flags); i++ {
+		switch flags[i] {
+		case 'g', 'y', 'd':
+			// stateful/position flags — fine for `.test` since we
+			// only call once
+		default:
+			return false
+		}
+	}
+	if pattern[0] == '^' {
+		return preferStringStartsEndsWithIsStaticString(pattern[1:])
+	}
+	if pattern[len(pattern)-1] == '$' {
+		return preferStringStartsEndsWithIsStaticString(pattern[:len(pattern)-1])
+	}
+	return false
+}
+
+// preferStringStartsEndsWithIsStaticString reports whether `pattern`
+// is a regex body made up only of literal characters (and accepted
+// escape sequences `\.`, `\\`, etc. that represent a single literal
+// character). Any metacharacter — `^`, `$`, `*`, `+`, `?`, `(`, `)`,
+// `[`, `]`, `{`, `}`, `|`, `.` — disqualifies the body because the
+// startsWith/endsWith rewrite would change matching semantics.
+func preferStringStartsEndsWithIsStaticString(pattern string) bool {
+	if pattern == "" {
+		return false
+	}
+	for i := 0; i < len(pattern); i++ {
+		ch := pattern[i]
+		if ch == '\\' {
+			// Accept only escapes that name a single literal
+			// character (`\.`, `\$`, `\^`, `\/`, `\\`, `\(`, `\)`,
+			// `\[`, `\]`, `\{`, `\}`, `\|`, `\+`, `\*`, `\?`).
+			// Reject character-class shortcuts (`\d`, `\w`, `\s`)
+			// and back-references — those would not survive a
+			// rewrite to startsWith/endsWith.
+			if i+1 >= len(pattern) {
+				return false
+			}
+			next := pattern[i+1]
+			switch next {
+			case '.', '$', '^', '/', '\\', '(', ')', '[', ']', '{', '}', '|', '+', '*', '?', '-':
+				i++
+				continue
+			}
+			return false
+		}
+		switch ch {
+		case '^', '$', '*', '+', '?', '(', ')', '[', ']', '{', '}', '|', '.':
+			return false
+		}
+	}
+	return true
+}
+
+// preferStringStartsEndsWithIsLengthMinusLength reports whether
+// `node` textually evaluates to `<receiver>.length - <arg>.length`.
+// The comparison is text-based (after stripping parens) because the
+// rewrite only fires when the call site spelled the offset that way
+// — matching the upstream rule's textual shape detector.
+func preferStringStartsEndsWithIsLengthMinusLength(
+	ctx *Context,
+	node *shimast.Node,
+	receiverText, argText string,
+) bool {
+	if node == nil {
+		return false
+	}
+	return preferStringStartsEndsWithIsLengthMinusLengthText(nodeText(ctx.File, node), receiverText, argText)
+}
+
+// preferStringStartsEndsWithIsLengthMinusLengthText is the text-level
+// half of `preferStringStartsEndsWithIsLengthMinusLength` — split out
+// so the `lastIndexOf === str.length - p.length` shape can use the
+// same matcher against the binary RHS text.
+func preferStringStartsEndsWithIsLengthMinusLengthText(text, receiverText, argText string) bool {
+	wanted := receiverText + ".length-" + argText + ".length"
+	return preferStringStartsEndsWithStripSpaces(text) == wanted
+}
+
+// preferStringStartsEndsWithStripSpaces removes whitespace from `s`.
+// Used for the textual equality match — `a.length - b.length` and
+// `a.length-b.length` should both match the canonical form.
+func preferStringStartsEndsWithStripSpaces(s string) string {
+	var b strings.Builder
+	for i := 0; i < len(s); i++ {
+		ch := s[i]
+		if ch == ' ' || ch == '\t' || ch == '\r' || ch == '\n' {
+			continue
+		}
+		b.WriteByte(ch)
+	}
+	return b.String()
+}
+
+// preferStringStartsEndsWithIsMinusOne reports whether `text` is the
+// numeric literal `-1` (with or without internal whitespace).
+func preferStringStartsEndsWithIsMinusOne(text string) bool {
+	return preferStringStartsEndsWithStripSpaces(text) == "-1"
+}
+
+// preferStringStartsEndsWithIsString reports whether t is provably
+// string-like. Mirrors `isStringLikeType` in no-base-to-string but
+// rejects `any` / `unknown` / `never` so generic helpers don't fire.
+// Union and intersection types must have every constituent string-like.
+func preferStringStartsEndsWithIsString(t *shimchecker.Type) bool {
+	if t == nil {
+		return false
+	}
+	flags := t.Flags()
+	if flags&(shimchecker.TypeFlagsAny|shimchecker.TypeFlagsUnknown|shimchecker.TypeFlagsNever) != 0 {
+		return false
+	}
+	if flags&shimchecker.TypeFlagsStringLike != 0 {
+		return true
+	}
+	if flags&(shimchecker.TypeFlagsUnion|shimchecker.TypeFlagsIntersection) != 0 {
+		for _, part := range t.Types() {
+			if part == nil {
+				continue
+			}
+			if !preferStringStartsEndsWithIsString(part) {
+				return false
+			}
+		}
+		return true
+	}
+	return false
+}
+
+func init() {
+	Register(preferStringStartsEndsWith{})
+}

package/linthost/rules_ts_promise_function_async.go

@@ -0,0 +1,77 @@
+// promiseFunctionAsync requires a function whose return type is
+// `Promise<T>` (or a Promise-like thenable) to be declared with the
+// `async` keyword. typescript-eslint:
+// https://typescript-eslint.io/rules/promise-function-async/
+//
+// Type-aware. An `async` function wraps a synchronous `throw` into a
+// rejected Promise so the caller's `await` / `.catch(...)` observes
+// it; the non-async equivalent throws synchronously and bypasses every
+// Promise-aware handler downstream. Marking the function `async` keeps
+// the rejection channel consistent with the declared return type.
+//
+// Skipped:
+//   - functions already declared `async` (the contract holds);
+//   - abstract methods and overload signatures (no body to wrap — the
+//     `async` keyword can only be applied to the implementation);
+//   - functions whose declared / inferred return type is not a
+//     Promise (`any` / `unknown` / `never` pass through, matching the
+//     conservative `isPromiseTypedExpression` baseline used by the
+//     surrounding async family).
+package linthost
+
+import (
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type promiseFunctionAsync struct{}
+
+func (promiseFunctionAsync) Name() string { return "typescript/promise-function-async" }
+func (promiseFunctionAsync) NeedsTypeChecker() bool {
+	return true
+}
+func (promiseFunctionAsync) Visits() []shimast.Kind {
+	return []shimast.Kind{
+		shimast.KindFunctionDeclaration,
+		shimast.KindFunctionExpression,
+		shimast.KindArrowFunction,
+		shimast.KindMethodDeclaration,
+	}
+}
+func (promiseFunctionAsync) Check(ctx *Context, node *shimast.Node) {
+	if ctx.Checker == nil {
+		return
+	}
+	if hasAsyncModifier(node) {
+		return
+	}
+	// Skip overload signatures and abstract methods — only the
+	// implementation signature carries an executable body that the
+	// `async` keyword could wrap.
+	if node.Body() == nil {
+		return
+	}
+	if hasModifier(node, shimast.KindAbstractKeyword) {
+		return
+	}
+	sig := ctx.Checker.GetSignatureFromDeclaration(node)
+	if sig == nil {
+		return
+	}
+	returnType := ctx.Checker.GetReturnTypeOfSignature(sig)
+	if returnType == nil {
+		return
+	}
+	if !isPromiseTypedExpression(ctx.Checker, returnType) {
+		return
+	}
+	startPos := keywordStart(ctx.File, node, "function")
+	if startPos >= 0 {
+		ctx.ReportRange(startPos, startPos+len("function"), "Function returning a Promise should be declared `async` so synchronous throws surface as a rejected Promise.")
+		return
+	}
+	ctx.Report(node, "Function returning a Promise should be declared `async` so synchronous throws surface as a rejected Promise.")
+}
+
+func init() {
+	Register(promiseFunctionAsync{})
+}