refactor/improve logging

AGENTS.md

@@ -79,6 +79,26 @@ imports into the middle of a file or even at the start of a function or class.
 - Support Python 3.11, 3.12, and 3.13 on MacOS, Linux, and Windows.
 - Use Pydantic models for data validation and JSON serialization.
 
+## Project Behavior Requirements
+
+- The `pytest-brightest` plugin works in the follow general way when it
+  comes to revising the execution of a Pytest test suite:
+  - Step 1: If the plugin is enabled, but there is no data,
+    then run the test suite as normal.
+  - Step 2: If the plugin is enabled and there is data, then run the
+    test suite based on the data from the prior run of the plugin.
+  - Step 3: Use the data collected by pytest-json-report to compute
+    the values for the cost and failure data for each test case and
+    for the test modules.
+  - Step 4: While keeping all prior data that was recorded by the tool,
+    the plugin will then update the data with the new cost and failure
+    data for each test case and for the test modules.
+  - Step 5: The plugin will then write the updated data to the
+    `pytest-brightest.json` file in the configured directory.
+- Critically, the `pytest-brightest` plugin should not, for instance,
+  delete data from a prior run unless the tool is beyond the maximum
+  amount of test runs that it is configured to persist.
+
 ## Test Requirements
 
 All test cases should follow these standards:
@@ -94,6 +114,7 @@ All test cases should follow these standards:
 - Test cases should aim to achieve full function, statement, and branch
   coverage.
 - Property-based tests must be marked with `@pytest.mark.property`.
+- Test cases should not produce any console output.
 
 ## Making Changes
 
@@ -110,3 +131,11 @@ All test cases should follow these standards:
 7. **Completion**: When you are finished with tasks, please summarize what tasks
    you completed, how you completed them, the challenges you faced, how you
    overcame them, and the rules that you followed during completion of the tasks.
+
+## Additional Notes for the Coding Agent
+
+Note: This file is specifically for coding agents and this section can be used
+by the coding agent to add additional details about this project that would
+be helpful for the agent to know when it is run again. Every time a coding
+agent finishes a task, it should add notes here as it deems appropriate.
+The coding agent should write the notes as a Markdown list.

ARGUMENTS.md

@@ -0,0 +1,62 @@
+# Command-Line Arguments Checklist
+
+This document provides a checklist of valid and invalid command-line arguments
+for `pytest-brightest`. It is intended to be used as a guide for manual and
+automated testing.
+
+## Valid Command-Line Arguments
+
+### Reordering by Cost
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-by-focus modules-within-suite --reorder-in-direction ascending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-by-focus modules-within-suite --reorder-in-direction descending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-by-focus tests-within-module --reorder-in-direction ascending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-by-focus tests-within-module --reorder-in-direction descending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-by-focus tests-across-modules --reorder-in-direction ascending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-by-focus tests-across-modules --reorder-in-direction descending`
+
+### Reordering by Name
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique name --reorder-by-focus modules-within-suite --reorder-in-direction ascending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique name --reorder-by-focus modules-within-suite --reorder-in-direction descending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique name --reorder-by-focus tests-within-module --reorder-in-direction ascending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique name --reorder-by-focus tests-within-module --reorder-in-direction descending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique name --reorder-by-focus tests-across-modules --reorder-in-direction ascending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique name --reorder-by-focus tests-across-modules --reorder-in-direction descending`
+
+### Reordering by Failure
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique failure --reorder-by-focus modules-within-suite --reorder-in-direction ascending`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique failure --reorder-by-focus modules-within-suite --reorder-in-direction descending`
+
+### Shuffling
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique shuffle --reorder-by-focus modules-within-suite`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique shuffle --reorder-by-focus tests-within-module`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique shuffle --reorder-by-focus tests-across-modules`
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique shuffle --seed 12345`
+
+## Invalid Command-Line Arguments
+
+### Missing `--brightest`
+
+- [ ] `uv run pytest --json-report --reorder-by-technique cost` (Plugin should not activate)
+
+### Invalid Technique
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique invalid_technique` (Should raise an error)
+
+### Invalid Focus
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-by-focus invalid_focus` (Should raise an error)
+
+### Invalid Direction
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --reorder-in-direction invalid_direction` (Should raise an error)
+
+### Conflicting Arguments
+
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique shuffle --reorder-in-direction ascending` (Direction should be ignored)
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique cost --seed 12345` (Seed should be ignored)
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique failure --reorder-by-focus tests-within-module` (Not a valid combination)
+- [ ] `uv run pytest --json-report --brightest --reorder-by-technique failure --reorder-by-focus tests-across-modules` (Not a valid combination)

GEMINI.md

@@ -7,20 +7,24 @@ changes to this repository. Your primary goal is to make safe, incremental,
 and high-quality contributions.
 
 - **Always use `uv`:** This project uses `uv` for all dependency management,
