From cd16787af923ed581d8bc1570a10ee849c3d84c1 Mon Sep 17 00:00:00 2001
From: Kazuki Yamada <koukun0120@gmail.com>
Date: Sat, 28 Sep 2024 18:56:27 +0900
Subject: [PATCH] feat(style): Add Markdown output style

---
 .gitignore                                    |  1 +
 README.md                                     | 43 +++++++++-
 src/cli/cliRunner.ts                          |  2 +-
 src/config/configTypes.ts                     |  2 +-
 src/core/output/markdownStyleGenerator.ts     | 81 +++++++++++++++++++
 src/core/output/outputGenerator.ts            |  4 +
 src/core/output/plainStyleGenerator.ts        | 28 +++----
 src/core/output/xmlStyleGenerator.ts          |  2 +-
 .../output/markdownStyleGenerator.test.ts     | 34 ++++++++
 9 files changed, 177 insertions(+), 20 deletions(-)
 create mode 100644 src/core/output/markdownStyleGenerator.ts
 create mode 100644 tests/core/output/markdownStyleGenerator.test.ts

diff --git a/.gitignore b/.gitignore
index d3593d30..cc49991d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,6 +24,7 @@ coverage/
 # Repopack output
 repopack-output.txt
 repopack-output.xml
+repopack-output.md
 
 # ESLint cache
 .eslintcache
diff --git a/README.md b/README.md
index 1bbdb818..5462669c 100644
--- a/README.md
+++ b/README.md
@@ -223,6 +223,45 @@ https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-
 
 This means that the XML output from Repopack is not just a different format, but potentially a more effective way to feed your codebase into AI systems for analysis, code review, or other tasks.
 
+#### Markdown Format
+
+To generate output in Markdown format, use the `--style markdown` option:
+```bash
+repopack --style markdown
+```
+
+The Markdown format structures the content in a hierarchical manner:
+
+````markdown
+This file is a merged representation of the entire codebase, combining all repository files into a single document.
+
+# File Summary
+(Metadata and usage AI instructions)
+
+# Repository Structure
+```
+src/
+  cli/
+    cliOutput.ts
+    index.ts
+```
+(...remaining directories)
+
+# Repository Files
+
+## File: src/index.js
+```
+// File contents here
+```
+
+(...remaining files)
+
+# Instruction
+(Custom instructions from `output.instructionFilePath`)
+````
+
+This format provides a clean, readable structure that is both human-friendly and easily parseable by AI systems.
+
 ### Command Line Options
 
 - `-v, --version`: Show tool version
@@ -230,7 +269,7 @@ This means that the XML output from Repopack is not just a different format, but
 - `--include <patterns>`: List of include patterns (comma-separated)
 - `-i, --ignore <patterns>`: Additional ignore patterns (comma-separated)
 - `-c, --config <path>`: Path to a custom config file
-- `--style <style>`: Specify the output style (`plain` or `xml`)
+- `--style <style>`: Specify the output style (`plain`, `xml`, `markdown`)
 - `--top-files-len <number>`: Number of top files to display in the summary
 - `--output-show-line-numbers`: Show line numbers in the output
 - `--remote <url>`: Process a remote Git repository
@@ -290,7 +329,7 @@ Here's an explanation of the configuration options:
 | Option | Description | Default |
 |--------|-------------|---------|
 |`output.filePath`| The name of the output file | `"repopack-output.txt"` |
-|`output.style`| The style of the output (`plain`, `xml`) |`"plain"`|
+|`output.style`| The style of the output (`plain`, `xml`, `markdown`) |`"plain"`|
 |`output.headerText`| Custom text to include in the file header |`null`|
 |`output.instructionFilePath`| Path to a file containing detailed custom instructions |`null`|
 |`output.removeComments`| Whether to remove comments from supported file types | `false` |
