@kubb/middleware-barrel 5.0.0-beta.3 → 5.0.0-beta.30

package/src/middleware.ts

@@ -1,10 +1,34 @@
 import path from 'node:path'
 import { resolve } from 'node:path'
+import type { FileNode } from '@kubb/ast'
 import { defineMiddleware } from '@kubb/core'
-import type { Middleware } from '@kubb/core'
+import type { Config, Middleware, NormalizedPlugin } from '@kubb/core'
 import type { BarrelConfig, PluginBarrelConfig } from './types.ts'
-import { getPluginOutputPrefix, isExcludedPath } from './utils/excludedPaths.ts'
-import { getBarrelFiles } from './utils/getBarrelFiles.ts'
+import { getBarrelFiles, getPluginOutputPrefix, isExcludedPath } from './utils.ts'
+
+/**
+ * Applies a plugin's configured `output.banner`/`footer` to a barrel file, flagged as `isBarrel`.
+ *
+ * Resolves through the plugin's own resolver, and only when the plugin explicitly sets a
+ * banner/footer — so barrels stay banner-free by default and never inherit the implicit
+ * "Generated by Kubb" notice.
+ */
+function withBarrelBannerFooter({ file, plugin, config }: { file: FileNode; plugin: NormalizedPlugin; config: Config }): FileNode {
+  const output = plugin.options?.output
+  const resolver = plugin.resolver
+  if (!resolver) return file
+
+  const hasBanner = output?.banner !== undefined
+  const hasFooter = output?.footer !== undefined
+  if (!hasBanner && !hasFooter) return file
+
+  const context = { output, config, file: { path: file.path, baseName: file.baseName, isBarrel: true } }
+  return {
+    ...file,
+    banner: hasBanner ? resolver.resolveBanner(undefined, context) : file.banner,
+    footer: hasFooter ? resolver.resolveFooter(undefined, context) : file.footer,
+  }
+}
 
 declare global {
   namespace Kubb {
@@ -38,17 +62,29 @@ declare global {
 }
 
 /**
- * Generates `index.ts` barrel files for each plugin and a root barrel at `config.output.path/index.ts`.
+ * Canonical middleware name for `@kubb/middleware-barrel`. Used for driver
+ * lookups.
+ */
+export const middlewareBarrelName = 'middleware-barrel' satisfies Middleware['name']
+
+/**
+ * Generates an `index.ts` for every plugin output directory and one root
+ * barrel at `config.output.path/index.ts` after the build completes. Ships
+ * with Kubb and is registered by default in `defineConfig`.
  *
- * Each plugin inherits `output.barrel` from `config.output.barrel` (defaults to `{ type: 'named' }`).
- * Set `barrel: false` on a plugin to disable its barrel and exclude it from the root barrel.
+ * Each plugin inherits `output.barrel` from `config.output.barrel` (which
+ * defaults to `{ type: 'named' }`). Set `barrel: false` on a plugin to skip
+ * its barrel and also exclude its files from the root barrel.
  *
  * @example
  * ```ts
  * import { defineConfig } from '@kubb/core'
  * import { middlewareBarrel } from '@kubb/middleware-barrel'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginZod } from '@kubb/plugin-zod'
  *
  * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
  *   output: { path: 'src/gen', barrel: { type: 'named' } },
  *   plugins: [
  *     pluginTs({ output: { path: 'types', barrel: { type: 'all' } } }),
@@ -58,12 +94,6 @@ declare global {
  * })
  * ```
  */
-
-/**
- * Stable string identifier for the barrel middleware.
- */
-export const middlewareBarrelName = 'middleware-barrel' satisfies Middleware['name']
-
 export const middlewareBarrel = defineMiddleware(() => {
   const excludedPrefixes = new Set<string>()
 
@@ -75,15 +105,12 @@ export const middlewareBarrel = defineMiddleware(() => {
         const configBarrel = config.output.barrel
         const defaultBarrel = { type: 'named' } as const
 
-        let barrelConfig: PluginBarrelConfig | false
-        if (pluginBarrel !== undefined) {
-          barrelConfig = pluginBarrel
-        } else if (configBarrel !== undefined) {
-          // Root config barrel doesn't have nested, so we add it
-          barrelConfig = configBarrel === false ? false : { ...configBarrel, nested: false }
-        } else {
-          barrelConfig = defaultBarrel
-        }
+        // Root config barrel doesn't have nested, so we add it
+        const barrelConfig: PluginBarrelConfig | false = (() => {
+          if (pluginBarrel !== undefined) return pluginBarrel
+          if (configBarrel !== undefined) return configBarrel === false ? false : { ...configBarrel, nested: false }
+          return defaultBarrel
+        })()
 
         if (barrelConfig === false) {
           excludedPrefixes.add(getPluginOutputPrefix(plugin, config))
@@ -99,16 +126,8 @@ export const middlewareBarrel = defineMiddleware(() => {
         if (relative.startsWith('..') || path.isAbsolute(relative)) {
           throw new Error('Invalid output path')
         }
-        const barrelFiles = getBarrelFiles({
-          outputPath: target,
-          files,
-          barrelType,
-          nested,
-          recursive: true,
-        })
-
-        if (barrelFiles.length > 0) {
-          upsertFile(...barrelFiles)
+        for (const file of getBarrelFiles({ outputPath: target, files, barrelType, nested, recursive: true })) {
+          upsertFile(withBarrelBannerFooter({ file, plugin, config }))
         }
       },
       'kubb:plugins:end'({ files, config, upsertFile }) {
@@ -121,14 +140,8 @@ export const middlewareBarrel = defineMiddleware(() => {
 
         const barrelType = barrelConfig.type
 
-        const rootBarrelFiles = getBarrelFiles({
-          outputPath: resolve(config.root, config.output.path),
-          files: filteredFiles,
-          barrelType,
-        })
-
-        if (rootBarrelFiles.length > 0) {
-          upsertFile(...rootBarrelFiles)
+        for (const file of getBarrelFiles({ outputPath: resolve(config.root, config.output.path), files: filteredFiles, barrelType })) {
+          upsertFile(file)
         }
       },
     },

package/src/{utils/getBarrelFiles.ts → utils.ts}

@@ -1,12 +1,12 @@
-import { extname } from 'node:path'
+import { extname, resolve } from 'node:path'
 import { createExport, createFile } from '@kubb/ast'
 import type { ExportNode, FileNode, SourceNode } from '@kubb/ast'
-import { BARREL_FILENAME } from '../constants.ts'
-import type { BarrelType } from '../types.ts'
+import type { Config, NormalizedPlugin } from '@kubb/core'
 import { type BuildTree, buildTree, toPosixPath } from '@internals/utils'
+import type { BarrelType } from './types.ts'
 
 const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx'])
-const BARREL_SUFFIX = `/${BARREL_FILENAME}`
+const BARREL_SUFFIX = `/index.ts`
 
 function toRelativeModulePath(fromDir: string, filePath: string): string {
   return `./${filePath.slice(fromDir.length + 1)}`
@@ -18,13 +18,14 @@ function isBarrelPath(path: string): boolean {
 
 function makeBarrel(dirPath: string, exports: Array<ExportNode>): FileNode {
   return createFile({
-    baseName: BARREL_FILENAME,
+    baseName: 'index.ts',
     path: `${dirPath}${BARREL_SUFFIX}`,
     exports,
     sources: [],
     imports: [],
-    // Barrel files must never carry a banner or footer: they only re-export
-    // symbols and adding a directive like "use server" would break consumers.
+    // Default to no banner/footer. The middleware resolves a configured plugin
+    // banner/footer (with isBarrel: true) afterwards, so a `banner` function can
+    // decide per file whether a barrel should carry a directive like "use server".
     banner: undefined,
     footer: undefined,
   })
@@ -33,7 +34,7 @@ function makeBarrel(dirPath: string, exports: Array<ExportNode>): FileNode {
 type LeafContext = {
   dirPath: string
   leafPath: string
-  sourceFile: FileNode | undefined
+  sourceFile: FileNode | null
 }
 
 type LeafStrategy = (ctx: LeafContext) => Array<ExportNode>
@@ -99,9 +100,10 @@ type LeafWalkParams = {
 }
 
 /**
- * Post-order walk that emits a barrel per visited directory.
+ * Post-order walk that yields a barrel per visited directory.
+ * Returns the list of leaf file paths collected in this subtree (used by the parent call).
  */
-function walkAllOrNamed(node: BuildTree, params: LeafWalkParams, isRoot: boolean, out: Array<FileNode>): Array<string> {
+function* walkAllOrNamed(node: BuildTree, params: LeafWalkParams, isRoot: boolean): Generator<FileNode, Array<string>> {
   const subtreeLeaves: Array<string> = []
 
   for (const child of node.children) {
@@ -110,26 +112,26 @@ function walkAllOrNamed(node: BuildTree, params: LeafWalkParams, isRoot: boolean
       continue
     }
 
-    const childLeaves = walkAllOrNamed(child, params, false, out)
+    const childLeaves = yield* walkAllOrNamed(child, params, false)
     for (const leaf of childLeaves) subtreeLeaves.push(leaf)
   }
 
   if (!isRoot && !params.recursive) return subtreeLeaves
 
-  const exports = subtreeLeaves.flatMap((leafPath) => params.strategy({ dirPath: node.path, leafPath, sourceFile: params.sourceFiles.get(leafPath) }))
+  const exports = subtreeLeaves.flatMap((leafPath) => params.strategy({ dirPath: node.path, leafPath, sourceFile: params.sourceFiles.get(leafPath) ?? null }))
 
   if (exports.length > 0) {
-    out.push(makeBarrel(node.path, exports))
+    yield makeBarrel(node.path, exports)
   }
 
   return subtreeLeaves
 }
 
 /**
- * Recursive walk that emits one barrel per directory, re-exporting files and sub-barrels.
+ * Recursive walk that yields one barrel per directory, re-exporting files and sub-barrels.
  * Used when nested: true.
  */
-function walkNested(node: BuildTree, out: Array<FileNode>): void {
+function* walkNested(node: BuildTree): Generator<FileNode> {
   const exports: Array<ExportNode> = []
 
   for (const child of node.children) {
@@ -139,12 +141,12 @@ function walkNested(node: BuildTree, out: Array<FileNode>): void {
       continue
     }
 
-    walkNested(child, out)
+    yield* walkNested(child)
     exports.push(createExport({ path: toRelativeModulePath(node.path, `${child.path}${BARREL_SUFFIX}`) }))
   }
 
   if (exports.length > 0) {
-    out.push(makeBarrel(node.path, exports))
+    yield makeBarrel(node.path, exports)
   }
 }
 
@@ -204,24 +206,49 @@ type GetBarrelFilesParams = {
 }
 
 /**
- * Generates barrel `FileNode`s for the directory rooted at `outputPath`.
+ * Yields barrel `FileNode`s for the directory rooted at `outputPath`.
+ *
+ * @example
+ * ```ts
+ * for (const file of getBarrelFiles({ outputPath, files, barrelType })) {
+ *   upsertFile(file)
+ * }
+ * // or collect into an array
+ * const barrels = [...getBarrelFiles({ outputPath, files, barrelType })]
+ * ```
  */
-export function getBarrelFiles({ outputPath, files, barrelType, nested = false, recursive = false }: GetBarrelFilesParams): Array<FileNode> {
+export function* getBarrelFiles({ outputPath, files, barrelType, nested = false, recursive = false }: GetBarrelFilesParams): Generator<FileNode> {
   const { sourceFiles, paths } = indexRelevantFiles(files, outputPath)
-  if (paths.length === 0) return []
+  if (paths.length === 0) return
 
   const tree = buildTree(outputPath, paths)
-  const result: Array<FileNode> = []
 
-  // Use nested walk for hierarchical barrel structure
   if (nested) {
-    walkNested(tree, result)
-    return result
+    yield* walkNested(tree)
+    return
   }
 
   const strategy = LEAF_STRATEGIES.get(barrelType)
-  if (!strategy) return result
+  if (!strategy) return
 
-  walkAllOrNamed(tree, { sourceFiles, strategy, recursive }, true, result)
-  return result
+  yield* walkAllOrNamed(tree, { sourceFiles, strategy, recursive }, true)
+}
+
+/**
+ * Builds a POSIX-normalized prefix for a plugin's output directory, with a trailing `/`.
+ *
+ * Used to detect (and later exclude) files generated by plugins that opted out of the root barrel.
+ */
+export function getPluginOutputPrefix(plugin: NormalizedPlugin, config: Config): string {
+  return `${toPosixPath(resolve(config.root, config.output.path, plugin.options.output.path))}/`
+}
+
+/**
+ * Returns `true` when `filePath` lives under any of the given excluded directory prefixes.
+ *
+ * Both sides are POSIX-normalized so Windows backslash paths match correctly.
+ */
+export function isExcludedPath(filePath: string, prefixes: ReadonlySet<string>): boolean {
+  const normalized = toPosixPath(filePath)
+  return prefixes.values().some((prefix) => normalized.startsWith(prefix))
 }

package/src/constants.ts

@@ -1,4 +0,0 @@
-/**
- * Full file name for barrel files (with extension).
- */
-export const BARREL_FILENAME = 'index.ts' as const

package/src/utils/excludedPaths.ts

@@ -1,22 +0,0 @@
-import { resolve } from 'node:path'
-import type { Config, NormalizedPlugin } from '@kubb/core'
-import { toPosixPath } from '@internals/utils'
-
-/**
- * Builds a POSIX-normalized prefix for a plugin's output directory, with a trailing `/`.
- *
- * Used to detect (and later exclude) files generated by plugins that opted out of the root barrel.
- */
-export function getPluginOutputPrefix(plugin: NormalizedPlugin, config: Config): string {
-  return `${toPosixPath(resolve(config.root, config.output.path, plugin.options.output.path))}/`
-}
-
-/**
- * Returns `true` when `filePath` lives under any of the given excluded directory prefixes.
- *
- * Both sides are POSIX-normalized so Windows backslash paths match correctly.
- */
-export function isExcludedPath(filePath: string, prefixes: ReadonlySet<string>): boolean {
-  const normalized = toPosixPath(filePath)
-  return prefixes.values().some((prefix) => normalized.startsWith(prefix))
-}