vuepress-jsdoc 4.3.1 → 6.1.0

package/dist/interfaces.d.ts

@@ -1,32 +1,58 @@
+import { StatisticType } from './constants.js';
 export interface DirectoryFile {
+    /** Path of the file relative to the working directory, e.g. `src/lib/foo.ts` */
     path: string;
-    isDir: boolean;
-    ext?: string;
+    /** Name of the generated page without extension. `index` files are prefixed with their folder. */
     name: string;
-    folder?: string;
+    /** File extension, e.g. `.ts` */
+    ext: string;
+    /** Folder of the file relative to the working directory with a trailing slash, e.g. `src/lib/` */
+    folder: string;
 }
 export interface CLIArguments {
-    include: string;
-    exclude: string;
-    partials: string[];
-    rmPattern: string[];
-    folder: string;
-    jsDocConfigPath: string;
-    source: string;
-    dist: string;
-    title: string;
-    readme: string;
-    watch: boolean;
+    /** Pattern to include files/folders (comma separated or list) */
+    include?: string | string[];
+    /** Pattern to exclude files/folders (comma separated or list) */
+    exclude?: string | string[];
+    /** jsdoc2markdown partial templates */
+    partials?: string[] | string;
+    /** Additional glob patterns of files to remove before generating */
+    rmPattern?: string[] | string;
+    /** Folder inside the destination folder, default `code` */
+    folder?: string;
+    /** Path to a jsdoc config */
+    jsDocConfigPath?: string;
+    /** Source folder, default `./src` */
+    source?: string;
+    /** Destination folder, default `./documentation` */
+    dist?: string;
+    /** Title of the documentation, default `API` */
+    title?: string;
+    /** Path to a custom readme */
+    readme?: string;
+    /** Watch the source files */
+    watch?: boolean;
+    /** Make the top level sidebar groups collapsible, default `false` */
+    collapsible?: boolean;
+    /** Sidebar format of the generated `config.js`, default `vuepress` */
+    format?: 'vuepress' | 'vitepress';
+    /** Path to a config file */
+    config?: string;
 }
+/**
+ * Options of a `vuepress-jsdoc.config.js` file
+ */
+export type UserConfig = Omit<CLIArguments, 'config'>;
 export interface ParseReturn {
-    success: boolean;
+    /** Result of parsing */
+    type: StatisticType;
+    /** Destination folder relative to the working directory */
     dest: string;
     file: DirectoryFile;
+    /** Rendered markdown (including the frontmatter) */
     content: string;
-    empty: boolean;
-    excluded?: boolean;
-    relativePathSrc: string;
-    relativePathDest: string;
+    /** Error message, if the file could not be parsed */
+    error?: string;
 }
 export interface FileTree {
     name: string;

package/dist/interfaces.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/lib/comment-parser.d.ts

@@ -1,17 +1,23 @@
-import { DirectoryFile } from '../interfaces';
+import { DirectoryFile } from '../interfaces.js';
+interface ParsedComment {
+    /** raw frontmatter string */
+    frontmatter: string | null;
+    /** parsed frontmatter attributes */
+    attributes: Record<string, any> | null;
+}
 /**
- * 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
  */
-export declare const parseComment: (fileContent: string) => import("front-matter").FrontMatterResult<Record<string, string>> | {
-    frontmatter: null;
-    attributes: null;
-};
+export declare const parseComment: (fileContent: string) => ParsedComment;
 /**
- * Helper function to get header as structured markdown
+ * 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
  */
-export declare const parseVuepressFileHeader: (content: string, file: DirectoryFile) => string;
+export declare const parseVuepressFileHeader: (content: string, file: Pick<DirectoryFile, 'name' | 'ext'>) => string;
+export {};

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
  * ---
  */
-var 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
  */
-var parseComment = function (fileContent) {
+export const parseComment = (fileContent) => {
+    const empty = { frontmatter: null, attributes: null };
+    if (typeof fileContent !== 'string')
+        return empty;
     try {
-        var allCommentBlocks = fileContent.match(/\/\*[\s\S]*?\*\/|([^:]|^)\/\/.*$/g);
-        var vuepressBlock = allCommentBlocks === null || allCommentBlocks === void 0 ? void 0 : allCommentBlocks.filter(function (block) {
-            return block.split('\n').filter(function (line) { return 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
  */
-var parseVuepressFileHeader = function (content, file) {
-    var _a = (0, exports.parseComment)(content), frontmatter = _a.frontmatter, attributes = _a.attributes;
-    var fileContent = '---\n';
-    fileContent += !(attributes === null || attributes === void 0 ? void 0 : attributes.title) ? "title: ".concat(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 += "".concat(frontmatter);
+        lines.push(frontmatter);
     }
-    fileContent += '\n---\n';
-    if ((attributes === null || attributes === void 0 ? void 0 : attributes.title) || file.ext !== '.vue') {
-        var 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# ".concat(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>;