proper-docs2

Author: edcdavid

docs/github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/README.md

@@ -0,0 +1,77 @@
+## Package main (github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite)
+
+# certsuite – Command‑line entry point
+
+`cmd/certsuite/main.go` is the sole executable package of the **certsuite** tool.  
+It wires together a set of sub‑commands (check, claim, generate, info, run,
+upload, version) and hands control over to Cobra’s command dispatcher.
+
+---
+
+## Core functions
+
+| Function | Purpose | Key interactions |
+|----------|---------|------------------|
+| `newRootCmd() *cobra.Command` | Builds the top‑level command tree. | Calls `NewCommand()` from each sub‑package (`check`, `claim`, …) and registers them via `AddCommand`. |
+| `main()` | Entry point for the binary. | Instantiates the root command, executes it with `Execute()`, logs any errors (`log.Error`) and exits with `os.Exit(1)` on failure. |
+
+---
+
+## How the command tree is built
+
+```mermaid
+graph TD;
+  main --> newRootCmd
+  newRootCmd -->|AddCommand| check.NewCommand()
+  newRootCmd --> claim.NewCommand()
+  newRootCmd --> generate.NewCommand()
+  newRootCmd --> info.NewCommand()
+  newRootCmd --> run.NewCommand()
+  newRootCmd --> upload.NewCommand()
+  newRootCmd --> version.NewCommand()
+```
+
+Each `NewCommand()` returns a fully configured `*cobra.Command` that knows how
+to parse its own flags and perform the requested action.  
+The root command simply acts as a dispatcher; all heavy lifting happens in
+those sub‑packages.
+
+---
+
+## Error handling
+
+```go
+if err := cmd.Execute(); err != nil {
+    log.Error(err)
+    os.Exit(1)
+}
+```
+
+* `log` is an internal wrapper around the standard logger, providing a unified
+  error output format.  
+* On any failure during command parsing or execution the program terminates with
+  status code **1**.
+
+---
+
+## Summary
+
+- The package contains only two functions: `main()` and `newRootCmd()`.  
+- `newRootCmd` constructs a Cobra root command and attaches sub‑commands from
+  dedicated packages.  
+- `main` runs the command tree, logs errors, and exits appropriately.
+
+This design keeps the executable thin; all domain logic lives in the
+sub‑packages, making the CLI straightforward to maintain and extend.
+
+### Functions
+
+
+### Call graph (exported symbols, partial)
+
+```mermaid
+graph LR
+```
+
+### Symbol docs
+

docs/github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/check/README.md

@@ -0,0 +1,110 @@
+## Package check (github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/check)
+
+# Package `check`
+
+The **`check`** package is a thin wrapper that stitches together the CLI commands for CertSuite’s
+*image‑certificate* checks and result handling.  
+It lives under `github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/check`.
+
+---
+
+## Global state
+
+| Name      | Type (inferred) | Purpose |
+|-----------|-----------------|---------|
+| `checkCmd` | `*cobra.Command` | Root command that will be returned by `NewCommand`. It is the entry point for all sub‑commands added in this package. |
+
+> The variable is unexported because it is only used internally when constructing the root
+> command tree.
+
+---
+
+## Key function
+
+### `NewCommand() *cobra.Command`
+
+```go
+func NewCommand() *cobra.Command
+```
+
+* **What it does**  
+  - Instantiates a new `checkCmd` root command (via its zero value, which is a `cobra.Command`).  
+  - Adds sub‑commands from the two internal packages:
+    - `image_cert_status.NewCommand()` – handles checks against image certificates.
+    - `results.NewCommand()` – deals with displaying or storing test results.  
+  - Returns the fully built command tree so that it can be wired into the top‑level CertSuite CLI.
+
+* **How it works**  
+
+```go
+func NewCommand() *cobra.Command {
+    // Add subcommands to the root
+    checkCmd.AddCommand(image_cert_status.NewCommand())
+    checkCmd.AddCommand(results.NewCommand())
+
+    return checkCmd
+}
+```
+
+  Each `AddCommand` call registers a new child command, allowing users to run e.g.
+  
+  ```bash
+  certsuite check image-cert-status …   # delegated to image_cert_status package
+  certsuite check results …             # delegated to results package
+  ```
+
+* **Dependencies**  
+
+| Dependency | Why it is needed |
+|------------|-----------------|
+| `github.com/spf13/cobra` | Provides the command‑line framework. |
+| `image_cert_status.NewCommand()` | Supplies the image‑certificate check subcommand. |
+| `results.NewCommand()` | Supplies the results subcommand. |
+
+---
+
+## How everything connects
+
+```
+certsuite (top level)
+  └── check
+        ├─ NewCommand() → returns *cobra.Command
+        │    ├─ rootCmd := checkCmd
+        │    ├─ add image_cert_status.NewCommand()
+        │    └─ add results.NewCommand()
+        └── sub‑commands:
+             ├─ image-cert-status (from image_cert_status package)
+             └─ results              (from results package)
+```
+
+The `check` command acts purely as a *command router*; it does not contain business logic itself.  
+All real functionality lives in the two imported packages, each of which follows the same
+Cobra pattern for defining flags and execution logic.
+
+---
+
+## Summary
+
+- **Global**: `checkCmd` – the root Cobra command.
+- **Function**: `NewCommand()` builds the command tree by attaching sub‑commands from
+  `image_cert_status` and `results`.
+- The package itself is a lightweight glue layer; all heavy lifting happens in its child packages.
+
+### Functions
+
+- **NewCommand** — func()(*cobra.Command)
+
+### Globals
+
+
+### Call graph (exported symbols, partial)
+
+```mermaid
+graph LR
+  NewCommand --> AddCommand
+  NewCommand --> AddCommand
+```
+
+### Symbol docs
+
+- [function NewCommand](symbols/function_NewCommand.md)

