@forsakringskassan/docs-generator 3.9.0 → 3.10.1

package/dist/index.mjs

@@ -3,12 +3,12 @@ import { createRequire as $createRequire } from "node:module";
 const require = $createRequire(import.meta.url);
 
 import { ApiItemKind, ApiModel } from '@microsoft/api-extractor-model';
-import { t as ts, Z as Ze, M as MarkdownItCallable, s as strToU8, z as zlibSync, g as strFromU8, d as dedent, h as closest, i as distance, j as fm, k as isCI, m as moduleImporter, l as cliProgress, n as tinylr, w as watch, o as createInstance, p as fse, q as inter } from './vendor-DqIMfP3a.mjs';
+import { t as ts, Z as Ze, M as MarkdownItCallable, g as fm, s as strToU8, z as zlibSync, h as strFromU8, d as dedent, i as closest, j as distance, k as isCI, m as moduleImporter, l as cliProgress, n as tinylr, w as watch, o as createInstance, p as fse, q as inter } from './vendor-DPuGyhL4.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 parseImport, d as findTag, e as getOutputFilePath, j as htmlencode, k as filePath, c as createMarkdownRenderer, l as generateExample } from './create-markdown-renderer-D5BdKyep.mjs';
+import { g as generateId, f as formatCode, p as parseInfostring, a as getFingerprint, h as hasTag, b as parseImport, d as findTag, e as getOutputFilePath, i as isDocumentPage, j as findDocument, k as getDocumentBody, n as normalizePath, l as htmlencode, m as filePath, c as createMarkdownRenderer, o as generateExample } from './create-markdown-renderer-CXtEyRCU.mjs';
 import { DocExcerpt } from '@microsoft/tsdoc';
 import fs from 'node:fs/promises';
 import util, { promisify, styleText } from 'node:util';
