@forsakringskassan/docs-generator 3.19.1 → 3.20.1

package/dist/{format-code.worker-DR9lHLhH.mjs → format-code.worker-NI_KIDrb.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-CLyw83WG.mjs';
+import { r as runAsWorker, f as format2, a as resolveConfig } from './vendor-GtJZoX7J.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-DR9lHLhH.mjs.map
+//# sourceMappingURL=format-code.worker-NI_KIDrb.mjs.map

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

@@ -1 +1 @@
-{"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;;"}
+{"version":3,"file":"format-code.worker-NI_KIDrb.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-CLyw83WG.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-GtJZoX7J.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 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 { 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-Bm-yRJ38.mjs';
 import { DocExcerpt } from '@microsoft/tsdoc';
 import pkg from '../package.json' with { type: "json" };
 import fs__default, { existsSync, readFileSync, copyFileSync } from 'node:fs';
@@ -828,7 +828,7 @@ function cmp(a, b) {
   return a[0].localeCompare(b[0]);
 }
 function findApiContainer(text, cb) {
-  const regex = /^:::\s*api(.*)\n([\s\S]+?):::\n/gm;
+  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();
@@ -908,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"),`,
@@ -938,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",
@@ -988,7 +1005,12 @@ 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 });
     }
   };