docs/github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/check/image_cert_status/README.md

@@ -0,0 +1,115 @@
+## Package imagecert (github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/check/image_cert_status)
+
+## `imagecert` Package – Overview
+
+| Topic | Summary |
+|-------|---------|
+| **Purpose** | Implements the `check image-cert-status` command for CertSuite, reporting whether a container image is certified and what policy it satisfies. |
+| **Key Exported API** | `NewCommand() *cobra.Command` – creates the Cobra command that gets wired into CertSuite’s CLI tree. |
+| **Internal State** | A single unexported global variable: `checkImageCertStatusCmd`, a `*cobra.Command`. |
+
+---
+
+### Global Variable
+
+```go
+var checkImageCertStatusCmd *cobra.Command
+```
+
+- Holds the command instance created by `NewCommand`.
+- Used only internally; not exposed to other packages.
+
+---
+
+### Core Functions
+
+#### 1. `checkImageCertStatus(cmd *cobra.Command, args []string) error`
+
+* **Role** – The actual execution logic for the command.  
+* **Workflow**:
+  1. **Read Flags** – Uses `cmd.Flags().GetString(...)` to obtain values for
+     - `image`
+     - `registry-url`
+     - `policy-name`
+     - `policy-version`
+  2. **Validation** – Calls `cmd.GetValidator()` (from the `certdb` package) and checks that the provided image is certified:
+     ```go
+     if err := validator.IsContainerCertified(image, registryURL, policyName, policyVersion); err != nil {
+         // error handling
+     }
+     ```
+  3. **Output** – Prints human‑readable status using `fmt` and color helpers from `github.com/fatih/color`.  
+     - Certified → green “YES”
+     - Not certified → red “NO” plus reason.
+  4. **Error Handling** – Returns descriptive errors for missing flags or validation failures.
+
+#### 2. `NewCommand() *cobra.Command`
+
+* **Role** – Constructs and configures the Cobra command that will be registered under CertSuite’s CLI tree.  
+* **Key Steps**:
+  - Instantiates `checkImageCertStatusCmd` with usage, short description, and the RunE handler set to `checkImageCertStatus`.
+  - Declares persistent flags (`image`, `registry-url`, `policy-name`, `policy-version`) using `cmd.PersistentFlags().String(...)`.
+  - Enforces flag rules:
+    * `MarkFlagsRequiredTogether` – ensures that `image` is always supplied with the other three flags.
+    * `MarkFlagsMutuallyExclusive` – guarantees no conflicting combinations (e.g., image vs. registry only).
+* **Return** – The fully configured command pointer.
+
+---
+
+### How Things Connect
+
+```mermaid
+graph TD;
+    A[User runs: certsuite check image-cert-status] --> B[NewCommand registers cmd];
+    B --> C[checkImageCertStatus executes on RunE];
+    C --> D{Read Flags};
+    D --> E[Validator.IsContainerCertified];
+    E -- certified --> F[Print green YES];
+    E -- not certified --> G[Print red NO + reason];
+    F & G --> H[Return nil or error];
+```
+
+1. **CLI entry point** (`certsuite check image-cert-status`) triggers Cobra’s command lookup.
+2. `NewCommand` supplies the command definition to Cobra during initialization.
+3. When executed, `checkImageCertStatus` pulls flag values, delegates certification logic to `certdb.Validator`, and formats output.
+
+---
+
+### Dependencies
+
+| Package | Role |
+|---------|------|
+| `github.com/fatih/color` | ANSI color helpers for terminal output. |
+| `github.com/redhat-best-practices-for-k8s/oct/pkg/certdb` | Provides the `Validator` interface and certification logic. |
+| `github.com/spf13/cobra` | CLI framework; handles command registration, flag parsing, and execution flow. |
+
+---
+
+### Summary
+
+The `imagecert` package is a thin wrapper around CertSuite’s validation engine that exposes a user‑friendly CLI subcommand. It relies on Cobra for argument handling and `certdb.Validator` for the actual certification check, presenting results with colorized console output. The design keeps all state local to the command instance (`checkImageCertStatusCmd`) and offers no exported types beyond the constructor.
+
+### Functions
+
+- **NewCommand** — func()(*cobra.Command)
+
+### Globals
+
+
+### Call graph (exported symbols, partial)
+
+```mermaid
+graph LR
+  NewCommand --> String
+  NewCommand --> PersistentFlags
+  NewCommand --> String
+  NewCommand --> PersistentFlags
+  NewCommand --> String
+  NewCommand --> PersistentFlags
+  NewCommand --> String
+  NewCommand --> PersistentFlags
+```
+
+### Symbol docs
+
+- [function NewCommand](symbols/function_NewCommand.md)

