modelable 1.0.0__py3-none-any.whl

modelable/compat/checker.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from modelable.compat.diff import FieldChange, compare_model_versions
+from modelable.parser.ir import ChangeKind, DirectMapping, MdlFile, ModelVersion
+
+
+@dataclass(frozen=True)
+class CompatibilityReport:
+    domain_name: str
+    model_name: str
+    from_version: int
+    to_version: int
+    status: str
+    findings: list[str] = field(default_factory=list)
+    changes: list[FieldChange] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ProjectionImpact:
+    domain_name: str
+    projection_name: str
+    version: int
+    status: str  # "broken", "affected", "compatible"
+    reason: str | None = None
+
+
+def check_model_version_compatibility(
+    mdl: MdlFile,
+    domain_name: str,
+    model_name: str,
+    from_version: int,
+    to_version: int,
+) -> CompatibilityReport:
+    """Compare two published versions and classify the change set."""
+    old_version = _find_version(mdl, domain_name, model_name, from_version)
+    new_version = _find_version(mdl, domain_name, model_name, to_version)
+    changes = compare_model_versions(old_version, new_version)
+    findings = [_format_finding(change) for change in changes]
+    status = "breaking" if _has_breaking_change(changes, new_version) else "compatible"
+    return CompatibilityReport(
+        domain_name=domain_name,
+        model_name=model_name,
+        from_version=from_version,
+        to_version=to_version,
+        status=status,
+        findings=findings,
+        changes=changes,
+    )
+
+
+def analyze_impact(
+    mdl: MdlFile,
+    report: CompatibilityReport,
+    dependent: tuple[str, str, int],
+) -> ProjectionImpact:
+    """Analyze the impact of a model change on a specific downstream projection."""
+    dep_domain_name, dep_proj_name, dep_version = dependent
+
+    # Find the projection version
+    pv = None
+    for domain in mdl.domains:
+        if domain.name == dep_domain_name:
+            pv = next(
+                (v for v in domain.projections.get(dep_proj_name, []) if v.version == dep_version),
+                None,
+            )
+            break
+
+    if pv is None:
+        return ProjectionImpact(dep_domain_name, dep_proj_name, dep_version, "affected", "unresolved projection")
+
+    # Determine the alias(es) used for this source model
+    source_ref = f"{report.domain_name}.{report.model_name}"
+    aliases = []
+    if pv.source.model == source_ref:
+        aliases.append(pv.source.alias)
+    for join in pv.joins:
+        if join.model == source_ref:
+            aliases.append(join.alias)
+
+    # Check if any breaking field change affects this projection's direct mappings
+    impacted_fields = []
+    for change in report.changes:
+        is_breaking_field = change.kind in {
+            "removed_field",
+            "renamed_field",
+            "type_changed",
+            "enum_changed",
+            "identity_changed",
+        }
+        if change.kind == "added_field" and change.to_optional is False:
+            is_breaking_field = True
+
+        if not is_breaking_field:
+            continue
+
+        for proj_field in pv.fields:
+            if (
+                isinstance(proj_field.mapping, DirectMapping)
+                and proj_field.mapping.source_alias in aliases
+                and proj_field.mapping.source_field == change.field_name
+            ):
+                impacted_fields.append(f"field '{change.field_name}' ({change.kind})")
+                break
+
+    if impacted_fields:
+        return ProjectionImpact(
+            dep_domain_name,
+            dep_proj_name,
+            dep_version,
+            "broken",
+            f"uses {', '.join(impacted_fields)}",
+        )
+
+    if report.status == "breaking":
+        return ProjectionImpact(
+            dep_domain_name,
+            dep_proj_name,
+            dep_version,
+            "affected",
+            f"source {source_ref} is marked breaking",
+        )
+
+    return ProjectionImpact(dep_domain_name, dep_proj_name, dep_version, "compatible")
+
+
+def _find_version(
+    mdl: MdlFile,
+    domain_name: str,
+    model_name: str,
+    version: int,
+) -> ModelVersion:
+    for domain in mdl.domains:
+        if domain.name != domain_name:
+            continue
+        versions = domain.models.get(model_name, [])
+        for candidate in versions:
+            if candidate.version == version:
+                return candidate
+        break
+    raise LookupError(f"unknown model version {domain_name}.{model_name}@{version}")
+
+
+def _format_finding(change: FieldChange) -> str:
+    if change.kind == "renamed_field":
+        return f"renamed_field {change.field_name} -> {change.replacement}"
+    if change.kind == "nullability_changed":
+        return (
+            f"nullability_changed {change.field_name}: "
+            f"{_bool_word(change.from_optional)} -> {_bool_word(change.to_optional)}"
+        )
+    if change.kind == "identity_changed":
+        return f"identity_changed {change.field_name}"
+    if change.kind == "enum_changed":
+        return f"enum_changed {change.field_name}"
+    if change.kind == "type_changed":
+        return f"type_changed {change.field_name}"
+    if change.kind == "removed_field":
+        return f"removed_field {change.field_name}"
+    if change.kind == "added_field":
+        return f"added_field {change.field_name}"
+    return f"{change.kind} {change.field_name}"
+
+
+def _bool_word(value: bool | None) -> str:
+    if value is None:
+        return "unknown"
+    return "optional" if value else "required"
+
+
+def _has_breaking_change(changes: list[FieldChange], new_version: ModelVersion) -> bool:
+    for change in changes:
+        if change.kind in {"removed_field", "renamed_field", "type_changed", "enum_changed", "identity_changed"}:
+            return True
+        if change.kind == "added_field" and change.to_optional is False:
+            return True
+    return new_version.change_kind == ChangeKind.breaking

