ethspecify 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

ethspecify/cli.py

@@ -3,7 +3,7 @@ import json
 import os
 import sys
 
-from .core import grep, replace_spec_tags, get_pyspec, get_latest_fork
+from .core import grep, replace_spec_tags, get_pyspec, get_latest_fork, get_spec_item_history, load_config, run_checks
 
 
 def process(args):
@@ -13,86 +13,122 @@ def process(args):
         print(f"Error: The directory {repr(project_dir)} does not exist.")
         return 1
 
+    # Load config once from the project directory
+    config = load_config(project_dir)
+
     for f in grep(project_dir, r"<spec\b.*?>", args.exclude):
         print(f"Processing file: {f}")
-        replace_spec_tags(f)
+        replace_spec_tags(f, config)
 
     return 0
 
 
 def list_tags(args):
-    """List all available tags for a specific fork and preset."""
-    # Get the specification data
-    pyspec = get_pyspec()
-    fork = args.fork
-    preset = args.preset
+    """List all available tags with their fork history."""
+    preset = getattr(args, 'preset', 'mainnet')
+    return _list_tags_with_history(args, preset)
+
 
-    # Validate that the fork exists
-    if fork not in pyspec[preset]:
-        print(f"Error: Fork '{fork}' not found in {preset} preset")
-        available_forks = list(pyspec[preset].keys())
-        print(f"Available forks: {', '.join(available_forks)}")
+def _list_tags_with_history(args, preset):
+    """List all tags with their fork history."""
+    try:
+        history = get_spec_item_history(preset)
+    except ValueError as e:
+        print(f"Error: {e}")
         return 1
 
-    # Format output based on requested format
     if args.format == "json":
         result = {
-            "fork": fork,
             "preset": preset,
-            "tags": {
-                "functions": list(pyspec[preset][fork]['functions'].keys()),
-                "constant_vars": list(pyspec[preset][fork]['constant_vars'].keys()),
-                "custom_types": list(pyspec[preset][fork]['custom_types'].keys()),
-                "ssz_objects": list(pyspec[preset][fork]['ssz_objects'].keys()),
-                "dataclasses": list(pyspec[preset][fork]['dataclasses'].keys()),
-                "preset_vars": list(pyspec[preset][fork]['preset_vars'].keys()),
-                "config_vars": list(pyspec[preset][fork]['config_vars'].keys()),
-            }
+            "mode": "history",
+            "history": history
         }
         print(json.dumps(result, indent=2))
     else:
-        # Plain text output
-        print(f"Available tags for {fork} fork ({preset} preset):")
-        maybe_fork = f' fork="{fork}"' if fork != get_latest_fork() else ""
-
-        print("\nFunctions:")
-        for fn_name in sorted(pyspec[preset][fork]['functions'].keys()):
-            if args.search is None or args.search.lower() in fn_name.lower():
-                print(f"  <spec fn=\"{fn_name}\"{maybe_fork} />")
-
-        print("\nConstants:")
-        for const_name in sorted(pyspec[preset][fork]['constant_vars'].keys()):
-            if args.search is None or args.search.lower() in const_name.lower():
-                print(f"  <spec constant_var=\"{const_name}\"{maybe_fork} />")
-
-        print("\nCustom Types:")
-        for type_name in sorted(pyspec[preset][fork]['custom_types'].keys()):
-            if args.search is None or args.search.lower() in type_name.lower():
-                print(f"  <spec custom_type=\"{type_name}\"{maybe_fork} />")
-
-        print("\nSSZ Objects:")
-        for obj_name in sorted(pyspec[preset][fork]['ssz_objects'].keys()):
-            if args.search is None or args.search.lower() in obj_name.lower():
-                print(f"  <spec ssz_object=\"{obj_name}\"{maybe_fork} />")
-
-        print("\nDataclasses:")
-        for class_name in sorted(pyspec[preset][fork]['dataclasses'].keys()):
-            if args.search is None or args.search.lower() in class_name.lower():
-                print(f"  <spec dataclass=\"{class_name}\"{maybe_fork} />")
-
-        print("\nPreset Variables:")
-        for var_name in sorted(pyspec[preset][fork]['preset_vars'].keys()):
-            if args.search is None or args.search.lower() in var_name.lower():
-                print(f"  <spec preset_var=\"{var_name}\"{maybe_fork} />")
-
-        print("\nConfig Variables:")
-        for var_name in sorted(pyspec[preset][fork]['config_vars'].keys()):
-            if args.search is None or args.search.lower() in var_name.lower():
-                print(f"  <spec config_var=\"{var_name}\"{maybe_fork} />")
+        print(f"Available tags across all forks ({preset} preset):")
+
+        def _print_items_with_history(category_name, items_dict, spec_attr):
+            """Helper to print items with their fork history."""
+            if not items_dict:
+                return
+            print(f"\n{category_name}:")
+            for item_name in sorted(items_dict.keys()):
+                if args.search is None or args.search.lower() in item_name.lower():
+                    forks = items_dict[item_name]
+                    fork_list = ", ".join(forks)
+                    print(f"  <spec {spec_attr}=\"{item_name}\" /> ({fork_list})")
+
+        _print_items_with_history("Functions", history['functions'], "fn")
+        _print_items_with_history("Constants", history['constant_vars'], "constant_var")
+        _print_items_with_history("Custom Types", history['custom_types'], "custom_type")
+        _print_items_with_history("SSZ Objects", history['ssz_objects'], "ssz_object")
+        _print_items_with_history("Dataclasses", history['dataclasses'], "dataclass")
+        _print_items_with_history("Preset Variables", history['preset_vars'], "preset_var")
+        _print_items_with_history("Config Variables", history['config_vars'], "config_var")
 
     return 0
 
 
