core-runtime-engine 11.5.1__py3-none-any.whl

core_runtime/tooling/contract_preflight.py

@@ -0,0 +1,293 @@
+"""Advisory-only contract preflight helpers for CORE tooling."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from core_runtime.tooling.diagnostics import DiagnosticCollection
+
+
+@dataclass(frozen=True)
+class ContractItem:
+    """A single contract review item."""
+
+    kind: str
+    name: str
+    path: str
+    status: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "kind": self.kind,
+            "name": self.name,
+            "path": self.path,
+            "status": self.status,
+        }
+        if self.details:
+            result["details"] = self.details
+        return result
+
+
+@dataclass
+class ContractPreflightReport:
+    """Normalized report for `core-runtime contract-preflight`."""
+
+    tool: str
+    command: str
+    status: str
+    mutation_performed: bool = False
+    summary: dict[str, Any] = field(default_factory=dict)
+    selection: dict[str, Any] | None = None
+    items: list[ContractItem] = field(default_factory=list)
+    diagnostics: DiagnosticCollection = field(default_factory=DiagnosticCollection)
+
+    def to_dict(self) -> dict[str, Any]:
+        counts = self.diagnostics.count_by_severity()
+        summary = dict(self.summary)
+        summary.setdefault("info", counts["info"])
+        summary.setdefault("warning", counts["warning"])
+        summary.setdefault("error", counts["error"])
+        summary.setdefault("blocked", counts["blocked"])
+        return {
+            "tool": self.tool,
+            "command": self.command,
+            "status": self.status,
+            "mutation_performed": self.mutation_performed,
+            "summary": summary,
+            "selection": self.selection,
+            "items": [item.to_dict() for item in self.items],
+            "diagnostics": [d.to_dict() for d in self.diagnostics.diagnostics],
+        }
+
+    def to_markdown(self) -> str:
+        counts = self.diagnostics.count_by_severity()
+        summary = dict(self.summary)
+        summary.setdefault("info", counts["info"])
+        summary.setdefault("warning", counts["warning"])
+        summary.setdefault("error", counts["error"])
+        summary.setdefault("blocked", counts["blocked"])
+        lines: list[str] = []
+        lines.append("# CORE contract preflight")
+        lines.append("")
+        lines.append("## Summary")
+        lines.append("")
+        lines.append("| Metric | Value |")
+        lines.append("|--------|-------|")
+        lines.append("| Tool | {0} |".format(self.tool))
+        lines.append("| Command | {0} |".format(self.command))
+        lines.append("| Status | {0} |".format(self.status.upper()))
+        lines.append("| Mutation Performed | No |")
+        lines.append("| Items | {0} |".format(summary.get("item_count", len(self.items))))
+        lines.append("| Info | {0} |".format(counts["info"]))
+        lines.append("| Warning | {0} |".format(counts["warning"]))
+        lines.append("| Error | {0} |".format(counts["error"]))
+        lines.append("| Blocked | {0} |".format(counts["blocked"]))
+        lines.append("")
+
+        if self.selection is not None:
+            lines.append("## Selection")
+            lines.append("")
+            for key, value in self.selection.items():
+                lines.append("- **{0}**: {1}".format(key, value))
+            lines.append("")
+
+        if self.items:
+            lines.append("## Items")
+            lines.append("")
+            lines.append("| Kind | Name | Path | Status |")
+            lines.append("|------|------|------|--------|")
+            for item in self.items:
+                lines.append("| {0} | {1} | {2} | {3} |".format(item.kind, item.name, item.path, item.status))
+            lines.append("")
+
+        if self.diagnostics.diagnostics:
+            lines.append("## Diagnostics")
+            lines.append("")
+            lines.append("| Severity | Code | Path | Message |")
+            lines.append("|----------|------|------|---------|")
+            for diagnostic in self.diagnostics.diagnostics:
+                path = diagnostic.path or "-"
+                message = diagnostic.message.replace("|", "\\|")
+                lines.append(
+                    "| {0} | {1} | {2} | {3} |".format(
+                        diagnostic.severity.value.upper(),
+                        diagnostic.code,
+                        path,
+                        message,
+                    )
+                )
+            lines.append("")
+
+        return "\n".join(lines)
+
+
+class RepositoryContractPreflight:
+    """Build advisory-only contract review reports from public CORE schemas."""
+
+    def __init__(self, repo_root: Path):
+        self.repo_root = repo_root
+
+    def build_candidate_report(self, name: str, diagnostics: DiagnosticCollection | None = None) -> ContractPreflightReport:
+        diagnostics = diagnostics or DiagnosticCollection()
+        contract = self._resolve_contract(name)
+        selection = {"mode": "candidate", "candidate": name}
+
+        if contract is None:
+            diagnostics.add_blocked(
+                code="core.contract_preflight.contract_unknown",
+                message="Unknown contract candidate: {0}".format(name),
+                path=name,
+                expected="known CORE contract name",
+                actual=name,
+            )
+            return ContractPreflightReport(
+                tool="core-runtime contract-preflight",
+                command="contract-preflight --candidate {0}".format(name),
+                status="blocked",
+                summary={"mode": "candidate", "item_count": 0},
+                selection=selection,
+                diagnostics=diagnostics,
+            )
+
+        item = self._contract_item(contract)
+        return ContractPreflightReport(
+            tool="core-runtime contract-preflight",
+            command="contract-preflight --candidate {0}".format(name),
+            status="pass",
+            summary={
+                "mode": "candidate",
+                "item_count": 1,
+                "required_field_count": len(item.details.get("required_fields", [])),
+                "property_count": len(item.details.get("property_names", [])),
+            },
+            selection=selection,
+            items=[item],
+            diagnostics=diagnostics,
+        )
+
+    def build_compare_report(
+        self,
+        left: str,
+        right: str,
+        diagnostics: DiagnosticCollection | None = None,
+    ) -> ContractPreflightReport:
+        diagnostics = diagnostics or DiagnosticCollection()
+        left_contract = self._resolve_contract(left)
+        right_contract = self._resolve_contract(right)
+        selection = {"mode": "compare", "left": left, "right": right}
+
+        missing: list[str] = []
+        if left_contract is None:
+            missing.append(left)
+        if right_contract is None:
+            missing.append(right)
+        if missing:
+            diagnostics.add_blocked(
+                code="core.contract_preflight.contract_unknown",
+                message="Unknown contract candidate(s): {0}".format(", ".join(missing)),
+                path=", ".join(missing),
+                expected="known CORE contract name",
+                actual=", ".join(missing),
+            )
+            return ContractPreflightReport(
+                tool="core-runtime contract-preflight",
+                command="contract-preflight --compare {0} {1}".format(left, right),
+                status="blocked",
+                summary={"mode": "compare", "item_count": 0},
+                selection=selection,
+                diagnostics=diagnostics,
+            )
+
+        left_item = self._contract_item(left_contract)
+        right_item = self._contract_item(right_contract)
+        left_required = set(left_item.details.get("required_fields", []))
+        right_required = set(right_item.details.get("required_fields", []))
+        shared_required = sorted(left_required & right_required)
+        left_only = sorted(left_required - right_required)
+        right_only = sorted(right_required - left_required)
+        status = "pass"
+        if left_item.details.get("schema_version") != right_item.details.get("schema_version"):
+            status = "warning"
+
+        return ContractPreflightReport(
+            tool="core-runtime contract-preflight",
+            command="contract-preflight --compare {0} {1}".format(left, right),
+            status=status,
+            summary={
+                "mode": "compare",
+                "item_count": 2,
+                "shared_required_fields": len(shared_required),
+                "left_only_required_fields": len(left_only),
+                "right_only_required_fields": len(right_only),
+                "same_schema_version": left_item.details.get("schema_version") == right_item.details.get("schema_version"),
+            },
+            selection=selection,
+            items=[left_item, right_item],
+            diagnostics=diagnostics,
+        )
+
+    def _resolve_contract(self, name: str) -> dict[str, Any] | None:
+        normalized = name.strip().lower()
+        for path in sorted((self.repo_root / "schemas" / "core").glob("*.json")):
+            contract = self._load_contract(path)
+            if contract is None:
+                continue
+            candidates = {
+                contract.get("title", "").lower(),
+                contract.get("schema_version", "").lower(),
+                path.stem.lower(),
+            }
+            if normalized in candidates:
+                return contract
+        return None
+
+    def _load_contract(self, path: Path) -> dict[str, Any] | None:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        if not isinstance(payload, dict):
+            return None
+        required = payload.get("required")
+        properties = payload.get("properties")
+        if not isinstance(properties, dict):
+            properties = {}
+        return {
+            "path": path,
+            "title": payload.get("title"),
+            "schema_version": self._schema_version(payload),
+            "required": required if isinstance(required, list) else [],
+            "properties": properties,
+            "additionalProperties": payload.get("additionalProperties"),
+        }
+
+    def _schema_version(self, payload: dict[str, Any]) -> str | None:
+        properties = payload.get("properties")
+        if isinstance(properties, dict):
+            schema_version = properties.get("schema_version")
+            if isinstance(schema_version, dict):
+                const = schema_version.get("const")
+                if isinstance(const, str) and const:
+                    return const
+        return None
+
+    def _contract_item(self, contract: dict[str, Any]) -> ContractItem:
+        properties = contract.get("properties", {})
+        property_names = sorted(properties.keys()) if isinstance(properties, dict) else []
+        required_fields = sorted(str(value) for value in contract.get("required", []))
+        return ContractItem(
+            kind="contract",
+            name=str(contract.get("title") or Path(contract["path"]).stem),
+            path=str(Path(contract["path"]).relative_to(self.repo_root)),
+            status="passed",
+            details={
+                "schema_version": contract.get("schema_version"),
+                "required_fields": required_fields,
+                "property_names": property_names,
+                "additional_properties": contract.get("additionalProperties"),
+            },
+        )

core_runtime/tooling/create_domain.py

@@ -0,0 +1,254 @@
+"""Dry-run-first domain scaffolding preflight for CORE tooling."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from core_runtime.tooling.diagnostics import DiagnosticCollection
+
+
+DOMAIN_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+@dataclass(frozen=True)
+class CreateDomainItem:
+    """A planned file or artifact in a domain scaffold."""
+
+    kind: str
+    name: str
+    path: str
+    status: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "kind": self.kind,
+            "name": self.name,
+            "path": self.path,
+            "status": self.status,
+        }
+        if self.details:
+            result["details"] = self.details
+        return result
+
+
+@dataclass
+class CreateDomainReport:
+    """Normalized report for `core-runtime create-domain`."""
+
+    tool: str
+    command: str
+    status: str
+    mutation_performed: bool = False
+    summary: dict[str, Any] = field(default_factory=dict)
+    selection: dict[str, Any] | None = None
+    items: list[CreateDomainItem] = field(default_factory=list)
+    diagnostics: DiagnosticCollection = field(default_factory=DiagnosticCollection)
+
+    def to_dict(self) -> dict[str, Any]:
+        counts = self.diagnostics.count_by_severity()
+        summary = dict(self.summary)
+        summary.setdefault("info", counts["info"])
+        summary.setdefault("warning", counts["warning"])
+        summary.setdefault("error", counts["error"])
+        summary.setdefault("blocked", counts["blocked"])
+        return {
+            "tool": self.tool,
+            "command": self.command,
+            "status": self.status,
+            "mutation_performed": self.mutation_performed,
+            "summary": summary,
+            "selection": self.selection,
+            "items": [item.to_dict() for item in self.items],
+            "diagnostics": [d.to_dict() for d in self.diagnostics.diagnostics],
+        }
+
+    def to_markdown(self) -> str:
+        counts = self.diagnostics.count_by_severity()
+        summary = dict(self.summary)
+        summary.setdefault("info", counts["info"])
+        summary.setdefault("warning", counts["warning"])
+        summary.setdefault("error", counts["error"])
+        summary.setdefault("blocked", counts["blocked"])
+        lines: list[str] = []
+        lines.append("# CORE create-domain plan")
+        lines.append("")
+        lines.append("## Summary")
+        lines.append("")
+        lines.append("| Metric | Value |")
+        lines.append("|--------|-------|")
+        lines.append("| Tool | {0} |".format(self.tool))
+        lines.append("| Command | {0} |".format(self.command))
+        lines.append("| Status | {0} |".format(self.status.upper()))
+        lines.append("| Mutation Performed | No |")
+        lines.append("| Items | {0} |".format(summary.get("item_count", len(self.items))))
+        lines.append("| Info | {0} |".format(counts["info"]))
+        lines.append("| Warning | {0} |".format(counts["warning"]))
+        lines.append("| Error | {0} |".format(counts["error"]))
+        lines.append("| Blocked | {0} |".format(counts["blocked"]))
+        lines.append("")
+
+        if self.selection is not None:
+            lines.append("## Selection")
+            lines.append("")
+            for key, value in self.selection.items():
+                lines.append("- **{0}**: {1}".format(key, value))
+            lines.append("")
+
+        if self.items:
+            lines.append("## Planned Artifacts")
+            lines.append("")
+            lines.append("| Kind | Name | Path | Status |")
+            lines.append("|------|------|------|--------|")
+            for item in self.items:
+                lines.append("| {0} | {1} | {2} | {3} |".format(item.kind, item.name, item.path, item.status))
+            lines.append("")
+
+        if self.diagnostics.diagnostics:
+            lines.append("## Diagnostics")
+            lines.append("")
+            lines.append("| Severity | Code | Path | Message |")
+            lines.append("|----------|------|------|---------|")
+            for diagnostic in self.diagnostics.diagnostics:
+                path = diagnostic.path or "-"
+                message = diagnostic.message.replace("|", "\\|")
+                lines.append(
+                    "| {0} | {1} | {2} | {3} |".format(
+                        diagnostic.severity.value.upper(),
+                        diagnostic.code,
+                        path,
+                        message,
+                    )
+                )
+            lines.append("")
+
+        return "\n".join(lines)
+
+
+class DomainScaffolder:
+    """Plan a deterministic domain scaffold without mutating the repo."""
+
+    def __init__(self, repo_root: Path):
+        self.repo_root = repo_root
+
+    def build_plan(self, name: str, template: str = "generic", diagnostics: DiagnosticCollection | None = None) -> CreateDomainReport:
+        diagnostics = diagnostics or DiagnosticCollection()
+        normalized_name = name.strip()
+        normalized_template = template.strip()
+        selection = {"domain": normalized_name, "template": normalized_template, "mode": "dry-run"}
+
+        if not DOMAIN_NAME_PATTERN.fullmatch(normalized_name):
+            diagnostics.add_blocked(
+                code="core.create_domain.invalid_name",
+                message="Domain name must match ^[a-z][a-z0-9_]*$",
+                path=normalized_name,
+                expected="lowercase identifier",
+                actual=normalized_name,
+            )
+            return CreateDomainReport(
+                tool="core-runtime create-domain",
+                command="create-domain {0} --dry-run".format(normalized_name),
+                status="blocked",
+                summary={"mode": "dry-run", "item_count": 0},
+                selection=selection,
+                diagnostics=diagnostics,
+            )
+
+        planned_items, collisions, risks = self._plan_items(normalized_name, normalized_template)
+        if collisions:
+            diagnostics.add_blocked(
+                code="core.create_domain.collision",
+                message="Domain scaffold collides with existing files or directories",
+                path=collisions[0],
+                expected="unused paths",
+                actual=", ".join(collisions),
+            )
+            status = "blocked"
+        else:
+            status = "pass"
+
+        if risks:
+            diagnostics.add_warning(
+                code="core.create_domain.review_required",
+                message="Domain scaffold has reviewable design risks",
+                path=normalized_name,
+                expected="bounded dry-run review",
+                actual=", ".join(risks),
+            )
+            if status == "pass":
+                status = "warning"
+
+        return CreateDomainReport(
+            tool="core-runtime create-domain",
+            command="create-domain {0} --dry-run".format(normalized_name),
+            status=status,
+            summary={
+                "mode": "dry-run",
+                "item_count": len(planned_items),
+                "collision_count": len(collisions),
+                "risk_count": len(risks),
+                "template": normalized_template,
+            },
+            selection=selection,
+            items=planned_items,
+            diagnostics=diagnostics,
+        )
+
+    def _plan_items(self, name: str, template: str) -> tuple[list[CreateDomainItem], list[str], list[str]]:
+        collisions: list[str] = []
+        risks: list[str] = []
+        items: list[CreateDomainItem] = []
+
+        domain_dir = self.repo_root / "core_runtime" / "domains" / name
+        test_path = self.repo_root / "tests" / f"test_domain_{name}.py"
+        example_dir = self.repo_root / "examples" / "domains" / name
+        docs_path = self.repo_root / "docs" / "domains" / f"{name}.md"
+
+        planned_paths = [
+            domain_dir,
+            domain_dir / "__init__.py",
+            domain_dir / "task.py",
+            domain_dir / "oracle.py",
+            domain_dir / "surrogate.py",
+            domain_dir / "projection.py",
+            domain_dir / "evaluator.py",
+            domain_dir / "confidence.py",
+            domain_dir / "manifest.json",
+            test_path,
+            example_dir / "valid_task.json",
+            example_dir / "invalid_task.json",
+            docs_path,
+        ]
+
+        for path in planned_paths:
+            if path.exists():
+                collisions.append(str(path.relative_to(self.repo_root)))
+            items.append(
+                CreateDomainItem(
+                    kind="planned_dir" if path == domain_dir else "planned_file",
+                    name=path.name,
+                    path=str(path.relative_to(self.repo_root)),
+                    status="planned",
+                    details={
+                        "template": template,
+                        "exists": path.exists(),
+                    },
+                )
+            )
+
+        risks.extend(
+            [
+                "no_runtime_behavior",
+                "advisory_only_manifest",
+                "fixtures_must_stay_synthetic",
+                "tests_require_followup",
+                "docs_need_manual_review",
+            ]
+        )
+        if template != "generic":
+            risks.append(f"template:{template}")
+
+        return items, collisions, risks

