@forsakringskassan/docs-generator 3.19.0 → 3.20.0

package/dist/{format-code.worker-CFQ372Nb.mjs → format-code.worker-DR9lHLhH.mjs}

@@ -2,7 +2,7 @@ import { createRequire as $createRequire } from "node:module";
 
 const require = $createRequire(import.meta.url);
 
-import { r as runAsWorker, f as format2, a as resolveConfig } from './vendor-i-8GIz5x.mjs';
+import { r as runAsWorker, f as format2, a as resolveConfig } from './vendor-CLyw83WG.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-CFQ372Nb.mjs.map
+//# sourceMappingURL=format-code.worker-DR9lHLhH.mjs.map

package/dist/{format-code.worker-CFQ372Nb.mjs.map → format-code.worker-DR9lHLhH.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"format-code.worker-CFQ372Nb.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\n/* eslint-disable-next-line unicorn/no-top-level-side-effects -- required for worker to function */\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;AAGA,WAAA,CAAY,UAAU,CAAA;;"}
+{"version":3,"file":"format-code.worker-DR9lHLhH.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\n/* eslint-disable-next-line unicorn/no-top-level-side-effects -- required for worker to function */\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;AAGA,WAAA,CAAY,UAAU,CAAA;;"}

package/dist/index.d.mts

@@ -184,6 +184,18 @@ export declare interface DocumentPartialReference {
     reference: string;
 }
 
+/**
+ * Serializable metadata exported with extracted documentation.
+ *
+ * This interface can be augmented to describe application-specific metadata.
+ *
+ * @public
+ * @since %version%
+ */
+export declare interface ExtractedDocsMetadata {
+    [key: string]: unknown;
+}
+
 /**
  * Type representing the exported docs module when extracting markdown
  * documents.
@@ -198,12 +210,14 @@ export declare interface DocumentPartialReference {
  */
 export declare interface ExtractedDocsModule {
     readonly generatorVersion: string;
+    readonly version: string | null;
+    readonly metadata: ExtractedDocsMetadata | null;
     readonly basePath: string;
     readonly exampleFolders: string[];
     readonly filesPath: string;
     readonly partialsPath: string;
     readonly linksPath: string;
-    sourceFiles(src: Partial<SourceFiles>): SourceFiles[];
+    sourceFiles(src?: Partial<SourceFiles>): SourceFiles[];
 }
 
 /**
@@ -245,6 +259,17 @@ export declare interface ExtractMarkdownOptions extends ProcessorOptions {
      * Folder to write docs to.
      */
     outputFolder: string;