+def check(args):
+    """Run checks to validate spec references."""
+    project_dir = os.path.abspath(os.path.expanduser(args.path))
+    if not os.path.isdir(project_dir):
+        print(f"Error: The directory {repr(project_dir)} does not exist.")
+        return 1
+
+    # Load config
+    config = load_config(project_dir)
+
+    # Run checks
+    success, results = run_checks(project_dir, config)
+
+    # Collect all missing items and errors
+    all_missing = []
+    all_errors = []
+    total_coverage = {"found": 0, "expected": 0}
+    total_source_files = {"valid": 0, "total": 0}
+
+    for section_name, section_results in results.items():
+        # Determine the type prefix from section name
+        if "Config Variables" in section_name:
+            type_prefix = "config_var"
+        elif "Preset Variables" in section_name:
+            type_prefix = "preset_var"
+        elif "Ssz Objects" in section_name:
+            type_prefix = "ssz_object"
+        elif "Dataclasses" in section_name:
+            type_prefix = "dataclass"
+        else:
+            type_prefix = section_name.lower().replace(" ", "_")
+
+        # Collect source file errors
+        source = section_results['source_files']
+        total_source_files["valid"] += source["valid"]
+        total_source_files["total"] += source["total"]
+        all_errors.extend(source["errors"])
+
+        # Collect missing items with type prefix
+        coverage = section_results['coverage']
+        total_coverage["found"] += coverage["found"]
+        total_coverage["expected"] += coverage["expected"]
+        for missing in coverage['missing']:
+            all_missing.append(f"MISSING: {type_prefix}.{missing}")
+
+    # Display only errors and missing items
+    for error in all_errors:
+        print(error)
+
+    for missing in sorted(all_missing):
+        print(missing)
+
+    if all_errors or all_missing:
+        return 1
+    else:
+        total_refs = total_coverage['expected']
+        print(f"All specification references ({total_refs}) are valid.")
+        return 0
+
+
 def list_forks(args):
     """List all available forks."""
     pyspec = get_pyspec()
@@ -103,10 +139,10 @@ def list_forks(args):
         print(f"Available presets: {', '.join(pyspec.keys())}")
         return 1
 
+    # Filter out EIP forks
     forks = sorted(
-        pyspec[preset].keys(),
-        # Put phase0 at the top & EIP feature forks at the bottom
-        key=lambda x: (x != "phase0", x.startswith("eip"), x)
+        [fork for fork in pyspec[preset].keys() if not fork.startswith("eip")],
+        key=lambda x: (x != "phase0", x)
     )
 
     if args.format == "json":
@@ -148,20 +184,8 @@ def main():
     )
 
     # Parser for 'list-tags' command
-    list_tags_parser = subparsers.add_parser("list-tags", help="List available specification tags")
+    list_tags_parser = subparsers.add_parser("list-tags", help="List available specification tags with fork history")
     list_tags_parser.set_defaults(func=list_tags)
-    list_tags_parser.add_argument(
-        "--fork",
-        type=str,
-        help="Fork to list tags for",
-        default=get_latest_fork(),
-    )
-    list_tags_parser.add_argument(
-        "--preset",
-        type=str,
-        help="Preset to use (mainnet or minimal)",
-        default="mainnet",
-    )
     list_tags_parser.add_argument(
         "--format",
         type=str,
@@ -176,6 +200,16 @@ def main():
         default=None,
     )
 
