feat(terraform-docs): monorepo-aware doc generation with tests

Find directories where Terraform files have changed via `git diff` and run
terraform-docs in each, honoring a root .terraform-docs.yaml when present.
Skips quietly when no Terraform files changed. Refactors the script into
testable functions and adds a unit test suite covering directory discovery,
config-vs-default command selection, and unstaged-README detection
(including newly-created untracked READMEs).

Builds on #1070 with these fixes:
- Restore executable bit on terraform-docs.py.
- Use `markdown-table` (single subcommand) for the no-config fallback.
- Use `subprocess(cwd=...)` instead of os.chdir to avoid global side effects.
- Prefer `git diff --cached` (the pre-commit source of truth), then union
  unstaged changes.
- Skip directories that no longer exist (e.g. when a module was deleted)
  so the script doesn't crash mid-run.
- Detect untracked README.md files in addition to modified ones.

Author: claude

.trunk/trunk.yaml

@@ -104,6 +104,7 @@ actions:
 
   enabled:
     # enabled actions inherited from github.com/trunk-io/configs plugin
+    - terraform-docs
     - linter-test-helper
     - npm-check-pre-push
     - remove-release-snapshots

actions/terraform-docs/terraform-docs.py

@@ -4,33 +4,38 @@
 
 This script acts as a pre-commit hook to ensure terraform documentation is up to date.
 It performs the following:
-1. Runs terraform-docs to update documentation
-2. Checks if any README.md files show up in the unstaged changes
-3. Exits with failure if there are unstaged README changes, success otherwise
+1. Finds directories where Terraform files have changed
+2. Runs terraform-docs in each directory containing changed Terraform files
+3. Checks if any README.md files show up in the unstaged changes
+4. Exits with failure if there are unstaged README changes, success otherwise
 """
 
-# trunk-ignore(bandit/B404)
-import subprocess
+import os
+import subprocess  # trunk-ignore(bandit/B404)
 import sys
 
+TERRAFORM_EXTENSIONS = (".tf", ".tofu", ".tfvars")
+CONFIG_FILENAME = ".terraform-docs.yaml"
 
-def run_command(cmd):
+
+def run_command(cmd, cwd=None):
     """
     Execute a shell command and return its exit code, stdout, and stderr.
 
     Args:
         cmd: List of command arguments to execute