modelable/compat/diff.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from modelable.parser.ir import AnnDeprecated, EnumType, FieldDef, ModelVersion
+
+
+@dataclass(frozen=True)
+class FieldChange:
+    kind: str
+    field_name: str
+    previous_name: str | None = None
+    replacement: str | None = None
+    from_optional: bool | None = None
+    to_optional: bool | None = None
+    from_type: str | None = None
+    to_type: str | None = None
+
+
+def compare_model_versions(old_version: ModelVersion, new_version: ModelVersion) -> list[FieldChange]:
+    """Compare two published model versions field by field."""
+    changes: list[FieldChange] = []
+    old_fields = {field.name: field for field in old_version.fields}
+    new_fields = {field.name: field for field in new_version.fields}
+    matched_old: set[str] = set()
+    matched_new: set[str] = set()
+
+    for old_field in old_version.fields:
+        replacement = _deprecated_replacement(old_field)
+        if replacement is None:
+            continue
+        new_field = new_fields.get(replacement)
+        if new_field is None or replacement in matched_new:
+            continue
+        changes.append(
+            FieldChange(
+                kind="renamed_field",
+                field_name=old_field.name,
+                previous_name=old_field.name,
+                replacement=replacement,
+                from_optional=old_field.optional,
+                to_optional=new_field.optional,
+                from_type=_type_signature(old_field),
+                to_type=_type_signature(new_field),
+            )
+        )
+        if old_field.optional != new_field.optional:
+            changes.append(
+                FieldChange(
+                    kind="nullability_changed",
+                    field_name=replacement,
+                    from_optional=old_field.optional,
+                    to_optional=new_field.optional,
+                    from_type=_type_signature(old_field),
+                    to_type=_type_signature(new_field),
+                )
+            )
+        if _type_signature(old_field) != _type_signature(new_field):
+            if isinstance(old_field.type, EnumType) and isinstance(new_field.type, EnumType):
+                kind = "enum_changed"
+            else:
+                kind = "type_changed"
+            changes.append(
+                FieldChange(
+                    kind=kind,
+                    field_name=replacement,
+                    from_type=_type_signature(old_field),
+                    to_type=_type_signature(new_field),
+                )
+            )
+        matched_old.add(old_field.name)
+        matched_new.add(replacement)
+
+    for old_field in old_version.fields:
+        if old_field.name in matched_old:
+            continue
+        if old_field.name not in new_fields:
+            changes.append(
+                FieldChange(
+                    kind="removed_field",
+                    field_name=old_field.name,
+                    from_optional=old_field.optional,
+                    from_type=_type_signature(old_field),
+                )
+            )
+
+    for name in _sorted_common_field_names(old_fields, new_fields):
+        old_field = old_fields[name]
+        new_field = new_fields[name]
+
+        if old_field.optional != new_field.optional:
+            changes.append(
+                FieldChange(
+                    kind="nullability_changed",
+                    field_name=name,
+                    from_optional=old_field.optional,
+                    to_optional=new_field.optional,
+                    from_type=_type_signature(old_field),
+                    to_type=_type_signature(new_field),
+                )
+            )
+
+        if old_field.is_key != new_field.is_key:
+            changes.append(
+                FieldChange(
+                    kind="identity_changed",
+                    field_name=name,
+                    from_type=_type_signature(old_field),
+                    to_type=_type_signature(new_field),
+                )
+            )
+
+        old_sig = _type_signature(old_field)
+        new_sig = _type_signature(new_field)
+        if old_sig == new_sig:
+            continue
+        if isinstance(old_field.type, EnumType) and isinstance(new_field.type, EnumType):
+            changes.append(
+                FieldChange(
+                    kind="enum_changed",
+                    field_name=name,
+                    from_type=old_sig,
+                    to_type=new_sig,
+                )
+            )
+        else:
+            changes.append(
+                FieldChange(
+                    kind="type_changed",
+                    field_name=name,
+                    from_type=old_sig,
+                    to_type=new_sig,
+                )
+            )
+
+    for new_field in new_version.fields:
+        if new_field.name in matched_new:
+            continue
+        if new_field.name not in old_fields:
+            changes.append(
+                FieldChange(
+                    kind="added_field",
+                    field_name=new_field.name,
+                    to_optional=new_field.optional,
+                    to_type=_type_signature(new_field),
+                )
+            )
+
+    return changes
+
+
+def _sorted_common_field_names(
+    old_fields: dict[str, FieldDef],
+    new_fields: dict[str, FieldDef],
+) -> list[str]:
+    names = [field.name for field in old_fields.values() if field.name in new_fields]
+    return names
+
+
+def _deprecated_replacement(field: FieldDef) -> str | None:
+    for annotation in field.annotations:
+        if isinstance(annotation, AnnDeprecated):
+            return annotation.replaced_by
+    return None
+
+
+def _type_signature(field: FieldDef) -> str:
+    return json.dumps(field.type.model_dump(mode="json"), sort_keys=True)

modelable/compiler/__init__.py

@@ -0,0 +1,3 @@
+from modelable.compiler.compiler import compile_file, compile_text
+
+__all__ = ["compile_file", "compile_text"]

modelable/compiler/compiler.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from modelable.parser.ir import MdlFile
+from modelable.parser.parse import parse_file_to_ir, parse_text_to_ir
+from modelable.validation.semantic import validate
+
+
+def compile_text(text: str) -> tuple[MdlFile, list[str]]:
+    """Parse and validate .mdl text."""
+    mdl = parse_text_to_ir(text)
+    return mdl, validate(mdl)
+
+
+def compile_file(path: str | Path) -> tuple[MdlFile, list[str]]:
+    """Parse and validate a .mdl file."""
+    mdl = parse_file_to_ir(path)
+    return mdl, validate(mdl)