docs/github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/check/image_cert_status/symbols/function_NewCommand.md

@@ -0,0 +1,86 @@
+NewCommand` – CLI entry point for the *image‑cert‑status* sub‑command
+
+```go
+func NewCommand() (*cobra.Command)
+```
+
+---
+
+## Purpose  
+Creates and configures a **Cobra** command that checks the status of container image certificates.  
+The returned `*cobra.Command` is intended to be added to the top‑level *check* command of the CertSuite CLI.
+
+---
+
+## Inputs / Outputs  
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| none | – | The function receives no arguments; all configuration comes from package‑wide defaults and flag values. |
+
+| Return value | Type | Meaning |
+|--------------|------|---------|
+| `*cobra.Command` | pointer to a Cobra command | Fully configured command ready for execution. Returns `nil` only if an internal error occurs (which never happens in the current implementation). |
+
+---
+
+## Key Flag Configuration  
+
+The function registers **six persistent string flags** on the command:
+
+| Flag name | Description |
+|-----------|-------------|
+| `--image-name` | Target image name to inspect. |
+| `--namespace` | Kubernetes namespace where the image is deployed. |
+| `--pod-name` | Pod name that runs the target container. |
+| `--container-name` | Specific container inside the pod. |
+| `--cluster-url` | URL of the cluster API server (optional; may default to in‑cluster config). |
+| `--ca-file` | Path to a custom CA bundle for TLS verification. |
+
+> **Flag relationships**  
+> *All six flags are required together* – the command will fail if any subset is omitted.  
+> Flags are also marked as *mutually exclusive*, preventing conflicting combinations (e.g., specifying both `--pod-name` and `--container-name` without a namespace).
+
+These constraints are enforced via:
+
+```go
+MarkFlagsRequiredTogether(...)
+MarkFlagsMutuallyExclusive(...)
+```
+
+---
+
+## Dependencies & Side Effects  
+
+| Dependency | Role |
+|------------|------|
+| `github.com/spf13/cobra` | Provides the command structure, flag handling, and execution plumbing. |
+| Global variable `checkImageCertStatusCmd` | Holds the constructed command; used elsewhere in the package to register sub‑commands. |
+
+The function has **no observable side effects** beyond populating the global variable. It does not modify any external state or perform I/O.
+
+---
+
+## Package Context  
+
+*Package*: `imagecert` (path:  
+`github.com/redhat-best-practices-for-k8s/certsuite/cmd/certsuite/check/image_cert_status`)  
+
+This package implements a single sub‑command of the CertSuite CLI that verifies whether a container image has an appropriate certificate attached. `NewCommand` is the public entry point that creates this command; callers typically invoke it during application bootstrap:
+
+```go
+checkCmd.AddCommand(imagecert.NewCommand())
+```
+
+---
+
+## Suggested Mermaid Diagram (Optional)
+
+```mermaid
+graph TD
+    A[CertSuite CLI] --> B[check Command]
+    B --> C[image_cert_status.Command]
+    C -.-> D[Flags: image-name, namespace, pod-name, container-name, cluster-url, ca-file]
+```
+
+This visual clarifies how the command fits into the overall CLI hierarchy.