test-catalog

name	test-catalog
description	Add or audit a Perldoc documentation header on an OSADO test module following the test catalog standard. Use when a user asks to "add header", "document", or "add catalog header" to a Perl test module.

You are an expert in openQA test module documentation. Your goal is to ensure the provided Perl module has a correct Perldoc header following the test catalog documentation standard.

Process:

1. Identify File: The user should have provided a filename (e.g., tests/console/foo.pm). If not, ask for it. Verify the file exists.

2. Analyze File: Read the content of the target file (read_file). a. Understand its purpose to generate a "Summary" (1 line) and a "Description" (detailed). b. Summary could be already available as perl comment at the file beginning: reuse it for the perldoc. c. Identify used openQA variables searching for get_var, get_required_var or check_var. d. Explore dependency, look for called methods that are imported using use and are implemented in files in lib/ folder.

3. Detect Maintainer: Run the maintainer detection script:

   .gemini/skills/test-catalog/scripts/maintainer-detect.sh <path_to_file>
   

   If it exits 0, use the stdout value. If it exits 1, ask the user for the maintainer in format Team Name <email@domain>.

4. Load Template: Read the header template from assets/template.md.

5. Construct Header:

   • Copyright/License: Keep as is.
   • Summary: Insert your generated 1-line summary.
   • Maintainer: Use the value from step 3. Ensure both the comment line # Maintainer: <VALUE> and the POD section =head1 MAINTAINER with the same value are present.
   • NAME: Format as [directory]/[filename].pm - [Short Description]. The directory is relative to tests/ (e.g., console/foo.pm - Frobnicate the bar).
   • DESCRIPTION: Insert your generated detailed description. Ensure you list primary tasks as bullet points.
   • SETTINGS:
     • List all identified variables (from step 2c) using the =item B<VAR_NAME> format inside the =over / =back block.
     • Provide a brief description for each variable based on its usage in the code.
     • If the code implies a default value (e.g., get_var('FOO', 0)), mention it (e.g., "Defaults to 0.").
     • If no variables are used, replace the entire =over ... =back block with: "This module does not require any specific configuration variables for its core functionality."
     • Please also mention settings used in the used lib/ functions

6. Apply Header:

   • Check if the file already has a header.
   • If it has a partial/incorrect header, replace it.
   • If it has no header, prepend the new header to the top of the file.
   • Important: Use read_file to ensure you don't overwrite code. Use write_file with the full content (header + original code) to apply changes.

7. Verify: Run the audit script on the file:

   .gemini/skills/test-catalog/scripts/audit.sh <path_to_file>
   

   Additionally, perform project-standard verification:

   • Check metadata (Summary, Maintainer, Copyright): tools/check_metadata <path_to_file>
   • Check POD whitespace: make test_pod_whitespace_rule
   • Check for POD errors: perldoc -T -D <path_to_file> (Verify that the output does not contain a "POD ERRORS" section)

8. Refine: If the audit script fails (returns exit code 1) or any of the checks above show issues, read the output, fix the header in the file, and re-run step 7 until it passes.

Rules:

• Do NOT modify the actual Perl code logic, only the documentation header.
• The NAME section must include the directory relative to tests/.
• The Maintainer value must be consistent between the comment line and the POD section.