tfplan2md

tfplan2md is a tool that converts Terraform plan JSON files (generated via terraform show -json) into human-readable Markdown reports. It is designed to improve Pull Request reviews by providing structured, semantic diffs instead of raw JSON or verbose text output.

Key benefits include:

• Logical Grouping: Changes are grouped by module.
• Semantic Diffs: Shows actual resource changes (e.g., adding/removing rules) rather than confusing index-based modifications.
• Readability: Uses collapsible sections, tables, and semantic icons (e.g., 🌐 for IPs, 🛡️ for roles).
• Security: Sensitive values are masked by default.
• Integration: Works with GitHub and Azure DevOps PR comments and supports static analysis findings (SARIF 2.1.0) from tools like Checkov, Trivy, TFLint, and Semgrep.

tfplan2md is a CLI tool designed to convert Terraform plan JSON files into human-readable Markdown reports. Its primary purpose is to facilitate infrastructure change reviews within Pull Requests (PRs).

Key Use Cases:

• Pull Request Reviews: Generating clean, readable Markdown reports specifically optimized for rendering in GitHub Pull Request comments and Azure DevOps Pull Request comments.
• CI/CD Integration: Running within Docker containers to automate the generation of infrastructure diffs during deployment pipelines.

Core Capabilities:

• Parses Terraform plan JSON output (generated via terraform show -json).
• Groups resources by module hierarchy.
• Provides semantic diffs for complex resources like firewall or NSG rules.
• Automatically masks sensitive values for security.

The Oocx.TfPlan2Md.HtmlRenderer is a standalone .NET console application designed to convert tfplan2md markdown reports into HTML. It provides two distinct rendering flavors to approximate how Markdown is displayed on specific platforms:

1. GitHub Flavor: Mimics GitHub's security sanitization by stripping style attributes, adding accessibility wrappers to tables, and adding notranslate classes to code elements.
2. Azure DevOps (AzDO) Flavor: Mimics Azure DevOps by preserving style attributes (useful for inline-diff rendering) and normalizing <details> tags.

The tool supports applying wrapper templates using a {{content}} placeholder to wrap the generated HTML content.

This document provides a retrospective on the development of the TerraformShowRenderer tool, which aims to produce output from Terraform plan JSON files that is 'authentically indistinguishable' from standard Terraform CLI output.

Key Technical Challenges

• Implicit Rule Deduction: AI models struggled to deduce implicit rendering rules such as whitespace, attribute ordering, and ANSI color patterns from examples alone.
• Formatting Fidelity: Achieving high-fidelity output required intensive user-guided test strategies and iterative model switching.

Successes

• Fidelity: The final tool achieves 100% fidelity against Terraform's output.
• Test Coverage: 33 new tests were added to ensure regression coverage for complex rendering logic.
• Architecture: The tool was implemented as a standalone component to keep the main production library clean.

The Website2 migration aims to move page bodies from legacy HTML (legacyContent shortcode) to native Eleventy Markdown and reusable components.

Current State:

• All 26 production routes are migrated to native Markdown sources.
• Shared shell concerns (navigation, footer, theme toggle, etc.) are already migrated.
• Interactive example fragments are located in website2/src/examples/.
• The legacyContent dependency has been removed from all production routes.

Active Migration Components: When authoring new or migrated pages, use these shared components:

• hero-block
• section-header
• feature-detail
• comparison-block
• related-docs
• code-window
• feature-card
• provider-card
• example-block

The project uses a phased approach for adding static analyzers to minimize disruption and manage technical debt. When adding a new analyzer (like SonarAnalyzer.CSharp), follow this 9-task pattern:

1. Add Package: Install the specific version of the analyzer package.
2. Baseline: Identify and baseline existing violations.
3. Configure: Set up rules in .editorconfig.
4. Fix Critical: Resolve high-priority violations.
5. Fix Non-Critical: Resolve lower-priority violations.
6. Promote: Change critical rule severity from warning to error.
7. Validate: Run existing test suites to ensure no regressions.
8. Measure: Evaluate the impact on build performance.
9. Finalize: Create the Pull Request for the phase completion.

Output Filename Derivation

If the --output parameter is not provided, the tool:

1. Strips the .html extension from the input filename.
2. Appends .png (the default format).
3. Places the file in the same directory as the input.

Example: report.html becomes report.png.

Image Format Detection

The tool determines the image format using the following priority:

1. The explicit --format parameter (e.g., --format png).
2. The file extension of the --output path (e.g., .jpg, .jpeg, .png).
3. Defaults to png if neither is specified.