+    /**
+     * Version written to the `version` field of the generated `index.mjs`.
+     */
+    version?: string;
+    /**
+     * Callback providing serializable metadata for the generated `index.mjs`.
+     *
+     * Called once per extraction and awaited. Missing callbacks and nullish
+     * results are exported as `null`.
+     */
+    metadata?: () => ExtractedDocsMetadata | undefined | null | Promise<ExtractedDocsMetadata | undefined | null>;
 }
 
 /**

package/dist/index.mjs

@@ -3,13 +3,13 @@ import { createRequire as $createRequire } from "node:module";
 const require = $createRequire(import.meta.url);
 
 import { ApiItemKind, ApiModel } from '@microsoft/api-extractor-model';
-import { 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, t as tinylr, w as watch, n as createInstance, o as fse, p as inter } from './vendor-i-8GIz5x.mjs';
+import { 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, t as tinylr, w as watch, n as createInstance, o as fse, p as inter } from './vendor-CLyw83WG.mjs';
 import path__default from 'node:path';
 import fs from 'node:fs/promises';
 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 parseImport, a as getFingerprint, b as parseInfostring, h as hasTag, d as findTag, e as getOutputFilePath, i as isDocumentPage, j as findDocument, k as getDocumentBody, n as normalizePath, l as htmlencode, c as createMarkdownRenderer } from './create-markdown-renderer-DrDHT9bZ.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, c as createMarkdownRenderer } from './create-markdown-renderer-DSov_Gkx.mjs';
 import { DocExcerpt } from '@microsoft/tsdoc';
 import pkg from '../package.json' with { type: "json" };
 import fs__default, { existsSync, readFileSync, copyFileSync } from 'node:fs';
@@ -640,108 +640,6 @@ function isDocumentPartial(doc) {
   return doc.kind === "partial";
 }
 
-function getExampleName(filename) {
-  return path__default.parse(filename).name;
-}
-
-const vueMajor = Number(version.split(".", 2)[0]);
-function vueGenerator() {
-  switch (vueMajor) {
-    case 2:
-      throw new Error(
-        "Vue 2 is no longer supported, upgrade to Vue 3 or downgrade docs-generator"
-      );
-    case 3:
-      return generateCode;
-  }
-}
-function generateExample(options) {
-  const { language, fileMatcher } = options;
-  if (language === "import") {
-    const parsed = parseImport(options.source);
-    const filename = fileMatcher(parsed.filename, "when importing example");
-    const language2 = parsed.extension;
-    const comments = parsed.comments;
-    const content = fs__default.readFileSync(filename, "utf8");
-    const example = generateExample({
-      ...options,
-      source: content,
-      language: language2,
-      filename
-    });
-    return { ...example, comments };
-  }
-  switch (language) {
-    case "vue":
-      return generateVueExample(options);
-    case "html":
-      return generateStaticExample(options);
-    default:
-      return generateStaticExample(options);
-  }
-}
-function generateVueExample(options) {
-  const { filename, source, parent, setupPath, tags } = options;
-  const fn = vueGenerator();
-  const slug = getExampleName(filename);
-  const fingerprint = getFingerprint(source);
-  const { markup, sourcecode, output } = fn({
-    filename,
-    slug,
-    fingerprint,
-    code: source,
-    setupPath
-  });
-  if (output) {
-    return {
-      source,
-      language: options.language,
-      comments: [],
-      tags,
-      markup,
-      output,
-      runtime: true,
-      task: {
-        outputFile: output,
-        sourcecode,
-        sourceFile: filename,
-        parent
-      }
-    };
-  }
-  return {
-    source: sourcecode,
-    language: "plaintext",
-    comments: [],
-    tags,
-    markup,
-    output: null,
-    runtime: true,
-    task: null
-  };
-}
-function generateStaticExample(options) {
-  const { filename, source, language, tags } = options;
-  const slug = getExampleName(filename);
-  const fingerprint = 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: runtime ? asset : null,
-    runtime,
-    task: null
-  };
-}
-
-const url = new URL("./worker--TrTGmqL.mjs", import.meta.url);
-const filePath = fileURLToPath(url);
-
 const md$6 = MarkdownItCallable();
 md$6.renderer.rules.fence = (tokens, idx, _options, env) => {
   const { collected, exampleFileMatcher } = env;
@@ -929,39 +827,46 @@ ${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
+function findApiContainer(text, cb) {
+  const regex = /^:::[ \t]*api(?=[ \t]|\r?\n)([^\n]*)\n([\s\S]+?):::\n/gm;
+  return text.replaceAll(regex, (match, info, rawContent) => {
+    const content = rawContent.trim();
+    const trimmedInfo = info.trim();
+    const tags = trimmedInfo ? trimmedInfo.split(/\s+/) : [];
+    return cb({ match, tags, content });
+  });
+}
+function onApiContainer(docs, partials, container) {
+  const { match, tags, content } = container;
+  const result = findDocument(docs, content);
+  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}
 :::
 `;
-    }
-  );
+}
+async function extractDocument(doc, docs, partials, options) {
+  const { outputFolder } = options;
+  const markdown = findApiContainer(doc.body, (container) => {
+    return onApiContainer(docs, partials, container);
+  });
   const src = doc.fileInfo.fullPath;
   const dst = path__default.join(outputFolder, "files", doc.fileInfo.fullPath);
   const fm2 = await getFrontMatter(src);
@@ -1003,21 +908,22 @@ async function extractLinks(docs, options) {
   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 = [
+function generateIndex$1(options) {
+  const { generatorVersion, version, metadata = null } = options;
+  return [
     `import path from "node:path";`,
     `import { frontMatterFileReader, partialFileReader } from "@forsakringskassan/docs-generator";`,
     ``,
-    `export const generatorVersion = "${pkg.version}";`,
+    `export const generatorVersion = ${JSON.stringify(generatorVersion)};`,
+    `export const version = ${JSON.stringify(version)};`,
+    `export const metadata = ${JSON.stringify(metadata)};`,
     `export const basePath = import.meta.dirname;`,
     `export const exampleFolders = [path.join(basePath, "files")];`,
     `export const filesPath = path.join(basePath, "files");`,
     `export const partialsPath = [path.join(basePath, "partials.json")];`,
     `export const linksPath = [path.join(basePath, "links.json")];`,
     ``,
-    `export function sourceFiles(src) {`,
+    `export function sourceFiles(src = {}) {`,
     `    return [`,
     `        { `,
     `            include: path.join(filesPath, "**/*.md"),`,
@@ -1033,27 +939,43 @@ async function writeIndex(options) {
     `    ];`,
     `}`
   ];
