preserve declarations if @internal is mentioned in unrelated comment

src/compiler/factory/nodeFactory.ts

@@ -227,6 +227,7 @@ import {
     JSDocFunctionType,
     JSDocImplementsTag,
     JSDocImportTag,
+    JSDocInternalTag,
     JSDocLink,
     JSDocLinkCode,
     JSDocLinkPlain,
@@ -950,6 +951,12 @@ export function createNodeFactory(flags: NodeFactoryFlags, baseFactory: BaseNode
         get updateJSDocSatisfiesTag() {
             return getJSDocTypeLikeTagUpdateFunction<JSDocSatisfiesTag>(SyntaxKind.JSDocSatisfiesTag);
         },
+        get createJSDocInternalTag() {
+            return getJSDocSimpleTagCreateFunction<JSDocInternalTag>(SyntaxKind.JSDocInternalTag);
+        },
+        get updateJSDocInternalTag() {
+            return getJSDocSimpleTagUpdateFunction<JSDocInternalTag>(SyntaxKind.JSDocInternalTag);
+        },
 
         createJSDocEnumTag,
         updateJSDocEnumTag,

src/compiler/factory/nodeTests.ts

@@ -92,6 +92,7 @@ import {
     JSDocFunctionType,
     JSDocImplementsTag,
     JSDocImportTag,
+    JSDocInternalTag,
     JSDocLink,
     JSDocLinkCode,
     JSDocLinkPlain,
@@ -1193,6 +1194,10 @@ export function isJSDocImportTag(node: Node): node is JSDocImportTag {
     return node.kind === SyntaxKind.JSDocImportTag;
 }
 
+export function isJSDocInternalTag(node: Node): node is JSDocInternalTag {
+    return node.kind === SyntaxKind.JSDocInternalTag;
+}
+
 // Synthesized list
 
 /** @internal */

src/compiler/parser.ts

@@ -177,6 +177,7 @@ import {
     JSDocFunctionType,
     JSDocImplementsTag,
     JSDocImportTag,
+    JSDocInternalTag,
     JSDocLink,
     JSDocLinkCode,
     JSDocLinkPlain,
@@ -1128,6 +1129,7 @@ const forEachChildTable: ForEachChildTable = {
     [SyntaxKind.JSDocProtectedTag]: forEachChildInJSDocTag,
     [SyntaxKind.JSDocReadonlyTag]: forEachChildInJSDocTag,
     [SyntaxKind.JSDocDeprecatedTag]: forEachChildInJSDocTag,
+    [SyntaxKind.JSDocInternalTag]: forEachChildInJSDocTag,
     [SyntaxKind.JSDocOverrideTag]: forEachChildInJSDocTag,
     [SyntaxKind.JSDocImportTag]: forEachChildInJSDocImportTag,
     [SyntaxKind.PartiallyEmittedExpression]: forEachChildInPartiallyEmittedExpression,
@@ -1214,7 +1216,7 @@ function forEachChildInJSDocLinkCodeOrPlain<T>(node: JSDocLink | JSDocLinkCode |
     return visitNode(cbNode, node.name);
 }
 
-function forEachChildInJSDocTag<T>(node: JSDocUnknownTag | JSDocClassTag | JSDocPublicTag | JSDocPrivateTag | JSDocProtectedTag | JSDocReadonlyTag | JSDocDeprecatedTag | JSDocOverrideTag, cbNode: (node: Node) => T | undefined, cbNodes?: (nodes: NodeArray<Node>) => T | undefined): T | undefined {
+function forEachChildInJSDocTag<T>(node: JSDocUnknownTag | JSDocClassTag | JSDocPublicTag | JSDocPrivateTag | JSDocProtectedTag | JSDocReadonlyTag | JSDocDeprecatedTag | JSDocOverrideTag | JSDocInternalTag, cbNode: (node: Node) => T | undefined, cbNodes?: (nodes: NodeArray<Node>) => T | undefined): T | undefined {
     return visitNode(cbNode, node.tagName)
         || (typeof node.comment === "string" ? undefined : visitNodes(cbNode, cbNodes, node.comment));
 }
@@ -9109,6 +9111,9 @@ namespace Parser {
                     case "satisfies":
                         tag = parseSatisfiesTag(start, tagName, margin, indentText);
                         break;
+                    case "internal":
+                        tag = parseSimpleTag(start, factory.createJSDocInternalTag, tagName, margin, indentText);
+                        break;
                     case "see":
                         tag = parseSeeTag(start, tagName, margin, indentText);
                         break;

src/compiler/scanner.ts

@@ -349,7 +349,7 @@ const commentDirectiveRegExSingleLine = /^\/\/\/?\s*@(ts-expect-error|ts-ignore)
  */
 const commentDirectiveRegExMultiLine = /^(?:\/|\*)*\s*@(ts-expect-error|ts-ignore)/;
 
-const jsDocSeeOrLink = /@(?:see|link)/i;
+const jsDocNeededInTypeScriptFile = /@(?:see|link|internal)/i;
 
 function lookupInUnicodeMap(code: number, map: readonly number[]): boolean {
     // Bail out quickly if it couldn't possibly be in the map.
@@ -2386,7 +2386,7 @@ export function createScanner(languageVersion: ScriptTarget, skipTrivia: boolean
             return false;
         }
 
-        return jsDocSeeOrLink.test(text.slice(fullStartPos, pos));
+        return jsDocNeededInTypeScriptFile.test(text.slice(fullStartPos, pos));
     }
 
     function reScanInvalidIdentifier(): SyntaxKind {

src/compiler/types.ts

@@ -439,6 +439,7 @@ export const enum SyntaxKind {
     JSDocThrowsTag,
     JSDocSatisfiesTag,
     JSDocImportTag,
+    JSDocInternalTag,
 
     // Synthesized list
     SyntaxList,
@@ -1035,6 +1036,7 @@ export type ForEachChildNodes =
     | JSDocProtectedTag
     | JSDocReadonlyTag
     | JSDocDeprecatedTag
+    | JSDocInternalTag
     | JSDocThrowsTag
     | JSDocOverrideTag
     | JSDocSatisfiesTag
@@ -4097,6 +4099,11 @@ export interface JSDocImportTag extends JSDocTag {
     readonly attributes?: ImportAttributes;
 }
 
+export interface JSDocInternalTag extends JSDocTag {
+    readonly kind: SyntaxKind.JSDocInternalTag;
+    readonly typeExpression: JSDocTypeExpression;
+}
+
 // NOTE: Ensure this is up-to-date with src/debug/debug.ts
 // dprint-ignore
 /** @internal */
@@ -8955,6 +8962,8 @@ export interface NodeFactory {
     updateJSDocSatisfiesTag(node: JSDocSatisfiesTag, tagName: Identifier | undefined, typeExpression: JSDocTypeExpression, comment: string | NodeArray<JSDocComment> | undefined): JSDocSatisfiesTag;
     createJSDocImportTag(tagName: Identifier | undefined, importClause: ImportClause | undefined, moduleSpecifier: Expression, attributes?: ImportAttributes, comment?: string | NodeArray<JSDocComment>): JSDocImportTag;
     updateJSDocImportTag(node: JSDocImportTag, tagName: Identifier | undefined, importClause: ImportClause | undefined, moduleSpecifier: Expression, attributes: ImportAttributes | undefined, comment: string | NodeArray<JSDocComment> | undefined): JSDocImportTag;
+    createJSDocInternalTag(tagName: Identifier | undefined, comment?: string | NodeArray<JSDocComment>): JSDocInternalTag;
+    updateJSDocInternalTag(node: JSDocInternalTag, tagName: Identifier | undefined, comment: string | NodeArray<JSDocComment> | undefined): JSDocInternalTag;
     createJSDocText(text: string): JSDocText;
     updateJSDocText(node: JSDocText, text: string): JSDocText;
     createJSDocComment(comment?: string | NodeArray<JSDocComment> | undefined, tags?: readonly JSDocTag[] | undefined): JSDoc;
@@ -10016,15 +10025,16 @@ export const enum JSDocParsingMode {
      * Parse only JSDoc comments which are needed to provide correct type errors.
      *
      * This will always parse JSDoc in non-TS files, but only parse JSDoc comments
-     * containing `@see` and `@link` in TS files.
+     * containing `see`, `link`, and `internal` in TS files.
      */
     ParseForTypeErrors,
     /**
      * Parse only JSDoc comments which are needed to provide correct type info.
      *
      * This will always parse JSDoc in non-TS files, but never in TS files.
      *
-     * Note: Do not use this mode if you require accurate type errors; use {@link ParseForTypeErrors} instead.
+     * Note: Do not use this mode if you require accurate type errors or need to
+     * observe `internal` JSDoc tags; use {@link ParseForTypeErrors} instead.
      */
     ParseForTypeInfo,
 }

src/compiler/utilitiesPublic.ts

@@ -32,10 +32,8 @@ import {
     ClassLikeDeclaration,
     ClassStaticBlockDeclaration,
     combinePaths,
-    CommentRange,
     compareDiagnostics,
     CompilerOptions,
-    concatenate,
     ConciseBody,
     ConstructorDeclaration,
     ConstructorTypeNode,
@@ -65,7 +63,6 @@ import {
     filter,
     find,
     flatMap,
-    forEach,
     ForInitializer,
     ForInOrOfStatement,
     FunctionBody,
@@ -85,10 +82,7 @@ import {
     getJSDocCommentsAndTags,
     getJSDocRoot,
     getJSDocTypeParameterDeclarations,
-    getLeadingCommentRanges,
-    getLeadingCommentRangesOfNode,
     getSourceFileOfNode,
-    getTrailingCommentRanges,
     hasAccessorModifier,
     HasDecorators,
     hasDecorators,
@@ -141,6 +135,7 @@ import {
     isJSDocEnumTag,
     isJSDocFunctionType,
     isJSDocImplementsTag,
+    isJSDocInternalTag,
     isJSDocOverloadTag,
     isJSDocOverrideTag,
     isJSDocParameterTag,
@@ -184,6 +179,7 @@ import {
     JSDocDeprecatedTag,
     JSDocEnumTag,
     JSDocImplementsTag,
+    JSDocInternalTag,
     JSDocLink,
     JSDocLinkCode,
     JSDocLinkPlain,
@@ -210,7 +206,6 @@ import {
     JsxTagNameExpression,
     KeywordSyntaxKind,
     LabeledStatement,
-    last,
     lastOrUndefined,
     LeftHandSideExpression,
     length,
@@ -262,7 +257,6 @@ import {
     setUILocale,
     SignatureDeclaration,
     skipOuterExpressions,
-    skipTrivia,
     some,
     sortAndDeduplicate,
     SortedReadonlyArray,
@@ -1185,6 +1179,10 @@ export function getJSDocSatisfiesTag(node: Node): JSDocSatisfiesTag | undefined
     return getFirstJSDocTag(node, isJSDocSatisfiesTag);
 }
 
+export function getJSDocInternalTag(node: Node): JSDocInternalTag | undefined {
+    return getFirstJSDocTag(node, isJSDocInternalTag);
+}
+
 /** Gets the JSDoc type tag for the node if present and valid */
 export function getJSDocTypeTag(node: Node): JSDocTypeTag | undefined {
     // We should have already issued an error if there were multiple type jsdocs, so just use the first one.
@@ -2609,31 +2607,8 @@ export function isRestParameter(node: ParameterDeclaration | JSDocParameterTag):
     return (node as ParameterDeclaration).dotDotDotToken !== undefined || !!type && type.kind === SyntaxKind.JSDocVariadicType;
 }
 
-function hasInternalAnnotation(range: CommentRange, sourceFile: SourceFile) {
-    const comment = sourceFile.text.substring(range.pos, range.end);
-    return comment.includes("@internal");
-}
-
 export function isInternalDeclaration(node: Node, sourceFile?: SourceFile) {
     sourceFile ??= getSourceFileOfNode(node);
     const parseTreeNode = getParseTreeNode(node);
-    if (parseTreeNode && parseTreeNode.kind === SyntaxKind.Parameter) {
-        const paramIdx = (parseTreeNode.parent as SignatureDeclaration).parameters.indexOf(parseTreeNode as ParameterDeclaration);
-        const previousSibling = paramIdx > 0 ? (parseTreeNode.parent as SignatureDeclaration).parameters[paramIdx - 1] : undefined;
-        const text = sourceFile.text;
-        const commentRanges = previousSibling
-            ? concatenate(
-                // to handle
-                // ... parameters, /** @internal */
-                // public param: string
-                getTrailingCommentRanges(text, skipTrivia(text, previousSibling.end + 1, /*stopAfterLineBreak*/ false, /*stopAtComments*/ true)),
-                getLeadingCommentRanges(text, node.pos),
-            )
-            : getTrailingCommentRanges(text, skipTrivia(text, node.pos, /*stopAfterLineBreak*/ false, /*stopAtComments*/ true));
-        return some(commentRanges) && hasInternalAnnotation(last(commentRanges), sourceFile);
-    }
-    const leadingCommentRanges = parseTreeNode && getLeadingCommentRangesOfNode(parseTreeNode, sourceFile);
-    return !!forEach(leadingCommentRanges, range => {
-        return hasInternalAnnotation(range, sourceFile);
-    });
+    return !!parseTreeNode && !!getJSDocInternalTag(parseTreeNode);
 }

tests/baselines/reference/api/typescript.d.ts

@@ -3978,12 +3978,13 @@ declare namespace ts {
         JSDocThrowsTag = 349,
         JSDocSatisfiesTag = 350,
         JSDocImportTag = 351,
-        SyntaxList = 352,
-        NotEmittedStatement = 353,
-        PartiallyEmittedExpression = 354,
-        CommaListExpression = 355,
-        SyntheticReferenceExpression = 356,
-        Count = 357,
+        JSDocInternalTag = 352,
+        SyntaxList = 353,
+        NotEmittedStatement = 354,
+        PartiallyEmittedExpression = 355,
+        CommaListExpression = 356,
+        SyntheticReferenceExpression = 357,
+        Count = 358,
         FirstAssignment = 64,
         LastAssignment = 79,
         FirstCompoundAssignment = 65,
@@ -5823,6 +5824,10 @@ declare namespace ts {
         readonly moduleSpecifier: Expression;
         readonly attributes?: ImportAttributes;
     }
+    interface JSDocInternalTag extends JSDocTag {
+        readonly kind: SyntaxKind.JSDocInternalTag;
+        readonly typeExpression: JSDocTypeExpression;
+    }
     type FlowType = Type | IncompleteType;
     interface IncompleteType {
         flags: TypeFlags | 0;
@@ -7691,6 +7696,8 @@ declare namespace ts {
         updateJSDocSatisfiesTag(node: JSDocSatisfiesTag, tagName: Identifier | undefined, typeExpression: JSDocTypeExpression, comment: string | NodeArray<JSDocComment> | undefined): JSDocSatisfiesTag;
         createJSDocImportTag(tagName: Identifier | undefined, importClause: ImportClause | undefined, moduleSpecifier: Expression, attributes?: ImportAttributes, comment?: string | NodeArray<JSDocComment>): JSDocImportTag;
         updateJSDocImportTag(node: JSDocImportTag, tagName: Identifier | undefined, importClause: ImportClause | undefined, moduleSpecifier: Expression, attributes: ImportAttributes | undefined, comment: string | NodeArray<JSDocComment> | undefined): JSDocImportTag;
+        createJSDocInternalTag(tagName: Identifier | undefined, comment?: string | NodeArray<JSDocComment>): JSDocInternalTag;
+        updateJSDocInternalTag(node: JSDocInternalTag, tagName: Identifier | undefined, comment: string | NodeArray<JSDocComment> | undefined): JSDocInternalTag;
         createJSDocText(text: string): JSDocText;
         updateJSDocText(node: JSDocText, text: string): JSDocText;
         createJSDocComment(comment?: string | NodeArray<JSDocComment> | undefined, tags?: readonly JSDocTag[] | undefined): JSDoc;
@@ -8109,15 +8116,16 @@ declare namespace ts {
          * Parse only JSDoc comments which are needed to provide correct type errors.
          *
          * This will always parse JSDoc in non-TS files, but only parse JSDoc comments
-         * containing `@see` and `@link` in TS files.
+         * containing `see`, `link`, and `internal` in TS files.
          */
         ParseForTypeErrors = 2,
         /**
          * Parse only JSDoc comments which are needed to provide correct type info.
          *
          * This will always parse JSDoc in non-TS files, but never in TS files.
          *
-         * Note: Do not use this mode if you require accurate type errors; use {@link ParseForTypeErrors} instead.
+         * Note: Do not use this mode if you require accurate type errors or need to
+         * observe `internal` JSDoc tags; use {@link ParseForTypeErrors} instead.
          */
         ParseForTypeInfo = 3,
     }
@@ -8545,6 +8553,7 @@ declare namespace ts {
     /** Gets the JSDoc template tag for the node if present */
     function getJSDocTemplateTag(node: Node): JSDocTemplateTag | undefined;
     function getJSDocSatisfiesTag(node: Node): JSDocSatisfiesTag | undefined;
+    function getJSDocInternalTag(node: Node): JSDocInternalTag | undefined;
     /** Gets the JSDoc type tag for the node if present and valid */
     function getJSDocTypeTag(node: Node): JSDocTypeTag | undefined;
     /**
@@ -8994,6 +9003,7 @@ declare namespace ts {
     function isJSDocSatisfiesTag(node: Node): node is JSDocSatisfiesTag;
     function isJSDocThrowsTag(node: Node): node is JSDocThrowsTag;
     function isJSDocImportTag(node: Node): node is JSDocImportTag;
+    function isJSDocInternalTag(node: Node): node is JSDocInternalTag;
     function isQuestionOrExclamationToken(node: Node): node is QuestionToken | ExclamationToken;
     function isIdentifierOrThisTypeNode(node: Node): node is Identifier | ThisTypeNode;
     function isReadonlyKeywordOrPlusOrMinusToken(node: Node): node is ReadonlyKeyword | PlusToken | MinusToken;

tests/baselines/reference/declarationEmitWorkWithInlineComments.js

@@ -93,7 +93,9 @@ exports.Baz = Baz;
 
 //// [declarationEmitWorkWithInlineComments.d.ts]
 export declare class Foo {
-    notInternal1: string;
+    isInternal4: string;
+    isInternal6: string;
+    isInternal7: string;
     notInternal2: string;
     notInternal3: string;
     constructor(
@@ -104,8 +106,10 @@ export declare class Foo {
     isInternal5: string, isInternal6: string, isInternal7: string, /** @internal */ notInternal1: string, notInternal2: string, notInternal3: string);
 }
 export declare class Bar {
+    isInternal1: string;
     constructor(/* @internal */ isInternal1: string);
 }
 export declare class Baz {
+    isInternal: string;
     constructor(/* @internal */ isInternal: string);
 }

tests/baselines/reference/stripInternal1.js

@@ -21,4 +21,5 @@ var C = /** @class */ (function () {
 //// [stripInternal1.d.ts]
 declare class C {
     foo(): void;
+    bar(): void;
 }