@@ -19,7 +19,7 @@ import { parse, compileScript as compileScript$1, compileTemplate } from 'vue/co
 import { parse as parse$2 } from 'vue-docgen-api';
 import fs__default, { existsSync, readFileSync, copyFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { compileStringAsync, NodePackageImporter } from 'sass';
+import { compileAsync, NodePackageImporter } from 'sass';
 import { t as tsconfigPath } from './tsconfig-path-bG7G_cK8.mjs';
 import esbuild$1, { build } from 'esbuild';
 import { Worker } from 'node:worker_threads';
@@ -288,6 +288,15 @@ function slugify(value) {
   return value.toLowerCase().replaceAll("/", "--").replaceAll(/[^a-z]+/g, "-").replace(/^-+|-+$/, "");
 }
 
+function* takeWhile(it, predicate) {
+  for (const value of it) {
+    if (!predicate(value)) {
+      return;
+    }
+    yield value;
+  }
+}
+
 function isRelease() {
   try {
     const cmd = `git log -n1 --format=format:%s`;
@@ -299,6 +308,19 @@ function isRelease() {
   }
 }
 
+function* zip(a, b) {
+  const ia = Array.isArray(a) ? a.values() : a;
+  const ib = Array.isArray(b) ? b.values() : b;
+  for (; ; ) {
+    const va = ia.next();
+    const vb = ib.next();
+    if (va.done || vb.done) {
+      return;
+    }
+    yield [va.value, vb.value];
+  }
+}
+
 const available = {
   interface: ["default", "interface", "properties"]
 };
@@ -570,6 +592,23 @@ function apiExtractorProcessor(options = {}) {
   };
 }
 
+function cookieProcessor(options = {}) {
+  const { enabled = true } = options;
+  return {
+    after: "generate-docs",
+    name: "cookie-processor",
+    runtime: [{ src: "src/runtime/cookie.ts" }],
+    handler(context) {
+      if (!enabled) {
+        return;
+      }
+      context.addTemplateBlock("body:begin", "cookie-warning", {
+        filename: "partials/cookie-warning.html"
+      });
+    }
+  };
+}
+
 const documentAttributeKeys = [
   "title",
   "short-title",
@@ -586,97 +625,12 @@ const documentAttributeKeys = [
   "redirect_from"
 ];
 
-const md$6 = MarkdownItCallable();
-md$6.renderer.rules.fence = (tokens, idx, _options, rawEnv) => {
-  const { collected } = rawEnv;
-  const { content, info } = tokens[idx];
-  const { language, tags } = parseInfostring(info);
-  if (language === "import") {
-    return "";
-  }
-  const nameTag = tags.find((it) => it.startsWith("name="));
-  const name = nameTag ? slugify(nameTag.slice("name=".length)) : void 0;
-  collected.push({
-    name,
-    content,
-    language,
-    tags
-  });
-  return "";
-};
-function findExamples$1(doc) {
-  if (doc.format !== "markdown") {
-    return [];
-  }
-  const collected = [];
-  md$6.render(doc.body, { collected });
-  return collected;
-}
-function getSuffix(tags) {
-  const relevant = tags.filter((it) => ["nocompile", "nolint"].includes(it));
-  if (relevant.length > 0) {
-    return `-${relevant.join("-")}`;
-  }
-  return "";
-}
-function getExtension(lang) {
-  switch (lang) {
-    case "typescript":
-      return "ts";
-    case "javascript":
-      return "js";
-    default:
-      return lang;
-  }
-}
-function extractExamplesProcessor(options) {
-  const {
-    enabled = true,
-    outputFolder,
-    languages = ["javascript", "typescript", "css", "scss"]
-  } = options;
-  function isRelevant(example) {
-    return languages.includes(example.language);
-  }
-  return {
-    stage: "render",
-    name: "extract-examples-processor",
-    async handler(context) {
-      if (!enabled) {
-        return;
-      }
-      if (!outputFolder) {
-        throw new Error(
-          `"outputFolder" not set in "extractExamplesProcessor(..)"`
-        );
-      }
-      await fs.rm(outputFolder, { recursive: true, force: true });
-      const docs = context.docs.filter(isDocumentPage).filter(haveOutput);
-      let total = 0;
-      for (const doc of docs) {
-        const examples = findExamples$1(doc).filter(isRelevant);
-        if (examples.length === 0) {
-          continue;
-        }
-        const dir = normalizePath(outputFolder, doc.fileInfo.fullPath);
-        await fs.mkdir(dir, { recursive: true });
-        let n = 1;
-        for (const example of examples) {
-          const suffix = getSuffix(example.tags);
-          const extension = getExtension(example.language);
-          const filename = `example-${example.name ?? String(n++)}${suffix}.${extension}`;
-          const filePath = path.join(dir, filename);
-          await fs.writeFile(filePath, example.content, "utf8");
-          total++;
-        }
-      }
-      context.log(total, "examples extracted");
-    }
-  };
+function isDocumentPartial(doc) {
+  return doc.kind === "partial";
 }
 
-const md$5 = MarkdownItCallable();
-md$5.renderer.rules.fence = (tokens, idx, _options, env) => {
+const md$6 = MarkdownItCallable();
+md$6.renderer.rules.fence = (tokens, idx, _options, env) => {
   const { collected, exampleFileMatcher } = env;
   const { content, info, map } = tokens[idx];
   const { language: rawLanguage, tags } = parseInfostring(info);
@@ -714,13 +668,13 @@ function flattenOutline(outline) {
     ];
   });
 }
-function findExamples(context, doc) {
+function findExamples$1(context, doc) {
   const { exampleFileMatcher } = context;
   if (doc.format !== "markdown") {
     return [];
   }
   const collected = [];
-  md$5.render(doc.body, {
+  md$6.render(doc.body, {
     exampleFileMatcher,
     collected
   });
@@ -734,10 +688,11 @@ function manifestPageFromDocument(context, doc) {
     title: doc.attributes.title ?? doc.name,
     redirect: format === "redirect" ? body : null,
     outline: flattenOutline(doc.outline),
-    examples: findExamples(context, doc)
+    examples: findExamples$1(context, doc)
   };
 }
 
+const manifestState = /* @__PURE__ */ Symbol("manifest");
 function line(page) {
   if (page.redirect) {
     return `${page.path} -> ${page.redirect}`;
@@ -792,6 +747,7 @@ function manifestProcessor(options = {}) {
         return a.path.localeCompare(b.path);
       });
       const manifest = { pages };
+      context.setState(manifestState, manifest);
       if (markdown) {
         const content = normalize(renderMarkdown(manifest));
         await fs.mkdir(path__default.dirname(markdown), { recursive: true });
@@ -815,6 +771,285 @@ function manifestProcessor(options = {}) {
   };
 }
 
+async function copyFile(src, dst) {
+  await fs.mkdir(path__default.dirname(dst), { recursive: true });
+  await fs.cp(src, dst);
+}
+function equal(values) {
+  return values[0] === values[1];
+}
+function commonPath(a, b) {
+  const it = zip(a.split(path__default.sep), b.split(path__default.sep));
+  const common = Array.from(takeWhile(it, equal), (it2) => it2[0]);
+  return common.join(path__default.sep);
+}
+async function extractExamples(page, options) {
+  const { outputFolder } = options;
+  for (const example of page.examples) {
+    if (!example.src) {
+      continue;
+    }
+    const common = commonPath(
+      path__default.resolve(outputFolder),
+      path__default.resolve(example.src)
+    );
+    const subpath = path__default.relative(common, path__default.resolve(example.src));
+    await copyFile(example.src, path__default.join(outputFolder, "files", subpath));
+  }
+}
+function isMarkdown(doc) {
+  return doc.format === "markdown";
+}
+async function getFrontMatter(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  const { attributes } = fm(content);
+  delete attributes.redirect_from;
+  if (Object.keys(attributes).length === 0) {
+    return "";
+  }
+  return `---
+${JSON.stringify(attributes)}
+---
+
+`;
+}
+function cmp(a, b) {
+  return a[0].localeCompare(b[0]);
+}
+async function extractDocument(doc, docs, partials, options) {
+  const { outputFolder } = options;
+  const markdown = doc.body.replaceAll(
+    /^:::\s*api(.*)\n([\s\S]+?):::/gm,
+    (match, info, content2) => {
+      const needle = content2.trim();
+      const trimmedInfo = info.trim();
+      const tags = trimmedInfo ? trimmedInfo.split(/\s+/) : [];
+      const result = findDocument(docs, needle);
+      if (!result.document) {
+        return match;
+      }
+      const { document, kind, reference } = result;
+      if (!isDocumentPartial(document)) {
+        return match;
+      }
+      const body = getDocumentBody(document, tags, {
+        kind,
+        reference
+      });
+      const fingerprint = getFingerprint(body);
+      const id = `partial:${document.format}:${fingerprint}`;
+      partials.set(id, {
+        id,
+        format: document.format,
+        body
+      });
+      return `:::api
+${id}
+:::
+`;
+    }
+  );
+  const src = doc.fileInfo.fullPath;
+  const dst = path__default.join(outputFolder, "files", doc.fileInfo.fullPath);
+  const fm2 = await getFrontMatter(src);
+  const content = `${fm2}${markdown}`;
+  await fs.mkdir(path__default.dirname(dst), { recursive: true });
+  await fs.writeFile(dst, content, "utf8");
+}
+async function extractDocuments(docs, partials, options) {
+  const files = docs.filter(isDocumentPage).filter(isMarkdown).filter(haveOutput).map((doc) => extractDocument(doc, docs, partials, options));
+  await Promise.all(files);
+}
+async function extractPartials(partials, options) {
+  const { outputFolder } = options;
+  const dst = path__default.join(outputFolder, "partials.json");
+  const content = JSON.stringify(Array.from(partials.values()), null, 2);
+  await fs.mkdir(path__default.dirname(dst), { recursive: true });
+  await fs.writeFile(dst, content, "utf8");
+}
+async function extractLinks(docs, options) {
+  const { outputFolder } = options;
+  const links = /* @__PURE__ */ new Map();
+  const pages = docs.filter(isDocumentPage).filter(haveOutput);
+  for (const page of pages) {
+    const path2 = getOutputFilePath("", page.fileInfo);
+    links.set(page.id, path2);
+    if (!links.has(page.name)) {
+      links.set(page.name, path2);
+    }
+    for (const alias of page.alias) {
+      if (!links.has(alias)) {
+        links.set(alias, path2);
+      }
+    }
+  }
+  const sorted = Array.from(links).toSorted(cmp);
+  const entries = Object.fromEntries(sorted);
+  const content = JSON.stringify(entries, null, 2);
+  const dst = path__default.join(outputFolder, "links.json");
+  await fs.mkdir(path__default.dirname(dst), { recursive: true });
+  await fs.writeFile(dst, content, "utf8");
+}
+async function writeIndex(options) {
+  const { outputFolder } = options;
+  const dst = path__default.join(outputFolder, "index.mjs");
+  const lines = [
+    `import path from "node:path";`,
+    `import { frontMatterFileReader, partialFileReader } from "@forsakringskassan/docs-generator";`,
+    ``,
+    `export const basename = import.meta.dirname;`,
+    `export const sourceFiles = [`,
+    `    { `,
+    `        include: path.join(basename, "files/**/*.md"),`,
+    `        basename,`,
+    `        fileReader: frontMatterFileReader,`,
+    `    }`,
+    `    { `,
+    `        include: path.join(basename, "partials.json"),`,
+    `        basename,`,
+    `        fileReader: partialFileReader,`,
+    `    }`,
+    `];`
+  ];
+  await fs.writeFile(dst, lines.join("\n"), "utf8");
+}
+async function writeDts(options) {
+  const { outputFolder } = options;
+  const dst = path__default.join(outputFolder, "index.d.mts");
+  const lines = [
+    `import { SourceFiles } from "@forsakringskassan/docs-generator";`,
+    ``,
+    `export declare const basename: string;`,
+    `export declare const sourceFiles: SourceFiles[];`
+  ];
+  await fs.writeFile(dst, lines.join("\n"), "utf8");
+}
+function extractMarkdownProcessor(options) {
+  const { enabled = true, outputFolder } = options;
+  return {
+    after: "render",
+    name: "extract-markdown-processor",
+    async handler(context) {
+      if (!enabled) {
+        return;
+      }
+      if (!outputFolder) {
+        throw new Error(
+          `"outputFolder" not set in "extractMarkdownProcessor(..)"`
+        );
+      }
+      const manifest = context.getState(manifestState);
+      if (!manifest) {
+        throw new Error(
+          `"extractMarkdownProcessor()" requires "manifestProcess()"`
+        );
+      }
+      await fs.rm(outputFolder, { recursive: true, force: true });
+      await fs.mkdir(outputFolder, { recursive: true });
+      const partials = /* @__PURE__ */ new Map();
+      await extractDocuments(context.docs, partials, { outputFolder });
+      await extractPartials(partials, { outputFolder });
+      await extractLinks(context.docs, { outputFolder });
+      const { pages } = manifest;
+      const resources = pages.map((page) => {
+        return extractExamples(page, { outputFolder });
+      });
+      await Promise.all(resources);
+      await writeIndex({ outputFolder });
+      await writeDts({ outputFolder });
+    }
+  };
+}
+
+const md$5 = MarkdownItCallable();
+md$5.renderer.rules.fence = (tokens, idx, _options, rawEnv) => {
+  const { collected } = rawEnv;
+  const { content, info } = tokens[idx];
+  const { language, tags } = parseInfostring(info);
+  if (language === "import") {
+    return "";
+  }
+  const nameTag = tags.find((it) => it.startsWith("name="));
+  const name = nameTag ? slugify(nameTag.slice("name=".length)) : void 0;
+  collected.push({
+    name,
+    content,
+    language,
+    tags
+  });
+  return "";
+};
+function findExamples(doc) {
+  if (doc.format !== "markdown") {
+    return [];
+  }
+  const collected = [];
+  md$5.render(doc.body, { collected });
+  return collected;
+}
+function getSuffix(tags) {
+  const relevant = tags.filter((it) => ["nocompile", "nolint"].includes(it));
+  if (relevant.length > 0) {
+    return `-${relevant.join("-")}`;
+  }
+  return "";
+}
+function getExtension(lang) {
+  switch (lang) {
+    case "typescript":
+      return "ts";
+    case "javascript":
+      return "js";
+    default:
+      return lang;
+  }
+}
+function extractExamplesProcessor(options) {
+  const {
+    enabled = true,
+    outputFolder,
+    languages = ["javascript", "typescript", "css", "scss"]
+  } = options;
+  function isRelevant(example) {
+    return languages.includes(example.language);
+  }
+  return {
+    stage: "render",
+    name: "extract-examples-processor",
+    async handler(context) {
+      if (!enabled) {
+        return;
+      }
+      if (!outputFolder) {
+        throw new Error(
+          `"outputFolder" not set in "extractExamplesProcessor(..)"`
+        );
+      }
+      await fs.rm(outputFolder, { recursive: true, force: true });
+      const docs = context.docs.filter(isDocumentPage).filter(haveOutput);
+      let total = 0;
+      for (const doc of docs) {
+        const examples = findExamples(doc).filter(isRelevant);
+        if (examples.length === 0) {
+          continue;
+        }
+        const dir = normalizePath(outputFolder, doc.fileInfo.fullPath);
+        await fs.mkdir(dir, { recursive: true });
+        let n = 1;
+        for (const example of examples) {
+          const suffix = getSuffix(example.tags);
+          const extension = getExtension(example.language);
+          const filename = `example-${example.name ?? String(n++)}${suffix}.${extension}`;
+          const filePath = path.join(dir, filename);
+          await fs.writeFile(filePath, example.content, "utf8");
+          total++;
+        }
+      }
+      context.log(total, "examples extracted");
+    }
+  };
+}
+
 function normalizeOptions(options) {
   const defaults = {
     enabled: true,
@@ -1141,6 +1376,42 @@ function selectableVersionProcessor(pkg, container, options) {
   };
 }
 
+function sourceUrlProcessor(...args) {
+  const pkg = args.length === 2 ? args[0] : {};
+  const options = args.length === 2 ? args[1] : args[0];
+  const {
+    enabled = true,
+    sourceFiles = ["**/*"],
+    urlFormat,
+    componentFileExtension = "vue"
+  } = options;
+  const repository = getRepositoryUrl(pkg) ?? "";
+  const matcher = fileMatcher(sourceFiles);
+  return {
+    after: "generate-docs",
+    name: "source-url-processor",
+    async handler(context) {
+      if (!enabled) {
+        return;
+      }
+      const hash = await gitCommitHash("full") ?? "";
+      const short = await gitCommitHash("short") ?? "";
+      function componentSourceUrl(component) {
+        const { source, name } = component;
+        const filename = source ?? `${name}.${componentFileExtension}`;
+        const path = matcher(filename, "when generating source url");
+        return interpolate(urlFormat, {
+          path,
+          hash,
+          short,
+          repository
+        });
+      }
+      context.setTemplateData("componentSourceUrl", componentSourceUrl);
+    }
+  };
+}
+
 function isNavigationSection(node) {
   return "key" in node;
 }
@@ -1469,59 +1740,6 @@ function versionProcessor(pkg, container, options) {
   };
 }
 
-function sourceUrlProcessor(...args) {
-  const pkg = args.length === 2 ? args[0] : {};
-  const options = args.length === 2 ? args[1] : args[0];
-  const {
-    enabled = true,
-    sourceFiles = ["**/*"],
-    urlFormat,
-    componentFileExtension = "vue"
-  } = options;
-  const repository = getRepositoryUrl(pkg) ?? "";
-  const matcher = fileMatcher(sourceFiles);
-  return {
-    after: "generate-docs",
-    name: "source-url-processor",
-    async handler(context) {
-      if (!enabled) {
-        return;
-      }
-      const hash = await gitCommitHash("full") ?? "";
-      const short = await gitCommitHash("short") ?? "";
-      function componentSourceUrl(component) {
-        const { source, name } = component;
-        const filename = source ?? `${name}.${componentFileExtension}`;
-        const path = matcher(filename, "when generating source url");
-        return interpolate(urlFormat, {
-          path,
-          hash,
-          short,
-          repository
-        });
-      }
-      context.setTemplateData("componentSourceUrl", componentSourceUrl);
-    }
-  };
-}
-
-function cookieProcessor(options = {}) {
-  const { enabled = true } = options;
-  return {
-    after: "generate-docs",
-    name: "cookie-processor",
-    runtime: [{ src: "src/runtime/cookie.ts" }],
-    handler(context) {
-      if (!enabled) {
-        return;
-      }
-      context.addTemplateBlock("body:begin", "cookie-warning", {
-        filename: "partials/cookie-warning.html"
-      });
-    }
-  };
-}
-
 function generateIndex(entries) {
   const index = {
     terms: [],
@@ -2653,8 +2871,8 @@ async function partialFileReader(filePath) {
   return parseFile(filePath, content);
 }
 
-async function compileSassString(dst, style) {
-  const result = await compileStringAsync(style, {
+async function compileSassString(dst, filePath) {
+  const result = await compileAsync(filePath, {
     style: "expanded",
     importers: [new NodePackageImporter(), moduleImporter()]
   });
@@ -2665,8 +2883,8 @@ async function compileSassString(dst, style) {
 async function compileStyle(assetFolder, name, src) {
   try {
     const outfile = path.join("temp", `asset-${name}.css`);
-    const source = await fs.readFile(src, "utf8");
-    await compileSassString(outfile, source);
+    const filePath = typeof src === "string" ? src : fileURLToPath(src);
+    await compileSassString(outfile, filePath);
     const content = await fs.readFile(outfile, "utf8");
     const fingerprint = getFingerprint(content);
     const integrity = getIntegrity(content);
@@ -3790,6 +4008,7 @@ function createContext(options) {
     visible: true
   };
   const templateData = /* @__PURE__ */ new Map();
+  const stateData = /* @__PURE__ */ new Map();
   return {
     get docs() {
       return docs;
@@ -3856,6 +4075,15 @@ function createContext(options) {
     },
     setTemplateData(key, value) {
       templateData.set(key, value);
+    },
+    setState(key, value) {
+      stateData.set(key, value);
+    },
+    getState(key) {
+      if (!stateData.has(key)) {
+        return null;
+      }
+      return stateData.get(key);
     }
   };
 }
@@ -4135,5 +4363,5 @@ class Generator {
   }
 }
 
-export { Generator, apiExtractorProcessor, availableProcessors, cookieProcessor, defineSources, extractExamplesProcessor, frontMatterFileReader, htmlRedirectProcessor, isRelease, livereloadProcessor, manifestProcessor, matomoProcessor, motdProcessor, navigationFileReader, partialFileReader, playgroundProcessor, processorRuntimeName, redirectFileProcessor, searchProcessor, selectableVersionProcessor, sourceUrlProcessor, topnavProcessor, versionBannerProcessor, versionProcessor, vueFileReader };
+export { Generator, apiExtractorProcessor, availableProcessors, cookieProcessor, defineSources, extractExamplesProcessor, extractMarkdownProcessor, frontMatterFileReader, htmlRedirectProcessor, isRelease, livereloadProcessor, manifestProcessor, matomoProcessor, motdProcessor, navigationFileReader, partialFileReader, playgroundProcessor, processorRuntimeName, redirectFileProcessor, searchProcessor, selectableVersionProcessor, sourceUrlProcessor, topnavProcessor, versionBannerProcessor, versionProcessor, vueFileReader };
 //# sourceMappingURL=index.mjs.map