vuepress-jsdoc 4.3.1 → 6.1.0

package/dist/lib/parser.js

@@ -1,265 +1,223 @@
-"use strict";
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
-    function verb(n) { return function (v) { return step([n, v]); }; }
-    function step(op) {
-        if (f) throw new TypeError("Generator is already executing.");
-        while (_) try {
-            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
-            if (y = 0, t) op = [op[0] & 2, t.value];
-            switch (op[0]) {
-                case 0: case 1: t = op; break;
-                case 4: _.label++; return { value: op[1], done: false };
-                case 5: _.label++; y = op[1]; op = [0]; continue;
-                case 7: op = _.ops.pop(); _.trys.pop(); continue;
-                default:
-                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
-                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
-                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
-                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
-                    if (t[2]) _.ops.pop();
-                    _.trys.pop(); continue;
-            }
-            op = body.call(thisArg, _);
-        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
-        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+/*
+ * @vuepress
+ * ---
+ * headline: lib/parser.ts
+ * ---
+ */
+import jsdoc2md from 'jsdoc-to-markdown';
+import fs from 'node:fs/promises';
+import nodeModule, { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { StatisticType, TYPESCRIPT_EXTENSIONS, VUE_EXTENSIONS } from '../constants.js';
+import { parseVuepressFileHeader } from './comment-parser.js';
+const require = createRequire(import.meta.url);
+const TEMPLATE_FOLDER = fileURLToPath(new URL('../../template/', import.meta.url));
+/**
+ * Get the folder of the generated markdown file
+ * @param {DirectoryFile} file
+ * @param {string} srcFolder
+ * @param {string} destFolder
+ * @returns {string} destination folder
+ */
+export const getDestFolder = (file, srcFolder, destFolder) => path.join(destFolder, path.relative(path.resolve(srcFolder), path.resolve(file.folder)));
+/**
+ * Get a readable error message
+ * @param {unknown} error
+ * @returns {string}
+ */
+const getErrorMessage = (error) => (error instanceof Error ? error.message : String(error)).split('\n').filter(Boolean).slice(0, 3).join('\n');
+/**
+ * Remove TypeScript types from source code, so jsdoc is able to parse it.
+ * Types are replaced with whitespace, so all comments and line numbers stay intact.
+ * @param {string} code TypeScript code
+ * @returns {string} JavaScript code
+ */
+export const stripTypes = (code) => {
+    const { stripTypeScriptTypes } = nodeModule;
+    if (typeof stripTypeScriptTypes !== 'function') {
+        throw new Error('TypeScript files need Node.js >= 22.13 or a jsdoc config (--jsDocConfigPath)');
     }
-};
-var __read = (this && this.__read) || function (o, n) {
-    var m = typeof Symbol === "function" && o[Symbol.iterator];
-    if (!m) return o;
-    var i = m.call(o), r, ar = [], e;
+    // stripTypeScriptTypes is still experimental and would print a warning
+    const emitWarning = process.emitWarning;
+    process.emitWarning = () => { };
     try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+        return stripTypeScriptTypes(code, { mode: 'strip' });
+    }
+    catch (e) {
+        throw new Error(getErrorMessage(e), { cause: e });
     }
-    catch (error) { e = { error: error }; }
     finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
-        }
-        finally { if (e) throw e.error; }
+        process.emitWarning = emitWarning;
     }
-    return ar;
 };
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
+/**
+ * Load the TypeScript compiler API. The project of the user is preferred over the bundled one.
+ * `typescript` >= 7 has no JavaScript API anymore, so `@typescript/typescript6` is tried as well.
+ * The result is cached, because it is used for every TypeScript file.
+ * @returns {TypeScriptApi | null} TypeScript module or null if it is not installed
+ */
+let typescript;
+const loadTypeScript = () => {
+    if (typescript !== undefined)
+        return typescript;
+    const requires = [createRequire(path.join(process.cwd(), 'package.json')), require];
+    for (const req of requires) {
+        for (const name of ['typescript', '@typescript/typescript6']) {
+            try {
+                const ts = req(name);
+                if (typeof ts?.transpileModule === 'function')
+                    return (typescript = ts);
+            }
+            catch {
+                // try the next one
+            }
         }
     }
-    return to.concat(ar || Array.prototype.slice.call(from));
+    return (typescript = null);
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeContentToFile = exports.parseVueFile = exports.parseFile = void 0;
-/*
- * @vuepress
- * ---
- * headline: lib/parser.ts
- * ---
+/**
+ * Transpile TypeScript with the TypeScript compiler. Comments and JSX are preserved.
+ * This supports syntax that type stripping can not handle: `enum`, `namespace`, parameter properties and JSX.
+ * @param {string} code TypeScript code
+ * @param {string} fileName used to detect `.tsx`
+ * @returns {string | null} JavaScript code or null if TypeScript is not installed
  */
-var promises_1 = __importDefault(require("fs/promises"));
-var jsdoc_to_markdown_1 = __importDefault(require("jsdoc-to-markdown"));
-var mkdirp_1 = __importDefault(require("mkdirp"));
-var path_1 = require("path");
-var compileTemplates_1 = __importDefault(require("vue-docgen-cli/lib/compileTemplates"));
-var docgen_1 = require("vue-docgen-cli/lib/docgen");
-var constants_1 = require("../constants");
-var comment_parser_1 = require("./comment-parser");
+const transpileTypes = (code, fileName) => {
+    const ts = loadTypeScript();
+    if (!ts)
+        return null;
+    return ts.transpileModule(code, {
+        fileName,
+        reportDiagnostics: false,
+        compilerOptions: {
+            target: ts.ScriptTarget.ESNext,
+            module: ts.ModuleKind.ESNext,
+            jsx: ts.JsxEmit.Preserve,
+            removeComments: false,
+            verbatimModuleSyntax: false,
+            isolatedModules: true
+        }
+    }).outputText;
+};
 /**
- * Parse a typescript or javascript file
- * @param file {DirectoryFile}
- * @param srcFolder {string}
- * @param destFolder {string}
- * @param configPath {string}
- * @param partials {string | string[]}
- * @returns {object} file data
+ * Convert TypeScript to JavaScript. Type stripping of Node.js is used first, because it keeps all line numbers.
+ * If the file contains syntax which needs a transformation, the TypeScript compiler is used.
+ * @param {string} code TypeScript code
+ * @param {string} fileName
+ * @returns {string} JavaScript code
  */
-var parseFile = function (file, srcFolder, destFolder, configPath, partials) { return __awaiter(void 0, void 0, void 0, function () {
-    var root, relativePathDest, folderInDest, folderInSrc, success, empty, excluded, fileContent, content, fileName, _a, e_1;
-    return __generator(this, function (_b) {
-        switch (_b.label) {
-            case 0:
-                if (!file.folder)
-                    return [2 /*return*/, null];
-                root = process.cwd();
-                relativePathDest = (0, path_1.join)(destFolder, file.folder.replace(srcFolder, ''));
-                folderInDest = (0, path_1.join)(root, relativePathDest);
-                folderInSrc = (0, path_1.join)(root, file.folder);
-                success = true;
-                empty = false;
-                excluded = false;
-                fileContent = '';
-                _b.label = 1;
-            case 1:
-                _b.trys.push([1, 4, , 5]);
-                content = '';
-                fileName = file.name;
-                if (fileName === '__index__') {
-                    fileName = 'index';
-                }
-                return [4 /*yield*/, jsdoc_to_markdown_1.default.render({
-                        'no-cache': configPath ? true : false,
-                        files: [(0, path_1.join)(process.cwd(), file.folder, fileName + file.ext)],
-                        configure: configPath,
-                        partial: __spreadArray([
-                            (0, path_1.resolve)(__filename, '../../../template/header.hbs'),
-                            (0, path_1.resolve)(__filename, '../../../template/main.hbs')
-                        ], __read(partials), false)
-                    })];
-            case 2:
-                content = _b.sent();
-                _a = comment_parser_1.parseVuepressFileHeader;
-                return [4 /*yield*/, promises_1.default.readFile("".concat((0, path_1.join)(folderInSrc, fileName + file.ext)), 'utf-8')];
-            case 3:
-                fileContent = _a.apply(void 0, [_b.sent(), file]);
-                if (content) {
-                    fileContent += content;
-                }
-                else {
-                    empty = true;
-                }
-                return [3 /*break*/, 5];
-            case 4:
-                e_1 = _b.sent();
-                success = false;
-                excluded = true;
-                return [3 /*break*/, 5];
-            case 5: return [2 /*return*/, {
-                    success: success,
-                    file: file,
-                    empty: empty,
-                    excluded: excluded,
-                    relativePathDest: relativePathDest,
-                    relativePathSrc: file.folder,
-                    dest: folderInDest,
-                    content: fileContent
-                }];
+export const typescriptToJavaScript = (code, fileName) => {
+    let reason = 'JSX can not be stripped';
+    if (!fileName.endsWith('.tsx')) {
+        try {
+            return stripTypes(code);
         }
-    });
-}); };
-exports.parseFile = parseFile;
+        catch (e) {
+            reason = getErrorMessage(e);
+        }
+    }
+    const transpiled = transpileTypes(code, fileName);
+    if (transpiled !== null)
+        return transpiled;
+    throw new Error(`${reason}\nInstall typescript or use a jsdoc config with babel (--jsDocConfigPath) for this file.`);
+};
+/**
+ * Escape vue interpolations (`{{ }}`) outside of code, because VuePress compiles every page as a vue template.
+ * @param {string} markdown
+ * @returns {string} escaped markdown
+ */
+export const escapeVueInterpolation = (markdown) => markdown
+    // split by fenced code blocks, <code> and <pre> tags and inline code
+    .split(/(```[\s\S]*?```|<pre[\s\S]*?<\/pre>|<code>[\s\S]*?<\/code>|`[^`\n]*`)/)
+    // odd parts are code, which is kept. Inside <code> tags vue still interpolates.
+    .map((part, i) => i % 2 === 1 && !part.startsWith('<code>')
+    ? part
+    : part.replace(/\{\{/g, '&#123;&#123;').replace(/\}\}/g, '&#125;&#125;'))
+    .join('');
 /**
- * Parse a vue file
+ * Render a javascript or typescript file with jsdoc-to-markdown
  * @param {DirectoryFile} file
- * @param {string} srcFolder
- * @param {string} destFolder
- * @returns {object} file data
+ * @param {ParseOptions} options
+ * @param {string} source content of the file
+ * @returns {Promise<string>} markdown
  */
-var parseVueFile = function (file, srcFolder, destFolder) { return __awaiter(void 0, void 0, void 0, function () {
-    var root, relativePathDest, folderInDest, folderInSrc, config, success, empty, fileContent, fileName, data, _a, e_2;
-    return __generator(this, function (_b) {
-        switch (_b.label) {
-            case 0:
-                if (!file.folder)
-                    return [2 /*return*/, null];
-                root = process.cwd();
-                relativePathDest = (0, path_1.join)(destFolder, file.folder.replace(srcFolder, ''));
-                folderInDest = (0, path_1.join)(root, relativePathDest);
-                folderInSrc = (0, path_1.join)(root, file.folder);
-                config = __assign(__assign({}, (0, docgen_1.extractConfig)((0, path_1.join)(root, file.folder))), { components: file.name + file.ext });
-                success = true;
-                empty = false;
-                fileContent = '';
-                _b.label = 1;
-            case 1:
-                _b.trys.push([1, 4, , 5]);
-                fileName = file.name;
-                if (fileName === '__index__') {
-                    fileName = 'index';
-                }
-                return [4 /*yield*/, (0, compileTemplates_1.default)((0, path_1.join)(config.componentsRoot, fileName + file.ext), config, fileName + file.ext)];
-            case 2:
-                data = _b.sent();
-                _a = comment_parser_1.parseVuepressFileHeader;
-                return [4 /*yield*/, promises_1.default.readFile("".concat((0, path_1.join)(folderInSrc, fileName + file.ext)), 'utf-8')];
-            case 3:
-                fileContent = _a.apply(void 0, [_b.sent(), file]);
-                if (data.content) {
-                    fileContent += data.content;
-                }
-                else {
-                    empty = true;
-                }
-                return [3 /*break*/, 5];
-            case 4:
-                e_2 = _b.sent();
-                console.log(e_2);
-                success = false;
-                return [3 /*break*/, 5];
-            case 5: return [2 /*return*/, {
-                    success: success,
-                    file: file,
-                    empty: empty,
-                    relativePathDest: relativePathDest,
-                    relativePathSrc: file.folder,
-                    dest: folderInDest,
-                    content: fileContent
-                }];
-        }
-    });
-}); };
-exports.parseVueFile = parseVueFile;
+const renderScript = async (file, options, source) => {
+    const absolutePath = path.resolve(file.path);
+    const jsdocOptions = {
+        partial: [
+            path.join(TEMPLATE_FOLDER, 'header.hbs'),
+            path.join(TEMPLATE_FOLDER, 'main.hbs'),
+            ...(options.partials || [])
+        ]
+    };
+    if (options.jsDocConfigPath) {
+        // the user config takes care of the file (e.g. typescript via jsdoc-babel)
+        jsdocOptions.files = [absolutePath];
+        jsdocOptions.configure = path.resolve(options.jsDocConfigPath);
+        jsdocOptions['no-cache'] = true;
+    }
+    else if (TYPESCRIPT_EXTENSIONS.includes(file.ext)) {
+        jsdocOptions.source = typescriptToJavaScript(source, file.path);
+    }
+    else {
+        jsdocOptions.files = [absolutePath];
+    }
+    return jsdoc2md.render(jsdocOptions);
+};
 /**
- * Write content on disk
- * @param {ParseReturn | null} parseData
- * @param {string} dest
- * @returns {Promise | null} null or type with some data of the saved file
+ * Render a vue file with vue-docgen-cli
+ * @param {DirectoryFile} file
+ * @returns {Promise<string>} markdown
  */
-var writeContentToFile = function (parseData, dest) { return __awaiter(void 0, void 0, void 0, function () {
-    var root, type, path, _a;
-    return __generator(this, function (_b) {
-        switch (_b.label) {
-            case 0:
-                root = process.cwd();
-                dest = (0, path_1.join)(root, dest);
-                type = constants_1.StatisticType.ERROR;
-                if (parseData === null || parseData === void 0 ? void 0 : parseData.excluded) {
-                    type = constants_1.StatisticType.EXCLUDE;
-                }
-                _b.label = 1;
-            case 1:
-                _b.trys.push([1, 5, , 6]);
-                if (!(parseData === null || parseData === void 0 ? void 0 : parseData.content)) return [3 /*break*/, 4];
-                path = "".concat((0, path_1.join)(dest, parseData.file.name), ".md");
-                return [4 /*yield*/, (0, mkdirp_1.default)(dest)];
-            case 2:
-                _b.sent();
-                return [4 /*yield*/, promises_1.default.writeFile(path, parseData.content, 'utf-8')];
-            case 3:
-                _b.sent();
-                type = (parseData === null || parseData === void 0 ? void 0 : parseData.empty) ? constants_1.StatisticType.EMPTY : constants_1.StatisticType.INCLUDE;
-                _b.label = 4;
-            case 4: return [2 /*return*/, __assign(__assign({}, parseData), { type: type })];
-            case 5:
-                _a = _b.sent();
-                return [3 /*break*/, 6];
-            case 6: return [2 /*return*/, null];
-        }
-    });
-}); };
-exports.writeContentToFile = writeContentToFile;
+const renderVue = async (file) => {
+    const { default: compileTemplates } = require('vue-docgen-cli/lib/compileTemplates');
+    const { extractConfig } = require('vue-docgen-cli/lib/docgen');
+    const fileName = path.basename(file.path);
+    const config = await extractConfig(path.resolve(file.folder));
+    const { content } = await compileTemplates('add', path.join(config.componentsRoot, fileName), config, fileName);
+    return content;
+};
+/**
+ * Parse a javascript, typescript or vue file and create the markdown content
+ * @param {DirectoryFile} file
+ * @param {ParseOptions} options
+ * @returns {Promise<ParseReturn>} file data
+ */
+export const parseFile = async (file, options) => {
+    const dest = getDestFolder(file, options.srcFolder, options.destFolder);
+    const empty = { type: StatisticType.EMPTY, file, dest, content: '' };
+    try {
+        const source = await fs.readFile(file.path, 'utf-8');
+        const isVue = VUE_EXTENSIONS.includes(file.ext);
+        const content = isVue ? await renderVue(file) : await renderScript(file, options, source);
+        if (!content?.trim())
+            return empty;
+        return {
+            type: StatisticType.INCLUDE,
+            file,
+            dest,
+            content: parseVuepressFileHeader(source, file) + escapeVueInterpolation(content.trim()) + '\n'
+        };
+    }
+    catch (e) {
+        const error = getErrorMessage(e);
+        // the file is excluded by the jsdoc config (source.excludePattern)
+        if (/no input files to process/i.test(error))
+            return empty;
+        return { ...empty, type: StatisticType.ERROR, error };
+    }
+};
+/**
+ * Write the parsed content to disk. Files without content are skipped.
+ * @param {ParseReturn} parseData
+ * @returns {Promise<string | null>} path of the written file or null
+ */
+export const writeContentToFile = async (parseData) => {
+    if (parseData.type !== StatisticType.INCLUDE || !parseData.content)
+        return null;
+    const filePath = path.join(parseData.dest, `${parseData.file.name}.md`);
+    await fs.mkdir(parseData.dest, { recursive: true });
+    await fs.writeFile(filePath, parseData.content, 'utf-8');
+    return filePath;
+};

package/dist/lib/vue-sidebar.d.ts

@@ -1,23 +1,66 @@
-/**
- * Runs through the given tree structure and creates a vuepress config
- * @param {object} data Informations to build config
- * @param {array} data.fileTree tree strcture
- * @param {string} data.codeFolder ./code/ folder
- * @param {string} data.srcFolder ./src/ folder
- * @param {string} data.docsFolder ./documentation/ folder
- * @param {string} data.title title string
- * @returns {object} returns the vuepress menu strcture
- */
-export declare const generateVueSidebar: ({ fileTree, codeFolder, srcFolder, docsFolder, title }: {
-    fileTree: any;
+import { FileTree } from '../interfaces.js';
+export interface SidebarGroup {
+    text: string;
+    collapsible: boolean;
+    children: SidebarItem[];
+}
+export type SidebarItem = string | {
+    text: string;
+    link: string;
+} | SidebarGroup;
+export interface SidebarOptions {
+    /** tree structure, created by `listFolder` */
+    fileTree: FileTree[];
+    /** name of the folder inside the vuepress folder, e.g. `code` */
     codeFolder: string;
+    /** source folder, e.g. `src` */
     srcFolder: string;
+    /** folder of the generated markdown files, e.g. `documentation/code` */
     docsFolder: string;
+    /** title of the first sidebar group */
     title: string;
-}) => {
-    [x: string]: {
-        title: string;
-        collapsable: boolean;
-        children: string[][];
-    }[];
+    /** sidebar format of the generated `config.js` */
+    format?: SiteFormat;
+    /** text of the first entry, which links to the readme */
+    readmeTitle?: string;
+    /** make the top level groups collapsible. Nested folders are always collapsible. */
+    collapsible?: boolean;
+}
+export type SiteFormat = 'vuepress' | 'vitepress';
+/**
+ * Get the route of the generated folder, e.g. `/code/`
+ * @param {string} codeFolder
+ * @returns {string}
+ */
+export declare const getSidebarBase: (codeFolder: string) => string;
+export interface VitepressSidebarItem {
+    text: string;
+    link?: string;
+    collapsed?: boolean;
+    items?: VitepressSidebarItem[];
+}
+/**
+ * Runs through the given tree structure and creates a vuepress 2 sidebar config.
+ * Only pages that were generated are linked. Folders become nested sidebar groups.
+ * @param {SidebarOptions} data Information to build config
+ * @returns {object} returns the vuepress sidebar structure
+ */
+export declare const generateVueSidebar: ({ fileTree, codeFolder, srcFolder, docsFolder, title, readmeTitle, collapsible }: SidebarOptions) => {
+    [x: string]: SidebarGroup[];
 };
+/**
+ * Runs through the given tree structure and creates a vitepress sidebar config.
+ * Vitepress needs the text of every link, so it is read from the generated page.
+ * @param {SidebarOptions} data Information to build config
+ * @returns {object} returns the vitepress sidebar structure
+ */
+export declare const generateVitepressSidebar: (data: SidebarOptions) => {
+    [x: string]: VitepressSidebarItem[];
+};
+/**
+ * Create the content of the `config.js`, which is placed into the generated folder.
+ * It exports the file tree and a `sidebarTree(title)` function, which returns the vuepress or vitepress sidebar.
+ * @param {SidebarOptions} options
+ * @returns {string} javascript code (ES module)
+ */
+export declare const createSidebarConfig: (options: SidebarOptions) => string;