chore: Bump marked from 10.0.0 to 11.1.1

packages/client/src/compiler.ts

@@ -40,12 +40,13 @@ export interface Compiler {
      * tag words array may be provided, in which case the line will be left as
      * is.
      */
-    renderBlock(blockContent: string, reservedTagWords?: string[]): Block;
+    renderBlock(blockContent: string, reservedTagWords?: string[]): Promise<Block>;
 
     /**
      * Render a string of markdown to HTML, using the options from `Documentalist`.
+     * If any `marked` plugin is set to `async: true`, the return value will be a Promise.
      */
-    renderMarkdown(markdown: string): string;
+    renderMarkdown(markdown: string): string | Promise<string>;
 }
 
 /**

packages/compiler/package.json

@@ -23,7 +23,7 @@
     "glob": "^10.3.10",
     "js-yaml": "^4.1.0",
     "kss": "^3.0.1",
-    "marked": "^10.0.0",
+    "marked": "^11.1.1",
     "tsconfig-resolver": "^3.0.1",
     "typedoc": "~0.25.2",
     "yargs": "^17.7.2"

packages/compiler/src/__tests__/__snapshots__/typescript.test.ts.snap

@@ -1502,7 +1502,9 @@ is.",
 }
 `;
 
-exports[`TypescriptPlugin options excludeNames 1`] = `
+exports[`TypescriptPlugin options includePrivateMembers 1`] = `{}`;
+
+exports[`TypescriptPlugin options includePrivateMembers 2`] = `
 [
   "active",
   "disabled",
@@ -1513,13 +1515,3 @@ exports[`TypescriptPlugin options excludeNames 1`] = `
   "type",
 ]
 `;
-
-exports[`TypescriptPlugin options excludePaths 1`] = `{}`;
-
-exports[`TypescriptPlugin options includePrivateMembers 1`] = `
-[
-  "bark",
-  "consumePrivate",
-  "eat",
-]
-`;

packages/compiler/src/__tests__/compilerImpl.test.ts

@@ -41,42 +41,42 @@ describe("CompilerImpl", () => {
         const MARKDOWN = "# Title\nbody body body";
         const OBJECT = { hello: "world", size: 1000 };
 
-        it("extracts contentsRaw and parses metadata", () => {
-            const data = API.renderBlock(METADATA + MARKDOWN);
+        it("extracts contentsRaw and parses metadata", async () => {
+            const data = await API.renderBlock(METADATA + MARKDOWN);
             expect(data.contentsRaw).toBe(MARKDOWN);
             expect(data.metadata).toEqual(OBJECT);
         });
 
-        it("supports empty metadata block", () => {
-            const data = API.renderBlock("---\n---\n" + MARKDOWN);
+        it("supports empty metadata block", async () => {
+            const data = await API.renderBlock("---\n---\n" + MARKDOWN);
             expect(data.contentsRaw).toBe(MARKDOWN);
             expect(data.metadata).toEqual({});
         });
 
-        it("metadata block is optional", () => {
-            const data = API.renderBlock(MARKDOWN);
+        it("metadata block is optional", async () => {
+            const data = await API.renderBlock(MARKDOWN);
             expect(data.contentsRaw).toBe(MARKDOWN);
             expect(data.metadata).toEqual({});
         });
     });
 
     describe("rendered contents", () => {
-        it("returns a single-element array for string without @tags", () => {
-            const { contents } = API.renderBlock("simple string");
+        it("returns a single-element array for string without @tags", async () => {
+            const { contents } = await API.renderBlock("simple string");
             expect(contents).toEqual(["<p>simple string</p>\n"]);
         });
 
-        it("converts @tag to object in array", () => {
-            const { contents } = API.renderBlock(FILE);
+        it("converts @tag to object in array", async () => {
+            const { contents } = await API.renderBlock(FILE);
             expect(contents).toHaveLength(3);
             expect(contents[1]).toEqual({
                 tag: "interface",
                 value: "ButtonProps",
             });
         });
 
-        it("converts @#+ to heading tags in array", () => {
-            const { contents } = API.renderBlock(HEADING_FILE);
+        it("converts @#+ to heading tags in array", async () => {
+            const { contents } = await API.renderBlock(HEADING_FILE);
             expect(contents).toHaveLength(9);
             const headings = contents.filter(isHeadingTag);
             expect(headings).toHaveLength(4);
@@ -89,8 +89,8 @@ describe("CompilerImpl", () => {
             });
         });
 
-        it("reservedWords will ignore matching @tag", () => {
-            const { contents } = API.renderBlock(FILE, ["interface"]);
+        it("reservedWords will ignore matching @tag", async () => {
+            const { contents } = await API.renderBlock(FILE, ["interface"]);
             // only one string (reserved @word does not get split to its own entry)
             expect(contents).toHaveLength(1);
             // @tag value comes out exactly as written in source, on its own line

packages/compiler/src/compilerImpl.ts

@@ -17,7 +17,7 @@
 import { Block, Compiler, HeadingTag, StringOrTag } from "@documentalist/client";
 import * as yaml from "js-yaml";
 import { marked, MarkedOptions } from "marked";
-import { relative } from "path";
+import { relative } from "node:path";
 
 /**
  * Matches the triple-dash metadata block on the first line of markdown file.
@@ -67,9 +67,9 @@ export class CompilerImpl implements Compiler {
         return relative(sourceBaseDir, path);
     };
 
-    public renderBlock = (blockContent: string, reservedTagWords = this.options.reservedTags): Block => {
+    public renderBlock = async (blockContent: string, reservedTagWords = this.options.reservedTags): Promise<Block> => {
         const { contentsRaw, metadata } = this.extractMetadata(blockContent.trim());
-        const contents = this.renderContents(contentsRaw, reservedTagWords);
+        const contents = await this.renderContents(contentsRaw, reservedTagWords);
         return { contents, contentsRaw, metadata };
     };
 
@@ -80,11 +80,12 @@ export class CompilerImpl implements Compiler {
      * `contents` option is `html`, the string nodes will also be rendered with
      * markdown.
      */