+    # Parser for 'check' command
+    check_parser = subparsers.add_parser("check", help="Check spec reference coverage and validity")
+    check_parser.set_defaults(func=check)
+    check_parser.add_argument(
+        "--path",
+        type=str,
+        help="Directory containing YAML files to check",
+        default=".",
+    )
+
     # Parser for 'list-forks' command
     list_forks_parser = subparsers.add_parser("list-forks", help="List available forks")
     list_forks_parser.set_defaults(func=list_forks)

ethspecify/core.py

@@ -1,5 +1,6 @@
 import difflib
 import functools
+import glob
 import hashlib
 import io
 import os
@@ -7,6 +8,50 @@ import re
 import requests
 import textwrap
 import tokenize
+import yaml
+
+
+def load_config(directory=None):
+    """
+    Load configuration from .ethspecify.yml file in the specified directory.
+    Returns a dict with configuration values, or empty dict if no config file found.
+    """
+    if directory is None:
+        directory = os.getcwd()
+
+    config_path = os.path.join(directory, '.ethspecify.yml')
+
+    if os.path.exists(config_path):
+        try:
+            with open(config_path, 'r') as f:
+                config = yaml.safe_load(f)
+                return config if config else {}
+        except (yaml.YAMLError, IOError) as e:
+            print(f"Warning: Error reading .ethspecify.yml file: {e}")
+            return {}
+
+    return {}
+
+
+def is_excepted(item_name, fork, exceptions):
+    """
+    Check if an item#fork combination is in the exception list.
+    Exceptions can be:
+    - Just the item name (applies to all forks)
+    - item#fork (specific fork)
+    """
+    if not exceptions:
+        return False
+
+    # Check for exact match with fork
+    if f"{item_name}#{fork}" in exceptions:
+        return True
+
+    # Check for item name only (all forks)
+    if item_name in exceptions:
+        return True
+
+    return False
 
 
 def strip_comments(code):
@@ -107,7 +152,9 @@ def get_previous_forks(fork, version="nightly"):
             if key != f"{fork.upper()}_FORK_VERSION":
                 if key != "GENESIS_FORK_VERSION":
                     f = key.split("_")[0].lower()
-                    previous_forks.append(f)
+                    # Skip EIP forks
+                    if not f.startswith("eip"):
+                        previous_forks.append(f)
     return list(reversed(previous_forks))
 
 
@@ -201,14 +248,155 @@ def get_latest_fork(version="nightly"):
     """A helper function to get the latest non-eip fork."""
     pyspec = get_pyspec(version)
     forks = sorted(
-        pyspec["mainnet"].keys(),
-        key=lambda x: (x != "phase0", x.startswith("eip"), x)
+        [fork for fork in pyspec["mainnet"].keys() if not fork.startswith("eip")],
+        key=lambda x: (x != "phase0", x)
     )
