@forsakringskassan/docs-generator 2.42.0 → 2.43.0

package/dist/index.mjs

@@ -2,13 +2,15 @@ import { createRequire as $createRequire } from "node:module";
 
 const require = $createRequire(import.meta.url);
 
-import fs from 'node:fs/promises';
-import path from 'node:path/posix';
-import { t as ts, M as MarkdownIt, d as dedent, g as closest, h as distance, i as fm, j as isCI, Z as Ze, m as moduleImporter, k as cliProgress, l as tinylr, w as watch, n as createInstance, o as fse, p as inter } from './vendor-BoRn-ubH.mjs';
-import { g as generateId, p as parseInfostring, i as isDocumentPage, n as normalizePath, a as getFingerprint, h as hasTag, f as findTag, b as getOutputFilePath, d as htmlencode, e as filePath, c as createMarkdownRenderer, j as generateExample } from './create-markdown-renderer-DX0B9T-x.mjs';
+import { ApiItemKind, ApiModel } from '@microsoft/api-extractor-model';
+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-BImorfXU.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 { g as generateId, f as formatCode, p as parseInfostring, i as isDocumentPage, n as normalizePath, a as getFingerprint, h as hasTag, b as findTag, d as getOutputFilePath, e as htmlencode, j as filePath, c as createMarkdownRenderer, k as generateExample } from './create-markdown-renderer-CO5Te-tH.mjs';
+import { DocExcerpt } from '@microsoft/tsdoc';
+import fs from 'node:fs/promises';
 import util, { promisify } from 'node:util';
 import { codeFrameColumns } from '@babel/code-frame';
 import { parse as parse$1 } from '@babel/parser';
@@ -74,22 +76,6 @@ function matomoProcessor(options) {
   };
 }
 
-const documentAttributeKeys = [
-  "title",
-  "short-title",
-  "layout",
-  "name",
-  "alias",
-  "status",
-  "visible",
-  "include",
-  "component",
-  "href",
-  "search",
-  "sortorder",
-  "redirect_from"
-];
-
 function cacheKey$1(...args) {
   return JSON.stringify(args);
 }
@@ -252,6 +238,19 @@ function interpolate(value, data) {
   });
 }
 
