Add JSDoc eslint rule

.eslintrc.json

@@ -87,7 +87,7 @@
         "local/simple-indent": "error",
         "local/debug-assert": "error",
         "local/no-keywords": "error",
-        "local/one-namespace-per-file": "error",
+        "local/jsdoc-format": "error",
 
         // eslint-plugin-import
         "import/no-extraneous-dependencies": ["error", { "optionalDependencies": false }],

.git-blame-ignore-revs

@@ -0,0 +1,8 @@
+# Generated module conversion step - inlineImports
+15139837058ce2af370bb4e8f4b18ccc75498881
+# Generated module conversion step - stripNamespaces
+459fb4c4db144fe25db9f99a85679da5c65d3fc9
+# Generated module conversion step - explicitify
+e3488bb30d460cedc2739ed0cc2b9fb4bb186825
+# Generated module conversion step - unindent
+85bdc31dba8f2b5a457f3cc87daf9d266b2d6481

.vscode/settings.template.json

@@ -6,4 +6,10 @@
 
     // To use the locally built compiler, after 'npm run build':
     // "typescript.tsdk": "built/local"
+
+    // To ignore commits listed in .git-blame-ignore-revs in GitLens:
+    // "gitlens.advanced.blame.customArguments": [
+    //     "--ignore-revs-file",
+    //     ".git-blame-ignore-revs"
+    // ]
 }

scripts/eslint/rules/jsdoc-format.cjs

@@ -0,0 +1,110 @@
+const { TSESTree } = require("@typescript-eslint/utils");
+const { createRule } = require("./utils.cjs");
+
+module.exports = createRule({
+    name: "jsdoc-format",
+    meta: {
+        docs: {
+            description: ``,
+            recommended: "error",
+        },
+        messages: {
+            internalCommentInNonJSDocError: `@internal should not appear in non-JSDoc comment for declaration.`,
+            internalCommentNotLastError: `@internal should only appear in final JSDoc comment for declaration.`,
+            multipleJSDocError: `Declaration has multiple JSDoc comments.`,
+            internalCommentOnParameterProperty: `@internal cannot appear on a JSDoc comment; use a declared property and an assignment in the constructor instead.`,
+        },
+        schema: [],
+        type: "problem",
+    },
+    defaultOptions: [],
+
+    create(context) {
+        const sourceCode = context.getSourceCode();
+        const atInternal = "@internal";
+        const jsdocStart = "/**";
+
+        /** @type {(c: TSESTree.Comment, indexInComment: number) => TSESTree.SourceLocation} */
+        const getAtInternalLoc = (c, indexInComment) => {
+            const line = c.loc.start.line;
+            return {
+                start: {
+                    line,
+                    column: c.loc.start.column + indexInComment,
+                },
+                end: {
+                    line,
+                    column: c.loc.start.column + indexInComment + atInternal.length,
+                },
+            };
+        };
+
+        /** @type {(c: TSESTree.Comment) => TSESTree.SourceLocation} */
+        const getJSDocStartLoc = (c) => {
+            return {
+                start: c.loc.start,
+                end: {
+                    line: c.loc.start.line,
+                    column: c.loc.start.column + jsdocStart.length,
+                },
+            };
+        };
+
+        /** @type {(node: TSESTree.Node) => void} */
+        const checkJSDocFormat = (node) => {
+            const blockComments = sourceCode.getCommentsBefore(node).filter(c => c.type === "Block");
+            if (blockComments.length === 0) {
+                return;
+            }
+
+            const last = blockComments.length - 1;
+            let seenJSDoc = false;
+            for (let i = 0; i < blockComments.length; i++) {
+                const c = blockComments[i];
+                const rawComment = sourceCode.getText(c);
+
+                const isJSDoc = rawComment.startsWith(jsdocStart);
+                if (isJSDoc && seenJSDoc) {
+                    context.report({ messageId: "multipleJSDocError", node: c, loc: getJSDocStartLoc(c) });
+                }
+                seenJSDoc = seenJSDoc || isJSDoc;
+
+                const indexInComment = rawComment.indexOf(atInternal);
+                if (indexInComment === -1) {
+                    continue;
+                }
+
+                if (!isJSDoc) {
+                    context.report({ messageId: "internalCommentInNonJSDocError", node: c, loc: getAtInternalLoc(c, indexInComment) });
+                }
+                else if (i !== last) {
+                    context.report({ messageId: "internalCommentNotLastError", node: c, loc: getAtInternalLoc(c, indexInComment) });
+                }
+                else if (node.type === "TSParameterProperty") {
+                    context.report({ messageId: "internalCommentOnParameterProperty", node: c, loc: getAtInternalLoc(c, indexInComment) });
+                }
+            }
+        };
+
+        return {
+            ClassDeclaration: checkJSDocFormat,
+            FunctionDeclaration: checkJSDocFormat,
+            TSEnumDeclaration: checkJSDocFormat,
+            TSModuleDeclaration: checkJSDocFormat,
+            VariableDeclaration: checkJSDocFormat,
+            TSInterfaceDeclaration: checkJSDocFormat,
+            TSTypeAliasDeclaration: checkJSDocFormat,
+            TSCallSignatureDeclaration: checkJSDocFormat,
+            ExportAllDeclaration: checkJSDocFormat,
+            ExportNamedDeclaration: checkJSDocFormat,
+            TSImportEqualsDeclaration: checkJSDocFormat,
+            TSNamespaceExportDeclaration: checkJSDocFormat,
+            TSConstructSignatureDeclaration: checkJSDocFormat,
+            ExportDefaultDeclaration: checkJSDocFormat,
+            TSPropertySignature: checkJSDocFormat,
+            TSIndexSignature: checkJSDocFormat,
+            TSMethodSignature: checkJSDocFormat,
+            TSParameterProperty: checkJSDocFormat,
+        };
+    },
+});

