feat: add protective comment to auto-generated markdown files

Author: suin

examples/per-kind-output/apps.example.com-v2-webapp.md

@@ -1,5 +1,7 @@
 # WebApp
 
+<!-- This file is auto-generated by KARG (https://github.com/appthrust/karg). Please don't edit it manually - your changes will be overwritten when the file is regenerated. -->
+
 WebApp represents a web application deployment
 
 - **API version:** `apps.example.com/v2`

examples/per-kind-output/data.example.com-v1beta1-database.md

@@ -1,5 +1,7 @@
 # Database
 
+<!-- This file is auto-generated by KARG (https://github.com/appthrust/karg). Please don't edit it manually - your changes will be overwritten when the file is regenerated. -->
+
 Database represents a **managed database instance** with automated backups and high availability.
 
 ## Supported Engines

examples/per-kind-output/library.example.com-v1-book.md

@@ -1,5 +1,7 @@
 # Book
 
+<!-- This file is auto-generated by KARG (https://github.com/appthrust/karg). Please don't edit it manually - your changes will be overwritten when the file is regenerated. -->
+
 Book represents a book in the library catalog system.
 
 ## Overview

examples/single-file-output.md

@@ -1,5 +1,7 @@
 # API Documentation
 
+<!-- This file is auto-generated by KARG (https://github.com/appthrust/karg). Please don't edit it manually - your changes will be overwritten when the file is regenerated. -->
+
 - [Book](#book)
 - [Database](#database)
 - [WebApp](#webapp)

ts/writer/__tests__/markdown.test.ts

@@ -61,17 +61,29 @@ describe("markdown writer", () => {
       expect(result).toContain("Name of the resource");
     });
 
+    test("inserts protective comment after H1 heading", () => {
+      const apiDoc = createAPIDoc("TestResource");
+
+      const result = renderAPIDocumentation(apiDoc);
+
+      // Check that comment appears after the heading
+      expect(result).toContain(
+        "# TestResource\n\n<!-- This file is auto-generated by KARG (https://github.com/appthrust/karg). " +
+          "Please don't edit it manually - your changes will be overwritten when the file is regenerated. -->"
+      );
+    });
+
     test("includes description when provided", () => {
       const apiDoc = createAPIDoc("TestResource", [], [], {
         description: "This is a test resource for unit testing.",
       });
 
       const result = renderAPIDocumentation(apiDoc);
 
-      // Description appears right after the title, not in a separate section
-      expect(result).toContain(
-        "# TestResource\n\nThis is a test resource for unit testing."
-      );
+      // Description appears after the title and protective comment
+      expect(result).toContain("# TestResource");
+      expect(result).toContain("<!-- This file is auto-generated by KARG");
+      expect(result).toContain("This is a test resource for unit testing.");
     });
 
     test("renders API description with Markdown formatting", () => {
@@ -119,8 +131,10 @@ spec:
       expect(result).toContain("kind: Book"); // Content inside code block
       expect(result).toContain("*special handling*"); // Italic text (converted from underscores)
 
-      // Ensure the description appears right after the main title
-      expect(result).toContain("# Book\n\nThis resource manages **books**");
+      // Ensure the description appears after the title and comment
+      expect(result).toContain("# Book");
+      expect(result).toContain("<!-- This file is auto-generated by KARG");
+      expect(result).toContain("This resource manages **books**");
     });
 
     test("handles API description with complex nested Markdown", () => {
@@ -178,8 +192,12 @@ spec:
       const apiDocNoDesc = createAPIDoc("TestResource");
       const resultNoDesc = renderAPIDocumentation(apiDocNoDesc);
 
-      // Should not have extra blank lines after title
-      expect(resultNoDesc).toContain("# TestResource\n\n- **API version:**");
+      // Should have title, comment, then API version
+      expect(resultNoDesc).toContain("# TestResource");
+      expect(resultNoDesc).toContain(
+        "<!-- This file is auto-generated by KARG"
+      );
+      expect(resultNoDesc).toContain("- **API version:**");
 
       // Test with empty string description
       const apiDocEmptyDesc = createAPIDoc("TestResource", [], [], {
@@ -188,7 +206,11 @@ spec:
       const resultEmptyDesc = renderAPIDocumentation(apiDocEmptyDesc);
 
       // Should handle empty description gracefully
-      expect(resultEmptyDesc).toContain("# TestResource\n\n- **API version:**");
+      expect(resultEmptyDesc).toContain("# TestResource");
+      expect(resultEmptyDesc).toContain(
+        "<!-- This file is auto-generated by KARG"
+      );
+      expect(resultEmptyDesc).toContain("- **API version:**");
     });
 
     test("includes metadata details", () => {
@@ -824,6 +846,22 @@ Default configuration uses PostgreSQL.`;
       expect(result).toContain("spec.fieldB");
     });
 
+    test("inserts protective comment after main H1 heading", () => {
+      const apiDocs = [createAPIDoc("ResourceA"), createAPIDoc("ResourceB")];
+
+      const result = renderCombinedDocumentation(apiDocs);
+
+      // Check that comment appears after the main heading
+      expect(result).toContain(
+        "# API Documentation\n\n<!-- This file is auto-generated by KARG (https://github.com/appthrust/karg). " +
+          "Please don't edit it manually - your changes will be overwritten when the file is regenerated. -->"
+      );
+
+      // Comment should only appear once at the top, not for each resource
+      const commentMatches = result.match(/<!-- This file is auto-generated/g);
+      expect(commentMatches?.length).toBe(1);
+    });
+
     test("creates table of contents", () => {
       const apiDocs = [
         createAPIDoc("Book"),
@@ -872,12 +910,18 @@ Default configuration uses PostgreSQL.`;
 
       const result = renderCombinedDocumentation(apiDocs);
 
+      // Check that protective comment is at the top
+      expect(result).toContain("# API Documentation");
+      expect(result).toContain("<!-- This file is auto-generated by KARG");
+
       // Check that descriptions are rendered with Markdown
-      expect(result).toContain("## Author\n\nRepresents book authors.");
+      expect(result).toContain("## Author");
+      expect(result).toContain("Represents book authors.");
       expect(result).toContain("- Supports multiple pen names");
       expect(result).toContain("Links to [books](#book)");
 
-      expect(result).toContain("## Book\n\nManages **books**");
+      expect(result).toContain("## Book");
+      expect(result).toContain("Manages **books**");
       expect(result).toContain("*metadata*");
       expect(result).toContain("`ISBN`");
     });
@@ -924,7 +968,12 @@ Default configuration uses PostgreSQL.`;
 
       const result = renderAPIDocumentation(apiDoc);
 
-      // Check that there's a blank line between description and metadata
+      // Check that there's a protective comment and a blank line between description and metadata
+      expect(result).toContain("# TestResource");
+      expect(result).toContain("<!-- This file is auto-generated by KARG");
+      expect(result).toContain(
+        "This is a test resource for testing blank lines"
+      );
       expect(result).toContain(
         "This is a test resource for testing blank lines\n\n- **API version:**"
       );

ts/writer/markdown.ts

@@ -4,6 +4,7 @@ import type {
   FootnoteDefinition,
   FootnoteReference,
   Heading,
+  Html,
   InlineCode,
   Link,
   List,
@@ -93,6 +94,9 @@ export function renderCombinedDocumentation(
   // Add main title
   children.push(heading(1, "API Documentation"));
 
+  // Insert protective comment after main title
+  children.push(protectiveComment() as RootContent);
+
   // Sort API docs alphabetically by Kind name
   const sortedApiDocs = [...apiDocs].sort((a, b) =>
     a.kind.localeCompare(b.kind)
@@ -109,7 +113,7 @@ export function renderCombinedDocumentation(
 
   // Add each API documentation with base heading level 2
   for (const apiDoc of sortedApiDocs) {
-    const apiAST = buildDocumentASTWithFootnotes(apiDoc, 2, footnotes);
+    const apiAST = buildDocumentASTWithFootnotes(apiDoc, 2, footnotes, false);
     // Add all children except footnote definitions (we'll add them at the end)
     children.push(
       ...apiAST.children.filter((child) => child.type !== "footnoteDefinition")
@@ -187,14 +191,20 @@ export function renderCombinedDocumentation(
 function buildDocumentASTWithFootnotes(
   apiDoc: APIDocumentation,
   baseHeadingLevel: number,
-  footnotes: Map<string, string>
+  footnotes: Map<string, string>,
+  includeProtectiveComment = true
 ): Root {
   const children: Array<RootContent> = [];
 
   // Title
   children.push(heading(baseHeadingLevel, apiDoc.title));
 
-  // API description (right after title)
+  // Insert protective comment after title only if requested
+  if (includeProtectiveComment) {
+    children.push(protectiveComment() as RootContent);
+  }
+
+  // API description (right after title and comment)
   if (apiDoc.description) {
     const parsed = fromMarkdown(apiDoc.description, {
       extensions: [gfmTable()],
@@ -579,6 +589,14 @@ function addExamplesToList(
 }
 
 // AST helper functions (Low-level abstraction)
+function protectiveComment(): Html {
+  return u(
+    "html",
+    "<!-- This file is auto-generated by KARG (https://github.com/appthrust/karg). " +
+      "Please don't edit it manually - your changes will be overwritten when the file is regenerated. -->"
+  ) as Html;
+}
+
 function heading(
   depth: number,
   content: string | Array<PhrasingContent>