-    for fork in reversed(forks):
-        if not fork.startswith("eip"):
-            return fork
+    return forks[-1] if forks else "phase0"
+
+
+def get_spec_item_changes(fork, preset="mainnet", version="nightly"):
+    """
+    Compare spec items in the given fork with previous forks to detect changes.
+    Returns dict with categories containing items marked as (new) or (modified).
+    """
+    pyspec = get_pyspec(version)
+    if fork not in pyspec[preset]:
+        raise ValueError(f"Fork '{fork}' not found in {preset} preset")
+
+    current_fork_data = pyspec[preset][fork]
+    previous_forks = get_previous_forks(fork, version)
+
+    changes = {
+        'functions': {},
+        'constant_vars': {},
+        'custom_types': {},
+        'ssz_objects': {},
+        'dataclasses': {},
+        'preset_vars': {},
+        'config_vars': {},
+    }
+
+    # Check each category of spec items
+    for category in changes.keys():
+        if category not in current_fork_data:
+            continue
+
+        for item_name, item_content in current_fork_data[category].items():
+            status = _get_item_status(item_name, item_content, category, previous_forks, pyspec, preset)
+            if status:
+                changes[category][item_name] = status
+
+    return changes
+
+
+def _get_item_status(item_name, current_content, category, previous_forks, pyspec, preset):
+    """
+    Determine if an item is new or modified compared to previous forks.
+    Returns 'new', 'modified', or None if unchanged.
+    """
+    # Check if item exists in any previous fork
+    found_in_previous = False
+    previous_content = None
+
+    for prev_fork in previous_forks:
+        if (prev_fork in pyspec[preset] and
+            category in pyspec[preset][prev_fork] and
+            item_name in pyspec[preset][prev_fork][category]):
+
+            found_in_previous = True
+            prev_content = pyspec[preset][prev_fork][category][item_name]
+
+            # Compare content with immediate previous version
+            if prev_content != current_content:
+                return "modified"
+            else:
+                # Found unchanged version, so this is not new or modified
+                return None
+
+    # If not found in any previous fork, it's new
+    if not found_in_previous:
+        return "new"
+
+    return None
+
+
+def get_spec_item_history(preset="mainnet", version="nightly"):
+    """
+    Get the complete history of all spec items across all forks.
+    Returns dict with categories containing items and their fork history.
+    """
+    pyspec = get_pyspec(version)
+    if preset not in pyspec:
+        raise ValueError(f"Preset '{preset}' not found")
+
+    # Get all forks in chronological order, excluding EIP forks
+    all_forks = sorted(
+        [fork for fork in pyspec[preset].keys() if not fork.startswith("eip")],
+        key=lambda x: (x != "phase0", x)
+    )
+
+    # Track all unique items across all forks
+    all_items = {
+        'functions': set(),
+        'constant_vars': set(),
+        'custom_types': set(),
+        'ssz_objects': set(),
+        'dataclasses': set(),
+        'preset_vars': set(),
+        'config_vars': set(),
+    }
+
+    # Collect all item names
+    for fork in all_forks:
+        if fork not in pyspec[preset]:
+            continue
+        fork_data = pyspec[preset][fork]
+        for category in all_items.keys():
+            if category in fork_data:
+                all_items[category].update(fork_data[category].keys())
+
+    # Build history for each item
+    history = {}
+    for category in all_items.keys():
+        history[category] = {}
+        for item_name in all_items[category]:
+            item_history = _trace_item_history(item_name, category, all_forks, pyspec, preset)
+            if item_history:
+                history[category][item_name] = item_history
+
+    return history
+
+
+def _trace_item_history(item_name, category, all_forks, pyspec, preset):
+    """
+    Trace the history of a specific item across all forks.
+    Returns a list of forks where the item was introduced or modified.
+    """
+    history_forks = []
+    previous_content = None
+
+    for fork in all_forks:
+        if (fork in pyspec[preset] and
+            category in pyspec[preset][fork] and
+            item_name in pyspec[preset][fork][category]):
+
+            current_content = pyspec[preset][fork][category][item_name]
+
+            if previous_content is None:
+                # First appearance
+                history_forks.append(fork)
+            elif current_content != previous_content:
+                # Content changed
+                history_forks.append(fork)
+
+            previous_content = current_content
+
+    return history_forks
+
+def parse_common_attributes(attributes, config=None):
+    if config is None:
+        config = {}
 
-def parse_common_attributes(attributes):
     try:
         preset = attributes["preset"]
     except KeyError:
@@ -217,7 +405,7 @@ def parse_common_attributes(attributes):
     try:
         version = attributes["version"]
     except KeyError:
-        version = "nightly"
+        version = config.get("version", "nightly")
 
     try:
         fork = attributes["fork"]
@@ -227,12 +415,12 @@ def parse_common_attributes(attributes):
     try:
         style = attributes["style"]
     except KeyError:
-        style = "hash"
+        style = config.get("style", "hash")
 
     return preset, fork, style, version
 
-def get_spec_item(attributes):
-    preset, fork, style, version = parse_common_attributes(attributes)
+def get_spec_item(attributes, config=None):
+    preset, fork, style, version = parse_common_attributes(attributes, config)
     spec = get_spec(attributes, preset, fork, version)
 
     if style == "full" or style == "hash":
@@ -283,10 +471,14 @@ def extract_attributes(tag):
     return dict(attr_pattern.findall(tag))
 
 
-def replace_spec_tags(file_path):
+def replace_spec_tags(file_path, config=None):
     with open(file_path, 'r') as file:
         content = file.read()
 