+function naturalJoin(values, conjunction = "or") {
+  switch (values.length) {
+    case 0:
+      return "";
+    case 1:
+      return values[0];
+    case 2:
+      return `${values[0]} ${conjunction} ${values[1]}`;
+    default:
+      return `${values.slice(0, -1).join(", ")} ${conjunction} ${values.at(-1)}`;
+  }
+}
+
 function quote(text) {
   return String(text).replaceAll('"', """);
 }
@@ -300,6 +299,290 @@ function isRelease() {
   }
 }
 
+const available = {
+  interface: ["default", "interface", "properties"]
+};
+function getVariant(kind, tags) {
+  const variant = available[kind].find((it) => tags.includes(it));
+  return variant ?? "default";
+}
+
+function isDocumentedItem(item) {
+  return "tsdocComment" in item;
+}
+function documentation(node) {
+  if (node && isDocumentedItem(node)) {
+    const { tsdocComment } = node;
+    return renderNode(tsdocComment?.summarySection).trim();
+  } else {
+    return void 0;
+  }
+}
+function documentationComment(node) {
+  const doc = documentation(node);
+  if (doc === void 0) {
+    return void 0;
+  }
+  if (!doc) {
+    return "";
+  }
+  const lines = doc.split("\n");
+  const commentLines = lines.map((line) => line ? ` * ${line}` : ` *`);
+  return ["/**", ...commentLines, " */"].join("\n");
+}
+function renderNode(docNode) {
+  let result = "";
+  if (docNode) {
+    if (docNode instanceof DocExcerpt) {
+      result += docNode.content.toString();
+    }
+    for (const childNode of docNode.getChildNodes()) {
+      result += renderNode(childNode);
+    }
+  }
+  return formatMarkdownLists(result);
+}
+function formatMarkdownLists(text) {
+  return text.replaceAll(/(\S)[^\S\n]+([*-])[^\S\n]+/g, "$1\n$2 ");
+}
+
+function isApiInterface(item) {
+  return item.kind === ApiItemKind.Interface;
+}
+function findMemberByName(name, pkg) {
+  for (const entryPoint of pkg.entryPoints) {
+    for (const member of entryPoint.findMembersByName(name)) {
+      if (isApiInterface(member)) {
+        return member;
+      }
+    }
+  }
+  return void 0;
+}
+function getNameFromExcerpt(excerpt) {
+  const [token] = excerpt.tokens.slice(
+    excerpt.tokenRange.startIndex,
+    excerpt.tokenRange.endIndex
+  );
+  return token.text;
+}
+function getInheritance(item) {
+  const pkg = item.getAssociatedPackage();
+  if (!pkg) {
+    return [];
+  }
+  const hierarchy = [];
+  const visited = /* @__PURE__ */ new Set();
+  function traverseParents(current, pkg2) {
+    if (visited.has(current.name)) {
+      return;
+    }
+    visited.add(current.name);
+    for (const { excerpt } of current.extendsTypes) {
+      const name = getNameFromExcerpt(excerpt);
+      const parentInterface = findMemberByName(name, pkg2);
+      if (parentInterface) {
+        traverseParents(parentInterface, pkg2);
+        hierarchy.push(parentInterface);
+      }
+    }
+  }
+  traverseParents(item, pkg);
+  hierarchy.push(item);
+  return hierarchy;
+}
+function collectMembers(item, inherit) {
+  if (!inherit) {
+    return item.members.filter(isSupported);
+  }
+  const hierarchy = getInheritance(item);
+  const members = /* @__PURE__ */ new Map();
+  for (const iface of hierarchy) {
+    for (const member of iface.members.filter(isSupported)) {
+      members.set(member.name, member);
+    }
+  }
+  return [...members.values()];
+}
+function isSupported(item) {
+  return [
+    ApiItemKind.PropertySignature,
+    ApiItemKind.MethodSignature
+  ].includes(item.kind);
+}
+function renderCode(item, members, options) {
+  const inherit = options.inherit ?? false;
+  const renderedMembers = members.map((it) => {
+    const summary = documentationComment(it);
+    const comment = summary ? `
+${summary}` : "";
+    return `${comment}
+${it.excerpt.text}`;
+  });
+  const header = item.excerpt.text.replace(/^export /, "").trimEnd();
+  const extendsIndex = header.indexOf(" extends ");
+  const declaration = inherit && extendsIndex !== -1 ? header.slice(0, extendsIndex) : header;
+  const source = `${declaration} { ${renderedMembers.join("")} }`;
+  return [
+    "```ts nocompile nolint",
+    formatCode(source, "docs/api-interface.ts"),
+    "```"
+  ].join("\n");
+}
+function renderProperties(members) {
+  return members.map((it) => {
+    const optional = it.isOptional ? " {@optional}" : "";
+    const summary = documentation(it);
+    const lines = summary ? summary.split("\n").map((it2, i) => {
+      if (it2.trim() === "") {
+        return "\n";
+      }
+      const prefix = i === 0 ? ": " : "    ";
+      return `${prefix}${it2.trim()}
+`;
+    }) : [": ‐\n"];
+    return [`\`${it.excerpt.text}\`${optional}
+`, ...lines].join("");
+  }).join("\n");
+}
+function renderInterface() {
+  return {
+    default(item, options) {
+      const inherit = options.inherit ?? false;
+      return renderCode(item, collectMembers(item, inherit), options);
+    },
+    interface(item, options) {
+      const inherit = options.inherit ?? false;
+      return renderCode(item, collectMembers(item, inherit), options);
+    },
+    properties(item, options) {
+      const inherit = options.inherit ?? true;
+      return renderProperties(collectMembers(item, inherit));
+    }
+  };
+}
+
+function getFilenames(patterns) {
+  return Ze(patterns, { posix: true });
+}
+function pluralize(text, array) {
+  const s = array.length !== 1 ? "s" : "";
+  return `${text}${s}`;
+}
+function loadedMessage(kind, array) {
+  return [array.length, pluralize(kind, array), "loaded"];
+}
+function getInheritOption(tags) {
+  if (tags.includes("inherit")) {
+    return true;
+  }
+  if (tags.includes("noinherit")) {
+    return false;
+  }
+  return void 0;
+}
+function walk(root, fns) {
+  const t = fns;
+  for (const member of root.members) {
+    const fn = t[member.kind];
+    if (fn) {
+      fn(member);
+    }
+    walk(member, fns);
+  }
+}
+function isAmbigious(name, names) {
+  const found = names.get(name);
+  return found.length > 1 ? found : null;
+}
+function createPartial(options) {
+  const { id, name, fullPath, names, render } = options;
+  return {
+    kind: "partial",
+    id,
+    alias: [],
+    name: `interface:${name}`,
+    body(tags, reference) {
+      if (reference.kind === "name") {
+        const ambigious = isAmbigious(name, names);
+        if (ambigious) {
+          const quoted = ambigious.map((it) => `"${it}"`);
+          const ids = naturalJoin(quoted, "and");
+          throw new Error(
+            `Ambiguous name "${name}", found ${ambigious.length} interfaces matching this name: ${ids}`
+          );
+        }
+      }
+      return render(tags);
+    },
+    format: "markdown",
+    fileInfo: {
+      fullPath
+    }
+  };
+}
+function apiExtractorProcessor(options = {}) {
+  const { apiModel: patterns = [], enabled = true } = options;
+  return {
+    name: "apiExtractorProcessor",
+    after: "generate-docs",
+    async handler(context) {
+      if (!enabled) {
+        return;
+      }
+      const symbols = {
+        interface: []
+      };
+      for (const filename of await getFilenames(patterns)) {
+        const apiModel = new ApiModel();
+        const apiPackage = apiModel.loadPackage(filename);
+        walk(apiPackage, {
+          [ApiItemKind.Interface](item) {
+            symbols.interface.push(item);
+          }
+        });
+      }
+      const interfaceRenderer = renderInterface();
+      const seenInterfaces = /* @__PURE__ */ new Map();
+      for (const item of symbols.interface) {
+        const id = item.canonicalReference.toString();
+        const found = seenInterfaces.get(item.name) ?? [];
+        seenInterfaces.set(item.name, [...found, id]);
+        const partial = createPartial({
+          id,
+          name: item.name,
+          names: seenInterfaces,
+          fullPath: item.sourceLocation.fileUrl,
+          render(tags) {
+            const variant = getVariant("interface", tags);
+            return interfaceRenderer[variant](item, {
+              inherit: getInheritOption(tags)
+            });
+          }
+        });
+        context.addDocument(partial);
+      }
+      context.log(...loadedMessage("interface", symbols.interface));
+    }
+  };
+}
+
+const documentAttributeKeys = [
+  "title",
+  "short-title",
+  "layout",
+  "name",
+  "alias",
+  "status",
+  "visible",
+  "include",
+  "component",
+  "href",
+  "search",
+  "sortorder",
+  "redirect_from"
+];
+
 const md$6 = MarkdownIt();
 md$6.renderer.rules.fence = (tokens, idx, _options, collected) => {
   const { content, info } = tokens[idx];
@@ -3594,5 +3877,5 @@ function searchProcessor() {
   };
 }
 
-export { Generator, availableProcessors, cookieProcessor, defineSources, extractExamplesProcessor, frontMatterFileReader, htmlRedirectProcessor, isRelease, livereloadProcessor, manifestProcessor, matomoProcessor, motdProcessor, navigationFileReader, processorRuntimeName, redirectFileProcessor, searchProcessor, selectableVersionProcessor, sourceUrlProcessor, topnavProcessor, versionBannerProcessor, versionProcessor, vueFileReader };
+export { Generator, apiExtractorProcessor, availableProcessors, cookieProcessor, defineSources, extractExamplesProcessor, frontMatterFileReader, htmlRedirectProcessor, isRelease, livereloadProcessor, manifestProcessor, matomoProcessor, motdProcessor, navigationFileReader, processorRuntimeName, redirectFileProcessor, searchProcessor, selectableVersionProcessor, sourceUrlProcessor, topnavProcessor, versionBannerProcessor, versionProcessor, vueFileReader };
 //# sourceMappingURL=index.mjs.map