@kubb/plugin-redoc 5.0.0-beta.22 → 5.0.0-beta.25

package/dist/index.cjs

@@ -52,11 +52,16 @@ function trimExtName(text) {
 }
 //#endregion
 //#region package.json
-var version = "5.0.0-beta.22";
+var version = "5.0.0-beta.25";
 //#endregion
 //#region src/redoc.tsx
 const __filename$1 = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
 const __dirname$1 = node_path.default.dirname(__filename$1);
+/**
+* Renders a self-contained Redoc HTML page for an OpenAPI document. The page
+* embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
+* the generated file works without further build steps.
+*/
 async function getPageHTML(api, { title, disableGoogleFont, templateOptions } = {}) {
 	const templateFileName = node_path.default.join(__dirname$1, "../static/redoc.hbs");
 	return handlebars.default.compile(node_fs.default.readFileSync(templateFileName).toString())({
@@ -77,7 +82,30 @@ async function getPageHTML(api, { title, disableGoogleFont, templateOptions } =
 }
 //#endregion
 //#region src/plugin.ts
+/**
+* Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+* cross-plugin dependency references.
+*/
 const pluginRedocName = "plugin-redoc";
+/**
+* Generates a self-contained static HTML documentation page from your OpenAPI
+* spec using Redoc. The file is regenerated on every Kubb build, so the docs
+* stay in lockstep with the spec the rest of your code is generated from.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { pluginRedoc } from '@kubb/plugin-redoc'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginRedoc({ output: { path: 'docs.html' } }),
+*   ],
+* })
+* ```
+*/
 const pluginRedoc = (0, _kubb_core.definePlugin)((options) => {
 	const { output = { path: "docs.html" } } = options;
 	return {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["__filename","__dirname","path","pkg","fs","adapterOasName","path","ast"],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\nconst __filename = fileURLToPath(import.meta.url)\nconst __dirname = path.dirname(__filename)\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(__dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,IAAI;CACtC,IAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,SAAS,EAC/C,OAAO,KAAK,MAAM,GAAG,SAAS;CAEhC,OAAO;;;;;;;AE5DT,MAAMA,gBAAAA,GAAAA,SAAAA,eAAAA,QAAAA,MAAAA,CAAAA,cAAAA,WAAAA,CAAAA,KAA2C;AACjD,MAAMC,cAAYC,UAAAA,QAAK,QAAQF,aAAW;AAQ1C,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,EAAE,EAAE;CACnI,MAAM,mBAAmBE,UAAAA,QAAK,KAAKD,aAAW,sBAAsB;CAEpE,OADiBE,WAAAA,QAAI,QAAQC,QAAAA,QAAG,aAAa,iBAAiB,CAAC,UAAU,CAC1D,CAAC;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC;;;;;;EAM3C;EACA;EACD,CAAC;;;;ACtBJ,MAAa,kBAAkB;AAE/B,MAAa,eAAA,GAAA,WAAA,eAAyC,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,KAAK;CAE3C,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,KAAK;IAC9B,SAAS,EAAE;IACX,UAAU,EAAE;IACb,CAAC;GAEF,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAASC,kBAAAA,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,uIACrB;GAGH,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,yHACrB;GAGH,MAAM,OAAOC,YAAAA,QAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,KAAK;GAClE,MAAM,WAAW,MAAM,YAAY,SAAS;GAE5C,IAAI,WAAW;IACb,UAAU;IACV,MAAMA,YAAAA,QAAK,QAAQ,MAAM,OAAO,QAAQ,cAAc;IACtD,SAAS,CACPC,WAAAA,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAACA,WAAAA,IAAI,WAAW,SAAS,CAAC;KAClC,CAAC,CACH;IACF,CAAC;KAEL;EACF;EACD"}
+{"version":3,"file":"index.cjs","names":["__filename","__dirname","path","pkg","fs","adapterOasName","path","ast"],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\nconst __filename = fileURLToPath(import.meta.url)\nconst __dirname = path.dirname(__filename)\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\n/**\n * Renders a self-contained Redoc HTML page for an OpenAPI document. The page\n * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so\n * the generated file works without further build steps.\n */\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(__dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and\n * cross-plugin dependency references.\n */\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\n/**\n * Generates a self-contained static HTML documentation page from your OpenAPI\n * spec using Redoc. The file is regenerated on every Kubb build, so the docs\n * stay in lockstep with the spec the rest of your code is generated from.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { pluginRedoc } from '@kubb/plugin-redoc'\n *\n * export default defineConfig({\n *   input: { path: './petStore.yaml' },\n *   output: { path: './src/gen' },\n *   plugins: [\n *     pluginRedoc({ output: { path: 'docs.html' } }),\n *   ],\n * })\n * ```\n */\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,IAAI;CACtC,IAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,SAAS,EAC/C,OAAO,KAAK,MAAM,GAAG,SAAS;CAEhC,OAAO;;;;;;;AE5DT,MAAMA,gBAAAA,GAAAA,SAAAA,eAAAA,QAAAA,MAAAA,CAAAA,cAAAA,WAAAA,CAAAA,KAA2C;AACjD,MAAMC,cAAYC,UAAAA,QAAK,QAAQF,aAAW;;;;;;AAa1C,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,EAAE,EAAE;CACnI,MAAM,mBAAmBE,UAAAA,QAAK,KAAKD,aAAW,sBAAsB;CAEpE,OADiBE,WAAAA,QAAI,QAAQC,QAAAA,QAAG,aAAa,iBAAiB,CAAC,UAAU,CAC1D,CAAC;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC;;;;;;EAM3C;EACA;EACD,CAAC;;;;;;;;ACvBJ,MAAa,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqB/B,MAAa,eAAA,GAAA,WAAA,eAAyC,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,KAAK;CAE3C,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,KAAK;IAC9B,SAAS,EAAE;IACX,UAAU,EAAE;IACb,CAAC;GAEF,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAASC,kBAAAA,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,uIACrB;GAGH,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,yHACrB;GAGH,MAAM,OAAOC,YAAAA,QAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,KAAK;GAClE,MAAM,WAAW,MAAM,YAAY,SAAS;GAE5C,IAAI,WAAW;IACb,UAAU;IACV,MAAMA,YAAAA,QAAK,QAAQ,MAAM,OAAO,QAAQ,cAAc;IACtD,SAAS,CACPC,WAAAA,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAACA,WAAAA,IAAI,WAAW,SAAS,CAAC;KAClC,CAAC,CACH;IACF,CAAC;KAEL;EACF;EACD"}

package/dist/index.d.ts

@@ -4,9 +4,14 @@ import { Exclude, Include, Output, Override, PluginFactoryOptions } from "@kubb/
 
 //#region src/types.d.ts
 type Options = {
+  /**
+   * Output location of the generated Redoc HTML file. The path is resolved
+   * against the global `output.path` set on `defineConfig`.
+   */
   output?: {
     /**
-     * Output path for the generated HTML documentation.
+     * File path of the generated HTML, relative to the global `output.path`.
+     * Unlike most plugins, this points at a single file rather than a directory.
      *
      * @default 'docs.html'
      */
@@ -30,7 +35,30 @@ declare global {
 }
 //#endregion
 //#region src/plugin.d.ts
+/**
+ * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+ * cross-plugin dependency references.
+ */
 declare const pluginRedocName = "plugin-redoc";
+/**
+ * Generates a self-contained static HTML documentation page from your OpenAPI
+ * spec using Redoc. The file is regenerated on every Kubb build, so the docs
+ * stay in lockstep with the spec the rest of your code is generated from.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginRedoc } from '@kubb/plugin-redoc'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginRedoc({ output: { path: 'docs.html' } }),
+ *   ],
+ * })
+ * ```
+ */
 declare const pluginRedoc: (options?: Options | undefined) => _$_kubb_core0.Plugin<PluginRedoc>;
 //#endregion
 export { type PluginRedoc, pluginRedoc as default, pluginRedoc, pluginRedocName };

package/dist/index.js

@@ -23,11 +23,16 @@ function trimExtName(text) {
 }
 //#endregion
 //#region package.json
-var version = "5.0.0-beta.22";
+var version = "5.0.0-beta.25";
 //#endregion
 //#region src/redoc.tsx
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+/**
+* Renders a self-contained Redoc HTML page for an OpenAPI document. The page
+* embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
+* the generated file works without further build steps.
+*/
 async function getPageHTML(api, { title, disableGoogleFont, templateOptions } = {}) {
 	const templateFileName = path.join(__dirname, "../static/redoc.hbs");
 	return pkg.compile(fs.readFileSync(templateFileName).toString())({
@@ -48,7 +53,30 @@ async function getPageHTML(api, { title, disableGoogleFont, templateOptions } =
 }
 //#endregion
 //#region src/plugin.ts
+/**
+* Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+* cross-plugin dependency references.
+*/
 const pluginRedocName = "plugin-redoc";
+/**
+* Generates a self-contained static HTML documentation page from your OpenAPI
+* spec using Redoc. The file is regenerated on every Kubb build, so the docs
+* stay in lockstep with the spec the rest of your code is generated from.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { pluginRedoc } from '@kubb/plugin-redoc'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginRedoc({ output: { path: 'docs.html' } }),
+*   ],
+* })
+* ```
+*/
 const pluginRedoc = definePlugin((options) => {
 	const { output = { path: "docs.html" } } = options;
 	return {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\nconst __filename = fileURLToPath(import.meta.url)\nconst __dirname = path.dirname(__filename)\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(__dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,IAAI;CACtC,IAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,SAAS,EAC/C,OAAO,KAAK,MAAM,GAAG,SAAS;CAEhC,OAAO;;;;;;;AE5DT,MAAM,aAAa,cAAc,OAAO,KAAK,IAAI;AACjD,MAAM,YAAY,KAAK,QAAQ,WAAW;AAQ1C,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,EAAE,EAAE;CACnI,MAAM,mBAAmB,KAAK,KAAK,WAAW,sBAAsB;CAEpE,OADiB,IAAI,QAAQ,GAAG,aAAa,iBAAiB,CAAC,UAAU,CAC1D,CAAC;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC;;;;;;EAM3C;EACA;EACD,CAAC;;;;ACtBJ,MAAa,kBAAkB;AAE/B,MAAa,cAAc,cAA2B,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,KAAK;CAE3C,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,KAAK;IAC9B,SAAS,EAAE;IACX,UAAU,EAAE;IACb,CAAC;GAEF,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAAS,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,uIACrB;GAGH,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,yHACrB;GAGH,MAAM,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,KAAK;GAClE,MAAM,WAAW,MAAM,YAAY,SAAS;GAE5C,IAAI,WAAW;IACb,UAAU;IACV,MAAM,KAAK,QAAQ,MAAM,OAAO,QAAQ,cAAc;IACtD,SAAS,CACP,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAAC,IAAI,WAAW,SAAS,CAAC;KAClC,CAAC,CACH;IACF,CAAC;KAEL;EACF;EACD"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../internals/utils/src/string.ts","../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["/**\n * Strips a single matching pair of `\"...\"`, `'...'`, or `` `...` `` from both ends of `text`.\n * Returns the string unchanged when no balanced quote pair is found.\n *\n * @example\n * trimQuotes('\"hello\"') // 'hello'\n * trimQuotes('hello')   // 'hello'\n */\nexport function trimQuotes(text: string): string {\n  if (text.length >= 2) {\n    const first = text[0]\n    const last = text[text.length - 1]\n    if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\") || (first === '`' && last === '`')) {\n      return text.slice(1, -1)\n    }\n  }\n  return text\n}\n\n/**\n * Escapes characters that are not allowed inside JS string literals.\n * Handles quotes, backslashes, and Unicode line terminators (U+2028 / U+2029).\n *\n * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4\n *\n * @example\n * ```ts\n * jsStringEscape('say \"hi\"\\nbye') // 'say \\\\\"hi\\\\\"\\\\nbye'\n * ```\n */\nexport function jsStringEscape(input: unknown): string {\n  return `${input}`.replace(/[\"'\\\\\\n\\r\\u2028\\u2029]/g, (character) => {\n    switch (character) {\n      case '\"':\n      case \"'\":\n      case '\\\\':\n        return `\\\\${character}`\n      case '\\n':\n        return '\\\\n'\n      case '\\r':\n        return '\\\\r'\n      case '\\u2028':\n        return '\\\\u2028'\n      case '\\u2029':\n        return '\\\\u2029'\n      default:\n        return ''\n    }\n  })\n}\n\n/**\n * Strips the file extension from a path or file name.\n * Only removes the last `.ext` segment when the dot is not part of a directory name.\n *\n * @example\n * trimExtName('petStore.ts')             // 'petStore'\n * trimExtName('/src/models/pet.ts')      // '/src/models/pet'\n * trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'\n * trimExtName('noExtension')             // 'noExtension'\n */\nexport function trimExtName(text: string): string {\n  const dotIndex = text.lastIndexOf('.')\n  if (dotIndex > 0 && !text.includes('/', dotIndex)) {\n    return text.slice(0, dotIndex)\n  }\n  return text\n}\n","","import fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport pkg from 'handlebars'\n\nconst __filename = fileURLToPath(import.meta.url)\nconst __dirname = path.dirname(__filename)\n\ntype BuildDocsOptions = {\n  title?: string\n  disableGoogleFont?: boolean\n  templateOptions?: any\n}\n\n/**\n * Renders a self-contained Redoc HTML page for an OpenAPI document. The page\n * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so\n * the generated file works without further build steps.\n */\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {\n  const templateFileName = path.join(__dirname, '../static/redoc.hbs')\n  const template = pkg.compile(fs.readFileSync(templateFileName).toString())\n  return template({\n    title: title || api.info.title || 'ReDoc documentation',\n    redocHTML: `\n     <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n   const data = ${JSON.stringify(api, null, 2)};\n   Redoc.init(data, {\n     \"expandResponses\": \"200,400\"\n   }, document.getElementById('redoc-container'))\n </script>\n    `,\n    disableGoogleFont,\n    templateOptions,\n  })\n}\n","import path from 'node:path'\nimport { trimExtName } from '@internals/utils'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and\n * cross-plugin dependency references.\n */\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\n/**\n * Generates a self-contained static HTML documentation page from your OpenAPI\n * spec using Redoc. The file is regenerated on every Kubb build, so the docs\n * stay in lockstep with the spec the rest of your code is generated from.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { pluginRedoc } from '@kubb/plugin-redoc'\n *\n * export default defineConfig({\n *   input: { path: './petStore.yaml' },\n *   output: { path: './src/gen' },\n *   plugins: [\n *     pluginRedoc({ output: { path: 'docs.html' } }),\n *   ],\n * })\n * ```\n */\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n  const { output = { path: 'docs.html' } } = options\n\n  return {\n    name: pluginRedocName,\n    version,\n    options,\n    hooks: {\n      async 'kubb:plugin:setup'(ctx) {\n        ctx.setOptions({\n          output,\n          name: trimExtName(output.path),\n          exclude: [],\n          override: [],\n        })\n\n        const adapter = ctx.config.adapter\n\n        if (adapter?.name !== adapterOasName) {\n          throw new Error(\n            `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n          )\n        }\n\n        const document = (adapter as Adapter<AdapterOas>).document\n\n        if (!document) {\n          throw new Error(\n            `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n          )\n        }\n\n        const root = path.resolve(ctx.config.root, ctx.config.output.path)\n        const pageHTML = await getPageHTML(document)\n\n        ctx.injectFile({\n          baseName: 'docs.html',\n          path: path.resolve(root, output.path || './docs.html'),\n          sources: [\n            ast.createSource({\n              name: 'docs.html',\n              nodes: [ast.createText(pageHTML)],\n            }),\n          ],\n        })\n      },\n    },\n  }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6DA,SAAgB,YAAY,MAAsB;CAChD,MAAM,WAAW,KAAK,YAAY,IAAI;CACtC,IAAI,WAAW,KAAK,CAAC,KAAK,SAAS,KAAK,SAAS,EAC/C,OAAO,KAAK,MAAM,GAAG,SAAS;CAEhC,OAAO;;;;;;;AE5DT,MAAM,aAAa,cAAc,OAAO,KAAK,IAAI;AACjD,MAAM,YAAY,KAAK,QAAQ,WAAW;;;;;;AAa1C,eAAsB,YAAY,KAA6B,EAAE,OAAO,mBAAmB,oBAAsC,EAAE,EAAE;CACnI,MAAM,mBAAmB,KAAK,KAAK,WAAW,sBAAsB;CAEpE,OADiB,IAAI,QAAQ,GAAG,aAAa,iBAAiB,CAAC,UAAU,CAC1D,CAAC;EACd,OAAO,SAAS,IAAI,KAAK,SAAS;EAClC,WAAW;;;;kBAIG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC;;;;;;EAM3C;EACA;EACD,CAAC;;;;;;;;ACvBJ,MAAa,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqB/B,MAAa,cAAc,cAA2B,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,KAAK;CAE3C,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA,MAAM,YAAY,OAAO,KAAK;IAC9B,SAAS,EAAE;IACX,UAAU,EAAE;IACb,CAAC;GAEF,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAAS,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,uIACrB;GAGH,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,yHACrB;GAGH,MAAM,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,KAAK;GAClE,MAAM,WAAW,MAAM,YAAY,SAAS;GAE5C,IAAI,WAAW;IACb,UAAU;IACV,MAAM,KAAK,QAAQ,MAAM,OAAO,QAAQ,cAAc;IACtD,SAAS,CACP,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAAC,IAAI,WAAW,SAAS,CAAC;KAClC,CAAC,CACH;IACF,CAAC;KAEL;EACF;EACD"}

package/extension.yaml

@@ -2,7 +2,7 @@ $schema: https://kubb.dev/schemas/extension.json
 kind: plugin
 id: plugin-redoc
 name: Redoc
-description: Generate API documentation with Redoc from OpenAPI specifications.
+description: Render your OpenAPI spec as a single-file HTML page using Redoc, regenerated as part of the Kubb build.
 category: documentation
 type: official
 npmPackage: '@kubb/plugin-redoc'
@@ -32,25 +32,60 @@ featured: false
 icon:
   light: https://kubb.dev/feature/openapi.svg
 intro: |
-  Generate interactive API documentation from your OpenAPI schema using [Redoc](https://redocly.com/).
+  # @kubb/plugin-redoc
+
+  Generate a static HTML documentation page for your OpenAPI spec using [Redoc](https://redocly.com/). The page is self-contained — drop it on any static host or open it locally.
+
+  Because the file is regenerated on every Kubb build, your docs stay in lockstep with the spec your code was generated from.
 options:
   - name: output
     type: '{ path: string }'
     required: false
-    description: Specify the output path for the generated documentation HTML file.
+    description: Output location of the generated HTML file.
     properties:
       - name: path
         type: string
         required: true
         description: |
-          The output file path for the generated documentation HTML.
+          File path of the generated HTML, relative to the global `output.path`.
+
+          Use a `.html` extension. Unlike most plugins, this option points at a single file rather than a directory.
         tip: |
-          if `output.path` is a file, `group` cannot be used.
+          When `output.path` points to a single file, the `group` option cannot be used because every operation ends up in the same file.
+        examples:
+          - name: kubb.config.ts
+            files:
+              - lang: typescript
+                twoslash: false
+                code: |
+                  import { defineConfig } from 'kubb'
+                  import { pluginTs } from '@kubb/plugin-ts'
+
+                  export default defineConfig({
+                    input: { path: './petStore.yaml' },
+                    output: { path: './src/gen' },
+                    plugins: [
+                      pluginTs({
+                        output: { path: './types' },
+                      }),
+                    ],
+                  })
+          - name: Resulting tree
+            files:
+              - lang: text
+                twoslash: false
+                code: |
+                  src/
+                  └── gen/
+                      └── types/
+                          ├── Pet.ts
+                          └── Store.ts
         default: "'docs.html'"
 examples:
   - name: kubb.config.ts
     files:
       - lang: typescript
+        twoslash: false
         code: |
           import { defineConfig } from 'kubb'
           import { pluginRedoc } from '@kubb/plugin-redoc'
@@ -64,4 +99,3 @@ examples:
               }),
             ],
           })
-        twoslash: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-redoc",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.25",
   "description": "Generate a beautiful, interactive ReDoc API reference page from your OpenAPI specification. Produces a standalone HTML file with a responsive, developer-friendly UI.",
   "keywords": [
     "api-docs",
@@ -50,8 +50,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/adapter-oas": "5.0.0-beta.22",
-    "@kubb/core": "5.0.0-beta.22",
+    "@kubb/adapter-oas": "5.0.0-beta.25",
+    "@kubb/core": "5.0.0-beta.25",
     "handlebars": "^4.7.9"
   },
   "devDependencies": {

package/src/plugin.ts

@@ -8,8 +8,31 @@ import { version } from '../package.json'
 import { getPageHTML } from './redoc.tsx'
 import type { PluginRedoc } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and
+ * cross-plugin dependency references.
+ */
 export const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']
 
+/**
+ * Generates a self-contained static HTML documentation page from your OpenAPI
+ * spec using Redoc. The file is regenerated on every Kubb build, so the docs
+ * stay in lockstep with the spec the rest of your code is generated from.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginRedoc } from '@kubb/plugin-redoc'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginRedoc({ output: { path: 'docs.html' } }),
+ *   ],
+ * })
+ * ```
+ */
 export const pluginRedoc = definePlugin<PluginRedoc>((options) => {
   const { output = { path: 'docs.html' } } = options
 

package/src/redoc.tsx

@@ -13,6 +13,11 @@ type BuildDocsOptions = {
   templateOptions?: any
 }
 
+/**
+ * Renders a self-contained Redoc HTML page for an OpenAPI document. The page
+ * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
+ * the generated file works without further build steps.
+ */
 export async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont, templateOptions }: BuildDocsOptions = {}) {
   const templateFileName = path.join(__dirname, '../static/redoc.hbs')
   const template = pkg.compile(fs.readFileSync(templateFileName).toString())

package/src/types.ts

@@ -1,9 +1,14 @@
 import type { Exclude, Include, Output, Override, PluginFactoryOptions } from '@kubb/core'
 
 export type Options = {
+  /**
+   * Output location of the generated Redoc HTML file. The path is resolved
+   * against the global `output.path` set on `defineConfig`.
+   */
   output?: {
     /**
-     * Output path for the generated HTML documentation.
+     * File path of the generated HTML, relative to the global `output.path`.
+     * Unlike most plugins, this points at a single file rather than a directory.
      *
      * @default 'docs.html'
      */