+}
+async function writeIndex(options) {
+  const { outputFolder, version, metadata } = options;
+  const dst = path__default.join(outputFolder, "index.mjs");
+  const lines = generateIndex$1({
+    generatorVersion: pkg.version,
+    version,
+    metadata
+  });
   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";`,
+    `import { ExtractedDocsMetadata, SourceFiles } from "@forsakringskassan/docs-generator";`,
     ``,
     `export declare const generatorVersion: string;`,
+    `export declare const version: string | null;`,
+    `export declare const metadata: ExtractedDocsMetadata | null;`,
     `export declare const basePath: string;`,
     `export declare const exampleFolders: string[];`,
     `export declare const filesPath: string;`,
     `export declare const partialsPath: string;`,
     `export declare const linksPath: string;`,
     ``,
-    `export declare function sourceFiles(src: Partial<SourceFiles>): SourceFiles[];`
+    `export declare function sourceFiles(this: void, src?: Partial<SourceFiles>): SourceFiles[];`
   ];
   await fs.writeFile(dst, lines.join("\n"), "utf8");
 }
 function extractMarkdownProcessor(options) {
-  const { enabled = true, outputFolder } = options;
+  const {
+    enabled = true,
+    outputFolder,
+    version = null,
+    metadata: metadataFn
+  } = options;
   return {
     after: "render",
     name: "extract-markdown-processor",
@@ -1083,12 +1005,119 @@ function extractMarkdownProcessor(options) {
         return extractExamples(page, { outputFolder });
       });
       await Promise.all(resources);
-      await writeIndex({ outputFolder });
+      const metadata = await metadataFn?.() ?? null;
+      await writeIndex({
+        outputFolder,
+        version,
+        metadata
+      });
       await writeDts({ outputFolder });
     }
   };
 }
 
+function getExampleName(filename) {
+  return path__default.parse(filename).name;
+}
+
+const vueMajor = Number(version.split(".", 2)[0]);
+function vueGenerator() {
+  switch (vueMajor) {
+    case 2:
+      throw new Error(
+        "Vue 2 is no longer supported, upgrade to Vue 3 or downgrade docs-generator"
+      );
+    case 3:
+      return generateCode;
+  }
+}
+function generateExample(options) {
+  const { language, fileMatcher } = options;
+  if (language === "import") {
+    const parsed = parseImport(options.source);
+    const filename = fileMatcher(parsed.filename, "when importing example");
+    const language2 = parsed.extension;
+    const comments = parsed.comments;
+    const content = fs__default.readFileSync(filename, "utf8");
+    const example = generateExample({
+      ...options,
+      source: content,
+      language: language2,
+      filename
+    });
+    return { ...example, comments };
+  }
+  switch (language) {
+    case "vue":
+      return generateVueExample(options);
+    case "html":
+      return generateStaticExample(options);
+    default:
+      return generateStaticExample(options);
+  }
+}
+function generateVueExample(options) {
+  const { filename, source, parent, setupPath, tags } = options;
+  const fn = vueGenerator();
+  const slug = getExampleName(filename);
+  const fingerprint = getFingerprint(source);
+  const { markup, sourcecode, output } = fn({
+    filename,
+    slug,
+    fingerprint,
+    code: source,
+    setupPath
+  });
+  if (output) {
+    return {
+      source,
+      language: options.language,
+      comments: [],
+      tags,
+      markup,
+      output,
+      runtime: true,
+      task: {
+        outputFile: output,
+        sourcecode,
+        sourceFile: filename,
+        parent
+      }
+    };
+  }
+  return {
+    source: sourcecode,
+    language: "plaintext",
+    comments: [],
+    tags,
+    markup,
+    output: null,
+    runtime: true,
+    task: null
+  };
+}
+function generateStaticExample(options) {
+  const { filename, source, language, tags } = options;
+  const slug = getExampleName(filename);
+  const fingerprint = 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: runtime ? asset : null,
+    runtime,
+    task: null
+  };
+}
+
+const url = new URL("./worker-DfUDllYf.mjs", import.meta.url);
+const filePath = fileURLToPath(url);
+
 const md$5 = MarkdownItCallable();
 md$5.renderer.rules.fence = (tokens, idx, _options, rawEnv) => {
   const { collected } = rawEnv;
@@ -2138,6 +2167,13 @@ function getComponent(attrs) {
   }
   return toArray$1(attrs.component).map(normalizeComponent);
 }
+function normalizeBody(text) {
+  text = text.replaceAll("\r\n", "\n");
+  if (!text.endsWith("\n")) {
+    text += "\n";
+  }
+  return text;
+}
 function parseFile$2(filePath, basePath, content) {
   const relative = basePath ? path__default.relative(basePath, normalizePath(filePath)) : normalizePath(filePath);
   const parsed = path__default.parse(relative);
@@ -2169,7 +2205,7 @@ function parseFile$2(filePath, basePath, content) {
       },
       sortorder: attributes.sortorder ?? Infinity
     },
-    body: blocks.body,
+    body: normalizeBody(blocks.body),
     outline,
     format: "markdown",
     tags: [],