From 0ce4e0b2d522507f42fdf4ce39a74a0ede66840d Mon Sep 17 00:00:00 2001
From: Andy Chen <amazingandyyy@gmail.com>
Date: Mon, 24 Jun 2024 13:12:08 -0700
Subject: [PATCH] docs(component): validate good component

---
 docs/modules/component.md               | 29 +++++++++++++++++++++++++
 docs/modules/index.md                   |  1 +
 hooks/domain-component-valididate/check |  7 ++++++
 3 files changed, 37 insertions(+)

diff --git a/docs/modules/component.md b/docs/modules/component.md
index e69de29..8c328e9 100644
--- a/docs/modules/component.md
+++ b/docs/modules/component.md
@@ -0,0 +1,29 @@
+# Module: Component
+
+## Define component
+
+Developer **MUST** use turo component module to define a component, and the resource name **MUST** prefix with `component_`.
+
+```tf
+module "component_good_foo_bar" {
+  source  = "app.terraform.io/turo/component-metadata/null"
+  version = "3.1.2"
+
+  name            = "good-foo-bar"
+  system_metadata = var.metadata_module.parent_system_metadata
+}
+```
+
+## Locate the component
+
+### Simple Component
+
+The component definition block **MUST** sit in a terraform file named `<component-name>.tf`
+
+For the above good-foo-bar example, the file name **MUST** be `good-foo-bar.tf`
+
+### Component module
+
+For complex component which has its own component module/folder, the component definition block **MUST** sit in the `main.tf` of the component module/folder.
+
+For the above good-foo-bar example, the file **MUST** be `<component-name>-component/main.tf`.
diff --git a/docs/modules/index.md b/docs/modules/index.md
index d47a4a6..002a372 100644
--- a/docs/modules/index.md
+++ b/docs/modules/index.md
@@ -9,5 +9,6 @@ We use modules for a few reasons:
 See:
 
 - [breaking-changes](breaking-changes.md)
+- [component](component.md)
 - [input-variables](input-variables.md)
 - [output-variables](output-variables.md)
diff --git a/hooks/domain-component-valididate/check b/hooks/domain-component-valididate/check
index 2878eac..a3d8791 100755
--- a/hooks/domain-component-valididate/check
+++ b/hooks/domain-component-valididate/check
@@ -1,5 +1,10 @@
 #!/bin/bash -e
 
+# This script check if the component usage is valid:
+
+# allow case: <component>.tf
+# allow case: <component>-component/main.tf
+
 # Function to check if module names follow the 'component_<name>' convention
 check_component_module_id() {
 	local module_name="$1"
@@ -25,6 +30,8 @@ check_component_file_name() {
 	parent_directory=$(dirname "$file")
 	parent_directory_name=$(basename "$parent_directory")
 
+  # allow <component>.tf
+  # allow <component>-component/main.tf
 	if [[ "$filename" != "$expected_file" && ("$filename" != "main.tf" || ! "$parent_directory_name" =~ -component$) ]]; then
 		echo "ERROR: Module '$module_name' with name '$component_name' should be in '$expected_file' or a 'main.tf' within a directory ending with '-component', but found in '$filename'."
 		return 1