feat: add comment option to IndexGeneratorSource (#89)

Author: kerwanp

src/index_generator/source.ts

@@ -81,6 +81,10 @@ export class IndexGeneratorSource {
   #generateOutput = throttle(async () => {
     const buffer = new FileBuffer().eol(true)
 
+    if (this.#config.comment) {
+      buffer.writeLine(this.#textToComment(this.#config.comment))
+    }
+
     if (this.#config.as === 'barrelFile') {
       this.#asBarrelFile(
         this.#vfs,
@@ -156,6 +160,13 @@ export class IndexGeneratorSource {
     })
   }
 
+  /**
+   * Converts a text into a JS comment block. Respecting line-breaks.
+   */
+  #textToComment(text: string) {
+    return `/**\n * ${text.split('\n').join('\n * ')}\n */`
+  }
+
   /**
    * Transforms the barrel file index key. Converts basename to PascalCase
    * and all other paths to camelCase

src/types/common.ts

@@ -61,6 +61,7 @@ export type IndexGeneratorSourceConfig = (
   importAlias?: string
   removeSuffix?: string
   skipSegments?: string[]
+  comment?: string
 } & VirtualFileSystemOptions
 
 /**

tests/index_generator.spec.ts

@@ -34,11 +34,17 @@ test.group('Index generator', () => {
       output: outputPath,
       source: 'app/controllers',
       importAlias: '#controllers',
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "export const controllers = {
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      export const controllers = {
         auth: {
           SignupController: () => import('#controllers/auth/signup_controller'),
         },
@@ -69,11 +75,17 @@ test.group('Index generator', () => {
       exportName: 'controllers',
       output: outputPath,
       source: 'app/controllers',
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "export const controllers = {
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      export const controllers = {
         auth: {
           SignupController: () => import('../../app/controllers/auth/signup_controller.ts'),
         },
@@ -106,11 +118,17 @@ test.group('Index generator', () => {
       removeSuffix: 'controller',
       importAlias: '#controllers',
       source: 'app/controllers',
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "export const controllers = {
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      export const controllers = {
         auth: {
           Signup: () => import('#controllers/auth/signup_controller'),
         },
@@ -186,6 +204,7 @@ test.group('Index generator', () => {
       output: outputPath,
       source: 'app/controllers',
       importAlias: '#controllers',
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
@@ -204,7 +223,12 @@ test.group('Index generator', () => {
     await transformer.addFile(join(source, 'app/controllers/README.md'))
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "export const controllers = {
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      export const controllers = {
         auth: {
           SignupController: () => import('#controllers/auth/signup_controller'),
         },
@@ -237,6 +261,7 @@ test.group('Index generator', () => {
       output: outputPath,
       source: 'app/controllers',
       importAlias: '#controllers',
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
@@ -251,7 +276,12 @@ test.group('Index generator', () => {
     await transformer.removeFile(join(source, 'app/controllers/user/users.ts'))
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "export const controllers = {
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      export const controllers = {
         auth: {
           SignupController: () => import('#controllers/auth/signup_controller'),
         },
@@ -281,11 +311,17 @@ test.group('Index generator', () => {
       output: outputPath,
       source: 'app/controllers',
       importAlias: '#controllers',
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "import AuthSignupController from '#controllers/auth/signup_controller'
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      import AuthSignupController from '#controllers/auth/signup_controller'
       import PostsController from '#controllers/posts_controller'
       import PublicHomePage from '#controllers/public/home_page'
       import UserPostsController from '#controllers/user/posts_controller'
@@ -318,11 +354,17 @@ test.group('Index generator', () => {
       output: outputPath,
       source: 'app/controllers',
       importAlias: '#controllers',
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "export const controllers = {}
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      export const controllers = {}
       "
     `)
   })
@@ -345,11 +387,17 @@ test.group('Index generator', () => {
       importAlias: '#app',
       removeSuffix: 'controller',
       skipSegments: ['controllers'],
+      comment: 'This file is automatically generated.\nDO NOT EDIT manually',
     })
     await transformer.generate()
 
     assert.snapshot(await fs.contents(outputPath)).matchInline(`
-      "export const controllers = {
+      "/**
+       * This file is automatically generated.
+       * DO NOT EDIT manually
+       */
+
+      export const controllers = {
         core: {
           Health: () => import('#app/core/controllers/health_controller'),
         },