datacontract-cli 1.1.1__tar.gz → 1.1.3__tar.gz

datacontract_cli-1.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Entropy Data GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{datacontract_cli-1.1.1/datacontract_cli.egg-info → datacontract_cli-1.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacontract-cli
-Version: 1.1.1
+Version: 1.1.3
 Summary: The datacontract CLI is an open source command-line tool for working with Data Contracts. It uses data contract YAML files to lint the data contract, connect to data sources and execute schema and quality tests, detect breaking changes, and export to different formats. The tool is written in Python. It can be used as a standalone CLI tool, in a CI/CD pipeline, or directly as a Python library.
 Author-email: Jochen Christ <jochen.christ@entropy-data.com>, Stefan Negele <stefan.negele@innoq.com>, Simon Harrer <simon.harrer@entropy-data.com>
 License-Expression: MIT
@@ -46,10 +46,10 @@ Requires-Dist: boto3<2.0.0,>=1.34.41
 Requires-Dist: Jinja2<4.0.0,>=3.1.5
 Requires-Dist: jinja_partials<1.0.0,>=0.2.1
 Requires-Dist: datacontract-specification<2.0.0,>=1.2.3
-Requires-Dist: open-data-contract-standard<4.0.0,>=3.1.2
+Requires-Dist: open-data-contract-standard<3.2.0,>=3.1.2
 Requires-Dist: deepdiff<10.0.0,>=6.0.0
 Provides-Extra: avro
-Requires-Dist: avro==1.12.1; extra == "avro"
+Requires-Dist: avro==1.12.2; extra == "avro"
 Provides-Extra: bigquery
 Requires-Dist: ibis-framework[bigquery]<13.0.0,>=10.0.0; extra == "bigquery"
 Provides-Extra: csv
@@ -67,7 +67,7 @@ Requires-Dist: rich>=12.4.4; extra == "dataframe"
 Provides-Extra: databricks
 Requires-Dist: ibis-framework[databricks]<13.0.0,>=10.0.0; extra == "databricks"
 Requires-Dist: databricks-sql-connector<4.5.0,>=3.7.0; extra == "databricks"
-Requires-Dist: databricks-sdk<0.126.0; extra == "databricks"
+Requires-Dist: databricks-sdk<0.134.0; extra == "databricks"
 Requires-Dist: packaging<27.0,>=21.3; extra == "databricks"
 Provides-Extra: databricks-runtime
 Requires-Dist: datacontract-cli[databricks]; extra == "databricks-runtime"
@@ -138,18 +138,19 @@ Requires-Dist: datacontract-cli[all]; extra == "dev"
 Requires-Dist: httpx==0.28.1; extra == "dev"
 Requires-Dist: kafka-python; extra == "dev"
 Requires-Dist: minio==7.2.20; extra == "dev"
-Requires-Dist: moto==5.2.2; extra == "dev"
+Requires-Dist: moto==5.2.3; extra == "dev"
 Requires-Dist: openapi-spec-validator<0.10,>=0.7; extra == "dev"
 Requires-Dist: pandas>=2.1.0; extra == "dev"
 Requires-Dist: pre-commit<4.7.0,>=3.7.1; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: pymssql==2.3.13; extra == "dev"
 Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "dev"
 Requires-Dist: mysql-connector-python<26.8.0,>=8.0.30; extra == "dev"
-Requires-Dist: ruff==0.16.2; extra == "dev"
+Requires-Dist: ruff==0.16.5; extra == "dev"
 Requires-Dist: testcontainers[kafka,minio,mssql,mysql,postgres]==4.15.0; extra == "dev"
-Requires-Dist: trino==0.338.0; extra == "dev"
+Requires-Dist: trino==0.339.0; extra == "dev"
 Dynamic: license-file
 
 # Data Contract CLI
@@ -295,6 +296,9 @@ $ datacontract lint odcs.yaml
 # show a changelog between two data contracts
 $ datacontract changelog v1.odcs.yaml v2.odcs.yaml
 
+# fail when a contract change is backward-incompatible
+$ datacontract breaking v1.odcs.yaml v2.odcs.yaml
+
 # execute schema and quality checks (define credentials as environment variables)
 $ datacontract test odcs.yaml
 

{datacontract_cli-1.1.1 → datacontract_cli-1.1.3}/README.md

@@ -141,6 +141,9 @@ $ datacontract lint odcs.yaml
 # show a changelog between two data contracts
 $ datacontract changelog v1.odcs.yaml v2.odcs.yaml
 
+# fail when a contract change is backward-incompatible
+$ datacontract breaking v1.odcs.yaml v2.odcs.yaml
+
 # execute schema and quality checks (define credentials as environment variables)
 $ datacontract test odcs.yaml
 

{datacontract_cli-1.1.1 → datacontract_cli-1.1.3}/datacontract/api.py

@@ -1,6 +1,7 @@
 import json
 import logging
 import os
+import secrets
 import tempfile
 from importlib import metadata
 from typing import Annotated, Optional
@@ -8,15 +9,15 @@ from typing import Annotated, Optional
 import pydantic
 import yaml
 from fastapi import Body, Depends, FastAPI, HTTPException, Query, Request, status
-from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import PlainTextResponse
 from fastapi.security.api_key import APIKeyHeader
 from pydantic import BaseModel, Field, ValidationError
 
 from datacontract.config import Config, known_env_names
 from datacontract.data_contract import DataContract, ExportFormat
+from datacontract.model.breaking import BreakingChangeEntry
 from datacontract.model.changelog import ChangelogEntry
-from datacontract.model.exceptions import DataContractException
+from datacontract.model.exceptions import DataContractException, DefinitionResolutionError
 from datacontract.model.run import Check, ResultEnum, Run
 
 DATA_CONTRACT_EXAMPLE_PAYLOAD = """apiVersion: v3.1.0
@@ -251,6 +252,16 @@ that value, and answers `401` when the header is missing and `403` when it is wr
 Securing the API is strongly recommended: `POST /test` connects to your data sources, and test
 results may contain sensitive information.
 
+## Contracts are untrusted
+
+A posted contract carries SQL and names the hosts to connect to, so the server treats it as
+untrusted input: a `quality.type: sql` rule must be a read-only query, a credential held in the
+server's environment is never sent to a host the contract names, a `publish_url` may only point at
+the Entropy Data platform or the host configured via `ENTROPY_DATA_HOST`, and `servers[].type: local`
+is refused so a caller cannot read the server's own files. Set
+`DATACONTRACT_CLI_API_ALLOW_LOCAL_FILES=true` if the deployment serves its own files on purpose;
+the contract is then still confined to the paths it declares.
+
 ## Connecting to data sources
 
 `POST /test` needs credentials for the server described in the contract's `servers` section. Provide
@@ -313,6 +324,14 @@ app = FastAPI(
                 "url": "https://docs.datacontract.com/commands/changelog",
             },
         },
+        {
+            "name": "breaking",
+            "description": "Compare two versions of a data contract and grade each change by compatibility impact.",
+            "externalDocs": {
+                "description": "Documentation",
+                "url": "https://docs.datacontract.com/commands/breaking",
+            },
+        },
     ],
 )
 
@@ -334,12 +353,17 @@ def _openapi_with_external_docs() -> dict:
 
 app.openapi = _openapi_with_external_docs
 
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
+# Contracts posted to this server arrive over HTTP from callers we do not trust,
+# so a credential the server holds in its environment must never be sent to a
+# host the contract names. The `edit` server reuses the `test` handler for a
+# local file the user owns, so it does not set this flag and is not guarded.
+app.state.untrusted_contracts = True
+
+# No CORS middleware: the only browser client is the Swagger UI served at "/",
+# which is same-origin and therefore not subject to CORS. Every other client
+# (curl, the SDK, CI) is not a browser and ignores CORS. Allowing arbitrary
+# origins would only let a page the operator happens to visit drive this server
+# and read its responses, so the safe default is to send no CORS headers at all.
 
 api_key_header = APIKeyHeader(
     name="x-api-key",
@@ -446,6 +470,198 @@ def _parse_filters_query(filters: str | None) -> dict[str, str] | None:
     return {schema_name: predicate.strip() for schema_name, predicate in parsed.items()}
 
 
+# For each server type whose connection host can be taken from the posted
+# contract: (the Server attribute that names the connection target, the Config
+# field an operator sets to pin that target in the environment or None when the
+# type has no such field, the Config fields that hold a connection secret).
+# See _reject_environment_credentials_to_untrusted_host.
+_ENVIRONMENT_CREDENTIAL_TARGETS: dict[str, tuple[str, str | None, tuple[str, ...]]] = {
+    "postgres": ("host", "postgres_host", ("postgres_password",)),
+    "mysql": ("host", "mysql_host", ("mysql_password",)),
+    "oracle": ("host", "oracle_host", ("oracle_password",)),
+    "impala": ("host", "impala_host", ("impala_password",)),
+    "trino": ("host", "trino_host", ("trino_password",)),
+    "redshift": ("host", "redshift_host", ("redshift_password",)),
+    "sqlserver": ("host", "sqlserver_host", ("sqlserver_password",)),
+    "snowflake": (
+        "account",
+        "snowflake_account",
+        ("snowflake_password", "snowflake_token", "snowflake_private_key"),
+    ),
+    "databricks": ("host", "databricks_server_hostname", ("databricks_token", "databricks_client_secret")),
+    # Kafka's broker host is always the contract's `server.host` (no environment
+    # option pins it), so an environment-held SASL password can never be paired
+    # with a posted contract safely -- host_field is None, so it is always rejected.
+    "kafka": ("broker host", None, ("kafka_sasl_password",)),
+}
+
+
+def _selected_server(body: str, server_name: str | None, config):
+    """The server the request would test, or None if that cannot be determined.
+
+    A contract that does not resolve, or that names no such server, is reported
+    by test() itself -- the guards below simply have nothing to check.
+    """
+    from datacontract.engines.data_contract_test import get_server
+    from datacontract.lint import resolve
+
+    try:
+        data_contract = resolve.resolve_data_contract(data_contract_str=body, config=config)
+        return get_server(data_contract, server_name)
+    except Exception:
+        return None
+
+
+# Server types that read their data through the local filesystem of the machine
+# running the test, rather than from a remote data source.
+_LOCAL_SERVER_TYPES = frozenset({"local", "duckdb"})
+
+ALLOW_LOCAL_FILES_ENV = "DATACONTRACT_CLI_API_ALLOW_LOCAL_FILES"
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+
+def _local_files_allowed() -> bool:
+    """Whether the operator opted in to serving data from the server's own disk.
+
+    Off by default. A deployment that mounts the data next to the API -- the data
+    directory in the container, say -- turns it on, accepting that a caller then
+    picks the path.
+    """
+    return (os.getenv(ALLOW_LOCAL_FILES_ENV) or "").strip().lower() in _TRUTHY
+
+
+def _reject_local_server_type(body: str, server_name: str | None, config) -> None:
+    """Keep a posted contract from reading the server's own disk.
+
+    `type: local` points the test at a path on the machine running it. For the
+    API server that machine is not the caller's, so the path is not theirs to
+    name -- and the result would tell them what is in it.
+    """
+    from datacontract.config import Config
+
+    if _local_files_allowed():
+        return
+    server = _selected_server(body, server_name, Config.resolve(config))
+    if server is None or server.type not in _LOCAL_SERVER_TYPES:
+        return
+    raise HTTPException(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        detail=(
+            f"Server type '{server.type}' reads from the file system of the server running this API, "
+            f"so it is refused. Use a server type that names a data source, such as s3, gcs, azure, "
+            f"postgres, or snowflake — or set {ALLOW_LOCAL_FILES_ENV}=true if this deployment serves "
+            f"its own files on purpose."
+        ),
+    )
+
+
+def _reject_environment_credentials_to_untrusted_host(body: str, server_name: str | None, config) -> None:
+    """Keep an environment-held data-source credential from reaching a host the
+    posted contract chose.
+
+    A contract that arrives over HTTP is untrusted. If it could name the
+    connection host (its ``servers`` section) while the server supplies the
+    password from its own environment, an attacker could point the host at their
+    own machine and capture that password. So when a credential for the selected
+    server's type resolves from the environment, the connection target must
+    resolve from the environment too -- not from the contract, and not from a
+    per-request header (a caller who brings the whole credential set may still
+    aim it wherever they like; only the server's environment secret is pinned).
+    """
+    from datacontract.config import Config
+    from datacontract.config.settings import env_name
+
+    resolved = Config.resolve(config)
+    server = _selected_server(body, server_name, resolved)
+    if server is None:
+        return
+    guard = _ENVIRONMENT_CREDENTIAL_TARGETS.get(server.type)
+    if guard is None:
+        return
+    target_attr, host_field, secret_fields = guard
+    if not any(resolved.option_source(field) == "env" for field in secret_fields):
+        return  # no environment-held secret for this server type; nothing to protect
+    if host_field is not None and resolved.option_source(host_field) == "env":
+        return  # the operator pinned the target host; the contract's host is ignored
+    if host_field is not None:
+        env_var = env_name(host_field, Config.model_fields[host_field])
+        detail = (
+            f"This server holds a {server.type} credential in its environment, so the connection "
+            f"{target_attr} must also come from the server's environment ({env_var}); it will not be "
+            f"taken from the posted data contract. Set {env_var}, or send the full set of credentials "
+            f"with the request instead of relying on the server's environment."
+        )
+    else:
+        detail = (
+            f"This server holds a {server.type} credential in its environment, but its {target_attr} "
+            f"can only come from the posted data contract, so the credential cannot be pinned to a "
+            f"trusted target. Send the credentials with the request instead of relying on the server's "
+            f"environment."
+        )
+    raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=detail)
+
+
+# The fields backing the platform API key and host, in the fallback order
+# _get_api_key / _get_host read them (current name first, deprecated synonyms after).
+_PLATFORM_KEY_FIELDS = ("entropy_data_api_key", "datamesh_manager_api_key", "datacontract_manager_api_key")
+_PLATFORM_HOST_FIELDS = ("entropy_data_host", "datamesh_manager_host", "datacontract_manager_host")
+
+
+def _reject_unpinned_publish_url(publish_url: str | None) -> None:
+    """Keep the API server from POSTing test results to a caller-chosen host.
+
+    `publish_url` names where the finished run — check details, failed-row
+    samples — is POSTed, so an arbitrary URL would let a caller aim a blind
+    POST into the operator's network and exfiltrate the results. The target
+    must be a platform URL as the server's own environment sees it: a
+    per-request `entropy-data-host` header does not widen the set, or the
+    guard would be the caller's to configure.
+    """
+    from datacontract.integration.entropy_data import is_platform_url
+
+    if publish_url is None or is_platform_url(publish_url, None):
+        return
+    raise HTTPException(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        detail=(
+            "The publish_url must point at the Entropy Data platform. To publish to a self-hosted "
+            "deployment, set the environment variable ENTROPY_DATA_HOST on the server running this "
+            "API to that host."
+        ),
+    )
+
+
+def _reject_request_platform_host_with_environment_key(config) -> None:
+    """Keep the environment-held platform API key from following a request-chosen host.
+
+    The platform host decides where the Entropy Data API key travels, and it can
+    be set per request (`entropy-data-host` header). A request that supplies the
+    host while the key resolves from the server's environment could therefore
+    aim that key at its own machine — same rule as the data sources: an
+    environment credential goes only to an environment-pinned destination. A
+    caller who brings the key itself may aim it wherever they like.
+    """
+    from datacontract.config import Config
+
+    resolved = Config.resolve(config)
+    key_source = next(
+        (source for field in _PLATFORM_KEY_FIELDS if (source := resolved.option_source(field)) is not None), None
+    )
+    if key_source != "env":
+        return
+    if not any(resolved.option_source(field) == "request" for field in _PLATFORM_HOST_FIELDS):
+        return
+    raise HTTPException(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        detail=(
+            "This server holds an Entropy Data API key in its environment, so the platform host must "
+            "also come from the server's environment (ENTROPY_DATA_HOST); it will not be taken from a "
+            "request header. Remove the entropy-data-host header, or send the API key with the request "
+            "instead of relying on the server's environment."
+        ),
+    )
+
+
 def check_api_key(api_key_header: str | None):
     correct_api_key = os.getenv("DATACONTRACT_CLI_API_KEY")
     if correct_api_key is None or correct_api_key == "":
@@ -457,7 +673,7 @@ def check_api_key(api_key_header: str | None):
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Missing API key. Use Header 'x-api-key' to provide the API key.",
         )
-    if api_key_header != correct_api_key:
+    if not secrets.compare_digest(api_key_header, correct_api_key):
         logging.info("The provided API key is not correct.")
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
@@ -500,8 +716,9 @@ handled. A contract that cannot be parsed is reported the same way, as a failed
             },
         },
         422: {
-            "description": "`filter` and `filters` were both given, or `filters` is not a JSON object "
-            "mapping schema name to a SQL predicate.",
+            "description": "`filter` and `filters` were both given, `filters` is not a JSON object "
+            "mapping schema name to a SQL predicate, or `publish_url` does not point at the Entropy "
+            "Data platform or the host configured via `ENTROPY_DATA_HOST`.",
             "model": UnprocessableEntityResponse,
         },
     },
@@ -529,7 +746,9 @@ async def test(
     publish_url: Annotated[
         str | None,
         Query(
-            description="URL to publish test results. Optional, if you want to publish the test results to a Data Mesh Manager or Data Contract Manager. Example: https://api.datamesh-manager.com/api/test-results",
+            description="URL to publish test results. Optional, if you want to publish the test results to a Data Mesh Manager or Data Contract Manager. Example: https://api.datamesh-manager.com/api/test-results. "
+            "Must point at the Entropy Data platform, or at the host configured on this server "
+            "via the environment variable ENTROPY_DATA_HOST — other hosts are refused with 422.",
             examples=["https://api.datamesh-manager.com/api/test-results"],
         ),
     ] = None,
@@ -560,14 +779,22 @@ async def test(
         )
     logging.info("Testing data contract...")
     logging.info(body)
+    config = config_from_headers(request.headers)
+    untrusted_contract = getattr(request.app.state, "untrusted_contracts", False)
+    if untrusted_contract:
+        _reject_unpinned_publish_url(publish_url)
+        _reject_request_platform_host_with_environment_key(config)
+        _reject_environment_credentials_to_untrusted_host(body, server, config)
+        _reject_local_server_type(body, server, config)
     return DataContract(
         data_contract_str=body,
         server=server,
         publish_url=publish_url,
         fastapi_url=str(request.url),
-        config=config_from_headers(request.headers),
+        config=config,
         filter=filter,
         filters=parsed_filters,
+        untrusted_contract=untrusted_contract,
     ).test()
 
 
@@ -663,6 +890,21 @@ class ChangelogResponse(BaseModel):
     )
 
 
+class BreakingChangesResponse(BaseModel):
+    """Every change between two versions of a data contract, each graded `info`, `warning` or `error`."""
+
+    summary: list[BreakingChangeEntry] = Field(
+        description="One entry per changed element, graded by the most severe change. A property whose type and requiredness "
+        "both changed appears once.",
+    )
+    entries: list[BreakingChangeEntry] = Field(
+        description="Every single change with its grade and the old and new value.",
+    )
+    is_breaking: bool = Field(
+        description="Whether any detected change is classified as an error-level breaking change.",
+    )
+
+
 @app.post(
     "/changelog",
     tags=["changelog"],
@@ -705,6 +947,59 @@ async def changelog_endpoint(
         raise HTTPException(status_code=422, detail=f"Invalid YAML: {e}")
     except pydantic.ValidationError as e:
         raise HTTPException(status_code=422, detail=f"Invalid data contract: {e}")
+    except DefinitionResolutionError as e:
+        # The reason names the host that was contacted and what it answered.
+        # Omit for security reasons.
+        logging.warning("Definition resolution failed: %s", e)
+        raise HTTPException(status_code=422, detail=f"Could not resolve authoritative definition '{e.url}'.")
+    except DataContractException as e:
+        raise HTTPException(status_code=422, detail=f"Data Contract Validation Failure: {e}")
+    finally:
+        os.unlink(v1_path)
+        os.unlink(v2_path)
+
+
+@app.post(
+    "/breaking",
+    tags=["breaking"],
+    operation_id="breakingChangesDataContracts",
+    summary="Show compatibility impact between two data contracts.",
+    description="""
+Compare two versions of an ODCS data contract and detect backward-incompatible changes.
+
+`POST` a JSON body with `v1` (before) and `v2` (after) as YAML strings. A contract that cannot be
+parsed is answered with `422`.
+    """,
+    response_description="The breaking changes detected between the two data contracts.",
+    responses={
+        **AUTHENTICATION_RESPONSES,
+        422: {
+            "description": "One of the two data contracts is not valid YAML or not a valid data contract.",
+            "model": UnprocessableEntityResponse,
+            "content": {"application/json": {"example": {"detail": "Invalid YAML: while parsing a block mapping"}}},
+        },
+    },
+)
+def breaking_endpoint(
+    body: ChangelogRequest,
+    api_key: Annotated[str | None, Depends(api_key_header)] = None,
+) -> BreakingChangesResponse:
+    check_api_key(api_key)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f1:
+        f1.write(body.v1)
+        v1_path = f1.name
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f2:
+        f2.write(body.v2)
+        v2_path = f2.name
+
+    try:
+        result = DataContract(data_contract_file=v1_path).breaking(DataContract(data_contract_file=v2_path))
+        return BreakingChangesResponse(summary=result.summary, entries=result.entries, is_breaking=result.is_breaking)
+    except yaml.YAMLError as e:
+        raise HTTPException(status_code=422, detail=f"Invalid YAML: {e}")
+    except pydantic.ValidationError as e:
+        raise HTTPException(status_code=422, detail=f"Invalid data contract: {e}")
     except DataContractException as e:
         raise HTTPException(status_code=422, detail=f"Data Contract Validation Failure: {e}")
     finally:
@@ -823,5 +1118,10 @@ def export(
         raise HTTPException(status_code=422, detail=f"Invalid YAML: {e}")
     except pydantic.ValidationError as e:
         raise HTTPException(status_code=422, detail=f"Invalid data contract: {e}")
+    except DefinitionResolutionError as e:
+        # The reason names the host that was contacted and what it answered.
+        # Omit for security reasons.
+        logging.warning("Definition resolution failed: %s", e)
+        raise HTTPException(status_code=422, detail=f"Could not resolve authoritative definition '{e.url}'.")
     except DataContractException as e:
         raise HTTPException(status_code=422, detail=f"Data Contract Validation Failure: {e}")

datacontract_cli-1.1.3/datacontract/breaking/detector.py

@@ -0,0 +1,74 @@
+from collections import defaultdict
+from collections.abc import Iterable
+
+from datacontract.breaking.rules import DEFAULT_RULES, BreakingChangeRule
+from datacontract.model.breaking import BreakingChangeEntry, BreakingChangeLevel, BreakingChangeResult
+from datacontract.model.changelog import ChangelogEntry, ChangelogResult, ChangelogType
+
+_LEVEL_ORDER = {
+    BreakingChangeLevel.INFO: 0,
+    BreakingChangeLevel.WARNING: 1,
+    BreakingChangeLevel.ERROR: 2,
+}
+
+
+class BreakingChangeDetector:
+    """Classify detailed changelog entries using an ordered rule set."""
+
+    def __init__(self, rules: Iterable[BreakingChangeRule] = DEFAULT_RULES):
+        self._rules = tuple(rules)
+        if not self._rules:
+            raise ValueError("At least one breaking-change rule is required")
+
+    def detect(self, changelog: ChangelogResult) -> BreakingChangeResult:
+        entries = [self._classify(entry) for entry in changelog.entries]
+        # Nothing inside a newly added element can break a consumer: it did not exist before.
+        added = {entry.path for entry in entries if entry.change_type == ChangelogType.added}
+        for entry in entries:
+            segments = entry.path.split(".")
+            if any(".".join(segments[:i]) in added for i in range(1, len(segments))):
+                entry.level = BreakingChangeLevel.INFO
+        entries_by_prefix = defaultdict(list)
+        for entry in entries:
+            prefix = ""
+            for segment in entry.path.split("."):
+                prefix = f"{prefix}.{segment}" if prefix else segment
+                entries_by_prefix[prefix].append(entry)
+        summary = [self._summarize(entry, entries_by_prefix.get(entry.path, [])) for entry in changelog.summary]
+        return BreakingChangeResult(v1=changelog.v1, v2=changelog.v2, summary=summary, entries=entries)
+
+    def _classify(self, entry: ChangelogEntry) -> BreakingChangeEntry:
+        for rule in self._rules:
+            evaluation = rule.evaluate(entry)
+            if evaluation is not None:
+                return BreakingChangeEntry(
+                    path=entry.path,
+                    change_type=entry.type,
+                    level=evaluation.level,
+                    message=evaluation.message,
+                    rule_id=evaluation.rule_id,
+                    old_value=entry.old_value,
+                    new_value=entry.new_value,
+                )
+        raise ValueError(f"No breaking-change rule classified {entry.path}")
+
+    @staticmethod
+    def _summarize(summary_entry: ChangelogEntry, entries: list[BreakingChangeEntry]) -> BreakingChangeEntry:
+        if not entries:
+            return BreakingChangeEntry(
+                path=summary_entry.path,
+                change_type=summary_entry.type,
+                level=BreakingChangeLevel.INFO,
+                message=f"Changed contract at {summary_entry.path}",
+                rule_id="summary-fallback",
+            )
+        highest = max(entries, key=lambda entry: _LEVEL_ORDER[entry.level])
+        return BreakingChangeEntry(
+            path=summary_entry.path,
+            change_type=summary_entry.type,
+            level=highest.level,
+            message=f"{highest.level.value.capitalize()} impact at {summary_entry.path}",
+            rule_id=f"summary:{highest.rule_id}",
+            old_value=highest.old_value,
+            new_value=highest.new_value,
+        )