vuepress-jsdoc 5.0.0 → 6.1.0

package/dist/lib/comment-parser.js

@@ -1,74 +1,68 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseVuepressFileHeader = exports.parseComment = void 0;
 /*
  * @vuepress
  * ---
  * headline: lib/comment-parser.ts
  * ---
  */
-const front_matter_1 = __importDefault(require("front-matter"));
+import { createRequire } from 'node:module';
+// front-matter is a commonjs module with wrong types for es modules
+const fm = createRequire(import.meta.url)('front-matter');
 /**
- * Search in file for @vuepress comment
+ * Search in file for a `@vuepress` comment block and parse its frontmatter
  * @param {string} fileContent content of given file
  * @returns {object} object of found frontmatter data
  */
-const parseComment = (fileContent) => {
+export const parseComment = (fileContent) => {
+    const empty = { frontmatter: null, attributes: null };
+    if (typeof fileContent !== 'string')
+        return empty;
     try {
-        const allCommentBlocks = fileContent.match(/\/\*[\s\S]*?\*\/|([^:]|^)\/\/.*$/g);
-        const vuepressBlock = allCommentBlocks === null || allCommentBlocks === void 0 ? void 0 : allCommentBlocks.filter((block) => {
-            return block.split('\n').filter(line => line.indexOf('@vuepress') >= 0).length;
-        })[0];
-        if (!vuepressBlock) {
-            return {
-                frontmatter: null,
-                attributes: null
-            };
-        }
-        return (0, front_matter_1.default)(vuepressBlock
-            .replace(/\n /g, '\n')
-            .replace('/*', '')
-            .replace('*/', '')
-            .replace(/@vuepress/g, '')
-            .replace(/\*\s?/g, '')
-            .trim());
+        const vuepressBlock = fileContent.match(/\/\*[\s\S]*?\*\//g)?.find((block) => /^[\s/*]*@vuepress\b/m.test(block));
+        if (!vuepressBlock)
+            return empty;
+        const body = vuepressBlock
+            .replace(/^\/\*+/, '')
+            .replace(/\*+\/$/, '')
+            .split('\n')
+            // remove the leading "*" of every comment line
+            .map((line) => line.replace(/^\s*\*\s?/, ''))
+            .filter((line) => !/^\s*@vuepress\s*$/.test(line))
+            .join('\n')
+            .trim();
+        const { frontmatter, attributes } = fm(body);
+        return { frontmatter: frontmatter || null, attributes: frontmatter ? attributes : null };
     }
-    catch (e) {
-        return {
-            frontmatter: null,
-            attributes: null
-        };
+    catch {
+        return empty;
     }
 };
-exports.parseComment = parseComment;
 /**
- * Helper function to get header as structured markdown
+ * Quote a string for the use inside yaml frontmatter
+ * @param {string} value
+ * @returns {string} quoted string
+ */
+const yamlString = (value) => JSON.stringify(value);
+/**
+ * Helper function to get the header of a page as structured markdown.
+ * It contains the frontmatter and a headline (`# headline`).
+ * The headline is omitted for vue files, because vue-docgen-cli renders its own.
  * @param {string} content file content
- * @param {object} file file object
+ * @param {DirectoryFile} file file object
  * @returns {string} markdown header
  */
-const parseVuepressFileHeader = (content, file) => {
-    const { frontmatter, attributes } = (0, exports.parseComment)(content);
-    let fileContent = '---\n';
-    fileContent += !(attributes === null || attributes === void 0 ? void 0 : attributes.title) ? `title: ${file.name}` : '';
+export const parseVuepressFileHeader = (content, file) => {
+    const { frontmatter, attributes } = parseComment(content);
+    const lines = [];
+    if (!attributes?.title) {
+        lines.push(`title: ${yamlString(file.name)}`);
+    }
     if (frontmatter) {
-        fileContent += !(attributes === null || attributes === void 0 ? void 0 : attributes.title) ? '\n' : '';
-        fileContent += `${frontmatter}`;
+        lines.push(frontmatter);
     }
-    fileContent += '\n---\n';
-    if ((attributes === null || attributes === void 0 ? void 0 : attributes.title) || file.ext !== '.vue') {
-        let headline = file.name;
-        if (attributes === null || attributes === void 0 ? void 0 : attributes.headline) {
-            headline = attributes.headline;
-        }
-        else if (attributes === null || attributes === void 0 ? void 0 : attributes.title) {
-            headline = attributes.title;
-        }
-        fileContent += `\n# ${headline}\n\n`;
+    let header = `---\n${lines.join('\n')}\n---\n`;
+    if (attributes?.title || file.ext !== '.vue') {
+        const headline = attributes?.headline || attributes?.title || file.name;
+        header += `\n# ${headline}\n\n`;
     }
-    return fileContent;
+    return header;
 };
-exports.parseVuepressFileHeader = parseVuepressFileHeader;

package/dist/lib/config.d.ts

@@ -0,0 +1,21 @@
+import { UserConfig } from '../interfaces.js';
+/**
+ * Helper for typed config files
+ * @example
+ * // vuepress-jsdoc.config.js
+ * import { defineConfig } from 'vuepress-jsdoc';
+ *
+ * export default defineConfig({ source: './lib', exclude: ['**\/*.test.js'] });
+ * @param {UserConfig} config
+ * @returns {UserConfig} the same config
+ */
+export declare const defineConfig: (config: UserConfig) => UserConfig;
+/**
+ * Load a config file. Without a path, the working directory is searched for a `vuepress-jsdoc.config.*` file.
+ * @param {string} [configPath] path to a config file
+ * @returns {Promise<{ path: string, config: UserConfig } | null>} config or null if there is no config file
+ */
+export declare const loadConfig: (configPath?: string) => Promise<{
+    path: string;
+    config: UserConfig;
+} | null>;

package/dist/lib/config.js

@@ -0,0 +1,57 @@
+/*
+ * @vuepress
+ * ---
+ * headline: lib/config.ts
+ * ---
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Names of config files, which are searched in the working directory
+ */
+const CONFIG_FILES = [
+    'vuepress-jsdoc.config.js',
+    'vuepress-jsdoc.config.mjs',
+    'vuepress-jsdoc.config.cjs',
+    'vuepress-jsdoc.config.json'
+];
+/**
+ * Helper for typed config files
+ * @example
+ * // vuepress-jsdoc.config.js
+ * import { defineConfig } from 'vuepress-jsdoc';
+ *
+ * export default defineConfig({ source: './lib', exclude: ['**\/*.test.js'] });
+ * @param {UserConfig} config
+ * @returns {UserConfig} the same config
+ */
+export const defineConfig = (config) => config;
+/**
+ * Load a config file. Without a path, the working directory is searched for a `vuepress-jsdoc.config.*` file.
+ * @param {string} [configPath] path to a config file
+ * @returns {Promise<{ path: string, config: UserConfig } | null>} config or null if there is no config file
+ */
+export const loadConfig = async (configPath) => {
+    const file = configPath
+        ? path.resolve(configPath)
+        : CONFIG_FILES.map((name) => path.resolve(name)).find((p) => fs.existsSync(p));
+    if (!file)
+        return null;
+    if (!fs.existsSync(file)) {
+        throw new Error(`Config file not found: ${configPath}`);
+    }
+    let config;
+    if (file.endsWith('.json')) {
+        config = JSON.parse(await fs.promises.readFile(file, 'utf-8'));
+    }
+    else {
+        // the timestamp prevents a cached module in watch mode or tests
+        const module = await import(`${pathToFileURL(file).href}?t=${Date.now()}`);
+        config = module.default ?? module;
+    }
+    if (!config || typeof config !== 'object') {
+        throw new Error(`Config file has to export an object: ${file}`);
+    }
+    return { path: file, config };
+};

package/dist/lib/list-folder.d.ts

@@ -1,15 +1,33 @@
-import { DirectoryFile, FileTree } from '../interfaces';
-/**
- * Recursively traverse folders and return exluded files, a file list and a file tree.
- * @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
- */
-export declare const listFolder: (srcPath: string, exclude: string[], include: string[], mainPath?: string, tree?: FileTree[]) => Promise<{
+import { DirectoryFile, FileTree } from '../interfaces.js';
+export interface ListFolderResult {
+    /** All files which should be parsed */
     paths: DirectoryFile[];
+    /** Folder structure of all parsable files */
     tree: FileTree[];
+    /** Files which were excluded by the include/exclude patterns */
     excluded: DirectoryFile[];
-}>;
+}
+/**
+ * Normalize a path to a posix path without leading `./` and trailing slash
+ * @param {string} p path
+ * @returns {string} normalized path
+ */
+export declare const normalizePath: (p: string) => string;
+/**
+ * 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 declare const getPageName: (dir: string, name: string) => string;
+/**
+ * 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 {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
+ */
+export declare const listFolder: (srcPath: string, exclude?: string[], include?: string[]) => Promise<ListFolderResult>;

package/dist/lib/list-folder.js

@@ -1,86 +1,116 @@
-"use strict";
-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 __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
  * ---
  */
-const micromatch_1 = __importDefault(require("micromatch"));
-const promises_1 = __importDefault(require("node:fs/promises"));
-const node_path_1 = __importDefault(require("node: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);
+/**
+ * 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 exluded files, a file list and a file tree.
+ * 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
  */
-const listFolder = (srcPath, exclude, include, mainPath, tree = []) => __awaiter(void 0, void 0, void 0, function* () {
-    if (!Boolean(exclude) || !Array.isArray(exclude)) {
-        exclude = [];
-    }
-    if (!Boolean(include) || !Array.isArray(include)) {
-        include = [];
-    }
-    exclude = exclude.filter(Boolean);
-    include = include.filter(Boolean);
+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 dirs = srcPath
-        ? yield promises_1.default.readdir(srcPath, {
-            withFileTypes: true
-        })
-        : [];
-    for (const dirent of dirs) {
-        const filePath = node_path_1.default.join(srcPath, dirent.name);
-        const isDir = dirent.isDirectory();
-        const ext = node_path_1.default.extname(filePath);
-        let name = node_path_1.default.basename(filePath).replace(ext, '');
-        const folder = filePath.replace(name, '').replace(ext, '');
-        if (name.endsWith('index')) {
-            name = srcPath.replace(/\//g, '-') + '-' + name;
-        }
-        const file = Object.assign({ isDir,
-            name, path: filePath }, (!isDir ? { ext, folder } : {}));
-        // skip readmes as they are automatically resolved
-        if (name.toLowerCase() === 'readme')
-            continue;
-        const baseSrc = mainPath || srcPath;
-        if (micromatch_1.default.every(node_path_1.default.join(srcPath.replace(baseSrc, ''), dirent.name), [...include, ...exclude.map((e) => '!' + e)]) ||
-            isDir) {
-            let treeEntry = {
-                name
-            };
-            if (isDir) {
-                treeEntry.children = [];
-                paths.push(...(yield (0, exports.listFolder)(filePath, exclude, include, baseSrc, treeEntry.children)).paths);
-            }
-            else {
-                treeEntry = Object.assign(Object.assign({}, treeEntry), { path: `/${name}`, fullPath: node_path_1.default.join(srcPath, name), ext });
+    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;
             }
-            tree.push(treeEntry);
             paths.push(file);
+            subTree.push({
+                name,
+                path: `/${name}`,
+                fullPath: path.posix.join(dir, name),
+                ext
+            });
         }
-        else {
-            excluded.push(file);
+        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>;