vuepress-jsdoc 4.3.1 → 6.1.0

package/dist/lib/list-folder.js

@@ -1,202 +1,116 @@
-"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 };
-    }
-};
-var __values = (this && this.__values) || function(o) {
-    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
-    if (m) return m.call(o);
-    if (o && typeof o.length === "number") return {
-        next: function () {
-            if (o && i >= o.length) o = void 0;
-            return { value: o && o[i++], done: !o };
-        }
-    };
-    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
-};
-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;
-    try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
-    }
-    catch (error) { e = { error: error }; }
-    finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
-        }
-        finally { if (e) throw e.error; }
-    }
-    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];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.listFolder = void 0;
 /*
  * @vuepress
  * ---
  * headline: lib/list-folder.ts
  * ---
  */
-var promises_1 = __importDefault(require("fs/promises"));
-var micromatch_1 = __importDefault(require("micromatch"));
-var path_1 = __importDefault(require("path"));
+import mm from 'micromatch';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { SCRIPT_EXTENSIONS, VUE_EXTENSIONS } from '../constants.js';
+const SUPPORTED_EXTENSIONS = [...SCRIPT_EXTENSIONS, ...VUE_EXTENSIONS];
+/**
+ * Normalize a path to a posix path without leading `./` and trailing slash
+ * @param {string} p path
+ * @returns {string} normalized path
+ */
+export const normalizePath = (p) => path.posix.normalize(p.split(path.sep).join('/')).replace(/\/$/, '') || '.';
+/**
+ * Normalize pattern lists, which may be passed as comma separated string or array
+ * @param {string|string[]} patterns patterns
+ * @returns {string[]} list of non empty patterns
+ */
+const toPatternList = (patterns) => {
+    if (typeof patterns === 'string')
+        return patterns.split(',').filter(Boolean);
+    if (Array.isArray(patterns))
+        return patterns.filter((p) => typeof p === 'string' && p.length > 0);
+    return [];
+};
+/**
+ * Check if a file should be documented
+ * @param {string} fileName name of the file
+ * @returns {boolean}
+ */
+const isSupportedFile = (fileName) => SUPPORTED_EXTENSIONS.includes(path.extname(fileName)) && !/\.d\.[cm]?ts$/.test(fileName);
 /**
- * Recursively traverse folders and return exluded files, a file list and a file tree.
+ * Get the page name of a file. Index files are prefixed with their folder,
+ * because an `index.md` would collide with the `README.md` of the folder.
+ * @param {string} dir directory of the file
+ * @param {string} name file name without extension
+ * @returns {string} page name
+ */
+export const getPageName = (dir, name) => {
+    if (name !== 'index')
+        return name;
+    const prefix = dir
+        .split('/')
+        .filter((segment) => segment && segment !== '.' && segment !== '..')
+        .join('-');
+    return `${prefix || path.basename(path.resolve(dir))}-${name}`;
+};
+/**
+ * Recursively traverse folders and return excluded files, a file list and a file tree.
+ * Only `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts` and `.vue` files are listed.
+ * Hidden folders and `node_modules` are skipped.
  * @param {string} srcPath path to source dir
- * @param {array} exclude exluded file patter list
- * @param {array} include included file patter list
- * @param {string} mainPath path to hold source dir
- * @param {object} tree tree array
- * @returns {object} paths array, tree, excluded array
+ * @param {string[]} exclude excluded file pattern list (relative to srcPath)
+ * @param {string[]} include included file pattern list (relative to srcPath)
+ * @returns {Promise<ListFolderResult>} paths array, tree, excluded array
  */
