Enhanced ReadableContentHandler.append to accept strings directly, eliminating many .from() calls

Co-authored-by: neilime <314088+neilime@users.noreply.github.com>

Author: Copilot

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

@@ -1,8 +1,8 @@
 import { injectable, inject } from 'inversify';
 import { StringDecoder } from 'string_decoder';
 import { MigrationAdapter, SectionIdentifier, FileReaderAdapter } from '@ci-dokumentor/core';
-import { ReadableContentHandler } from '@ci-dokumentor/core';
-import type { FormatterAdapter, MigrateDocumentationPayload, ReadableContent, ReadableContentHandler, ReaderAdapter } from '@ci-dokumentor/core';
+import { ReadableContent } from '@ci-dokumentor/core';
+import type { FormatterAdapter, MigrateDocumentationPayload, ReadableContent, ReadableContent, ReaderAdapter } from '@ci-dokumentor/core';
 
 /**
  * Abstract base class for migration adapters in the github-actions package.
@@ -89,14 +89,14 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
         await rendererAdapter.replaceContent(content);
     }
 
-    protected abstract migrateContent(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent;
+    protected abstract migrateContent(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent;
 
     /**
      * Generic helper that replaces tool-specific start/end markers inside a
      * content fragment with the standardized ci-dokumentor markers using the
      * configured patterns and section mappings.
      */
