Validate kernel identifiers and constants

Closes #1
Closes #2

Author: denisecase

src/se_kernel/app.py

@@ -1,4 +1,4 @@
-"""Application orchestration for se_kernel."""
+"""app.py - Application orchestration for se_kernel."""
 
 from pathlib import Path
 

src/se_kernel/types.py

@@ -0,0 +1,64 @@
+"""Typed structures for se-kernel artifacts."""
+
+from typing import TypedDict
+
+
+class ArtifactMeta(TypedDict):
+    """Shared artifact metadata."""
+
+    version: str
+    status: str
+
+
+class IdentifierGlobal(TypedDict):
+    """Global identifier rules."""
+
+    character_set: str
+    case: str
+    separator: str
+    allow_unicode: bool
+
+
+class IdentifierKind(TypedDict):
+    """Identifier kind definition."""
+
+    summary: str
+    pattern: str
+    examples: list[str]
+
+
+class IdentifierRules(TypedDict):
+    """Identifier invariant rules."""
+
+    must_be_stable: bool
+    must_be_ascii: bool
+    must_be_lowercase: bool
+    must_use_hyphen_separator: bool
+    must_not_embed_semantics: bool
+
+
+# WHY: TOML key is global, not global_ and global is a Python keyword.
+# For direct loaded TOML, use functional syntax instead:
+IdentifiersData = TypedDict(
+    "IdentifiersData",
+    {
+        "meta": ArtifactMeta,
+        "global": IdentifierGlobal,
+        "kind": dict[str, IdentifierKind],
+        "rules": IdentifierRules,
+    },
+)
+
+
+class ReservedValues(TypedDict):
+    """Reserved value list."""
+
+    values: list[str]
+
+
+class ConstantsData(TypedDict):
+    """constants.toml structure."""
+
+    meta: ArtifactMeta
+    reserved: dict[str, ReservedValues]
+    base_types: dict[str, str]

src/se_kernel/validate.py

@@ -0,0 +1,44 @@
+"""Validation for se-kernel artifacts."""
+
+from se_kernel.types import ConstantsData, IdentifiersData
+
+
+def validate_identifiers(data: IdentifiersData) -> list[str]:
+    """Validate identifiers.toml structure."""
+    errors: list[str] = []
+
+    if not data["kind"]:
+        errors.append("identifiers.toml: [kind] must not be empty.")
+
+    for kind_name, kind_def in data["kind"].items():
+        if not kind_def.get("summary", "").strip():
+            errors.append(f"identifiers.toml: [kind.{kind_name}] must define summary.")
+
+        if not kind_def.get("pattern", "").strip():
+            errors.append(f"identifiers.toml: [kind.{kind_name}] must define pattern.")
+
+        examples = kind_def.get("examples", [])
+        if not examples:
+            errors.append(f"identifiers.toml: [kind.{kind_name}] must define examples.")
+
+    return errors
+
+
+def validate_constants(data: ConstantsData) -> list[str]:
+    """Validate constants.toml structure."""
+    errors: list[str] = []
+
+    if not data["reserved"]:
+        errors.append("constants.toml: [reserved] must not be empty.")
+
+    for group_name, group_def in data["reserved"].items():
+        values = group_def.get("values", [])
+        if not values:
+            errors.append(
+                f"constants.toml: [reserved.{group_name}] must define values."
+            )
+
+    if not data["base_types"]:
+        errors.append("constants.toml: [base_types] must not be empty.")
+
+    return errors

tests/test_cli.py

@@ -1,4 +1,4 @@
-"""Minimal CLI smoke tests for se_kernel."""
+"""tests/test_cli.py - Minimal CLI smoke tests for se_kernel."""
 
 from se_kernel.app import run_show
 

tests/test_validate.py

@@ -0,0 +1,101 @@
+"""Validation tests for se-kernel artifacts."""
+
+from typing import Any, cast
+
+from se_kernel.types import ConstantsData, IdentifiersData
+from se_kernel.validate import validate_constants, validate_identifiers
+
+
+def make_valid_identifiers() -> IdentifiersData:
+    """Return valid identifiers data."""
+    return {
+        "meta": {"version": "0.1.0", "status": "draft"},
+        "global": {
+            "character_set": "ascii-lower-hyphen",
+            "case": "lower",
+            "separator": "-",
+            "allow_unicode": False,
+        },
+        "kind": {
+            "repo": {
+                "summary": "Canonical repository identifier.",
+                "pattern": "se-{name}",
+                "examples": ["se-kernel"],
+            }
+        },
+        "rules": {
+            "must_be_stable": True,
+            "must_be_ascii": True,
+            "must_be_lowercase": True,
+            "must_use_hyphen_separator": True,
+            "must_not_embed_semantics": True,
+        },
+    }
+
+
+def make_valid_constants() -> ConstantsData:
+    """Return valid constants data."""
+    return {
+        "meta": {"version": "0.1.0", "status": "draft"},
+        "reserved": {
+            "repo_classes": {"values": ["constitution", "kernel"]},
+        },
+        "base_types": {
+            "identifier": "string",
+            "string_list": "list[string]",
+        },
+    }
+
+
+def test_validate_identifiers_accepts_valid_data() -> None:
+    """Valid identifiers data should produce no errors."""
+    errors = validate_identifiers(make_valid_identifiers())
+    assert errors == []
+
+
+def test_validate_identifiers_requires_kind_entries() -> None:
+    """Identifier kinds must not be empty."""
+    data = make_valid_identifiers()
+    data["kind"] = {}
+
+    errors = validate_identifiers(data)
+
+    assert "identifiers.toml: [kind] must not be empty." in errors
+
+
+def test_validate_identifiers_requires_summary_pattern_and_examples() -> None:
+    """Identifier kinds must define summary, pattern, and examples."""
+    data = cast(dict[str, Any], make_valid_identifiers())
+    data["kind"]["repo"] = {"summary": "", "pattern": "", "examples": []}
+
+    errors = validate_identifiers(cast(IdentifiersData, data))
+
+    assert "identifiers.toml: [kind.repo] must define summary." in errors
+    assert "identifiers.toml: [kind.repo] must define pattern." in errors
+    assert "identifiers.toml: [kind.repo] must define examples." in errors
+
+
+def test_validate_constants_accepts_valid_data() -> None:
+    """Valid constants data should produce no errors."""
+    errors = validate_constants(make_valid_constants())
+    assert errors == []
+
+
+def test_validate_constants_requires_reserved_values() -> None:
+    """Reserved groups must define values."""
+    data = make_valid_constants()
+    data["reserved"]["repo_classes"] = {"values": []}
+
+    errors = validate_constants(data)
+
+    assert "constants.toml: [reserved.repo_classes] must define values." in errors
+
+
+def test_validate_constants_requires_base_types() -> None:
+    """Base types must not be empty."""
+    data = make_valid_constants()
+    data["base_types"] = {}
+
+    errors = validate_constants(data)
+
+    assert "constants.toml: [base_types] must not be empty." in errors