feature: Inspector Gadget

pkg/inspector/.relspec-rules.yaml.example

@@ -0,0 +1,177 @@
+# RelSpec Inspector Rules Configuration Example
+# Copy this file to .relspec-rules.yaml and customize as needed
+
+version: "1.0"
+
+rules:
+  # ============================================================================
+  # PRIMARY KEY RULES
+  # ============================================================================
+
+  # Validate primary key column naming convention
+  primary_key_naming:
+    enabled: warn  # enforce|warn|off
+    function: primary_key_naming
+    pattern: "^id_"  # Regex pattern - PK columns must start with "id_"
+    message: "Primary key columns should start with 'id_'"
+
+  # Validate primary key data types
+  primary_key_datatype:
+    enabled: warn
+    function: primary_key_datatype
+    allowed_types:
+      - bigserial
+      - bigint
+      - int
+      - serial
+      - integer
+      - int4
+      - int8
+    message: "Primary keys should use integer types (bigserial, bigint, int, serial)"
+
+  # Check if primary keys have auto-increment enabled
+  primary_key_auto_increment:
+    enabled: off  # Often disabled as not all PKs need auto-increment
+    function: primary_key_auto_increment
+    require_auto_increment: true
+    message: "Primary key without auto-increment detected"
+
+  # ============================================================================
+  # FOREIGN KEY RULES
+  # ============================================================================
+
+  # Validate foreign key column naming convention
+  foreign_key_column_naming:
+    enabled: warn
+    function: foreign_key_column_naming
+    pattern: "^rid_"  # FK columns must start with "rid_" (referenced id)
+    message: "Foreign key columns should start with 'rid_'"
+
+  # Validate foreign key constraint naming convention
+  foreign_key_constraint_naming:
+    enabled: warn
+    function: foreign_key_constraint_naming
+    pattern: "^fk_"  # FK constraints must start with "fk_"
+    message: "Foreign key constraint names should start with 'fk_'"
+
+  # Ensure foreign key columns have indexes for performance
+  foreign_key_index:
+    enabled: warn
+    function: foreign_key_index
+    require_index: true
+    message: "Foreign key columns should have indexes for optimal performance"
+
+  # ============================================================================
+  # NAMING CONVENTION RULES
+  # ============================================================================
+
+  # Validate table naming follows snake_case convention
+  table_naming_case:
+    enabled: warn
+    function: table_regexpr  # Generic regex validator for table names
+    case: lowercase
+    pattern: "^[a-z][a-z0-9_]*$"  # Lowercase letters, numbers, underscores only
+    message: "Table names should be lowercase with underscores (snake_case)"
+
+  # Validate column naming follows snake_case convention
+  column_naming_case:
+    enabled: warn
+    function: column_regexpr  # Generic regex validator for column names
+    case: lowercase
+    pattern: "^[a-z][a-z0-9_]*$"  # Lowercase letters, numbers, underscores only
+    message: "Column names should be lowercase with underscores (snake_case)"
+
+  # ============================================================================
+  # LENGTH RULES
+  # ============================================================================
+
+  # Limit table name length (PostgreSQL max is 63, but 64 is common practice)
+  table_name_length:
+    enabled: warn
+    function: table_name_length
+    max_length: 64
+    message: "Table name exceeds recommended maximum length of 64 characters"
+
+  # Limit column name length
+  column_name_length:
+    enabled: warn
+    function: column_name_length
+    max_length: 64
+    message: "Column name exceeds recommended maximum length of 64 characters"
+
+  # ============================================================================
+  # RESERVED KEYWORDS
+  # ============================================================================
+
+  # Warn about using SQL reserved keywords as identifiers
+  reserved_keywords:
+    enabled: warn
+    function: reserved_words
+    check_tables: true
+    check_columns: true
+    message: "Using SQL reserved keywords as identifiers can cause issues"
+
+  # ============================================================================
+  # SCHEMA INTEGRITY RULES
+  # ============================================================================
+
+  # Ensure all tables have primary keys
+  missing_primary_key:
+    enabled: warn
+    function: have_primary_key
+    message: "Table is missing a primary key"
+
+  # Detect orphaned foreign keys (referencing non-existent tables)
+  orphaned_foreign_key:
+    enabled: warn
+    function: orphaned_foreign_key
+    message: "Foreign key references a non-existent table"
+
+  # Detect circular foreign key dependencies
+  circular_dependency:
+    enabled: warn
+    function: circular_dependency
+    message: "Circular foreign key dependency detected"
+
+# ============================================================================
+# RULE CONFIGURATION NOTES
+# ============================================================================
+#
+# enabled: Controls rule enforcement level
+#   - enforce: Violations are errors (exit code 1)
+#   - warn:    Violations are warnings (exit code 0)
+#   - off:     Rule is disabled
+#
+# function: The validation function to execute
+#   - Must match a registered validator function
+#   - Generic functions like table_regexpr and column_regexpr can be reused
+#
+# pattern: Regular expression for pattern matching
+#   - Used by naming validators
+#   - Must be valid Go regex syntax
+#
+# message: Custom message shown when rule is violated
+#   - Should be clear and actionable
+#   - Explains what the violation is and how to fix it
+#
+# ============================================================================
+# CUSTOM RULES EXAMPLES
+# ============================================================================
+#
+# You can add custom rules using the generic validator functions:
+#
+#   # Example: Ensure table names don't contain numbers
+#   table_no_numbers:
+#     enabled: warn
+#     function: table_regexpr
+#     pattern: "^[a-z_]+$"
+#     message: "Table names should not contain numbers"
+#
+#   # Example: Audit columns must end with _audit
+#   audit_column_suffix:
+#     enabled: enforce
+#     function: column_regexpr
+#     pattern: ".*_audit$"
+#     message: "Audit columns must end with '_audit'"
+#
+# ============================================================================