Merge pull request #14 from linkml/up2

New Value Sets and Infrastructure Improvements

Author: cmungall

.claude/hooks/README.md

@@ -0,0 +1,40 @@
+# Claude Code Hooks
+
+This directory contains hooks that integrate with Claude Code to provide automated validation and other features.
+
+## validate_schema_hook.py
+
+This hook automatically validates LinkML schema files when they are written or edited using Claude Code.
+
+### Features
+- Automatically runs validation when saving YAML files in the schema directory
+- Blocks file modifications if validation fails
+- Shows detailed validation output in the Claude Code interface
+- Filters out noise from warning messages for cleaner output
+- Uses the project's `just validate-schema PATH` command for validation
+
+### How it works
+1. Intercepts Write, Edit, and MultiEdit operations on YAML files containing "schema" in the path
+2. Runs the validation command: `just validate-schema <file>`
+3. Displays validation results with filtered output for readability
+4. Returns exit code 2 to block the operation if validation fails
+
+### Validation Command
+The hook uses the existing `just validate-schema PATH` command which:
+- Validates ontology mappings in enum definitions
+- Checks for label mismatches between expected and actual ontology terms
+- Uses the configured OAK adapters for strict validation of configured prefixes
+- Treats label mismatches as errors for configured ontologies (NCIT, GO, CHEBI, etc.)
+
+### Configuration
+The hook is configured in `.claude/settings.json` as a PostToolUse hook that runs after Write, Edit, and MultiEdit operations.
+
+### Testing
+You can test the hook by editing any schema file and seeing if validation runs automatically. The hook will:
+- ✅ Allow valid schema modifications
+- ❌ Block invalid schema modifications with validation errors
+- 📋 Show helpful validation output including ontology label mismatches
+
+### Exit Codes
+- **Exit 0**: Validation passed, allow operation
+- **Exit 2**: Validation failed, block operation (see [Claude Code hooks documentation](https://docs.claude.com/en/docs/claude-code/hooks#exit-code-2-behavior))

.claude/hooks/validate_schema_hook.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+Hook to automatically validate LinkML schema files after they are written or edited.
+This hook runs `just validate-schema PATH` and displays the results to provide immediate feedback.
+
+**NOTE**
+
+Be sure to exit with code 2 if you want to block the operation.
+https://docs.claude.com/en/docs/claude-code/hooks#exit-code-2-behavior
+"""
+
+import sys
+import json
+import subprocess
+import os
+from pathlib import Path
+
+
+def main():
+    # Read the hook input from stdin
+    data = json.load(sys.stdin)
+
+    # Extract the file path from the tool input
+    tool_name = data.get("tool_name", "")
+    file_path = data.get("tool_input", {}).get("file_path", "")
+
+    # Only process Write and Edit tool calls
+    if tool_name not in ["Write", "Edit", "MultiEdit"]:
+        sys.exit(0)
+
+    # Check if this is a YAML file in the schema directory
+    if not file_path.endswith(".yaml") or "schema" not in file_path:
+        sys.exit(0)
+
+    # Convert to Path object for easier manipulation
+    file_path = Path(file_path)
+
+    # Check if the file exists (it should after Write/Edit)
+    if not file_path.exists():
+        print(f"⚠️ File not found: {file_path}", file=sys.stderr)
+        sys.exit(0)
+
+    # Run the validation command
+    try:
+        # Build the validation command
+        cmd = ["just", "validate-schema", str(file_path)]
+
+        # Run the command and capture output
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            cwd=os.path.dirname(
+                os.path.dirname(os.path.dirname(__file__))
+            ),  # Project root
+        )
+
+        # Display the validation output
+        print("\n" + "=" * 60, file=sys.stderr)
+        print(f"🔍 Schema Validation Results for {file_path.name}", file=sys.stderr)
+        print("=" * 60, file=sys.stderr)
+
+        # Show stdout (the actual validation results)
+        if result.stdout:
+            # Filter out noise from warning messages
+            lines = result.stdout.split("\n")
+            filtered_lines = []
+            for line in lines:
+                # Filter out common noise patterns
+                if any(pattern in line for pattern in [
+                    "/eutils/__init__.py",
+                    "UserWarning",
+                    "pkg_resources is deprecated",
+                    "RuntimeWarning: 'src.valuesets.validators.enum_evaluator'",
+                    "found in sys.modules after import"
+                ]):
+                    continue
+                else:
+                    filtered_lines.append(line)
+
+            output = "\n".join(filtered_lines).strip()
+            if output:
+                print(output, file=sys.stderr)
+
+        # Show any errors
+        if result.returncode != 0 and result.stderr:
+            # Filter stderr similarly
+            lines = result.stderr.split("\n")
+            filtered_lines = []
+            for line in lines:
+                if not any(pattern in line for pattern in [
+                    "/eutils/__init__.py",
+                    "UserWarning",
+                    "pkg_resources is deprecated"
+                ]):
+                    filtered_lines.append(line)
+
+            error_output = "\n".join(filtered_lines).strip()
+            if error_output:
+                print("\n⚠️ Schema validation errors:", file=sys.stderr)
+                print(error_output, file=sys.stderr)
+
+        print("=" * 60 + "\n", file=sys.stderr)
+
+        # Return non-zero exit code if validation failed
+        if result.returncode != 0:
+            print("❌ Schema validation failed - blocking file modification", file=sys.stderr)
+            print("Fix validation errors before saving the file.", file=sys.stderr)
+            sys.exit(2)  # Block the operation
+
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Failed to run schema validation: {e}", file=sys.stderr)
+        sys.exit(2)  # Block on validation errors
+    except Exception as e:
+        print(f"❌ Unexpected error during schema validation: {e}", file=sys.stderr)
+        # Block on hook failures to ensure schema integrity
+        sys.exit(2)
+
+    # Exit 0 if validation passed
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

.claude/settings.json

@@ -10,5 +10,18 @@
         "WebSearch",
         "Write"
     ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate_schema_hook.py"
+          }
+        ]
+      }
+    ]
   }
 }

CONTRIBUTING.md

@@ -51,6 +51,23 @@ Please use our [Discussions forum][discussions] to ask general questions or cont
 
 Please submit a [Pull Request][pulls] to submit a new term for consideration.
 
+#### Term Caching System
+
+This project uses an ontology term caching system to improve validation performance and reduce external API calls. When you contribute new ontology mappings:
+
+1. **Cache Updates**: Adding new ontology mappings may result in changes to the cache files in the `cache/` directory
+2. **Include Cache Changes**: These cache updates should be included in your Pull Request
+3. **Validation Process**: Run `just validate` before submitting to ensure all ontology mappings are valid
+4. **Cache Structure**: The cache organizes terms by ontology prefix (e.g., `cache/ncit/`, `cache/vo/`) for efficient lookup
+
+**Standard Operating Procedure for Contributors:**
+
+- When adding enums with `meaning:` annotations pointing to ontology terms:
+  - Run validation locally with `just validate`
+  - Include any generated cache files in your commit
+  - Ensure all ontology IDs are correct (never guess - use [OLS](https://www.ebi.ac.uk/ols4/) to verify)
+  - Follow the project's naming conventions (e.g., `UPPER_CASE` for enum values)
+
 <a id="best-practices"></a>
 
 ## Best Practices

cache/afo/terms.csv

@@ -0,0 +1,5 @@
+curie,label,retrieved_at
+AFO:AFQ_0000112,,2025-10-19T08:36:02.778895
+AFO:AFQ_0000113,,2025-10-19T08:36:02.779656
+AFO:AFQ_0000114,,2025-10-19T08:36:02.779835
+AFO:AFQ_0000115,,2025-10-19T08:36:02.779968