scripts/processDiagnosticMessages.mjs

@@ -44,10 +44,7 @@ function main() {
         }
     }
 
-    const outputFilesDir = path.dirname(inputFilePath);
-    const thisFilePathRel = path.relative(process.cwd(), outputFilesDir);
-
-    const infoFileOutput = buildInfoFileOutput(diagnosticMessages, `./${path.basename(inputFilePath)}`, thisFilePathRel);
+    const infoFileOutput = buildInfoFileOutput(diagnosticMessages, inputFilePath);
     checkForUniqueCodes(diagnosticMessages);
     writeFile("diagnosticInformationMap.generated.ts", infoFileOutput);
 
@@ -72,31 +69,34 @@ function checkForUniqueCodes(diagnosticTable) {
 /**
  * @param {InputDiagnosticMessageTable} messageTable
  * @param {string} inputFilePathRel
- * @param {string} thisFilePathRel
  * @returns {string}
  */
-function buildInfoFileOutput(messageTable, inputFilePathRel, thisFilePathRel) {
-    let result =
-        "// <auto-generated />\r\n" +
-        "// generated from '" + inputFilePathRel + "' in '" + thisFilePathRel.replace(/\\/g, "/") + "'\r\n" +
-        "/* @internal */\r\n" +
-        "namespace ts {\r\n" +
-        "    function diag(code: number, category: DiagnosticCategory, key: string, message: string, reportsUnnecessary?: {}, elidedInCompatabilityPyramid?: boolean, reportsDeprecated?: {}): DiagnosticMessage {\r\n" +
-        "        return { code, category, key, message, reportsUnnecessary, elidedInCompatabilityPyramid, reportsDeprecated };\r\n" +
-        "    }\r\n" +
-        "    export const Diagnostics = {\r\n";
+function buildInfoFileOutput(messageTable, inputFilePathRel) {
+    const result = [
+        "// <auto-generated />",
+        `// generated from '${inputFilePathRel}'`,
+        "",
+        "import { DiagnosticCategory, DiagnosticMessage } from \"./types\";",
+        "",
+        "function diag(code: number, category: DiagnosticCategory, key: string, message: string, reportsUnnecessary?: {}, elidedInCompatabilityPyramid?: boolean, reportsDeprecated?: {}): DiagnosticMessage {",
+        "    return { code, category, key, message, reportsUnnecessary, elidedInCompatabilityPyramid, reportsDeprecated };",
+        "}",
+        "",
+        "/** @internal */",
+        "export const Diagnostics = {",
+    ];
     messageTable.forEach(({ code, category, reportsUnnecessary, elidedInCompatabilityPyramid, reportsDeprecated }, name) => {
         const propName = convertPropertyName(name);
         const argReportsUnnecessary = reportsUnnecessary ? `, /*reportsUnnecessary*/ ${reportsUnnecessary}` : "";
         const argElidedInCompatabilityPyramid = elidedInCompatabilityPyramid ? `${!reportsUnnecessary ? ", /*reportsUnnecessary*/ undefined" : ""}, /*elidedInCompatabilityPyramid*/ ${elidedInCompatabilityPyramid}` : "";
         const argReportsDeprecated = reportsDeprecated ? `${!argElidedInCompatabilityPyramid ? ", /*reportsUnnecessary*/ undefined, /*elidedInCompatabilityPyramid*/ undefined" : ""}, /*reportsDeprecated*/ ${reportsDeprecated}` : "";
 
-        result += `        ${propName}: diag(${code}, DiagnosticCategory.${category}, "${createKey(propName, code)}", ${JSON.stringify(name)}${argReportsUnnecessary}${argElidedInCompatabilityPyramid}${argReportsDeprecated}),\r\n`;
+        result.push(`    ${propName}: diag(${code}, DiagnosticCategory.${category}, "${createKey(propName, code)}", ${JSON.stringify(name)}${argReportsUnnecessary}${argElidedInCompatabilityPyramid}${argReportsDeprecated}),`);
     });
 
-    result += "    };\r\n}";
+    result.push("};");
 
-    return result;
+    return result.join("\r\n");
 }
 
 /**

src/compiler/_namespaces/ts.moduleSpecifiers.ts

@@ -0,0 +1,3 @@
+/* Generated file to emulate the ts.moduleSpecifiers namespace. */
+
+export * from "../moduleSpecifiers";

src/compiler/_namespaces/ts.performance.ts

@@ -0,0 +1,3 @@
+/* Generated file to emulate the ts.performance namespace. */
+
+export * from "../performance";

src/compiler/_namespaces/ts.ts

@@ -0,0 +1,74 @@
+/* Generated file to emulate the ts namespace. */
+
+export * from "../corePublic";
+export * from "../core";
+export * from "../debug";
+export * from "../semver";
+export * from "../performanceCore";
+export * from "../perfLogger";
+export * from "../tracing";
+export * from "../types";
+export * from "../sys";
+export * from "../path";
+export * from "../diagnosticInformationMap.generated";
+export * from "../scanner";
+export * from "../utilitiesPublic";
+export * from "../utilities";
+export * from "../factory/baseNodeFactory";
+export * from "../factory/parenthesizerRules";
+export * from "../factory/nodeConverters";
+export * from "../factory/nodeFactory";
+export * from "../factory/emitNode";
+export * from "../factory/emitHelpers";
+export * from "../factory/nodeTests";
+export * from "../factory/utilities";
+export * from "../factory/utilitiesPublic";
+export * from "../parser";
+export * from "../commandLineParser";
+export * from "../moduleNameResolver";
+export * from "../binder";
+export * from "../symbolWalker";
+export * from "../checker";
+export * from "../visitorPublic";
+export * from "../sourcemap";
+export * from "../transformers/utilities";
+export * from "../transformers/destructuring";
+export * from "../transformers/taggedTemplate";
+export * from "../transformers/ts";
+export * from "../transformers/classFields";
+export * from "../transformers/typeSerializer";
+export * from "../transformers/legacyDecorators";
+export * from "../transformers/es2017";
+export * from "../transformers/es2018";
+export * from "../transformers/es2019";
+export * from "../transformers/es2020";
+export * from "../transformers/es2021";
+export * from "../transformers/esnext";
+export * from "../transformers/jsx";
+export * from "../transformers/es2016";
+export * from "../transformers/es2015";
+export * from "../transformers/es5";
+export * from "../transformers/generators";
+export * from "../transformers/module/module";
+export * from "../transformers/module/system";
+export * from "../transformers/module/esnextAnd2015";
+export * from "../transformers/module/node";
+export * from "../transformers/declarations/diagnostics";
+export * from "../transformers/declarations";
+export * from "../transformer";
+export * from "../emitter";
+export * from "../watchUtilities";
+export * from "../program";
+export * from "../builderStatePublic";
+export * from "../builderState";
+export * from "../builder";
+export * from "../builderPublic";
+export * from "../resolutionCache";
+export * from "../watch";
+export * from "../watchPublic";
+export * from "../tsbuild";
+export * from "../tsbuildPublic";
+import * as moduleSpecifiers from "./ts.moduleSpecifiers";
+export { moduleSpecifiers };
+import * as performance from "./ts.performance";
+export { performance };