-    private renderContents(content: string, reservedTagWords?: string[]) {
+    private async renderContents(content: string, reservedTagWords?: string[]) {
         const splitContents = this.parseTags(content, reservedTagWords);
-        return splitContents
-            .map(node => (typeof node === "string" ? this.renderMarkdown(node) : node))
-            .filter(node => node !== "");
+        const renderedContents = await Promise.all(
+            splitContents.map(node => Promise.resolve(typeof node === "string" ? this.renderMarkdown(node) : node)),
+        );
+        return renderedContents.filter(node => node !== "");
     }
 
     /**

packages/compiler/src/documentalist.ts

@@ -15,9 +15,10 @@
  */
 
 import { File, Plugin } from "@documentalist/client";
-import * as fs from "fs";
 import * as glob from "glob";
-import * as path from "path";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+
 import { CompilerImpl, CompilerOptions } from "./compilerImpl";
 
 /**
@@ -112,7 +113,7 @@ export class Documentalist<T> {
                 const absolutePath = path.resolve(fileName);
                 return {
                     path: absolutePath,
-                    read: () => fs.readFileSync(absolutePath, "utf8"),
+                    read: () => readFileSync(absolutePath, "utf8"),
                 };
             });
     }

packages/compiler/src/launch.ts

@@ -14,7 +14,8 @@
  * limitations under the License.
  */
 
-import * as path from "path";
+import { join } from "node:path";
+
 import { Documentalist } from "./documentalist";
 import { NpmPlugin } from "./plugins/npm";
 import { TypescriptPlugin } from "./plugins/typescript";
@@ -28,9 +29,9 @@ Documentalist.create()
     .use(".ts", new TypescriptPlugin())
     .use("package.json", new NpmPlugin())
     .documentGlobs(
-        path.join(__dirname, "..", "package.json"),
+        join(__dirname, "..", "package.json"),
         // compile test fixtures:
-        path.join(__dirname, "__tests__", "__fixtures__", "*.ts"),
+        join(__dirname, "__tests__", "__fixtures__", "*.ts"),
         // compile our own source code:
         // path.join(__dirname, "..", "src", "index.ts"),
     );

packages/compiler/src/plugins/kss.ts

@@ -15,8 +15,8 @@
  */
 
 import { Compiler, File, KssExample, KssModifier, KssPluginData, Plugin } from "@documentalist/client";
-import * as kss from "kss";
-import * as path from "path";
+import kss from "kss";
+import { dirname } from "node:path";
 
 /**
  * The `KssPlugin` extracts [KSS doc comments](http://warpspire.com/kss/syntax/) from CSS code (or similar languages).
@@ -28,16 +28,16 @@ import * as path from "path";
 export class KssPlugin implements Plugin<KssPluginData> {
     public constructor(private options: kss.Options = {}) {}
 
-    public compile(cssFiles: File[], dm: Compiler): KssPluginData {
+    public async compile(cssFiles: File[], dm: Compiler): Promise<KssPluginData> {
         const styleguide = this.parseFiles(cssFiles);
-        const sections = styleguide.sections().map(s => convertSection(s, dm));
+        const sections = await Promise.all(styleguide.sections().map(s => convertSection(s, dm)));
         const css = dm.objectify(sections, s => s.reference);
         return { css };
     }
 
     private parseFiles(files: File[]) {
         const input = files.map<kss.File>(file => ({
-            base: path.dirname(file.path),
+            base: dirname(file.path),
             contents: file.read(),
             path: file.path,
         }));
@@ -46,19 +46,19 @@ export class KssPlugin implements Plugin<KssPluginData> {
     }
 }
 
-function convertSection(section: kss.KssSection, dm: Compiler): KssExample {
+async function convertSection(section: kss.KssSection, dm: Compiler): Promise<KssExample> {
     return {
-        documentation: dm.renderMarkdown(section.description()),
+        documentation: await dm.renderMarkdown(section.description()),
         markup: section.markup() || "",
-        markupHtml: dm.renderMarkdown(`\`\`\`html\n${section.markup() || ""}\n\`\`\``),
-        modifiers: section.modifiers().map(mod => convertModifier(mod, dm)),
+        markupHtml: await dm.renderMarkdown(`\`\`\`html\n${section.markup() || ""}\n\`\`\``),
+        modifiers: await Promise.all(section.modifiers().map(mod => convertModifier(mod, dm))),
         reference: section.reference(),
     };
 }
 
-function convertModifier(mod: kss.KssModifier, dm: Compiler): KssModifier {
+async function convertModifier(mod: kss.KssModifier, dm: Compiler): Promise<KssModifier> {
     return {
-        documentation: dm.renderMarkdown(mod.description()),
+        documentation: await dm.renderMarkdown(mod.description()),
         name: mod.name(),
     };
 }

packages/compiler/src/plugins/markdown.ts

@@ -27,7 +27,7 @@ import {
     Plugin,
     slugify,
 } from "@documentalist/client";
-import * as path from "path";
+import { basename, extname } from "node:path";
 import { PageMap } from "../page";
 
 export interface MarkdownPluginOptions {
@@ -60,8 +60,8 @@ export class MarkdownPlugin implements Plugin<MarkdownPluginData> {
      * Reads the given set of markdown files and adds their data to the internal storage.
      * Returns a plain object mapping page references to their data.
      */
-    public compile(markdownFiles: File[], compiler: Compiler): MarkdownPluginData {
-        const pageMap = this.buildPageStore(markdownFiles, compiler);
+    public async compile(markdownFiles: File[], compiler: Compiler): Promise<MarkdownPluginData> {
+        const pageMap = await this.buildPageStore(markdownFiles, compiler);
         // now that we have all known pages, we can resolve @include tags.
         this.resolveIncludeTags(pageMap);
         // generate navigation tree after all pages loaded and processed.
@@ -89,10 +89,10 @@ export class MarkdownPlugin implements Plugin<MarkdownPluginData> {
     }
 
     /** Convert each file to PageData and populate store. */
-    private buildPageStore(markdownFiles: File[], { relativePath, renderBlock }: Compiler) {
+    private async buildPageStore(markdownFiles: File[], { relativePath, renderBlock }: Compiler) {
         const pageMap = new PageMap();
         for (const file of markdownFiles) {
-            const block = renderBlock(file.read());
+            const block = await renderBlock(file.read());
             const page = this.blockToPage(relativePath(file.path), block);
             pageMap.set(page.reference, page);
         }
@@ -158,7 +158,7 @@ function getReference(absolutePath: string, { metadata }: Block) {
     if (metadata.reference != null) {
         return metadata.reference;
     }
-    return path.basename(absolutePath, path.extname(absolutePath));
+    return basename(absolutePath, extname(absolutePath));
 }
 
 function getTitle(block: Block) {

packages/compiler/src/plugins/npm.ts

@@ -15,7 +15,7 @@
  */
 
 import { Compiler, File, NpmPackageInfo, NpmPluginData, Plugin } from "@documentalist/client";
-import { spawnSync } from "child_process";
+import { spawnSync } from "node:child_process";
 
 export interface NpmPluginOptions {
     /** Whether to exclude packages marked `private`. */

packages/compiler/src/plugins/typescript/typescriptPlugin.ts

@@ -15,11 +15,12 @@
  */
 
 import type { Compiler, File, Plugin, TsDocEntry, TypescriptPluginData } from "@documentalist/client";
-import { readFileSync } from "fs";
-import { dirname } from "path";
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { tsconfigResolverSync } from "tsconfig-resolver";
 import { Application, LogLevel, TSConfigReader, TypeDocOptions, TypeDocReader } from "typedoc";
 import * as ts from "typescript";
+
 import { Visitor } from "./visitor";
 
 export interface TypescriptPluginOptions {
@@ -208,7 +209,7 @@ export class TypescriptPlugin implements Plugin<TypescriptPluginData> {
             );
         }
 
-        return compiler.objectify(visitor.visitProject(project), i => i.name);
+        return compiler.objectify(await visitor.visitProject(project), i => i.name);
     }
 
     private resolveClosestTsconfig(file: File) {