tfreadme 0.1.0__tar.gz

tfreadme-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: tfreadme
+Version: 0.1.0
+Summary: Generate Markdown reports from Terraform plans
+Author: Aswin
+License: MIT
+Project-URL: Homepage, https://github.com/Aswin-00/tfreadme.git
+Keywords: terraform,terraform-plan,iac,devops,aws,cloud,markdown,report,automation,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: tabulate>=0.9.0
+
+# Terraform Plan Report Generator
+
+Generate clean, human-readable Markdown reports from Terraform plan files.
+
+This utility converts the output of `terraform show -json` into a structured Markdown report that is easier to review during infrastructure changes, pull requests, and CI/CD pipelines.
+
+## Features
+
+* Generate Markdown reports from Terraform plan files
+* Summary of resource actions
+
+  * CREATE
+  * UPDATE
+  * DELETE
+  * REPLACE
+* Resource type summary
+* Friendly resource name detection
+* Resource ID extraction
+* Terraform resource address listing
+* Collapsible sections for improved readability
+* Lightweight and dependency-minimal
+
+## Example Workflow
+
+```text
+terraform plan -out=tfplan
+              │
+              ▼
+terraform show -json tfplan
+              │
+              ▼
+     Terraform Plan Report
+              │
+              ▼
+      README_TFPLAN.md
+```
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/<your-username>/tfplan-report.git
+cd tfplan-report
+```
+
+Install the package:
+
+```bash
+pip install .
+```
+
+Or install the dependency manually:
+
+```bash
+pip install tabulate
+```
+
+## Requirements
+
+* Python 3.9+
+* Terraform CLI
+* tabulate
+
+## Usage
+
+Generate a Terraform plan:
+
+```bash
+terraform plan -out=tfplan
+```
+
+Generate the Markdown report:
+
+```bash
+tfreadme tfplan
+```
+
+or
+
+```bash
+python tfreadme.py tfplan
+```
+
+The tool generates:
+
+```text
+README_TFPLAN.md
+```
+
+## Sample Output
+
+### Plan Summary
+
+| Action  | Count |
+| ------- | ----: |
+| CREATE  |    12 |
+| UPDATE  |     5 |
+| DELETE  |     2 |
+| REPLACE |     1 |
+
+### Resource Type Summary
+
+| Resource Type      | Count |
+| ------------------ | ----: |
+| aws_instance       |     8 |
+| aws_security_group |     4 |
+| aws_iam_role       |     2 |
+
+### CREATE
+
+| Name       | Type         | Resource ID | Terraform Address |
+| ---------- | ------------ | ----------- | ----------------- |
+| web-server | aws_instance | N/A         | aws_instance.web  |
+
+## Project Structure
+
+```text
+.
+├── pyproject.toml
+├── requirements.txt
+├── tfreadme.py
+└── README.md
+```
+
+## How It Works
+
+The tool:
+
+1. Reads a Terraform binary plan file
+2. Executes `terraform show -json`
+3. Parses the JSON output
+4. Classifies resource actions
+5. Groups resources by operation
+6. Generates a clean Markdown report
+
+## Current Capabilities
+
+* Parse Terraform plan files
+* Generate Markdown summaries
+* Count resources by action
+* Count resources by type
+* Extract resource names
+* Extract resource IDs
+* Display Terraform addresses
+* Produce review-friendly output
+
+
+## Technologies Used
+
+* Python
+* Terraform
+* JSON
+* tabulate
+
+
+## License
+
+MIT License
+
+## Author
+
+Developed by **Aswin** as a practical DevOps automation tool to simplify Terraform plan reviews and improve infrastructure change visibility.

tfreadme-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Terraform Plan Report Generator
+
+Generate clean, human-readable Markdown reports from Terraform plan files.
+
+This utility converts the output of `terraform show -json` into a structured Markdown report that is easier to review during infrastructure changes, pull requests, and CI/CD pipelines.
+
+## Features
+
+* Generate Markdown reports from Terraform plan files
+* Summary of resource actions
+
+  * CREATE
+  * UPDATE
+  * DELETE
+  * REPLACE
+* Resource type summary
+* Friendly resource name detection
+* Resource ID extraction
+* Terraform resource address listing
+* Collapsible sections for improved readability
+* Lightweight and dependency-minimal
+
+## Example Workflow
+
+```text
+terraform plan -out=tfplan
+              │
+              ▼
+terraform show -json tfplan
+              │
+              ▼
+     Terraform Plan Report
+              │
+              ▼
+      README_TFPLAN.md
+```
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/<your-username>/tfplan-report.git
+cd tfplan-report
+```
+
+Install the package:
+
+```bash
+pip install .
+```
+
+Or install the dependency manually:
+
+```bash
+pip install tabulate
+```
+
+## Requirements
+
+* Python 3.9+
+* Terraform CLI
+* tabulate
+
+## Usage
+
+Generate a Terraform plan:
+
+```bash
+terraform plan -out=tfplan
+```
+
+Generate the Markdown report:
+
+```bash
+tfreadme tfplan
+```
+
+or
+
+```bash
+python tfreadme.py tfplan
+```
+
+The tool generates:
+
+```text
+README_TFPLAN.md
+```
+
+## Sample Output
+
+### Plan Summary
+
+| Action  | Count |
+| ------- | ----: |
+| CREATE  |    12 |
+| UPDATE  |     5 |
+| DELETE  |     2 |
+| REPLACE |     1 |
+
+### Resource Type Summary
+
+| Resource Type      | Count |
+| ------------------ | ----: |
+| aws_instance       |     8 |
+| aws_security_group |     4 |
+| aws_iam_role       |     2 |
+
+### CREATE
+
+| Name       | Type         | Resource ID | Terraform Address |
+| ---------- | ------------ | ----------- | ----------------- |
+| web-server | aws_instance | N/A         | aws_instance.web  |
+
+## Project Structure
+
+```text
+.
+├── pyproject.toml
+├── requirements.txt
+├── tfreadme.py
+└── README.md
+```
+
+## How It Works
+
+The tool:
+
+1. Reads a Terraform binary plan file
+2. Executes `terraform show -json`
+3. Parses the JSON output
+4. Classifies resource actions
+5. Groups resources by operation
+6. Generates a clean Markdown report
+
+## Current Capabilities
+
+* Parse Terraform plan files
+* Generate Markdown summaries
+* Count resources by action
+* Count resources by type
+* Extract resource names
+* Extract resource IDs
+* Display Terraform addresses
+* Produce review-friendly output
+
+
+## Technologies Used
+
+* Python
+* Terraform
+* JSON
+* tabulate
+
+
+## License
+
+MIT License
+
+## Author
+
+Developed by **Aswin** as a practical DevOps automation tool to simplify Terraform plan reviews and improve infrastructure change visibility.

