@forsakringskassan/docs-generator 2.2.2 → 2.4.0

package/dist/compile-example.js

@@ -3,10 +3,10 @@
 var path$1 = require('node:path');
 var esbuild = require('esbuild');
 var vue = require('vue');
-var vue3 = require('./vue3-Cy22ZQUZ.js');
+var vue3 = require('./vue3-CSK73bce.js');
 var path = require('node:path/posix');
 require('@vue/compiler-sfc');
-require('./vendor-CLTTCh4j.js');
+require('./vendor-BJuS1z3U.js');
 require('typescript');
 require('node:url');
 require('fs');

package/dist/{create-markdown-renderer-Db4n4L1y.js → create-markdown-renderer-CipdiqUn.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var vendor = require('./vendor-CLTTCh4j.js');
+var vendor = require('./vendor-BJuS1z3U.js');
 var path = require('node:path/posix');
 var path$1 = require('node:path');
 require('crypto');

package/dist/index.d.ts

@@ -26,6 +26,17 @@ export declare interface CompileOptions {
      * Extra attributes to include in the `<link>` or `<script>` tag.
      */
     attributes: AttributeTable;
+    /**
+     * Assets with higher priority is sorted and loaded earlier than assets with
+     * lower.
+     *
+     * The builtin priorities:
+     *
+     * - Default is `0`.
+     * - Processor runtime assets uses `50`.
+     * - Bootstrap runtime uses `100`.
+     */
+    priority: number;
 }
 
 declare interface Component {
@@ -154,7 +165,9 @@ declare class Generator_2 {
     private resources;
     private sourceFiles;
     constructor(options: GeneratorOptions);
-    compileScript(name: string, src: string | URL, options?: Partial<CompileOptions>): void;
+    compileScript(name: string, src: string | URL, options?: Partial<CompileOptions>, buildOptions?: {
+        define?: Record<string, string>;
+    }): void;
     compileStyle(name: string, src: string | URL, options?: Partial<CompileOptions>): void;
     /**
      * @param dst - Destination directory relative to asset folder.
@@ -345,6 +358,19 @@ export declare interface NormalizedDocumentAttributes {
     sortorder: number;
 }
 
+/**
+ * Interface representing `package.json`.
+ *
+ * @public
+ */
+export declare interface PackageJson {
+    readonly name: string;
+    readonly version: string;
+    readonly repository?: {
+        readonly url?: string;
+    };
+}
+
 /**
  * @public
  */
@@ -378,6 +404,7 @@ export declare interface ProcessorContext {
      */
     addTemplateBlock<T>(container: string, id: string, renderer: TemplateBlockRenderer<T>): void;
     /* Excluded from this release type: getAllTemplateBlocks */
+    /* Excluded from this release type: hasTemplate */
     setTopNavigation(root: NavigationSection): void;
     setSideNavigation(root: NavigationSection): void;
     getAllTemplateData(): Record<string, unknown>;
@@ -432,6 +459,10 @@ export declare interface ProcessorRuntime {
     src: string;
     /** Bundle name (in dist/processors) folder (default: derived from processor name) */
     name?: string;
+    /** Build options (passed to compileScript) */
+    buildOptions?: {
+        define?: Record<string, string>;
+    };
 }
 
 /* Excluded from this release type: processorRuntimeName */
@@ -461,10 +492,7 @@ export declare function searchProcessor(): Processor;
  *
  * @public
  */
-export declare function selectableVersionProcessor(pkg: {
-    name: string;
-    version: string;
-}, container: string, options?: ProcessorOptions): Processor;
+export declare function selectableVersionProcessor(pkg: PackageJson, container: string, options?: ProcessorOptions): Processor;
 
 /**
  * Options passed from the example compiler to the `setup` function.
@@ -494,6 +522,14 @@ export declare interface SourceFiles {
     transform?(doc: Document_2): Document_2;
 }
 
+/**
+ * Processor that provide `componentSourceUrl` template function used for resolving
+ * component source urls.
+ *
+ * @public
+ */
+export declare function sourceUrlProcessor(pkg: PackageJson, options: SourceUrlProcessorOptions): Processor;
+
 /**
  * Processor that provide `componentSourceUrl` template function used for resolving
  * component source urls.
@@ -503,7 +539,7 @@ export declare interface SourceFiles {
 export declare function sourceUrlProcessor(options: SourceUrlProcessorOptions): Processor;
 
 /**
- * Options for {@link sourceUrlProcessor}.
+ * Options for {@link sourceUrlProcessor#}.
  *
  * @public
  */

package/dist/index.js

@@ -1,21 +1,21 @@
 'use strict';
 
 var fs = require('node:fs/promises');
-var vendor = require('./vendor-CLTTCh4j.js');
+var vendor = require('./vendor-BJuS1z3U.js');
 var path = require('node:path');
 var require$$1 = require('crypto');
-var createMarkdownRenderer = require('./create-markdown-renderer-Db4n4L1y.js');
+var createMarkdownRenderer = require('./create-markdown-renderer-CipdiqUn.js');
 var node_child_process = require('node:child_process');
 var path$1 = require('node:path/posix');
 require('node:crypto');
 var util = require('node:util');
 var fs$1 = require('node:fs');
 var vue = require('vue');
-var vue3 = require('./vue3-Cy22ZQUZ.js');
+var vue3 = require('./vue3-CSK73bce.js');
 var vueDocgenApi = require('vue-docgen-api');
 var sass = require('sass');
 var node_url = require('node:url');
-var esbuild = require('esbuild');
+var esbuild$1 = require('esbuild');
 var nunjucks = require('nunjucks');
 var express = require('express');
 require('@vue/compiler-sfc');
@@ -128,6 +128,39 @@ function getIntegrity(source) {
   return `sha384-${hash}`;
 }
 
+function getPullRequestID(env) {
+  if (env.JOB_BASE_NAME) {
+    const name = env.JOB_BASE_NAME;
+    const match = name.match(/^PR-(\d+)$/);
+    return match ? match[1] : void 0;
+  }
+  if (env.GITHUB_REF) {
+    const name = env.GITHUB_REF;
+    const match = name.match(/^refs\/pull\/([^/]+)\/merge$/);
+    return match ? match[1] : void 0;
+  }
+  return void 0;
+}
+
+const RE_MATCH_SSH = /^(ssh:\/\/)?(?<user>[^@]+)@(?<host>[^:]+):(?<path>.*)$/;
+function getRepositoryUrl(value) {
+  if (typeof value !== "string") {
+    const url = value.repository?.url;
+    if (!url) {
+      return null;
+    }
+    value = url;
+  }
+  value = value.replace(/^git[+]/, "");
+  const ssh = value.match(RE_MATCH_SSH);
+  if (ssh) {
+    const { host, path } = ssh.groups;
+    value = `https://${host}/${path}`;
+  }
+  value = value.replace(/[.]git$/, "");
+  return value;
+}
+
 function cacheKey$1(...args) {
   return JSON.stringify(args);
 }
@@ -169,7 +202,7 @@ function haveOutput(doc) {
 }
 
 function interpolate(value, data) {
-  return value.replace(/{{([^}]+)}}/g, (match, raw) => {
+  return value.replace(/{{([^{}]+)}}/g, (match, raw) => {
     const key = raw.trim();
     return data[key] ?? match;
   });
@@ -435,14 +468,6 @@ async function getGitBranch() {
     return branch;
   }
 }
-function getPullRequestID() {
-  if (process.env.JOB_BASE_NAME) {
-    const name = process.env.JOB_BASE_NAME;
-    const match = name.match(/PR-(\d+)/);
-    return match ? match[1] : void 0;
-  }
-  return void 0;
-}
 async function getSCMData(pkg, options) {
   const commitHash = await gitCommitHash("full");
   const commitShort = await gitCommitHash("short");
@@ -450,8 +475,9 @@ async function getSCMData(pkg, options) {
     return null;
   }
   const { homepage } = pkg;
-  const pr = getPullRequestID();
-  const prUrl = pr ? interpolate(options.prUrlFormat, { homepage, pr }) : void 0;
+  const repository = getRepositoryUrl(pkg) ?? "";
+  const pr = getPullRequestID(process.env);
+  const prUrl = pr ? interpolate(options.prUrlFormat, { homepage, pr, repository }) : void 0;
   return {
     branch: await getGitBranch(),
     commitShort,
@@ -459,7 +485,8 @@ async function getSCMData(pkg, options) {
     commitUrl: interpolate(options.commitUrlFormat, {
       hash: commitHash,
       short: commitShort,
-      homepage
+      homepage,
+      repository
     }),
     pr,
     prUrl
@@ -585,25 +612,33 @@ function generateVueExample(options) {
   };
 }
 function generateStaticExample(options) {
-  const { source, language, tags } = options;
+  const { filename, source, language, tags } = options;
+  const slug = getExampleName(filename);
+  const fingerprint = createMarkdownRenderer.getFingerprint(source);
+  const asset = `${slug}-${fingerprint}.${language}`;
   const runtimeLanguages = ["html"];
+  const runtime = runtimeLanguages.includes(language);
   return {
     source,
     language: options.language,
     comments: [],
     tags,
     markup: source,
-    output: null,
-    runtime: runtimeLanguages.includes(language)
+    output: runtime ? asset : null,
+    runtime,
+    task: null
   };
 }
 
-function sourceUrlProcessor(options) {
+function sourceUrlProcessor(...args) {
+  const pkg = args.length === 2 ? args[0] : {};
+  const options = args.length === 2 ? args[1] : args[0];
   const {
     enabled = true,
     urlFormat,
     componentFileExtension = "vue"
   } = options;
+  const repository = getRepositoryUrl(pkg) ?? "";
   return {
     after: "generate-docs",
     name: "source-url-processor",
@@ -617,7 +652,12 @@ function sourceUrlProcessor(options) {
         const { source, name } = component;
         const filename = source ?? `${name}.${componentFileExtension}`;
         const path = getExampleImport(["./"], filename);
-        return interpolate(urlFormat, { path, hash, short });
+        return interpolate(urlFormat, {
+          path,
+          hash,
+          short,
+          repository
+        });
       }
       context.setTemplateData("componentSourceUrl", componentSourceUrl);
     }
@@ -1003,7 +1043,7 @@ async function navigationFileReader(filePath, basePath) {
   return [doc];
 }
 
-function resolveScssImport(filePath) {
+function resolveScssImport(filePath, throwError = true) {
   const { dir, base } = path$1.parse(filePath);
   const search = [`${base}.css`, `${base}.scss`, `_${base}.scss`, `${base}`];
   for (const variant of search) {
@@ -1017,20 +1057,24 @@ function resolveScssImport(filePath) {
       }
     }
   }
-  throw new Error(`Failed to resolve "${filePath}"`);
+  if (throwError) {
+    throw new Error(`Failed to resolve "${filePath}"`);
+  }
+  return null;
 }
-const tildeImporter = {
+const WEBPACK_NODE_MODULE_PREFIX = "~";
+const moduleImporter = {
   canonicalize(url) {
-    const indexOfTilde = url.indexOf("~");
-    if (indexOfTilde >= 0) {
-      return resolveScssImport(url.slice(indexOfTilde + 1));
+    const indexOfPrefix = url.indexOf(WEBPACK_NODE_MODULE_PREFIX);
+    if (indexOfPrefix >= 0) {
+      return resolveScssImport(url.slice(indexOfPrefix + 1));
     }
     if (url.startsWith("file://")) {
       const path$1 = node_url.fileURLToPath(url);
       const relative = path.isAbsolute(path$1) ? path.relative(__dirname, path$1) : path$1;
       return resolveScssImport(relative.replace(/\\/g, "/"));
     }
-    return null;
+    return resolveScssImport(url, false);
   },
   async load(url) {
     const filepath = node_url.fileURLToPath(url);
@@ -1046,7 +1090,7 @@ const tildeImporter = {
 async function compileSassString(dst, style) {
   const result = await sass.compileStringAsync(style, {
     style: "expanded",
-    importers: [tildeImporter]
+    importers: [new sass.NodePackageImporter(), moduleImporter]
   });
   await fs.mkdir(path.dirname(dst), { recursive: true });
   await fs.writeFile(dst, result.css, "utf-8");
@@ -1078,6 +1122,12 @@ async function compileStyle(assetFolder, name, src) {
   }
 }
 
+function byPriority$1({ options: a }, { options: b }) {
+  return b.priority - a.priority;
+}
+function toSorted$1(values, comparator) {
+  return [...values].sort(comparator);
+}
 function cssAssetProcessor(assetFolder, assets) {
   return {
     name: "css-asset-processor",
@@ -1086,7 +1136,7 @@ function cssAssetProcessor(assetFolder, assets) {
       const assetInfo = context.getTemplateData("assets") ?? {};
       const head = context.getTemplateData("injectHead") ?? [];
       const body = context.getTemplateData("injectBody") ?? [];
-      for (const asset of assets) {
+      for (const asset of toSorted$1(assets, byPriority$1)) {
         const info = await compileStyle(
           assetFolder,
           asset.name,
@@ -1114,12 +1164,23 @@ function cssAssetProcessor(assetFolder, assets) {
   };
 }
 
-async function compileScript(assetFolder, name, src, options) {
+function esbuild(options) {
+  return esbuild$1.build(options);
+}
+
+async function compileScript(options) {
+  const {
+    assetFolder,
+    name,
+    src,
+    buildOptions,
+    fs: fs$1 = fs
+  } = options;
   const iconLib = process.env.DOCS_ICON_LIB ?? "@fkui/icon-lib-default";
   try {
     const entryPoints = [src instanceof URL ? node_url.fileURLToPath(src) : src];
     const outfile = path.join("temp", `asset-${name}.js`);
-    await esbuild.build({
+    await esbuild({
       entryPoints,
       outfile,
       bundle: true,
@@ -1127,19 +1188,20 @@ async function compileScript(assetFolder, name, src, options) {
       platform: "browser",
       external: ["vue", "@fkui/vue"],
       tsconfig: path.join(__dirname, "../tsconfig-examples.json"),
+      ...buildOptions,
       define: {
-        "process.env.DOCS_ICON_LIB": JSON.stringify(iconLib)
-      },
-      ...options
+        "process.env.DOCS_ICON_LIB": JSON.stringify(iconLib),
+        ...buildOptions?.define
+      }
     });
-    const content = await fs.readFile(outfile, "utf-8");
+    const content = await fs$1.readFile(outfile, "utf-8");
     const fingerprint = createMarkdownRenderer.getFingerprint(content);
     const integrity = getIntegrity(content);
     const filename = `${name}-${fingerprint}.js`;
     const dst = path.join(assetFolder, filename);
-    await fs.mkdir(path.dirname(dst), { recursive: true });
-    await fs.rename(outfile, dst);
-    const stat = await fs.stat(dst);
+    await fs$1.mkdir(path.dirname(dst), { recursive: true });
+    await fs$1.rename(outfile, dst);
+    const stat = await fs$1.stat(dst);
     return {
       name,
       filename,
@@ -1154,6 +1216,12 @@ async function compileScript(assetFolder, name, src, options) {
   }
 }
 
+function byPriority({ options: a }, { options: b }) {
+  return b.priority - a.priority;
+}
+function toSorted(values, comparator) {
+  return [...values].sort(comparator);
+}
 function jsAssetProcessor(assetFolder, assets) {
   return {
     name: "js-asset-processor",
@@ -1162,12 +1230,13 @@ function jsAssetProcessor(assetFolder, assets) {
       const assetInfo = context.getTemplateData("assets") ?? {};
       const head = context.getTemplateData("injectHead") ?? [];
       const body = context.getTemplateData("injectBody") ?? [];
-      for (const asset of assets) {
-        const info = await compileScript(
+      for (const asset of toSorted(assets, byPriority)) {
+        const info = await compileScript({
           assetFolder,
-          asset.name,
-          asset.src
-        );
+          name: asset.name,
+          src: asset.src,
+          buildOptions: asset.buildOptions
+        });
         const attrs = serializeAttrs(asset.options.attributes);
         const inject = { ...info, attrs: Array.from(attrs).join(" ") };
         assetInfo[asset.name] = info;
@@ -1227,9 +1296,17 @@ function compileProcessorRuntime(generator, distDir, processors) {
       const name = processorRuntimeName(processor, entry);
       const bundled = new URL(`${name}.js`, distDir);
       const scriptPath = fs$1.existsSync(bundled) ? bundled : entry.src;
-      generator.compileScript(assetName, scriptPath, {
-        appendTo: "body"
-      });
+      generator.compileScript(
+        assetName,
+        scriptPath,
+        {
+          appendTo: "body",
+          priority: 50
+        },
+        {
+          ...entry.buildOptions
+        }
+      );
     }
   }
 }
@@ -1449,14 +1526,22 @@ class TemplateLoader {
       }
     }
   }
+  hasTemplate(name) {
+    const { templateCache } = this;
+    const cached = templateCache.get(name);
+    if (cached) {
+      return true;
+    }
+    const filePath = this.findTemplateFile(name);
+    return Boolean(filePath);
+  }
   async resolveTemplate(name) {
     const { templateCache, folders } = this;
     const cached = templateCache.get(name);
     if (cached) {
       return cached;
     }
-    const searchPaths = folders.map((it) => path.join(it, name));
-    const filePath = searchPaths.find((it) => fs$1.existsSync(it));
+    const filePath = this.findTemplateFile(name);
     if (!filePath) {
       const searched = folders.map((it) => `  - "${it}"`).join("\n");
       const message = `Failed to resolve template "${name}", searched in:
@@ -1471,6 +1556,11 @@ Make sure the name is correct and the template file exists in one of the listed
     templateCache.set(name, resolved);
     return resolved;
   }
+  findTemplateFile(name) {
+    const { folders } = this;
+    const searchPaths = folders.map((it) => path.join(it, name));
+    return searchPaths.find((it) => fs$1.existsSync(it));
+  }
 }
 
 function dump(value) {
@@ -1647,6 +1737,7 @@ async function compileStandalones(options) {
 }
 function createTemplateLoader(folders) {
   loader = new TemplateLoader(folders);
+  return loader;
 }
 async function render(doc, docs, nav, vendors, options) {
   const { fileInfo } = doc;
@@ -1694,7 +1785,9 @@ async function render(doc, docs, nav, vendors, options) {
       });
       if (example.output) {
         const { dir, name } = path.parse(example.output);
-        generatedExamples.push(example.task);
+        if (example.task) {
+          generatedExamples.push(example.task);
+        }
         generatedStandalone.push({
           outputFile: path.join(dir, `${name}.html`),
           content: example.markup
@@ -1824,7 +1917,6 @@ function nunjucksProcessor(options) {
       const docs = context.docs.filter((it) => {
         return it.fileInfo.outputName;
       });
-      createTemplateLoader(options.templateFolders);
       progressbar.start(docs.length, 0, {
         filename: docs.length > 0 ? docs[0].fileInfo.fullPath : ""
       });
@@ -1898,7 +1990,7 @@ async function compileVendor(assetFolder, vendor, options) {
   const source = getAssetSource(vendor, customRequire.toString());
   const tsconfig = path.resolve(__dirname, "../tsconfig-examples.json");
   await fs.writeFile(tmpfile, source, "utf-8");
-  await esbuild.build({
+  await esbuild$1.build({
     entryPoints: [tmpfile],
     outfile,
     bundle: true,
@@ -2128,7 +2220,7 @@ async function stage(stage2, context, processors, { verbose } = { verbose: true
   }
   return generatedFiles;
 }
-function createContext() {
+function createContext(templateLoader) {
   let docs = [];
   let vendors = [];
   const resources = [];
@@ -2188,6 +2280,9 @@ function createContext() {
     getAllTemplateBlocks() {
       return templateBlocks;
     },
+    hasTemplate(name) {
+      return Boolean(templateLoader?.hasTemplate(name));
+    },
     setTopNavigation(root) {
       topnav = root;
     },
@@ -2238,17 +2333,22 @@ class Generator {
     this.sourceFiles = [];
     const bootstrapUrl = new URL("runtime-bootstrap.js", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)));
     this.compileScript("bootstrap", bootstrapUrl, {
-      appendTo: "head"
+      appendTo: "head",
+      priority: 100
     });
   }
-  compileScript(name, src, options) {
+  compileScript(name, src, options, buildOptions) {
     this.scripts.push({
       name,
       src,
       options: {
         appendTo: "none",
         attributes: {},
+        priority: 0,
         ...options
+      },
+      buildOptions: {
+        ...buildOptions
       }
     });
   }
@@ -2259,6 +2359,7 @@ class Generator {
       options: {
         appendTo: "none",
         attributes: {},
+        priority: 0,
         ...options
       }
     });
@@ -2287,7 +2388,8 @@ class Generator {
       fileReaderProcessor(sourceFiles),
       ...this.processors
     ];
-    const context = createContext();
+    const templateLoader = createTemplateLoader([]);
+    const context = createContext(templateLoader);
     await stage("generate-docs", context, processors, { verbose: false });
     const docs = context.docs.filter(haveOutput);
     const pages = docs.map(manifestPageFromDocument);
@@ -2326,7 +2428,8 @@ class Generator {
       ...this.processors
     ];
     compileProcessorRuntime(this, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)), processors);
-    const context = createContext();
+    const templateLoader = createTemplateLoader(templateFolders);
+    const context = createContext(templateLoader);
     const generatedFiles = [
       await stage("generate-docs", context, processors),
       await stage("generate-nav", context, processors),

package/dist/markdown.d.ts

@@ -127,9 +127,11 @@ export declare interface ExampleStaticResult {
     /** HTML markup to inject into document */
     markup: string;
     /** asset filename */
-    output: null;
+    output: string | null;
     /** enables/disables running example live in the browser */
     runtime: boolean;
+    /** task data for compiler */
+    task: null;
 }
 
 /**

package/dist/markdown.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var createMarkdownRenderer = require('./create-markdown-renderer-Db4n4L1y.js');
-require('./vendor-CLTTCh4j.js');
+var createMarkdownRenderer = require('./create-markdown-renderer-CipdiqUn.js');
+require('./vendor-BJuS1z3U.js');
 require('@vue/compiler-sfc');
 require('typescript');
 require('node:url');