-var listFolder = function (srcPath, exclude, include, mainPath, tree) {
-    if (tree === void 0) { tree = []; }
-    return __awaiter(void 0, void 0, void 0, function () {
-        var paths, excluded, dirs, _a, dirs_1, dirs_1_1, dirent, filePath, isDir, ext, name_1, folder, file, baseSrc, treeEntry, _b, _c, _d, _e, e_1_1;
-        var e_1, _f;
-        return __generator(this, function (_g) {
-            switch (_g.label) {
-                case 0:
-                    if (!Boolean(exclude) || !Array.isArray(exclude)) {
-                        exclude = [];
-                    }
-                    if (!Boolean(include) || !Array.isArray(include)) {
-                        include = [];
-                    }
-                    exclude = exclude.filter(Boolean);
-                    include = include.filter(Boolean);
-                    paths = [];
-                    excluded = [];
-                    if (!srcPath) return [3 /*break*/, 2];
-                    return [4 /*yield*/, promises_1.default.readdir(srcPath, {
-                            withFileTypes: true
-                        })];
-                case 1:
-                    _a = _g.sent();
-                    return [3 /*break*/, 3];
-                case 2:
-                    _a = [];
-                    _g.label = 3;
-                case 3:
-                    dirs = _a;
-                    _g.label = 4;
-                case 4:
-                    _g.trys.push([4, 12, 13, 14]);
-                    dirs_1 = __values(dirs), dirs_1_1 = dirs_1.next();
-                    _g.label = 5;
-                case 5:
-                    if (!!dirs_1_1.done) return [3 /*break*/, 11];
-                    dirent = dirs_1_1.value;
-                    filePath = path_1.default.join(srcPath, dirent.name);
-                    isDir = dirent.isDirectory();
-                    ext = path_1.default.extname(filePath);
-                    name_1 = path_1.default.basename(filePath).replace(ext, '');
-                    folder = filePath.replace(name_1, '').replace(ext, '');
-                    if (name_1 === 'index') {
-                        name_1 = '__index__';
-                    }
-                    file = __assign({ isDir: isDir, name: name_1, path: filePath }, (!isDir ? { ext: ext, folder: folder } : {}));
-                    // skip readmes as they are automatically resolved
-                    if (name_1.toLowerCase() === 'readme')
-                        return [3 /*break*/, 10];
-                    baseSrc = mainPath || srcPath;
-                    if (!(micromatch_1.default.every(path_1.default.join(srcPath.replace(baseSrc, ''), dirent.name), __spreadArray(__spreadArray([], __read(include), false), __read(exclude.map(function (e) { return '!' + e; })), false)) ||
-                        isDir)) return [3 /*break*/, 9];
-                    treeEntry = {
-                        name: name_1
-                    };
-                    if (!isDir) return [3 /*break*/, 7];
-                    treeEntry.children = [];
-                    _c = (_b = paths.push).apply;
-                    _d = [paths];
-                    _e = [[]];
-                    return [4 /*yield*/, (0, exports.listFolder)(filePath, exclude, include, baseSrc, treeEntry.children)];
-                case 6:
-                    _c.apply(_b, _d.concat([__spreadArray.apply(void 0, _e.concat([__read.apply(void 0, [(_g.sent()).paths]), false]))]));
-                    return [3 /*break*/, 8];
-                case 7:
-                    treeEntry = __assign(__assign({}, treeEntry), { path: "/".concat(name_1), fullPath: path_1.default.join(srcPath, name_1), ext: ext });
-                    _g.label = 8;
-                case 8:
-                    tree.push(treeEntry);
-                    paths.push(file);
-                    return [3 /*break*/, 10];
-                case 9:
-                    excluded.push(file);
-                    _g.label = 10;
-                case 10:
-                    dirs_1_1 = dirs_1.next();
-                    return [3 /*break*/, 5];
-                case 11: return [3 /*break*/, 14];
-                case 12:
-                    e_1_1 = _g.sent();
-                    e_1 = { error: e_1_1 };
-                    return [3 /*break*/, 14];
-                case 13:
-                    try {
-                        if (dirs_1_1 && !dirs_1_1.done && (_f = dirs_1.return)) _f.call(dirs_1);
-                    }
-                    finally { if (e_1) throw e_1.error; }
-                    return [7 /*endfinally*/];
-                case 14: return [2 /*return*/, { paths: paths, tree: tree, excluded: excluded }];
+export const listFolder = async (srcPath, exclude = [], include = []) => {
+    const excludePatterns = toPatternList(exclude);
+    const includePatterns = toPatternList(include);
+    const patterns = [...includePatterns, ...excludePatterns.map((e) => '!' + e)];
+    const paths = [];
+    const excluded = [];
+    const tree = [];
+    if (!srcPath || typeof srcPath !== 'string') {
+        return { paths, tree, excluded };
+    }
+    const root = normalizePath(srcPath);
+    const walk = async (dir, subTree) => {
+        const dirents = await fs.readdir(dir, { withFileTypes: true });
+        dirents.sort((a, b) => a.name.localeCompare(b.name));
+        const files = dirents.filter((d) => !d.isDirectory());
+        const dirs = dirents.filter((d) => d.isDirectory());
+        for (const dirent of files) {
+            if (!isSupportedFile(dirent.name))
+                continue;
+            const filePath = path.posix.join(dir, dirent.name);
+            const relativePath = path.posix.relative(root, filePath);
+            const ext = path.extname(dirent.name);
+            const name = getPageName(dir, path.basename(dirent.name, ext));
+            const folder = `${dir}/`;
+            const file = { name, ext, folder, path: filePath };
+            if (patterns.length && !mm.every(relativePath, patterns)) {
+                excluded.push(file);
+                continue;
             }
-        });
-    });
+            paths.push(file);
+            subTree.push({
+                name,
+                path: `/${name}`,
+                fullPath: path.posix.join(dir, name),
+                ext
+            });
+        }
+        for (const dirent of dirs) {
+            if (dirent.name.startsWith('.') || dirent.name === 'node_modules')
+                continue;
+            const dirPath = path.posix.join(dir, dirent.name);
+            const relativeDir = path.posix.relative(root, dirPath);
+            // a folder can be excluded as a whole, e.g. --exclude="tests" or --exclude="**/__tests__"
+            if (excludePatterns.length && mm.isMatch(relativeDir, excludePatterns))
+                continue;
+            const children = [];
+            await walk(dirPath, children);
+            // do not add empty folders to the tree
+            if (children.length > 0) {
+                subTree.push({ name: dirent.name, children });
+            }
+        }
+    };
+    await walk(root, tree);
+    return { paths, tree, excluded };
 };
-exports.listFolder = listFolder;

package/dist/lib/parser.d.ts

@@ -1,37 +1,53 @@
-import { StatisticType } from '../constants';
-import { DirectoryFile, ParseReturn } from '../interfaces';
+import { DirectoryFile, ParseReturn } from '../interfaces.js';
+export interface ParseOptions {
+    /** source folder relative to the working directory */
+    srcFolder: string;
+    /** destination folder relative to the working directory */
+    destFolder: string;
+    /** path to a jsdoc config */
+    jsDocConfigPath?: string;
+    /** additional jsdoc2markdown partials */
+    partials?: string[];
+}
 /**
- * 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
- */
-export declare const parseFile: (file: DirectoryFile, srcFolder: string, destFolder: string, configPath: string, partials: string | string[]) => Promise<ParseReturn | null>;
-/**
- * Parse a vue file
+ * Get the folder of the generated markdown file
  * @param {DirectoryFile} file
  * @param {string} srcFolder
  * @param {string} destFolder
- * @returns {object} file data
+ * @returns {string} destination folder
+ */
+export declare const getDestFolder: (file: Pick<DirectoryFile, 'folder'>, srcFolder: string, destFolder: string) => string;
+/**
+ * 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 declare const stripTypes: (code: string) => string;
+/**
+ * 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
+ */
+export declare const typescriptToJavaScript: (code: string, fileName: string) => string;
+/**
+ * Escape vue interpolations (`{{ }}`) outside of code, because VuePress compiles every page as a vue template.
+ * @param {string} markdown
+ * @returns {string} escaped markdown
+ */
+export declare const escapeVueInterpolation: (markdown: string) => string;
+/**
+ * Parse a javascript, typescript or vue file and create the markdown content
+ * @param {DirectoryFile} file
+ * @param {ParseOptions} options
+ * @returns {Promise<ParseReturn>} file data
  */
-export declare const parseVueFile: (file: DirectoryFile, srcFolder: string, destFolder: string) => Promise<ParseReturn | null>;
+export declare const parseFile: (file: DirectoryFile, options: ParseOptions) => Promise<ParseReturn>;
 /**
- * Write content on disk
- * @param {ParseReturn | null} parseData
- * @param {string} dest
- * @returns {Promise | null} null or type with some data of the saved file
+ * 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 declare const writeContentToFile: (parseData: ParseReturn | null, dest: string) => Promise<{
-    type: StatisticType;
-    success?: boolean | undefined;
-    dest?: string | undefined;
-    file?: DirectoryFile | undefined;
-    content?: string | undefined;
-    empty?: boolean | undefined;
-    excluded?: boolean | undefined;
-    relativePathSrc?: string | undefined;
-    relativePathDest?: string | undefined;
-} | null>;
+export declare const writeContentToFile: (parseData: ParseReturn) => Promise<string | null>;