-  virtual environments, and task running. Do not use `pip` or `venv` directly.
+virtual environments, and task running. Do not use `pip` or `venv` directly.
 - **Follow all guidelines:** This document contains the complete set of
-  guidelines from `AGENTS.md` and `docs/plan.md`. You must follow them strictly.
+guidelines from `AGENTS.md` and `docs/plan.md`. You must follow them strictly.
 - **Verify your changes:** Before committing any changes, you must run all
-  linters and tests to ensure your changes are correct and follow the project's
-  style. Use `uv run task all`.
-- **Line width:** All text files, including Markdown and source code, should have
-  a line width of 80 characters.
-- **Permission to run commands:** You have permission to run all commands in this
-  file to verify their functionality.
-- **Incremental changes:** Make small, incremental changes. This makes it easier
-  to review your work and catch errors early.
+linters and tests to ensure your changes are correct and follow the project's
+style. Use `uv run task all`.
+- **Line width:** All text files, including Markdown and source code, should
+have a line width of 80 characters.
+- **Permission to run commands:** You have permission to run all commands in
+this file to verify their functionality.
+- **Incremental changes:** Make small, incremental changes. This makes it
+easier to review your work and catch errors early.
 - **Communicate clearly:** When you propose changes, explain what you've done
-  and why.
+and why.
+- **Save your plan:** Save a copy of your plan for completing a task in the
+`docs/plan.md` file. There is a section called `Current Plan` at the bottom of
+the file and you can save your plan there. Create a new sub-sub-section with
+the title of your plan and the date you plan to complete it.
 
 As a Gemini agent, you must also follow these behavior guidelines, especially
 when it comes to notifying the programmer about your work and status:
@@ -83,6 +87,26 @@ messages.
 - Support Python 3.11, 3.12, and 3.13 on MacOS, Linux, and Windows.
 - Use Pydantic models for data validation and JSON serialization.
 
+## Project Behavior Requirements
+
+- The `pytest-brightest` plugin works in the follow general way when it
+  comes to revising the execution of a Pytest test suite:
+  - Step 1: If the plugin is enabled, but there is no data,
+    then run the test suite as normal.
+  - Step 2: If the plugin is enabled and there is data, then run the
+    test suite based on the data from the prior run of the plugin.
+  - Step 3: Use the data collected by pytest-json-report to compute
+    the values for the cost and failure data for each test case and
+    for the test modules.
+  - Step 4: While keeping all prior data that was recorded by the tool,
+    the plugin will then update the data with the new cost and failure
+    data for each test case and for the test modules.
+  - Step 5: The plugin will then write the updated data to the
+    `pytest-brightest.json` file in the configured directory.
+- Critically, the `pytest-brightest` plugin should not, for instance,
+  delete data from a prior run unless the tool is beyond the maximum
+  amount of test runs that it is configured to persist.
+
 ## Test Requirements
 
 All test cases should follow these standards:
@@ -98,6 +122,7 @@ All test cases should follow these standards:
 - Test cases should aim to achieve full function, statement, and branch
   coverage.
 - Property-based tests must be marked with `@pytest.mark.property`.
+- Test cases should not produce any console output.
 
 ## Making Changes
 
@@ -114,3 +139,11 @@ All test cases should follow these standards:
 7. **Completion**: When you are finished with tasks, please summarize what tasks
    you completed, how you completed them, the challenges you faced, how you
    overcame them, and the rules that you followed during completion of the tasks.
+
+## Additional Notes for the Gemini Agent
+
+Note: This file is specifically for Gemini agents and this section can be used
+by the Gemini agent to add additional details about this project that would
+be helpful for the agent to know when it is run again. Every time a Gemini
+agent finishes a task, it should add notes here as it deems appropriate.
+The Gemini agent should write the notes as a Markdown list.

README.md

@@ -9,6 +9,7 @@
 [![Coverage](https://img.shields.io/badge/dynamic/json?color=brightgreen&label=coverage&query=%24.totals.percent_covered_display&suffix=%25&url=https%3A//raw.githubusercontent.com/wiki/AstuteSource/pytest-brightest/coverage.json)](https://github.com/AstuteSource/pytest-brightest)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytest-brightest)
 ![PyPI - Version](https://img.shields.io/pypi/v/pytest-brightest?logoColor=blue&color=blue)
+[![PyPI Downloads](https://static.pepy.tech/badge/pytest-brightest)](https://pepy.tech/projects/pytest-brightest)
 [![Maintenance](https://img.shields.io/badge/maintained%3F-Yes-blue.svg)](https://github.com/AstuteSource/pytest-brightest/graphs/commit-activity)
 [![License LGPL v3](https://img.shields.io/badge/license-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)