+        cwd: Optional working directory in which to run the command
 
     Returns:
         Tuple containing (return_code, stdout, stderr)
     """
     try:
-
         process = subprocess.Popen(
             cmd,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             universal_newlines=True,
+            cwd=cwd,
             # trunk-ignore(bandit/B603)
             shell=False,  # Explicitly disable shell to prevent command injection
         )
@@ -46,28 +51,98 @@ def run_command(cmd):
         sys.exit(1)
 
 
-# First, run terraform-docs to update documentation
-update_cmd = ["terraform-docs", "."]
-return_code, stdout, stderr = run_command(update_cmd)
+def terraform_dirs_from_paths(paths, repo_root="."):
+    """
+    Given an iterable of repo-relative file paths, return the set of directories
+    that contain Terraform files and still exist on disk.
+
+    Deleted files are skipped because their parent directory may no longer exist
+    (or the module may have been removed entirely), and there's nothing for
+    terraform-docs to document there.
+    """
+    dirs = set()
+    for file_path in paths:
+        file_path = file_path.strip()
+        if not file_path or not file_path.endswith(TERRAFORM_EXTENSIONS):
+            continue
+        dir_path = os.path.dirname(file_path) or "."
+        abs_dir = dir_path if os.path.isabs(dir_path) else os.path.join(repo_root, dir_path)
+        if os.path.isdir(abs_dir):
+            dirs.add(dir_path)
+    return dirs
+
+
+def get_changed_terraform_directories():
+    """
+    Return the set of directories containing Terraform files that are part of
+    this commit (staged) or have been modified in the working tree.
+
+    The hook runs pre-commit, so staged changes are the primary source of truth;
+    we also include unstaged edits so that a developer iterating in the working
+    tree sees their docs regenerated.
+    """
+    paths = set()
+    for diff_args in (["--cached", "--name-only"], ["--name-only"]):
+        cmd = ["git", "diff", *diff_args]
+        return_code, stdout, _stderr = run_command(cmd)
+        if return_code != 0:
+            continue
+        paths.update(stdout.splitlines())
+    return terraform_dirs_from_paths(paths)
+
+
+def build_terraform_docs_cmd(repo_root):
+    """Pick the terraform-docs invocation based on whether a config file exists."""
+    config_file_path = os.path.join(repo_root, CONFIG_FILENAME)
+    if os.path.exists(config_file_path):
+        return ["terraform-docs", "--config", config_file_path, "."]
+    return ["terraform-docs", "markdown-table", "."]
+
+
+def find_unstaged_readmes(porcelain_output):
+    """
+    Parse `git status --porcelain` output and return README.md paths that are
+    either modified-but-unstaged or untracked. Both states block the commit
+    because the developer needs to `git add` the regenerated docs.
+    """
+    unstaged = []
+    for line in porcelain_output.splitlines():
+        if len(line) < 3:
+            continue
+        status = line[:2]
+        path = line[3:].strip()
+        # `_M` = unstaged modification (any X), `??` = untracked.
+        if (status[1] == "M" or status == "??") and path.endswith("README.md"):
+            unstaged.append(path)
+    return unstaged
+
+
+def main():
+    repo_root = os.getcwd()
+    terraform_dirs = get_changed_terraform_directories()
+
+    if not terraform_dirs:
+        print("terraform-docs: No Terraform files changed, skipping documentation update")
+        return 0
+
+    update_cmd = build_terraform_docs_cmd(repo_root)
 
-if stderr:
-    print(f"terraform-docs error: Warning during execution:\n{stderr}", file=sys.stderr)
+    for directory in sorted(terraform_dirs):
+        print(f"terraform-docs: Updating documentation in {directory}")
+        target = directory if directory != "." else repo_root
+        _return_code, _stdout, stderr = run_command(update_cmd, cwd=target)
+        if stderr:
+            print(f"terraform-docs warning in {directory}: {stderr}", file=sys.stderr)
 
-# Check git status for unstaged README changes
-status_cmd = ["git", "status", "--porcelain"]
-return_code, stdout, stderr = run_command(status_cmd)
+    _return_code, stdout, _stderr = run_command(["git", "status", "--porcelain"])
+    unstaged_readmes = find_unstaged_readmes(stdout)
+    if unstaged_readmes:
+        print("terraform-docs error: Please stage any README changes before committing.")
+        return 1
 
-# Look for any README.md files in the unstaged changes
-unstaged_readmes = [
-    line.split()[-1]
-    for line in stdout.splitlines()
-    if line.startswith(" M") and line.endswith("README.md")
-]
+    print("terraform-docs: Documentation is up to date")
+    return 0
 
-# Check if we found any unstaged README files
-if len(unstaged_readmes) > 0:
-    print("terraform-docs error: Please stage any README changes before committing.")
-    sys.exit(1)
 
-print("terraform-docs: Documentation is up to date")
-sys.exit(0)
+if __name__ == "__main__":
+    sys.exit(main())

actions/terraform-docs/test_terraform_docs.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Unit tests for terraform-docs.py.
+
+These tests cover the directory-discovery and README-status parsing logic that
+underpins the monorepo-aware behaviour of the action. They do not require
+terraform-docs or git to be installed.
+
+Run with: python3 -m unittest actions/terraform-docs/test_terraform_docs.py
+"""
+
+import importlib.util
+import os
+import pathlib
+import tempfile
+import unittest
+
+HERE = pathlib.Path(__file__).resolve().parent
+SCRIPT = HERE / "terraform-docs.py"
+
+
+def _load_script_module():
+    spec = importlib.util.spec_from_file_location("terraform_docs_action", SCRIPT)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+terraform_docs = _load_script_module()
+
+
+class TerraformDirsFromPathsTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = self.tmp.name
+
+    def _touch(self, *parts):
+        path = os.path.join(self.root, *parts)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        pathlib.Path(path).touch()
+
+    def test_groups_files_by_directory(self):
+        for rel in ("modules/a/main.tf", "modules/a/vars.tf", "modules/b/main.tf"):
+            self._touch(*rel.split("/"))
+
+        dirs = terraform_docs.terraform_dirs_from_paths(
+            [
+                "modules/a/main.tf",
+                "modules/a/vars.tf",
+                "modules/b/main.tf",
+            ],
+            repo_root=self.root,
+        )
+
+        self.assertEqual(dirs, {"modules/a", "modules/b"})
+
+    def test_root_level_files_use_dot(self):
+        self._touch("main.tf")
+
+        dirs = terraform_docs.terraform_dirs_from_paths(["main.tf"], repo_root=self.root)
+
+        self.assertEqual(dirs, {"."})
+
+    def test_picks_up_all_terraform_extensions(self):
+        for rel in ("a/x.tf", "b/y.tofu", "c/z.tfvars"):
+            self._touch(*rel.split("/"))
+
+        dirs = terraform_docs.terraform_dirs_from_paths(
+            ["a/x.tf", "b/y.tofu", "c/z.tfvars"], repo_root=self.root
+        )
+
+        self.assertEqual(dirs, {"a", "b", "c"})
+
+    def test_ignores_non_terraform_files(self):
+        self._touch("modules/a/main.tf")
+        # README.md and other files should never trigger a re-run.
+        dirs = terraform_docs.terraform_dirs_from_paths(
+            ["modules/a/README.md", "src/main.go", "modules/a/main.tf"],
+            repo_root=self.root,
+        )
+
+        self.assertEqual(dirs, {"modules/a"})
+
+    def test_skips_deleted_directories(self):
+        # `modules/gone/main.tf` was deleted along with its directory; the
+        # function should silently drop it instead of crashing later when we
+        # try to chdir/run there.
+        self._touch("modules/here/main.tf")
+
+        dirs = terraform_docs.terraform_dirs_from_paths(
+            ["modules/here/main.tf", "modules/gone/main.tf"],
+            repo_root=self.root,
+        )
+
+        self.assertEqual(dirs, {"modules/here"})
+
+    def test_handles_empty_input(self):
+        self.assertEqual(
+            terraform_docs.terraform_dirs_from_paths([], repo_root=self.root),
+            set(),
+        )
+
+    def test_strips_whitespace_and_blank_lines(self):
+        self._touch("modules/a/main.tf")
+        dirs = terraform_docs.terraform_dirs_from_paths(
+            ["", "  ", "modules/a/main.tf\n"], repo_root=self.root
+        )
+        self.assertEqual(dirs, {"modules/a"})
+
+
+class BuildTerraformDocsCmdTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = self.tmp.name
+
+    def test_uses_config_when_present(self):
+        config = os.path.join(self.root, ".terraform-docs.yaml")
+        pathlib.Path(config).write_text("formatter: markdown table\n")
+
+        cmd = terraform_docs.build_terraform_docs_cmd(self.root)
+
+        self.assertEqual(cmd, ["terraform-docs", "--config", config, "."])
+
+    def test_falls_back_to_markdown_table_subcommand(self):
+        cmd = terraform_docs.build_terraform_docs_cmd(self.root)
+
+        # `markdown-table` is a single positional subcommand recognised by
+        # terraform-docs; the previous form (`markdown table`) split it across
+        # two args, which only worked by accident.
+        self.assertEqual(cmd, ["terraform-docs", "markdown-table", "."])
+
+
+class FindUnstagedReadmesTest(unittest.TestCase):
+    def test_detects_modified_but_unstaged_readme(self):
+        porcelain = " M modules/a/README.md\n"
+        self.assertEqual(
+            terraform_docs.find_unstaged_readmes(porcelain),
+            ["modules/a/README.md"],
+        )
+
+    def test_detects_partially_staged_readme(self):
+        # `MM` means staged + further unstaged changes; the unstaged half still
+        # needs to be added before the commit can land.
+        porcelain = "MM modules/a/README.md\n"
+        self.assertEqual(
+            terraform_docs.find_unstaged_readmes(porcelain),
+            ["modules/a/README.md"],
+        )
+
+    def test_detects_newly_generated_untracked_readme(self):
+        # A previously-undocumented module gets its first README.md on this
+        # run; `??` means untracked. The original code missed this case.
+        porcelain = "?? modules/new/README.md\n"
+        self.assertEqual(
+            terraform_docs.find_unstaged_readmes(porcelain),
+            ["modules/new/README.md"],
+        )
+
+    def test_ignores_fully_staged_readme(self):
+        porcelain = "M  modules/a/README.md\n"
+        self.assertEqual(terraform_docs.find_unstaged_readmes(porcelain), [])
+
+    def test_ignores_other_files(self):
+        porcelain = " M modules/a/main.tf\n M src/app.go\n"
+        self.assertEqual(terraform_docs.find_unstaged_readmes(porcelain), [])
+
+    def test_handles_multiple_entries(self):
+        porcelain = (
+            " M modules/a/README.md\n"
+            "M  modules/b/README.md\n"
+            "?? modules/c/README.md\n"
+            " M modules/d/main.tf\n"
+        )
+        self.assertEqual(
+            sorted(terraform_docs.find_unstaged_readmes(porcelain)),
+            ["modules/a/README.md", "modules/c/README.md"],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()