core_runtime/tooling/diagnostics.py

@@ -0,0 +1,129 @@
+"""Diagnostic data structures and severity handling for CORE tooling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class Severity(str, Enum):
+    """Diagnostic severity levels."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    BLOCKED = "blocked"
+
+    def exit_code_weight(self) -> int:
+        """Return the weight for exit code computation."""
+        return {
+            Severity.INFO: 0,
+            Severity.WARNING: 0,
+            Severity.ERROR: 1,
+            Severity.BLOCKED: 2,
+        }[self]
+
+
+class ExitCode(Enum):
+    """Exit codes for lint command."""
+
+    OK = 0
+    ERROR = 1
+    BLOCKED = 2
+    INTERNAL_ERROR = 3
+
+
+@dataclass(frozen=True, order=False)
+class Diagnostic:
+    """A single diagnostic result from a check."""
+
+    code: str
+    severity: Severity
+    message: str
+    mutation_allowed: bool
+    path: Optional[str] = None
+    expected: Optional[str] = None
+    actual: Optional[str] = None
+    details: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "code": self.code,
+            "severity": self.severity.value,
+            "message": self.message,
+            "mutation_allowed": self.mutation_allowed,
+        }
+        if self.path is not None:
+            result["path"] = self.path
+        if self.expected is not None:
+            result["expected"] = self.expected
+        if self.actual is not None:
+            result["actual"] = self.actual
+        if self.details is not None:
+            result["details"] = self.details
+        return result
+
+
+@dataclass
+class DiagnosticCollection:
+    """Collection of diagnostics with summary statistics."""
+
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+
+    def add(self, diagnostic: Diagnostic) -> None:
+        """Add a diagnostic."""
+        self.diagnostics.append(diagnostic)
+
+    def add_error(self, code: str, message: str, path: Optional[str] = None, **kwargs: Any) -> None:
+        """Add an error severity diagnostic."""
+        self.add(Diagnostic(code=code, severity=Severity.ERROR, message=message, path=path, mutation_allowed=False, **kwargs))
+
+    def add_warning(self, code: str, message: str, path: Optional[str] = None, **kwargs: Any) -> None:
+        """Add a warning severity diagnostic."""
+        self.add(Diagnostic(code=code, severity=Severity.WARNING, message=message, path=path, mutation_allowed=False, **kwargs))
+
+    def add_info(self, code: str, message: str, path: Optional[str] = None, **kwargs: Any) -> None:
+        """Add an info severity diagnostic."""
+        self.add(Diagnostic(code=code, severity=Severity.INFO, message=message, path=path, mutation_allowed=False, **kwargs))
+
+    def add_blocked(self, code: str, message: str, path: Optional[str] = None, **kwargs: Any) -> None:
+        """Add a blocked severity diagnostic."""
+        self.add(Diagnostic(code=code, severity=Severity.BLOCKED, message=message, path=path, mutation_allowed=False, **kwargs))
+
+    def count_by_severity(self) -> dict[str, int]:
+        """Count diagnostics by severity."""
+        counts = {s.value: 0 for s in Severity}
+        for d in self.diagnostics:
+            counts[d.severity.value] += 1
+        return counts
+
+    def has_errors(self) -> bool:
+        """Check if any error or blocked diagnostics exist."""
+        return any(d.severity in (Severity.ERROR, Severity.BLOCKED) for d in self.diagnostics)
+
+    def has_blocked(self) -> bool:
+        """Check if any blocked diagnostics exist."""
+        return any(d.severity == Severity.BLOCKED for d in self.diagnostics)
+
+    def compute_exit_code(self) -> ExitCode:
+        """Compute exit code based on diagnostics."""
+        if not self.diagnostics:
+            return ExitCode.OK
+
+        has_errors = any(d.severity == Severity.ERROR for d in self.diagnostics)
+        has_blocked = any(d.severity == Severity.BLOCKED for d in self.diagnostics)
+
+        if has_blocked:
+            return ExitCode.BLOCKED
+        if has_errors:
+            return ExitCode.ERROR
+        return ExitCode.OK
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "diagnostics": [d.to_dict() for d in self.diagnostics],
+            "summary": self.count_by_severity(),
+        }