fix(migrate): write empty sections properly

Signed-off-by: Emilien Escalle <emilien.escalle@escemi.com>

Author: neilime

.github/workflows/main-ci.yml

@@ -49,7 +49,7 @@ jobs:
         with:
           ci-dokumentor-version: ${{ needs.ci.outputs.image-tag }}
           source: action.yml
-          include-sections: badges,contributing,license,generated
+          exclude-sections: overview,usage,inputs,outputs,secrets,examples
           extra-badges: |
             [
               {
@@ -76,7 +76,7 @@ jobs:
           ci-dokumentor-version: ${{ needs.ci.outputs.image-tag }}
           source: action.yml
           destination: packages/docs/content/integrations/github-action.md
-          include-sections: usage,inputs,outputs,secrets
+          exclude-sections: header,badges,overview,contributing,security,license,generated
           github-token: ${{ secrets.GITHUB_TOKEN }}
           format-link: full
 

packages/cicd/github-actions/src/migration/abstract-migration.adapter.ts

@@ -295,12 +295,16 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
         const findInsertAfterSection = (contentString: string, sectionName: SectionIdentifier): number => {
             const endMarker = formatterAdapter.sectionEnd(sectionName).toString('utf-8');
             const idx = contentString.lastIndexOf(endMarker);
-            if (idx !== -1) return idx + endMarker.length;
+            if (idx !== -1) {
+                return idx + endMarker.length;
+            }
 
             // If there's a start marker but no end (malformed), insert after start
             const startMarker = formatterAdapter.sectionStart(sectionName).toString('utf-8');
             const sidx = result.lastIndexOf(startMarker);
-            if (sidx !== -1) return sidx + startMarker.length;
+            if (sidx !== -1) {
+                return sidx + startMarker.length;
+            }
 
             return -1;
         };
@@ -313,7 +317,9 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
             let anchorIndex = -1;
             for (let i = 0; i < expectedSections.length; i++) {
                 const sek = expectedSections[i];
-                if (sek === missingSection) break;
+                if (sek === missingSection) {
+                    break;
+                }
                 if (presentSections.has(sek)) {
                     const candidate = findInsertAfterSection(contentString, sek);
                     if (candidate !== -1 && candidate > anchorIndex) {
@@ -336,7 +342,7 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
                     Buffer.from(sep),
                     formatterAdapter.lineBreak(),
                     sectionContent,
-                    after.trim().length > 0 ? Buffer.from(after) : formatterAdapter.lineBreak()
+                    after.trim().length > 0 ? Buffer.from(after) : Buffer.alloc(0)
                 );
             } else {
                 // No suitable anchor, append at end with a preceding newline

packages/cicd/github-actions/src/migration/action-docs-migration.adapter.e2e.spec.ts

@@ -104,6 +104,7 @@ Header here
 <!-- badges:start -->
 <!-- badges:end -->
 
+
 <!-- overview:start -->
 
 Desc here

packages/cicd/github-actions/src/migration/github-action-readme-generator-migration.adapter.e2e.spec.ts

@@ -155,6 +155,7 @@ Output details
 <!-- secrets:start -->
 <!-- secrets:end -->
 
+
 <!-- examples:start -->
 
 ExampleX

packages/core/src/formatter/markdown/markdown-formatter.adapter.spec.ts

@@ -1056,7 +1056,8 @@ Section Content
 
       // Assert
       expect(result.toString()).toEqual(`<!-- examples:start -->
-<!-- examples:end -->`);
+<!-- examples:end -->
+`);
     });
   });
 

packages/core/src/formatter/markdown/markdown-formatter.adapter.ts

@@ -235,7 +235,12 @@ export class MarkdownFormatterAdapter implements FormatterAdapter {
     const endMarker = this.sectionEnd(section);
 
     if (!input.length) {
-      return this.appendContent(startMarker, this.lineBreak(), endMarker);
+      return this.appendContent(
+        startMarker,
+        this.lineBreak(),
+        endMarker,
+        this.lineBreak()
+      );
     }
 
     return this.appendContent(

packages/core/src/renderer/file-renderer.adapter.e2e.spec.ts

@@ -23,28 +23,28 @@ describe('FileRendererAdapter', () => {
     mockFs({
       '/test': {
         'document.md': 'Initial content\nSome text\n',
-        'existing-section.md': [
-          'Content before section',
-          '<!-- examples:start -->',
-          'Old section content',
-          '<!-- examples:end -->',
-          'Content after section',
-          '',
-        ].join('\n'),
-        'multiple-sections.md': [
-          'Header content',
-          '<!-- examples:start -->',
-          '',
-          'First section content',
-          '',
-          '<!-- examples:end -->',
-          'Middle content',
-          '<!-- usage:start -->',
-          'Second section content',
-          '<!-- usage:end -->',
-          'Footer content',
-          '',
-        ].join('\n'),
+        'existing-section.md': `Content before section
+<!-- examples:start -->
+Old section content
+<!-- examples:end -->
+Content after section
+`,
+        'multiple-sections.md': `Header content
+<!-- usage:start -->
+Second section content
+<!-- usage:end -->
+Middle content
+<!-- examples:start -->
+
+First section content
+
+<!-- examples:end -->
+<!-- security:start -->
+<!-- security:end -->
+<!-- license:start -->
+License content
+<!-- license:end -->
+`,
         'empty.md': '',
       },
       '/unsupported': {
@@ -77,11 +77,14 @@ describe('FileRendererAdapter', () => {
 
       // Assert
       const fileContent = readFileSync(testFilePath, 'utf-8');
-      expect(fileContent).toContain('Initial content');
-      expect(fileContent).toContain('Some text');
-      expect(fileContent).toContain(`<!-- ${testSectionIdentifier}:start -->`);
-      expect(fileContent).toContain('New section content');
-      expect(fileContent).toContain(`<!-- ${testSectionIdentifier}:end -->`);
+      expect(fileContent).toEqual(`Initial content
+Some text
+<!-- examples:start -->
+
+New section content
+
+<!-- examples:end -->
+`);
     });
 
     it('should replace existing section content when section already exists', async () => {
@@ -94,12 +97,14 @@ describe('FileRendererAdapter', () => {
 
       // Assert
       const fileContent = readFileSync('/test/existing-section.md', 'utf-8');
-      expect(fileContent).toContain('Content before section');
-      expect(fileContent).toContain('Content after section');
-      expect(fileContent).toContain(`<!-- ${testSectionIdentifier}:start -->`);
-      expect(fileContent).toContain('New section content');
-      expect(fileContent).toContain(`<!-- ${testSectionIdentifier}:end -->`);
-      expect(fileContent).not.toContain('Old section content');
+      expect(fileContent).toEqual(`Content before section
+<!-- examples:start -->
+
+New section content
+
+<!-- examples:end -->
+Content after section
+`);
     });
 
     it('should handle empty files correctly', async () => {
@@ -124,29 +129,38 @@ New section content
     it('should handle multiple sections without affecting other sections', async () => {
       // Arrange
       const multipleSectionsAdapter = new FileRendererAdapter(new FileReaderAdapter());
-      const newData = Buffer.from('Updated second section\n');
+      const newUsageContent = Buffer.from('Updated usage section\n');
+      const newLicenseContent = Buffer.from('Updated license section\n');
 
       // Act
       await multipleSectionsAdapter.initialize('/test/multiple-sections.md', formatterAdapter);
-      await multipleSectionsAdapter.writeSection(SectionIdentifier.Usage, newData);
+      await multipleSectionsAdapter.writeSection(SectionIdentifier.Usage, newUsageContent);
+      await multipleSectionsAdapter.writeSection(SectionIdentifier.Security, Buffer.alloc(0)); // Empty content for security section
+      await multipleSectionsAdapter.writeSection(SectionIdentifier.License, newLicenseContent);
 
       // Assert
       const fileContent = readFileSync('/test/multiple-sections.md', 'utf-8');
 
       // Should preserve first section with blank lines around content
       expect(fileContent).toEqual(`Header content
+<!-- usage:start -->
+
+Updated usage section
+
+<!-- usage:end -->
+Middle content
 <!-- examples:start -->
 
 First section content
 
 <!-- examples:end -->
-Middle content
-<!-- usage:start -->
+<!-- security:start -->
+<!-- security:end -->
+<!-- license:start -->
 
-Updated second section
+Updated license section
 
-<!-- usage:end -->
-Footer content
+<!-- license:end -->
 `);
     });
 

packages/core/src/renderer/file-renderer.adapter.ts

@@ -20,15 +20,15 @@ export class FileRendererAdapter extends AbstractRendererAdapter {
         super();
     }
 
-    async replaceContent(data: ReadableContent): Promise<void> {
+    async replaceContent(content: ReadableContent): Promise<void> {
         await this.safeWriteWithLock(async () => {
-            return this.performReplaceContent(data);
+            return this.performReplaceContent(content);
         });
     }
 
-    async writeSection(sectionIdentifier: SectionIdentifier, data: ReadableContent): Promise<void> {
+    async writeSection(sectionIdentifier: SectionIdentifier, content: ReadableContent): Promise<void> {
         await this.safeWriteWithLock(async () => {
-            return this.performWriteSection(sectionIdentifier, data);
+            return this.performWriteSection(sectionIdentifier, content);
         });
     }
 
@@ -44,11 +44,11 @@ export class FileRendererAdapter extends AbstractRendererAdapter {
         return undefined;
     }
 
-    private performReplaceContent(data: ReadableContent): Promise<void> {
+    private performReplaceContent(content: ReadableContent): Promise<void> {
         const destination = this.getDestination();
 
         return new Promise((resolve, reject) => {
-            writeFile(destination, data, (err) => {
+            writeFile(destination, content, (err) => {
                 if (err) {
                     reject(err);
                 } else {
@@ -58,12 +58,20 @@ export class FileRendererAdapter extends AbstractRendererAdapter {
         });
     }
 
-    private performWriteSection(sectionIdentifier: SectionIdentifier, data: ReadableContent): Promise<void> {
+    private performWriteSection(sectionIdentifier: SectionIdentifier, content: ReadableContent): Promise<void> {
         const destination = this.getDestination();
         const formatterAdapter = this.getFormatterAdapter();
 
-        // Look for the section in the file, replace content if it exists, or append if it doesn't.
+        const sectionContent = formatterAdapter.section(
+            sectionIdentifier,
+            content
+        );
+
+        const sectionStart = formatterAdapter.sectionStart(sectionIdentifier).toString();
+        const sectionEnd = formatterAdapter.sectionEnd(sectionIdentifier).toString();
 
+
+        // Look for the section in the file, replace content if it exists, or append if it doesn't.
         // Read file line by line to find the section
         return new Promise((resolve, reject) => {
             try {
@@ -87,15 +95,6 @@ export class FileRendererAdapter extends AbstractRendererAdapter {
                 let inSection = false;
                 let output: ReadableContent = Buffer.alloc(0);
 
-
-                const sectionContent = formatterAdapter.section(
-                    sectionIdentifier,
-                    data
-                );
-
-                const sectionStart = formatterAdapter.sectionStart(sectionIdentifier).toString();
-                const sectionEnd = formatterAdapter.sectionEnd(sectionIdentifier).toString();
-
                 readLine.on('line', (line) => {
                     const isSectionStart = line.trim() === sectionStart;
                     if (isSectionStart) {

packages/core/src/renderer/renderer.adapter.ts

@@ -19,14 +19,14 @@ export interface RendererAdapter {
 
     getDestination(): string;
 
-    writeSection(sectionIdentifier: string, data: ReadableContent): Promise<void>;
+    writeSection(sectionIdentifier: string, content: ReadableContent): Promise<void>;
 
     /**
      * Replace the entire content at the destination with the provided data.
      * This is useful for migration scenarios where the entire content needs
      * to be transformed and replaced, rather than appending sections.
      */
-    replaceContent(data: ReadableContent): Promise<void>;
+    replaceContent(content: ReadableContent): Promise<void>;
 
     /**
      * Finalize the rendering process and cleanup initialization.

packages/docs/README.md

@@ -1,3 +1,5 @@
-# Site
+# Docs Package
+
+The `@ci-dokumentor/docs` package contains the documentation site for the project.
 
 This site is built using [Docusaurus](https://docusaurus.io/), a modern static site generator.