-    protected processMarkerMappings(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent {
+    protected processMarkerMappings(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent {
         // Process the fragment line-by-line to avoid allocating a single large
         // string for the entire fragment. We still perform replacements on each
         // line using the configured start/end patterns, but the scope is the
@@ -125,9 +125,9 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
                     // Alternate between start and end on successive matches
                     seenToggle = !seenToggle;
                     if (seenToggle) {
-                        return ReadableContentHandler.append(formatterAdapter.sectionStart(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
+                        return ReadableContent.append(formatterAdapter.sectionStart(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
                     }
-                    return ReadableContentHandler.append(formatterAdapter.lineBreak(), formatterAdapter.sectionEnd(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
+                    return ReadableContent.append(formatterAdapter.lineBreak(), formatterAdapter.sectionEnd(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
                 });
             } else {
                 // Replace end then start to avoid nested replacement issues when
@@ -138,7 +138,7 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
                         if (!standardSection) {
                             return '';
                         }
-                        return ReadableContentHandler.append(formatterAdapter.lineBreak(), formatterAdapter.sectionEnd(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
+                        return ReadableContent.append(formatterAdapter.lineBreak(), formatterAdapter.sectionEnd(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
                     });
                 }
 
@@ -148,12 +148,12 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
                         if (!standardSection) {
                             return '';
                         }
-                        return ReadableContentHandler.append(formatterAdapter.sectionStart(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
+                        return ReadableContent.append(formatterAdapter.sectionStart(standardSection), formatterAdapter.lineBreak()).toString('utf-8');
                     });
                 }
             }
 
-            parts.push(ReadableContentHandler.from(out));
+            parts.push(ReadableContent.from(out));
 
             if (addNewline) {
                 parts.push(formatterAdapter.lineBreak());
@@ -180,7 +180,7 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
             processLine(rem, false);
         }
 
-        return ReadableContentHandler.append(...parts);
+        return ReadableContent.append(...parts);
     }
 
     protected mapToStandardSection(sectionName: string) {
@@ -191,7 +191,7 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
     /**
      * Merge consecutive sections that map to the same target section
      */
-    private mergeConsecutiveSections(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent {
+    private mergeConsecutiveSections(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent {
         let result = content.toString('utf-8');
 
         // Pattern to match section start and end markers
@@ -253,20 +253,20 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
                 const mergedContent = group.contents.join('').replace(/^\s*\n|\n\s*$/g, '').trim();
                 const replacement = formatterAdapter.section(
                     group.type,
-                    ReadableContentHandler.from(mergedContent)
+                    ReadableContent.from(mergedContent)
                 ).toString('utf-8');
 
                 result = result.substring(0, group.start) + replacement.trim() + result.substring(group.end);
             }
         });
 
-        return ReadableContentHandler.from(result);
+        return ReadableContent.from(result);
     }
 
     /**
      * Add missing supported section markers in the appropriate positions
      */
-    private addMissingSections(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent {
+    private addMissingSections(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent {
 
         const expectedSections: SectionIdentifier[] = Object.values(SectionIdentifier);
 
@@ -338,20 +338,20 @@ export abstract class AbstractMigrationAdapter implements MigrationAdapter {
 
                 // If before doesn't end with a newline, add one
                 const sep = /\n$/.test(before) ? '' : '\n';
-                content = ReadableContentHandler.append(
-                    ReadableContentHandler.from(before),
-                    ReadableContentHandler.from(sep),
+                content = ReadableContent.append(
+                    ReadableContent.from(before),
+                    ReadableContent.from(sep),
                     formatterAdapter.lineBreak(),
                     sectionContent,
-                    after.trim().length > 0 ? ReadableContentHandler.from(after) : Buffer.alloc(0)
+                    after.trim().length > 0 ? ReadableContent.from(after) : Buffer.alloc(0)
                 );
             } else {
                 // No suitable anchor, append at end with a preceding newline
                 const sep = /\n$/.test(contentString) ? '' : '\n';
 
-                content = ReadableContentHandler.append(
+                content = ReadableContent.append(
                     content,
-                    ReadableContentHandler.from(sep),
+                    ReadableContent.from(sep),
                     formatterAdapter.lineBreak(),
                     sectionContent,
                 );

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

@@ -33,7 +33,7 @@ export class ActdocsMigrationAdapter extends AbstractMigrationAdapter {
     detectionPattern: /<!--\s*actdocs\s+\w+\s+(start|end)\s*-->/i,
   };
 
-  protected migrateContent(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent {
+  protected migrateContent(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent {
     // Delegate the replacement logic to the shared helper in the abstract class.
     return this.processMarkerMappings(content, formatterAdapter);
   }

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

@@ -33,7 +33,7 @@ export class ActionDocsMigrationAdapter extends AbstractMigrationAdapter {
     detectionPattern: /<!--\s*action-docs-\w+\s+source=["'][^"']+["']\s*-->/,
   };
 
-  protected migrateContent(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent {
+  protected migrateContent(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent {
     // Delegate marker replacement and mapping to the base class helper which
     // operates on the provided content fragment to avoid allocating large
     // intermediate strings here.

packages/cicd/github-actions/src/migration/auto-doc-migration.adapter.ts

@@ -1,7 +1,7 @@
 import { injectable, injectFromBase } from 'inversify';
 import { StringDecoder } from 'string_decoder';
 import { SectionIdentifier } from '@ci-dokumentor/core';
-import { ReadableContentHandler } from '@ci-dokumentor/core';
+import { ReadableContent } from '@ci-dokumentor/core';
 import type { FormatterAdapter, ReadableContent } from '@ci-dokumentor/core';
 import { AbstractMigrationAdapter } from './abstract-migration.adapter.js';
 
@@ -32,7 +32,7 @@ export class AutoDocMigrationAdapter extends AbstractMigrationAdapter {
     detectionPattern: /^##\s+(Inputs|Outputs|Secrets|Description)\s*$/m,
   };
 
-  protected migrateContent(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent {
+  protected migrateContent(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent {
 
     const decoder = new StringDecoder('utf8');
     const chunkSize = 8 * 1024;
@@ -53,14 +53,14 @@ export class AutoDocMigrationAdapter extends AbstractMigrationAdapter {
       const sectionIdentifier = this.mapToStandardSection(current.sectionKey.toLowerCase());
       if (sectionIdentifier) {
         const contentPart = current.parts.length
-          ? ReadableContentHandler.append(ReadableContentHandler.from(current.headerLine), formatterAdapter.lineBreak(), ...current.parts)
-          : ReadableContentHandler.from(current.headerLine);
+          ? ReadableContent.append(ReadableContent.from(current.headerLine), formatterAdapter.lineBreak(), ...current.parts)
+          : ReadableContent.from(current.headerLine);
         const wrapped = formatterAdapter.section(sectionIdentifier, contentPart);
         outputParts.push(wrapped);
       } else {
         // Unknown section: emit original header + content as-is
-        outputParts.push(ReadableContentHandler.from(current.headerLine), formatterAdapter.lineBreak());
-        if (current.parts.length) outputParts.push(ReadableContentHandler.append(...current.parts));
+        outputParts.push(ReadableContent.from(current.headerLine), formatterAdapter.lineBreak());
+        if (current.parts.length) outputParts.push(ReadableContent.append(...current.parts));
       }
       current = null;
     };
@@ -80,10 +80,10 @@ export class AutoDocMigrationAdapter extends AbstractMigrationAdapter {
 
       // Not a header
       if (current) {
-        current.parts.push(ReadableContentHandler.from(line), formatterAdapter.lineBreak());
+        current.parts.push(ReadableContent.from(line), formatterAdapter.lineBreak());
       } else {
         // Outside any section, preserve original content
-        outputParts.push(ReadableContentHandler.from(line), formatterAdapter.lineBreak());
+        outputParts.push(ReadableContent.from(line), formatterAdapter.lineBreak());
       }
     };
 
@@ -107,6 +107,6 @@ export class AutoDocMigrationAdapter extends AbstractMigrationAdapter {
     // Flush any final open section
     flushCurrent();
 
-    return ReadableContentHandler.append(...outputParts);
+    return ReadableContent.append(...outputParts);
   }
 }

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

@@ -41,7 +41,7 @@ export class GitHubActionReadmeGeneratorMigrationAdapter extends AbstractMigrati
     detectionPattern: /<!--\s*(start|end)\s+[\w[\]/.-]+\s*-->/,
   };
 
-  protected migrateContent(content: ReadableContent, ReadableContentHandler, formatterAdapter: FormatterAdapter): ReadableContent {
+  protected migrateContent(content: ReadableContent, ReadableContent, formatterAdapter: FormatterAdapter): ReadableContent {
     // The adapter needs some special normalization for example paths; we
     // perform normalization first by mapping any examples-like identifiers to
     // a canonical 'examples' key inside the fragment before handing it to the

packages/cicd/github-actions/src/section/badges-section-generator.adapter.ts

@@ -1,4 +1,4 @@
-import { ReadableContent, ReadableContentHandler, ReadableContent, ReadableContentHandler, RepositoryProvider, SectionGenerationPayload, SectionGeneratorAdapter, SectionOptions } from '@ci-dokumentor/core';
+import { ReadableContent, ReadableContent, ReadableContent, ReadableContent, RepositoryProvider, SectionGenerationPayload, SectionGeneratorAdapter, SectionOptions } from '@ci-dokumentor/core';
 import { GitHubActionsManifest } from '../github-actions-parser.js';
 import { GitHubActionsSectionGeneratorAdapter } from './github-actions-section-generator.adapter.js';
 import { FormatterAdapter, SectionIdentifier } from '@ci-dokumentor/core';
@@ -194,16 +194,16 @@ export class BadgesSectionGenerator extends GitHubActionsSectionGeneratorAdapter
     }
 
     const badgeCollectionContent = linkedBadges.map((linkedBadge) => {
-      let badgeContent = formatterAdapter.badge(ReadableContentHandler.from(linkedBadge.badge.label).from(linkedBadge.badge.url));
+      let badgeContent = formatterAdapter.badge(ReadableContent.from(linkedBadge.badge.label).from(linkedBadge.badge.url));
       if (linkedBadge.url) {
         badgeContent = formatterAdapter.link(
           badgeContent,
-          ReadableContentHandler.from(linkedBadge.url)
+          ReadableContent.from(linkedBadge.url)
         );
       }
       return [badgeContent, formatterAdapter.lineBreak()];
     }).flat();
 
-    return ReadableContentHandler.append(...badgeCollectionContent);
+    return ReadableContent.append(...badgeCollectionContent);
   }
 }

packages/cicd/github-actions/src/section/contributing-section-generator.adapter.ts

@@ -1,4 +1,4 @@
-import { ReadableContent, ReadableContentHandler, ReadableContent, ReadableContentHandler, SectionGenerationPayload } from '@ci-dokumentor/core';
+import { ReadableContent, ReadableContent, ReadableContent, ReadableContent, SectionGenerationPayload } from '@ci-dokumentor/core';
 import { GitHubActionsManifest } from '../github-actions-parser.js';
 import { GitHubActionsSectionGeneratorAdapter } from './github-actions-section-generator.adapter.js';
 import { SectionIdentifier } from '@ci-dokumentor/core';
@@ -19,10 +19,10 @@ export class ContributingSectionGenerator extends GitHubActionsSectionGeneratorA
 
     const contributingText = `Contributions are welcome! Please see the [contributing guidelines](${contributingInfo.url}) for more details.`;
 
-    return ReadableContentHandler.append(
-      formatterAdapter.heading(ReadableContentHandler.from('Contributing'), 2),
+    return ReadableContent.append(
+      formatterAdapter.heading(ReadableContent.from('Contributing'), 2),
       formatterAdapter.lineBreak(),
-      formatterAdapter.paragraph(ReadableContentHandler.from(contributingText)),
+      formatterAdapter.paragraph(ReadableContent.from(contributingText)),
     );
   }
 }

packages/cicd/github-actions/src/section/examples-section-generator.adapter.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach, vi, Mocked } from 'vitest';
 import { ExamplesSectionGenerator } from './examples-section-generator.adapter.js';
-import { VersionService, SectionIdentifier, ManifestVersion, ReadableContent, ReadableContentHandler, FormatterAdapter, RepositoryProvider, ReaderAdapter } from '@ci-dokumentor/core';
+import { VersionService, SectionIdentifier, ManifestVersion, ReadableContent, ReadableContent, FormatterAdapter, RepositoryProvider, ReaderAdapter } from '@ci-dokumentor/core';
 import { GitHubAction, GitHubWorkflow } from '../github-actions-parser.js';
 import { ReaderAdapterMockFactory, RepositoryInfoMockFactory, RepositoryProviderMockFactory, VersionServiceMockFactory } from '@ci-dokumentor/core/tests';
 

packages/cicd/github-actions/src/section/examples-section-generator.adapter.ts

@@ -102,7 +102,7 @@ export class ExamplesSectionGenerator extends GitHubActionsSectionGeneratorAdapt
       }
     }
 
-    return ReadableContentHandler.append(...examplesContent);
+    return ReadableContent.append(...examplesContent);
   }
 
   /**
@@ -289,7 +289,7 @@ export class ExamplesSectionGenerator extends GitHubActionsSectionGeneratorAdapt
   /**
    * Process code snippets to replace or add version information for action calls
    */
-  private processCodeSnippet(code: ReadableContent, ReadableContentHandler, usesName: string, version?: ManifestVersion): ReadableContent {
+  private processCodeSnippet(code: ReadableContent, ReadableContent, usesName: string, version?: ManifestVersion): ReadableContent {
     if (!version || !version.sha) {
       return code;
     }

packages/cicd/github-actions/src/section/generated-section-generator.adapter.ts

@@ -1,4 +1,4 @@
-import { ReadableContent, ReadableContentHandler, ReadableContent, ReadableContentHandler, SectionGenerationPayload } from '@ci-dokumentor/core';
+import { ReadableContent, ReadableContent, ReadableContent, ReadableContent, SectionGenerationPayload } from '@ci-dokumentor/core';
 import { GitHubActionsManifest } from '../github-actions-parser.js';
 import { GitHubActionsSectionGeneratorAdapter } from './github-actions-section-generator.adapter.js';
 import { SectionIdentifier } from '@ci-dokumentor/core';
@@ -13,10 +13,10 @@ export class GeneratedSectionGenerator extends GitHubActionsSectionGeneratorAdap
   async generateSection({ formatterAdapter }: SectionGenerationPayload<GitHubActionsManifest>): Promise<ReadableContent> {
     const generatedText = 'This documentation was automatically generated by [CI Dokumentor](https://github.com/hoverkraft-tech/ci-dokumentor).';
 
-    return ReadableContentHandler.append(
+    return ReadableContent.append(
       formatterAdapter.horizontalRule(),
       formatterAdapter.lineBreak(),
-      formatterAdapter.paragraph(ReadableContentHandler.from(generatedText)),
+      formatterAdapter.paragraph(ReadableContent.from(generatedText)),
     );
   }
 }