tsc-ts 0.0.4 → 0.0.6

package/dist/api/compiler/checker-jsdoc.js

@@ -0,0 +1,320 @@
+// JSDoc semantics: the intended types of JSDoc type references like `String`, `function` and
+// `Object<K, V>`, functions typed by a JSDoc `@type` tag, and `@param` tags without parameters.
+import { ArrowFunction, FunctionDeclaration, FunctionExpression, MethodDeclaration, NodeVisitor, getBody, getDotDotDotToken, getExpression, getInitializer, getName, getParameters, getText, getType, } from './ast.js';
+import { getSourceFileOfNode, isTypeNodeKind } from './binder-utilities.js';
+import { getAttachedJSDoc, getJSDoc } from './parser.js';
+import { isInJSFile } from './ast-utilities.js';
+import { getGlobalTypeAliasSymbol } from './checker-symbols.js';
+import { checkNoTypeArguments, getTypeAliasInstantiation, getTypeFromTypeNode } from './checker-type-nodes.js';
+import { createPromiseType } from './checker-iteration.js';
+import { isValidIndexKeyType } from './checker-utilities.js';
+import { getRestTypeAtPosition, getReturnTypeOfSignature, getSingleCallSignature, getTypeAtPosition, } from './checker-signatures.js';
+import { getContextualCallSignature } from './checker-contextual.js';
+import { entityNameToString, getResolvedSymbol } from './checker-expressions.js';
+import { isArrayType } from './checker-type-factory.js';
+/** The type a JSDoc type reference to a JavaScript-style name means, if it is one. */
+export function getIntendedTypeFromJSDocTypeReference(c, node) {
+    if ((node.flags & 4194304 /* NodeFlags.JSDoc */) === 0 || node.kind !== 184 /* SyntaxKind.TypeReference */)
+        return undefined;
+    const reference = node;
+    const typeName = reference.typeName;
+    if (typeName.kind !== 79 /* SyntaxKind.Identifier */)
+        return undefined;
+    const typeArguments = reference.typeArguments !== undefined ? reference.typeArguments.nodes : [];
+    switch (getText(typeName)) {
+        case 'String':
+            checkNoTypeArguments(c, node, undefined);
+            return c.stringType;
+        case 'Number':
+            checkNoTypeArguments(c, node, undefined);
+            return c.numberType;
+        case 'BigInt':
+            checkNoTypeArguments(c, node, undefined);
+            return c.bigintType;
+        case 'Boolean':
+            checkNoTypeArguments(c, node, undefined);
+            return c.booleanType;
+        case 'Void':
+            checkNoTypeArguments(c, node, undefined);
+            return c.voidType;
+        case 'Undefined':
+            checkNoTypeArguments(c, node, undefined);
+            return c.undefinedType;
+        case 'Null':
+            checkNoTypeArguments(c, node, undefined);
+            return c.nullType;
+        case 'Function':
+        case 'function':
+            checkNoTypeArguments(c, node, undefined);
+            return c.globalFunctionType;
+        case 'array':
+            if (typeArguments.length === 0 && !c.noImplicitAny)
+                return c.anyArrayType;
+            break;
+        case 'promise':
+            if (typeArguments.length === 0 && !c.noImplicitAny)
+                return createPromiseType(c, c.anyType);
+            break;
+        case 'Object':
+            if (typeArguments.length === 2) {
+                const recordSymbol = getGlobalTypeAliasSymbol(c, 'Record', 2, true);
+                if (recordSymbol !== undefined) {
+                    const indexType = getTypeFromTypeNode(c, typeArguments[0]);
+                    if (isValidIndexKeyType(c, indexType))
+                        return getTypeAliasInstantiation(c, recordSymbol, [indexType, getTypeFromTypeNode(c, typeArguments[1])], undefined);
+                }
+                return c.anyType;
+            }
+            if (!c.noImplicitAny) {
+                checkNoTypeArguments(c, node, undefined);
+                return c.anyType;
+            }
+            break;
+    }
+    return undefined;
+}
+// ---- Functions typed by `@type`
+/** The JSDoc `@type` of a function, method or arrow function in a JavaScript file. */
+export function getFullSignatureTypeNode(node) {
+    if (!isInJSFile(node))
+        return undefined;
+    if (node instanceof FunctionDeclaration)
+        return node.fullSignature;
+    if (node instanceof MethodDeclaration)
+        return node.fullSignature;
+    if (node instanceof FunctionExpression)
+        return node.fullSignature;
+    if (node instanceof ArrowFunction)
+        return node.fullSignature;
+    return undefined;
+}
+/** The signature a JSDoc `@type` tag gives a function. */
+export function getSignatureOfFullSignatureType(c, node) {
+    const typeNode = getFullSignatureTypeNode(node);
+    return typeNode !== undefined ? getSingleCallSignature(c, getTypeFromTypeNode(c, typeNode)) : undefined;
+}
+/** The type of a parameter of a function typed by a JSDoc `@type` tag. */
+export function getParameterTypeOfFullSignature(c, fn, parameter) {
+    const signature = getSignatureOfFullSignatureType(c, fn);
+    if (signature === undefined)
+        return undefined;
+    const pos = getParameters(fn).nodes.indexOf(parameter);
+    return getDotDotDotToken(parameter) !== undefined
+        ? getRestTypeAtPosition(c, signature, pos, false)
+        : getTypeAtPosition(c, signature, pos);
+}
+/** The return type of a function typed by a JSDoc `@type` tag. */
+export function getReturnTypeOfFullSignature(c, fn) {
+    const signature = getSignatureOfFullSignatureType(c, fn);
+    return signature !== undefined ? getReturnTypeOfSignature(c, signature) : undefined;
+}
+/** A JSDoc `@type` on a function needs a call signature taking at least its parameters. */
+export function checkJSDocFullSignature(c, fn) {
+    const typeNode = getFullSignatureTypeNode(fn);
+    if (typeNode === undefined)
+        return;
+    if (getContextualCallSignature(c, getTypeFromTypeNode(c, typeNode), fn) === undefined)
+        c.error(typeNode, 1759 /* Diagnostics.A_JSDoc_type_tag_on_a_function_must_have_a_signature_with_the_correct_number_of_arguments */);
+}
+// ---- `@param` tags
+/** The tags of the last JSDoc comment of `node` or of the declaration or statement it heads. */
+function getAllJSDocTags(node) {
+    if ((node.flags & 4194304 /* NodeFlags.JSDoc */) !== 0)
+        return [];
+    const file = getSourceFileOfNode(node);
+    for (let current = node; current !== undefined; current = getNextJSDocCommentLocation(current)) {
+        const jsDoc = getJSDoc(file, current);
+        if (jsDoc.length === 0)
+            continue;
+        const tags = jsDoc[jsDoc.length - 1].tags;
+        if (tags !== undefined)
+            return tags.nodes;
+    }
+    return [];
+}
+function getNextJSDocCommentLocation(node) {
+    const parent = node.parent;
+    if (parent === undefined)
+        return undefined;
+    switch (parent.kind) {
+        case 303 /* SyntaxKind.PropertyAssignment */:
+        case 278 /* SyntaxKind.ExportAssignment */:
+        case 173 /* SyntaxKind.PropertyDeclaration */:
+        case 261 /* SyntaxKind.VariableDeclaration */:
+        case 239 /* SyntaxKind.SatisfiesExpression */:
+        case 254 /* SyntaxKind.ReturnStatement */:
+        case 244 /* SyntaxKind.VariableStatement */:
+        case 245 /* SyntaxKind.ExpressionStatement */:
+            return parent;
+        case 262 /* SyntaxKind.VariableDeclarationList */:
+            return parent.declarations.nodes[0] === node ? parent : undefined;
+    }
+    return undefined;
+}
+/**
+ * Reports `@param` tags of a JavaScript function naming no parameter, and qualified `@param` names
+ * without a parent `@param {object}`.
+ */
+export function checkUnmatchedJSDocParameters(c, node) {
+    // Only JavaScript files report unmatched tags. In a TypeScript file with `@param` tags, tsgo still resolves the
+    // `arguments` references of the body (containsArgumentsReference), which can report errors, such as TS2448 for a
+    // `const arguments`. The JSDoc of a TypeScript function is parsed only when its file has an identifier `arguments`.
+    const isJs = isInJSFile(node);
+    if (!isJs && !fileMentionsArguments(c, node))
+        return;
+    const jsdocParameters = [];
+    for (const tag of getAllJSDocTags(node)) {
+        if (tag.kind !== 333 /* SyntaxKind.JSDocParameterTag */)
+            continue;
+        const name = tag.name;
+        if (name.kind === 79 /* SyntaxKind.Identifier */ && getText(name).length === 0)
+            continue;
+        jsdocParameters.push(tag);
+    }
+    if (jsdocParameters.length === 0)
+        return;
+    const parameters = new Set();
+    const excludedParameters = new Set();
+    const params = getParameters(node).nodes;
+    for (let i = 0; i < params.length; i++) {
+        const name = getName(params[i]);
+        if (name.kind === 79 /* SyntaxKind.Identifier */)
+            parameters.add(getText(name));
+        if (name.kind === 207 /* SyntaxKind.ObjectBindingPattern */ || name.kind === 208 /* SyntaxKind.ArrayBindingPattern */)
+            excludedParameters.add(i);
+    }
+    if (containsArgumentsReference(c, node)) {
+        if (!isJs)
+            return;
+        const lastIndex = jsdocParameters.length - 1;
+        const last = jsdocParameters[lastIndex];
+        if (last.name.kind !== 79 /* SyntaxKind.Identifier */)
+            return;
+        if (excludedParameters.has(lastIndex) || parameters.has(getText(last.name)))
+            return;
+        const typeExpression = last.typeExpression;
+        const typeNode = typeExpression !== undefined ? getType(typeExpression) : undefined;
+        if (typeNode === undefined || isArrayType(c, getTypeFromTypeNode(c, typeNode)))
+            return;
+        c.error(last.name, 1758 /* 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 */, getText(last.name));
+        return;
+    }
+    if (!isJs)
+        return;
+    for (let index = 0; index < jsdocParameters.length; index++) {
+        const tag = jsdocParameters[index];
+        const name = tag.name;
+        if (excludedParameters.has(index) || (name.kind === 79 /* SyntaxKind.Identifier */ && parameters.has(getText(name))))
+            continue;
+        if (name.kind === 167 /* SyntaxKind.QualifiedName */)
+            c.error(name, 1761 /* Diagnostics.Qualified_name_0_is_not_allowed_without_a_leading_param_object_1 */, entityNameToString(name), entityNameToString(name.left));
+        else if (!tag.isNameFirst)
+            c.error(name, 1753 /* Diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name */, getText(name));
+    }
+}
+/** Finds a reference to `arguments` outside nested functions and types. */
+class ArgumentsReferenceFinder extends NodeVisitor {
+    c;
+    constructor(c) {
+        super();
+        this.c = c;
+    }
+    visitNode(node) {
+        switch (node.kind) {
+            case 79 /* SyntaxKind.Identifier */:
+                return getText(node) === 'arguments' && getResolvedSymbol(this.c, node) === this.c.argumentsSymbol;
+            case 173 /* SyntaxKind.PropertyDeclaration */:
+            case 175 /* SyntaxKind.MethodDeclaration */:
+            case 178 /* SyntaxKind.GetAccessor */:
+            case 179 /* SyntaxKind.SetAccessor */: {
+                const name = getName(node);
+                if (name !== undefined && name.kind === 168 /* SyntaxKind.ComputedPropertyName */)
+                    return this.visitNode(name);
+                break;
+            }
+            case 212 /* SyntaxKind.PropertyAccessExpression */:
+            case 213 /* SyntaxKind.ElementAccessExpression */:
+                return this.visitNode(getExpression(node));
+            case 303 /* SyntaxKind.PropertyAssignment */:
+                return this.visitNode(getInitializer(node));
+        }
+        if (startsNewLexicalEnvironment(node) || isTypeNodeKind(node.kind))
+            return false;
+        return node.forEachChild(this);
+    }
+}
+function startsNewLexicalEnvironment(node) {
+    switch (node.kind) {
+        case 177 /* SyntaxKind.Constructor */:
+        case 219 /* SyntaxKind.FunctionExpression */:
+        case 263 /* SyntaxKind.FunctionDeclaration */:
+        case 220 /* SyntaxKind.ArrowFunction */:
+        case 175 /* SyntaxKind.MethodDeclaration */:
+        case 178 /* SyntaxKind.GetAccessor */:
+        case 179 /* SyntaxKind.SetAccessor */:
+        case 268 /* SyntaxKind.ModuleDeclaration */:
+        case 307 /* SyntaxKind.SourceFile */:
+            return true;
+    }
+    return false;
+}
+/** Whether the file of `node` has an identifier `arguments`; cached in the links of the source file. */
+function fileMentionsArguments(c, node) {
+    const file = getSourceFileOfNode(node);
+    const links = c.nodeLinks(file);
+    if (links.mentionsArguments === 0)
+        links.mentionsArguments = file.identifierTexts.includes('arguments') ? 2 : 1;
+    return links.mentionsArguments === 2;
+}
+function containsArgumentsReference(c, node) {
+    const body = getBody(node);
+    if (body === undefined)
+        return false;
+    const links = c.nodeLinks(node);
+    if (links.containsArgumentsReference === 0)
+        links.containsArgumentsReference = new ArgumentsReferenceFinder(c).visitNode(body) ? 2 : 1;
+    return links.containsArgumentsReference === 2;
+}
+// ---- `@augments`
+/** The rightmost identifier of `a.b.c`, or `a` itself. */
+function getIdentifierFromEntityNameExpression(node) {
+    if (node.kind === 79 /* SyntaxKind.Identifier */)
+        return node;
+    if (node.kind === 212 /* SyntaxKind.PropertyAccessExpression */)
+        return getName(node);
+    return undefined;
+}
+/** An `@augments` or `@extends` tag naming another class than the `extends` clause. */
+export class AugmentsMismatch {
+    name;
+    tagName;
+    className;
+    extendsName;
+    constructor(name, tagName, className, extendsName) {
+        this.name = name;
+        this.tagName = tagName;
+        this.className = className;
+        this.extendsName = extendsName;
+    }
+}
+/** The `@augments` or `@extends` tag of a class whose class name differs from its `extends` clause. */
+export function findMismatchedAugmentsTag(classLike, extendsType) {
+    const jsDoc = getAttachedJSDoc(classLike);
+    if (jsDoc === undefined)
+        return undefined;
+    for (const j of jsDoc) {
+        const tags = j.tags;
+        if (tags === undefined)
+            continue;
+        for (const tag of tags.nodes) {
+            if (tag.kind !== 323 /* SyntaxKind.JSDocAugmentsTag */)
+                continue;
+            const augments = tag;
+            const targetName = getIdentifierFromEntityNameExpression(extendsType.expression);
+            const sourceName = getIdentifierFromEntityNameExpression(augments.className.expression);
+            if (targetName !== undefined && sourceName !== undefined && getText(targetName) !== getText(sourceName))
+                return new AugmentsMismatch(sourceName, getText(augments.tagName), getText(sourceName), getText(targetName));
+        }
+    }
+    return undefined;
+}

