rds-analyzer: Instructions file for Codex

AI Agent Guidelines for RDS Analyzer

This document provides guidelines for AI agents working with the RDS Analyzer codebase.

Project Overview

RDS Analyzer is a Go CLI tool and library that evaluates kube-compare JSON reports against a set of rules. It determines the impact of configuration deviations and generates text or HTML reports.

Architecture

Package Structure

pkg/                 # Public library API - importable by external Go modules
├── analyzer/    # Orchestration - coordinates rule engine and report generation
├── parser/      # Diff parsing - transforms unified diff to structured data
├── report/      # Output generators - text (terminal) and HTML formats
├── rules/       # Rule engine - pattern matching and impact resolution
└── types/       # Data structures - shared types for validation reports
internal/
└── cli/         # Cobra CLI - command parsing and flag handling (not importable)

Data Flow

1. CLI loads rules YAML (-r). For a full run, analyzer.New calls rules.ValidateRulesRegexpPatterns (which walks the YAML AST with validateRegexPatternsFromYAML), then builds rules.Engine. With --validate-rules-only, the CLI calls rules.ValidateRulesRegexpPatterns only and exits without building an engine or reading input JSON. On regexp failure, the process exits before reading input. For library usage, analyzer.NewFromBytes accepts in-memory YAML rules bytes instead of a file path.
2. CLI reads JSON input (file or stdin) into types.ValidationReport
3. analyzer.Analyzer orchestrates processing:
   • Uses the loaded rules.Engine
   • Passes report to appropriate generator
4. Report generator:
   • Uses parser to transform diffs
   • Uses rules.Engine to evaluate each diff
   • Outputs formatted results

Regex Validation

All regex patterns in rule files are validated by rules.ValidateRulesRegexpPatterns (YAML regex walk). analyzer.New invokes it before constructing the engine for normal analysis. The --validate-rules-only path runs the same validation from the CLI without loading the full analyzer. This includes:

• regex patterns in condition rules (global_rules, rules)
• value_regex patterns in label_annotation_rules