Exclude definitions.yaml from audits

PythonScripts/audit_translations/README.md

@@ -50,6 +50,10 @@ The tool automatically adjusts its matching logic based on the file type:
     * Matches rules based on character/range keys.
     * *Examples:* `unicode.yaml`, `unicode-full.yaml` (keys like `a-z`, `!`, `0-9`).
 
+`definitions.yaml` is intentionally excluded from audits *for now*. It does not have the same semantics
+ as normal rules, so the tool ignores it during automatic file discovery and when it is passed to
+`--file`.
+
 ---
 
 ### ⚙️ Usage & Commands

PythonScripts/audit_translations/auditor.py

@@ -31,6 +31,11 @@ def get_rules_dir(rules_dir: str | None = None) -> Path:
     return package_dir.parent.parent / "Rules" / "Languages"
 
 
+def is_definitions_file(file_path: str | Path) -> bool:
+    """Return if the file name is definitions.yaml, which is not yet supported."""
+    return Path(file_path).name == "definitions.yaml"
+
+
 def get_yaml_files(lang_dir: Path, region_dir: Path | None = None) -> list[Path]:
     """Get all YAML files to audit for a language, including region overrides."""
     files: set[Path] = set()
@@ -39,12 +44,13 @@ def collect_from(directory: Path, root: Path) -> None:
         if not directory.exists():
             return
         for f in directory.glob("*.yaml"):
-            if f.name != "prefs.yaml":  # Skip prefs.yaml as it's not translated
+            if f.name != "prefs.yaml" and not is_definitions_file(f):
                 files.add(f.relative_to(root))
         shared_dir = directory / "SharedRules"
         if shared_dir.exists():
             for f in shared_dir.glob("*.yaml"):
-                files.add(f.relative_to(root))
+                if not is_definitions_file(f):
+                    files.add(f.relative_to(root))
 
     collect_from(lang_dir, lang_dir)
     if region_dir:
@@ -144,7 +150,11 @@ def audit_language(
     verbose: bool = False,
     source_language: str = "en",
 ) -> int:
-    """Audit translations for a specific language. Returns total issue count."""
+    """Audit translations for a specific language and return the total issue count.
+
+    ``specific_file`` is the relative file path supplied by the CLI's ``--file``
+    option. When set, the audit is limited to that file.
+    """
     rules_dir_path = get_rules_dir(rules_dir)
 
     source_base_language, source_region = split_language_into_base_and_region(source_language)
@@ -168,7 +178,10 @@ def audit_language(
         raise AuditError(f"Target region directory not found: {translated_region_dir}")
 
     # Get list of files to audit
-    files = [specific_file] if specific_file else get_yaml_files(source_dir, source_region_dir)
+    if specific_file:
+        files = [] if is_definitions_file(Path(specific_file)) else [specific_file]
+    else:
+        files = get_yaml_files(source_dir, source_region_dir)
 
     print_audit_header(language, len(files), source_language)
 

PythonScripts/audit_translations/tests/test_auditor.py

@@ -322,6 +322,34 @@ def test_get_yaml_files_includes_region(tmp_path) -> None:
     assert set(files) == {Path("base.yaml"), Path("SharedRules/shared.yaml"), Path("unicode.yaml")}
 
 
+def test_get_yaml_files_ignores_definitions(tmp_path) -> None:
+    """Definitions files are excluded from automatic audit discovery."""
+    lang_dir = tmp_path / "lang"
+    shared_dir = lang_dir / "SharedRules"
+    shared_dir.mkdir(parents=True)
+    (lang_dir / "rules.yaml").write_text("---", encoding="utf-8")
+    (lang_dir / "definitions.yaml").write_text("---", encoding="utf-8")
+    (shared_dir / "definitions.yaml").write_text("---", encoding="utf-8")
+
+    assert get_yaml_files(lang_dir) == [Path("rules.yaml")]
+
+
+def test_audit_language_ignores_explicit_definitions_file(tmp_path, fixed_console_width) -> None:
+    """Passing definitions.yaml through --file produces an empty audit."""
+    rules_dir = tmp_path / "Rules" / "Languages"
+    (rules_dir / "en").mkdir(parents=True)
+    (rules_dir / "de").mkdir(parents=True)
+
+    with console.capture() as capture:
+        total_issues = audit_language("de", specific_file="definitions.yaml", rules_dir=str(rules_dir))
+    output = strip_ansi(capture.get())
+
+    assert total_issues == 0
+    assert "Files to check: 0" in output
+    assert "Files checked" in output
+    assert "definitions.yaml" not in output
+
+
 def test_list_languages_includes_region_codes(tmp_path) -> None:
     """
     Ensures list_languages reports region variants.