@runtime-type-inspector/repl 3.2.2 → 3.2.4

package/ts-to-jsdoc-test.js

@@ -0,0 +1,31 @@
+//import {transpile} from "ts-to-jsdoc";
+import {transpile} from "./ts-to-jsdoc.js";
+const ret = transpile(`
+
+import type {
+	ImportDeclaration,
+	ClassDeclaration,
+	FunctionLikeDeclaration,
+	InterfaceDeclaration,
+	JSDoc,
+	JSDocableNode,
+	MethodDeclaration,
+	ModifierableNode,
+	PropertyAssignment,
+	PropertyDeclaration,
+	PropertySignature,
+	TypeAliasDeclaration,
+	TypedNode,
+	VariableDeclaration,
+} from "ts-morph";
+
+import type {
+A,B
+} from "abc";
+
+/***/
+const groups: Record<string, string[]> = {
+  test: ['a', 'b']
+} as const;
+`);
+console.log(ret);

package/ts-to-jsdoc.js

@@ -0,0 +1,460 @@
+import path from "path";
+//import * as ts from 'typescript';
+//debugger;
+//const ScriptTarget = ts.ScriptTarget;
+import * as tsDefault from 'typescript';
+const ts = tsDefault.default;
+import {
+    Node,
+    Project,
+    //ScriptTarget,
+    //SyntaxKind
+} from "./ts-morph.js";
+const {
+    //Project,
+    ScriptTarget,
+    SyntaxKind,
+} = ts;
+//import { Node, Project, ScriptTarget, SyntaxKind, } from "ts-morph";
+Node.isObjectProperty = (node) => (Node.isPropertyDeclaration(node)
+    || Node.isPropertyAssignment(node)
+    || Node.isPropertySignature(node));
+/**
+ * Get children for object node
+ * @param {Node} node
+ * @returns {ObjectProperty[]}
+ */
+function getChildProperties(node) {
+    const properties = node?.getType()?.getProperties();
+    const valueDeclarations = properties.map((child) => child.getValueDeclaration())
+        // Hacky way to check if the child is actually a defined child in the interface
+        // or if it's, e.g. a built-in method of the type (such as array.length)
+        ?.filter((child) => node.getFullText().includes(child?.getFullText()));
+    return (valueDeclarations ?? []);
+}
+/**
+ * @param {JSDocableNode} node
+ * @returns {JSDoc | undefined}
+ */
+function getJsDoc(node) {
+    return node.getJsDocs().at(-1);
+}
+/**
+ * Get JSDoc for a node or create one if there isn't any
+ * @param {JSDocableNode} node
+ * @returns {JSDoc}
+ */
+function getJsDocOrCreate(node) {
+    return getJsDoc(node) || node.addJsDoc({});
+}
+/**
+ * getJsDocOrCreate, but if JSDoc is created, insert a newline at the beginning
+ * so that the first line of JSDoc doesn't appear on the same line as `/**`
+ * @param {JSDocableNode} node
+ * @returns {JSDoc}
+ */
+function getJsDocOrCreateMultiline(node) {
+    return getJsDoc(node) || node.addJsDoc({
+        description: "\n",
+    });
+}
+/**
+ * Return the node most suitable for JSDoc for a function, adding JSDoc if there isn't any
+ * @param {FunctionLikeDeclaration} functionNode
+ * @param {JSDocableNode} [docNode]
+ * @returns {JSDocableNode}
+ */
+function getOutputJsDocNodeOrCreate(functionNode, docNode) {
+    if (docNode) {
+        const funcNodeDocs = functionNode.getJsDocs();
+        if (funcNodeDocs.length)
+            return functionNode;
+        getJsDocOrCreateMultiline(docNode);
+        return docNode;
+    }
+    getJsDocOrCreateMultiline(functionNode);
+    return functionNode;
+}
+/**
+ * Generate `@param` documentation from function parameters for functionNode, storing it in docNode
+ * @param {FunctionLikeDeclaration} functionNode
+ * @param {JSDocableNode} docNode
+ * @returns {void}
+ */
+function generateParameterDocumentation(functionNode, docNode) {
+    const params = functionNode.getParameters();
+    if (!params.length)
+        return;
+    const jsDoc = getJsDocOrCreateMultiline(docNode);
+    // Get existing param tags, store their comments, then remove them
+    const paramTags = (jsDoc.getTags() || [])
+        .filter((tag) => ["param", "parameter"].includes(tag.getTagName()));
+    const commentLookup = Object.fromEntries(paramTags.map((tag) => [
+        // @ts-ignore
+        tag.compilerNode.name?.getText().replace(/\[|\]|(=.*)/g, "").trim(),
+        (tag.getComment() || "").toString().trim(),
+    ]));
+    const preferredTagName = paramTags[0]?.getTagName();
+    paramTags.forEach((tag) => tag.remove());
+    for (const param of params) {
+        const paramType = param.getTypeNode()?.getText() || param.getType().getText();
+        if (!paramType)
+            continue;
+        const paramName = param.compilerNode.name?.getText();
+        const isOptional = param.isOptional();
+        const isRest = param.isRestParameter();
+        // Rest parameters are arrays, but the JSDoc syntax is `...number` instead of `number[]`
+        const paramTypeOut = isRest ? `...${paramType.replace(/\[\]\s*$/, "")}` : paramType;
+        let defaultValue;
+        if (isOptional) {
+            const paramInitializer = param.getInitializer();
+            defaultValue = paramInitializer?.getText().replaceAll(/(\s|\t)*\n(\s|\t)*/g, " ");
+        }
+        let paramNameOut = paramName;
+        // Skip parameter names if they are present in the type as an object literal
+        // e.g. destructuring; { a }: { a: string }
+        if (paramNameOut.match(/[{},]/))
+            paramNameOut = "";
+        if (paramNameOut && isOptional) {
+            // Wrap name in square brackets if the parameter is optional
+            const defaultValueOut = defaultValue !== undefined ? `=${defaultValue}` : "";
+            paramNameOut = `[${paramNameOut}${defaultValueOut}]`;
+        }
+        paramNameOut = paramNameOut ? ` ${paramNameOut}` : "";
+        const comment = commentLookup[paramName.trim()];
+        jsDoc.addTag({
+            tagName: preferredTagName || "param",
+            text: `{${paramTypeOut}}${paramNameOut}${comment ? ` ${comment}` : ""}`,
+        });
+    }
+}
+/**
+ * Generate `@returns` documentation from function return type for functionNode, storing it in docNode
+ * @param {FunctionLikeDeclaration} functionNode
+ * @param {JSDocableNode} docNode
+ * @returns {void}
+ */
+function generateReturnTypeDocumentation(functionNode, docNode) {
+    const returnTypeNode = functionNode.getReturnTypeNode() ?? functionNode.getReturnType();
+    const functionReturnType = returnTypeNode.getText(functionNode.getSignature().getDeclaration());
+    const jsDoc = getJsDocOrCreate(docNode);
+    const returnsTag = (jsDoc?.getTags() || [])
+        .find((tag) => ["returns", "return"].includes(tag.getTagName()));
+    // Replace tag with one that contains type info if tag exists
+    const tagName = returnsTag?.getTagName() || "returns";
+    const comment = (returnsTag?.getComment() || "").toString().trim();
+    if (returnsTag) {
+        returnsTag.remove();
+    }
+    jsDoc.addTag({
+        tagName,
+        text: `{${functionReturnType}}${comment ? ` ${comment}` : ""}`,
+    });
+}
+/**
+ * Generate documentation for a function, storing it in functionNode or docNode
+ * @param {FunctionLikeDeclaration} functionNode
+ * @param {JSDocableNode} [docNode]
+ * @returns {void}
+ */
+function generateFunctionDocumentation(functionNode, docNode) {
+    const outputDocNode = getOutputJsDocNodeOrCreate(functionNode, docNode);
+    generateParameterDocumentation(functionNode, outputDocNode);
+    generateReturnTypeDocumentation(functionNode, outputDocNode);
+}
+/**
+ * Generate modifier documentation for class member
+ * @param {ClassMemberNode} classMemberNode
+ * @returns {void}
+ */
+function generateModifierDocumentation(classMemberNode) {
+    const modifiers = classMemberNode.getModifiers() || [];
+    for (const modifier of modifiers) {
+        const text = modifier?.getText();
+        if (["public", "private", "protected", "readonly", "static"].includes(text)) {
+            const jsDoc = getJsDocOrCreateMultiline(classMemberNode);
+            jsDoc.addTag({ tagName: text });
+        }
+    }
+}
+/**
+ * Create class property initializer in constructor if it doesn't exist
+ * so that documentation is preserved when transpiling
+ * @param {ObjectProperty} classPropertyNode
+ * @returns {void}
+ */
+function generateInitializerDocumentation(classPropertyNode) {
+    if (!classPropertyNode.getStructure()?.initializer) {
+        classPropertyNode.setInitializer("undefined");
+    }
+    const initializer = classPropertyNode.getStructure()?.initializer;
+    if (initializer !== "undefined") {
+        const jsDoc = getJsDocOrCreate(classPropertyNode);
+        jsDoc.addTag({ tagName: "default", text: initializer });
+    }
+}
+/**
+ * Document the class itself; at the moment just its extends signature
+ * @param {ClassDeclaration} classNode
+ * @returns {void}
+ */
+function generateClassBaseDocumentation(classNode) {
+    const extendedClass = classNode.getExtends();
+    if (extendedClass) {
+        const jsDoc = getJsDocOrCreate(classNode);
+        jsDoc.addTag({ tagName: "extends", text: extendedClass.getText() });
+    }
+}
+/**
+ * Generate documentation for class members in general; either property or method
+ * @param {ClassMemberNode} classMemberNode
+ * @returns {void}
+ */
+function generateClassMemberDocumentation(classMemberNode) {
+    generateModifierDocumentation(classMemberNode);
+    Node.isObjectProperty(classMemberNode) && generateInitializerDocumentation(classMemberNode);
+    Node.isMethodDeclaration(classMemberNode) && generateFunctionDocumentation(classMemberNode);
+}
+/**
+ * Generate documentation for a class — itself and its members
+ * @param {ClassDeclaration} classNode
+ * @returns {void}
+ */
+function generateClassDocumentation(classNode) {
+    generateClassBaseDocumentation(classNode);
+    classNode.getMembers().forEach(generateClassMemberDocumentation);
+}
+/**
+ * Generate `@typedefs` from type aliases
+ * @param {TypeAliasDeclaration} typeAlias
+ * @return {string} A JSDoc comment containing the typedef
+ */
+function generateTypedefDocumentation(typeAlias) {
+    const name = typeAlias.getName();
+    const typeNode = typeAlias.getTypeNode();
+    const isObjectType = Node.isTypeLiteral(typeNode) && typeAlias.getType().isObject();
+    const properties = isObjectType ? typeNode.getProperties() : [];
+    const typeParams = typeAlias.getTypeParameters();
+    // If we're going to have multiple tags, we need to create a multiline JSDoc
+    const jsDoc = properties.length || typeParams.length
+        ? getJsDocOrCreateMultiline(typeAlias)
+        : getJsDocOrCreate(typeAlias);
+    if (Node.isTypeLiteral(typeNode) && typeAlias.getType().isObject()) {
+        jsDoc.addTag({ tagName: "typedef", text: `{Object} ${name}` });
+        typeNode.getProperties().forEach((prop) => {
+            generateObjectPropertyDocumentation(prop, jsDoc);
+        });
+    }
+    else {
+        const { type } = typeAlias.getStructure();
+        if (typeof type !== "string")
+            return jsDoc.getFullText();
+        jsDoc.addTag({ tagName: "typedef", text: `{${type}} ${name}` });
+    }
+    typeParams.forEach((param) => {
+        const constraint = param.getConstraint();
+        const defaultType = param.getDefault();
+        const paramName = param.getName();
+        const nameWithDefault = defaultType ? `[${paramName}=${defaultType.getText()}]` : paramName;
+        jsDoc.addTag({
+            tagName: "template",
+            text: `${constraint ? `{${constraint.getText()}} ` : ""}${nameWithDefault}`,
+        });
+    });
+    return jsDoc.getFullText();
+}
+/**
+ * Generate documentation for object properties; runs recursively for nested objects
+ * @param {ObjectProperty} node
+ * @param {JSDoc} jsDoc
+ * @param {string} [name=""] The name to assign child docs to;
+ * "obj" will generate docs for "obj.val1", "obj.val2", etc
+ * @param {boolean} [topLevelCall=true] recursive functions are funky
+ * @returns {void}
+ */
+function generateObjectPropertyDocumentation(node, jsDoc, name = "", topLevelCall = true) {
+    name = name || node.getName();
+    if (!topLevelCall)
+        name = `${name}.${node.getName()}`;
+    let propType = node.getTypeNode()
+        ?.getText()
+        ?.replace(/\n/g, "")?.trim();
+    const isOptional = node.hasQuestionToken()
+        || node.getJsDocs()?.[0]
+            ?.getTags()
+            ?.some((tag) => tag.getTagName() === "optional");
+    // Copy over existing description if there is one
+    const existingPropDocs = node.getJsDocs()?.[0]?.getDescription()?.trim() || "";
+    const children = getChildProperties(node);
+    if (children.length)
+        propType = "Object";
+    jsDoc.addTag({
+        tagName: "property",
+        text: `{${propType}} ${isOptional ? `[${name}]` : name} ${existingPropDocs}`,
+    });
+    if (children.length) {
+        children.forEach((child) => generateObjectPropertyDocumentation(child, jsDoc, name, false));
+    }
+}
+/**
+ * Generate `@typedefs` from interfaces
+ * @param {InterfaceDeclaration} interfaceNode
+ * @returns {string}
+ */
+function generateInterfaceDocumentation(interfaceNode) {
+    const name = interfaceNode.getName();
+    const jsDoc = getJsDocOrCreateMultiline(interfaceNode);
+    jsDoc.addTag({ tagName: "typedef", text: `{Object} ${name}` });
+    interfaceNode.getProperties().forEach((prop) => {
+        generateObjectPropertyDocumentation(prop, jsDoc);
+    });
+    return jsDoc.getFullText();
+}
+/**
+ * Generate documentation for top-level var, const, and let declarations
+ * @param {VariableDeclaration} varNode
+ * @returns {void}
+ */
+function generateTopLevelVariableDocumentation(varNode) {
+    const paramType = (varNode.getTypeNode() || varNode.getType())?.getText();
+    if (!paramType) {
+        return;
+    }
+    const jsDoc = getJsDoc(varNode.getVariableStatement());
+    if (!jsDoc) {
+        // Only generate documentation for variables that have an existing comment in JSDoc format
+        return;
+    }
+    const tags = jsDoc?.getTags() || [];
+    if (tags.find((tag) => ["type"].includes(tag.getTagName()))) {
+        return;
+    }
+    const constTag = tags.find((tag) => ["const", "constant"].includes(tag.getTagName()));
+    if (constTag && constTag.getComment()?.length) {
+        return;
+    }
+    jsDoc.addTag({
+        tagName: "type",
+        text: `{${paramType}}`,
+    });
+}
+/**
+ * Transpile.
+ * @param {string} src Source code to transpile
+ * @param {string} [filename="input.ts"] Filename to use internally when transpiling (can be a path or a name)
+ * @param {object} [compilerOptions={}] Options for the compiler.
+ * See https://www.typescriptlang.org/tsconfig#compilerOptions
+ * @param {boolean} [debug=false] Whether to log errors
+ * @return {string} Transpiled code (or the original source code if something went wrong)
+ */
+function transpile(src, filename = "input.ts", compilerOptions = {}, debug = false) {
+    // Useless variable to prevent comments from getting removed when code contains just
+    // typedefs/interfaces, which get transpiled to nothing but comments
+    const protectCommentsHeader = "const __tsToJsdoc_protectCommentsHeader = 1;\n";
+    src = protectCommentsHeader + src;
+    try {
+        const project = new Project({
+            compilerOptions: {
+                target: ScriptTarget.ESNext,
+                esModuleInterop: true,
+                ...compilerOptions,
+            },
+        });
+        // Preserve blank lines in output
+        const blankLineMarker = "// TS-TO-JSDOC BLANK LINE //";
+        const code = src.split("\n").map((line) => (line.match(/^[\s\t]*$/) ? (blankLineMarker + line) : line)).join("\n");
+        // ts-morph throws a fit if the path already exists
+        const sourceFile = project.createSourceFile(`${path.basename(filename, ".ts")}.ts-to-jsdoc.ts`, code);
+        sourceFile.getClasses().forEach(generateClassDocumentation);
+        // Convert something like:
+        //   import type {
+        // 	   ImportDeclaration,
+	    //     ClassDeclaration,
+	    //     FunctionLikeDeclaration,
+        //   } from 'ts-morph'
+        // Into:
+        //   @typedef {import('ts-morph').ImportDeclaration      } ImportDeclaration
+        //   @typedef {import('ts-morph').ClassDeclaration       } ClassDeclaration
+        //   @typedef {import('ts-morph').FunctionLikeDeclaration} FunctionLikeDeclaration
+        const importDeclarations = sourceFile.getImportDeclarations();
+        let importTypesToTypedefs = '';
+        for (const importDeclaration of importDeclarations) {
+            const {importClause, moduleSpecifier} = importDeclaration.compilerNode;
+            if (importClause.isTypeOnly) {
+                const {elements} = importClause.namedBindings;
+                let out = '';
+                for (const element of elements) {
+                    if (element.kind === ts.SyntaxKind.ImportSpecifier) {
+                        const moduleSpecifierName = moduleSpecifier.text;
+                        const elementName = element.name.text;
+                        out += `/** @typedef {import('${moduleSpecifierName}').${elementName}} ${elementName} */\n`;
+                    }
+                }
+                importTypesToTypedefs += out;
+            }
+        }
+        //console.log("importDeclarations", importDeclarations);
+
+        const typedefs = sourceFile.getTypeAliases()
+            .map((typeAlias) => generateTypedefDocumentation(typeAlias).trim())
+            .join("\n");
+        const interfaces = sourceFile.getInterfaces()
+            .map((interfaceNode) => generateInterfaceDocumentation(interfaceNode).trim())
+            .join("\n");
+        const directFunctions = sourceFile.getFunctions();
+        directFunctions.forEach((node) => generateFunctionDocumentation(node));
+        const varDeclarations = sourceFile.getVariableDeclarations();
+        varDeclarations.forEach((varDeclaration) => {
+            const initializer = varDeclaration.getInitializerIfKind(SyntaxKind.ArrowFunction)
+                || varDeclaration.getInitializerIfKind(SyntaxKind.FunctionExpression);
+            if (initializer) {
+                generateFunctionDocumentation(initializer, varDeclaration.getVariableStatement());
+            }
+            else {
+                generateTopLevelVariableDocumentation(varDeclaration);
+            }
+        });
+        let result = project
+            .emitToMemory()
+            ?.getFiles()
+            ?.find((file) => file.filePath.slice(0, -3) === sourceFile.getFilePath().slice(0, -3))
+            ?.text;
+        if (result) {
+            //console.log("RESULT", result);
+            if (!result.startsWith(protectCommentsHeader)) {
+                throw new Error("Internal error: generated header is missing in output.\n\n"
+                    + `Output: ${JSON.stringify(`${result.slice(protectCommentsHeader.length + 100)} ...`)}`);
+            }
+            result = result.replace(protectCommentsHeader, "");
+            result = importTypesToTypedefs + result;
+            // Restore blank lines in output
+            result = result.split("\n").map((_line) => {
+                const line = _line.trim();
+                return line.startsWith(blankLineMarker)
+                    ? line.slice(blankLineMarker.length)
+                    : _line;
+            }).join("\n").trim();
+            if (typedefs)
+                result += `\n\n${typedefs}`;
+            if (interfaces)
+                result += `\n\n${interfaces}`;
+            result = `${result.trim()}\n`;
+            return result;
+        }
+        throw new Error("Could not emit output to memory.");
+    }
+    catch (e) {
+        debug && console.error(e);
+        return src;
+    }
+    return src;
+}
+export {transpile};
+/**
+ * @typedef {JSDocableNode & TypedNode & (
+ * 	| PropertyDeclaration
+ * 	| PropertyAssignment
+ * 	| PropertySignature
+ * )} ObjectProperty
+ */
+/** @typedef {JSDocableNode & ModifierableNode & ObjectProperty & MethodDeclaration} ClassMemberNode */