@forsakringskassan/docs-generator 1.26.0 → 1.28.0

package/dist/create-markdown-renderer-CPrI2LLQ.js

@@ -0,0 +1,640 @@
+'use strict';
+
+var vendor = require('./vendor-uab7h6x-.js');
+var path = require('node:path/posix');
+require('node:path');
+require('crypto');
+var crypto = require('node:crypto');
+
+function findDocument(haystack, needle) {
+  const match = haystack.find((it) => {
+    if (it.id === needle) {
+      return true;
+    }
+    if (it.name === needle) {
+      return true;
+    }
+    if (it.alias.includes(needle)) {
+      return true;
+    }
+    return false;
+  });
+  return match ?? null;
+}
+
+const replacements = {
+  \u00E5: "a",
+  \u00E4: "a",
+  \u00F6: "o"
+};
+function findVersion(text) {
+  const match = text.match(/(\d+)\.(\d+)\.(\d+) \(\d+-\d+-\d+\)/);
+  if (match) {
+    return [
+      parseInt(match[1], 10),
+      parseInt(match[2], 10),
+      parseInt(match[3], 10)
+    ];
+  } else {
+    return null;
+  }
+}
+function generateId(text) {
+  const version = findVersion(text);
+  if (version) {
+    return `v${version.join("-")}`;
+  }
+  return text.toLowerCase().trim().replace(/[åäö]/g, (m) => replacements[m]).replace(/[^a-z0-9]+/g, "_").replace(/^_+/, "").replace(/_+$/, "");
+}
+
+function getFingerprint(source) {
+  return crypto.createHash("md5").update(source).digest("hex").slice(0, 6);
+}
+
+function normalizePath(...pathSegments) {
+  const filePath = path.join(...pathSegments);
+  return path.normalize(filePath).replace(/\\/g, "/");
+}
+
+function getOutputFilePath(outputFolder, fileInfo) {
+  const { path, outputName } = fileInfo;
+  if (outputName === false) {
+    return null;
+  }
+  return normalizePath(outputFolder, path, outputName);
+}
+
+class SoftError extends Error {
+  code;
+  details;
+  /**
+   * @internal
+   */
+  constructor(code, message, ...args) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    const [details] = args;
+    this.details = details;
+  }
+}
+
+function processInlineTags(tags, doc, docs, text, handleSoftError) {
+  return text.replace(/{@([\S}]+)([^}]*)}/g, (_, name, content) => {
+    const tag = tags.find((it) => it.name === name);
+    if (!tag) {
+      return handleSoftError(
+        new SoftError(
+          "ETAGMISSING",
+          `No inline tag registered with the name "${name}"`
+        )
+      );
+    }
+    try {
+      return tag.handler(doc, docs, content.trim());
+    } catch (err) {
+      if (err instanceof SoftError) {
+        return handleSoftError(err);
+      } else {
+        throw err;
+      }
+    }
+  });
+}
+
+function getRelativeUrl(from, to) {
+  const fromResolved = getOutputFilePath(".", from.fileInfo);
+  const toResolved = getOutputFilePath(".", to.fileInfo);
+  if (!fromResolved || !toResolved) {
+    throw new Error("Cannot create link to document with no output");
+  }
+  const fromDir = path.dirname(fromResolved);
+  const toDir = path.dirname(toResolved);
+  const relative = path.relative(fromDir, toResolved);
+  if (fromDir === toDir) {
+    return relative === "index.html" ? "./" : `./${relative}`;
+  } else if (relative.endsWith("/index.html")) {
+    return path.dirname(relative);
+  } else {
+    return relative;
+  }
+}
+function getLinkTitle(doc, key, explicitTitle) {
+  if (explicitTitle) {
+    return explicitTitle;
+  }
+  const { title, component } = doc.attributes;
+  if (component && component.includes(key)) {
+    return `<code>${key}</code>`;
+  } else {
+    return title ?? doc.name;
+  }
+}
+const linkTag = {
+  name: "link",
+  description: "Create a link to another document",
+  handler(doc, docs, content) {
+    const match = content.match(/^([^\s#]+)(#\S+)?\s*(.+)?$/);
+    if (!match) {
+      throw new SoftError(
+        "ELINKFORMAT",
+        `Failed to parse link "${content}"`
+      );
+    }
+    const [, key, hash, explicitTitle] = match;
+    if (key.startsWith("http://") || key.startsWith("https://")) {
+      return `<a href="${key}${hash ?? ""}">${explicitTitle ?? key}</a>`;
+    }
+    const linked = findDocument(docs, key);
+    if (!linked) {
+      throw new SoftError(
+        "ELINKTARGET",
+        `Failed to find linked document "${key}"`,
+        {
+          key,
+          hash,
+          title: explicitTitle
+        }
+      );
+    }
+    const url = getRelativeUrl(doc, linked);
+    const title = getLinkTitle(linked, key, explicitTitle);
+    return `<a href="${url}${hash ?? ""}">${title}</a>`;
+  }
+};
+
+const inlineTags = [linkTag];
+
+function findTestId(tags) {
+  const prefix = "test-id=";
+  const tag = tags.find((it) => {
+    return it.startsWith(prefix);
+  });
+  const match = tag == null ? void 0 : tag.match(/^test-id=(?:"([^"]+)"|'([^']+)'|([^'"]+))$/);
+  if (!match) {
+    return null;
+  }
+  return match.slice(1).find(Boolean) ?? null;
+}
+
+const HTML_ESCAPE_REPLACE_RE = /[&<>"]/g;
+const HTML_REPLACEMENTS = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;"
+};
+function escapeHtml(str) {
+  return str.replace(HTML_ESCAPE_REPLACE_RE, (ch) => HTML_REPLACEMENTS[ch]);
+}
+function wrap(content, language) {
+  const markup = (
+    /* HTML */
+    `
+        <code class="hljs lang-${language}" tabindex="0">${content}</code>
+    `
+  );
+  return markup.trim();
+}
+function highlight({
+  source,
+  language
+}) {
+  switch (language) {
+    case "":
+    case "import":
+    case "mermaid":
+    case "plaintext":
+      return `<code>${escapeHtml(source)}</code>`;
+    case "vue":
+      return highlight({ source, language: "html" });
+  }
+  try {
+    const { value } = vendor.HighlightJS.highlight(source, { language });
+    return wrap(value, language);
+  } catch (err) {
+    return wrap(String(err), language);
+  }
+}
+
+const replacement = {
+  "<": `&lt;`,
+  ">": `&gt;`,
+  "&": `&amp;`,
+  '"': `&quot;`,
+  "'": `&apos;`
+};
+function htmlencode(text) {
+  return text.replace(/[<>&"']/g, (m) => {
+    return replacement[m];
+  });
+}
+
+function replaceAtLink(text) {
+  return text.replace(
+    /{@link [^}]+[$}]/g,
+    (match) => match.replace("{", "&lcub;").replace("}", "&rcub;")
+  );
+}
+
+function getClassModifier(tags) {
+  if (tags.includes("borderless")) {
+    return "code-preview--borderless";
+  }
+  return "code-preview--default";
+}
+function codePreview(options) {
+  const { generateExample } = options;
+  return (md) => {
+    md.renderer.rules.fence = fence.bind(void 0, md);
+  };
+  function fence(_md, tokens, idx, _options, env) {
+    const { fileInfo } = env;
+    const { content: source, info, map } = tokens[idx];
+    const [language, ...rawTags] = info.split(/\s+/);
+    if (language === "mermaid") {
+      return (
+        /* HTML */
+        `
+                <pre class="mermaid">${htmlencode(source)}</pre>
+            `
+      );
+    }
+    const example = generateExample({
+      source,
+      language,
+      filename: fileInfo.fullPath,
+      tags: rawTags
+    });
+    const { tags } = example;
+    const hashContent = `${map == null ? void 0 : map[0]}:${map == null ? void 0 : map[1]}:${info}:${source}`;
+    const fingerprint = getFingerprint(hashContent);
+    const highlightedCode = replaceAtLink(highlight(example));
+    const testId = findTestId(tags);
+    const liveExample = tags.includes("live-example");
+    const staticCode = example.runtime === false || tags.includes("static");
+    const noMarkup = tags.includes("nomarkup");
+    const fullscreen = tags.includes("fullscreen");
+    const modifier = getClassModifier(tags);
+    const standalone = Boolean(example.output) && fullscreen;
+    const testIdAttr = testId ? `data-test="${testId}"` : "";
+    const filteredTags = tags.filter((it) => {
+      if (it.startsWith("test-id=")) {
+        return false;
+      }
+      return true;
+    });
+    const dataTagsAttr = filteredTags.length > 0 ? `data-tags=${filteredTags.join(" ")}` : "";
+    if (liveExample) {
+      return (
+        /* HTML */
+        `
+                <div
+                    id="example-${fingerprint}"
+                    class="code-preview code-preview--borderless"
+                    ${testIdAttr}
+                    ${dataTagsAttr}
+                    data-language="${example.language}"
+                >
+                    ${example.markup}
+                </div>
+            `
+      );
+    }
+    if (staticCode) {
+      return (
+        /* HTML */
+        `
+                <div
+                    id="example-${fingerprint}"
+                    class="code-preview ${modifier}"
+                    ${testIdAttr}
+                    ${dataTagsAttr}
+                    data-language="${example.language}"
+                >
+                    ${example.comments.join("\n")}
+                    <pre class="code-preview__markup">${highlightedCode}</pre>
+                </div>
+            `
+      );
+    }
+    if (noMarkup) {
+      return (
+        /* HTML */
+        `
+                <div
+                    id="example-${fingerprint}"
+                    class="code-preview ${modifier}"
+                    ${testIdAttr}
+                    ${dataTagsAttr}
+                    data-language="${example.language}"
+                >
+                    ${example.comments.join("\n")}
+                    <div class="code-preview__preview">${example.markup}</div>
+                </div>
+            `
+      );
+    }
+    const toggleMarkup = (
+      /* HTML */
+      `
+            <button
+                type="button"
+                class="button button--discrete code-preview__toggle-markup"
+                aria-expanded="false"
+                onclick="toggleMarkup(this)"
+            >
+                <i class="icon icon--code"></i>
+                Visa kod
+            </button>
+        `
+    );
+    const toggleFullscreen = fullscreen ? (
+      /* HTML */
+      `
+                  <a href="${standalone}" class="code-preview__fullscreen">
+                      <i class="icon icon--fullscreen"></i>
+                      Helsk\xE4rm
+                  </a>
+              `
+    ) : "";
+    return (
+      /* HTML */
+      `
+            <div
+                id="example-${fingerprint}"
+                class="code-preview ${modifier}"
+                ${testIdAttr}
+                ${dataTagsAttr}
+                data-language="${example.language}"
+            >
+                ${example.comments.join("\n")}
+                <div class="code-preview__preview">${example.markup}</div>
+                <div>${toggleMarkup} ${toggleFullscreen}</div>
+                <div
+                    class="code-preview__expand animate-expand"
+                    style="height: 0px;"
+                    hidden
+                >
+                    <pre class="code-preview__markup">${highlightedCode}</pre>
+                </div>
+            </div>
+        `
+    );
+  }
+}
+
+function getTokensText(tokens) {
+  return tokens.filter((token) => ["text", "code_inline"].includes(token.type)).map((token) => token.content).join("");
+}
+function headingLevel(options) {
+  const { initialLevel } = options;
+  const offset = initialLevel - 1;
+  let counter = 1;
+  return function(md) {
+    md.renderer.rules.heading_open = function(tokens, idx, _options, env) {
+      var _a;
+      const { ids } = env;
+      const { tag } = tokens[idx];
+      const title = getTokensText(((_a = tokens[idx + 1]) == null ? void 0 : _a.children) ?? []);
+      let id = generateId(title);
+      if (ids.has(id)) {
+        id += `--${counter++}`;
+      }
+      ids.add(id);
+      return tag.replace(/h(\d)/, (_, n) => {
+        const level = parseInt(n, 10) + offset;
+        return `<h${level} id="${id}"><a class="header-anchor" href="#${id}">`;
+      });
+    };
+    md.renderer.rules.heading_close = function(tokens, idx) {
+      const { tag } = tokens[idx];
+      return tag.replace(/h(\d)/, (_, n) => {
+        const level = parseInt(n, 10) + offset;
+        return `</a></h${level}>`;
+      });
+    };
+  };
+}
+
+function computeHash(source) {
+  return crypto.createHash("md5").update(source).digest("hex");
+}
+function getFilename(fileInfo, src) {
+  const key = [fileInfo.fullPath, src].join("-");
+  const hash = computeHash(key);
+  const { ext } = path.parse(src);
+  return `images/${hash}${ext}`;
+}
+function imageResources(options) {
+  const { addResource } = options;
+  function imageResource(tokens, index, options2, env, self) {
+    const { fileInfo } = env;
+    const token = tokens[index];
+    token.attrs ??= [];
+    const srcAttr = token.attrGet("src");
+    if (srcAttr) {
+      const dst = getFilename(fileInfo, srcAttr);
+      const src = path.join(path.dirname(fileInfo.fullPath), srcAttr);
+      const url = path.relative(fileInfo.path, path.join("assets", dst));
+      addResource(dst, src);
+      token.attrs[token.attrIndex("src")][1] = url;
+    }
+    token.attrs[token.attrIndex("alt")][1] = self.renderInlineAsText(
+      /* eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- from upstream code */
+      token.children,
+      options2,
+      env
+    );
+    return self.renderToken(tokens, index, options2);
+  }
+  return function(md) {
+    md.renderer.rules.image = imageResource;
+  };
+}
+
+const markerStr = ":";
+const markerChar = markerStr.charCodeAt(0);
+function parser(md, options) {
+  function container(state, startLine, endLine, silent) {
+    let pos = state.bMarks[startLine] + state.tShift[startLine];
+    let max = state.eMarks[startLine];
+    if (state.sCount[startLine] - state.blkIndent >= 4) {
+      return false;
+    }
+    if (pos + 3 > max) {
+      return false;
+    }
+    const marker = state.src.charCodeAt(pos);
+    if (marker !== markerChar) {
+      return false;
+    }
+    let mem = pos;
+    pos = state.skipChars(pos, marker);
+    let len = pos - mem;
+    if (len < 3) {
+      return false;
+    }
+    const markup = state.src.slice(mem, pos);
+    const params = state.src.slice(pos, max).trim();
+    const kind = params.split(" ", 2)[0];
+    if (silent) {
+      return true;
+    }
+    let nextLine = startLine;
+    let haveEndMarker = false;
+    for (; ; ) {
+      nextLine++;
+      if (nextLine >= endLine) {
+        break;
+      }
+      pos = mem = state.bMarks[nextLine] + state.tShift[nextLine];
+      max = state.eMarks[nextLine];
+      if (pos < max && state.sCount[nextLine] < state.blkIndent) {
+        break;
+      }
+      if (state.src.charCodeAt(pos) !== marker) {
+        continue;
+      }
+      if (state.sCount[nextLine] - state.blkIndent >= 4) {
+        continue;
+      }
+      pos = state.skipChars(pos, marker);
+      if (pos - mem < len) {
+        continue;
+      }
+      pos = state.skipSpaces(pos);
+      if (pos < max) {
+        continue;
+      }
+      haveEndMarker = true;
+      break;
+    }
+    len = state.sCount[startLine];
+    state.line = nextLine + (haveEndMarker ? 1 : 0);
+    const token = state.push(`doc_${kind}`, "div", 0);
+    token.info = params;
+    token.content = state.getLines(startLine + 1, nextLine, len, true);
+    token.markup = markup;
+    token.map = [startLine, state.line];
+    return true;
+  }
+  md.block.ruler.before("fence", "container_include", container, {
+    alt: ["paragraph", "reference", "blockquote", "list"]
+  });
+  for (const [kind, fn] of Object.entries(options)) {
+    md.renderer.rules[`doc_${kind}`] = fn;
+  }
+}
+function include(docs, env, included, handleSoftError) {
+  return function(md) {
+    md.use(parser, {
+      api(tokens, index) {
+        const token = tokens[index];
+        const needle = token.content.trim();
+        const doc = findDocument(docs, needle);
+        if (!doc) {
+          return handleSoftError(
+            new SoftError(
+              "EINCLUDETARGET",
+              `No document matches "${needle}" when trying to include content`,
+              { id: needle }
+            )
+          );
+        }
+        if (included.has(doc.id)) {
+          return handleSoftError(
+            new SoftError(
+              "EINCLUDERECURSION",
+              `Recursion detected when including document "${doc.id}"`
+            )
+          );
+        }
+        included.add(doc.id);
+        if (doc.format === "html") {
+          return doc.body;
+        }
+        const content = md.render(doc.body, env);
+        return (
+          /* HTML */
+          ` <div>${content}</div> `
+        );
+      }
+    });
+  };
+}
+
+function table() {
+  return function(md) {
+    md.renderer.rules.table_open = () => `<table class="table">
+`;
+    md.renderer.rules.tr_open = () => `<tr class="table__row">
+`;
+    md.renderer.rules.th_open = () => `<th class="table__column table__column--text" scope="col">`;
+    md.renderer.rules.td_open = () => `<td class="table__column table__column--text">`;
+  };
+}
+
+function codeInline() {
+  return function(md) {
+    const original = md.renderer.rules.code_inline;
+    md.renderer.rules.code_inline = (...args) => {
+      const tmp = original(...args);
+      return replaceAtLink(tmp);
+    };
+  };
+}
+
+function createMarkdownRenderer(options) {
+  const { docs } = options;
+  const env = {
+    fileInfo: {
+      fullPath: "",
+      name: "",
+      path: "",
+      outputName: false
+    },
+    ids: /* @__PURE__ */ new Set()
+  };
+  const included = /* @__PURE__ */ new Set();
+  const md = vendor.MarkdownIt({
+    html: true
+  });
+  md.use(
+    codePreview({
+      generateExample: options.generateExample
+    })
+  );
+  md.use(headingLevel({ initialLevel: 1 }));
+  md.use(
+    imageResources({
+      addResource: options.addResource
+    })
+  );
+  md.use(include(docs, env, included, options.handleSoftError));
+  md.use(table());
+  md.use(codeInline());
+  return {
+    render(doc, content) {
+      included.clear();
+      included.add(doc.id);
+      env.fileInfo = doc.fileInfo;
+      env.ids = /* @__PURE__ */ new Set();
+      const html = md.render(content, env);
+      return processInlineTags(
+        inlineTags,
+        doc,
+        docs,
+        html,
+        options.handleSoftError
+      );
+    }
+  };
+}
+
+exports.SoftError = SoftError;
+exports.createMarkdownRenderer = createMarkdownRenderer;
+exports.generateId = generateId;
+exports.getFingerprint = getFingerprint;
+exports.getOutputFilePath = getOutputFilePath;
+exports.normalizePath = normalizePath;

