Add markdown format output for code analysis tool

[Copilot]

Implementation Plan for Markdown Output Feature

Adding markdown format output to the code analysis tool to help Large Language Models understand the business model.

• Add --format option to generate command (supporting html and markdown formats)
• Create VisualizationMarkdownBuilder that converts CodeFlowAnalysisResult to markdown format
• Include sections for all architecture elements and relationships
• Update AppCsContentGenerator to handle markdown output format
• Update Program.cs to support format option with auto-extension detection
• Update documentation (README.md) with format examples
• Add comprehensive unit tests for markdown generation (10 tests total)
• Run existing tests to ensure no regression (all tests pass)
• Address code review feedback:
  • Add pipe character | escaping in EscapeMarkdown function
  • Escape chainName and aggregateName in Mermaid diagram headings
  • Escape timestampStr and descriptions in history tables
  • Fix unused outputPath variable in Program.cs
  • Use expectedExtension for extension mismatch warnings
  • Optimize foreach loops with LINQ .UnionWith()
  • Optimize dictionary lookup with .TryGetValue()
  • Add 6 new tests covering history, snapshots, edge cases, escaping, and configuration
• Add documentation to docs/content/zh/code-analysis/code-analysis-tools.md
• Add documentation to docs/content/en/code-analysis/code-analysis-tools.md
• Add maxEdges and maxTextSize parameters for API consistency with HTML builder
• Add node and relationship type filtering to match HTML template behavior
• Remove node and relationship count information from version history section

Changes Summary

Version History Simplification

• Removed node and relationship count display from version history bullet points
• Removed the "节点数量变化" table that showed total node and relationship counts per version
• Version history now only shows version timestamp, description, and hash
• Kept detailed type breakdown table ("各类型节点数量变化") for analyzing trends by specific types

Type Filtering (Consistent with HTML)

• Added DisplayNodeTypes and DisplayRelationshipTypes arrays to filter output
• Excludes internal implementation types (ControllerMethod, CommandSenderMethod, EntityMethod)
• Excludes internal relationship types (ControllerMethodToCommand, CommandSenderMethodToCommand, etc.)
• Types displayed in same order as HTML template for consistency
• Applied filtering to statistics, node listings, relationship listings, and history trends
• Total counts reflect only filtered/displayed types

API Consistency

• Added maxEdges (default: 5000) and maxTextSize (default: 1000000) parameters to GenerateVisualizationMarkdown
• Parameters match those in GenerateVisualizationHtml for consistency
• Added configuration note in markdown output documenting recommended Mermaid settings for users

Documentation Updates

• Added --format parameter to command parameters table in both Chinese and English docs
• Updated --output and --title descriptions to reflect support for both HTML and Markdown
• Added comprehensive "Output Formats" section with examples for both formats
• Documented Markdown format benefits for LLMs and included usage examples

Escaping Improvements

• Added pipe | character escaping to prevent table formatting issues
• All user-provided text (descriptions, names, versions) now properly escaped
• Safe handling of malformed version strings

Code Optimizations

• Replaced nested foreach with .UnionWith() for better performance
• Replaced ContainsKey + indexer with TryGetValue pattern
• Removed unused variables in Program.cs

Testing

• Added 6 comprehensive tests for history/snapshot scenarios, configuration, and edge cases
• Tests cover pipe escaping, malformed versions, special characters in tables, and Mermaid config notes
• Updated test to reflect removal of total count table
• All 10 markdown tests + 41 tools tests passing

Security Summary

No security vulnerabilities introduced. All user input properly escaped before rendering in markdown.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>代码分析工具添加输出markdown格式的分析结果输出</issue_title>
<issue_description>代码分析工具添加输出markdown格式的分析结果，以帮助大语言模型理解业务模型

类似bun的md格式输出