+    # Use provided config or load from file's directory as fallback
+    if config is None:
+        config = load_config(os.path.dirname(file_path))
+
     # Define regex to match self-closing tags and long (paired) tags separately
     pattern = re.compile(
         r'(?P<self><spec\b[^>]*\/>)|(?P<long><spec\b[^>]*>[\s\S]*?</spec>)',
@@ -327,7 +519,7 @@ def replace_spec_tags(file_path):
 
         attributes = extract_attributes(original_tag_text)
         print(f"spec tag: {attributes}")
-        preset, fork, style, version = parse_common_attributes(attributes)
+        preset, fork, style, version = parse_common_attributes(attributes, config)
         spec = get_spec(attributes, preset, fork, version)
         hash_value = hashlib.sha256(spec.encode('utf-8')).hexdigest()[:8]
 
@@ -338,7 +530,7 @@ def replace_spec_tags(file_path):
         else:
             # For full/diff styles, rebuild as a long (paired) tag.
             new_opening = rebuild_opening_tag(attributes, hash_value)
-            spec_content = get_spec_item(attributes)
+            spec_content = get_spec_item(attributes, config)
             prefix = content[:match.start()].splitlines()[-1]
             prefixed_spec = "\n".join(
                 f"{prefix}{line}" if line.rstrip() else prefix.rstrip()
@@ -354,3 +546,406 @@ def replace_spec_tags(file_path):
     # Write the updated content back to the file
     with open(file_path, 'w') as file:
         file.write(updated_content)
+
+
+def check_source_files(yaml_file, project_root, exceptions=None):
+    """
+    Check that source files referenced in a YAML file exist and contain expected search strings.
+    Returns (valid_count, total_count, errors)
+    """
+    if exceptions is None:
+        exceptions = []
+    if not os.path.exists(yaml_file):
+        return 0, 0, [f"YAML file not found: {yaml_file}"]
+
+    errors = []
+    total_count = 0
+
+    try:
+        with open(yaml_file, 'r') as f:
+            content_str = f.read()
+
+        # Try to fix common YAML issues with unquoted search strings
+        # Replace unquoted search values ending with colons
+        content_str = re.sub(r'(\s+search:\s+)([^"\n]+:)(\s*$)', r'\1"\2"\3', content_str, flags=re.MULTILINE)
+
+        try:
+            content = yaml.safe_load(content_str)
+        except yaml.YAMLError:
+            # Fall back to FullLoader if safe_load fails
+            content = yaml.load(content_str, Loader=yaml.FullLoader)
+    except (yaml.YAMLError, IOError) as e:
+        return 0, 0, [f"YAML parsing error in {yaml_file}: {e}"]
+
+    if not content:
+        return 0, 0, []
+
+    # Handle both array of objects and single object formats
+    items = content if isinstance(content, list) else [content]
+
+    for item in items:
+        if not isinstance(item, dict) or 'sources' not in item:
+            continue
+
+        # Extract spec reference information from the item
+        spec_ref = None
+        if 'spec' in item and isinstance(item['spec'], str):
+            # Try to extract spec reference from spec content
+            spec_content = item['spec']
+            # Look for any spec tag attribute and fork
+            spec_tag_match = re.search(r'<spec\s+([^>]+)>', spec_content)
+            if spec_tag_match:
+                tag_attrs = spec_tag_match.group(1)
+                # Extract fork
+                fork_match = re.search(r'fork="([^"]+)"', tag_attrs)
+                # Extract the main attribute (not hash or fork)
+                attr_matches = re.findall(r'(\w+)="([^"]+)"', tag_attrs)
+
+                if fork_match:
+                    fork = fork_match.group(1)
+                    # Find the first non-meta attribute
+                    for attr_name, attr_value in attr_matches:
+                        if attr_name not in ['fork', 'hash', 'preset', 'version', 'style']:
+                            # Map attribute names to type prefixes
+                            type_map = {
+                                'fn': 'functions',
+                                'function': 'functions',
+                                'constant_var': 'constants',
+                                'config_var': 'configs',
+                                'preset_var': 'presets',
+                                'ssz_object': 'ssz_objects',
+                                'dataclass': 'dataclasses',
+                                'custom_type': 'custom_types'
+                            }
+                            type_prefix = type_map.get(attr_name, attr_name)
+                            spec_ref = f"{type_prefix}.{attr_value}#{fork}"
+                            break
+
+        # Fallback to just the name if spec extraction failed
+        if not spec_ref and 'name' in item:
+            spec_ref = item['name']
+
+        # Check if sources list is empty
+        if not item['sources']:
+            if spec_ref:
+                # Extract item name and fork from spec_ref for exception checking
+                if '#' in spec_ref and '.' in spec_ref:
+                    # Format: "functions.item_name#fork"
+                    _, item_with_fork = spec_ref.split('.', 1)
+                    if '#' in item_with_fork:
+                        item_name, fork = item_with_fork.split('#', 1)
+                        # Check if this item is in exceptions
+                        if is_excepted(item_name, fork, exceptions):
+                            total_count += 1
+                            continue
+
+                errors.append(f"EMPTY SOURCES: {spec_ref}")
+            else:
+                # Fallback if we can't extract spec reference
+                item_name = item.get('name', 'unknown')
+                errors.append(f"EMPTY SOURCES: No sources defined ({item_name})")
+            total_count += 1
+            continue
+
+        for source in item['sources']:
+            # All sources now use the standardized dict format with file and optional search
+            if not isinstance(source, dict) or 'file' not in source:
+                continue
+
+            file_path = source['file']
+            search_string = source.get('search')
+            is_regex = source.get('regex', False)
+
+            total_count += 1
+
+            # Parse line range from file path if present (#L123 or #L123-L456)
+            line_range = None
+            if '#L' in file_path:
+                base_path, line_part = file_path.split('#L', 1)
+                file_path = base_path
+                # Format is always #L123 or #L123-L456, so just remove all 'L' characters
+                line_range = line_part.replace('L', '')
+
+            full_path = os.path.join(project_root, file_path)
+
+            # Create error prefix with spec reference if available
+            ref_prefix = f"{spec_ref} | " if spec_ref else ""
+
+            # Check if file exists
+            if not os.path.exists(full_path):
+                errors.append(f"MISSING FILE: {ref_prefix}{file_path}")
+                continue
+
+            # Check line range if specified
+            if line_range:
+                try:
+                    with open(full_path, 'r', encoding='utf-8') as f:
+                        lines = f.readlines()
+                        total_lines = len(lines)
+
+                    # Parse line range
+                    if '-' in line_range:
+                        # Range like "123-456"
+                        start_str, end_str = line_range.split('-', 1)
+                        start_line = int(start_str)
+                        end_line = int(end_str)
+
+                        if start_line < 1 or end_line < 1 or start_line > end_line:
+                            errors.append(f"INVALID LINE RANGE: {ref_prefix}#{line_range} - invalid range in {file_path}")
+                            continue
+                        elif end_line > total_lines:
+                            errors.append(f"INVALID LINE RANGE: {ref_prefix}#{line_range} - line {end_line} exceeds file length ({total_lines}) in {file_path}")
+                            continue
+                    else:
+                        # Single line like "123"
+                        line_num = int(line_range)
+                        if line_num < 1:
+                            errors.append(f"INVALID LINE RANGE: {ref_prefix}#{line_range} - invalid line number in {file_path}")
+                            continue
+                        elif line_num > total_lines:
+                            errors.append(f"INVALID LINE RANGE: {ref_prefix}#{line_range} - line {line_num} exceeds file length ({total_lines}) in {file_path}")
+                            continue
+
+                except ValueError:
+                    errors.append(f"INVALID LINE RANGE: {ref_prefix}#{line_range} - invalid line format in {file_path}")
+                    continue
+                except (IOError, UnicodeDecodeError):
+                    errors.append(f"ERROR READING: {ref_prefix}{file_path}")
+                    continue
+
+            # Check search string if provided
+            if search_string:
+                try:
+                    with open(full_path, 'r', encoding='utf-8') as f:
+                        content = f.read()
+
+                        if is_regex:
+                            # Use regex search
+                            try:
+                                pattern = re.compile(search_string, re.MULTILINE)
+                                matches = list(pattern.finditer(content))
+                                count = len(matches)
+                                search_type = "REGEX"
+                            except re.error as e:
+                                errors.append(f"INVALID REGEX: {ref_prefix}'{search_string}' in {file_path} - {e}")
+                                continue
+                        else:
+                            # Use literal string search
+                            count = content.count(search_string)
+                            search_type = "SEARCH"
+
+                        if count == 0:
+                            errors.append(f"{search_type} NOT FOUND: {ref_prefix}'{search_string}' in {file_path}")
+                        elif count > 1:
+                            errors.append(f"AMBIGUOUS {search_type}: {ref_prefix}'{search_string}' found {count} times in {file_path}")
+                except (IOError, UnicodeDecodeError):
+                    errors.append(f"ERROR READING: {ref_prefix}{file_path}")
+
+    valid_count = total_count - len(errors)
+    return valid_count, total_count, errors
+
+
+def extract_spec_tags_from_yaml(yaml_file, tag_type):
+    """
+    Extract spec tags from a YAML file and return item#fork pairs.
+    """
+    if not os.path.exists(yaml_file):
+        return set()
+
+    pairs = set()
+    try:
+        with open(yaml_file, 'r') as f:
+            content_str = f.read()
+
+        # Try to fix common YAML issues with unquoted search strings
+        # Replace unquoted search values ending with colons
+        content_str = re.sub(r'(\s+search:\s+)([^"\n]+:)(\s*$)', r'\1"\2"\3', content_str, flags=re.MULTILINE)
+
+        try:
+            content = yaml.safe_load(content_str)
+        except yaml.YAMLError:
+            # Fall back to FullLoader if safe_load fails
+            content = yaml.load(content_str, Loader=yaml.FullLoader)
+
+        if not content:
+            return set()
+
+        # Handle both array of objects and single object formats
+        items = content if isinstance(content, list) else [content]
+
+        for item in items:
+            if not isinstance(item, dict) or 'spec' not in item:
+                continue
+
+            spec_content = item['spec']
+            if not isinstance(spec_content, str):
+                continue
+
+            # Find spec tags using regex in the spec field
+            pattern = rf'<spec\s+{tag_type}="([^"]+)"[^>]*fork="([^"]+)"'
+            matches = re.findall(pattern, spec_content)
+
+            for match_item, fork in matches:
+                pairs.add(f"{match_item}#{fork}")
+
+    except (IOError, UnicodeDecodeError, yaml.YAMLError):
+        pass
+
+    return pairs
+
+
+def check_coverage(yaml_file, tag_type, exceptions, preset="mainnet"):
+    """
+    Check that all spec items from ethspecify have corresponding tags in the YAML file.
+    Returns (found_count, total_count, missing_items)
+    """
+    # Map tag types to history keys
+    history_key_map = {
+        'ssz_object': 'ssz_objects',
+        'config_var': 'config_vars',
+        'preset_var': 'preset_vars',
+        'dataclass': 'dataclasses',
+        'fn': 'functions',
+        'constant_var': 'constant_vars',
+        'custom_type': 'custom_types'
+    }
+
+    # Get expected items from ethspecify
+    history = get_spec_item_history(preset)
+    expected_pairs = set()
+
+    history_key = history_key_map.get(tag_type, tag_type)
+    if history_key in history:
+        for item_name, forks in history[history_key].items():
+            for fork in forks:
+                expected_pairs.add(f"{item_name}#{fork}")
+
+    # Get actual pairs from YAML file
+    actual_pairs = extract_spec_tags_from_yaml(yaml_file, tag_type)
+
+    # Find missing items (excluding exceptions)
+    missing_items = []
+    total_count = len(expected_pairs)
+
+    for item_fork in expected_pairs:
+        item_name, fork = item_fork.split('#', 1)
+
+        if is_excepted(item_name, fork, exceptions):
+            continue
+
+        if item_fork not in actual_pairs:
+            missing_items.append(item_fork)
+
+    found_count = total_count - len(missing_items)
+    return found_count, total_count, missing_items
+
+
+def run_checks(project_dir, config):
+    """
+    Run all checks based on the configuration.
+    Returns (success, results)
+    """
+    results = {}
+    overall_success = True
+
+    # Get specrefs config
+    specrefs_config = config.get('specrefs', {})
+
+    # Handle both old format (specrefs as array) and new format (specrefs as dict)
+    if isinstance(specrefs_config, list):
+        # Old format: specrefs: [file1, file2, ...]
+        specrefs_files = specrefs_config
+        exceptions = config.get('exceptions', {})
+    else:
+        # New format: specrefs: { files: [...], exceptions: {...} }
+        specrefs_files = specrefs_config.get('files', [])
+        exceptions = specrefs_config.get('exceptions', {})
+
+    if not specrefs_files:
+        print("Error: No specrefs files specified in .ethspecify.yml")
+        print("Please add a 'specrefs:' section with 'files:' listing the files to check")
+        return False, {}
+
+    # File type mapping for coverage checking
+    file_type_mapping = {
+        'ssz-objects': 'ssz_object',
+        'config-variables': 'config_var',
+        'preset-variables': 'preset_var',
+        'dataclasses': 'dataclass',
+        'functions': 'fn',
+        'constants': 'constant_var',
+    }
+
+    # Use explicit file list only
+    for filename in specrefs_files:
+        yaml_path = os.path.join(project_dir, filename)
+
+        if not os.path.exists(yaml_path):
+            print(f"Error: File {filename} defined in config but not found")
+            overall_success = False
+            continue
+
+        # Determine the tag type from filename for coverage checking
+        tag_type = None
+        preset = "mainnet"  # default preset
+
+        for pattern, file_tag_type in file_type_mapping.items():
+            if pattern in filename:
+                tag_type = file_tag_type
+                # Check for preset indicators
+                if 'minimal' in filename.lower():
+                    preset = "minimal"
+                break
+
+        # Get the appropriate exceptions for this file type
+        section_exceptions = []
+        if tag_type:
+            # Map tag types to exception keys (support both singular and plural)
+            exception_key_map = {
+                'ssz_object': ['ssz_objects', 'ssz_object'],
+                'config_var': ['configs', 'config_variables', 'config_var'],
+                'preset_var': ['presets', 'preset_variables', 'preset_var'],
+                'dataclass': ['dataclasses', 'dataclass'],
+                'fn': ['functions', 'fn'],
+                'constant_var': ['constants', 'constant_variables', 'constant_var'],
+                'custom_type': ['custom_types', 'custom_type']
+            }
+
+            # Try plural first, then singular for backward compatibility
+            if tag_type in exception_key_map:
+                for key in exception_key_map[tag_type]:
+                    if key in exceptions:
+                        section_exceptions = exceptions[key]
+                        break
+
+        # Check source files
+        valid_count, total_count, source_errors = check_source_files(yaml_path, os.path.dirname(project_dir), section_exceptions)
+
+        # Check coverage if we can determine the type
+        found_count, expected_count, missing_items = 0, 0, []
+        if tag_type:
+            found_count, expected_count, missing_items = check_coverage(yaml_path, tag_type, section_exceptions, preset)
+
+        # Store results using filename as section name
+        section_name = filename.replace('.yml', '').replace('-', ' ').title()
+        if preset != "mainnet":
+            section_name += f" ({preset.title()})"
+
+        results[section_name] = {
+            'source_files': {
+                'valid': valid_count,
+                'total': total_count,
+                'errors': source_errors
+            },
+            'coverage': {
+                'found': found_count,
+                'expected': expected_count,
+                'missing': missing_items
+            }
+        }
+
+        # Update overall success
+        if source_errors or missing_items:
+            overall_success = False
+
+    return overall_success, results

{ethspecify-0.2.1.dist-info → ethspecify-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethspecify
-Version: 0.2.1
+Version: 0.2.3
 Summary: A utility for processing Ethereum specification tags.
 Home-page: https://github.com/jtraglia/ethspecify
 Author: Justin Traglia
@@ -12,6 +12,7 @@ Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests==2.32.3
+Requires-Dist: PyYAML>=6.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

ethspecify-0.2.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+ethspecify/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ethspecify/cli.py,sha256=SZ47-lgfeDHmzXCE-rx8ydM66N9NfNAA2GDxoC4DE7E,7641
+ethspecify/core.py,sha256=bQ1D7zdR_xDx_OuyPrFBNKBNxXpH3bjn2L4-pqHhgJo,35530
+ethspecify-0.2.3.dist-info/licenses/LICENSE,sha256=Awxsr73mm9YMBVhBYnzeI7bNdRd-bH6RDtO5ItG0DaM,1071
+ethspecify-0.2.3.dist-info/METADATA,sha256=77_CCIaxJ5Cf6Cg_FlIDXhS_djSf-D5nAujQ9DJthys,9212
+ethspecify-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ethspecify-0.2.3.dist-info/entry_points.txt,sha256=09viGkCg9J3h0c9BFRN-BKaJUEaIc4JyULNgBP5EL_g,51
+ethspecify-0.2.3.dist-info/top_level.txt,sha256=0klaMvlVyOkXW09fwZTijJpdybITEp2c9zQKV5v30VM,11
+ethspecify-0.2.3.dist-info/RECORD,,

ethspecify-0.2.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-ethspecify/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ethspecify/cli.py,sha256=73NnY6-xvFcxMnpeZ1LqvU02EiNiPx5jOor1KPERenk,6903
-ethspecify/core.py,sha256=Nu5-onBdtmibdO9FkwZL1gGWjRAvZkTPeWZ0H9v2NoI,13292
-ethspecify-0.2.1.dist-info/licenses/LICENSE,sha256=Awxsr73mm9YMBVhBYnzeI7bNdRd-bH6RDtO5ItG0DaM,1071
-ethspecify-0.2.1.dist-info/METADATA,sha256=qYoT3-9O7b2SbY7mDJrDJo7T--VpjkIJTPrD2Ob03rc,9185
-ethspecify-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ethspecify-0.2.1.dist-info/entry_points.txt,sha256=09viGkCg9J3h0c9BFRN-BKaJUEaIc4JyULNgBP5EL_g,51
-ethspecify-0.2.1.dist-info/top_level.txt,sha256=0klaMvlVyOkXW09fwZTijJpdybITEp2c9zQKV5v30VM,11
-ethspecify-0.2.1.dist-info/RECORD,,