diff --git a/src/cli/cliRunner.ts b/src/cli/cliRunner.ts
index d6c3c3f9..047e227f 100644
--- a/src/cli/cliRunner.ts
+++ b/src/cli/cliRunner.ts
@@ -39,7 +39,7 @@ export async function run() {
       .option('-c, --config <path>', 'path to a custom config file')
       .option('--top-files-len <number>', 'specify the number of top files to display', Number.parseInt)
       .option('--output-show-line-numbers', 'add line numbers to each line in the output')
-      .option('--style <type>', 'specify the output style (plain or xml)')
+      .option('--style <type>', 'specify the output style (plain, xml, markdown)')
       .option('--verbose', 'enable verbose logging for detailed output')
       .option('--init', 'initialize a new repopack.config.json file')
       .option('--global', 'use global configuration (only applicable with --init)')
diff --git a/src/config/configTypes.ts b/src/config/configTypes.ts
index 65a24506..9c61a092 100644
--- a/src/config/configTypes.ts
+++ b/src/config/configTypes.ts
@@ -1,4 +1,4 @@
-export type RepopackOutputStyle = 'plain' | 'xml';
+export type RepopackOutputStyle = 'plain' | 'xml' | 'markdown';
 
 interface RepopackConfigBase {
   output?: {
diff --git a/src/core/output/markdownStyleGenerator.ts b/src/core/output/markdownStyleGenerator.ts
new file mode 100644
index 00000000..693629d8
--- /dev/null
+++ b/src/core/output/markdownStyleGenerator.ts
@@ -0,0 +1,81 @@
+import Handlebars from 'handlebars';
+import type { OutputGeneratorContext } from './outputGeneratorTypes.js';
+import {
+  generateHeader,
+  generateSummaryAdditionalInfo,
+  generateSummaryFileFormat,
+  generateSummaryNotes,
+  generateSummaryPurpose,
+  generateSummaryUsageGuidelines,
+} from './outputStyleDecorator.js';
+
+export const generateMarkdownStyle = (outputGeneratorContext: OutputGeneratorContext) => {
+  const template = Handlebars.compile(markdownTemplate);
+
+  const renderContext = {
+    generationHeader: generateHeader(outputGeneratorContext.generationDate),
+    summaryPurpose: generateSummaryPurpose(),
+    summaryFileFormat: generateSummaryFileFormat(),
+    summaryUsageGuidelines: generateSummaryUsageGuidelines(
+      outputGeneratorContext.config,
+      outputGeneratorContext.instruction,
+    ),
+    summaryNotes: generateSummaryNotes(outputGeneratorContext.config),
+    summaryAdditionalInfo: generateSummaryAdditionalInfo(),
+    headerText: outputGeneratorContext.config.output.headerText,
+    instruction: outputGeneratorContext.instruction,
+    treeString: outputGeneratorContext.treeString,
+    processedFiles: outputGeneratorContext.processedFiles,
+  };
+
+  return `${template(renderContext).trim()}\n`;
+};
+
+const markdownTemplate = /* md */ `
+{{{generationHeader}}}
+
+# File Summary
+
+## Purpose
+{{{summaryPurpose}}}
+
+## File Format
+{{{summaryFileFormat}}}
+4. Multiple file entries, each consisting of:
+  a. A header with the file path (## File: path/to/file)
+  b. The full contents of the file in a code block
+
+## Usage Guidelines
+{{{summaryUsageGuidelines}}}
+
+## Notes
+{{{summaryNotes}}}
+
+## Additional Info
+{{#if headerText}}
+### User Provided Header
+{{{headerText}}}
+{{/if}}
+
+{{{summaryAdditionalInfo}}}
+
+# Repository Structure
+\`\`\`
+{{{treeString}}}
+\`\`\`
+
+# Repository Files
+
+{{#each processedFiles}}
+## File: {{{this.path}}}
+\`\`\`
+{{{this.content}}}
+\`\`\`
+
+{{/each}}
+
+{{#if instruction}}
+# Instruction
+{{{instruction}}}
+{{/if}}
+`;
diff --git a/src/core/output/outputGenerator.ts b/src/core/output/outputGenerator.ts
index 9654ffe0..7f5af745 100644
--- a/src/core/output/outputGenerator.ts
+++ b/src/core/output/outputGenerator.ts
@@ -4,6 +4,7 @@ import type { RepopackConfigMerged } from '../../config/configTypes.js';
 import { RepopackError } from '../../shared/errorHandler.js';
 import { generateTreeString } from '../file/fileTreeGenerator.js';
 import type { ProcessedFile } from '../file/fileTypes.js';
+import { generateMarkdownStyle } from './markdownStyleGenerator.js';
 import type { OutputGeneratorContext } from './outputGeneratorTypes.js';
 import { generatePlainStyle } from './plainStyleGenerator.js';
 import { generateXmlStyle } from './xmlStyleGenerator.js';
@@ -21,6 +22,9 @@ export const generateOutput = async (
     case 'xml':
       output = generateXmlStyle(outputGeneratorContext);
       break;
+    case 'markdown':
+      output = generateMarkdownStyle(outputGeneratorContext);
+      break;
     default:
       output = generatePlainStyle(outputGeneratorContext);
   }
diff --git a/src/core/output/plainStyleGenerator.ts b/src/core/output/plainStyleGenerator.ts
index eb58521b..74b27f93 100644
--- a/src/core/output/plainStyleGenerator.ts
+++ b/src/core/output/plainStyleGenerator.ts
@@ -9,16 +9,11 @@ import {
   generateSummaryUsageGuidelines,
 } from './outputStyleDecorator.js';
 
-const PLAIN_SEPARATOR = '='.repeat(16);
-const PLAIN_LONG_SEPARATOR = '='.repeat(64);
-
 export const generatePlainStyle = (outputGeneratorContext: OutputGeneratorContext) => {
   const template = Handlebars.compile(plainTemplate);
 
   const renderContext = {
     generationHeader: generateHeader(outputGeneratorContext.generationDate),
-    plainSeparator: PLAIN_SEPARATOR,
-    plainLongSeparator: PLAIN_LONG_SEPARATOR,
     summaryPurpose: generateSummaryPurpose(),
     summaryFileFormat: generateSummaryFileFormat(),
     summaryUsageGuidelines: generateSummaryUsageGuidelines(
@@ -36,12 +31,15 @@ export const generatePlainStyle = (outputGeneratorContext: OutputGeneratorContex
   return `${template(renderContext).trim()}\n`;
 };
 
+const PLAIN_SEPARATOR = '='.repeat(16);
+const PLAIN_LONG_SEPARATOR = '='.repeat(64);
+
 const plainTemplate = `
 {{{generationHeader}}}
 
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 File Summary
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 
 Purpose:
 --------
@@ -75,27 +73,27 @@ User Provided Header:
 
 {{{summaryAdditionalInfo}}}
 
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 Repository Structure
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 {{{treeString}}}
 
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 Repository Files
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 
 {{#each processedFiles}}
-{{{../plainSeparator}}}
+${PLAIN_SEPARATOR}
 File: {{{this.path}}}
-{{{../plainSeparator}}}
+${PLAIN_SEPARATOR}
 {{{this.content}}}
 
 {{/each}}
 
 {{#if instruction}}
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 Instruction
-{{{plainLongSeparator}}}
+${PLAIN_LONG_SEPARATOR}
 {{{instruction}}}
 {{/if}}
 
diff --git a/src/core/output/xmlStyleGenerator.ts b/src/core/output/xmlStyleGenerator.ts
index 7d03e567..b6a01960 100644
--- a/src/core/output/xmlStyleGenerator.ts
+++ b/src/core/output/xmlStyleGenerator.ts
@@ -31,7 +31,7 @@ export const generateXmlStyle = (outputGeneratorContext: OutputGeneratorContext)
   return `${template(renderContext).trim()}\n`;
 };
 
-const xmlTemplate = `
+const xmlTemplate = /* xml */ `
 {{{generationHeader}}}
 
 <file_summary>
diff --git a/tests/core/output/markdownStyleGenerator.test.ts b/tests/core/output/markdownStyleGenerator.test.ts
new file mode 100644
index 00000000..7281305a
--- /dev/null
+++ b/tests/core/output/markdownStyleGenerator.test.ts
@@ -0,0 +1,34 @@
+import process from 'node:process';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { generateMarkdownStyle } from '../../../src/core/output/markdownStyleGenerator.js';
+import { buildOutputGeneratorContext } from '../../../src/core/output/outputGenerator.js';
+import { createMockConfig } from '../../testing/testUtils.js';
+
+vi.mock('fs/promises');
+
+describe('outputGenerator', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  test('generateMarkdownOutput should include user-provided header text', async () => {
+    const mockConfig = createMockConfig({
+      output: {
+        filePath: 'output.md',
+        style: 'markdown',
+        headerText: 'Custom header text',
+        topFilesLength: 2,
+        showLineNumbers: false,
+        removeComments: false,
+        removeEmptyLines: false,
+      },
+    });
+
+    const context = await buildOutputGeneratorContext(process.cwd(), mockConfig, [], []);
+    const output = await generateMarkdownStyle(context);
+
+    expect(output).toContain('# File Summary');
+    expect(output).toContain('# Repository Structure');
+    expect(output).toContain('# Repository Files');
+  });
+});