feat: handle unmatched jsdoc parameters

internal/checker/checker.go

@@ -727,6 +727,7 @@ type Checker struct {
 	unknownSignature                            *Signature
 	resolvingSignature                          *Signature
 	silentNeverSignature                        *Signature
+	cachedArgumentsReferenced                   map[*ast.Node]bool
 	enumNumberIndexInfo                         *IndexInfo
 	anyBaseTypeIndexInfo                        *IndexInfo
 	patternAmbientModules                       []*ast.PatternAmbientModule
@@ -1000,6 +1001,7 @@ func NewChecker(program Program) *Checker {
 	c.unknownSignature = c.newSignature(SignatureFlagsNone, nil, nil, nil, nil, c.errorType, nil, 0)
 	c.resolvingSignature = c.newSignature(SignatureFlagsNone, nil, nil, nil, nil, c.anyType, nil, 0)
 	c.silentNeverSignature = c.newSignature(SignatureFlagsNone, nil, nil, nil, nil, c.silentNeverType, nil, 0)
+	c.cachedArgumentsReferenced = make(map[*ast.Node]bool)
 	c.enumNumberIndexInfo = &IndexInfo{keyType: c.numberType, valueType: c.stringType, isReadonly: true}
 	c.anyBaseTypeIndexInfo = &IndexInfo{keyType: c.stringType, valueType: c.anyType, isReadonly: false}
 	c.emptyStringType = c.getStringLiteralType("")
@@ -2554,6 +2556,7 @@ func (c *Checker) checkSignatureDeclaration(node *ast.Node) {
 		c.checkGrammarFunctionLikeDeclaration(node)
 	}
 	c.checkTypeParameters(node.TypeParameters())
+	c.checkUnmatchedJSDocParameters(node)
 	c.checkSourceElements(node.Parameters())
 	returnTypeNode := node.Type()
 	if returnTypeNode != nil {
@@ -30520,6 +30523,43 @@ func (c *Checker) getRegularTypeOfExpression(expr *ast.Node) *Type {
 	return c.getRegularTypeOfLiteralType(c.getTypeOfExpression(expr))
 }
 
+func (c *Checker) containsArgumentsReference(node *ast.Node) bool {
+	if node.Body() == nil {
+		return false
+	}
+
+	if containsArguments, ok := c.cachedArgumentsReferenced[node]; ok {
+		return containsArguments
+	}
+
+	var visit func(node *ast.Node) bool
+	visit = func(node *ast.Node) bool {
+		if node == nil {
+			return false
+		}
+		switch node.Kind {
+		case ast.KindIdentifier:
+			return node.Text() == c.argumentsSymbol.Name && c.IsArgumentsSymbol(c.getResolvedSymbol(node))
+		case ast.KindPropertyDeclaration, ast.KindMethodDeclaration, ast.KindGetAccessor, ast.KindSetAccessor:
+			if ast.IsComputedPropertyName(node.Name()) {
+				return visit(node.Name())
+			}
+		case ast.KindPropertyAccessExpression, ast.KindElementAccessExpression:
+			return visit(node.Expression())
+		case ast.KindPropertyAssignment:
+			return visit(node.AsPropertyAssignment().Initializer)
+		}
+		if nodeStartsNewLexicalEnvironment(node) || ast.IsPartOfTypeNode(node) {
+			return false
+		}
+		return node.ForEachChild(visit)
+	}
+
+	containsArguments := visit(node.Body())
+	c.cachedArgumentsReferenced[node] = containsArguments
+	return containsArguments
+}
+
 func (c *Checker) GetTypeAtLocation(node *ast.Node) *Type {
 	return c.getTypeOfNode(node)
 }

internal/checker/jsdoc.go

@@ -0,0 +1,97 @@
+package checker
+
+import (
+	"github.com/microsoft/typescript-go/internal/ast"
+	"github.com/microsoft/typescript-go/internal/collections"
+	"github.com/microsoft/typescript-go/internal/diagnostics"
+)
+
+func (c *Checker) checkUnmatchedJSDocParameters(node *ast.Node) {
+	var jsdocParameters []*ast.Node
+	for _, tag := range getAllJSDocTags(node) {
+		if tag.Kind == ast.KindJSDocParameterTag {
+			name := tag.AsJSDocParameterOrPropertyTag().Name()
+			if ast.IsIdentifier(name) && len(name.Text()) == 0 {
+				continue
+			}
+			jsdocParameters = append(jsdocParameters, tag)
+		}
+	}
+
+	if len(jsdocParameters) == 0 {
+		return
+	}
+
+	isJs := ast.IsInJSFile(node)
+	parameters := collections.Set[string]{}
+	excludedParameters := collections.Set[int]{}
+
+	for i, param := range node.Parameters() {
+		name := param.AsParameterDeclaration().Name()
+		if ast.IsIdentifier(name) {
+			parameters.Add(name.Text())
+		}
+		if ast.IsBindingPattern(name) {
+			excludedParameters.Add(i)
+		}
+	}
+	if c.containsArgumentsReference(node) {
+		if isJs {
+			lastJSDocParamIndex := len(jsdocParameters) - 1
+			lastJSDocParam := jsdocParameters[lastJSDocParamIndex].AsJSDocParameterOrPropertyTag()
+			if lastJSDocParam == nil || !ast.IsIdentifier(lastJSDocParam.Name()) {
+				return
+			}
+			if excludedParameters.Has(lastJSDocParamIndex) || parameters.Has(lastJSDocParam.Name().Text()) {
+				return
+			}
+			if lastJSDocParam.TypeExpression == nil || lastJSDocParam.TypeExpression.Type() == nil {
+				return
+			}
+			if c.isArrayType(c.getTypeFromTypeNode(lastJSDocParam.TypeExpression.Type())) {
+				return
+			}
+			c.error(lastJSDocParam.Name(), diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name_It_would_match_arguments_if_it_had_an_array_type, lastJSDocParam.Name().Text())
+		}
+	} else {
+		for index, tag := range jsdocParameters {
+			name := tag.AsJSDocParameterOrPropertyTag().Name()
+			isNameFirst := tag.AsJSDocParameterOrPropertyTag().IsNameFirst
+
+			if excludedParameters.Has(index) || (ast.IsIdentifier(name) && parameters.Has(name.Text())) {
+				continue
+			}
+
+			if ast.IsQualifiedName(name) {
+				if isJs {
+					c.error(name, diagnostics.Qualified_name_0_is_not_allowed_without_a_leading_param_object_1,
+						entityNameToString(name),
+						entityNameToString(name.AsQualifiedName().Left),
+					)
+				}
+			} else {
+				if !isNameFirst {
+					c.errorOrSuggestion(isJs, name,
+						diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name,
+						name.Text(),
+					)
+				}
+			}
+		}
+	}
+}
+
+func getAllJSDocTags(node *ast.Node) []*ast.Node {
+	if node == nil {
+		return nil
+	}
+	jsdocs := node.JSDoc(nil)
+	if len(jsdocs) == 0 {
+		return nil
+	}
+	lastJSDoc := jsdocs[len(jsdocs)-1].AsJSDoc()
+	if lastJSDoc.Tags == nil {
+		return nil
+	}
+	return lastJSDoc.Tags.Nodes
+}

internal/checker/utilities.go

@@ -1952,3 +1952,12 @@ func ValueToString(value any) string {
 	}
 	panic("unhandled value type in valueToString")
 }
+
+func nodeStartsNewLexicalEnvironment(node *ast.Node) bool {
+	switch node.Kind {
+	case ast.KindConstructor, ast.KindFunctionExpression, ast.KindFunctionDeclaration, ast.KindArrowFunction,
+		ast.KindMethodDeclaration, ast.KindGetAccessor, ast.KindSetAccessor, ast.KindModuleDeclaration, ast.KindSourceFile:
+		return true
+	}
+	return false
+}

testdata/baselines/reference/submodule/compiler/jsdocParamTagInvalid.errors.txt

@@ -0,0 +1,9 @@
+/a.js(1,21): error TS8024: JSDoc '@param' tag has name 'colour', but there is no parameter with that name.
+
+
+==== /a.js (1 errors) ====
+    /** @param {string} colour */
+                        ~~~~~~
+!!! error TS8024: JSDoc '@param' tag has name 'colour', but there is no parameter with that name.
+    function f(color) {}
+

testdata/baselines/reference/submodule/conformance/jsdocParamTag2.errors.txt

@@ -0,0 +1,80 @@
+0.js(70,20): error TS8024: JSDoc '@param' tag has name 'y', but there is no parameter with that name.
+
+
+==== 0.js (1 errors) ====
+    // Object literal syntax
+    /**
+     * @param {{a: string, b: string}} obj
+     * @param {string} x
+     */
+    function good1({a, b}, x) {}
+    /**
+     * @param {{a: string, b: string}} obj
+     * @param {{c: number, d: number}} OBJECTION
+     */
+    function good2({a, b}, {c, d}) {}
+    /**
+     * @param {number} x
+     * @param {{a: string, b: string}} obj
+     * @param {string} y
+     */
+    function good3(x, {a, b}, y) {}
+    /**
+     * @param {{a: string, b: string}} obj
+     */
+    function good4({a, b}) {}
+
+    // nested object syntax
+    /**
+     * @param {Object} obj
+     * @param {string} obj.a - this is like the saddest way to specify a type
+     * @param {string} obj.b - but it sure does allow a lot of documentation
+     * @param {string} x
+     */
+    function good5({a, b}, x) {}
+    /**
+     * @param {Object} obj
+     * @param {string} obj.a
+     * @param {string} obj.b - but it sure does allow a lot of documentation
+     * @param {Object} OBJECTION - documentation here too
+     * @param {string} OBJECTION.c
+     * @param {string} OBJECTION.d - meh
+     */
+    function good6({a, b}, {c, d}) {}
+    /**
+     * @param {number} x
+     * @param {Object} obj
+     * @param {string} obj.a
+     * @param {string} obj.b
+     * @param {string} y
+     */
+    function good7(x, {a, b}, y) {}
+    /**
+     * @param {Object} obj
+     * @param {string} obj.a
+     * @param {string} obj.b
+     */
+    function good8({a, b}) {}
+
+    /**
+     * @param {{ a: string }} argument
+     */
+    function good9({ a }) {
+        console.log(arguments, a);
+    }
+
+    /**
+     * @param {object} obj - this type gets ignored
+     * @param {string} obj.a
+     * @param {string} obj.b - and x's type gets used for both parameters
+     * @param {string} x
+     */
+    function bad1(x, {a, b}) {}
+    /**
+     * @param {string} y - here, y's type gets ignored but obj's is fine
+                       ~
+!!! error TS8024: JSDoc '@param' tag has name 'y', but there is no parameter with that name.
+     * @param {{a: string, b: string}} obj
+     */
+    function bad2(x, {a, b}) {}
+

testdata/baselines/reference/submodule/conformance/jsdocParamTagTypeLiteral.errors.txt

@@ -0,0 +1,78 @@
+0.js(3,20): error TS8024: JSDoc '@param' tag has name 'unrelated', but there is no parameter with that name.
+
+
+==== 0.js (1 errors) ====
+    /**
+     * @param {Object} notSpecial
+     * @param {string} unrelated - not actually related because it's not notSpecial.unrelated
+                       ~~~~~~~~~
+!!! error TS8024: JSDoc '@param' tag has name 'unrelated', but there is no parameter with that name.
+     */
+    function normal(notSpecial) {
+        notSpecial; // should just be 'Object'
+    }
+    normal(12);
+
+    /**
+     * @param {Object} opts1 doc1
+     * @param {string} opts1.x doc2
+     * @param {string=} opts1.y doc3
+     * @param {string} [opts1.z] doc4
+     * @param {string} [opts1.w="hi"] doc5
+     */
+    function foo1(opts1) {
+        opts1.x;
+    }
+
+    foo1({x: 'abc'});
+
+    /**
+     * @param {Object[]} opts2
+     * @param {string} opts2[].anotherX
+     * @param {string=} opts2[].anotherY
+     */
+    function foo2(/** @param opts2 bad idea theatre! */opts2) {
+        opts2[0].anotherX;
+    }
+
+    foo2([{anotherX: "world"}]);
+
+    /**
+     * @param {object} opts3
+     * @param {string} opts3.x
+     */
+    function foo3(opts3) {
+        opts3.x;
+    }
+    foo3({x: 'abc'});
+
+    /**
+     * @param {object[]} opts4
+     * @param {string} opts4[].x
+     * @param {string=} opts4[].y
+     * @param {string} [opts4[].z]
+     * @param {string} [opts4[].w="hi"]
+     */
+    function foo4(opts4) {
+        opts4[0].x;
+    }
+
+    foo4([{ x: 'hi' }]);
+
+    /**
+     * @param {object[]} opts5 - Let's test out some multiple nesting levels
+     * @param {string} opts5[].help - (This one is just normal)
+     * @param {object} opts5[].what - Look at us go! Here's the first nest!
+     * @param {string} opts5[].what.a - (Another normal one)
+     * @param {Object[]} opts5[].what.bad - Now we're nesting inside a nested type
+     * @param {string} opts5[].what.bad[].idea - I don't think you can get back out of this level...
+     * @param {boolean} opts5[].what.bad[].oh - Oh ... that's how you do it.
+     * @param {number} opts5[].unnest - Here we are almost all the way back at the beginning.
+     */
+    function foo5(opts5) {
+        opts5[0].what.bad[0].idea;
+        opts5[0].unnest;
+    }
+
+    foo5([{ help: "help", what: { a: 'a', bad: [{ idea: 'idea', oh: false }] }, unnest: 1 }]);
+

testdata/baselines/reference/submodule/conformance/paramTagNestedWithoutTopLevelObject.errors.txt

@@ -0,0 +1,12 @@
+paramTagNestedWithoutTopLevelObject.js(2,20): error TS8032: Qualified name 'xyz.p' is not allowed without a leading '@param {object} xyz'.
+
+
+==== paramTagNestedWithoutTopLevelObject.js (1 errors) ====
+    /**
+     * @param {number} xyz.p
+                       ~~~~~
+!!! error TS8032: Qualified name 'xyz.p' is not allowed without a leading '@param {object} xyz'.
+     */
+    function g(xyz) {
+        return xyz.p;
+    }

testdata/baselines/reference/submodule/conformance/paramTagNestedWithoutTopLevelObject2.errors.txt

@@ -0,0 +1,13 @@
+paramTagNestedWithoutTopLevelObject2.js(2,20): error TS8032: Qualified name 'xyz.bar' is not allowed without a leading '@param {object} xyz'.
+
+
+==== paramTagNestedWithoutTopLevelObject2.js (1 errors) ====
+    /**
+     * @param {object} xyz.bar
+                       ~~~~~~~
+!!! error TS8032: Qualified name 'xyz.bar' is not allowed without a leading '@param {object} xyz'.
+     * @param {number} xyz.bar.p
+     */
+    function g(xyz) {
+        return xyz.bar.p;
+    }

testdata/baselines/reference/submodule/conformance/paramTagNestedWithoutTopLevelObject3.errors.txt

@@ -1,10 +1,13 @@
+paramTagNestedWithoutTopLevelObject3.js(3,20): error TS8032: Qualified name 'xyz.bar.p' is not allowed without a leading '@param {object} xyz.bar'.
 paramTagNestedWithoutTopLevelObject3.js(6,16): error TS2339: Property 'bar' does not exist on type 'object'.
 
 
-==== paramTagNestedWithoutTopLevelObject3.js (1 errors) ====
+==== paramTagNestedWithoutTopLevelObject3.js (2 errors) ====
     /**
      * @param {object} xyz
      * @param {number} xyz.bar.p
+                       ~~~~~~~~~
+!!! error TS8032: Qualified name 'xyz.bar.p' is not allowed without a leading '@param {object} xyz.bar'.
      */
     function g(xyz) {
         return xyz.bar.p;