@forsakringskassan/docs-generator 3.0.3 → 3.1.0

package/dist/{format-code.worker-DHkJESkS.mjs → format-code.worker-Cs0VeEOX.mjs}

@@ -2,7 +2,7 @@ import { createRequire as $createRequire } from "node:module";
 
 const require = $createRequire(import.meta.url);
 
-import { o as runAsWorker, j as format2, r as resolveConfig } from './vendor-DLyCCfC4.mjs';
+import { r as runAsWorker, f as format2, a as resolveConfig } from './vendor-DO1GigtJ.mjs';
 import 'node:url';
 import 'node:path';
 import 'fs';
@@ -54,4 +54,4 @@ async function formatCode(source, filepath) {
 runAsWorker(formatCode);
 
 export { formatCode };
-//# sourceMappingURL=format-code.worker-DHkJESkS.mjs.map
+//# sourceMappingURL=format-code.worker-Cs0VeEOX.mjs.map

package/dist/{format-code.worker-DHkJESkS.mjs.map → format-code.worker-Cs0VeEOX.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"format-code.worker-DHkJESkS.mjs","sources":["../src/utils/format-code.worker.ts"],"sourcesContent":["import { type Options, format as prettier, resolveConfig } from \"prettier\";\nimport { runAsWorker } from \"synckit\";\n\nconst configCache = new Map<string, Options | null>();\n\nasync function getConfig(filepath: string): Promise<Options | null> {\n    const cached = configCache.get(filepath);\n    if (cached !== undefined) {\n        return cached;\n    }\n    const options = await resolveConfig(filepath);\n    configCache.set(filepath, options);\n    return options;\n}\n\n/**\n * @internal\n */\nexport async function formatCode(\n    source: string,\n    filepath: string,\n): Promise<string> {\n    const options = await getConfig(filepath);\n    const formatted = await prettier(source, { ...options, filepath });\n    return formatted.trim();\n}\n\nrunAsWorker(formatCode);\n"],"names":["prettier"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,MAAM,WAAA,uBAAkB,GAAA,EAA4B;AAEpD,eAAe,UAAU,QAAA,EAA2C;AAChE,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,GAAA,CAAI,QAAQ,CAAA;AACvC,EAAA,IAAI,WAAW,MAAA,EAAW;AACtB,IAAA,OAAO,MAAA;AAAA,EACX;AACA,EAAA,MAAM,OAAA,GAAU,MAAM,aAAA,CAAc,QAAQ,CAAA;AAC5C,EAAA,WAAA,CAAY,GAAA,CAAI,UAAU,OAAO,CAAA;AACjC,EAAA,OAAO,OAAA;AACX;AAKA,eAAsB,UAAA,CAClB,QACA,QAAA,EACe;AACf,EAAA,MAAM,OAAA,GAAU,MAAM,SAAA,CAAU,QAAQ,CAAA;AACxC,EAAA,MAAM,SAAA,GAAY,MAAMA,OAAA,CAAS,MAAA,EAAQ,EAAE,GAAG,OAAA,EAAS,UAAU,CAAA;AACjE,EAAA,OAAO,UAAU,IAAA,EAAK;AAC1B;AAEA,WAAA,CAAY,UAAU,CAAA;;;;"}
+{"version":3,"file":"format-code.worker-Cs0VeEOX.mjs","sources":["../src/utils/format-code.worker.ts"],"sourcesContent":["import { type Options, format as prettier, resolveConfig } from \"prettier\";\nimport { runAsWorker } from \"synckit\";\n\nconst configCache = new Map<string, Options | null>();\n\nasync function getConfig(filepath: string): Promise<Options | null> {\n    const cached = configCache.get(filepath);\n    if (cached !== undefined) {\n        return cached;\n    }\n    const options = await resolveConfig(filepath);\n    configCache.set(filepath, options);\n    return options;\n}\n\n/**\n * @internal\n */\nexport async function formatCode(\n    source: string,\n    filepath: string,\n): Promise<string> {\n    const options = await getConfig(filepath);\n    const formatted = await prettier(source, { ...options, filepath });\n    return formatted.trim();\n}\n\nrunAsWorker(formatCode);\n"],"names":["prettier"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGA,MAAM,WAAA,uBAAkB,GAAA,EAA4B;AAEpD,eAAe,UAAU,QAAA,EAA2C;AAChE,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,GAAA,CAAI,QAAQ,CAAA;AACvC,EAAA,IAAI,WAAW,MAAA,EAAW;AACtB,IAAA,OAAO,MAAA;AAAA,EACX;AACA,EAAA,MAAM,OAAA,GAAU,MAAM,aAAA,CAAc,QAAQ,CAAA;AAC5C,EAAA,WAAA,CAAY,GAAA,CAAI,UAAU,OAAO,CAAA;AACjC,EAAA,OAAO,OAAA;AACX;AAKA,eAAsB,UAAA,CAClB,QACA,QAAA,EACe;AACf,EAAA,MAAM,OAAA,GAAU,MAAM,SAAA,CAAU,QAAQ,CAAA;AACxC,EAAA,MAAM,SAAA,GAAY,MAAMA,OAAA,CAAS,MAAA,EAAQ,EAAE,GAAG,OAAA,EAAS,UAAU,CAAA;AACjE,EAAA,OAAO,UAAU,IAAA,EAAK;AAC1B;AAEA,WAAA,CAAY,UAAU,CAAA;;;;"}

package/dist/index.d.mts

@@ -233,6 +233,18 @@ export declare interface FileInfo {
     outputName: string | false;
 }
 
+/**
+ * A function to search for a filename.
+ *
+ * @public
+ * @since %version%
+ * @param filename - The filename to search for
+ * @param context - An optional context for usage in error messages
+ * @throws Throws an error if the filename could not be found
+ * @returns Filename relative to project root
+ */
+export declare type FileMatcher = (filename: string, context?: string) => string;
+
 /**
  * Read and parse a file from disk to a doc-generator document.
  *
@@ -331,7 +343,7 @@ export declare interface GeneratorOptions {
     /** Path to file with exported `setup` function, responsible for mounting of component.
      * `function setup(options: { rootComponent: string, selector: string }): void`
      */
-    setupPath: string;
+    setupPath: string | null;
     /**
      * Options for markdown renderer.
      */
@@ -398,6 +410,8 @@ export declare function livereloadProcessor(options: ProcessorOptions): Processo
 export declare interface Manifest {
     pages: Array<{
         path: string;
+        /** Path to the source document (relative to the project root) */
+        src: string;
         title: string;
         redirect: null | string;
         outline: Array<{
@@ -406,6 +420,8 @@ export declare interface Manifest {
         }>;
         examples: Array<{
             name?: string;
+            /** Path to imported example file (relative to project root) or `null` if example is inline */
+            src: string | null;
             selector: string;
             language: string;
             tags: string[];
@@ -579,6 +595,10 @@ export declare interface ProcessorContext {
      * @param renderer - Describes how to render the block content.
      */
     addTemplateBlock<T>(container: string, id: string, renderer: TemplateBlockRenderer<T>): void;
+    /**
+     * A `fileMatcher()` instance for finding imported examples.
+     */
+    readonly exampleFileMatcher: FileMatcher;
     /* Excluded from this release type: getAllTemplateBlocks */
     /* Excluded from this release type: hasTemplate */
     setTopNavigation(root: NavigationSection): void;
@@ -589,7 +609,16 @@ export declare interface ProcessorContext {
     getTemplateData(key: string): unknown;
     setTemplateData<K extends keyof TemplateData>(key: K, value: TemplateData[K]): void;
     setTemplateData(key: string, value: unknown): void;
+    /**
+     * Log information to the user.
+     */
     log(...args: unknown[]): void;
+    /**
+     * Log error to the user.
+     *
+     * The process will exit with a non-zero exit code after displaying one or more errors.
+     */
+    error(...args: unknown[]): void;
 }
 
 /**

package/dist/index.mjs

@@ -3,15 +3,15 @@ import { createRequire as $createRequire } from "node:module";
 const require = $createRequire(import.meta.url);
 
 import { ApiItemKind, ApiModel } from '@microsoft/api-extractor-model';
-import { p as ts, Z as Ze, M as MarkdownIt, f as dedent, a as closest, h as distance, i as fm, m as isCI, n as moduleImporter, c as cliProgress, t as tinylr, w as watch, b as createInstance, k as fse, l as inter } from './vendor-DLyCCfC4.mjs';
+import { t as ts, Z as Ze, M as MarkdownIt, d as dedent, g as closest, h as distance, i as fm, j as isCI, m as moduleImporter, k as cliProgress, l as tinylr, w as watch, n as createInstance, o as fse, p as inter } from './vendor-DO1GigtJ.mjs';
 import path__default from 'node:path';
 import crypto from 'node:crypto';
 import path from 'node:path/posix';
 import { exec, execSync } from 'node:child_process';
-import { d as generateId, b as formatCode, p as parseInfostring, k as isDocumentPage, n as normalizePath, e as getFingerprint, i as hasTag, a as findTag, h as getOutputFilePath, j as htmlencode, f as filePath, c as createMarkdownRenderer, g as generateExample } from './create-markdown-renderer-B2sP7UDF.mjs';
+import { g as generateId, f as formatCode, p as parseInfostring, i as isDocumentPage, n as normalizePath, a as getFingerprint, h as hasTag, b as parseImport, d as findTag, e as getOutputFilePath, j as htmlencode, k as filePath, c as createMarkdownRenderer, l as generateExample } from './create-markdown-renderer-castrIfY.mjs';
 import { DocExcerpt } from '@microsoft/tsdoc';
 import fs from 'node:fs/promises';
-import util, { promisify } from 'node:util';
+import util, { promisify, styleText } from 'node:util';
 import { codeFrameColumns } from '@babel/code-frame';
 import { parse as parse$1 } from '@babel/parser';
 import traverseModule from '@babel/traverse';
@@ -51,7 +51,7 @@ import 'fs/promises';
 import 'process';
 import 'v8';
 import 'vue';
-import './vue3-RC792pPN.mjs';
+import './vue3-CnvFixWY.mjs';
 
 function toArray$2(value) {
   return Array.isArray(value) ? value : [value];
@@ -673,18 +673,22 @@ function extractExamplesProcessor(options) {
 }
 
 const md$5 = MarkdownIt();
-md$5.renderer.rules.fence = (tokens, idx, _options, collected) => {
+md$5.renderer.rules.fence = (tokens, idx, _options, env) => {
+  const { collected, exampleFileMatcher } = env;
   const { content, info, map } = tokens[idx];
   const { language: rawLanguage, tags } = parseInfostring(info);
   const hashContent = `${String(map?.[0])}:${String(map?.[1])}:${info}:${content}`;
   const fingerprint = getFingerprint(hashContent);
   let extension = void 0;
+  let src = null;
   let language = rawLanguage;
   if (hasTag(tags, "compare")) {
     language = "diff";
   }
   if (language === "import") {
-    extension = content.split(".").at(-1)?.trim();
+    const parsed = parseImport(content);
+    src = exampleFileMatcher(parsed.filename);
+    extension = parsed.extension;
   }
   if (hasTag(tags, "hidden")) {
     return "";
@@ -692,6 +696,7 @@ md$5.renderer.rules.fence = (tokens, idx, _options, collected) => {
   const name = findTag(tags, "name")?.value ?? void 0;
   collected.push({
     name,
+    src,
     selector: `#example-${fingerprint}`,
     language: extension ?? language,
     tags
@@ -706,22 +711,27 @@ function flattenOutline(outline) {
     ];
   });
 }
-function findExamples(doc) {
+function findExamples(context, doc) {
+  const { exampleFileMatcher } = context;
   if (doc.format !== "markdown") {
     return [];
   }
   const collected = [];
-  md$5.render(doc.body, collected);
+  md$5.render(doc.body, {
+    exampleFileMatcher,
+    collected
+  });
   return collected;
 }
-function manifestPageFromDocument(doc) {
+function manifestPageFromDocument(context, doc) {
   const { body, fileInfo, format } = doc;
   return {
     path: getOutputFilePath("", fileInfo),
+    src: doc.fileInfo.fullPath,
     title: doc.attributes.title ?? doc.name,
     redirect: format === "redirect" ? body : null,
     outline: flattenOutline(doc.outline),
-    examples: findExamples(doc)
+    examples: findExamples(context, doc)
   };
 }
 
@@ -772,7 +782,9 @@ function manifestProcessor(options = {}) {
     before: "render",
     async handler(context) {
       const docs = context.docs.filter(isDocumentPage).filter(haveOutput);
-      const pages = docs.map(manifestPageFromDocument);
+      const pages = docs.map(
+        (doc) => manifestPageFromDocument(context, doc)
+      );
       pages.sort((a, b) => {
         return a.path.localeCompare(b.path);
       });
@@ -2289,12 +2301,32 @@ async function globAll(pattern) {
   );
   return new Set(results.flat());
 }
-async function getDocumentsForSource(src) {
+async function getDocumentsForSource(context, src, index) {
   const { transform } = src;
   const include = await globAll(src.include);
   const exclude = await globAll(src.exclude);
   const files = Array.from(difference(include, exclude));
+  let showWarning = true;
   const promises = files.map(async (it) => {
+    if (!src.fileReader) {
+      if (showWarning) {
+        const lines = JSON.stringify(src, null, 2).split("\n");
+        context.error(
+          `"${it}" ignored: \`fileReader\` property was not specified in configuration.`
+        );
+        context.error();
+        context.error(
+          `The file was matched from sourceFiles[${index}]:`
+        );
+        for (const line of lines) {
+          context.error("  ", line);
+        }
+        context.error();
+        context.error("This warning is only shown once.");
+        showWarning = false;
+      }
+      return [];
+    }
     const docs2 = await src.fileReader(it, src.basePath);
     if (transform) {
       return docs2.map((it2) => transform(it2));
@@ -2305,8 +2337,12 @@ async function getDocumentsForSource(src) {
   const docs = await Promise.all(promises);
   return docs.flat();
 }
-async function getAllDocuments(sourceFiles) {
-  const result = await Promise.all(sourceFiles.map(getDocumentsForSource));
+async function getAllDocuments(context, sourceFiles) {
+  const result = await Promise.all(
+    sourceFiles.map((entry, index) => {
+      return getDocumentsForSource(context, entry, index);
+    })
+  );
   return result.flat();
 }
 function fileReaderProcessor(sourceFiles) {
@@ -2314,7 +2350,7 @@ function fileReaderProcessor(sourceFiles) {
     stage: "generate-docs",
     name: "file-reader-processor",
     async handler(context) {
-      const result = await getAllDocuments(sourceFiles);
+      const result = await getAllDocuments(context, sourceFiles);
       context.addDocument(result);
       context.log(result.length, "documents found");
     }
@@ -2396,7 +2432,7 @@ async function compileStyle(assetFolder, name, src) {
     };
   } catch (err) {
     console.error(err);
-    throw new Error(`Failed to compile style "${name}"`);
+    throw new Error(`Failed to compile style "${name}"`, { cause: err });
   }
 }
 
@@ -2495,7 +2531,9 @@ async function compileScript(options) {
     };
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to compile script "${name}": ${reason}`);
+    throw new Error(`Failed to compile script "${name}": ${reason}`, {
+      cause: err
+    });
   }
 }
 
@@ -2666,19 +2704,6 @@ var langSv = {
 	translation: translation
 };
 
-function navigationProcessor() {
-  return {
-    stage: "generate-nav",
-    name: "navigation-processor",
-    handler(context) {
-      const pages = context.docs.filter(isDocumentPage);
-      const navtree = generateNavtree(pages);
-      context.setTopNavigation(navtree);
-      context.setSideNavigation(navtree);
-    }
-  };
-}
-
 function sortNavigationTree(tree) {
   tree.children.sort((a, b) => {
     if (a.sortorder < b.sortorder) {
@@ -2703,6 +2728,20 @@ function sortNavigationTree(tree) {
   }
 }
 
+function navigationProcessor() {
+  return {
+    stage: "generate-nav",
+    name: "navigation-processor",
+    handler(context) {
+      const pages = context.docs.filter(isDocumentPage);
+      const navtree = generateNavtree(pages);
+      sortNavigationTree(navtree);
+      context.setTopNavigation(navtree);
+      context.setSideNavigation(navtree);
+    }
+  };
+}
+
 const templateUrl = new URL("../templates", import.meta.url);
 const templateDirectory = fileURLToPath(templateUrl);
 
@@ -2962,9 +3001,17 @@ function createTemplateLoader(folders) {
 function stripPrettierComments(content) {
   return content.replaceAll(/\s*<!-- prettier-ignore -->\s*/gm, "");
 }
-async function render(doc, docs, nav, vendors, options) {
+async function render(doc, docs, options) {
   const { fileInfo } = doc;
-  const { i18n, outputFolder, cacheFolder, templateFolders, fileMatcher } = options;
+  const {
+    i18n,
+    outputFolder,
+    cacheFolder,
+    exampleFileMatcher,
+    nav,
+    templateFolders,
+    vendors
+  } = options;
   if (!haveOutputFile(fileInfo)) {
     return null;
   }
@@ -3032,7 +3079,7 @@ async function render(doc, docs, nav, vendors, options) {
         setupPath: options.setupPath,
         exampleFolders: options.exampleFolders,
         tags,
-        fileMatcher
+        fileMatcher: exampleFileMatcher
       });
       if (example.output) {
         const { dir, name } = path__default.parse(example.output);
@@ -3048,7 +3095,7 @@ async function render(doc, docs, nav, vendors, options) {
     },
     getImportedSource(filename) {
       const context = `when importing example from "${fileInfo.fullPath}"`;
-      const match = fileMatcher(filename, context);
+      const match = exampleFileMatcher(filename, context);
       return readFileSync(match, "utf8");
     },
     addResource(dst2, src) {
@@ -3169,14 +3216,16 @@ function nunjucksProcessor(options) {
     name: "nunjucks-renderer",
     async handler(context) {
       function renderDocument(doc) {
-        const nav = {
-          topnav: context.topnav,
-          sidenav: context.sidenav
-        };
-        return render(doc, context.docs, nav, context.vendors, {
+        return render(doc, context.docs, {
           ...options,
+          exampleFileMatcher: context.exampleFileMatcher,
+          nav: {
+            topnav: context.topnav,
+            sidenav: context.sidenav
+          },
           templateBlocks: context.getAllTemplateBlocks(),
           templateData: context.getAllTemplateData(),
+          vendors: context.vendors,
           addResource(dst, src) {
             context.addResource(dst, src);
           }
@@ -3452,12 +3501,28 @@ async function stage(stage2, context, processors, options) {
       console.log(isLast ? "  \u2514\u2500" : "  \u251C\u2500", processor.name);
     }
     try {
+      const prefix = (() => {
+        if (verbose) {
+          return isLast ? "      " : "  \u2502   ";
+        } else {
+          return "";
+        }
+      })();
       const result = await processor.handler({
         ...context,
         log(...args) {
           if (verbose) {
-            console.log(isLast ? "      " : "  \u2502   ", ...args);
+            console.log(prefix, ...args);
           }
+        },
+        error(...args) {
+          process.exitCode = 1;
+          console.error(
+            prefix,
+            ...args.map(
+              (it) => typeof it === "string" ? styleText("red", it) : it
+            )
+          );
         }
       });
       if (result) {
@@ -3470,7 +3535,8 @@ async function stage(stage2, context, processors, options) {
   }
   return generatedFiles;
 }
-function createContext(outputFolder, templateLoader) {
+function createContext(options) {
+  const { outputFolder, exampleFileMatcher, templateLoader } = options;
   let docs = [];
   let vendors = [];
   const resources = [];
@@ -3509,6 +3575,7 @@ function createContext(outputFolder, templateLoader) {
       return sidenav;
     },
     outputFolder,
+    exampleFileMatcher,
     addDocument(document) {
       docs = [...docs, ...toArray(document)];
     },
@@ -3607,7 +3674,7 @@ class Generator {
     this.templateFolders = options.templateFolders ?? [];
     this.processors = options.processors ?? [];
     this.vendor = options.vendor ?? [];
-    this.setupPath = options.setupPath.replaceAll("\\", "/");
+    this.setupPath = options.setupPath?.replaceAll("\\", "/") ?? null;
     this.scripts = [];
     this.styles = [];
     this.resources = [];
@@ -3678,11 +3745,19 @@ class Generator {
       redirectProcessor(),
       ...this.processors
     ];
+    const examplePatterns = this.exampleFolders.map((it) => `${it}/**/*`);
+    const exampleFileMatcher = fileMatcher(examplePatterns);
     const templateLoader = createTemplateLoader([]);
-    const context = createContext("", templateLoader);
+    const context = createContext({
+      outputFolder: "",
+      exampleFileMatcher,
+      templateLoader
+    });
     await stage("generate-docs", context, processors, { verbose: false });
     const docs = context.docs.filter(isDocumentPage).filter(haveOutput);
-    const pages = docs.map(manifestPageFromDocument);
+    const pages = docs.map((doc) => {
+      return manifestPageFromDocument({ exampleFileMatcher }, doc);
+    });
     return { pages };
   }
   async build(sourceFiles) {
@@ -3728,14 +3803,17 @@ class Generator {
         exampleFolders,
         templateFolders,
         setupPath,
-        markdown: markdownOptions ?? {},
-        fileMatcher: fileMatcher(examplePatterns)
+        markdown: markdownOptions ?? {}
       }),
       ...this.processors
     ];
     compileProcessorRuntime(this, import.meta.url, processors);
     const templateLoader = createTemplateLoader(templateFolders);
-    const context = createContext(outputFolder, templateLoader);
+    const context = createContext({
+      outputFolder,
+      exampleFileMatcher: fileMatcher(examplePatterns),
+      templateLoader
+    });
     const generatedFiles = [
       await stage("generate-docs", context, processors),
       await stage("generate-nav", context, processors),
@@ -3881,6 +3959,9 @@ function searchProcessor() {
       context.addTemplateBlock("toolbar", "search-toolbar", {
         filename: "partials/search-toolbar.html"
       });
+      context.addTemplateBlock("head", "search-preload", {
+        filename: "partials/search-preload.html"
+      });
       context.addTemplateBlock("body:end", "search-dialog", {
         filename: "partials/search-dialog.html"
       });