codd-dev 2.67.0__tar.gz → 2.69.0__tar.gz

{codd_dev-2.67.0 → codd_dev-2.69.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.67.0
+Version: 2.69.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev

{codd_dev-2.67.0 → codd_dev-2.69.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.67.0"
+__version__ = "2.69.0"

{codd_dev-2.67.0 → codd_dev-2.69.0}/codd/languages/__init__.py

@@ -39,8 +39,26 @@ from .registry import (
     AdapterRegistry,
     LanguageRegistry,
     UnknownLanguageError,
+    default_adapter_registry,
     default_registry,
 )
+from .contract import (
+    AdapterRequirement,
+    IncompleteLanguageContractError,
+    ResolvedLanguageContract,
+    build_language_contract,
+    resolve_language_contract,
+    resolve_language_profile,
+)
+from .verify_plan import (
+    ShadowComparison,
+    VerifyClass,
+    VerifyOutcome,
+    VerifyRunPlan,
+    build_verify_plan,
+    classify_verify_outcome,
+    shadow_compare,
+)
 from .compat import (
     UnsupportedLayoutShape,
     layout_profile_from_language_profile,
@@ -74,7 +92,23 @@ __all__ = [
     "AdapterRegistry",
     "LanguageRegistry",
     "UnknownLanguageError",
+    "default_adapter_registry",
     "default_registry",
+    # resolved language contract (the language-free kernel seam, v2.68)
+    "AdapterRequirement",
+    "IncompleteLanguageContractError",
+    "ResolvedLanguageContract",
+    "build_language_contract",
+    "resolve_language_contract",
+    "resolve_language_profile",
+    # verify run plan + semantic classifier (v2.69a, shadow)
+    "ShadowComparison",
+    "VerifyClass",
+    "VerifyOutcome",
+    "VerifyRunPlan",
+    "build_verify_plan",
+    "classify_verify_outcome",
+    "shadow_compare",
     # compat shim (LanguageProfile -> legacy LayoutProfile)
     "UnsupportedLayoutShape",
     "layout_profile_from_language_profile",

codd_dev-2.69.0/codd/languages/contract.py

@@ -0,0 +1,248 @@
+"""ResolvedLanguageContract — the language-free view the kernel consumes (v2.68).
+
+The Contract Kernel goal: the harness core never branches on a language name; it
+resolves a project's language to a :class:`LanguageProfile`, resolves the
+adapters that profile *names* against the :class:`AdapterRegistry`, and operates
+only on the resulting :class:`ResolvedLanguageContract` (profile + resolved
+adapter capabilities + a content hash).
+
+Anti-false-green seam: a profile that NAMES an adapter the registry cannot
+supply is an INCOMPLETE contract. :meth:`ResolvedLanguageContract.require_complete`
+raises (RED) rather than letting a gate run with a missing observation
+capability — a missing adapter must never become a silent green. (Legacy mode
+may instead inspect :attr:`~ResolvedLanguageContract.is_complete` and degrade to
+a warning; that choice belongs to the caller, not to this module.)
+
+This module is ADDITIVE in v2.68: it establishes the resolution seam and is
+exercised by tests, but is not yet wired into the live verify/greenfield gates
+(that switch is v2.69+). Adapter *implementations* are registered in v2.72; until
+then every declared adapter resolves as missing, which is exactly what the
+incomplete-contract test asserts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+import json
+from typing import Any, Mapping
+
+from .profile import LanguageProfile
+from .registry import (
+    AdapterRegistry,
+    LanguageRegistry,
+    default_adapter_registry,
+    default_registry,
+)
+
+# Adapter "kind" is implied by WHERE in the profile the adapter id is declared.
+# These kind names are the contract between profiles (which name bare ids) and
+# the AdapterRegistry (keyed by (kind, id)); v2.72 registers adapters under them.
+KIND_TEST_SEMANTICS = "test_semantics"
+KIND_RUNNER_REPORT = "runner_report"
+KIND_IMPORT_RESOLVER = "import_resolver"
+KIND_SCAFFOLD = "scaffold"
+
+
+@dataclass(frozen=True)
+class AdapterRequirement:
+    """An adapter a profile declares it needs, with where it was declared."""
+
+    kind: str
+    id: str
+    source: str  # e.g. "tests.semantics_adapter" — for honest diagnostics
+
+    @property
+    def ref(self) -> str:
+        return f"{self.kind}:{self.id}"
+
+
+class IncompleteLanguageContractError(RuntimeError):
+    """A profile names adapters the registry cannot supply (RED, not silent green)."""
+
+    def __init__(self, language_id: str, missing: tuple[AdapterRequirement, ...]) -> None:
+        self.language_id = language_id
+        self.missing = tuple(missing)
+        detail = ", ".join(f"{r.ref} (from {r.source})" for r in self.missing)
+        super().__init__(
+            f"incomplete language contract for {language_id!r}: no adapter registered "
+            f"for {detail}. A profile that names an adapter the registry cannot supply "
+            f"is an incomplete contract (RED), never a silent green."
+        )
+
+
+def _config_language(config: Mapping[str, Any] | None) -> str | None:
+    """Read ``project.language`` from a codd.yaml mapping (None if absent)."""
+    if not isinstance(config, Mapping):
+        return None
+    project = config.get("project")
+    if isinstance(project, Mapping):
+        language = project.get("language")
+        if isinstance(language, str) and language.strip():
+            return language.strip()
+    return None
+
+
+def _declared_adapter_requirements(
+    profile: LanguageProfile,
+) -> tuple[AdapterRequirement, ...]:
+    """Collect every adapter id the profile declares, as (kind, id) requirements.
+
+    Walks the MODELED profile fields only (commands/imports/tests/verify/scaffold).
+    ``implement_oracle`` / ``path_rules`` adapters live in ``profile.extra`` and
+    are not modeled until v2.73/v2.74, so they are intentionally not collected yet.
+    """
+    reqs: list[AdapterRequirement] = []
+
+    tests = profile.tests
+    if tests is not None:
+        if tests.semantics_adapter:
+            reqs.append(
+                AdapterRequirement(KIND_TEST_SEMANTICS, tests.semantics_adapter, "tests.semantics_adapter")
+            )
+        if tests.runner_report_adapter:
+            reqs.append(
+                AdapterRequirement(KIND_RUNNER_REPORT, tests.runner_report_adapter, "tests.runner_report_adapter")
+            )
+
+    imports = profile.imports
+    if imports is not None and imports.resolver_adapter:
+        reqs.append(
+            AdapterRequirement(KIND_IMPORT_RESOLVER, imports.resolver_adapter, "imports.resolver_adapter")
+        )
+
+    scaffold = profile.scaffold
+    if scaffold is not None and scaffold.adapter:
+        reqs.append(AdapterRequirement(KIND_SCAFFOLD, scaffold.adapter, "scaffold.adapter"))
+
+    verify = profile.verify
+    if verify is not None and verify.report is not None and verify.report.adapter:
+        reqs.append(
+            AdapterRequirement(KIND_RUNNER_REPORT, verify.report.adapter, "verify.report.adapter")
+        )
+
+    for cmd_id, cmd in profile.commands.items():
+        if cmd.report is not None and cmd.report.adapter:
+            reqs.append(
+                AdapterRequirement(KIND_RUNNER_REPORT, cmd.report.adapter, f"commands.{cmd_id}.report.adapter")
+            )
+
+    # Dedupe by (kind, id), keeping the first declaration site for diagnostics.
+    seen: set[tuple[str, str]] = set()
+    unique: list[AdapterRequirement] = []
+    for req in reqs:
+        key = (req.kind, req.id)
+        if key not in seen:
+            seen.add(key)
+            unique.append(req)
+    # Deterministic order so the content hash is stable.
+    unique.sort(key=lambda r: (r.kind, r.id))
+    return tuple(unique)
+
+
+def _contract_hash(
+    profile: LanguageProfile, required: tuple[AdapterRequirement, ...]
+) -> str:
+    payload = json.dumps(
+        {
+            "language": profile.identity.id,
+            "adapters": [r.ref for r in required],
+        },
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class ResolvedLanguageContract:
+    """Profile + resolved adapter capabilities + content hash (kernel input)."""
+
+    language_id: str
+    profile: LanguageProfile
+    required_adapters: tuple[AdapterRequirement, ...]
+    resolved_adapter_refs: tuple[str, ...]
+    missing_adapters: tuple[AdapterRequirement, ...]
+    content_hash: str
+
+    @property
+    def is_complete(self) -> bool:
+        return not self.missing_adapters
+
+    @property
+    def adapter_ids(self) -> tuple[str, ...]:
+        """All declared adapter refs (``kind:id``), resolved or not."""
+        return tuple(r.ref for r in self.required_adapters)
+
+    def require_complete(self) -> "ResolvedLanguageContract":
+        """Return self if every declared adapter resolved; else raise (RED)."""
+        if self.missing_adapters:
+            raise IncompleteLanguageContractError(self.language_id, self.missing_adapters)
+        return self
+
+    def to_trace(self) -> dict[str, Any]:
+        """Run-trace fields proving the run went through the contract seam."""
+        return {
+            "resolved_language_profile_id": self.language_id,
+            "language_contract_hash": self.content_hash,
+            "adapter_ids": list(self.adapter_ids),
+            "missing_adapters": [r.ref for r in self.missing_adapters],
+        }
+
+
+def build_language_contract(
+    profile: LanguageProfile,
+    *,
+    adapter_registry: AdapterRegistry | None = None,
+) -> ResolvedLanguageContract:
+    """Resolve a profile's declared adapters into a contract (no live wiring)."""
+    registry = adapter_registry if adapter_registry is not None else default_adapter_registry
+    required = _declared_adapter_requirements(profile)
+    resolved: list[str] = []
+    missing: list[AdapterRequirement] = []
+    for req in required:
+        if (req.kind, req.id) in registry:
+            resolved.append(req.ref)
+        else:
+            missing.append(req)
+    return ResolvedLanguageContract(
+        language_id=profile.identity.id,
+        profile=profile,
+        required_adapters=required,
+        resolved_adapter_refs=tuple(resolved),
+        missing_adapters=tuple(missing),
+        content_hash=_contract_hash(profile, required),
+    )
+
+
+def resolve_language_profile(
+    config: Mapping[str, Any] | None,
+    *,
+    registry: LanguageRegistry | None = None,
+) -> LanguageProfile | None:
+    """Resolve the project's declared language to a profile.
+
+    Returns ``None`` when no ``project.language`` is declared (the caller stays
+    on the legacy path). Raises ``UnknownLanguageError`` when a language IS
+    declared but no profile matches — a declared-unknown language is an honest
+    error, never silently ignored. This is the single language-resolution seam;
+    new code MUST use it instead of a fixed ``registry.resolve("go")``.
+    """
+    lang_registry = registry if registry is not None else default_registry
+    language = _config_language(config)
+    if not language:
+        return None
+    return lang_registry.resolve(language)
+
+
+def resolve_language_contract(
+    config: Mapping[str, Any] | None,
+    *,
+    language_registry: LanguageRegistry | None = None,
+    adapter_registry: AdapterRegistry | None = None,
+) -> ResolvedLanguageContract | None:
+    """``config`` -> resolved language contract, or ``None`` if no language."""
+    profile = resolve_language_profile(config, registry=language_registry)
+    if profile is None:
+        return None
+    return build_language_contract(profile, adapter_registry=adapter_registry)

{codd_dev-2.67.0 → codd_dev-2.69.0}/codd/languages/registry.py

@@ -141,3 +141,9 @@ class AdapterRegistry:
 
 #: Process-wide default language registry (lazy).
 default_registry = LanguageRegistry()
+
+#: Process-wide default adapter registry. Empty until v2.72 registers the real
+#: test_semantics / runner_report / import_resolver / scaffold adapters; a
+#: language contract that names an unregistered adapter is INCOMPLETE (RED), not
+#: a silent green (see :mod:`codd.languages.contract`).
+default_adapter_registry = AdapterRegistry()

codd_dev-2.69.0/codd/languages/verify_plan.py

@@ -0,0 +1,192 @@
+"""Verify run plan + semantic-class classifier (v2.69a — shadow only).
+
+Builds a verify run plan from the resolved language contract's
+``commands["verify"]`` (the declarative verify command: argv/cwd/env/report)
+and classifies a verify outcome into one of six semantic classes. This runs in
+SHADOW alongside the legacy ``detect_test_command`` path — it does NOT switch
+verify behaviour (that is v2.69b). The point of the shadow stage is to prove,
+on fixtures and on live runs, that the contract-driven plan classifies outcomes
+the SAME way the legacy verifier does (or is intentionally stricter) BEFORE the
+switch.
+
+Anti-false-green: the classifier is a PURE mapping of already-computed signals
+to a class — it never re-derives the zero-tests / report heuristics itself (the
+caller supplies them, reusing the single legacy source), so there is no risk of
+a second, drifting copy of the anti-false-green logic. The class ordering puts
+every not-green verdict (TOOL_MISSING / timeout-FAIL / CONFIG_ERROR /
+ZERO_TESTS / REPORT_MISSING) BEFORE the exit-0 PASS, so a run that exits 0 while
+observing nothing is never classified green.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Mapping
+
+from .contract import ResolvedLanguageContract
+
+
+class VerifyClass(str, Enum):
+    """Semantic class of a verify outcome (design §v2.69a)."""
+
+    PASS = "PASS"
+    FAIL = "FAIL"
+    ZERO_TESTS = "ZERO_TESTS"
+    REPORT_MISSING = "REPORT_MISSING"
+    TOOL_MISSING = "TOOL_MISSING"
+    CONFIG_ERROR = "CONFIG_ERROR"
+
+    @property
+    def is_green(self) -> bool:
+        return self is VerifyClass.PASS
+
+
+@dataclass(frozen=True)
+class VerifyRunPlan:
+    """The contract-derived verify command (declarative, not yet executed)."""
+
+    language_id: str
+    argv: tuple[str, ...]
+    cwd: str | None
+    env: Mapping[str, str]
+    report_path: str | None
+    report_adapter: str | None
+    report_required: bool
+    must_include_test_sets: tuple[str, ...]
+
+    @property
+    def command_str(self) -> str:
+        return " ".join(self.argv)
+
+
+def build_verify_plan(contract: ResolvedLanguageContract) -> VerifyRunPlan | None:
+    """Derive the verify run plan from ``contract.profile.commands['verify']``.
+
+    Returns ``None`` when the profile declares no verify command (the caller
+    stays on the legacy path). A declared ``report.path`` means the command is
+    expected to PRODUCE that report — its absence after a run is REPORT_MISSING
+    (a not-green outcome), enforced once adapters land (v2.72) / the switch
+    happens (v2.69b).
+    """
+    cmd = contract.profile.commands.get("verify")
+    if cmd is None:
+        return None
+    report = cmd.report
+    scope = cmd.scope
+    return VerifyRunPlan(
+        language_id=contract.language_id,
+        argv=tuple(cmd.argv),
+        cwd=cmd.cwd,
+        env=dict(cmd.env),
+        report_path=(report.path if report else None),
+        report_adapter=(report.adapter if report else None),
+        report_required=bool(report and report.path),
+        must_include_test_sets=(scope.must_include_test_sets if scope else ()),
+    )
+
+
+@dataclass(frozen=True)
+class VerifyOutcome:
+    """Observed signals from running a verify command.
+
+    The signals are computed by the CALLER (reusing the single legacy source for
+    the zero-tests heuristic, the report adapter for report presence, etc.) — this
+    keeps the classifier a pure mapping with no duplicated anti-false-green logic.
+    """
+
+    spawned: bool  # did the tool execute at all? (False ⇒ tool missing / spawn error)
+    returncode: int | None = None
+    timed_out: bool = False
+    zero_tests_observed: bool = False  # runner started but collected/ran 0 tests
+    config_error: bool = False  # runner usage/config error (e.g. pytest exit 4)
+    report_present: bool | None = None  # None ⇒ no report expected / not yet checked
+
+
+def classify_verify_outcome(
+    outcome: VerifyOutcome, plan: VerifyRunPlan | None = None
+) -> VerifyClass:
+    """Map an observed verify outcome to a semantic class (pure, anti-false-green).
+
+    Not-green verdicts are checked BEFORE the exit-0 PASS so a command that exits
+    0 while observing nothing (zero tests, missing required report) can never be
+    classified green.
+    """
+    if not outcome.spawned:
+        return VerifyClass.TOOL_MISSING
+    if outcome.timed_out:
+        return VerifyClass.FAIL  # a timeout is a failure, never green
+    if outcome.config_error:
+        return VerifyClass.CONFIG_ERROR
+    if outcome.zero_tests_observed:
+        return VerifyClass.ZERO_TESTS
+    if outcome.returncode == 0:
+        if plan is not None and plan.report_required and outcome.report_present is False:
+            return VerifyClass.REPORT_MISSING
+        return VerifyClass.PASS
+    return VerifyClass.FAIL
+
+
+@dataclass(frozen=True)
+class ShadowComparison:
+    """Result of comparing the contract verify plan against the legacy command."""
+
+    language_id: str
+    legacy_command: str
+    profile_command: str | None
+    commands_identical: bool
+    legacy_class: VerifyClass
+    profile_class: VerifyClass
+    classes_match: bool
+    note: str = ""
+
+    def to_trace(self) -> dict[str, object]:
+        return {
+            "shadow_language_id": self.language_id,
+            "legacy_command": self.legacy_command,
+            "profile_command": self.profile_command,
+            "commands_identical": self.commands_identical,
+            "legacy_verify_class": self.legacy_class.value,
+            "profile_verify_class": self.profile_class.value,
+            "verify_classes_match": self.classes_match,
+            "shadow_note": self.note,
+        }
+
+
+def shadow_compare(
+    contract: ResolvedLanguageContract,
+    *,
+    legacy_command: str,
+    legacy_outcome: VerifyOutcome,
+) -> ShadowComparison | None:
+    """Compare the contract verify plan to the legacy command for one run.
+
+    SHADOW ONLY — never changes behaviour. The legacy outcome's signals are
+    reused to classify what the profile plan WOULD report; divergence (or an
+    intentionally stricter profile, e.g. Go's ``-json`` report variant) is
+    recorded for review before the v2.69b switch.
+    """
+    plan = build_verify_plan(contract)
+    if plan is None:
+        return None
+    legacy_class = classify_verify_outcome(legacy_outcome, plan=None)
+    profile_class = classify_verify_outcome(legacy_outcome, plan=plan)
+    identical = plan.command_str == legacy_command.strip()
+    note = ""
+    if not identical:
+        note = (
+            f"profile verify command differs from legacy "
+            f"(profile={plan.command_str!r} vs legacy={legacy_command!r})"
+        )
+        if plan.report_required:
+            note += "; profile is stricter (declares a required machine-readable report)"
+    return ShadowComparison(
+        language_id=contract.language_id,
+        legacy_command=legacy_command,
+        profile_command=plan.command_str,
+        commands_identical=identical,
+        legacy_class=legacy_class,
+        profile_class=profile_class,
+        classes_match=(legacy_class is profile_class),
+        note=note,
+    )

{codd_dev-2.67.0 → codd_dev-2.69.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codd-dev"
-version = "2.67.0"
+version = "2.69.0"
 description = "CoDD: Coherence-Driven Development — cross-artifact change impact analysis"
 readme = "README.md"
 license = "MIT"