tfreadme-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tfreadme"
+version = "0.1.0"
+description = "Generate Markdown reports from Terraform plans"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Aswin"}
+]
+
+
+keywords = [
+    "terraform",
+    "terraform-plan",
+    "iac",
+    "devops",
+    "aws",
+    "cloud",
+    "markdown",
+    "report",
+    "automation",
+    "cli"
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities"
+]
+
+dependencies = [
+    "tabulate>=0.9.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/Aswin-00/tfreadme.git"
+
+
+[project.scripts]
+tfreadme = "tfreadme:main"
+
+[tool.setuptools]
+py-modules = ["tfreadme"]

tfreadme-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tfreadme-0.1.0/tfreadme.egg-info/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: tfreadme
+Version: 0.1.0
+Summary: Generate Markdown reports from Terraform plans
+Author: Aswin
+License: MIT
+Project-URL: Homepage, https://github.com/Aswin-00/tfreadme.git
+Keywords: terraform,terraform-plan,iac,devops,aws,cloud,markdown,report,automation,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: tabulate>=0.9.0
+
+# Terraform Plan Report Generator
+
+Generate clean, human-readable Markdown reports from Terraform plan files.
+
+This utility converts the output of `terraform show -json` into a structured Markdown report that is easier to review during infrastructure changes, pull requests, and CI/CD pipelines.
+
+## Features
+
+* Generate Markdown reports from Terraform plan files
+* Summary of resource actions
+
+  * CREATE
+  * UPDATE
+  * DELETE
+  * REPLACE
+* Resource type summary
+* Friendly resource name detection
+* Resource ID extraction
+* Terraform resource address listing
+* Collapsible sections for improved readability
+* Lightweight and dependency-minimal
+
+## Example Workflow
+
+```text
+terraform plan -out=tfplan
+              │
+              ▼
+terraform show -json tfplan
+              │
+              ▼
+     Terraform Plan Report
+              │
+              ▼
+      README_TFPLAN.md
+```
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/<your-username>/tfplan-report.git
+cd tfplan-report
+```
+
+Install the package:
+
+```bash
+pip install .
+```
+
+Or install the dependency manually:
+
+```bash
+pip install tabulate
+```
+
+## Requirements
+
+* Python 3.9+
+* Terraform CLI
+* tabulate
+
+## Usage
+
+Generate a Terraform plan:
+
+```bash
+terraform plan -out=tfplan
+```
+
+Generate the Markdown report:
+
+```bash
+tfreadme tfplan
+```
+
+or
+
+```bash
+python tfreadme.py tfplan
+```
+
+The tool generates:
+
+```text
+README_TFPLAN.md
+```
+
+## Sample Output
+
+### Plan Summary
+
+| Action  | Count |
+| ------- | ----: |
+| CREATE  |    12 |
+| UPDATE  |     5 |
+| DELETE  |     2 |
+| REPLACE |     1 |
+
+### Resource Type Summary
+
+| Resource Type      | Count |
+| ------------------ | ----: |
+| aws_instance       |     8 |
+| aws_security_group |     4 |
+| aws_iam_role       |     2 |
+
+### CREATE
+
+| Name       | Type         | Resource ID | Terraform Address |
+| ---------- | ------------ | ----------- | ----------------- |
+| web-server | aws_instance | N/A         | aws_instance.web  |
+
+## Project Structure
+
+```text
+.
+├── pyproject.toml
+├── requirements.txt
+├── tfreadme.py
+└── README.md
+```
+
+## How It Works
+
+The tool:
+
+1. Reads a Terraform binary plan file
+2. Executes `terraform show -json`
+3. Parses the JSON output
+4. Classifies resource actions
+5. Groups resources by operation
+6. Generates a clean Markdown report
+
+## Current Capabilities
+
+* Parse Terraform plan files
+* Generate Markdown summaries
+* Count resources by action
+* Count resources by type
+* Extract resource names
+* Extract resource IDs
+* Display Terraform addresses
+* Produce review-friendly output
+
+
+## Technologies Used
+
+* Python
+* Terraform
+* JSON
+* tabulate
+
+
+## License
+
+MIT License
+
+## Author
+
+Developed by **Aswin** as a practical DevOps automation tool to simplify Terraform plan reviews and improve infrastructure change visibility.

tfreadme-0.1.0/tfreadme.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+tfreadme.py
+tfreadme.egg-info/PKG-INFO
+tfreadme.egg-info/SOURCES.txt
+tfreadme.egg-info/dependency_links.txt
+tfreadme.egg-info/entry_points.txt
+tfreadme.egg-info/requires.txt
+tfreadme.egg-info/top_level.txt

tfreadme-0.1.0/tfreadme.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tfreadme-0.1.0/tfreadme.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tfreadme = tfreadme:main

tfreadme-0.1.0/tfreadme.egg-info/requires.txt

@@ -0,0 +1 @@
+tabulate>=0.9.0

tfreadme-0.1.0/tfreadme.egg-info/top_level.txt

@@ -0,0 +1 @@
+tfreadme

tfreadme-0.1.0/tfreadme.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+
+import json
+import sys
+from collections import defaultdict
+from tabulate import tabulate
+import subprocess
+import argparse
+
+
+OUTPUT_FILE = "README_TFPLAN.md"
+def get_resource_name(change):
+    """
+    Extract a friendly name from before/after state.
+    """
+    candidates = [
+        change.get("after", {}),
+        change.get("before", {})
+    ]
+
+    for obj in candidates:
+        if not isinstance(obj, dict):
+            continue
+
+        if obj.get("name"):
+            return str(obj["name"])
+
+        tags = obj.get("tags", {})
+        if isinstance(tags, dict) and tags.get("Name"):
+            return str(tags["Name"])
+
+        tags_all = obj.get("tags_all", {})
+        if isinstance(tags_all, dict) and tags_all.get("Name"):
+            return str(tags_all["Name"])
+
+    return "N/A"
+
+
+def get_resource_id(change: dict) -> str:
+    for obj in (
+        change.get("before"),
+        change.get("after"),
+    ):
+        if isinstance(obj, dict):
+            if obj.get("id"):
+                return str(obj["id"])
+
+    return "N/A"
+
+
+def classify_action(actions):
+    actions = set(actions)
+
+    if actions == {"create"}:
+        return "CREATE"
+
+    if actions == {"update"}:
+        return "UPDATE"
+
+    if actions == {"delete"}:
+        return "DELETE"
+
+    if actions == {"create", "delete"}:
+        return "REPLACE"
+
+    return ",".join(sorted(actions)).upper()
+
+def load_plan(plan_file: str) -> dict:
+    """
+    Load a Terraform binary plan using `terraform show -json`
+    and return it as a Python dictionary.
+    """
+    try:
+        result = subprocess.run(
+            ["terraform", "show", "-json", plan_file],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        return json.loads(result.stdout)
+
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(
+            f"terraform show failed:\n{e.stderr}"
+        ) from e
+
+    except json.JSONDecodeError as e:
+        raise RuntimeError(
+            "Failed to parse terraform JSON output."
+        ) from e
+
+
+def build_report(plan):
+    grouped = defaultdict(list)
+    summary = defaultdict(int)
+    type_summary = defaultdict(int)
+
+    resource_changes = plan.get("resource_changes", [])
+
+    for rc in resource_changes:
+        change = rc.get("change", {})
+        actions = change.get("actions", [])
+
+        action = classify_action(actions)
+
+        resource = {
+            "name": get_resource_name(change),
+            "type": rc.get("type", "N/A"),
+            "address": rc.get("address", "N/A"),
+            "id": get_resource_id(change),
+        }
+
+        grouped[action].append(resource)
+
+        summary[action] += 1
+        type_summary[resource["type"]] += 1
+
+    md = []
+
+    md.append("# Terraform Plan Report")
+    md.append("")
+    md.append("Generated from `terraform show -json` output.")
+    md.append("")
+
+    # Summary
+    md.append("## Plan Summary")
+    md.append("")
+
+    summary_rows = [
+        [action, count]
+        for action, count in sorted(summary.items())
+    ]
+
+    md.append(
+        tabulate(
+            summary_rows,
+            headers=["Action", "Count"],
+            tablefmt="github"
+        )
+    )
+
+    md.append("")
+    md.append(
+        f"**Total Resource Changes:** {sum(summary.values())}"
+    )
+    md.append("")
+
+    # Resource Type Summary
+    md.append("## Resource Type Summary")
+    md.append("")
+
+    type_rows = sorted(
+        type_summary.items(),
+        key=lambda x: x[1],
+        reverse=True
+    )
+
+    md.append(
+        tabulate(
+            type_rows,
+            headers=["Resource Type", "Count"],
+            tablefmt="github"
+        )
+    )
+
+    md.append("")
+
+    action_order = [
+        "CREATE",
+        "UPDATE",
+        "DELETE",
+        "REPLACE"
+    ]
+
+    for action in action_order:
+
+        if action not in grouped:
+            continue
+
+        resources = sorted(
+            grouped[action],
+            key=lambda x: x["address"]
+        )
+
+        md.append(
+            f"<details open>"
+        )
+        md.append(
+            f"<summary><strong>{action} ({len(resources)})</strong></summary>"
+        )
+        md.append("")
+        md.append("")
+
+        rows = []
+
+        for r in resources:
+            rows.append([
+                r["name"],
+                r["type"],
+                r["id"],
+                r["address"]
+            ])
+
+        md.append(
+            tabulate(
+                rows,
+                headers=[
+                    "Name",
+                    "Type",
+                    "Resource ID",
+                    "Terraform Address"
+                ],
+                tablefmt="github"
+            )
+        )
+
+        md.append("")
+        md.append("</details>")
+        md.append("")
+
+    return "\n".join(md)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate a Markdown report from a Terraform plan."
+    )
+
+    parser.add_argument(
+        "plan",
+        help="Terraform binary plan file (e.g. tfplan)"
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="README_TFPLAN.md",
+        help="Output markdown file (default: README_TFPLAN.md)"
+    )
+
+    args = parser.parse_args()
+
+    try:
+        plan = load_plan(args.plan)
+
+        report = build_report(plan)
+
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(report)
+
+        print(f"Report generated: {args.output}")
+
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+
+
+
+if __name__ == "__main__":
+    main()