package/dist/{generator.d.ts → index.d.ts}

@@ -26,6 +26,13 @@ export declare interface CompileOptions {
     attributes: AttributeTable;
 }
 
+/**
+ * Tiny wrapper to provide type completion for IDE.
+ *
+ * @public
+ */
+export declare function defineSources(sources: SourceFiles[]): SourceFiles[];
+
 /**
  * @public
  */
@@ -332,7 +339,7 @@ export declare interface ProcessorContext {
      * @param id - A unique identifier for this block.
      * @param renderer - Describes how to render the block content.
      */
-    addTemplateBlock(container: string, id: string, renderer: TemplateBlockRenderer): void;
+    addTemplateBlock<T>(container: string, id: string, renderer: TemplateBlockRenderer<T>): void;
     /* Excluded from this release type: getAllTemplateBlocks */
     setTopNavigation(root: NavigationSection): void;
     setSideNavigation(root: NavigationSection): void;
@@ -444,9 +451,9 @@ export declare interface SourceFiles {
  *
  * @public
  */
-export declare type TemplateBlockRenderer = {
+export declare type TemplateBlockRenderer<T> = {
     filename: string;
-    data?: Record<string, unknown>;
+    data?: T;
 } | {
     render(): string;
 };
@@ -464,6 +471,26 @@ export declare interface TemplateData {
  */
 export declare function themeSelectProcessor(): Processor;
 
+/**
+ * Single entry for a topnav item.
+ *
+ * @public
+ */
+export declare interface TopnavEntry {
+    path: string;
+    title: string;
+}
+
+/**
+ * Processor to create a manual topnav:
+ *
+ * - Custom order.
+ * - Custom items.
+ *
+ * @public
+ */
+export declare function topnavProcessor(filename: string, title: string): Processor;
+
 /**
  * Represents a compiled vendor asset.
  *
@@ -555,7 +582,21 @@ export declare function versionBannerProcessor(message: string, container: strin
 export declare function versionProcessor(pkg: {
     name: string;
     version: string;
-}, container: string): Processor;
+    homepage: string;
+}, container: string, options?: VersionProcessorOptions): Processor;
+
+/**
+ * Options for {@link versionProcessor}.
+ *
+ * @public
+ */
+export declare interface VersionProcessorOptions {
+    readonly enabled: boolean;
+    readonly scm?: {
+        readonly commitUrlFormat: string;
+        readonly prUrlFormat: string;
+    };
+}
 
 /**
  * Generate API documentation from a Vue SFC.