Preserve block position (#347)

## Description

This PR adds a new option to preserve the position of the generated
block if the user so desires. this is helpful when there's certain
strict order the developer wants to keep. Normally because there are
manual entries.

This closes #343 

Missing:

- [x] CLI option
- [x] Documentation
- [x] Logic Refactor (because it looks ugly what I did)

Extra:

So I was playing with ChatGPT, and I decided to ask for rewrites on my
code the changes are not that bad. So I left them in

README.md

@@ -199,6 +199,8 @@ You can configure `codeowners-generator` from several places:
 
 - **groupSourceComments** (`--group-source-comments`): Instead of generating one comment per rule, enabling this flag will group them, reducing comments to one per source file. Useful if your codeowners file gets too noisy.
 
+- **preserveBlockPosition** (`--preserve-block-position`): It will keep the generated block in the same position it was found in the CODEOWNERS file (if present). Useful for when you make manual additions.
+
 - **customRegenerationCommand** (`--custom-regeneration-command`): Specify a custom regeneration command to be printed in the generated CODEOWNERS file, it should be mapped to run codeowners-generator (e.g. "npm run codeowners").
 
 - **check** (`--check`): It will fail if the CODEOWNERS generated doesn't match the current (or missing) CODEOWNERS . Useful for validating that the CODEOWNERS file is not out of date during CI.

__mocks__/CODEOWNERS_POPULATED_OUTPUT

@@ -9,3 +9,6 @@ scripts/ @myOrg/infraTeam
 # Rule extracted from dir1/CODEOWNERS
 dir1/*.ts @eeny @meeny
 #################################### Generated content - do not edit! ####################################
+
+# Another line here that should be moved to after the generated block without preserve-block-position option enabled
+dir2/ @otherTeam

__tests__/generate.spec.ts

@@ -66,7 +66,12 @@ describe('Generate', () => {
     });
 
     await generateCommand(
-      { output: 'CODEOWNERS', customRegenerationCommand: 'yarn codeowners-generator generate', check: true },
+      {
+        output: 'CODEOWNERS',
+        customRegenerationCommand: 'yarn codeowners-generator generate',
+        check: true,
+        preserveBlockPosition: true,
+      },
       { parent: {} }
     );
   });
@@ -130,6 +135,10 @@ describe('Generate', () => {
       # We might wanna keep an eye on something else, like yml files and workflows.
       .github/workflows/ @myOrg/infraTeam
 
+
+      # Another line here that should be moved to after the generated block without preserve-block-position option enabled
+      dir2/ @otherTeam
+
       #################################### Generated content - do not edit! ####################################
       # This block has been generated with codeowners-generator (for more information https://github.com/gagoar/codeowners-generator)
       # To re-generate, run \`yarn codeowners-generator generate\`. Don't worry, the content outside this block will be kept.
@@ -157,6 +166,72 @@ describe('Generate', () => {
       ]
     `);
   });
+
+  it('should generate a CODEOWNERS file (re-using codeowners content, with preserve-block-position enabled)', async () => {
+    sync.mockReturnValueOnce(Object.keys(files));
+
+    sync.mockReturnValueOnce(['.gitignore']);
+
+    const withPopulatedCodeownersFile = {
+      ...withGitIgnore,
+      CODEOWNERS: '../__mocks__/CODEOWNERS_POPULATED_OUTPUT',
+    };
+    existsSync.mockReturnValue(true);
+    readFile.mockImplementation((file, callback): void => {
+      const fullPath = path.join(
+        __dirname,
+        withPopulatedCodeownersFile[file as keyof typeof withPopulatedCodeownersFile]
+      );
+      const content = readFileSync(fullPath);
+      callback(null, content);
+    });
+
+    await generateCommand(
+      {
+        output: 'CODEOWNERS',
+        customRegenerationCommand: 'yarn codeowners-generator generate',
+        preserveBlockPosition: true,
+      },
+      { parent: {} }
+    );
+    expect(writeFile.mock.calls[0]).toMatchInlineSnapshot(`
+      Array [
+        "CODEOWNERS",
+        "# We are already using CODEOWNERS and we don't want to lose the content of this file.
+      scripts/ @myOrg/infraTeam
+      # We might wanna keep an eye on something else, like yml files and workflows.
+      .github/workflows/ @myOrg/infraTeam
+
+      #################################### Generated content - do not edit! ####################################
+      # This block has been generated with codeowners-generator (for more information https://github.com/gagoar/codeowners-generator)
+      # To re-generate, run \`yarn codeowners-generator generate\`. Don't worry, the content outside this block will be kept.
+
+      # Rule extracted from dir1/CODEOWNERS
+      /dir1/**/*.ts @eeny @meeny
+      # Rule extracted from dir1/CODEOWNERS
+      /dir1/*.ts @miny
+      # Rule extracted from dir1/CODEOWNERS
+      /dir1/**/README.md @miny
+      # Rule extracted from dir1/CODEOWNERS
+      /dir1/README.md @moe
+      # Rule extracted from dir2/CODEOWNERS
+      /dir2/**/*.ts @moe
+      # Rule extracted from dir2/CODEOWNERS
+      /dir2/dir3/*.ts @miny
+      # Rule extracted from dir2/CODEOWNERS
+      /dir2/**/*.md @meeny
+      # Rule extracted from dir2/CODEOWNERS
+      /dir2/**/dir4/ @eeny
+      # Rule extracted from dir2/dir3/CODEOWNERS
+      /dir2/dir3/**/*.ts @miny
+
+      #################################### Generated content - do not edit! ####################################
+
+      # Another line here that should be moved to after the generated block without preserve-block-position option enabled
+      dir2/ @otherTeam",
+      ]
+    `);
+  });
   it('should generate a CODEOWNERS FILE with groupSourceComments and customRegenerationCommand', async () => {
     sync.mockReturnValueOnce(Object.keys(files));
 

src/bin/cli.ts

@@ -29,6 +29,11 @@ program
     'Instead of generating one comment per rule, enabling this flag will group them, reducing comments to one per source file. Useful if your codeowners file gets too noisy',
     false
   )
+  .option(
+    '--preserve-block-position',
+    'It will keep the generated block in the same position it was found in the CODEOWNERS file (if present). Useful for when you make manual additions',
+    false
+  )
   .option(
     '--custom-regeneration-command',
     'Specify a custom regeneration command to be printed in the generated CODEOWNERS file, it should be mapped to run codeowners-generator'

src/commands/generate.ts

@@ -101,6 +101,7 @@ interface Options {
   useMaintainers?: boolean;
   useRootMaintainers?: boolean;
   groupSourceComments?: boolean;
+  preserveBlockPosition?: boolean;
   includes?: string[];
   customRegenerationCommand?: string;
   check?: boolean;
@@ -109,7 +110,7 @@ interface Options {
 export const command = async (options: Options, command: Command): Promise<void> => {
   const globalOptions = await getGlobalOptions(command);
 
-  const { verifyPaths, useMaintainers, useRootMaintainers, check } = options;
+  const { verifyPaths, useMaintainers, useRootMaintainers, check, preserveBlockPosition } = options;
 
   const { output = globalOptions.output || OUTPUT } = options;
 
@@ -124,6 +125,7 @@ export const command = async (options: Options, command: Command): Promise<void>
     useMaintainers,
     useRootMaintainers,
     groupSourceComments,
+    preserveBlockPosition,
     customRegenerationCommand,
     output,
   });
@@ -141,8 +143,9 @@ export const command = async (options: Options, command: Command): Promise<void>
       const [originalContent, newContent] = await generateOwnersFile(
         output,
         ownerRules,
-        customRegenerationCommand,
-        groupSourceComments
+        groupSourceComments,
+        preserveBlockPosition,
+        customRegenerationCommand
       );
 
       if (check) {

src/utils/codeowners.ts

@@ -1,16 +1,11 @@
 import fs from 'fs';
 import isGlob from 'is-glob';
-import {
-  MAINTAINERS_EMAIL_PATTERN,
-  contentTemplate,
-  CONTENT_MARK,
-  CHARACTER_RANGE_PATTERN,
-  rulesBlockTemplate,
-} from './constants';
+import { MAINTAINERS_EMAIL_PATTERN, CONTENT_MARK, CHARACTER_RANGE_PATTERN } from './constants';
 import { dirname, join } from 'path';
 import { readContent } from './readContent';
 import { logger } from '../utils/debug';
 import groupBy from 'lodash.groupby';
+import { generatedContentTemplate, rulesBlockTemplate } from './templates';
 
 const debug = logger('utils/codeowners');
 
@@ -26,27 +21,34 @@ export type ownerRule = {
   glob: string;
 };
 
-const filterGeneratedContent = (content: string) => {
+const filterGeneratedContent = (content: string): [withoutGeneratedCode: string[], blockPosition: number] => {
   const lines = content.split('\n');
 
   let skip = false;
-  return lines
-    .reduce((memo, line) => {
-      if (line === CONTENT_MARK) {
-        skip = !skip;
-        return memo;
+  let generatedBlockPosition = -1;
+
+  const withoutGeneratedCode = lines.reduce((memo, line, index) => {
+    if (line === CONTENT_MARK) {
+      skip = !skip;
+      if (generatedBlockPosition === -1) {
+        generatedBlockPosition = index;
       }
+      return memo;
+    }
+
+    return skip ? memo : [...memo, line];
+  }, [] as string[]);
 
-      return skip ? memo : [...memo, line];
-    }, [] as string[])
-    .join('\n');
+  return [withoutGeneratedCode, generatedBlockPosition];
 };
+
 type createOwnersFileResponse = [originalContent: string, newContent: string];
 export const generateOwnersFile = async (
   outputFile: string,
   ownerRules: ownerRule[],
-  customRegenerationCommand?: string,
-  groupSourceComments = false
+  groupSourceComments = false,
+  preserveBlockPosition = false,
+  customRegenerationCommand?: string
 ): Promise<createOwnersFileResponse> => {
   let originalContent = '';
 
@@ -67,14 +69,28 @@ export const generateOwnersFile = async (
   } else {
     content = ownerRules.map((rule) => rulesBlockTemplate(rule.filePath, [`${rule.glob} ${rule.owners.join(' ')}`]));
   }
+  const [withoutGeneratedCode, blockPosition] = filterGeneratedContent(originalContent);
 
-  const normalizedContent = contentTemplate(
-    content.join('\n'),
-    filterGeneratedContent(originalContent),
-    customRegenerationCommand
-  );
+  let normalizedContent = '';
+
+  const generatedContent = generatedContentTemplate(content.join('\n'), customRegenerationCommand) + '\n';
+
+  if (originalContent) {
+    normalizedContent = withoutGeneratedCode.reduce((memo, line, index) => {
+      if (preserveBlockPosition && index === blockPosition) {
+        memo += generatedContent;
+      }
+      memo += line + '\n';
+
+      return memo;
+    }, '');
+  }
+
+  if (!preserveBlockPosition) {
+    normalizedContent = normalizedContent + generatedContent;
+  }
 
-  return [originalContent, normalizedContent];
+  return [originalContent, normalizedContent.trimEnd()];
 };
 
 const parseCodeOwner = (filePath: string, codeOwnerContent: string): ownerRule[] => {

src/utils/constants.ts

@@ -12,32 +12,3 @@ export const CHARACTER_RANGE_PATTERN = /\[(?:.-.)+\]/;
 export const CONTENT_MARK = stripIndents`
 #################################### Generated content - do not edit! ####################################
 `;
-
-const getContentLegend = (customRegenerationCommand?: string) => stripIndents`
-# This block has been generated with codeowners-generator (for more information https://github.com/gagoar/codeowners-generator)
-# ${
-  customRegenerationCommand ? `To re-generate, run \`${customRegenerationCommand}\`. ` : ''
-}Don't worry, the content outside this block will be kept. 
-`;
-
-export const contentTemplate = (
-  generatedContent: string,
-  originalContent: string,
-  customRegenerationCommand?: string
-): string => {
-  return stripIndents`
-  ${originalContent && originalContent.trimEnd()}
-
-  ${CONTENT_MARK}
-  ${getContentLegend(customRegenerationCommand)}\n
-  ${generatedContent}\n
-  ${CONTENT_MARK}\n
-`;
-};
-
-export const rulesBlockTemplate = (source: string, entries: string[]): string => {
-  return stripIndents`
-  # Rule${entries.length > 1 ? 's' : ''} extracted from ${source}
-  ${entries.join('\n')}
-  `;
-};

src/utils/getCustomConfiguration.ts

@@ -16,7 +16,7 @@ export type CustomConfig = {
 };
 
 export const getCustomConfiguration = async (): Promise<CustomConfig | void> => {
-  const loader = ora('Loading available configuration').start();
+  const loader = ora('Loading configuration').start();
 
   try {
     const explorer = cosmiconfig(packageJSON.name);

src/utils/templates.ts

@@ -0,0 +1,24 @@
+import { stripIndents } from 'common-tags';
+import { CONTENT_MARK } from './constants';
+
+const getContentLegend = (customRegenerationCommand?: string) => stripIndents`
+# This block has been generated with codeowners-generator (for more information https://github.com/gagoar/codeowners-generator)
+# ${
+  customRegenerationCommand ? `To re-generate, run \`${customRegenerationCommand}\`. ` : ''
+}Don't worry, the content outside this block will be kept. 
+`;
+
+export const generatedContentTemplate = (generatedContent: string, customRegenerationCommand?: string) => {
+  return stripIndents`
+  ${CONTENT_MARK}
+  ${getContentLegend(customRegenerationCommand)}\n
+  ${generatedContent}\n
+  ${CONTENT_MARK}\n
+  `;
+};
+export const rulesBlockTemplate = (source: string, entries: string[]): string => {
+  return stripIndents`
+  # Rule${entries.length > 1 ? 's' : ''} extracted from ${source}
+  ${entries.join('\n')}
+  `;
+};