package/dist/api/compiler/checker-jsx.d.ts

@@ -0,0 +1,94 @@
+import { type JsxAttributes, type Node, type SourceFile } from './ast.js';
+import { Diagnostic } from './diagnostics.js';
+import { type Checker } from './checker.js';
+import { CheckMode, type Signature, type Type } from './checker-types.js';
+import { type Relation } from './relations.js';
+import { ContextFlags } from './checker-contextual.js';
+import { type InferenceContext } from './checker-inference.js';
+import { type Symbol } from './symbol.js';
+declare const enum JsxFlags {
+    None = 0,
+    /** An element from a named property of `JSX.IntrinsicElements`. */
+    IntrinsicNamedElement = 1,
+    /** An element from the string index signature of `JSX.IntrinsicElements`. */
+    IntrinsicIndexedElement = 2
+}
+/** Per-element JSX state. */
+declare class JsxElementLinks {
+    jsxFlags: JsxFlags;
+    resolvedJsxElementAttributesType: Type | undefined;
+    resolvedSymbol: Symbol | undefined;
+    /** The resolved `JSX` namespace; `unknownSymbol` when the local lookup failed. */
+    jsxNamespace: Symbol | undefined;
+}
+/** Per-file JSX state: pragmas, factories and the implicit runtime import. */
+declare class JsxFileLinks {
+    localJsxNamespace: string;
+    localJsxFactory: Node | undefined;
+    localJsxFragmentNamespace: string;
+    localJsxFragmentFactory: Node | undefined;
+    jsxFragmentType: Type | undefined;
+    /** `unknownSymbol` when there is no implicit import container. */
+    jsxImplicitImportContainer: Symbol | undefined;
+}
+/** The checker's JSX caches. */
+export declare class JsxState {
+    readonly elementLinks: Map<Node, JsxElementLinks>;
+    readonly fileLinks: Map<SourceFile, JsxFileLinks>;
+    /** getJsxIntrinsicConstructorType by attributes and element type ids. */
+    readonly intrinsicConstructorTypes: Map<string, Type>;
+    jsxNamespace: string;
+    jsxFactoryEntity: Node | undefined;
+}
+export declare function isJsxOpeningLikeElement(node: Node): boolean;
+/** Whether a tag name refers to an intrinsic element: a lowercase or dashed identifier, or `ns:name`. */
+export declare function isJsxIntrinsicTagName(tagName: Node): boolean;
+export declare function getTagNameOf(node: Node): Node;
+export declare function getAttributesOf(node: Node): JsxAttributes;
+/** Children that produce values: non-empty expressions, non-whitespace text and elements. */
+export declare function getSemanticJsxChildren(children: readonly Node[]): Node[];
+/** The name of the factory namespace in scope at `location`, such as `React`. */
+export declare function getJsxNamespace(c: Checker, location: Node | undefined): string;
+/** The module of the automatic runtime's implicit import, such as `react/jsx-runtime`. */
+export declare function getJsxNamespaceContainerForImplicitImport(c: Checker, location: Node): Symbol | undefined;
+/** The `JSX` namespace for `location`: the factory's, the runtime module's, or the global one. */
+export declare function getJsxNamespaceAt(c: Checker, location: Node): Symbol | undefined;
+export declare function getJsxType(c: Checker, name: string, location: Node): Type;
+/** `JSX.Element`, or the error type when it doesn't exist. */
+export declare function getJsxElementTypeAt(c: Checker, location: Node): Type;
+export declare function getJsxElementChildrenPropertyName(c: Checker, ns: Symbol | undefined): string;
+/**
+ * The `JSX.IntrinsicElements` property or index signature for an intrinsic tag, recording which in the
+ * element's flags; `unknownSymbol` when neither exists.
+ */
+export declare function getIntrinsicTagSymbol(c: Checker, node: Node): Symbol;
+/** The props type a signature expects of an element's attributes. */
+export declare function getEffectiveFirstArgumentForJsxSignature(c: Checker, signature: Signature, node: Node): Type;
+export declare function checkJsxAttribute(c: Checker, node: Node, checkMode: CheckMode): Type;
+export declare function checkJsxChildren(c: Checker, node: Node, checkMode: CheckMode): Type[];
+/** The object type of an element's attributes and children, like an object literal's. */
+export declare function createJsxAttributesTypeFromAttributesProperty(c: Checker, openingLikeElement: Node, checkMode: CheckMode): Type;
+export declare function isTupleLikeType(c: Checker, t: Type): boolean;
+export declare function isArrayOrTupleLikeType(c: Checker, t: Type): boolean;
+/** The attributes argument of an element, if it has attributes or children. */
+export declare function getEffectiveJsxArguments(node: Node): Node[];
+/** Whether `signature` accepts the element's attributes, reporting why not when `reportErrors`. */
+export declare function checkApplicableSignatureForJsxCallLikeElement(c: Checker, node: Node, signature: Signature, relation: Relation, checkMode: CheckMode, reportErrors: boolean, diagnosticOutput: Diagnostic[] | undefined): boolean;
+export declare function resolveJsxOpeningLikeElement(c: Checker, node: Node, checkMode: CheckMode): Signature;
+/** The signature an element resolves to, computed once. */
+export declare function getResolvedJsxSignature(c: Checker, node: Node): Signature;
+/** Infers a generic component's type arguments from the element's attributes. */
+export declare function inferJsxTypeArguments(c: Checker, node: Node, signature: Signature, checkMode: CheckMode, context: InferenceContext): Type[];
+/** Checks a JSX expression, element, fragment or attributes node. */
+export declare function checkJsx(c: Checker, node: Node, checkMode: CheckMode): Type;
+/** The deferred check of an element: its signature, closing tag and children. */
+export declare function checkJsxElementDeferred(c: Checker, node: Node): void;
+export declare function getContextualTypeForJsxExpression(c: Checker, node: Node, contextFlags: ContextFlags): Type | undefined;
+export declare function getContextualTypeForJsxAttribute(c: Checker, attribute: Node, contextFlags: ContextFlags): Type | undefined;
+export declare function getContextualJsxElementAttributesType(c: Checker, node: Node, contextFlags: ContextFlags): Type | undefined;
+export declare function isJsxAttributesContextSensitive(c: Checker, node: Node): boolean;
+/** Reports attribute and children errors at the attributes and children themselves. */
+export declare function elaborateJsxComponents(c: Checker, node: Node, source: Type, target: Type, relation: Relation, diagnosticOutput: Diagnostic[] | undefined): boolean;
+/** Suggests `htmlFor` for `for`, `className` for `class`, or a similar property name. */
+export declare function getSuggestedSymbolForNonexistentJSXAttribute(c: Checker, name: string, containingType: Type): Symbol | undefined;
+export {};