bun --cpu-prof-md script.js
```</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
</comments>

• Fixes 代码分析工具添加输出markdown格式的分析结果输出 #339

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

Adds a Markdown output mode to the code analysis visualization tool so the architecture output can be consumed as structured text (including optional Mermaid), alongside the existing HTML output.

Changes:

• Added VisualizationMarkdownBuilder to generate Markdown reports (stats, elements, relationships, Mermaid, optional history).
• Extended generate CLI with --format (html/markdown/md) and updated default output extension behavior.
• Updated tool README and added unit tests for Markdown generation basics/escaping.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/NetCorePal.Extensions.CodeAnalysis/VisualizationMarkdownBuilder.cs	Implements Markdown report generation, including optional Mermaid diagrams and snapshot history/trends.
src/NetCorePal.Extensions.CodeAnalysis.Tools/Program.cs	Adds --format option and adjusts default output path extension for Markdown.
src/NetCorePal.Extensions.CodeAnalysis.Tools/AppCsContentGenerator.cs	Emits generated app.cs that writes either HTML or Markdown depending on selected format.
src/NetCorePal.Extensions.CodeAnalysis.Tools/README.md	Documents the new output format option and usage examples.
test/NetCorePal.Extensions.CodeAnalysis.UnitTests/VisualizationMarkdownBuilderTests.cs	Adds unit tests for basic Markdown output behavior and escaping.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

chainName is used directly in a Markdown heading. Since it comes from node names, it may contain Markdown-special characters and break the heading/rendering. Escape chainName (or sanitize it) before writing it into the document.

[Copilot]

Fixed in 05e2a25. chainName is now escaped using EscapeMarkdown() before being written to headings.

[Copilot]

aggregateName is used directly in a Markdown heading. Since it comes from node names, it may contain Markdown-special characters and break the heading/rendering. Escape aggregateName (or sanitize it) before writing it into the document.

[Copilot]

Fixed in 05e2a25. aggregateName is now escaped using EscapeMarkdown() before being written to headings.

[Copilot]

In the history trends tables, timestampStr falls back to the raw Metadata.Version string when parsing fails, but it is not escaped before being inserted into a Markdown table cell. If a non-timestamp version contains | or other Markdown characters, the table will break. Escape timestampStr before writing it into the table.

[Copilot]

Fixed in 05e2a25. timestampStr fallback now uses EscapeMarkdown() to safely handle malformed version strings containing special characters.

[Copilot]

Tests currently only cover withHistory: false and don't validate output when withHistory: true with snapshots (version history + trend tables). Add tests covering snapshot rendering and table-escaping edge cases (e.g., descriptions containing |, backticks, newlines) to prevent regressions.

[Copilot]

Fixed in 05e2a25. Added 5 comprehensive tests covering:

• History with version snapshots
• Pipe character escaping in descriptions
• Multiple snapshots with trend tables
• Malformed version string handling
• Special markdown characters in descriptions

[Copilot]

expectedExtension is computed but never used, which creates dead code and can generate compiler warnings. Either remove it or use it to validate/adjust the output filename extension when --format is specified.

Suggested change

	// Auto-adjust output file extension if needed
	var expectedExtension = normalizedFormat == "markdown" ? ".md" : ".html";
	var outputPath = outputFile.FullName;
	// Determine the expected file extension for the selected format
	var expectedExtension = normalizedFormat == "markdown" ? ".md" : ".html";
	var outputPath = outputFile.FullName;
	// Warn when the chosen output file extension does not match the selected format
	if (!outputPath.EndsWith(expectedExtension, StringComparison.OrdinalIgnoreCase) && verbose)
	{
	var currentExtension = System.IO.Path.GetExtension(outputPath);
	Console.WriteLine(
	$"Warning: Output file extension '{currentExtension}' does not match the selected format '{normalizedFormat}'. Expected '{expectedExtension}'.");
	}

[Copilot]

Fixed in 05e2a25. Removed unused outputPath variable and now use expectedExtension to display extension mismatch warnings when verbose mode is enabled.

[Copilot]

EscapeMarkdown does not escape the pipe character (|). Because snapshot descriptions are inserted into Markdown tables, a | in input will break table formatting. Add escaping for | (e.g., \|) or a table-cell specific escaping routine for values written into tables.

[Copilot]

Fixed in 05e2a25. Added pipe character | escaping to EscapeMarkdown() function to prevent table formatting issues.

[Copilot]

This foreach loop immediately maps its iteration variable to another variable - consider mapping the sequence explicitly using '.Select(...)'.

[Copilot]

This foreach loop immediately maps its iteration variable to another variable - consider mapping the sequence explicitly using '.Select(...)'.

Suggested change

	foreach (var nodeType in result.Nodes.Select(n => n.Type).Distinct())
	{
	allNodeTypes.Add(nodeType);
	}
	allNodeTypes.UnionWith(result.Nodes.Select(n => n.Type));

[Copilot]

Fixed in 05e2a25. Replaced nested foreach loop with .UnionWith() for better performance and cleaner code.

[Copilot]

Inefficient use of 'ContainsKey' and indexer.

Suggested change

	var count = nodesByType.ContainsKey(nodeType) ? nodesByType[nodeType] : 0;
	var count = nodesByType.TryGetValue(nodeType, out var value) ? value : 0;

[Copilot]

Fixed in 05e2a25. Replaced ContainsKey + indexer pattern with more efficient .TryGetValue() pattern.

[Copilot]

This assignment to outputPath is useless, since its value is never read.

Suggested change

	var outputPath = outputFile.FullName;
	// If output uses default value and format is markdown, change extension
	if (outputFile.FullName.EndsWith("architecture-visualization.html", StringComparison.OrdinalIgnoreCase)
	&& normalizedFormat == "markdown")
	{
	outputPath = outputFile.FullName.Replace(".html", ".md");
	outputFile = new FileInfo(outputPath);
	// If output uses default value and format is markdown, change extension
	if (outputFile.FullName.EndsWith("architecture-visualization.html", StringComparison.OrdinalIgnoreCase)
	&& normalizedFormat == "markdown")
	{
	outputFile = new FileInfo(outputFile.FullName.Replace(".html", ".md"));

[Copilot]

Fixed in 05e2a25. Removed unused outputPath assignment and simplified the code to directly reassign outputFile.

[witskeeper]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

All code review feedback has been addressed in commit 05e2a25:

Escaping & Security:

• Added pipe | character escaping to prevent table formatting issues
• All user-provided text (names, descriptions, versions) properly escaped before rendering
• Safe handling of malformed version strings

Code Quality:

• Replaced nested foreach with .UnionWith() for better performance
• Replaced ContainsKey + indexer with .TryGetValue() pattern
• Removed unused variables (outputPath, expectedExtension now used for warnings)

Testing:

• Added 5 comprehensive tests covering history/snapshot scenarios
• Tests validate pipe escaping, malformed versions, special characters in tables
• All 9 markdown tests + 41 tools tests passing

The markdown output now safely handles all edge cases and special characters.

[witskeeper]

@copilot 在code-analysis-tools.md中添加说明

[witskeeper]

@copilot 生成md时，应该添加html模版中相同的过滤条件

[Copilot]

@copilot 在code-analysis-tools.md中添加说明

已在 1f96ace 中添加说明。更新了以下文档文件：

中文文档 (docs/content/zh/code-analysis/code-analysis-tools.md):

• 在命令参数表中添加 --format 选项
• 更新 --output 和 --title 的描述以反映对 HTML 和 Markdown 的支持
• 添加"输出格式"章节，包含 HTML 和 Markdown 格式的详细说明和使用示例

英文文档 (docs/content/en/code-analysis/code-analysis-tools.md):

• 同样更新了参数表和格式说明
• 添加了 "Output Formats" 章节

两个文档现在都包含了完整的 Markdown 格式输出功能说明，包括用法示例和注意事项。

[witskeeper]

@copilot 生成md时，应该添加html模版中相同的过滤条件

// 定义要显示的节点类型（按定义顺序，排除指定类型）
const displayNodeTypes = [
'Controller',
'Endpoint',
'CommandSender',
'Command',
'CommandHandler',
'Aggregate',
'DomainEvent',
'IntegrationEvent',
'DomainEventHandler',
'IntegrationEventHandler',
'IntegrationEventConverter'
];

        // 定义要显示的关系类型（按定义顺序，排除指定类型）
        const displayRelationshipTypes = [
            'ControllerToCommand',
            'EndpointToCommand',
            'CommandSenderToCommand',
            'CommandToAggregate',
            'AggregateToDomainEvent',
            'DomainEventToHandler',
            'DomainEventHandlerToCommand',
            'IntegrationEventToHandler',
            'IntegrationEventHandlerToCommand',
            'DomainEventToIntegrationEvent'
        ];

[Copilot]

@copilot 生成md时，应该添加html模版中相同的过滤条件

已在 0b2b520 中添加。为保持与 HTML 模板的一致性，在 Markdown 生成器中添加了相同的过滤条件参数：

添加的参数：

• maxEdges (默认: 5000) - 最大边数
• maxTextSize (默认: 1000000) - 最大文本大小

实现细节：

• 参数签名与 GenerateVisualizationHtml 保持一致
• 在 Markdown 输出的架构图表部分添加配置说明，告知用户建议的 Mermaid 配置参数
• 添加单元测试验证配置说明正确生成

示例输出：

> **注意**: 以下 Mermaid 图表建议配置参数: `maxEdges: 5000, maxTextSize: 1000000`

所有测试通过 (10/10)。

[Copilot]

@copilot 生成md时，应该添加html模版中相同的过滤条件

// 定义要显示的节点类型（按定义顺序，排除指定类型）
...

已在 3bfdd21 中添加。为保持与 HTML 模板的一致性，在 Markdown 生成器中添加了相同的节点和关系类型过滤：

添加的过滤规则：

DisplayNodeTypes (显示的节点类型)：

• Controller, Endpoint, CommandSender, Command, CommandHandler, Aggregate, DomainEvent, IntegrationEvent, DomainEventHandler, IntegrationEventHandler, IntegrationEventConverter

DisplayRelationshipTypes (显示的关系类型)：

• ControllerToCommand, EndpointToCommand, CommandSenderToCommand, CommandToAggregate, AggregateToDomainEvent, DomainEventToHandler, DomainEventHandlerToCommand, IntegrationEventToHandler, IntegrationEventHandlerToCommand, DomainEventToIntegrationEvent

过滤掉的内部实现类型：

• 节点: ControllerMethod, CommandSenderMethod, EntityMethod
• 关系: ControllerMethodToCommand, CommandSenderMethodToCommand, CommandToEntityMethod, EntityMethodToEntityMethod, EntityMethodToDomainEvent

实现细节：

• 所有统计、节点列表、关系列表和历史趋势现在都使用过滤后的类型
• 类型按定义顺序显示，与 HTML 模板保持完全一致
• 总计数字反映的是过滤后的数量

所有测试通过 (10/10)。

[witskeeper]

@copilot 生成md的统计信息部分时，应该基于类似html模版中相同的过滤条件，仅统计下列类型

// 定义要显示的节点类型（按定义顺序，排除指定类型）
const displayNodeTypes = [
'Controller',
'Endpoint',
'CommandSender',
'Command',
'CommandHandler',
'Aggregate',
'DomainEvent',
'IntegrationEvent',
'DomainEventHandler',
'IntegrationEventHandler',
'IntegrationEventConverter'
];

        // 定义要显示的关系类型（按定义顺序，排除指定类型）
        const displayRelationshipTypes = [
            'ControllerToCommand',
            'EndpointToCommand',
            'CommandSenderToCommand',
            'CommandToAggregate',
            'AggregateToDomainEvent',
            'DomainEventToHandler',
            'DomainEventHandlerToCommand',
            'IntegrationEventToHandler',
            'IntegrationEventHandlerToCommand',
            'DomainEventToIntegrationEvent'
        ];

[Copilot]

@copilot 生成md的统计信息部分时，应该基于类似html模版中相同的过滤条件，仅统计下列类型

// 定义要显示的节点类型（按定义顺序，排除指定类型）
...

统计信息部分已在 3bfdd21 中实现了相同的过滤条件。

当前实现：

• GenerateStatistics 方法在第 135-138 行过滤节点类型：使用 DisplayNodeTypes.Contains(n.Type)
• 第 140-143 行过滤关系类型：使用 DisplayRelationshipTypes.Contains(r.Type)
• 总计数字（第 158 和 174 行）反映的是过滤后的数量

过滤的类型与 HTML 模板完全一致：

• 仅统计 DisplayNodeTypes 中定义的 11 种节点类型
• 仅统计 DisplayRelationshipTypes 中定义的 10 种关系类型
• 排除了内部实现类型（ControllerMethod, CommandSenderMethod, EntityMethod 等）

统计部分已正确应用过滤条件，与 HTML 模板保持一致。

[witskeeper]

@copilot 移除生成md的版本历史里节点数、关系数 的信息

[Copilot]

@copilot 移除生成md的版本历史里节点数、关系数 的信息

已在 9760ae6 中完成。移除了版本历史中的节点数和关系数信息：

移除的内容：

1. 版本历史列表中的节点数和关系数行（原第 61 行）
2. 演进趋势中的"节点数量变化"表格（显示总节点数和总关系数的表格）

保留的内容：

• 版本历史列表仍显示：时间戳、描述、Hash
• 演进趋势中的"各类型节点数量变化"表格（按类型分解的详细趋势）

所有测试通过 (10/10)。