chore(config): add a config class for check_eip_versions

Author: danceratopz

docs/library/cli/index.md

@@ -1,4 +1,5 @@
 # EEST CLI Tools
 
+- [`check_eip_versions`](../../writing_tests/reference_specification.md) - A CLI tool to check the SHA values specified in EIP tests match the latest version from ethereum/EIPs.
 - [`eest`](eest.md) - A CLI tool that helps with routine tasks in ethereum/execution-spec-tests.
 - [`evm_bytes`](evm_bytes.md) - Convert the given EVM bytes from a binary file or a hex string to EEST's python opcodes.

docs/writing_tests/img/eip_reference_spec_console_output.png

@@ -1,14 +1,21 @@
 # Referencing an EIP Spec Version
 
-An Ethereum Improvement Proposal ([ethereum/EIPs](https://github.com/ethereum/EIPs/tree/master/EIPS)) and its SHA digest can be directly referenced within a python test module in order to check whether the test implementation could be out-dated. The test framework automatically generates tests for every module that defines a spec version. If the spec is out-of-date because the SHA of the specified file in the remote repo changes, the corresponding `test_eip_spec_version()` test fails.
+Tests that implement features from an Ethereum Improvement Proposal ([ethereum/EIPs](https://github.com/ethereum/EIPs/tree/master/EIPS)) must define the EIP's markdown SHA digest within the test's Python module. This ensures our tests stay up-to-date with any changes to the EIP specifications.
+
+The `check_eip_versions` command-line utility automatically verifies that all EIP references in the codebase are current. It works by comparing the SHA specified in the test against the latest version in the ethereum/EIPs repository. This utility uses pytest to generate test cases for every module that includes "eip" in its path.
 
 <figure markdown>  <!-- markdownlint-disable MD033 (MD033=no-inline-html) -->
   ![Test framework summary for a failing EIP spec version test](./img/eip_reference_spec_console_output.png){ width=auto align=center}
-  `<-snip->`
-  ![EIP spec version test fail](./img/eip_reference_spec_console_output_fail.png){ width=auto align=center}
 </figure>
 
-!!! info ""
+!!! note "The SHA digest value is provided in the failure message of the corresponding test"
+
+    <figure markdown>  <!-- markdownlint-disable MD033 (MD033=no-inline-html) -->
+      ![EIP spec version test fail](./img/eip_reference_spec_console_output_fail.png){ width=auto align=center}
+    </figure>
+
+!!! info "Understanding and Retrieving the EIP Markdown's SHA Digest"
+
     The SHA value is the output from git's `hash-object` command, for example:
 
     ```console
@@ -18,7 +25,7 @@ An Ethereum Improvement Proposal ([ethereum/EIPs](https://github.com/ethereum/EI
     ```
 
     and can be retrieved from the remote repo via the Github API on the command-line as following:
-    
+
     ```console
     sudo apt install jq
     curl -s -H "Accept: application/vnd.github.v3+json" \
@@ -31,10 +38,34 @@ An Ethereum Improvement Proposal ([ethereum/EIPs](https://github.com/ethereum/EI
 
 This check accomplished by adding the following two global variables anywhere in the Python source file:
 
-| Variable Name               | Explanation                                                                                                                                                        |
-|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `REFERENCE_SPEC_GIT_PATH`   | The relative path of the EIP markdown file in the [ethereum/EIPs](https://github.com/ethereum/EIPs/) repository, e.g. "`EIPS/eip-1234.md`"                         |
-| `REFERENCE_SPEC_VERSION`    | The SHA hash of the latest version of the file retrieved from the Github API:<br>`https://api.github.com/repos/ethereum/EIPs/contents/EIPS/eip-<EIP Number>.md`    |
+| Variable Name             | Explanation                                                                                                                                                     |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `REFERENCE_SPEC_GIT_PATH` | The relative path of the EIP markdown file in the [ethereum/EIPs](https://github.com/ethereum/EIPs/) repository, e.g. "`EIPS/eip-1234.md`"                      |
+| `REFERENCE_SPEC_VERSION`  | The SHA hash of the latest version of the file retrieved from the Github API:<br>`https://api.github.com/repos/ethereum/EIPs/contents/EIPS/eip-<EIP Number>.md` |
+
+## Running the `check_eip_versions` Command Locally
+
+A Github Personal Access Token (PAT) is required to avoid rate-limiting issues when using the Github API. A PAT can be created at: https://github.com/settings/personal-access-tokens/new.
+
+After setting the `GITHUB_TOKEN` environment variable to the value of your PAT, EIP versions can be checked locally using:
+
+```shell
+uv run check_eip_versions
+```
+
+By default, only tests up to and including the current fork under development will be checked. This is controlled by the `UNTIL_FORK` setting in the `src/config/check_eip_versions.py` configuration file. You can also pass a specific test path to limit the scope:
+
+```shell
+uv run check_eip_versions tests/shanghai/eip3651_warm_coinbase/
+```
+
+This would only check EIP versions for the EIP-3651 tests in the `shanghai/eip3651_warm_coinbase` sub-directory.
+
+## Automated Checks via GitHub Actions
+
+The repository includes a [GitHub Actions workflow](https://github.com/ethereum/execution-spec-tests/actions/workflows/check_eip_versions.yaml) that automatically runs `check_eip_versions` on a daily schedule. If any outdated EIP references are detected, the workflow creates an issue in the repository with details about which references need to be updated.
+
+This workflow uses GitHub's built-in token for authentication, so there's no need to configure personal access tokens for the automated checks. The issue will include links to the relevant workflow run and details about which tests need updating.
 
 ## Example
 

docs/writing_tests/img/eip_reference_spec_console_output_fail.png

@@ -6,6 +6,8 @@
 import click
 import pytest
 
+from config.check_eip_versions import CheckEipVersionsConfig
+
 from .common import common_click_options, handle_help_flags
 
 
@@ -14,6 +16,7 @@
 def check_eip_versions(pytest_args: List[str], **kwargs) -> None:
     """Run pytest with the `spec_version_checker` plugin."""
     args = ["-c", "pytest-check-eip-versions.ini"]
+    args += ["--until", CheckEipVersionsConfig().UNTIL_FORK]
     args += handle_help_flags(list(pytest_args), pytest_type="check-eip-versions")
     result = pytest.main(args)
     sys.exit(result)

docs/writing_tests/reference_specification.md

@@ -0,0 +1,10 @@
+"""A module for managing configuration for the `check_eip_version` utility."""
+
+from pydantic import BaseModel
+
+
+class CheckEipVersionsConfig(BaseModel):
+    """A class for accessing configurations for `check_eip_version`."""
+
+    UNTIL_FORK: str = "Prague"
+    """The target fork to check eip versions until."""

src/cli/pytest_commands/check_eip_versions.py

@@ -137,6 +137,7 @@ P7692
 eip7251
 eips
 EIPs
+EIP's
 el
 endianness
 EngineAPI